@zodmon/core 0.10.0 → 0.12.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ObjectId, Document, DeleteResult, FindCursor, Collection, UpdateResult, MongoClientOptions } from 'mongodb';
+import { ObjectId, Document, DeleteResult, Collection, FindCursor, ClientSession, UpdateResult, MongoClientOptions } from 'mongodb';
 import { ZodPipe, ZodCustom, ZodTransform, z, ZodDefault } from 'zod';
 
 /**
@@ -260,6 +260,8 @@ type InferInsert<TDef extends {
 type CollectionDefinition<TName extends string = string, TShape extends z.core.$ZodShape = z.core.$ZodShape, TIndexes extends readonly CompoundIndexDefinition<Extract<keyof TShape, string>>[] = readonly CompoundIndexDefinition<Extract<keyof TShape, string>>[]> = {
     readonly name: TName;
     readonly schema: z.ZodObject<ResolvedShape<TShape>>;
+    /** Strict validation variant that throws on unknown fields. */
+    readonly strictSchema: z.ZodObject<ResolvedShape<TShape>>;
     readonly shape: TShape;
     readonly fieldIndexes: FieldIndexDefinition[];
     readonly compoundIndexes: TIndexes;
@@ -319,6 +321,40 @@ type ExtractNames<T extends readonly {
 type Prettify<T> = {
     [K in keyof T]: T[K];
 } & {};
+/**
+ * Generates all valid dot-separated field paths for a document type.
+ *
+ * Recursively traverses nested objects and unwraps arrays to match
+ * MongoDB's implicit array traversal semantics. Both top-level keys
+ * and nested paths are included in the resulting union.
+ *
+ * @example
+ * ```ts
+ * type Doc = { address: { city: string }; tags: Array<{ label: string }> }
+ * type Paths = DotPath<Doc>
+ * //   ^? 'address' | 'address.city' | 'tags' | 'tags.label'
+ * ```
+ */
+type DotPath<T> = T extends ReadonlyArray<infer E> ? DotPath<E> : T extends Record<string, unknown> ? {
+    [K in keyof T & string]: T[K] extends ReadonlyArray<infer E> ? E extends Record<string, unknown> ? K | `${K}.${DotPath<E>}` : K : T[K] extends Record<string, unknown> ? K | `${K}.${DotPath<T[K]>}` : K;
+}[keyof T & string] : never;
+/**
+ * Resolves the value type at a dot-separated path within a document type.
+ *
+ * Splits the path on `.` and recursively descends into nested types.
+ * Unwraps arrays at intermediate levels to match MongoDB's implicit
+ * array traversal. Returns `never` for invalid paths.
+ *
+ * @example
+ * ```ts
+ * type Doc = { address: { city: string }; tags: Array<{ label: string }> }
+ * type City = DotPathValue<Doc, 'address.city'>
+ * //   ^? string
+ * type Label = DotPathValue<Doc, 'tags.label'>
+ * //   ^? string
+ * ```
+ */
+type DotPathValue<T, P extends string> = P extends `${infer K}.${infer Rest}` ? K extends keyof T ? T[K] extends ReadonlyArray<infer E> ? DotPathValue<E, Rest> : DotPathValue<T[K], Rest> : never : P extends keyof T ? T[P] : never;
 
 /**
  * Type-level marker that carries the target collection type through the
@@ -397,6 +433,48 @@ declare module 'zod' {
  * ```
  */
 declare function getRefMetadata(schema: unknown): RefMetadata | undefined;
+/**
+ * Peel Zod wrappers (ZodOptional, ZodNullable, ZodDefault, ZodArray)
+ * to reach the inner schema type. Used to detect RefMarker on wrapped
+ * fields like `objectId().ref(X).optional()` or `z.array(objectId().ref(X))`.
+ *
+ * Bounded by wrapper depth (1-3 layers) — no circular risk.
+ *
+ * @example
+ * ```ts
+ * // ZodOptional<ZodObjectId & RefMarker<typeof Users>> → ZodObjectId & RefMarker<typeof Users>
+ * type Inner = UnwrapRef<typeof schema>
+ * ```
+ */
+type UnwrapRef<T> = T extends z.ZodOptional<infer U> ? UnwrapRef<U> : T extends z.ZodNullable<infer U> ? UnwrapRef<U> : T extends z.ZodDefault<infer U> ? UnwrapRef<U> : T extends z.ZodArray<infer E> ? UnwrapRef<E> : T;
+/**
+ * Extract field names that carry `.ref()` metadata from a collection definition.
+ *
+ * Unwraps ZodArray, ZodOptional, ZodNullable, ZodDefault to detect refs on
+ * inner schemas. Works for bare refs, array refs, and optional refs.
+ *
+ * @example
+ * ```ts
+ * type PostRefs = RefFields<typeof Posts>
+ * //   ^? 'authorId' | 'categoryIds' | 'reviewerId'
+ * ```
+ */
+type RefFields<TDef extends AnyCollection> = {
+    [K in keyof TDef['shape'] & string]: UnwrapRef<TDef['shape'][K]> extends RefMarker ? K : never;
+}[keyof TDef['shape'] & string];
+/**
+ * Given a collection definition and a ref-bearing field key, extract
+ * the target collection type from the `RefMarker<TCollection>` phantom.
+ *
+ * Unwraps Zod wrappers to reach the inner RefMarker.
+ *
+ * @example
+ * ```ts
+ * type Target = ExtractRefCollection<typeof Posts, 'authorId'>
+ * //   ^? typeof Users
+ * ```
+ */
+type ExtractRefCollection<TDef extends AnyCollection, K extends RefFields<TDef>> = UnwrapRef<TDef['shape'][K]> extends RefMarker<infer TCol> ? TCol : never;
 
 /**
  * Branded wrapper for accumulator expressions used inside `groupBy`.
@@ -448,21 +526,25 @@ type InferAccumulators<T extends Record<string, Accumulator>> = {
     [K in keyof T]: InferAccumulator<T[K]>;
 };
 /**
- * Field reference string prefixed with `$`, constrained to keys of `T`.
+ * Field reference string prefixed with `$`, constrained to dot-paths of `T`.
+ *
+ * Supports both top-level fields (`$price`) and nested dot-paths
+ * (`$address.city`, `$address.geo.lat`).
  *
  * @example
  * ```ts
- * type OrderRef = FieldRef<{ price: number; qty: number }>
- * //   ^? '$price' | '$qty'
+ * type OrderRef = FieldRef<{ price: number; address: { city: string } }>
+ * //   ^? '$price' | '$address' | '$address.city'
  * ```
  */
-type FieldRef<T> = `$${keyof T & string}`;
+type FieldRef<T> = `$${DotPath<T>}`;
 /**
  * Typed accumulator factory passed to the `groupBy` callback.
  *
- * Each method constrains field names to `keyof T & string`, providing
- * IDE autocomplete and compile-time validation. Return types resolve
- * to the actual field type (`T[K]`), not `unknown`.
+ * Each method constrains field names to `DotPath<T>`, providing
+ * IDE autocomplete and compile-time validation for both top-level
+ * and nested dot-path fields. Return types resolve to the actual
+ * field type via `DotPathValue<T, F>`, not `unknown`.
  *
  * @typeParam T - The current pipeline output document type.
  *
@@ -470,10 +552,10 @@ type FieldRef<T> = `$${keyof T & string}`;
  * ```ts
  * users.aggregate()
  *   .groupBy('role', acc => ({
- *     minSalary: acc.min('salary'),   // Accumulator<number>
- *     firstName: acc.first('name'),   // Accumulator<string>
- *     allNames: acc.push('name'),     // Accumulator<string[]>
- *     count: acc.count(),             // Accumulator<number>
+ *     minSalary: acc.min('salary'),           // Accumulator<number>
+ *     firstName: acc.first('name'),           // Accumulator<string>
+ *     allCities: acc.push('address.city'),    // Accumulator<string[]>
+ *     count: acc.count(),                     // Accumulator<number>
  *   }))
  * ```
  */
@@ -481,64 +563,109 @@ type AccumulatorBuilder<T> = {
     /** Count documents in each group. Always returns `Accumulator<number>`. */
     count(): Accumulator<number>;
     /** Sum a numeric field. Always returns `Accumulator<number>`. */
-    sum<K extends keyof T & string>(field: K): Accumulator<number>;
+    sum(field: DotPath<T>): Accumulator<number>;
     /** Sum a literal number per document. Always returns `Accumulator<number>`. */
     sum(value: number): Accumulator<number>;
     /** Average a numeric field. Always returns `Accumulator<number>`. */
-    avg<K extends keyof T & string>(field: K): Accumulator<number>;
-    /** Minimum value of a field. Returns `Accumulator<T[K]>`. */
-    min<K extends keyof T & string>(field: K): Accumulator<T[K]>;
-    /** Maximum value of a field. Returns `Accumulator<T[K]>`. */
-    max<K extends keyof T & string>(field: K): Accumulator<T[K]>;
-    /** First value in each group (by document order). Returns `Accumulator<T[K]>`. */
-    first<K extends keyof T & string>(field: K): Accumulator<T[K]>;
-    /** Last value in each group (by document order). Returns `Accumulator<T[K]>`. */
-    last<K extends keyof T & string>(field: K): Accumulator<T[K]>;
-    /** Collect values into an array (with duplicates). Returns `Accumulator<T[K][]>`. */
-    push<K extends keyof T & string>(field: K): Accumulator<T[K][]>;
-    /** Collect unique values into an array. Returns `Accumulator<T[K][]>`. */
-    addToSet<K extends keyof T & string>(field: K): Accumulator<T[K][]>;
+    avg(field: DotPath<T>): Accumulator<number>;
+    /** Minimum value of a field. Returns `Accumulator<DotPathValue<T, F>>`. */
+    min<F extends DotPath<T>>(field: F): Accumulator<DotPathValue<T, F>>;
+    /** Maximum value of a field. Returns `Accumulator<DotPathValue<T, F>>`. */
+    max<F extends DotPath<T>>(field: F): Accumulator<DotPathValue<T, F>>;
+    /** First value in each group (by document order). Returns `Accumulator<DotPathValue<T, F>>`. */
+    first<F extends DotPath<T>>(field: F): Accumulator<DotPathValue<T, F>>;
+    /** Last value in each group (by document order). Returns `Accumulator<DotPathValue<T, F>>`. */
+    last<F extends DotPath<T>>(field: F): Accumulator<DotPathValue<T, F>>;
+    /** Collect values into an array (with duplicates). Returns `Accumulator<DotPathValue<T, F>[]>`. */
+    push<F extends DotPath<T>>(field: F): Accumulator<DotPathValue<T, F>[]>;
+    /** Collect unique values into an array. Returns `Accumulator<DotPathValue<T, F>[]>`. */
+    addToSet<F extends DotPath<T>>(field: F): Accumulator<DotPathValue<T, F>[]>;
 };
 /**
  * Resolves the document field type from a `$`-prefixed field reference.
  *
+ * Supports both top-level refs (`$price`) and dot-path refs
+ * (`$address.city`), resolving through nested objects and arrays.
+ *
  * @example
  * ```ts
- * type Order = { price: number; name: string }
+ * type Order = { price: number; address: { city: string } }
  * type PriceType = FieldRefType<Order, '$price'>
  * //   ^? number
+ * type CityType = FieldRefType<Order, '$address.city'>
+ * //   ^? string
  * ```
  */
-type FieldRefType<T, F extends string> = F extends `$${infer K}` ? K extends keyof T ? T[K] : never : never;
+type FieldRefType<T, F extends string> = F extends `$${infer K}` ? DotPathValue<T, K> extends never ? never : DotPathValue<T, K> : never;
 /**
  * Output shape of a single-field `groupBy` stage.
  *
  * The `_id` field holds the grouped-by field's value, and the rest of the
- * shape comes from the inferred accumulator types.
+ * shape comes from the inferred accumulator types. Supports dot-path keys
+ * for grouping by nested fields.
  *
  * @example
  * ```ts
  * type Result = GroupByResult<Order, 'status', { count: Accumulator<number> }>
  * //   ^? { _id: string; count: number }
+ *
+ * type Nested = GroupByResult<Order, 'address.city', { count: Accumulator<number> }>
+ * //   ^? { _id: string; count: number }
  * ```
  */
-type GroupByResult<T, K extends keyof T, TAccum extends Record<string, Accumulator>> = Prettify<{
-    _id: T[K];
+type GroupByResult<T, K extends DotPath<T>, TAccum extends Record<string, Accumulator>> = Prettify<{
+    _id: DotPathValue<T, K & string>;
 } & InferAccumulators<TAccum>>;
+/**
+ * Replace dots with underscores in a string type.
+ *
+ * Used to sanitize dot-path keys for compound `groupBy` `_id` sub-documents,
+ * since MongoDB forbids dots in field names.
+ *
+ * @example
+ * ```ts
+ * type R = ReplaceDots<'address.city'>
+ * //   ^? 'address_city'
+ * ```
+ */
+type ReplaceDots<S extends string> = S extends `${infer A}.${infer B}` ? `${A}_${ReplaceDots<B>}` : S;
 /**
  * Output shape of a compound (multi-field) `groupBy` stage.
  *
  * The `_id` field is an object with one property per grouped field,
  * and the rest of the shape comes from the inferred accumulator types.
+ * Dot-path keys are sanitized (dots replaced with underscores) because
+ * MongoDB forbids dots in field names.
  *
  * @example
  * ```ts
  * type Result = GroupByCompoundResult<Order, 'status' | 'region', { count: Accumulator<number> }>
- * //   ^? { _id: Pick<Order, 'status' | 'region'>; count: number }
+ * //   ^? { _id: { status: string; region: string }; count: number }
+ *
+ * type Nested = GroupByCompoundResult<Order, 'name' | 'address.city', { count: Accumulator<number> }>
+ * //   ^? { _id: { name: string; address_city: string }; count: number }
+ * ```
+ */
+type GroupByCompoundResult<T, K extends DotPath<T>, TAccum extends Record<string, Accumulator>> = Prettify<{
+    _id: Prettify<{
+        [P in K & string as ReplaceDots<P>]: DotPathValue<T, P>;
+    }>;
+} & InferAccumulators<TAccum>>;
+/**
+ * Output shape of a null-key `groupBy` stage (global aggregation).
+ *
+ * When `groupBy(null, ...)` is used, MongoDB collapses all documents
+ * into a single group with `_id: null`. The rest of the shape comes
+ * from the inferred accumulator types.
+ *
+ * @example
+ * ```ts
+ * type Result = GroupByNullResult<{ total: Accumulator<number> }>
+ * //   ^? { _id: null; total: number }
  * ```
  */
-type GroupByCompoundResult<T, K extends keyof T, TAccum extends Record<string, Accumulator>> = Prettify<{
-    _id: Prettify<Pick<T, K>>;
+type GroupByNullResult<TAccum extends Record<string, Accumulator>> = Prettify<{
+    _id: null;
 } & InferAccumulators<TAccum>>;
 /**
  * Output shape after unwinding an array field.
@@ -591,29 +718,6 @@ type NarrowFromFilter<T, F> = {
         $nin: ReadonlyArray<infer V extends T[K]>;
     } ? Exclude<T[K], V> : T[K] : T[K];
 };
-/**
- * Extract field keys from a collection definition whose schema fields
- * carry `RefMarker` (i.e. fields that have `.ref()` metadata).
- *
- * @example
- * ```ts
- * type EmpRefs = RefFields<typeof Employees> // → 'departmentId'
- * ```
- */
-type RefFields<TDef extends AnyCollection> = {
-    [K in keyof TDef['shape'] & string]: TDef['shape'][K] extends RefMarker ? K : never;
-}[keyof TDef['shape'] & string];
-/**
- * Given a collection definition and a ref-bearing field key, extract
- * the target collection type from the `RefMarker<TCollection>` phantom.
- *
- * @example
- * ```ts
- * type Target = ExtractRefCollection<typeof Employees, 'departmentId'>
- * // → typeof Departments
- * ```
- */
-type ExtractRefCollection<TDef extends AnyCollection, K extends RefFields<TDef>> = TDef['shape'][K] extends RefMarker<infer TCol> ? TCol : never;
 /**
  * Extract the collection name string literal from a collection definition.
  *
@@ -670,12 +774,44 @@ type InferExpression<T> = T extends Expression<infer R> ? R : unknown;
 type InferAddedFields<T extends Record<string, unknown>> = {
     [K in keyof T]: InferExpression<T[K]>;
 };
+/**
+ * Accepts either a dot-path field reference or a pre-built `Expression<R>`.
+ *
+ * Used throughout `ExpressionBuilder` to allow method inputs to be either a
+ * field name string (auto-prefixed with `$` at runtime) or the result of a
+ * previous expression call (embedded directly into the pipeline stage).
+ *
+ * @typeParam T - The current pipeline document type.
+ * @typeParam R - The runtime value type produced by this input.
+ *
+ * @example
+ * ```ts
+ * // Field path (common case)
+ * expr.round('salary', 2)
+ *
+ * // Composed expression
+ * expr.round(expr.multiply('salary', 0.1), 2)
+ * ```
+ */
+type FieldOrExpr<T, R = unknown> = DotPath<T> | Expression<R>;
+/**
+ * Extracts the element type from a readonly or mutable array type.
+ *
+ * @example
+ * ```ts
+ * type Item = ArrayElement<string[]>     // → string
+ * type Num  = ArrayElement<number[]>     // → number
+ * type N    = ArrayElement<string>       // → never
+ * ```
+ */
+type ArrayElement<T> = T extends ReadonlyArray<infer E> ? E : never;
 /**
  * Typed expression factory passed to the `addFields` callback.
  *
- * Each method constrains field names to `keyof T & string`, providing
- * IDE autocomplete and compile-time validation. Return types resolve
- * to `Expression<R>` where `R` is the MongoDB operator's output type.
+ * Each method accepts either a `DotPath<T>` field name string (auto-prefixed
+ * with `$` at runtime) or the result of a previous expression call
+ * (`Expression<R>`, embedded directly). This enables arbitrarily deep
+ * expression composition without `.raw()`.
  *
  * @typeParam T - The current pipeline output document type.
  *
@@ -683,65 +819,181 @@ type InferAddedFields<T extends Record<string, unknown>> = {
  * ```ts
  * employees.aggregate()
  *   .addFields(expr => ({
- *     hireYear: expr.year('hiredAt'),     // Expression<number>
- *     fullName: expr.concat('name', ' '), // Expression<string>
- *     isHighPay: expr.gte('salary', 100_000), // Expression<boolean>
+ *     hireYear: expr.year('hiredAt'),
+ *     bonus: expr.round(expr.multiply('salary', 0.1), 2),
+ *     profitMargin: expr.cond(
+ *       expr.eq('revenue', 0),
+ *       0,
+ *       expr.round(expr.divide(expr.subtract('revenue', 'cost'), 'revenue'), 4),
+ *     ),
  *   }))
  * ```
  */
 type ExpressionBuilder<T> = {
-    /** Add a numeric field and a value. Returns `Expression<number>`. */
-    add<K extends keyof T & string>(field: K, value: number | (keyof T & string)): Expression<number>;
-    /** Subtract a value from a numeric field. Returns `Expression<number>`. */
-    subtract<K extends keyof T & string>(field: K, value: number | (keyof T & string)): Expression<number>;
-    /** Multiply a numeric field by a value. Returns `Expression<number>`. */
-    multiply<K extends keyof T & string>(field: K, value: number | (keyof T & string)): Expression<number>;
-    /** Divide a numeric field by a value. Returns `Expression<number>`. */
-    divide<K extends keyof T & string>(field: K, value: number | (keyof T & string)): Expression<number>;
-    /** Modulo of a numeric field. Returns `Expression<number>`. */
-    mod<K extends keyof T & string>(field: K, value: number | (keyof T & string)): Expression<number>;
-    /** Absolute value of a numeric field. Returns `Expression<number>`. */
-    abs<K extends keyof T & string>(field: K): Expression<number>;
-    /** Ceiling of a numeric field. Returns `Expression<number>`. */
-    ceil<K extends keyof T & string>(field: K): Expression<number>;
-    /** Floor of a numeric field. Returns `Expression<number>`. */
-    floor<K extends keyof T & string>(field: K): Expression<number>;
-    /** Round a numeric field to N decimal places. Returns `Expression<number>`. */
-    round<K extends keyof T & string>(field: K, place?: number): Expression<number>;
-    /** Concatenate field values and literal strings. Returns `Expression<string>`. */
-    concat(...parts: Array<(keyof T & string) | string>): Expression<string>;
-    /** Convert a string field to lowercase. Returns `Expression<string>`. */
-    toLower<K extends keyof T & string>(field: K): Expression<string>;
-    /** Convert a string field to uppercase. Returns `Expression<string>`. */
-    toUpper<K extends keyof T & string>(field: K): Expression<string>;
-    /** Trim whitespace from a string field. Returns `Expression<string>`. */
-    trim<K extends keyof T & string>(field: K): Expression<string>;
-    /** Extract a substring from a string field. Returns `Expression<string>`. */
-    substr<K extends keyof T & string>(field: K, start: number, length: number): Expression<string>;
-    /** Test equality of a field against a value. Returns `Expression<boolean>`. */
-    eq<K extends keyof T & string>(field: K, value: T[K]): Expression<boolean>;
-    /** Test if a field is greater than a value. Returns `Expression<boolean>`. */
-    gt<K extends keyof T & string>(field: K, value: T[K]): Expression<boolean>;
-    /** Test if a field is greater than or equal to a value. Returns `Expression<boolean>`. */
-    gte<K extends keyof T & string>(field: K, value: T[K]): Expression<boolean>;
-    /** Test if a field is less than a value. Returns `Expression<boolean>`. */
-    lt<K extends keyof T & string>(field: K, value: T[K]): Expression<boolean>;
-    /** Test if a field is less than or equal to a value. Returns `Expression<boolean>`. */
-    lte<K extends keyof T & string>(field: K, value: T[K]): Expression<boolean>;
-    /** Test if a field is not equal to a value. Returns `Expression<boolean>`. */
-    ne<K extends keyof T & string>(field: K, value: T[K]): Expression<boolean>;
-    /** Extract year from a date field. Returns `Expression<number>`. */
-    year<K extends keyof T & string>(field: K): Expression<number>;
-    /** Extract month (1-12) from a date field. Returns `Expression<number>`. */
-    month<K extends keyof T & string>(field: K): Expression<number>;
-    /** Extract day of month (1-31) from a date field. Returns `Expression<number>`. */
-    dayOfMonth<K extends keyof T & string>(field: K): Expression<number>;
-    /** Count elements in an array field. Returns `Expression<number>`. */
-    size<K extends keyof T & string>(field: K): Expression<number>;
-    /** Conditional expression. Returns `Expression<TThen | TElse>`. */
-    cond<TThen, TElse>(condition: Expression<boolean>, thenValue: TThen, elseValue: TElse): Expression<TThen | TElse>;
-    /** Replace null/missing field with a default. Returns `Expression<NonNullable<T[K]> | TDefault>`. */
-    ifNull<K extends keyof T & string, TDefault>(field: K, fallback: TDefault): Expression<NonNullable<T[K]> | TDefault>;
+    /** Add two numeric values. Returns `Expression<number>`. */
+    add(a: FieldOrExpr<T, number>, b: FieldOrExpr<T, number> | number): Expression<number>;
+    /** Subtract `b` from `a`. Returns `Expression<number>`. */
+    subtract(a: FieldOrExpr<T, number>, b: FieldOrExpr<T, number> | number): Expression<number>;
+    /** Multiply two numeric values. Returns `Expression<number>`. */
+    multiply(a: FieldOrExpr<T, number>, b: FieldOrExpr<T, number> | number): Expression<number>;
+    /** Divide `a` by `b`. Returns `Expression<number>`. */
+    divide(a: FieldOrExpr<T, number>, b: FieldOrExpr<T, number> | number): Expression<number>;
+    /** Modulo of `a` divided by `b`. Returns `Expression<number>`. */
+    mod(a: FieldOrExpr<T, number>, b: FieldOrExpr<T, number> | number): Expression<number>;
+    /** Absolute value of a numeric field or expression. Returns `Expression<number>`. */
+    abs(field: FieldOrExpr<T, number>): Expression<number>;
+    /** Ceiling (round up) of a numeric field or expression. Returns `Expression<number>`. */
+    ceil(field: FieldOrExpr<T, number>): Expression<number>;
+    /** Floor (round down) of a numeric field or expression. Returns `Expression<number>`. */
+    floor(field: FieldOrExpr<T, number>): Expression<number>;
+    /** Round to `place` decimal places (default 0). Returns `Expression<number>`. */
+    round(field: FieldOrExpr<T, number>, place?: number): Expression<number>;
+    /** Concatenate field values, literal strings, and string expressions. Returns `Expression<string>`. */
+    concat(...parts: Array<DotPath<T> | string | Expression<string>>): Expression<string>;
+    /** Convert a string field or expression to lowercase. Returns `Expression<string>`. */
+    toLower(field: FieldOrExpr<T, string>): Expression<string>;
+    /** Convert a string field or expression to uppercase. Returns `Expression<string>`. */
+    toUpper(field: FieldOrExpr<T, string>): Expression<string>;
+    /** Trim whitespace from a string field or expression. Returns `Expression<string>`. */
+    trim(field: FieldOrExpr<T, string>): Expression<string>;
+    /** Extract a byte-based substring. Returns `Expression<string>`. */
+    substr(field: FieldOrExpr<T, string>, start: number, length: number): Expression<string>;
+    /** Convert any value (number, date, ObjectId, etc.) to its string representation. Returns `Expression<string>`. */
+    toString(field: FieldOrExpr<T, unknown>): Expression<string>;
+    /** Test equality of a field against a value (type-safe value). Returns `Expression<boolean>`. */
+    eq<F extends DotPath<T>>(field: F, value: DotPathValue<T, F>): Expression<boolean>;
+    /** Test equality of a field against a field reference expression (field-vs-field). Returns `Expression<boolean>`. */
+    eq(field: DotPath<T>, value: Expression<unknown>): Expression<boolean>;
+    /** Test equality with a composed expression as the left-hand side. Returns `Expression<boolean>`. */
+    eq(field: Expression<unknown>, value: unknown): Expression<boolean>;
+    /** Test if a field is greater than a value (type-safe). Returns `Expression<boolean>`. */
+    gt<F extends DotPath<T>>(field: F, value: DotPathValue<T, F>): Expression<boolean>;
+    /** Test if a field is greater than a field reference expression (field-vs-field). Returns `Expression<boolean>`. */
+    gt(field: DotPath<T>, value: Expression<unknown>): Expression<boolean>;
+    /** Test if a composed expression is greater than a value. Returns `Expression<boolean>`. */
+    gt(field: Expression<unknown>, value: unknown): Expression<boolean>;
+    /** Test if a field is greater than or equal to a value (type-safe). Returns `Expression<boolean>`. */
+    gte<F extends DotPath<T>>(field: F, value: DotPathValue<T, F>): Expression<boolean>;
+    /** Test if a field is greater than or equal to a field reference expression (field-vs-field). Returns `Expression<boolean>`. */
+    gte(field: DotPath<T>, value: Expression<unknown>): Expression<boolean>;
+    /** Test if a composed expression is greater than or equal to a value. Returns `Expression<boolean>`. */
+    gte(field: Expression<unknown>, value: unknown): Expression<boolean>;
+    /** Test if a field is less than a value (type-safe). Returns `Expression<boolean>`. */
+    lt<F extends DotPath<T>>(field: F, value: DotPathValue<T, F>): Expression<boolean>;
+    /** Test if a field is less than a field reference expression (field-vs-field). Returns `Expression<boolean>`. */
+    lt(field: DotPath<T>, value: Expression<unknown>): Expression<boolean>;
+    /** Test if a composed expression is less than a value. Returns `Expression<boolean>`. */
+    lt(field: Expression<unknown>, value: unknown): Expression<boolean>;
+    /** Test if a field is less than or equal to a value (type-safe). Returns `Expression<boolean>`. */
+    lte<F extends DotPath<T>>(field: F, value: DotPathValue<T, F>): Expression<boolean>;
+    /** Test if a field is less than or equal to a field reference expression (field-vs-field). Returns `Expression<boolean>`. */
+    lte(field: DotPath<T>, value: Expression<unknown>): Expression<boolean>;
+    /** Test if a composed expression is less than or equal to a value. Returns `Expression<boolean>`. */
+    lte(field: Expression<unknown>, value: unknown): Expression<boolean>;
+    /** Test if a field is not equal to a value (type-safe). Returns `Expression<boolean>`. */
+    ne<F extends DotPath<T>>(field: F, value: DotPathValue<T, F>): Expression<boolean>;
+    /** Test if a field is not equal to a field reference expression (field-vs-field). Returns `Expression<boolean>`. */
+    ne(field: DotPath<T>, value: Expression<unknown>): Expression<boolean>;
+    /** Test if a composed expression is not equal to a value. Returns `Expression<boolean>`. */
+    ne(field: Expression<unknown>, value: unknown): Expression<boolean>;
+    /** Extract year from a date field or expression. Returns `Expression<number>`. */
+    year(field: FieldOrExpr<T, Date>): Expression<number>;
+    /** Extract month (1-12) from a date field or expression. Returns `Expression<number>`. */
+    month(field: FieldOrExpr<T, Date>): Expression<number>;
+    /** Extract day of month (1-31) from a date field or expression. Returns `Expression<number>`. */
+    dayOfMonth(field: FieldOrExpr<T, Date>): Expression<number>;
+    /** Extract day of week (1=Sunday … 7=Saturday) from a date field or expression. Returns `Expression<number>`. */
+    dayOfWeek(field: FieldOrExpr<T, Date>): Expression<number>;
+    /**
+     * Format a date field or expression as a string.
+     *
+     * Uses MongoDB format specifiers: `%Y` year, `%m` month (01-12), `%d` day (01-31), etc.
+     *
+     * @example
+     * ```ts
+     * expr.dateToString('createdAt', '%Y-%m')  // Expression<string>
+     * ```
+     */
+    dateToString(field: FieldOrExpr<T, Date>, format: string): Expression<string>;
+    /** Current timestamp at query start (`$$NOW`). Returns `Expression<Date>`. */
+    now(): Expression<Date>;
+    /** Count elements in an array field or expression. Returns `Expression<number>`. */
+    size(field: FieldOrExpr<T, unknown[]>): Expression<number>;
+    /**
+     * Check if a value is present in an array.
+     *
+     * Named `inArray` to distinguish from the filter-level `$in` operator.
+     * The second argument may be a field/expression producing an array, or a literal array.
+     *
+     * @example
+     * ```ts
+     * expr.inArray(expr.dayOfWeek('createdAt'), [1, 7])  // Expression<boolean>
+     * ```
+     */
+    inArray(value: FieldOrExpr<T, unknown>, array: FieldOrExpr<T, unknown[]> | ReadonlyArray<unknown>): Expression<boolean>;
+    /**
+     * Return the element at `index` from an array field (zero-based).
+     *
+     * When called with a typed field path, the element type is inferred from the schema.
+     * When called with a composed expression, the element type is `unknown`.
+     *
+     * @example
+     * ```ts
+     * // items: Item[] in schema → Expression<Item>
+     * expr.arrayElemAt('items', 0)
+     * ```
+     */
+    arrayElemAt<F extends DotPath<T>>(field: F, index: number): Expression<ArrayElement<DotPathValue<T, F>>>;
+    /** Return the element at `index` from an array expression. Returns `Expression<unknown>`. */
+    arrayElemAt(field: Expression<unknown[]>, index: number): Expression<unknown>;
+    /**
+     * Conditional expression: if `condition` is true return `thenValue`, else return `elseValue`.
+     *
+     * Both `thenValue` and `elseValue` accept literal values or composed `Expression<R>` results.
+     * Returns `Expression<TThen | TElse>`.
+     *
+     * @example
+     * ```ts
+     * expr.cond(expr.eq('revenue', 0), 0, expr.round(expr.divide('profit', 'revenue'), 4))
+     * ```
+     */
+    cond<TThen, TElse>(condition: Expression<boolean>, thenValue: TThen | Expression<TThen>, elseValue: TElse | Expression<TElse>): Expression<TThen | TElse>;
+    /** Replace null/missing field with a default. Returns `Expression<NonNullable<DotPathValue<T, F>> | TDefault>`. */
+    ifNull<F extends DotPath<T>, TDefault>(field: F, fallback: TDefault): Expression<NonNullable<DotPathValue<T, F>> | TDefault>;
+    /** Replace null/missing expression result with a default. Returns `Expression<NonNullable<R> | TDefault>`. */
+    ifNull<R, TDefault>(field: Expression<R>, fallback: TDefault): Expression<NonNullable<R> | TDefault>;
+    /**
+     * Multi-branch conditional. Evaluates `branches` in order and returns the first matching `then` value,
+     * or `fallback` if no branch matches.
+     *
+     * TypeScript infers `TThen` as the union of all `then` value types and the fallback type.
+     *
+     * @example
+     * ```ts
+     * expr.switch([
+     *   { case: expr.gte('spend', 10_000), then: 'VIP'    },
+     *   { case: expr.gte('spend', 5_000),  then: 'Gold'   },
+     * ], 'Bronze')
+     * // → Expression<'VIP' | 'Gold' | 'Bronze'>
+     * ```
+     */
+    switch<TThen>(branches: ReadonlyArray<{
+        case: Expression<boolean>;
+        then: TThen | Expression<TThen>;
+    }>, fallback: TThen | Expression<TThen>): Expression<TThen>;
+    /**
+     * Create a typed field reference for use as a comparison operand.
+     *
+     * Use when the right-hand side of a comparison should be a document
+     * field rather than a literal value (field-vs-field comparison).
+     *
+     * @example
+     * ```ts
+     * // Compare two fields in the same document
+     * .match({}, (expr) => expr.gt('totalAmount', expr.field('refundedAmount')))
+     * ```
+     */
+    field<F extends DotPath<T>>(name: F): Expression<DotPathValue<T, F>>;
 };
 
 /**
@@ -792,139 +1044,169 @@ declare const $avg: (field: `$${string}`) => Accumulator<number>;
 /**
  * Returns the minimum value across documents in each group.
  *
- * For full type safety, prefer the callback builder (`acc.min('price')`).
- * The standalone form accepts an explicit result type `R` for manual typing.
+ * Three tiers of type safety:
+ * - **Tier 1 (document type):** `$min<Doc>('$address.city')` — resolves via `FieldRefType`.
+ * - **Tier 2 (explicit scalar):** `$min<number>('$price')` — manual result type.
+ * - **Tier 3 (untyped):** `$min('$price')` — defaults to `unknown`.
  *
- * @typeParam R - The expected result type (defaults to `unknown`).
- * @param field - A `$field` reference.
- * @returns An `Accumulator<R>`.
+ * For best type safety, prefer the callback builder (`acc.min('price')`).
+ *
+ * @param field - A `$field` reference (supports dot-paths with document type param).
+ * @returns An `Accumulator` with the resolved result type.
  *
  * @example
  * ```ts
+ * // Tier 1 — document type with dot-path
+ * $min<Doc>('$address.city')  // Accumulator<string>
+ *
  * // Tier 2 — explicit result type
- * const pipeline = orders.aggregate()
- * 	.groupBy('category', { cheapest: $min<number>('$price') })
+ * $min<number>('$price')      // Accumulator<number>
  *
- * // Tier 1 — callback builder (recommended)
- * orders.aggregate()
- * 	.groupBy('category', acc => ({ cheapest: acc.min('price') }))
+ * // Tier 3 — untyped
+ * $min('$price')              // Accumulator<unknown>
  * ```
  */
-declare const $min: <R = unknown>(field: `$${string}`) => Accumulator<R>;
+declare function $min<T extends Record<string, unknown>>(field: FieldRef<T>): Accumulator<FieldRefType<T, FieldRef<T>>>;
+declare function $min<R = unknown>(field: `$${string}`): Accumulator<R>;
 /**
  * Returns the maximum value across documents in each group.
  *
- * For full type safety, prefer the callback builder (`acc.max('price')`).
- * The standalone form accepts an explicit result type `R` for manual typing.
+ * Three tiers of type safety:
+ * - **Tier 1 (document type):** `$max<Doc>('$address.city')` — resolves via `FieldRefType`.
+ * - **Tier 2 (explicit scalar):** `$max<number>('$price')` — manual result type.
+ * - **Tier 3 (untyped):** `$max('$price')` — defaults to `unknown`.
+ *
+ * For best type safety, prefer the callback builder (`acc.max('price')`).
  *
- * @typeParam R - The expected result type (defaults to `unknown`).
- * @param field - A `$field` reference.
- * @returns An `Accumulator<R>`.
+ * @param field - A `$field` reference (supports dot-paths with document type param).
+ * @returns An `Accumulator` with the resolved result type.
  *
  * @example
  * ```ts
+ * // Tier 1 — document type with dot-path
+ * $max<Doc>('$tags.label')    // Accumulator<string>
+ *
  * // Tier 2 — explicit result type
- * const pipeline = orders.aggregate()
- * 	.groupBy('category', { priciest: $max<number>('$price') })
+ * $max<number>('$price')      // Accumulator<number>
  *
- * // Tier 1 — callback builder (recommended)
- * orders.aggregate()
- * 	.groupBy('category', acc => ({ priciest: acc.max('price') }))
+ * // Tier 3 — untyped
+ * $max('$price')              // Accumulator<unknown>
  * ```
  */
-declare const $max: <R = unknown>(field: `$${string}`) => Accumulator<R>;
+declare function $max<T extends Record<string, unknown>>(field: FieldRef<T>): Accumulator<FieldRefType<T, FieldRef<T>>>;
+declare function $max<R = unknown>(field: `$${string}`): Accumulator<R>;
 /**
  * Returns the first value in each group according to the document order.
  *
- * For full type safety, prefer the callback builder (`acc.first('name')`).
- * The standalone form accepts an explicit result type `R` for manual typing.
+ * Three tiers of type safety:
+ * - **Tier 1 (document type):** `$first<Doc>('$address.city')` — resolves via `FieldRefType`.
+ * - **Tier 2 (explicit scalar):** `$first<Date>('$createdAt')` — manual result type.
+ * - **Tier 3 (untyped):** `$first('$name')` — defaults to `unknown`.
  *
- * @typeParam R - The expected result type (defaults to `unknown`).
- * @param field - A `$field` reference.
- * @returns An `Accumulator<R>`.
+ * For best type safety, prefer the callback builder (`acc.first('name')`).
+ *
+ * @param field - A `$field` reference (supports dot-paths with document type param).
+ * @returns An `Accumulator` with the resolved result type.
  *
  * @example
  * ```ts
+ * // Tier 1 — document type with dot-path
+ * $first<Doc>('$address.city')  // Accumulator<string>
+ *
  * // Tier 2 — explicit result type
- * const pipeline = orders.aggregate()
- * 	.sort({ createdAt: 1 })
- * 	.groupBy('status', { earliest: $first<Date>('$createdAt') })
+ * $first<Date>('$createdAt')    // Accumulator<Date>
  *
- * // Tier 1 — callback builder (recommended)
- * orders.aggregate()
- * 	.sort({ createdAt: 1 })
- * 	.groupBy('status', acc => ({ earliest: acc.first('createdAt') }))
+ * // Tier 3 — untyped
+ * $first('$name')               // Accumulator<unknown>
  * ```
  */
-declare const $first: <R = unknown>(field: `$${string}`) => Accumulator<R>;
+declare function $first<T extends Record<string, unknown>>(field: FieldRef<T>): Accumulator<FieldRefType<T, FieldRef<T>>>;
+declare function $first<R = unknown>(field: `$${string}`): Accumulator<R>;
 /**
  * Returns the last value in each group according to the document order.
  *
- * For full type safety, prefer the callback builder (`acc.last('name')`).
- * The standalone form accepts an explicit result type `R` for manual typing.
+ * Three tiers of type safety:
+ * - **Tier 1 (document type):** `$last<Doc>('$address.city')` — resolves via `FieldRefType`.
+ * - **Tier 2 (explicit scalar):** `$last<Date>('$createdAt')` — manual result type.
+ * - **Tier 3 (untyped):** `$last('$name')` — defaults to `unknown`.
+ *
+ * For best type safety, prefer the callback builder (`acc.last('name')`).
  *
- * @typeParam R - The expected result type (defaults to `unknown`).
- * @param field - A `$field` reference.
- * @returns An `Accumulator<R>`.
+ * @param field - A `$field` reference (supports dot-paths with document type param).
+ * @returns An `Accumulator` with the resolved result type.
  *
  * @example
  * ```ts
+ * // Tier 1 — document type with dot-path
+ * $last<Doc>('$address.city')  // Accumulator<string>
+ *
  * // Tier 2 — explicit result type
- * const pipeline = orders.aggregate()
- * 	.sort({ createdAt: -1 })
- * 	.groupBy('status', { latest: $last<Date>('$createdAt') })
+ * $last<Date>('$createdAt')    // Accumulator<Date>
  *
- * // Tier 1 — callback builder (recommended)
- * orders.aggregate()
- * 	.sort({ createdAt: -1 })
- * 	.groupBy('status', acc => ({ latest: acc.last('createdAt') }))
+ * // Tier 3 — untyped
+ * $last('$name')               // Accumulator<unknown>
  * ```
  */
-declare const $last: <R = unknown>(field: `$${string}`) => Accumulator<R>;
+declare function $last<T extends Record<string, unknown>>(field: FieldRef<T>): Accumulator<FieldRefType<T, FieldRef<T>>>;
+declare function $last<R = unknown>(field: `$${string}`): Accumulator<R>;
 /**
  * Pushes values into an array for each group.
  *
  * May contain duplicates. Use `$addToSet` for unique values.
- * For full type safety, prefer the callback builder (`acc.push('name')`).
  *
- * @typeParam R - The element type (defaults to `unknown`).
- * @param field - A `$field` reference.
- * @returns An `Accumulator<R[]>`.
+ * Three tiers of type safety:
+ * - **Tier 1 (document type):** `$push<Doc>('$address.city')` — resolves via `FieldRefType`.
+ * - **Tier 2 (explicit scalar):** `$push<string>('$name')` — manual element type.
+ * - **Tier 3 (untyped):** `$push('$name')` — defaults to `unknown[]`.
+ *
+ * For best type safety, prefer the callback builder (`acc.push('name')`).
+ *
+ * @param field - A `$field` reference (supports dot-paths with document type param).
+ * @returns An `Accumulator` with the resolved array result type.
  *
  * @example
  * ```ts
+ * // Tier 1 — document type with dot-path
+ * $push<Doc>('$address.city')  // Accumulator<string[]>
+ *
  * // Tier 2 — explicit element type
- * const pipeline = orders.aggregate()
- * 	.groupBy('status', { items: $push<string>('$name') })
+ * $push<string>('$name')       // Accumulator<string[]>
  *
- * // Tier 1 — callback builder (recommended)
- * orders.aggregate()
- * 	.groupBy('status', acc => ({ items: acc.push('name') }))
+ * // Tier 3 — untyped
+ * $push('$name')               // Accumulator<unknown[]>
  * ```
  */
-declare const $push: <R = unknown>(field: `$${string}`) => Accumulator<R[]>;
+declare function $push<T extends Record<string, unknown>>(field: FieldRef<T>): Accumulator<FieldRefType<T, FieldRef<T>>[]>;
+declare function $push<R = unknown>(field: `$${string}`): Accumulator<R[]>;
 /**
  * Collects unique values into an array for each group (set semantics).
  *
  * Like `$push` but deduplicates.
- * For full type safety, prefer the callback builder (`acc.addToSet('tag')`).
  *
- * @typeParam R - The element type (defaults to `unknown`).
- * @param field - A `$field` reference.
- * @returns An `Accumulator<R[]>`.
+ * Three tiers of type safety:
+ * - **Tier 1 (document type):** `$addToSet<Doc>('$address.zip')` — resolves via `FieldRefType`.
+ * - **Tier 2 (explicit scalar):** `$addToSet<string>('$tag')` — manual element type.
+ * - **Tier 3 (untyped):** `$addToSet('$tag')` — defaults to `unknown[]`.
+ *
+ * For best type safety, prefer the callback builder (`acc.addToSet('tag')`).
+ *
+ * @param field - A `$field` reference (supports dot-paths with document type param).
+ * @returns An `Accumulator` with the resolved array result type.
  *
  * @example
  * ```ts
+ * // Tier 1 — document type with dot-path
+ * $addToSet<Doc>('$address.zip')  // Accumulator<string[]>
+ *
  * // Tier 2 — explicit element type
- * const pipeline = orders.aggregate()
- * 	.groupBy('category', { uniqueTags: $addToSet<string>('$tag') })
+ * $addToSet<string>('$tag')       // Accumulator<string[]>
  *
- * // Tier 1 — callback builder (recommended)
- * orders.aggregate()
- * 	.groupBy('category', acc => ({ uniqueTags: acc.addToSet('tag') }))
+ * // Tier 3 — untyped
+ * $addToSet('$tag')               // Accumulator<unknown[]>
  * ```
  */
-declare const $addToSet: <R = unknown>(field: `$${string}`) => Accumulator<R[]>;
+declare function $addToSet<T extends Record<string, unknown>>(field: FieldRef<T>): Accumulator<FieldRefType<T, FieldRef<T>>[]>;
+declare function $addToSet<R = unknown>(field: `$${string}`): Accumulator<R[]>;
 /**
  * Create a typed accumulator builder for use inside `groupBy` callbacks.
  *
@@ -947,19 +1229,20 @@ declare function createAccumulatorBuilder<T>(): AccumulatorBuilder<T>;
 /**
  * Create a typed expression builder for use inside `addFields` callbacks.
  *
- * The builder adds the `$` prefix to field names automatically and returns
- * properly typed `Expression<T>` values. Primarily used internally by
- * `AggregatePipeline.addFields` — most users interact with the builder via
- * the callback parameter rather than calling this directly.
+ * The builder accepts either a field name string (auto-prefixed with `$`) or a
+ * pre-built `Expression<R>` from another builder method, enabling composition.
+ * Primarily used internally by `AggregatePipeline.addFields` — most users
+ * interact with the builder via the callback parameter rather than calling
+ * this directly.
  *
  * @typeParam T - The current pipeline output document type.
  * @returns An `ExpressionBuilder<T>` with methods for each MongoDB expression operator.
  *
  * @example
  * ```ts
- * const expr = createExpressionBuilder<{ salary: number; name: string; hiredAt: Date }>()
- * expr.year('hiredAt')         // { __expr: true, value: { $year: '$hiredAt' } }
- * expr.multiply('salary', 0.9) // { __expr: true, value: { $multiply: ['$salary', 0.9] } }
+ * const expr = createExpressionBuilder<{ salary: number; hiredAt: Date }>()
+ * expr.year('hiredAt')                        // { __expr: true, value: { $year: '$hiredAt' } }
+ * expr.round(expr.multiply('salary', 0.1), 2) // { __expr: true, value: { $round: [{ $multiply: ['$salary', 0.1] }, 2] } }
  * ```
  */
 declare function createExpressionBuilder<T>(): ExpressionBuilder<T>;
@@ -1005,40 +1288,21 @@ type ComparisonOperators<V> = {
 } & (V extends string ? {
     $regex?: RegExp | string;
 } : unknown);
-/** Depth counter for limiting dot-notation recursion. Index = current depth, value = next depth. */
-type Prev = [never, 0, 1, 2];
-/**
- * Generates a union of all valid dot-separated paths for nested object fields in `T`.
- *
- * Recursion is limited to 3 levels deep to prevent TypeScript compilation performance issues.
- * Only plain object fields are traversed — arrays, `Date`, `RegExp`, and `ObjectId` are
- * treated as leaf nodes and do not produce sub-paths.
- *
- * @example
- * ```ts
- * type User = { address: { city: string; geo: { lat: number; lng: number } } }
- *
- * // DotPaths<User> = 'address.city' | 'address.geo' | 'address.geo.lat' | 'address.geo.lng'
- * ```
- */
-type DotPaths<T, Depth extends number = 3> = Depth extends 0 ? never : {
-    [K in keyof T & string]: NonNullable<T[K]> extends ReadonlyArray<unknown> | Date | RegExp | ObjectId ? never : NonNullable<T[K]> extends Record<string, unknown> ? `${K}.${keyof NonNullable<T[K]> & string}` | `${K}.${DotPaths<NonNullable<T[K]>, Prev[Depth]>}` : never;
-}[keyof T & string];
 /**
- * Resolves the value type at a dot-separated path `P` within type `T`.
+ * Dot-separated paths for nested fields, excluding top-level keys.
  *
- * Splits `P` on the first `.` and recursively descends into `T`'s nested types.
- * Returns `never` if the path is invalid.
+ * Filters out `keyof T & string` because top-level fields are already
+ * handled by slot (A) of {@link TypedFilter}. Keeping them separate
+ * preserves the intersection structure for lazy TypeScript evaluation.
  *
  * @example
  * ```ts
- * type User = { address: { city: string; geo: { lat: number } } }
- *
- * // DotPathType<User, 'address.city'> = string
- * // DotPathType<User, 'address.geo.lat'> = number
+ * type User = { name: string; address: { city: string } }
+ * type Paths = DotSubPaths<User>
+ * //   ^? 'address.city'
  * ```
  */
-type DotPathType<T, P extends string> = P extends `${infer K}.${infer Rest}` ? K extends keyof T ? Rest extends keyof NonNullable<T[K]> ? NonNullable<T[K]>[Rest] : DotPathType<NonNullable<T[K]>, Rest> : never : P extends keyof T ? T[P] : never;
+type DotSubPaths<T> = Exclude<DotPath<T>, keyof T & string>;
 /**
  * Strict type-safe MongoDB filter query type.
  *
@@ -1049,7 +1313,7 @@ type DotPathType<T, P extends string> = P extends `${infer K}.${infer Rest}` ? K
  * Supports three forms of filter expressions:
  * - **Direct field values** (implicit `$eq`): `{ name: 'Alice' }`
  * - **Comparison operators**: `{ age: { $gt: 25 } }` or `{ age: $gt(25) }`
- * - **Dot notation** for nested fields up to 3 levels: `{ 'address.city': 'NYC' }`
+ * - **Dot notation** including nested and array-traversed fields: `{ 'address.city': 'NYC' }`
  *
  * Logical operators `$and`, `$or`, and `$nor` accept arrays of `TypedFilter<T>`
  * for composing complex queries.
@@ -1078,7 +1342,7 @@ type DotPathType<T, P extends string> = P extends `${infer K}.${infer Rest}` ? K
 type TypedFilter<T> = {
     [K in keyof T]?: T[K] | ComparisonOperators<T[K]>;
 } & {
-    [P in DotPaths<T>]?: DotPathType<T, P> | ComparisonOperators<DotPathType<T, P>>;
+    [P in DotSubPaths<T>]?: DotPathValue<T, P> | ComparisonOperators<DotPathValue<T, P>>;
 } & {
     /** Joins clauses with a logical AND. Matches documents that satisfy all filters. */
     $and?: TypedFilter<T>[];
@@ -1239,72 +1503,602 @@ type CursorPage<TDoc> = {
     endCursor: string | null;
 };
 
+type IncludeValue = 1 | true;
+type ExcludeValue = 0 | false;
 /**
- * Type-safe sort specification for a document type.
+ * Inclusion projection — maps document fields to `1 | true`.
  *
- * Constrains sort keys to top-level fields of `T` with direction `1` (ascending)
- * or `-1` (descending). Dot-path sorts deferred to v1.0.
+ * Allows `_id: 0 | false` to suppress the `_id` field from the result.
+ * All other fields only accept inclusion values (`1` or `true`).
  *
  * @example
  * ```ts
- * const sort: TypedSort<User> = { name: 1, createdAt: -1 }
+ * type UserInclusion = InclusionProjection<User>
+ * const proj: UserInclusion = { name: 1, email: 1 }
+ * const withoutId: UserInclusion = { name: 1, _id: 0 }
  * ```
  */
-type TypedSort<T> = Partial<Record<keyof T & string, 1 | -1>>;
+type InclusionProjection<T> = {
+    [K in keyof T & string]?: K extends '_id' ? IncludeValue | ExcludeValue : IncludeValue;
+};
 /**
- * Type-safe cursor wrapping MongoDB's `FindCursor`.
+ * Exclusion projection — maps document fields to `0 | false`.
  *
- * Provides chainable query modifiers (`sort`, `skip`, `limit`, `hint`) that return
- * `this` for fluent chaining, and terminal methods (`toArray`,
- * `[Symbol.asyncIterator]`) that validate each document against the
- * collection's Zod schema before returning.
+ * Removes the specified fields from the result, keeping all others.
  *
- * Created by {@link find} — do not construct directly.
+ * @example
+ * ```ts
+ * type UserExclusion = ExclusionProjection<User>
+ * const proj: UserExclusion = { email: 0, age: 0 }
+ * ```
+ */
+type ExclusionProjection<T> = {
+    [K in keyof T & string]?: ExcludeValue;
+};
+/**
+ * Union of inclusion or exclusion projection for a document type `T`.
  *
- * @typeParam TDef - The collection definition type, used to infer the document type.
- * @typeParam TIndexNames - Union of declared index names accepted by `.hint()`.
+ * MongoDB projections must be either all-inclusion or all-exclusion (with the
+ * exception of `_id`, which can always be excluded). This type enforces that
+ * constraint at the type level.
  *
  * @example
  * ```ts
- * const docs = await find(users, { role: 'admin' })
- *   .sort({ name: 1 })
- *   .limit(10)
- *   .toArray()
+ * type UserProjection = TypedProjection<User>
+ * const include: UserProjection = { name: 1, email: 1 }
+ * const exclude: UserProjection = { email: 0, age: 0 }
  * ```
  */
-declare class TypedFindCursor<TDef extends AnyCollection, TIndexNames extends string = string> {
-    /** @internal */
-    private cursor;
-    /** @internal */
-    private schema;
-    /** @internal */
-    private collectionName;
-    /** @internal */
-    private mode;
-    /** @internal */
-    private readonly nativeCollection;
-    /** @internal */
-    private readonly filter;
-    /** @internal */
-    private sortSpec;
-    /** @internal */
-    constructor(cursor: FindCursor<InferDocument<TDef>>, definition: TDef, mode: ValidationMode | false, nativeCollection: Collection<InferDocument<TDef>>, filter: any);
+type TypedProjection<T> = InclusionProjection<T> | ExclusionProjection<T>;
+/** True if any key in `P` (excluding `_id`) has value `1 | true`. */
+type IsInclusion<P> = true extends {
+    [K in keyof P]: K extends '_id' ? never : P[K] extends IncludeValue ? true : never;
+}[keyof P] ? true : false;
+/** Keys of `P` whose value is `1 | true` (excluding `_id`). */
+type IncludedKeys<P> = {
+    [K in keyof P]: K extends '_id' ? never : P[K] extends IncludeValue ? K : never;
+}[keyof P];
+/** Keys of `P` whose value is `0 | false`. */
+type ExcludedKeys<P> = {
+    [K in keyof P]: P[K] extends ExcludeValue ? K : never;
+}[keyof P];
+/** True if `P` has `_id` set to `0 | false`. */
+type IsIdSuppressed<P> = '_id' extends keyof P ? P['_id'] extends ExcludeValue ? true : false : false;
+/**
+ * Computes the result type after applying a projection `P` to document type `T`.
+ *
+ * For inclusion projections (`{ name: 1 }`), returns only the included fields
+ * plus `_id` (unless `_id: 0` is specified). For exclusion projections
+ * (`{ email: 0 }`), returns all fields except the excluded ones.
+ *
+ * @example
+ * ```ts
+ * type User = { _id: ObjectId; name: string; email: string; age: number }
+ *
+ * // Inclusion: picks name + _id
+ * type A = ProjectionResult<User, { name: 1 }>
+ * //   ^? { _id: ObjectId; name: string }
+ *
+ * // Inclusion with _id suppressed
+ * type B = ProjectionResult<User, { name: 1; _id: 0 }>
+ * //   ^? { name: string }
+ *
+ * // Exclusion: drops email
+ * type C = ProjectionResult<User, { email: 0 }>
+ * //   ^? { _id: ObjectId; name: string; age: number }
+ * ```
+ */
+type ProjectionResult<T, P> = IsInclusion<P> extends true ? IsIdSuppressed<P> extends true ? Prettify<Pick<T, IncludedKeys<P> & keyof T>> : Prettify<Pick<T, (IncludedKeys<P> | '_id') & keyof T>> : IsIdSuppressed<P> extends true ? Prettify<Omit<T, ExcludedKeys<P>>> : Prettify<Omit<T, Exclude<ExcludedKeys<P>, '_id'>>>;
+/**
+ * Returns `true` if the projection is an inclusion projection.
+ *
+ * A projection is considered inclusion when any key other than `_id` has
+ * a value of `1` or `true`. This mirrors the MongoDB rule: you cannot mix
+ * inclusion and exclusion (except for `_id`, which may always be suppressed).
+ *
+ * @example
+ * ```ts
+ * isInclusionProjection({ name: 1 })            // true
+ * isInclusionProjection({ name: 1, _id: 0 })    // true
+ * isInclusionProjection({ email: 0 })            // false
+ * ```
+ */
+declare function isInclusionProjection(projection: Record<string, 0 | 1 | boolean>): boolean;
+/**
+ * Derives a scoped Zod schema by applying a MongoDB-style projection.
+ *
+ * For inclusion projections (`{ name: 1, email: 1 }`), returns a schema with
+ * only the specified fields plus `_id` (unless `_id: 0`). For exclusion
+ * projections (`{ email: 0 }`), returns a schema with the specified fields
+ * removed.
+ *
+ * Keys not present in the original schema are silently ignored.
+ *
+ * @example
+ * ```ts
+ * const userSchema = z.object({
+ *   _id: z.string(),
+ *   name: z.string(),
+ *   email: z.string(),
+ *   age: z.number(),
+ * })
+ *
+ * // Inclusion: picks name + email + _id
+ * const projected = deriveProjectedSchema(userSchema, { name: 1, email: 1 })
+ *
+ * // Exclusion: drops email
+ * const excluded = deriveProjectedSchema(userSchema, { email: 0 })
+ * ```
+ */
+declare function deriveProjectedSchema(schema: z.ZodObject<z.core.$ZodShape>, projection: Record<string, 0 | 1 | boolean>): z.ZodObject<z.core.$ZodShape>;
+
+/**
+ * Typed return value from {@link PopulateRefBuilder.project}.
+ *
+ * Carries the projection type `P` for compile-time narrowing in populate calls.
+ * Callers never construct this directly — it is returned by the builder and
+ * consumed by the `.populate()` overload to narrow the result type.
+ *
+ * @example
+ * ```ts
+ * // P is inferred as { name: 1; email: 1 } — post.authorId is narrowed accordingly
+ * const post = await posts.findOne({}).populate('authorId', (b) => b.project({ name: 1, email: 1 }))
+ * ```
+ */
+type PopulateProjectionConfig<P> = {
+    readonly projection: P;
+};
+/**
+ * Fluent builder passed to populate projection callbacks.
+ *
+ * Call `.project()` to specify which fields to fetch from the referenced collection.
+ * The projection type `P` flows back to the `.populate()` overload to narrow the
+ * result type at compile time.
+ *
+ * @typeParam TDoc - The referenced document type (e.g. `InferDocument<typeof Users>`).
+ *
+ * @example
+ * ```ts
+ * posts.findOne({}).populate('authorId', (b) => b.project({ name: 1, email: 1 }))
+ * // post.authorId is narrowed to { _id: ObjectId; name: string; email: string }
+ * ```
+ */
+declare class PopulateRefBuilder<TDoc> {
     /**
-     * Set the sort order for the query.
+     * Declare a projection to apply when fetching the referenced documents.
      *
-     * Only top-level document fields are accepted as sort keys.
-     * Values must be `1` (ascending) or `-1` (descending).
+     * Supported: inclusion (`{ name: 1 }`), exclusion (`{ email: 0 }`), or
+     * `_id` suppression (`{ name: 1, _id: 0 }`).
      *
-     * @param spec - Sort specification mapping field names to sort direction.
-     * @returns `this` for chaining.
+     * @param projection - MongoDB-style inclusion or exclusion projection.
+     * @returns A config object carrying the projection type for compile-time narrowing.
      *
      * @example
      * ```ts
-     * find(users, {}).sort({ name: 1, age: -1 }).toArray()
+     * (b) => b.project({ name: 1, email: 1 })
+     * (b) => b.project({ password: 0 })
      * ```
      */
-    sort(spec: TypedSort<InferDocument<TDef>>): this;
-    /**
+    project<P extends TypedProjection<TDoc>>(projection: P): PopulateProjectionConfig<P>;
+}
+
+/**
+ * Resolve the populated type for a ref field, preserving wrappers.
+ *
+ * Transforms the field type from ID to document based on the Zod wrapper:
+ * - `ObjectId` → `InferDocument<Target>`
+ * - `ObjectId[]` → `InferDocument<Target>[]`
+ * - `ObjectId | undefined` → `InferDocument<Target> | undefined`
+ * - `ObjectId | null` → `InferDocument<Target> | null`
+ *
+ * @example
+ * ```ts
+ * type Author = PopulateField<typeof Posts, 'authorId'>
+ * //   ^? { _id: ObjectId; name: string; email: string; companyId: ObjectId }
+ *
+ * type Cats = PopulateField<typeof Posts, 'categoryIds'>
+ * //   ^? { _id: ObjectId; title: string }[]
+ * ```
+ */
+type PopulateField<TDef extends AnyCollection, K extends RefFields<TDef>> = TDef['shape'][K] extends z.ZodArray<infer _E> ? InferDocument<ExtractRefCollection<TDef, K>>[] : TDef['shape'][K] extends z.ZodOptional<infer _U> ? InferDocument<ExtractRefCollection<TDef, K>> | undefined : TDef['shape'][K] extends z.ZodNullable<infer _U> ? InferDocument<ExtractRefCollection<TDef, K>> | null : InferDocument<ExtractRefCollection<TDef, K>>;
+/**
+ * Document type with specified ref fields replaced by their populated types.
+ *
+ * @example
+ * ```ts
+ * type PostWithAuthor = Populated<typeof Posts, 'authorId'>
+ * //   ^? { _id: ObjectId; title: string; authorId: User; categoryIds: ObjectId[]; ... }
+ *
+ * type PostFull = Populated<typeof Posts, 'authorId' | 'categoryIds'>
+ * //   ^? { ...; authorId: User; categoryIds: Category[]; ... }
+ * ```
+ */
+type Populated<TDef extends AnyCollection, K extends RefFields<TDef>> = Prettify<Omit<InferDocument<TDef>, K> & {
+    [P in K]: PopulateField<TDef, P>;
+}>;
+/**
+ * Apply a single populate step to the output type.
+ *
+ * Without rename: replaces the field type in-place.
+ * With rename: removes the old key and adds the new key with the populated type.
+ *
+ * @example
+ * ```ts
+ * // No rename: authorId stays, type changes to User
+ * type A = ApplyPopulate<PostDoc, typeof Posts, 'authorId'>
+ *
+ * // Rename: authorId removed, author added with User type
+ * type B = ApplyPopulate<PostDoc, typeof Posts, 'authorId', 'author'>
+ * ```
+ */
+type ApplyPopulate<T, TDef extends AnyCollection, K extends RefFields<TDef>, TAs extends string = K> = Prettify<Omit<T, K> & {
+    [P in TAs]: PopulateField<TDef, K>;
+}>;
+/**
+ * Resolve the projected populated type for a ref field, preserving wrappers.
+ *
+ * Like {@link PopulateField} but applies `ProjectionResult<T, P>` to narrow
+ * the document type to only the projected fields.
+ *
+ * - `ObjectId` → `ProjectionResult<InferDocument<Target>, P>`
+ * - `ObjectId[]` → `ProjectionResult<InferDocument<Target>, P>[]`
+ * - `ObjectId | undefined` → `ProjectionResult<InferDocument<Target>, P> | undefined`
+ * - `ObjectId | null` → `ProjectionResult<InferDocument<Target>, P> | null`
+ *
+ * @example
+ * ```ts
+ * type Author = PopulateFieldProjected<typeof Posts, 'authorId', { name: 1; email: 1 }>
+ * //   ^? { _id: ObjectId; name: string; email: string }
+ * ```
+ */
+type PopulateFieldProjected<TDef extends AnyCollection, K extends RefFields<TDef>, P> = TDef['shape'][K] extends z.ZodArray<infer _E> ? ProjectionResult<InferDocument<ExtractRefCollection<TDef, K>>, P>[] : TDef['shape'][K] extends z.ZodOptional<infer _U> ? ProjectionResult<InferDocument<ExtractRefCollection<TDef, K>>, P> | undefined : TDef['shape'][K] extends z.ZodNullable<infer _U> ? ProjectionResult<InferDocument<ExtractRefCollection<TDef, K>>, P> | null : ProjectionResult<InferDocument<ExtractRefCollection<TDef, K>>, P>;
+/**
+ * Apply a projected populate step to the output type.
+ *
+ * Like {@link ApplyPopulate} but uses {@link PopulateFieldProjected} to narrow
+ * the result to only the projected fields. Use `TAs` to rename the output field.
+ *
+ * @example
+ * ```ts
+ * type Result = ApplyPopulateProjected<PostDoc, typeof Posts, 'authorId', { name: 1; email: 1 }>
+ * //   ^? { ...; authorId: { _id: ObjectId; name: string; email: string } }
+ * ```
+ */
+type ApplyPopulateProjected<T, TDef extends AnyCollection, K extends RefFields<TDef>, P, TAs extends string = K> = Prettify<Omit<T, K> & {
+    [F in TAs]: PopulateFieldProjected<TDef, K, P>;
+}>;
+/**
+ * Apply a populate at an arbitrary nesting depth.
+ *
+ * Splits the dot-path and recursively navigates into the output type.
+ * If a parent field is an array, the element type is transformed.
+ *
+ * @example
+ * ```ts
+ * // Nested: author.companyId → author.company
+ * type Result = DeepPopulate<PostWithAuthor, 'author.companyId', 'companyId', 'company', Company>
+ * ```
+ */
+type DeepPopulate<T, Path extends string, LeafField extends string, TAs extends string, PopType> = Path extends `${infer Parent}.${infer Rest}` ? Parent extends keyof T ? T[Parent] extends (infer E)[] ? Prettify<Omit<T, Parent> & {
+    [P in Parent]: DeepPopulate<E, Rest, LeafField, TAs, PopType>[];
+}> : Prettify<Omit<T, Parent> & {
+    [P in Parent]: DeepPopulate<T[Parent], Rest, LeafField, TAs, PopType>;
+}> : never : Prettify<Omit<T, LeafField> & {
+    [P in TAs]: PopType;
+}>;
+/**
+ * Valid nested populate paths given the current TPopMap.
+ *
+ * Produces a union of `parentPath.refField` strings where `parentPath`
+ * is a key in TPopMap and `refField` is a ref-bearing field in that
+ * parent's collection definition.
+ *
+ * @example
+ * ```ts
+ * // If TPopMap = { author: typeof Users }, produces:
+ * // 'author.companyId' | 'author.<other ref fields>'
+ * type Paths = NestedRefPath<{ author: typeof Users }>
+ * ```
+ */
+type NestedRefPath<TPopMap extends Record<string, AnyCollection>> = {
+    [Path in keyof TPopMap & string]: `${Path}.${RefFields<TPopMap[Path]>}`;
+}[keyof TPopMap & string];
+/**
+ * Runtime data for a single populate step.
+ *
+ * Built by each `.populate()` call and consumed by `executePopulate()`.
+ */
+type PopulateStep = {
+    /** The original field path from the root collection. */
+    readonly originalPath: string;
+    /** The leaf field name in the target shape. */
+    readonly leafField: string;
+    /** The output field name (renamed or original). */
+    readonly as: string;
+    /** Parent path in the output document for nesting, or undefined for top-level. */
+    readonly parentOutputPath: string | undefined;
+    /** The target collection definition resolved from RefMarker metadata. */
+    readonly targetCollection: AnyCollection;
+    /** Whether the field is an array ref. */
+    readonly isArray: boolean;
+    /** MongoDB projection spec to pass to the `$in` query. Omit to fetch the full document. */
+    readonly projection?: Record<string, 0 | 1 | boolean>;
+};
+
+/**
+ * Extract the parent segment from a dot-separated path.
+ *
+ * @example
+ * ```ts
+ * type P = ExtractParent<'author.companyId'> // 'author'
+ * ```
+ */
+type ExtractParent$1<T extends string> = T extends `${infer P}.${string}` ? P : never;
+/**
+ * Extract the leaf segment from a dot-separated path.
+ *
+ * @example
+ * ```ts
+ * type L = ExtractLeaf<'author.companyId'> // 'companyId'
+ * ```
+ */
+type ExtractLeaf$1<T extends string> = T extends `${string}.${infer L}` ? L : never;
+/**
+ * Cursor with chained populate steps, wrapping a {@link TypedFindCursor}.
+ *
+ * Created by calling `.populate()` on a `TypedFindCursor`. Exposes only
+ * `.populate()` (for additional fields) and terminal methods (`toArray`,
+ * async iteration). Cursor modifiers (`sort`, `skip`, `limit`) are not
+ * available -- they must be called before `.populate()`.
+ *
+ * @typeParam TDef - The root collection definition type.
+ * @typeParam TOutput - The current output document type after populate transforms.
+ * @typeParam TPopMap - Map of populated alias names to their collection definitions,
+ *   used to resolve nested populate paths.
+ *
+ * @example
+ * ```ts
+ * const posts = await db.use(Posts)
+ *   .find({ published: true })
+ *   .sort({ createdAt: -1 })
+ *   .limit(10)
+ *   .populate('authorId', 'author')
+ *   .populate('categoryIds')
+ *   .toArray()
+ * ```
+ */
+declare class PopulateCursor<TDef extends AnyCollection, TOutput, TPopMap extends Record<string, AnyCollection> = Record<string, never>> {
+    private readonly cursor;
+    private readonly definition;
+    private readonly steps;
+    private readonly nativeCollection;
+    /** @internal */
+    constructor(cursor: TypedFindCursor<TDef>, definition: TDef, steps: readonly PopulateStep[], nativeCollection: Collection<InferDocument<TDef>>);
+    /**
+     * Populate a top-level ref field, keeping the original field name.
+     *
+     * @param field - A ref-bearing field name on the root collection.
+     * @returns A new cursor with the field type replaced by the referenced document.
+     *
+     * @example
+     * ```ts
+     * const posts = await db.use(Posts)
+     *   .find({})
+     *   .populate('authorId')
+     *   .toArray()
+     * // posts[0].authorId is now a User document instead of ObjectId
+     * ```
+     */
+    populate<K extends RefFields<TDef>>(field: K): PopulateCursor<TDef, ApplyPopulate<TOutput, TDef, K>, TPopMap & {
+        [P in K]: ExtractRefCollection<TDef, K>;
+    }>;
+    /**
+     * Populate a top-level ref field with a projection, keeping the original field name.
+     *
+     * @param field - A ref-bearing field name on the root collection.
+     * @param configure - Callback receiving a builder; call `.project()` to set the projection.
+     * @returns A new cursor with the field type narrowed to only the projected fields.
+     *
+     * @example
+     * ```ts
+     * const posts = await db.use(Posts)
+     *   .find({})
+     *   .populate('authorId', (b) => b.project({ name: 1, email: 1 }))
+     *   .toArray()
+     * // posts[0].authorId is { _id: ObjectId; name: string; email: string }
+     * ```
+     */
+    populate<K extends RefFields<TDef>, P>(field: K, configure: (b: PopulateRefBuilder<InferDocument<ExtractRefCollection<TDef, K>>>) => PopulateProjectionConfig<P>): PopulateCursor<TDef, ApplyPopulateProjected<TOutput, TDef, K, P>, TPopMap & {
+        [F in K]: ExtractRefCollection<TDef, K>;
+    }>;
+    /**
+     * Populate a top-level ref field and rename it in the output.
+     *
+     * @param field - A ref-bearing field name on the root collection.
+     * @param as - The new field name in the output document.
+     * @returns A new cursor with the old field removed and the new field added.
+     *
+     * @example
+     * ```ts
+     * const posts = await db.use(Posts)
+     *   .find({})
+     *   .populate('authorId', 'author')
+     *   .toArray()
+     * // posts[0].author is a User document; posts[0].authorId no longer exists
+     * ```
+     */
+    populate<K extends RefFields<TDef>, TAs extends string>(field: K, as: TAs): PopulateCursor<TDef, ApplyPopulate<TOutput, TDef, K, TAs>, TPopMap & {
+        [P in TAs]: ExtractRefCollection<TDef, K>;
+    }>;
+    /**
+     * Populate a nested ref field, keeping the leaf field name.
+     *
+     * The parent path must have been populated in a previous `.populate()` call.
+     *
+     * @param path - A dot-separated path like `'author.companyId'`.
+     * @returns A new cursor with the nested field type replaced.
+     *
+     * @example
+     * ```ts
+     * const posts = await db.use(Posts)
+     *   .find({})
+     *   .populate('authorId', 'author')
+     *   .populate('author.companyId')
+     *   .toArray()
+     * // posts[0].author.companyId is now a Company document
+     * ```
+     */
+    populate<TPath extends NestedRefPath<TPopMap>>(path: TPath): PopulateCursor<TDef, DeepPopulate<TOutput, `${ExtractParent$1<TPath>}.${ExtractLeaf$1<TPath>}`, ExtractLeaf$1<TPath>, ExtractLeaf$1<TPath>, PopulateField<TPopMap[ExtractParent$1<TPath>], ExtractLeaf$1<TPath> & RefFields<TPopMap[ExtractParent$1<TPath>]>>>, TPopMap & {
+        [P in `${ExtractParent$1<TPath>}.${ExtractLeaf$1<TPath>}`]: ExtractRefCollection<TPopMap[ExtractParent$1<TPath>], ExtractLeaf$1<TPath> & RefFields<TPopMap[ExtractParent$1<TPath>]>>;
+    }>;
+    /**
+     * Populate a nested ref field and rename the leaf in the output.
+     *
+     * The parent path must have been populated in a previous `.populate()` call.
+     *
+     * @param path - A dot-separated path like `'author.companyId'`.
+     * @param as - The new name for the leaf field in the output.
+     * @returns A new cursor with the nested field renamed and typed.
+     *
+     * @example
+     * ```ts
+     * const posts = await db.use(Posts)
+     *   .find({})
+     *   .populate('authorId', 'author')
+     *   .populate('author.companyId', 'company')
+     *   .toArray()
+     * // posts[0].author.company is a Company document
+     * ```
+     */
+    populate<TPath extends NestedRefPath<TPopMap>, TAs extends string>(path: TPath, as: TAs): PopulateCursor<TDef, DeepPopulate<TOutput, `${ExtractParent$1<TPath>}.${TAs}`, ExtractLeaf$1<TPath>, TAs, PopulateField<TPopMap[ExtractParent$1<TPath>], ExtractLeaf$1<TPath> & RefFields<TPopMap[ExtractParent$1<TPath>]>>>, TPopMap & {
+        [P in `${ExtractParent$1<TPath>}.${TAs}`]: ExtractRefCollection<TPopMap[ExtractParent$1<TPath>], ExtractLeaf$1<TPath> & RefFields<TPopMap[ExtractParent$1<TPath>]>>;
+    }>;
+    /**
+     * Execute the query and return all matching documents as a populated array.
+     *
+     * Fetches all documents from the underlying cursor, then applies populate
+     * steps in order using batch `$in` queries (no N+1 problem).
+     *
+     * @returns Array of populated documents.
+     *
+     * @example
+     * ```ts
+     * const posts = await db.use(Posts)
+     *   .find({})
+     *   .populate('authorId', 'author')
+     *   .toArray()
+     * ```
+     */
+    toArray(): Promise<TOutput[]>;
+    /**
+     * Async iterator for streaming populated documents.
+     *
+     * Fetches all documents first (populate requires the full batch for
+     * efficient `$in` queries), then yields results one at a time.
+     *
+     * @yields Populated documents one at a time.
+     *
+     * @example
+     * ```ts
+     * for await (const post of db.use(Posts).find({}).populate('authorId', 'author')) {
+     *   console.log(post.author.name)
+     * }
+     * ```
+     */
+    [Symbol.asyncIterator](): AsyncGenerator<TOutput>;
+}
+/**
+ * Create a new {@link PopulateCursor} from a {@link TypedFindCursor}.
+ *
+ * This factory function exists to break the circular import between
+ * `query/cursor.ts` and `populate/cursor.ts`. The `TypedFindCursor.populate()`
+ * method uses a lazy `require()` to call this function at runtime.
+ *
+ * @param cursor - The typed find cursor to wrap.
+ * @param definition - The collection definition.
+ * @param steps - Initial populate steps (typically empty).
+ * @returns A new PopulateCursor instance.
+ *
+ * @example
+ * ```ts
+ * const popCursor = createPopulateCursor(typedCursor, Posts, [])
+ * ```
+ */
+declare function createPopulateCursor<TDef extends AnyCollection>(cursor: TypedFindCursor<TDef>, definition: TDef, steps: readonly PopulateStep[]): PopulateCursor<TDef, InferDocument<TDef>>;
+
+/**
+ * Type-safe sort specification for a document type.
+ *
+ * Constrains sort keys to top-level fields of `T` with direction `1` (ascending)
+ * or `-1` (descending). Dot-path sorts deferred to v1.0.
+ *
+ * @example
+ * ```ts
+ * const sort: TypedSort<User> = { name: 1, createdAt: -1 }
+ * ```
+ */
+type TypedSort<T> = Partial<Record<keyof T & string, 1 | -1>>;
+/**
+ * Type-safe cursor wrapping MongoDB's `FindCursor`.
+ *
+ * Provides chainable query modifiers (`sort`, `skip`, `limit`, `hint`) that return
+ * `this` for fluent chaining, and terminal methods (`toArray`,
+ * `[Symbol.asyncIterator]`) that validate each document against the
+ * collection's Zod schema before returning.
+ *
+ * Created by {@link find} — do not construct directly.
+ *
+ * @typeParam TDef - The collection definition type, used to infer the document type.
+ * @typeParam TIndexNames - Union of declared index names accepted by `.hint()`.
+ * @typeParam TOutput - The output document type, narrowed by `.project()`.
+ *
+ * @example
+ * ```ts
+ * const docs = await find(users, { role: 'admin' })
+ *   .sort({ name: 1 })
+ *   .limit(10)
+ *   .toArray()
+ * ```
+ */
+declare class TypedFindCursor<TDef extends AnyCollection, TIndexNames extends string = string, TOutput = InferDocument<TDef>> {
+    /** @internal */
+    private cursor;
+    /** @internal */
+    readonly definition: TDef;
+    /** @internal */
+    private schema;
+    /** @internal */
+    private collectionName;
+    /** @internal */
+    private mode;
+    /** @internal */
+    readonly nativeCollection: Collection<InferDocument<TDef>>;
+    /** @internal */
+    private readonly filter;
+    /** @internal */
+    private readonly session;
+    /** @internal */
+    private sortSpec;
+    /** @internal */
+    private projectedSchema;
+    /** @internal */
+    constructor(cursor: FindCursor<InferDocument<TDef>>, definition: TDef, mode: ValidationMode | false, nativeCollection: Collection<InferDocument<TDef>>, filter: any, session?: ClientSession);
+    /**
+     * Set the sort order for the query.
+     *
+     * Only top-level document fields are accepted as sort keys.
+     * Values must be `1` (ascending) or `-1` (descending).
+     *
+     * @param spec - Sort specification mapping field names to sort direction.
+     * @returns `this` for chaining.
+     *
+     * @example
+     * ```ts
+     * find(users, {}).sort({ name: 1, age: -1 }).toArray()
+     * ```
+     */
+    sort(spec: TypedSort<InferDocument<TDef>>): this;
+    /**
      * Skip the first `n` documents in the result set.
      *
      * @param n - Number of documents to skip.
@@ -1348,6 +2142,100 @@ declare class TypedFindCursor<TDef extends AnyCollection, TIndexNames extends st
      * ```
      */
     hint(indexName: TIndexNames): this;
+    /**
+     * Apply a projection to narrow the returned fields.
+     *
+     * Inclusion projections (`{ name: 1 }`) return only the specified fields
+     * plus `_id` (unless `_id: 0`). Exclusion projections (`{ email: 0 }`)
+     * return all fields except those excluded.
+     *
+     * The cursor's output type is narrowed at compile time. A derived Zod
+     * schema is built for runtime validation of the projected fields.
+     *
+     * Projects from the original document type, not from a previous projection.
+     * Calling `.project()` twice overrides the previous projection.
+     *
+     * @param spec - Type-safe projection document.
+     * @returns A new cursor with the narrowed output type.
+     *
+     * @example
+     * ```ts
+     * const names = await find(users, {})
+     *   .project({ name: 1 })
+     *   .sort({ name: 1 })
+     *   .toArray()
+     * // names[0].name   ✓
+     * // names[0].email  TS error
+     * ```
+     */
+    project<P extends TypedProjection<InferDocument<TDef>>>(spec: P): TypedFindCursor<TDef, TIndexNames, Prettify<ProjectionResult<InferDocument<TDef>, P>>>;
+    /**
+     * Populate a top-level ref field, keeping the original field name.
+     *
+     * Transitions to a {@link PopulateCursor} that only exposes `.populate()`
+     * and terminal methods. Cursor modifiers (`sort`, `skip`, `limit`) must
+     * be called before `.populate()`.
+     *
+     * @param field - A ref-bearing field name on the root collection.
+     * @returns A populate cursor with the field type replaced by the referenced document.
+     *
+     * @example
+     * ```ts
+     * const posts = await db.use(Posts)
+     *   .find({})
+     *   .populate('authorId')
+     *   .toArray()
+     * ```
+     */
+    populate<K extends RefFields<TDef>>(field: K): PopulateCursor<TDef, ApplyPopulate<TOutput, TDef, K>, {
+        [P in K]: ExtractRefCollection<TDef, K>;
+    }>;
+    /**
+     * Populate a top-level ref field with a projection, keeping the original field name.
+     *
+     * Transitions to a {@link PopulateCursor}. Cursor modifiers (`sort`, `skip`, `limit`)
+     * must be called before `.populate()`.
+     *
+     * @param field - A ref-bearing field name on the root collection.
+     * @param configure - Callback receiving a builder; call `.project()` to set the projection.
+     * @returns A populate cursor with the field type narrowed to only the projected fields.
+     *
+     * @example
+     * ```ts
+     * const posts = await db.use(Posts)
+     *   .find({})
+     *   .populate('authorId', (b) => b.project({ name: 1, email: 1 }))
+     *   .toArray()
+     * // posts[0].authorId is { _id: ObjectId; name: string; email: string }
+     * ```
+     */
+    populate<K extends RefFields<TDef>, P>(field: K, configure: (b: PopulateRefBuilder<InferDocument<ExtractRefCollection<TDef, K>>>) => PopulateProjectionConfig<P>): PopulateCursor<TDef, ApplyPopulateProjected<TOutput, TDef, K, P>, {
+        [F in K]: ExtractRefCollection<TDef, K>;
+    }>;
+    /**
+     * Populate a top-level ref field and rename it in the output.
+     *
+     * Transitions to a {@link PopulateCursor} that only exposes `.populate()`
+     * and terminal methods. Cursor modifiers (`sort`, `skip`, `limit`) must
+     * be called before `.populate()`.
+     *
+     * @param field - A ref-bearing field name on the root collection.
+     * @param as - The new field name in the output document.
+     * @returns A populate cursor with the old field removed and the new field added.
+     *
+     * @example
+     * ```ts
+     * const posts = await db.use(Posts)
+     *   .find({})
+     *   .sort({ createdAt: -1 })
+     *   .limit(10)
+     *   .populate('authorId', 'author')
+     *   .toArray()
+     * ```
+     */
+    populate<K extends RefFields<TDef>, TAs extends string>(field: K, as: TAs): PopulateCursor<TDef, ApplyPopulate<TOutput, TDef, K, TAs>, {
+        [P in TAs]: ExtractRefCollection<TDef, K>;
+    }>;
     /**
      * Execute the query with offset-based pagination, returning a page of documents
      * with total count and navigation metadata.
@@ -1367,7 +2255,7 @@ declare class TypedFindCursor<TDef extends AnyCollection, TIndexNames extends st
      * console.log(page.total, page.totalPages, page.hasNext)
      * ```
      */
-    paginate(opts: OffsetPaginateOptions): Promise<OffsetPage<InferDocument<TDef>>>;
+    paginate(opts: OffsetPaginateOptions): Promise<OffsetPage<TOutput>>;
     /**
      * Execute the query with cursor-based pagination, returning a page of documents
      * with opaque cursors for forward/backward navigation.
@@ -1388,7 +2276,7 @@ declare class TypedFindCursor<TDef extends AnyCollection, TIndexNames extends st
      *   .paginate({ cursor: first.endCursor, limit: 10 })
      * ```
      */
-    paginate(opts: CursorPaginateOptions): Promise<CursorPage<InferDocument<TDef>>>;
+    paginate(opts: CursorPaginateOptions): Promise<CursorPage<TOutput>>;
     /** @internal Offset pagination implementation. */
     private offsetPaginate;
     /** @internal Cursor pagination implementation. */
@@ -1407,7 +2295,7 @@ declare class TypedFindCursor<TDef extends AnyCollection, TIndexNames extends st
      * const admins = await find(users, { role: 'admin' }).toArray()
      * ```
      */
-    toArray(): Promise<InferDocument<TDef>[]>;
+    toArray(): Promise<TOutput[]>;
     /**
      * Async iterator for streaming documents one at a time.
      *
@@ -1424,17 +2312,33 @@ declare class TypedFindCursor<TDef extends AnyCollection, TIndexNames extends st
      * }
      * ```
      */
-    [Symbol.asyncIterator](): AsyncGenerator<InferDocument<TDef>>;
+    [Symbol.asyncIterator](): AsyncGenerator<TOutput>;
     /** @internal Validate a single raw document against the schema. */
     private validateDoc;
 }
 
 /**
- * Options for {@link findOne} and {@link findOneOrThrow}.
+ * Options for {@link findOne} and {@link findOneOrThrow} without projection.
  */
 type FindOneOptions = {
-    /** MongoDB projection — include (`1`) or exclude (`0`) fields. Typed projections deferred to v1.0. */
-    project?: Record<string, 0 | 1>;
+    /** Override the collection-level validation mode, or `false` to skip validation entirely. */
+    validate?: ValidationMode | false;
+};
+/**
+ * Options for projected {@link findOne} and {@link findOneOrThrow} queries.
+ *
+ * @typeParam T - The document type.
+ * @typeParam P - The projection document type.
+ *
+ * @example
+ * ```ts
+ * const user = await findOne(users, { name: 'Ada' }, { project: { name: 1 } })
+ * //    ^? { _id: ObjectId; name: string } | null
+ * ```
+ */
+type FindOneProjectionOptions<T, P extends TypedProjection<T>> = {
+    /** Type-safe MongoDB projection — include (`1 | true`) or exclude (`0 | false`) fields. */
+    project: P;
     /** Override the collection-level validation mode, or `false` to skip validation entirely. */
     validate?: ValidationMode | false;
 };
@@ -1447,7 +2351,7 @@ type FindOneOptions = {
  *
  * @param handle - The collection handle to query.
  * @param filter - Type-safe filter to match documents.
- * @param options - Optional projection and validation overrides.
+ * @param options - Optional validation overrides.
  * @returns The matched document, or `null` if no document matches.
  * @throws {ZodmonValidationError} When the fetched document fails schema validation in strict mode.
  *
@@ -1458,6 +2362,26 @@ type FindOneOptions = {
  * ```
  */
 declare function findOne<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, options?: FindOneOptions): Promise<InferDocument<TDef> | null>;
+/**
+ * Find a single document matching the filter with a type-safe projection.
+ *
+ * Returns only the fields specified by the projection. The return type is
+ * narrowed to reflect which fields are included or excluded.
+ *
+ * @param handle - The collection handle to query.
+ * @param filter - Type-safe filter to match documents.
+ * @param options - Projection and optional validation overrides.
+ * @returns The projected document, or `null` if no document matches.
+ * @throws {ZodmonValidationError} When the fetched document fails schema validation in strict mode.
+ *
+ * @example
+ * ```ts
+ * const user = await findOne(users, { name: 'Ada' }, { project: { name: 1 } })
+ * if (user) console.log(user.name) // typed as string
+ * // user.role would be a type error — not in the projection
+ * ```
+ */
+declare function findOne<TDef extends AnyCollection, P extends TypedProjection<InferDocument<TDef>>>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, options: FindOneProjectionOptions<InferDocument<TDef>, P>): Promise<Prettify<ProjectionResult<InferDocument<TDef>, P>> | null>;
 /**
  * Find a single document matching the filter, or throw if none exists.
  *
@@ -1466,7 +2390,7 @@ declare function findOne<TDef extends AnyCollection>(handle: CollectionHandle<TD
  *
  * @param handle - The collection handle to query.
  * @param filter - Type-safe filter to match documents.
- * @param options - Optional projection and validation overrides.
+ * @param options - Optional validation overrides.
  * @returns The matched document (never null).
  * @throws {ZodmonNotFoundError} When no document matches the filter.
  * @throws {ZodmonValidationError} When the fetched document fails schema validation in strict mode.
@@ -1478,6 +2402,28 @@ declare function findOne<TDef extends AnyCollection>(handle: CollectionHandle<TD
  * ```
  */
 declare function findOneOrThrow<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, options?: FindOneOptions): Promise<InferDocument<TDef>>;
+/**
+ * Find a single document matching the filter with a type-safe projection, or throw if none exists.
+ *
+ * Returns only the fields specified by the projection. The return type is
+ * narrowed to reflect which fields are included or excluded. Throws
+ * {@link ZodmonNotFoundError} instead of returning `null`.
+ *
+ * @param handle - The collection handle to query.
+ * @param filter - Type-safe filter to match documents.
+ * @param options - Projection and optional validation overrides.
+ * @returns The projected document (never null).
+ * @throws {ZodmonNotFoundError} When no document matches the filter.
+ * @throws {ZodmonValidationError} When the fetched document fails schema validation in strict mode.
+ *
+ * @example
+ * ```ts
+ * const user = await findOneOrThrow(users, { name: 'Ada' }, { project: { name: 1 } })
+ * console.log(user.name) // typed as string
+ * // user.role would be a type error — not in the projection
+ * ```
+ */
+declare function findOneOrThrow<TDef extends AnyCollection, P extends TypedProjection<InferDocument<TDef>>>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, options: FindOneProjectionOptions<InferDocument<TDef>, P>): Promise<Prettify<ProjectionResult<InferDocument<TDef>, P>>>;
 /**
  * Options for {@link find}.
  */
@@ -1485,6 +2431,25 @@ type FindOptions = {
     /** Override the collection-level validation mode, or `false` to skip validation entirely. */
     validate?: ValidationMode | false;
 };
+/**
+ * Options for projected {@link find} queries.
+ *
+ * @typeParam T - The document type.
+ * @typeParam P - The projection document type.
+ *
+ * @example
+ * ```ts
+ * const admins = await find(users, { role: 'admin' }, { project: { name: 1 } })
+ *   .toArray()
+ * //    ^? Array<{ _id: ObjectId; name: string }>
+ * ```
+ */
+type FindProjectionOptions<T, P extends TypedProjection<T>> = {
+    /** Type-safe MongoDB projection — include (`1 | true`) or exclude (`0 | false`) fields. */
+    project: P;
+    /** Override the collection-level validation mode, or `false` to skip validation entirely. */
+    validate?: ValidationMode | false;
+};
 /**
  * Find all documents matching the filter, returning a chainable typed cursor.
  *
@@ -1516,17 +2481,29 @@ type FindOptions = {
  * ```
  */
 declare function find<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, options?: FindOptions): TypedFindCursor<TDef, IndexNames<TDef>>;
-
 /**
- * Extracts the element type from an array type.
+ * Find all documents matching the filter with a type-safe projection, returning a chainable typed cursor.
+ *
+ * The cursor is lazy — no query is executed until a terminal method
+ * (`toArray`, `for await`) is called. The return type is narrowed to
+ * reflect which fields are included or excluded by the projection.
+ *
+ * @param handle - The collection handle to query.
+ * @param filter - Type-safe filter to match documents.
+ * @param options - Projection and optional validation overrides.
+ * @returns A typed cursor whose output type matches the projection.
  *
  * @example
  * ```ts
- * type E = ArrayElement<string[]> // string
- * type N = ArrayElement<number[]> // number
+ * const names = await find(users, { role: 'admin' }, { project: { name: 1 } })
+ *   .sort({ name: 1 })
+ *   .toArray()
+ * // names[0].name  — string
+ * // names[0].role  — type error, not in projection
  * ```
  */
-type ArrayElement<T> = T extends ReadonlyArray<infer E> ? E : never;
+declare function find<TDef extends AnyCollection, P extends TypedProjection<InferDocument<TDef>>>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, options: FindProjectionOptions<InferDocument<TDef>, P>): TypedFindCursor<TDef, IndexNames<TDef>, Prettify<ProjectionResult<InferDocument<TDef>, P>>>;
+
 /**
  * Fields valid for `$set`, `$setOnInsert`, `$min`, and `$max` operators.
  *
@@ -1541,7 +2518,7 @@ type ArrayElement<T> = T extends ReadonlyArray<infer E> ? E : never;
 type SetFields<T> = {
     [K in keyof T]?: T[K];
 } & {
-    [P in DotPaths<T>]?: DotPathType<T, P>;
+    [P in DotSubPaths<T>]?: DotPathValue<T, P>;
 };
 /**
  * Fields valid for the `$inc` operator — only number-typed fields.
@@ -1556,7 +2533,7 @@ type SetFields<T> = {
 type IncFields<T> = {
     [K in keyof T as NonNullable<T[K]> extends number ? K : never]?: number;
 } & {
-    [P in DotPaths<T> as DotPathType<T, P> extends number ? P : never]?: number;
+    [P in DotSubPaths<T> as DotPathValue<T, P> extends number ? P : never]?: number;
 };
 /**
  * Modifiers for the `$push` operator.
@@ -1847,59 +2824,310 @@ type SyncIndexesOptions = {
      * options). When `false` (the default), orphaned and stale indexes are
      * reported but left untouched.
      */
-    dropOrphaned?: boolean;
-};
-/**
- * Describes an index whose key matches a desired index but whose options differ.
- *
- * Returned in {@link SyncIndexesResult.stale} so the caller can decide whether
- * to manually reconcile or re-run with `dropOrphaned: true`.
- *
- * @example
- * ```ts
- * const result = await users.syncIndexes()
- * for (const s of result.stale) {
- *   console.log(`${s.name}: key=${JSON.stringify(s.key)}`)
- *   console.log(`  existing=${JSON.stringify(s.existing)}`)
- *   console.log(`  desired=${JSON.stringify(s.desired)}`)
- * }
- * ```
- */
-type StaleIndex = {
-    /** The MongoDB index name (e.g. `'email_1'`). */
-    name: string;
-    /** The index key spec (e.g. `{ email: 1 }`). */
-    key: Record<string, 1 | -1 | 'text'>;
-    /** The relevant options currently set on the existing index. */
-    existing: Record<string, unknown>;
-    /** The options the schema declares for this index. */
-    desired: Record<string, unknown>;
-};
+    dropOrphaned?: boolean;
+};
+/**
+ * Describes an index whose key matches a desired index but whose options differ.
+ *
+ * Returned in {@link SyncIndexesResult.stale} so the caller can decide whether
+ * to manually reconcile or re-run with `dropOrphaned: true`.
+ *
+ * @example
+ * ```ts
+ * const result = await users.syncIndexes()
+ * for (const s of result.stale) {
+ *   console.log(`${s.name}: key=${JSON.stringify(s.key)}`)
+ *   console.log(`  existing=${JSON.stringify(s.existing)}`)
+ *   console.log(`  desired=${JSON.stringify(s.desired)}`)
+ * }
+ * ```
+ */
+type StaleIndex = {
+    /** The MongoDB index name (e.g. `'email_1'`). */
+    name: string;
+    /** The index key spec (e.g. `{ email: 1 }`). */
+    key: Record<string, 1 | -1 | 'text'>;
+    /** The relevant options currently set on the existing index. */
+    existing: Record<string, unknown>;
+    /** The options the schema declares for this index. */
+    desired: Record<string, unknown>;
+};
+/**
+ * The result of a {@link syncIndexes} call.
+ *
+ * Every array contains index names. `stale` contains full details so the
+ * caller can inspect the mismatch.
+ *
+ * @example
+ * ```ts
+ * const result = await users.syncIndexes()
+ * console.log('created:', result.created)
+ * console.log('dropped:', result.dropped)
+ * console.log('skipped:', result.skipped)
+ * console.log('stale:', result.stale.map(s => s.name))
+ * ```
+ */
+type SyncIndexesResult = {
+    /** Names of indexes that were created (or would be created in dryRun mode). */
+    created: string[];
+    /** Names of indexes that were dropped (or would be dropped in dryRun mode). */
+    dropped: string[];
+    /** Names of indexes that already existed with matching options — no action taken. */
+    skipped: string[];
+    /** Indexes whose key matches a desired spec but whose options differ. */
+    stale: StaleIndex[];
+};
+
+/**
+ * Extract the parent segment from a dot-separated path.
+ *
+ * @example
+ * ```ts
+ * type P = ExtractParent<'author.companyId'> // 'author'
+ * ```
+ */
+type ExtractParent<T extends string> = T extends `${infer P}.${string}` ? P : never;
+/**
+ * Extract the leaf segment from a dot-separated path.
+ *
+ * @example
+ * ```ts
+ * type L = ExtractLeaf<'author.companyId'> // 'companyId'
+ * ```
+ */
+type ExtractLeaf<T extends string> = T extends `${string}.${infer L}` ? L : never;
+/**
+ * Fluent populate builder for findOne queries.
+ *
+ * Implements `PromiseLike` so it can be awaited directly without `.populate()`.
+ * Each `.populate()` call returns a new builder with updated generics.
+ *
+ * @example
+ * ```ts
+ * // Without populate (backward compatible)
+ * const post = await posts.findOne({ title: 'Hello' })
+ *
+ * // With populate
+ * const post = await posts.findOne({ title: 'Hello' })
+ *   .populate('authorId', 'author')
+ *   .populate('author.companyId', 'company')
+ * ```
+ */
+declare class PopulateOneQuery<TDef extends AnyCollection, TOutput, TPopMap extends Record<string, AnyCollection> = Record<string, never>> implements PromiseLike<TOutput | null> {
+    private readonly handle;
+    private readonly filter;
+    private readonly options;
+    private readonly steps;
+    constructor(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, options: FindOneOptions | undefined, steps?: readonly PopulateStep[]);
+    /**
+     * Populate a top-level ref field, keeping the original field name.
+     *
+     * @param field - A ref-bearing field name on the root collection.
+     * @returns A new builder with the field type replaced by the referenced document.
+     *
+     * @example
+     * ```ts
+     * const post = await posts.findOne({ title: 'Hello' })
+     *   .populate('authorId')
+     * // post.authorId is now a User document instead of ObjectId
+     * ```
+     */
+    populate<K extends RefFields<TDef>>(field: K): PopulateOneQuery<TDef, ApplyPopulate<TOutput, TDef, K>, TPopMap & {
+        [P in K]: ExtractRefCollection<TDef, K>;
+    }>;
+    /**
+     * Populate a top-level ref field with a projection, keeping the original field name.
+     *
+     * @param field - A ref-bearing field name on the root collection.
+     * @param configure - Callback receiving a builder; call `.project()` to set the projection.
+     * @returns A new builder with the field type narrowed to only the projected fields.
+     *
+     * @example
+     * ```ts
+     * const post = await posts.findOne({ title: 'Hello' })
+     *   .populate('authorId', (b) => b.project({ name: 1, email: 1 }))
+     * // post.authorId is { _id: ObjectId; name: string; email: string }
+     * // post.authorId.age  →  TS error
+     * ```
+     */
+    populate<K extends RefFields<TDef>, P>(field: K, configure: (b: PopulateRefBuilder<InferDocument<ExtractRefCollection<TDef, K>>>) => PopulateProjectionConfig<P>): PopulateOneQuery<TDef, ApplyPopulateProjected<TOutput, TDef, K, P>, TPopMap & {
+        [F in K]: ExtractRefCollection<TDef, K>;
+    }>;
+    /**
+     * Populate a top-level ref field and rename it in the output.
+     *
+     * @param field - A ref-bearing field name on the root collection.
+     * @param as - The new field name in the output document.
+     * @returns A new builder with the old field removed and the new field added.
+     *
+     * @example
+     * ```ts
+     * const post = await posts.findOne({ title: 'Hello' })
+     *   .populate('authorId', 'author')
+     * // post.author is a User document; post.authorId no longer exists
+     * ```
+     */
+    populate<K extends RefFields<TDef>, TAs extends string>(field: K, as: TAs): PopulateOneQuery<TDef, ApplyPopulate<TOutput, TDef, K, TAs>, TPopMap & {
+        [P in TAs]: ExtractRefCollection<TDef, K>;
+    }>;
+    /**
+     * Populate a nested ref field, keeping the leaf field name.
+     *
+     * The parent path must have been populated in a previous `.populate()` call.
+     *
+     * @param path - A dot-separated path like `'author.companyId'`.
+     * @returns A new builder with the nested field type replaced.
+     *
+     * @example
+     * ```ts
+     * const post = await posts.findOne({ title: 'Hello' })
+     *   .populate('authorId', 'author')
+     *   .populate('author.companyId')
+     * // post.author.companyId is now a Company document
+     * ```
+     */
+    populate<TPath extends NestedRefPath<TPopMap>>(path: TPath): PopulateOneQuery<TDef, DeepPopulate<TOutput, `${ExtractParent<TPath>}.${ExtractLeaf<TPath>}`, ExtractLeaf<TPath>, ExtractLeaf<TPath>, PopulateField<TPopMap[ExtractParent<TPath>], ExtractLeaf<TPath> & RefFields<TPopMap[ExtractParent<TPath>]>>>, TPopMap & {
+        [P in `${ExtractParent<TPath>}.${ExtractLeaf<TPath>}`]: ExtractRefCollection<TPopMap[ExtractParent<TPath>], ExtractLeaf<TPath> & RefFields<TPopMap[ExtractParent<TPath>]>>;
+    }>;
+    /**
+     * Populate a nested ref field and rename the leaf in the output.
+     *
+     * The parent path must have been populated in a previous `.populate()` call.
+     *
+     * @param path - A dot-separated path like `'author.companyId'`.
+     * @param as - The new name for the leaf field in the output.
+     * @returns A new builder with the nested field renamed and typed.
+     *
+     * @example
+     * ```ts
+     * const post = await posts.findOne({ title: 'Hello' })
+     *   .populate('authorId', 'author')
+     *   .populate('author.companyId', 'company')
+     * // post.author.company is a Company document
+     * ```
+     */
+    populate<TPath extends NestedRefPath<TPopMap>, TAs extends string>(path: TPath, as: TAs): PopulateOneQuery<TDef, DeepPopulate<TOutput, `${ExtractParent<TPath>}.${TAs}`, ExtractLeaf<TPath>, TAs, PopulateField<TPopMap[ExtractParent<TPath>], ExtractLeaf<TPath> & RefFields<TPopMap[ExtractParent<TPath>]>>>, TPopMap & {
+        [P in `${ExtractParent<TPath>}.${TAs}`]: ExtractRefCollection<TPopMap[ExtractParent<TPath>], ExtractLeaf<TPath> & RefFields<TPopMap[ExtractParent<TPath>]>>;
+    }>;
+    /**
+     * Attach fulfillment and rejection handlers to the query promise.
+     *
+     * Executes the base findOne query and applies populate steps if any.
+     * Returns `null` when no document matches the filter.
+     */
+    then<TResult1 = TOutput | null, TResult2 = never>(onfulfilled?: ((value: TOutput | null) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    private execute;
+}
 /**
- * The result of a {@link syncIndexes} call.
+ * Fluent populate builder for findOneOrThrow queries.
  *
- * Every array contains index names. `stale` contains full details so the
- * caller can inspect the mismatch.
+ * Identical to {@link PopulateOneQuery} but resolves to `TOutput` (never null).
+ * Throws {@link ZodmonNotFoundError} when no document matches the filter.
  *
  * @example
  * ```ts
- * const result = await users.syncIndexes()
- * console.log('created:', result.created)
- * console.log('dropped:', result.dropped)
- * console.log('skipped:', result.skipped)
- * console.log('stale:', result.stale.map(s => s.name))
+ * const post = await posts.findOneOrThrow({ title: 'Hello' })
+ *   .populate('authorId', 'author')
+ * // Guaranteed non-null; throws if not found
  * ```
  */
-type SyncIndexesResult = {
-    /** Names of indexes that were created (or would be created in dryRun mode). */
-    created: string[];
-    /** Names of indexes that were dropped (or would be dropped in dryRun mode). */
-    dropped: string[];
-    /** Names of indexes that already existed with matching options — no action taken. */
-    skipped: string[];
-    /** Indexes whose key matches a desired spec but whose options differ. */
-    stale: StaleIndex[];
-};
+declare class PopulateOneOrThrowQuery<TDef extends AnyCollection, TOutput, TPopMap extends Record<string, AnyCollection> = Record<string, never>> implements PromiseLike<TOutput> {
+    private readonly handle;
+    private readonly filter;
+    private readonly options;
+    private readonly steps;
+    constructor(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, options: FindOneOptions | undefined, steps?: readonly PopulateStep[]);
+    /**
+     * Populate a top-level ref field, keeping the original field name.
+     *
+     * @param field - A ref-bearing field name on the root collection.
+     * @returns A new builder with the field type replaced by the referenced document.
+     *
+     * @example
+     * ```ts
+     * const post = await posts.findOneOrThrow({ title: 'Hello' })
+     *   .populate('authorId')
+     * ```
+     */
+    populate<K extends RefFields<TDef>>(field: K): PopulateOneOrThrowQuery<TDef, ApplyPopulate<TOutput, TDef, K>, TPopMap & {
+        [P in K]: ExtractRefCollection<TDef, K>;
+    }>;
+    /**
+     * Populate a top-level ref field with a projection, keeping the original field name.
+     *
+     * @param field - A ref-bearing field name on the root collection.
+     * @param configure - Callback receiving a builder; call `.project()` to set the projection.
+     * @returns A new builder with the field type narrowed to only the projected fields.
+     *
+     * @example
+     * ```ts
+     * const post = await posts.findOneOrThrow({ title: 'Hello' })
+     *   .populate('authorId', (b) => b.project({ name: 1, email: 1 }))
+     * // post.authorId is { _id: ObjectId; name: string; email: string }
+     * // post.authorId.age  →  TS error
+     * ```
+     */
+    populate<K extends RefFields<TDef>, P>(field: K, configure: (b: PopulateRefBuilder<InferDocument<ExtractRefCollection<TDef, K>>>) => PopulateProjectionConfig<P>): PopulateOneOrThrowQuery<TDef, ApplyPopulateProjected<TOutput, TDef, K, P>, TPopMap & {
+        [F in K]: ExtractRefCollection<TDef, K>;
+    }>;
+    /**
+     * Populate a top-level ref field and rename it in the output.
+     *
+     * @param field - A ref-bearing field name on the root collection.
+     * @param as - The new field name in the output document.
+     * @returns A new builder with the old field removed and the new field added.
+     *
+     * @example
+     * ```ts
+     * const post = await posts.findOneOrThrow({ title: 'Hello' })
+     *   .populate('authorId', 'author')
+     * ```
+     */
+    populate<K extends RefFields<TDef>, TAs extends string>(field: K, as: TAs): PopulateOneOrThrowQuery<TDef, ApplyPopulate<TOutput, TDef, K, TAs>, TPopMap & {
+        [P in TAs]: ExtractRefCollection<TDef, K>;
+    }>;
+    /**
+     * Populate a nested ref field, keeping the leaf field name.
+     *
+     * @param path - A dot-separated path like `'author.companyId'`.
+     * @returns A new builder with the nested field type replaced.
+     *
+     * @example
+     * ```ts
+     * const post = await posts.findOneOrThrow({ title: 'Hello' })
+     *   .populate('authorId', 'author')
+     *   .populate('author.companyId')
+     * ```
+     */
+    populate<TPath extends NestedRefPath<TPopMap>>(path: TPath): PopulateOneOrThrowQuery<TDef, DeepPopulate<TOutput, `${ExtractParent<TPath>}.${ExtractLeaf<TPath>}`, ExtractLeaf<TPath>, ExtractLeaf<TPath>, PopulateField<TPopMap[ExtractParent<TPath>], ExtractLeaf<TPath> & RefFields<TPopMap[ExtractParent<TPath>]>>>, TPopMap & {
+        [P in `${ExtractParent<TPath>}.${ExtractLeaf<TPath>}`]: ExtractRefCollection<TPopMap[ExtractParent<TPath>], ExtractLeaf<TPath> & RefFields<TPopMap[ExtractParent<TPath>]>>;
+    }>;
+    /**
+     * Populate a nested ref field and rename the leaf in the output.
+     *
+     * @param path - A dot-separated path like `'author.companyId'`.
+     * @param as - The new name for the leaf field in the output.
+     * @returns A new builder with the nested field renamed and typed.
+     *
+     * @example
+     * ```ts
+     * const post = await posts.findOneOrThrow({ title: 'Hello' })
+     *   .populate('authorId', 'author')
+     *   .populate('author.companyId', 'company')
+     * ```
+     */
+    populate<TPath extends NestedRefPath<TPopMap>, TAs extends string>(path: TPath, as: TAs): PopulateOneOrThrowQuery<TDef, DeepPopulate<TOutput, `${ExtractParent<TPath>}.${TAs}`, ExtractLeaf<TPath>, TAs, PopulateField<TPopMap[ExtractParent<TPath>], ExtractLeaf<TPath> & RefFields<TPopMap[ExtractParent<TPath>]>>>, TPopMap & {
+        [P in `${ExtractParent<TPath>}.${TAs}`]: ExtractRefCollection<TPopMap[ExtractParent<TPath>], ExtractLeaf<TPath> & RefFields<TPopMap[ExtractParent<TPath>]>>;
+    }>;
+    /**
+     * Attach fulfillment and rejection handlers to the query promise.
+     *
+     * Executes the base findOneOrThrow query and applies populate steps if any.
+     * Throws {@link ZodmonNotFoundError} when no document matches.
+     */
+    then<TResult1 = TOutput, TResult2 = never>(onfulfilled?: ((value: TOutput) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    private execute;
+}
 
 /**
  * Typed wrapper around a MongoDB driver `Collection`.
@@ -1916,7 +3144,35 @@ declare class CollectionHandle<TDef extends AnyCollection = AnyCollection> {
     readonly definition: TDef;
     /** The underlying MongoDB driver collection, typed to the inferred document type. */
     readonly native: Collection<InferDocument<TDef>>;
-    constructor(definition: TDef, native: Collection<InferDocument<TDef>>);
+    /**
+     * The MongoDB client session bound to this handle, if any.
+     *
+     * When set, all CRUD and aggregation operations performed through this
+     * handle will include the session in their options, enabling transactional
+     * reads and writes. Undefined when no session is bound.
+     */
+    readonly session: ClientSession | undefined;
+    constructor(definition: TDef, native: Collection<InferDocument<TDef>>, session?: ClientSession);
+    /**
+     * Create a new handle bound to the given MongoDB client session.
+     *
+     * Returns a new {@link CollectionHandle} that shares the same collection
+     * definition and native driver collection, but passes `session` to every
+     * CRUD and aggregation operation. The original handle is not modified.
+     *
+     * @param session - The MongoDB `ClientSession` to bind.
+     * @returns A new handle with the session attached.
+     *
+     * @example
+     * ```ts
+     * const users = db.use(Users)
+     * await db.client.withSession(async (session) => {
+     *   const bound = users.withSession(session)
+     *   await bound.insertOne({ name: 'Ada' }) // uses session
+     * })
+     * ```
+     */
+    withSession(session: ClientSession): CollectionHandle<TDef>;
     /**
      * Insert a single document into the collection.
      *
@@ -1960,13 +3216,12 @@ declare class CollectionHandle<TDef extends AnyCollection = AnyCollection> {
     /**
      * Find a single document matching the filter.
      *
-     * Queries MongoDB, then validates the fetched document against the collection's
-     * Zod schema. Validation mode is resolved from the per-query option, falling
-     * back to the collection-level default (which defaults to `'strict'`).
+     * Returns a {@link PopulateOneQuery} that can be awaited directly or chained
+     * with `.populate()` calls to resolve foreign key references.
      *
      * @param filter - Type-safe filter to match documents.
-     * @param options - Optional projection and validation overrides.
-     * @returns The matched document, or `null` if no document matches.
+     * @param options - Optional validation overrides.
+     * @returns A populate builder that resolves to the matched document, or `null`.
      * @throws {ZodmonValidationError} When the fetched document fails schema validation in strict mode.
      *
      * @example
@@ -1975,17 +3230,44 @@ declare class CollectionHandle<TDef extends AnyCollection = AnyCollection> {
      * const user = await users.findOne({ name: 'Ada' })
      * if (user) console.log(user.role)
      * ```
+     *
+     * @example
+     * ```ts
+     * const post = await posts.findOne({ title: 'Hello' })
+     *   .populate('authorId', 'author')
+     * ```
+     */
+    findOne(filter: TypedFilter<InferDocument<TDef>>, options?: FindOneOptions): PopulateOneQuery<TDef, InferDocument<TDef>>;
+    /**
+     * Find a single document matching the filter with a type-safe projection.
+     *
+     * Returns only the fields specified by the projection. The return type is
+     * narrowed to reflect which fields are included or excluded.
+     * Projected queries do not support `.populate()`.
+     *
+     * @param filter - Type-safe filter to match documents.
+     * @param options - Projection and optional validation overrides.
+     * @returns The projected document, or `null` if no document matches.
+     * @throws {ZodmonValidationError} When the fetched document fails schema validation in strict mode.
+     *
+     * @example
+     * ```ts
+     * const users = db.use(Users)
+     * const user = await users.findOne({ name: 'Ada' }, { project: { name: 1 } })
+     * if (user) console.log(user.name) // typed as string
+     * ```
      */
-    findOne(filter: TypedFilter<InferDocument<TDef>>, options?: FindOneOptions): Promise<InferDocument<TDef> | null>;
+    findOne<P extends TypedProjection<InferDocument<TDef>>>(filter: TypedFilter<InferDocument<TDef>>, options: FindOneProjectionOptions<InferDocument<TDef>, P>): Promise<Prettify<ProjectionResult<InferDocument<TDef>, P>> | null>;
     /**
      * Find a single document matching the filter, or throw if none exists.
      *
-     * Behaves identically to {@link findOne} but throws {@link ZodmonNotFoundError}
-     * instead of returning `null` when no document matches the filter.
+     * Returns a {@link PopulateOneOrThrowQuery} that can be awaited directly or
+     * chained with `.populate()` calls. Throws {@link ZodmonNotFoundError}
+     * instead of returning `null` when no document matches.
      *
      * @param filter - Type-safe filter to match documents.
-     * @param options - Optional projection and validation overrides.
-     * @returns The matched document (never null).
+     * @param options - Optional validation overrides.
+     * @returns A populate builder that resolves to the matched document (never null).
      * @throws {ZodmonNotFoundError} When no document matches the filter.
      * @throws {ZodmonValidationError} When the fetched document fails schema validation in strict mode.
      *
@@ -1995,8 +3277,36 @@ declare class CollectionHandle<TDef extends AnyCollection = AnyCollection> {
      * const user = await users.findOneOrThrow({ name: 'Ada' })
      * console.log(user.role) // guaranteed non-null
      * ```
+     *
+     * @example
+     * ```ts
+     * const post = await posts.findOneOrThrow({ title: 'Hello' })
+     *   .populate('authorId', 'author')
+     * ```
+     */
+    findOneOrThrow(filter: TypedFilter<InferDocument<TDef>>, options?: FindOneOptions): PopulateOneOrThrowQuery<TDef, InferDocument<TDef>>;
+    /**
+     * Find a single document matching the filter with a type-safe projection, or throw if none exists.
+     *
+     * Returns only the fields specified by the projection. The return type is
+     * narrowed to reflect which fields are included or excluded. Throws
+     * {@link ZodmonNotFoundError} instead of returning `null`.
+     * Projected queries do not support `.populate()`.
+     *
+     * @param filter - Type-safe filter to match documents.
+     * @param options - Projection and optional validation overrides.
+     * @returns The projected document (never null).
+     * @throws {ZodmonNotFoundError} When no document matches the filter.
+     * @throws {ZodmonValidationError} When the fetched document fails schema validation in strict mode.
+     *
+     * @example
+     * ```ts
+     * const users = db.use(Users)
+     * const user = await users.findOneOrThrow({ name: 'Ada' }, { project: { name: 1 } })
+     * console.log(user.name) // typed as string
+     * ```
      */
-    findOneOrThrow(filter: TypedFilter<InferDocument<TDef>>, options?: FindOneOptions): Promise<InferDocument<TDef>>;
+    findOneOrThrow<P extends TypedProjection<InferDocument<TDef>>>(filter: TypedFilter<InferDocument<TDef>>, options: FindOneProjectionOptions<InferDocument<TDef>, P>): Promise<Prettify<ProjectionResult<InferDocument<TDef>, P>>>;
     /**
      * Find all documents matching the filter, returning a chainable typed cursor.
      *
@@ -2018,6 +3328,24 @@ declare class CollectionHandle<TDef extends AnyCollection = AnyCollection> {
      * ```
      */
     find(filter: TypedFilter<InferDocument<TDef>>, options?: FindOptions): TypedFindCursor<TDef, IndexNames<TDef>>;
+    /**
+     * Find all documents matching the filter with a type-safe projection, returning a chainable typed cursor.
+     *
+     * The return type is narrowed to reflect which fields are included or excluded.
+     *
+     * @param filter - Type-safe filter to match documents.
+     * @param options - Projection and optional validation overrides.
+     * @returns A typed cursor whose output type matches the projection.
+     *
+     * @example
+     * ```ts
+     * const users = db.use(Users)
+     * const names = await users.find({ role: 'admin' }, { project: { name: 1 } })
+     *   .toArray()
+     * // names[0].name  — string
+     * ```
+     */
+    find<P extends TypedProjection<InferDocument<TDef>>>(filter: TypedFilter<InferDocument<TDef>>, options: FindProjectionOptions<InferDocument<TDef>, P>): TypedFindCursor<TDef, IndexNames<TDef>, Prettify<ProjectionResult<InferDocument<TDef>, P>>>;
     /**
      * Update a single document matching the filter.
      *
@@ -2213,7 +3541,8 @@ declare class AggregatePipeline<TDef extends AnyCollection, TOutput> {
     protected readonly definition: TDef;
     private readonly nativeCollection;
     private readonly stages;
-    constructor(definition: TDef, nativeCollection: Collection<InferDocument<TDef>>, stages: Document[]);
+    private readonly session;
+    constructor(definition: TDef, nativeCollection: Collection<InferDocument<TDef>>, stages: Document[], session?: ClientSession);
     /**
      * Append an arbitrary aggregation stage to the pipeline (escape hatch).
      *
@@ -2329,10 +3658,21 @@ declare class AggregatePipeline<TDef extends AnyCollection, TOutput> {
      *   .toArray()
      * // subset[0].role → 'engineer' | 'designer'
      * ```
+     *
+     * @example
+     * ```ts
+     * // Field-vs-field comparison via $expr callback
+     * const overRefunded = await orders.aggregate()
+     *   .match(
+     *     { status: 'completed' },
+     *     (expr) => expr.gt('totalAmount', expr.field('refundedAmount')),
+     *   )
+     *   .toArray()
+     * ```
      */
     match<TNarrow extends {
         [K in keyof TNarrow]: K extends keyof TOutput ? TOutput[K] : never;
-    } = {}, F extends TypedFilter<TOutput> = TypedFilter<TOutput>>(filter: F): AggregatePipeline<TDef, Prettify<Omit<NarrowFromFilter<TOutput, F>, keyof TNarrow> & TNarrow>>;
+    } = {}, F extends TypedFilter<TOutput> = TypedFilter<TOutput>>(filter: F, exprCb?: (expr: ExpressionBuilder<TOutput>) => Expression<boolean>): AggregatePipeline<TDef, Prettify<Omit<NarrowFromFilter<TOutput, F>, keyof TNarrow> & TNarrow>>;
     /**
      * Sort documents by one or more fields.
      *
@@ -2449,7 +3789,7 @@ declare class AggregatePipeline<TDef extends AnyCollection, TOutput> {
      * and compile-time field validation. Builder methods resolve return types
      * to the actual field type (`T[K]`), not `unknown`.
      *
-     * @param field - A field name or array of field names to group by.
+     * @param field - A field name, array of field names, or `null` to aggregate all documents into a single group.
      * @param accumulators - A callback `(acc) => ({ ... })` or plain accumulator object.
      * @returns A new pipeline with the `$group` stage appended.
      *
@@ -2480,9 +3820,22 @@ declare class AggregatePipeline<TDef extends AnyCollection, TOutput> {
      *   .groupBy(['role', 'dept'], acc => ({ count: acc.count() }))
      *   .toArray()
      * ```
+     *
+     * @example
+     * ```ts
+     * // Null groupBy — aggregate all documents into a single summary
+     * const totals = await aggregate(orders)
+     *   .groupBy(null, acc => ({
+     *     grandTotal: acc.sum('amount'),
+     *     orderCount: acc.count(),
+     *   }))
+     *   .toArray()
+     * // → [{ _id: null, grandTotal: 2740, orderCount: 7 }]
+     * ```
      */
-    groupBy<K extends keyof TOutput & string, TAccum extends Record<string, Accumulator>>(field: K, accumulators: ((acc: AccumulatorBuilder<TOutput>) => TAccum) | TAccum): AggregatePipeline<TDef, GroupByResult<TOutput, K, TAccum>>;
-    groupBy<K extends keyof TOutput & string, TAccum extends Record<string, Accumulator>>(field: K[], accumulators: ((acc: AccumulatorBuilder<TOutput>) => TAccum) | TAccum): AggregatePipeline<TDef, GroupByCompoundResult<TOutput, K, TAccum>>;
+    groupBy<TAccum extends Record<string, Accumulator>>(field: null, accumulators: ((acc: AccumulatorBuilder<TOutput>) => TAccum) | TAccum): AggregatePipeline<TDef, GroupByNullResult<TAccum>>;
+    groupBy<K extends DotPath<TOutput>, TAccum extends Record<string, Accumulator>>(field: K, accumulators: ((acc: AccumulatorBuilder<TOutput>) => TAccum) | TAccum): AggregatePipeline<TDef, GroupByResult<TOutput, K, TAccum>>;
+    groupBy<K extends DotPath<TOutput>, TAccum extends Record<string, Accumulator>>(field: K[], accumulators: ((acc: AccumulatorBuilder<TOutput>) => TAccum) | TAccum): AggregatePipeline<TDef, GroupByCompoundResult<TOutput, K, TAccum>>;
     /**
      * Add new fields or overwrite existing ones in the output documents.
      *
@@ -2617,6 +3970,37 @@ declare class AggregatePipeline<TDef extends AnyCollection, TOutput> {
     }): AggregatePipeline<TDef, Prettify<TOutput & {
         [P in TAs]: InferDocument<TForeignDef>[];
     }>>;
+    /**
+     * Run multiple sub-pipelines on the same input documents in parallel.
+     *
+     * Each key in `spec` maps to a callback that receives a fresh `SubPipeline`
+     * starting from `TOutput`. The callback chains stages and returns the terminal
+     * pipeline. Zodmon extracts the accumulated stages at runtime to build the
+     * `$facet` document. The output type is fully inferred — no annotation needed.
+     *
+     * Sub-pipelines support all stage methods including `.raw()` for operators not
+     * yet first-class. Execution methods (`toArray`, `explain`) are not available
+     * inside branches.
+     *
+     * @param spec - An object mapping branch names to sub-pipeline builder callbacks.
+     * @returns A new pipeline whose output is one document with each branch name mapped to an array of results.
+     *
+     * @example
+     * ```ts
+     * const [report] = await aggregate(orders)
+     *   .facet({
+     *     byCategory: (sub) => sub
+     *       .groupBy('category', acc => ({ count: acc.count() }))
+     *       .sort({ count: -1 }),
+     *     totals: (sub) => sub
+     *       .groupBy(null, acc => ({ grandTotal: acc.sum('amount') })),
+     *   })
+     *   .toArray()
+     * // report.byCategory → { _id: 'electronics' | 'books' | 'clothing'; count: number }[]
+     * // report.totals     → { _id: null; grandTotal: number }[]
+     * ```
+     */
+    facet<TSpec extends Record<string, (sub: SubPipeline<TDef, TOutput>) => AggregatePipeline<TDef, any>>>(spec: TSpec): AggregatePipeline<TDef, Prettify<InferFacetOutput<TSpec>>>;
     /**
      * Count documents per group, sorted by count descending.
      *
@@ -2713,6 +4097,8 @@ declare class AggregatePipeline<TDef extends AnyCollection, TOutput> {
     bottom(n: number, options: {
         by: keyof TOutput & string;
     }): AggregatePipeline<TDef, TOutput>;
+    /** @internal Used by facet() to extract branch stages. Not part of the public API. */
+    getStages(): Document[];
 }
 /**
  * Create a new aggregation pipeline for a collection.
@@ -2732,6 +4118,99 @@ declare class AggregatePipeline<TDef extends AnyCollection, TOutput> {
  * ```
  */
 declare function aggregate<TDef extends AnyCollection>(handle: CollectionHandle<TDef>): AggregatePipeline<TDef, InferDocument<TDef>>;
+/**
+ * A sub-pipeline passed to each `.facet()` branch callback.
+ *
+ * All stage-building methods are available. Execution methods (`toArray`,
+ * `explain`, `[Symbol.asyncIterator]`) are omitted — sub-pipelines are
+ * not executed directly; they only accumulate stages for the parent `$facet` stage.
+ *
+ * @typeParam TDef - The collection definition type.
+ * @typeParam TOutput - The current output document type.
+ *
+ * @example
+ * ```ts
+ * .facet({
+ *   summary: (sub: SubPipeline<typeof Orders, Order>) => sub.groupBy(null, acc => ({ total: acc.sum('amount') }))
+ * })
+ * ```
+ */
+type SubPipeline<TDef extends AnyCollection, TOutput> = Omit<AggregatePipeline<TDef, TOutput>, 'toArray' | 'explain' | typeof Symbol.asyncIterator>;
+/**
+ * Maps a `.facet()` spec object to its inferred output shape.
+ *
+ * Each key maps to the array of results produced by that branch's terminal pipeline.
+ * Uses `any` for the sub-pipeline parameter to avoid TypeScript contravariance
+ * complications — inference of `TOut` from the return type is what matters.
+ *
+ * @example
+ * ```ts
+ * type Spec = {
+ *   byCategory: (sub: SubPipeline<any, any>) => AggregatePipeline<any, { _id: string; count: number }>
+ * }
+ * type Result = InferFacetOutput<Spec>
+ * //   ^? { byCategory: { _id: string; count: number }[] }
+ * ```
+ */
+type InferFacetOutput<TSpec> = {
+    [K in keyof TSpec]: TSpec[K] extends (sub: any) => AggregatePipeline<any, infer TOut> ? TOut[] : never;
+};
+
+/**
+ * The callback signature for {@link Database.transaction}.
+ *
+ * @typeParam T - The return type of the transaction callback.
+ *
+ * @example
+ * ```ts
+ * const fn: TransactionFn<void> = async (tx) => {
+ *   const txUsers = tx.use(users)
+ *   await txUsers.insertOne({ name: 'Ada' })
+ * }
+ * ```
+ */
+type TransactionFn<T> = (tx: TransactionContext) => Promise<T>;
+/**
+ * Transaction context passed to the {@link Database.transaction} callback.
+ *
+ * Use {@link use} to bind existing collection handles to this transaction's
+ * session. All operations on the returned handle participate in the
+ * transaction -- auto-committed on success, auto-rolled-back on error.
+ *
+ * @example
+ * ```ts
+ * await db.transaction(async (tx) => {
+ *   const txUsers = tx.use(users)
+ *   const txPosts = tx.use(posts)
+ *   const user = await txUsers.insertOne({ name: 'Ada' })
+ *   await txPosts.insertOne({ authorId: user._id, title: 'Hello' })
+ * })
+ * ```
+ */
+declare class TransactionContext {
+    /** @internal */
+    private readonly session;
+    /** @internal */
+    constructor(session: ClientSession);
+    /**
+     * Bind a collection handle to this transaction's session.
+     *
+     * Returns a cloned handle whose CRUD operations automatically include
+     * the transaction session. The original handle is not modified.
+     *
+     * @param handle - An existing collection handle from `db.use()`.
+     * @returns A new handle bound to the transaction session.
+     *
+     * @example
+     * ```ts
+     * await db.transaction(async (tx) => {
+     *   const txUsers = tx.use(users)
+     *   await txUsers.insertOne({ name: 'Ada' })
+     * })
+     * ```
+     */
+    use<TDef extends AnyCollection>(handle: CollectionHandle<TDef>): CollectionHandle<TDef>;
+}
 
 /**
  * Wraps a MongoDB `MongoClient` and `Db`, providing typed collection access
@@ -2788,11 +4267,40 @@ declare class Database {
      */
     syncIndexes(options?: SyncIndexesOptions): Promise<Record<string, SyncIndexesResult>>;
     /**
-     * Execute a function within a MongoDB transaction with auto-commit/rollback.
+     * Execute a function within a MongoDB transaction.
+     *
+     * Starts a client session and runs the callback inside
+     * `session.withTransaction()`. The driver handles commit on success,
+     * abort on error, and automatic retries for transient transaction errors.
+     *
+     * The return value of `fn` is forwarded as the return value of this method.
+     *
+     * @param fn - Async callback receiving a {@link TransactionContext}.
+     * @returns The value returned by `fn`.
+     *
+     * @example
+     * ```ts
+     * const user = await db.transaction(async (tx) => {
+     *   const txUsers = tx.use(users)
+     *   return await txUsers.insertOne({ name: 'Ada' })
+     * })
+     * ```
      *
-     * Stub — full implementation in TASK-106.
+     * @example
+     * ```ts
+     * // Rollback on error
+     * try {
+     *   await db.transaction(async (tx) => {
+     *     const txUsers = tx.use(users)
+     *     await txUsers.insertOne({ name: 'Ada' })
+     *     throw new Error('abort!')
+     *   })
+     * } catch (err) {
+     *   // insert was rolled back, err is the original error
+     * }
+     * ```
      */
-    transaction<T>(_fn: () => Promise<T>): Promise<T>;
+    transaction<T>(fn: TransactionFn<T>): Promise<T>;
     /**
      * Close the underlying `MongoClient` connection. Safe to call even if
      * no connection was established (the driver handles this gracefully).
@@ -3610,6 +5118,68 @@ type WarnableDefinition = {
  */
 declare function checkUnindexedFields(definition: WarnableDefinition, filter: Record<string, unknown>): void;
 
+/**
+ * Walk through Zod wrappers to find the inner schema with ref metadata.
+ *
+ * Mirrors the type-level `UnwrapRef<T>` at runtime. Peels ZodOptional,
+ * ZodNullable, ZodDefault (via `_zod.def.innerType`), and ZodArray
+ * (via `_zod.def.element`).
+ *
+ * @param schema - The Zod schema to unwrap.
+ * @returns The innermost schema after stripping wrappers.
+ *
+ * @example
+ * ```ts
+ * const inner = unwrapRefSchema(Posts.shape.categoryIds)
+ * const ref = getRefMetadata(inner) // { collection: Categories }
+ * ```
+ */
+declare function unwrapRefSchema(schema: z.ZodType): z.ZodType;
+/**
+ * Resolve a `.populate()` call into a `PopulateStep`.
+ *
+ * For top-level fields, inspects the collection's shape directly.
+ * For nested dot-paths, walks previous steps to find the parent
+ * collection definition, then resolves the leaf field in that shape.
+ *
+ * @param definition - The root collection definition.
+ * @param previousSteps - Steps from earlier `.populate()` calls.
+ * @param path - The field path (e.g. `'authorId'` or `'author.companyId'`).
+ * @param as - The output field name (renamed or original).
+ * @param projection - Optional projection to pass to the `$in` query.
+ * @returns A resolved `PopulateStep`.
+ * @throws When the field has no `.ref()` metadata or the parent path is not populated.
+ *
+ * @example
+ * ```ts
+ * const step = resolvePopulateStep(Posts, [], 'authorId', 'author')
+ * // { leafField: 'authorId', as: 'author', targetCollection: Users, ... }
+ * ```
+ */
+declare function resolvePopulateStep(definition: AnyCollection, previousSteps: readonly PopulateStep[], path: string, as: string, projection?: Record<string, 0 | 1 | boolean>): PopulateStep;
+/**
+ * Execute populate steps against a set of documents.
+ *
+ * Processes steps in order. For each step:
+ * 1. Navigate to the parent level for nested paths
+ * 2. Collect unique IDs from the leaf field
+ * 3. Batch query the target collection with `$in`
+ * 4. Merge results back, applying rename if needed
+ *
+ * Mutates the documents in place and returns them.
+ *
+ * @param documents - The documents to populate (mutated in place).
+ * @param steps - The populate steps to execute in order.
+ * @param getCollection - Function to get a native MongoDB Collection by name.
+ * @returns The populated documents.
+ *
+ * @example
+ * ```ts
+ * const docs = await executePopulate(rawDocs, steps, name => db.collection(name))
+ * ```
+ */
+declare function executePopulate(documents: Document[], steps: readonly PopulateStep[], getCollection: (name: string) => Collection): Promise<Document[]>;
+
 /**
  * Convenience namespace that groups all query operators under a single import.
  *
@@ -3918,4 +5488,4 @@ type UpdateFilterOf<TDef extends AnyCollection> = TypedUpdateFilter<InferDocumen
  */
 type SortOf<TDef extends AnyCollection> = TypedSort<InferDocument<TDef>>;
 
-export { $, $addToSet, $and, $avg, $count, $eq, $exists, $first, $gt, $gte, $in, $last, $lt, $lte, $max, $min, $ne, $nin, $nor, $not, $or, $push, $regex, $sum, type Accumulator, type AccumulatorBuilder, type AddToSetEach, type AddToSetFields, AggregatePipeline, type AnyCollection, type ArrayElement, type CollectionDefinition, CollectionHandle, type CollectionName, type CollectionOptions, type ComparisonOperators, type CompoundIndexDefinition, type CurrentDateFields, type CursorPage, type CursorPaginateOptions, Database, type DotPathType, type DotPaths, type Expression, type ExpressionBuilder, type ExtractRefCollection, type FieldIndexDefinition, type FieldRef, type FieldRefType, type FilterOf, type FindOneAndDeleteOptions, type FindOneAndUpdateOptions, type FindOneOptions, type FindOptions, type GroupByCompoundResult, type GroupByResult, type HandleOf, type IncFields, IndexBuilder, type IndexMetadata, type IndexNames, type IndexOptions, type IndexSpec, type InferAccumulator, type InferAccumulators, type InferAddedFields, type InferDocument, type InferExpression, type InferInsert, type NarrowFromFilter, type OffsetPage, type OffsetPaginateOptions, type PopFields, type Prettify, type PullFields, type PushFields, type PushModifiers, type RefFields, type RefMarker, type RefMetadata, type RenameFields, type ResolvedShape, type SetFields, type SortOf, type StaleIndex, type SyncIndexesOptions, type SyncIndexesResult, type TypedFilter, TypedFindCursor, type TypedSort, type TypedUpdateFilter, type UnsetFields, type UnwindResult, type UpdateFilterOf, type UpdateOptions, type ValidationMode, type ZodObjectId, ZodmonAuthError, ZodmonBulkWriteError, ZodmonDocValidationError, ZodmonDuplicateKeyError, ZodmonError, ZodmonIndexError, ZodmonNetworkError, ZodmonNotFoundError, ZodmonQueryError, ZodmonTimeoutError, ZodmonValidationError, ZodmonWriteConflictError, aggregate, checkUnindexedFields, collection, createAccumulatorBuilder, createClient, createExpressionBuilder, deleteMany, deleteOne, extractComparableOptions, extractDbName, extractFieldIndexes, find, findOne, findOneAndDelete, findOneAndUpdate, findOneOrThrow, generateIndexName, getIndexMetadata, getRefMetadata, index, insertMany, insertOne, isOid, objectId, oid, raw, serializeIndexKey, syncIndexes, toCompoundIndexSpec, toFieldIndexSpec, updateMany, updateOne, wrapMongoError };
+export { $, $addToSet, $and, $avg, $count, $eq, $exists, $first, $gt, $gte, $in, $last, $lt, $lte, $max, $min, $ne, $nin, $nor, $not, $or, $push, $regex, $sum, type Accumulator, type AccumulatorBuilder, type AddToSetEach, type AddToSetFields, AggregatePipeline, type AnyCollection, type ApplyPopulate, type ApplyPopulateProjected, type ArrayElement, type CollectionDefinition, CollectionHandle, type CollectionName, type CollectionOptions, type ComparisonOperators, type CompoundIndexDefinition, type CurrentDateFields, type CursorPage, type CursorPaginateOptions, Database, type DeepPopulate, type DotPath, type DotPathValue, type DotSubPaths, type ExclusionProjection, type Expression, type ExpressionBuilder, type ExtractRefCollection, type FieldIndexDefinition, type FieldOrExpr, type FieldRef, type FieldRefType, type FilterOf, type FindOneAndDeleteOptions, type FindOneAndUpdateOptions, type FindOneOptions, type FindOneProjectionOptions, type FindOptions, type FindProjectionOptions, type GroupByCompoundResult, type GroupByNullResult, type GroupByResult, type HandleOf, type IncFields, type InclusionProjection, IndexBuilder, type IndexMetadata, type IndexNames, type IndexOptions, type IndexSpec, type InferAccumulator, type InferAccumulators, type InferAddedFields, type InferDocument, type InferExpression, type InferInsert, type NarrowFromFilter, type NestedRefPath, type OffsetPage, type OffsetPaginateOptions, type PopFields, PopulateCursor, type PopulateField, type PopulateFieldProjected, PopulateOneOrThrowQuery, PopulateOneQuery, type PopulateProjectionConfig, PopulateRefBuilder, type PopulateStep, type Populated, type Prettify, type ProjectionResult, type PullFields, type PushFields, type PushModifiers, type RefFields, type RefMarker, type RefMetadata, type RenameFields, type ReplaceDots, type ResolvedShape, type SetFields, type SortOf, type StaleIndex, type SyncIndexesOptions, type SyncIndexesResult, TransactionContext, type TransactionFn, type TypedFilter, TypedFindCursor, type TypedProjection, type TypedSort, type TypedUpdateFilter, type UnsetFields, type UnwindResult, type UnwrapRef, type UpdateFilterOf, type UpdateOptions, type ValidationMode, type ZodObjectId, ZodmonAuthError, ZodmonBulkWriteError, ZodmonDocValidationError, ZodmonDuplicateKeyError, ZodmonError, ZodmonIndexError, ZodmonNetworkError, ZodmonNotFoundError, ZodmonQueryError, ZodmonTimeoutError, ZodmonValidationError, ZodmonWriteConflictError, aggregate, checkUnindexedFields, collection, createAccumulatorBuilder, createClient, createExpressionBuilder, createPopulateCursor, deleteMany, deleteOne, deriveProjectedSchema, executePopulate, extractComparableOptions, extractDbName, extractFieldIndexes, find, findOne, findOneAndDelete, findOneAndUpdate, findOneOrThrow, generateIndexName, getIndexMetadata, getRefMetadata, index, insertMany, insertOne, isInclusionProjection, isOid, objectId, oid, raw, resolvePopulateStep, serializeIndexKey, syncIndexes, toCompoundIndexSpec, toFieldIndexSpec, unwrapRefSchema, updateMany, updateOne, wrapMongoError };