sluice-orm 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2444 @@
+import { Collection as Collection$1, Document, ChangeStreamDocument, ObjectId, CollationOptions, InsertOneResult, InsertManyResult, UpdateResult, DeleteResult, BulkWriteResult, Db, BSONTypeAlias, Decimal128 } from 'mongodb';
+import { BSONValue } from 'bson';
+import * as tf from 'type-fest';
+import { Simplify, GreaterThan, IsAny, IsUnknown, UnionToTuple, ValueOf } from 'type-fest';
+import { JSONSchema } from 'json-schema-to-typescript';
+
+declare const functionToString: (fn: Function) => string;
+type TypedAccumulator<InitFn extends (...args: any[]) => any, AccArgs extends readonly unknown[], Result = ReturnType<InitFn>> = {
+    init: InitFn;
+    initArgs: Parameters<InitFn>;
+    accumulate: (state: ReturnType<InitFn>, ...args: [...AccArgs]) => ReturnType<InitFn>;
+    accumulateArgs: Readonly<{
+        [K in keyof AccArgs]: string;
+    }>;
+    merge: (state1: ReturnType<InitFn>, state2: ReturnType<InitFn>) => ReturnType<InitFn>;
+    finalize?: (state: ReturnType<InitFn>) => Result;
+    lang: "js";
+};
+declare const resolveAccumulator: <InitFn extends (...args: any[]) => any, AccArgs extends readonly unknown[], Result>(config: TypedAccumulator<InitFn, AccArgs, Result>) => {
+    init: string;
+    initArgs: Parameters<InitFn>;
+    accumulate: string;
+    accumulateArgs: Readonly<{ [K in keyof AccArgs]: string; }>;
+    merge: string;
+    lang: "js";
+} | {
+    finalize: string;
+    init: string;
+    initArgs: Parameters<InitFn>;
+    accumulate: string;
+    accumulateArgs: Readonly<{ [K in keyof AccArgs]: string; }>;
+    merge: string;
+    lang: "js";
+};
+
+declare const opaqueErrorBrand: unique symbol;
+/**
+ * Opaque error type that carries a message but hides implementation details
+ */
+type OpaqueError<Msg extends string> = {
+    readonly __error: Msg;
+    readonly __tag: "OpaqueError";
+    readonly [opaqueErrorBrand]: never;
+};
+/**
+ * Type error with structured details: what went wrong, expected type, got type
+ */
+type TypeError<Msg extends string, Expected = unknown, Got = unknown> = OpaqueError<Msg> & {
+    readonly __expected: Expected;
+    readonly __got: Got;
+    readonly __tag: "TypeError";
+};
+
+/**
+ * Type utilities for simplifying and making types writable
+ */
+
+type AnyDict = Dict<any>;
+type __ = unknown;
+type Dict<T> = Record<string, T>;
+/**
+ * SimplifyWritable - Makes a type writable (removes readonly) and simplifies it
+ * This combines WritableDeep and Simplify for cleaner type signatures
+ */
+type WritableBsonDeep<T> = T extends BSONValue | Date ? T : T extends readonly [] ? [] : T extends readonly [infer A, ...infer R] ? [WritableBsonDeep<A>, ...WritableBsonDeep<R>] : T extends readonly (infer E)[] ? WritableBsonDeep<E>[] : T extends object ? {
+    -readonly [K in keyof T]: WritableBsonDeep<T[K]>;
+} : T;
+type SimplifyWritable<T> = tf.Simplify<WritableBsonDeep<T>>;
+type LiteralKeys<T> = keyof T extends infer K ? true extends tf.IsLiteral<K> ? K & string : never : never;
+type HasStringIndex<T> = string extends keyof T ? true : false;
+type IndexValue<T> = string extends keyof T ? T[string] : never;
+type HasLiteralKey<T, K extends string> = K extends LiteralKeys<T> ? true : false;
+type MergeWithIndexOverride<A, B> = tf.Simplify<{
+    [K in LiteralKeys<A> | LiteralKeys<B>]: HasLiteralKey<B, K> extends true ? B[K & keyof B] : HasLiteralKey<A, K> extends true ? A[K & keyof A] : never;
+} & (HasStringIndex<B> extends true ? {
+    [k: string]: IndexValue<B>;
+} : HasStringIndex<A> extends true ? {
+    [k: string]: IndexValue<A>;
+} : NonNullable<unknown>)>;
+/**
+ * ShallowMergeObjectsOverride - Shallow merge array of object types with last-wins semantics
+ */
+type ShallowMergeObjectsOverride<T extends readonly AnyDict[]> = T extends readonly [] ? Dict<never> : T extends readonly [infer First extends AnyDict] ? First : T extends readonly [infer First extends AnyDict, ...infer Rest extends readonly AnyDict[]] ? MergeWithIndexOverride<First, ShallowMergeObjectsOverride<Rest>> : never;
+
+/**
+ * Path type utilities for MongoDB dot-notation access
+ *
+ * This module provides type-safe path utilities for MongoDB operations:
+ * - Path<T>: Generate all valid dot-notation paths (using type-fest)
+ * - ResolveValue<T, P>: Resolve the type at a given path
+ * - PathValueArrayProjection<T, P>: MongoDB array projection semantics
+ * - Type-filtered paths (NumericPath, StringPath, etc.)
+ * - Positional update paths ($[identifier])
+ *
+ * Uses type-fest's Paths with BsonStop to handle BSON types as leaf nodes.
+ */
+
+type BsonGuard<T> = T extends Date | BSONValue ? T & never : T extends readonly (infer E)[] ? readonly BsonGuard<E>[] : {
+    [K in keyof T]: BsonGuard<T[K]>;
+};
+type RawPath<T> = tf.Paths<BsonGuard<T>, {
+    maxRecursionDepth: 10;
+}> & string;
+type ReplaceDotNumber<T, With extends string> = T extends `${infer Head}.${infer Rest}` ? Rest extends `${number}${infer Tail}` ? `${Head}${With}${ReplaceDotNumber<Tail, With>}` : `${Head}.${ReplaceDotNumber<Rest, With>}` : T;
+type PathType<T> = ReplaceDotNumber<RawPath<T>, "" | `.${number}`>;
+type UpdatePathType<T> = ReplaceDotNumber<RawPath<T>, `.${number}` | `.$` | `.$[]` | `.$[${string}]`>;
+/**
+ * Normalize arrayFilters syntax to positional operator
+ * Transforms $[] and $[identifier] to $ for type checking
+ */
+type NormalizeArrayFilterPath<T extends string> = T extends `${infer Before}.${infer Rest}` ? `${NormalizeSegment<Before>}.${NormalizeArrayFilterPath<Rest>}` : NormalizeSegment<T>;
+type NormalizeSegment<T extends string> = T extends `${number}` ? "$" : T extends "$[]" | `$[${string}]` ? "$" : T;
+type ArrayIndex = `${number}` | `$` | `$[]` | `$[${string}]`;
+type _PathValue<T, P extends string> = P extends `${infer Key}.${infer Rest}` ? T extends readonly (infer E)[] ? Key extends ArrayIndex ? _PathValue<E, Rest> : _PathValue<E, P> : Key extends keyof T ? _PathValue<T[Key], Rest> : never : T extends readonly (infer E)[] ? P extends ArrayIndex ? E : _PathValue<E, P> : P extends keyof T ? T[P] : never;
+/**
+ * ResolveValue<T, P> - Get the value type at a given path P in type T
+ *
+ * MongoDB-compatible path resolution supporting:
+ * - Direct property access: ResolveValue<{name: string}, "name"> = string
+ * - Nested access: ResolveValue<{a: {b: string}}, "a.b"> = string
+ * - Array access: ResolveValue<{items: Item[]}, "items"> = Item[]
+ * - Array element via dot: ResolveValue<{items: {id: string}[]}, "items.id"> = string
+ * - Numeric index: ResolveValue<{items: string[]}, "items.0"> = string
+ * - Numeric index + nested: ResolveValue<{items: {id: string}[]}, "items.0.id"> = string
+ *
+ * Returns `never` for invalid paths.
+ */
+type ResolveValue<T, P extends string> = _PathValue<T, P>;
+type ResolvePath<T, P extends PathType<T>> = P extends PathType<T> ? ResolveValue<T, P> : never;
+type ResolveUpdatePath<T, P extends UpdatePathType<T>> = P extends UpdatePathType<T> ? ResolveValue<T, P> : never;
+type FilteredPath<T, Target> = {
+    [K in PathType<T>]: [ResolvePath<T, K>] extends [never] ? never : ResolvePath<T, K> extends Target ? K : never;
+}[PathType<T>];
+type UpdateFilteredPath<T, Target> = {
+    [K in UpdatePathType<T>]: [ResolveValue<T, K>] extends [never] ? never : ResolveValue<T, K> extends Target ? K : never;
+}[UpdatePathType<T>];
+type NumericPath<T> = FilteredPath<T, number | null | undefined>;
+type StringPath<T> = FilteredPath<T, string | null | undefined>;
+type BooleanPath<T> = FilteredPath<T, boolean | null | undefined>;
+type DatePath<T> = FilteredPath<T, Date | null | undefined>;
+type ArrayPath<T> = FilteredPath<T, readonly unknown[]>;
+type ComparablePath<T> = FilteredPath<T, number | string | boolean | Date | BSONValue | null | undefined>;
+type UpdateArrayPath<T> = UpdateFilteredPath<T, readonly unknown[]>;
+/**
+ * UpdateSpecOfType<T, Target, Value> - A spec type that validates paths resolve to Target
+ *
+ * Uses the 'as' clause to filter paths during iteration. This works because:
+ * - TypeScript's pattern matching allows specific strings like "$[x]" to match "$[${string}]"
+ * - The filter happens at assignment time, not enumeration time
+ * - Invalid paths (wrong type or doesn't exist) are excluded via `as ... never`
+ */
+type UpdateSpecOfType<T, Target, Value> = {
+    [K in UpdatePathType<T> as ResolveValue<T, K> extends Target ? ValidPositionalPath<K> : never]?: Value;
+};
+type HasPrefix<Target extends string, Union extends string> = Union extends unknown ? Target extends `${Union}.${string}` ? true : never : never;
+type _ArrayRootPath<T extends string, All extends string = T> = T extends unknown ? true extends HasPrefix<T, Exclude<All, T>> ? never : T : never;
+type IsPrefix<Needle extends string, Union extends string> = Union extends unknown ? Union extends `${Needle}.${string}` ? true : never : never;
+type ArrayRootPath<T> = _ArrayRootPath<ArrayPath<T>>;
+/**
+ * ArrayProjectionPath<T> - Paths that resolve to arrays via MongoDB array projection semantics
+ * This includes:
+ * - Direct array paths (e.g., "tags" where tags is string[])
+ * - Projection paths through arrays (e.g., "items.name" where items is {name: string}[] - projects to string[])
+ */
+type ArrayProjectionPath<T> = {
+    [K in PathType<T>]: PathValueArrayProjection<T, K> extends readonly unknown[] ? K : never;
+}[PathType<T>];
+type UpdateArrayElementType<T, P extends UpdatePathType<T>> = ResolveUpdatePath<T, P> extends readonly (infer E)[] ? E : never;
+/**
+ * PathValueArrayProjection<T, P> - Get the value type at path P with MongoDB array projection semantics
+ *
+ * In MongoDB, when you reference a path through an array like $items.name where items is an array
+ * of documents with a name field, it returns an array of all the name values (not a single value).
+ *
+ * Examples:
+ * - PathValueArrayProjection<{info: {name: string}[]}, "info.name"> = string[]
+ * - PathValueArrayProjection<{info: {name: string}[]}, "info"> = {name: string}[]
+ * - PathValueArrayProjection<{name: string}, "name"> = string
+ * - PathValueArrayProjection<{items: {discounts: {code: string}[]}[]}, "items.discounts.code"> = string[][]
+ */
+type PathValueArrayProjection<T, P extends PathType<T>> = _PathValueArrayProjection<T, P>;
+type _PathValueArrayProjection<T, P extends string> = P extends `${infer Key}.${infer Rest}` ? T extends readonly (infer E)[] ? Key extends `${number}` ? _PathValueArrayProjection<E, Rest> : _PathValueArrayProjection<E, P>[] : Key extends keyof T ? _PathValueArrayProjection<T[Key], Rest> : never : T extends readonly (infer E)[] ? P extends `${number}` ? E : _PathValueArrayProjection<E, P>[] : P extends keyof T ? T[P] : never;
+type NumericFieldRef<T> = `$${NumericPath<T>}`;
+type StringFieldRef<T> = `$${StringPath<T>}`;
+type DateFieldRef<T> = `$${DatePath<T>}`;
+type BooleanFieldRef<T> = `$${BooleanPath<T>}`;
+type ArrayFieldRef<T> = `$${ArrayPath<T>}`;
+/**
+ * Validates that positional paths don't contain double $ (.$. pattern) and don't start with $
+ * Returns the path if valid, OpaqueError if invalid
+ */
+type ValidPositionalPath<P extends string> = P extends `$${string}` ? OpaqueError<"Paths cannot start with $"> : P extends `${string}.$.${infer Rest1}` ? Rest1 extends `${string}.$.${string}` ? OpaqueError<"Paths cannot contain double $"> : P : P;
+
+/**
+ * Pipeline type utilities for type-safe stage chaining
+ *
+ * This module provides a unified PipelineBuilder that works for both
+ * aggregation pipelines and update pipelines.
+ */
+type CheckedResult<T> = tf.IsAny<T> extends true ? OpaqueError<"Pipeline stage produced or propagated 'any' or 'unknown' type. Please ensure all expressions are fully typed."> & {
+    __inferredType: T;
+} : T;
+/**
+ * Core Agg type - represents a pipeline at a point with input and current document types
+ */
+type Agg<TIn, TCurrent> = {
+    readonly _in: TIn;
+    readonly _current: SimplifyWritable<TCurrent>;
+    readonly stages: readonly object[];
+    pipe<TOut>(stage: (agg: Agg<TIn, TCurrent>) => Agg<TIn, TOut>): Agg<TIn, TOut>;
+    toList(collection?: Collection$1): Promise<SimplifyWritable<CheckedResult<TCurrent>>[]>;
+    /** Returns the accumulated pipeline stages as formatted JSON */
+    toMQL(): string;
+};
+/**
+ * Typed pipeline marker - used for sub-pipelines in $facet, $lookup, update pipelines, etc.
+ */
+type TypedPipeline<TIn, TOut> = {
+    readonly __pipelineIn: TIn;
+    readonly __pipelineOut: TOut;
+    readonly stages: readonly unknown[];
+};
+/**
+ * A stage function transforms an Agg<TIn, TFrom> to Agg<TIn, TTo>
+ * The TIn parameter is the original input type (for expression context)
+ *
+ * Used by both aggregation stages and update stages.
+ */
+type StageFunction<TIn, TFrom, TTo> = (agg: Agg<TIn, TFrom>) => Agg<TIn, TTo>;
+/**
+ * Brand for stages that are allowed in update pipelines.
+ * Only $set, $unset, $addFields, $project, $replaceRoot, $replaceWith are branded.
+ *
+ * IMPORTANT: UpdateStageFunction uses a callable object type with a call signature
+ * (`{ (agg): result; [brand]: true }`) rather than a function-object intersection
+ * (`((agg) => result) & { [brand]: true }`). TypeScript's inference engine cannot
+ * propagate generic parameters through function-object intersections in multi-stage
+ * overload resolution, causing C to default to {}.
+ */
+declare const __updateStage: unique symbol;
+type UpdateStageBrand = {
+    readonly [__updateStage]: true;
+};
+type UpdateStageFunction<TFrom, TTo> = {
+    <TIn>(agg: Agg<TIn, TFrom>): Agg<TIn, TTo>;
+    readonly [__updateStage]: true;
+};
+/**
+ * Output type resolver for all pipeline builder variants.
+ *
+ * - "agg": returns Agg (for collection.aggregate)
+ * - "pipeline": returns TypedPipeline (for sub-pipelines, pipe())
+ * - "update": validates Last extends Target, wraps in CheckedResult
+ * - "migration": validates Simplify<Last> extends Target
+ */
+type PipelineOutput<Mode extends "agg" | "pipeline" | "update" | "migration", TIn, Last, Target> = Mode extends "agg" ? Agg<TIn, Last> : Mode extends "pipeline" ? TypedPipeline<TIn, Last> : Mode extends "update" ? Last extends Target ? TypedPipeline<TIn, CheckedResult<Last>> : OpaqueError<"Update pipeline output must be assignable to collection type"> & TypedPipeline<TIn, Last> : tf.Simplify<Last> extends Target ? TypedPipeline<TIn, Last> : OpaqueError<"Migration output does not match target schema"> & TypedPipeline<TIn, Last>;
+/**
+ * Branded stage: bare StageFunction for standard builders,
+ * callable-object UpdateStageFunction for update/migration builders.
+ */
+type BStage<TIn, Brand, From, To> = [
+    {}
+] extends [Brand] ? StageFunction<TIn, From, To> : UpdateStageFunction<From, To>;
+/**
+ * GenericPipelineBuilder — single set of 15 overloads parameterized by Brand and Mode.
+ * All exported pipeline builder types derive from this.
+ */
+type GenericPipelineBuilder<TIn, Brand, Mode extends "agg" | "pipeline" | "update" | "migration", Target = unknown> = {
+    <A>(s1: BStage<TIn, Brand, TIn, A>): PipelineOutput<Mode, TIn, A, Target>;
+    <A, B>(s1: BStage<TIn, Brand, TIn, A>, s2: BStage<TIn, Brand, A, B>): PipelineOutput<Mode, TIn, B, Target>;
+    <A, B, C>(s1: BStage<TIn, Brand, TIn, A>, s2: BStage<TIn, Brand, A, B>, s3: BStage<TIn, Brand, B, C>): PipelineOutput<Mode, TIn, C, Target>;
+    <A, B, C, D>(s1: BStage<TIn, Brand, TIn, A>, s2: BStage<TIn, Brand, A, B>, s3: BStage<TIn, Brand, B, C>, s4: BStage<TIn, Brand, C, D>): PipelineOutput<Mode, TIn, D, Target>;
+    <A, B, C, D, E>(s1: BStage<TIn, Brand, TIn, A>, s2: BStage<TIn, Brand, A, B>, s3: BStage<TIn, Brand, B, C>, s4: BStage<TIn, Brand, C, D>, s5: BStage<TIn, Brand, D, E>): PipelineOutput<Mode, TIn, E, Target>;
+    <A, B, C, D, E, F>(s1: BStage<TIn, Brand, TIn, A>, s2: BStage<TIn, Brand, A, B>, s3: BStage<TIn, Brand, B, C>, s4: BStage<TIn, Brand, C, D>, s5: BStage<TIn, Brand, D, E>, s6: BStage<TIn, Brand, E, F>): PipelineOutput<Mode, TIn, F, Target>;
+    <A, B, C, D, E, F, G>(s1: BStage<TIn, Brand, TIn, A>, s2: BStage<TIn, Brand, A, B>, s3: BStage<TIn, Brand, B, C>, s4: BStage<TIn, Brand, C, D>, s5: BStage<TIn, Brand, D, E>, s6: BStage<TIn, Brand, E, F>, s7: BStage<TIn, Brand, F, G>): PipelineOutput<Mode, TIn, G, Target>;
+    <A, B, C, D, E, F, G, H>(s1: BStage<TIn, Brand, TIn, A>, s2: BStage<TIn, Brand, A, B>, s3: BStage<TIn, Brand, B, C>, s4: BStage<TIn, Brand, C, D>, s5: BStage<TIn, Brand, D, E>, s6: BStage<TIn, Brand, E, F>, s7: BStage<TIn, Brand, F, G>, s8: BStage<TIn, Brand, G, H>): PipelineOutput<Mode, TIn, H, Target>;
+    <A, B, C, D, E, F, G, H, I>(s1: BStage<TIn, Brand, TIn, A>, s2: BStage<TIn, Brand, A, B>, s3: BStage<TIn, Brand, B, C>, s4: BStage<TIn, Brand, C, D>, s5: BStage<TIn, Brand, D, E>, s6: BStage<TIn, Brand, E, F>, s7: BStage<TIn, Brand, F, G>, s8: BStage<TIn, Brand, G, H>, s9: BStage<TIn, Brand, H, I>): PipelineOutput<Mode, TIn, I, Target>;
+    <A, B, C, D, E, F, G, H, I, J>(s1: BStage<TIn, Brand, TIn, A>, s2: BStage<TIn, Brand, A, B>, s3: BStage<TIn, Brand, B, C>, s4: BStage<TIn, Brand, C, D>, s5: BStage<TIn, Brand, D, E>, s6: BStage<TIn, Brand, E, F>, s7: BStage<TIn, Brand, F, G>, s8: BStage<TIn, Brand, G, H>, s9: BStage<TIn, Brand, H, I>, s10: BStage<TIn, Brand, I, J>): PipelineOutput<Mode, TIn, J, Target>;
+    <A, B, C, D, E, F, G, H, I, J, K>(s1: BStage<TIn, Brand, TIn, A>, s2: BStage<TIn, Brand, A, B>, s3: BStage<TIn, Brand, B, C>, s4: BStage<TIn, Brand, C, D>, s5: BStage<TIn, Brand, D, E>, s6: BStage<TIn, Brand, E, F>, s7: BStage<TIn, Brand, F, G>, s8: BStage<TIn, Brand, G, H>, s9: BStage<TIn, Brand, H, I>, s10: BStage<TIn, Brand, I, J>, s11: BStage<TIn, Brand, J, K>): PipelineOutput<Mode, TIn, K, Target>;
+    <A, B, C, D, E, F, G, H, I, J, K, L>(s1: BStage<TIn, Brand, TIn, A>, s2: BStage<TIn, Brand, A, B>, s3: BStage<TIn, Brand, B, C>, s4: BStage<TIn, Brand, C, D>, s5: BStage<TIn, Brand, D, E>, s6: BStage<TIn, Brand, E, F>, s7: BStage<TIn, Brand, F, G>, s8: BStage<TIn, Brand, G, H>, s9: BStage<TIn, Brand, H, I>, s10: BStage<TIn, Brand, I, J>, s11: BStage<TIn, Brand, J, K>, s12: BStage<TIn, Brand, K, L>): PipelineOutput<Mode, TIn, L, Target>;
+    <A, B, C, D, E, F, G, H, I, J, K, L, M>(s1: BStage<TIn, Brand, TIn, A>, s2: BStage<TIn, Brand, A, B>, s3: BStage<TIn, Brand, B, C>, s4: BStage<TIn, Brand, C, D>, s5: BStage<TIn, Brand, D, E>, s6: BStage<TIn, Brand, E, F>, s7: BStage<TIn, Brand, F, G>, s8: BStage<TIn, Brand, G, H>, s9: BStage<TIn, Brand, H, I>, s10: BStage<TIn, Brand, I, J>, s11: BStage<TIn, Brand, J, K>, s12: BStage<TIn, Brand, K, L>, s13: BStage<TIn, Brand, L, M>): PipelineOutput<Mode, TIn, M, Target>;
+    <A, B, C, D, E, F, G, H, I, J, K, L, M, N>(s1: BStage<TIn, Brand, TIn, A>, s2: BStage<TIn, Brand, A, B>, s3: BStage<TIn, Brand, B, C>, s4: BStage<TIn, Brand, C, D>, s5: BStage<TIn, Brand, D, E>, s6: BStage<TIn, Brand, E, F>, s7: BStage<TIn, Brand, F, G>, s8: BStage<TIn, Brand, G, H>, s9: BStage<TIn, Brand, H, I>, s10: BStage<TIn, Brand, I, J>, s11: BStage<TIn, Brand, J, K>, s12: BStage<TIn, Brand, K, L>, s13: BStage<TIn, Brand, L, M>, s14: BStage<TIn, Brand, M, N>): PipelineOutput<Mode, TIn, N, Target>;
+    <A, B, C, D, E, F, G, H, I, J, K, L, M, N, O>(s1: BStage<TIn, Brand, TIn, A>, s2: BStage<TIn, Brand, A, B>, s3: BStage<TIn, Brand, B, C>, s4: BStage<TIn, Brand, C, D>, s5: BStage<TIn, Brand, D, E>, s6: BStage<TIn, Brand, E, F>, s7: BStage<TIn, Brand, F, G>, s8: BStage<TIn, Brand, G, H>, s9: BStage<TIn, Brand, H, I>, s10: BStage<TIn, Brand, I, J>, s11: BStage<TIn, Brand, J, K>, s12: BStage<TIn, Brand, K, L>, s13: BStage<TIn, Brand, L, M>, s14: BStage<TIn, Brand, M, N>, s15: BStage<TIn, Brand, N, O>): PipelineOutput<Mode, TIn, O, Target>;
+};
+/** For sub-pipeline composition (pipe(), $facet, etc.) — no output validation */
+type PipelineBuilder<TIn> = GenericPipelineBuilder<TIn, {}, "pipeline">;
+/** For collection.aggregate() — returns Agg instead of TypedPipeline */
+type AggregateBuilder<T> = GenericPipelineBuilder<T, {}, "agg">;
+/** For update pipelines — only UpdateStageBrand stages, validates output extends C */
+type UpdatePipelineBuilder<C> = GenericPipelineBuilder<C, UpdateStageBrand, "update", C>;
+/** For schema migration — only UpdateStageBrand stages, validates Simplify<output> extends TTo */
+type MigrationPipelineBuilder<TFrom, TTo> = GenericPipelineBuilder<TFrom, UpdateStageBrand, "migration", TTo>;
+
+/**
+ * Common error types and utilities for consistent error handling
+ * across the MongoDB aggregation and CRUD operations.
+ */
+type CallbackOnlyError<Op extends string> = {
+    __error: true;
+    __tag: "CallbackOnlyError";
+    __op: Op;
+    message: `Operation '${Op}' requires a callback function, not a raw expression`;
+};
+
+type DotPathToObject<Path extends string, Value> = Path extends `${infer Head}.${infer Tail}` ? {
+    [K in Head]: DotPathToObject<Tail, Value>;
+} : {
+    [K in Path]: Value;
+};
+type DeepMerge<A, B> = A extends object ? B extends object ? {
+    [K in keyof A | keyof B]: K extends keyof B ? K extends keyof A ? DeepMerge<A[K], B[K]> : B[K] : K extends keyof A ? A[K] : never;
+} : A | B : A | B;
+type ValidateSpec<C, Spec> = {
+    [K in keyof Spec]: Spec[K] extends 0 | 1 ? Spec[K] : Spec[K] extends Ret<any, any> ? Spec[K] : ValidExpressionValue<C, Spec[K]>;
+};
+type HasKey<Spec, K, V> = {
+    [P in keyof Spec]: Spec[P] extends V ? true : false;
+}[keyof Spec];
+type OnlyIdMixed<Spec> = HasKey<Spec, any, 1> extends true ? HasKey<Spec, any, 0> extends true ? keyof Spec & string extends "_id" | `_${string}` ? true : false : true : true;
+type ValidateProjectRules<Spec> = OnlyIdMixed<Spec> extends true ? Spec : CallbackOnlyError<"$project cannot mix inclusion (1) and exclusion (0) except for _id">;
+type ProjectIdResult<C, Spec> = Spec extends {
+    _id: 0;
+} ? {} : Spec extends {
+    _id: 1;
+} ? C extends {
+    _id: infer Id;
+} ? {
+    _id: Id;
+} : OpaqueError<"$project field does not exist: _id"> : C extends {
+    _id: infer Id;
+} ? {
+    _id: Id;
+} : {};
+type ProjectResult<C, Spec> = Simplify<ProjectIdResult<C, Spec> & {
+    [K in Exclude<keyof Spec, "_id">]: Spec[K] extends 1 ? K extends keyof C ? C[K] : OpaqueError<`$project field does not exist: ${K & string}`> : Spec[K] extends 0 ? never : ResolveType<C, Spec[K]>;
+}>;
+type WindowBoundary$1 = "unbounded" | "current" | number;
+type WindowDef = {
+    documents?: [WindowBoundary$1, WindowBoundary$1];
+    range?: [WindowBoundary$1, WindowBoundary$1];
+    unit?: TimeUnit;
+};
+type AccumulatorOp<C, T = ExpressionIn<C>> = {
+    window?: WindowDef;
+} & ({
+    $sum: T;
+} | {
+    $avg: T;
+} | {
+    $min: T;
+} | {
+    $max: T;
+} | {
+    $first: T;
+} | {
+    $last: T;
+} | {
+    $count: Dict<never>;
+} | {
+    $push: T;
+} | {
+    $addToSet: T;
+});
+type WindowOperatorSpec<C> = AccumulatorOp<C> | Ret<C, any> | {
+    $rank: Dict<never>;
+} | {
+    $denseRank: Dict<never>;
+} | {
+    $documentNumber: Dict<never>;
+} | {
+    $percentRank: Dict<never>;
+} | {
+    $shift: {
+        output: ExpressionIn<C>;
+        by: number;
+        default?: ExpressionIn<C>;
+    };
+} | {
+    $expMovingAvg: {
+        input: ExpressionIn<C>;
+        N?: number;
+        alpha?: number;
+    };
+} | {
+    $linearFill: ExpressionIn<C>;
+} | {
+    $derivative: {
+        input: ExpressionIn<C>;
+        unit?: TimeUnit;
+    };
+    window: WindowDef;
+} | {
+    $integral: {
+        input: ExpressionIn<C>;
+        unit?: TimeUnit;
+    };
+};
+type HasNullish$1<T> = [Extract<T, null | undefined>] extends [never] ? false : true;
+type NullishResult$1<C, T, Output> = HasNullish$1<ResolveType<C, T>> extends true ? Output | null : Output;
+type WindowOperatorResult<C, Op> = Op extends Ret<C, infer T> ? T : Op extends {
+    $sum: NumericIn<C>;
+} ? number : Op extends {
+    $avg: infer A;
+} ? NullishResult$1<C, A, number> : Op extends {
+    $min: ExpressionIn<C>;
+} ? ResolveType<C, Op["$min"]> | null : Op extends {
+    $max: ExpressionIn<C>;
+} ? ResolveType<C, Op["$max"]> | null : Op extends {
+    $first: ExpressionIn<C>;
+} ? ResolveType<C, Op["$first"]> : Op extends {
+    $last: ExpressionIn<C>;
+} ? ResolveType<C, Op["$last"]> : Op extends {
+    $count: Dict<never>;
+} ? number : Op extends {
+    $push: ExpressionIn<C>;
+} ? ResolveType<C, Op["$push"]>[] : Op extends {
+    $addToSet: ExpressionIn<C>;
+} ? ResolveType<C, Op["$addToSet"]>[] : Op extends {
+    $rank: Dict<never>;
+} ? number : Op extends {
+    $denseRank: Dict<never>;
+} ? number : Op extends {
+    $documentNumber: Dict<never>;
+} ? number : Op extends {
+    $percentRank: Dict<never>;
+} ? number : Op extends {
+    $shift: {
+        output: infer Output;
+        default?: infer Default;
+    };
+} ? Default extends ExpressionIn<C> ? ResolveType<C, Output> | ResolveType<C, Default> : ResolveType<C, Output> | null : Op extends {
+    $expMovingAvg: any;
+} ? number | null : Op extends {
+    $linearFill: ExpressionIn<C>;
+} ? ResolveType<C, Op["$linearFill"]> | null : Op extends {
+    $derivative: any;
+} ? number | null : Op extends {
+    $integral: any;
+} ? number | null : unknown;
+type SortBySpec$1<C> = Partial<Record<keyof C & string, 1 | -1>>;
+type SortBySingle<C> = {
+    [K in keyof C & string]: {
+        [P in K]: 1 | -1;
+    };
+}[keyof C & string];
+type SortPath$1<C> = ComparablePath<C> | "_id" | `_id.${string}`;
+type SortValue = 1 | -1 | {
+    $meta: "textScore" | "searchScore";
+};
+type SortSpec$1<C> = Partial<Record<SortPath$1<C>, SortValue>> | {
+    $meta: "textScore" | "searchScore";
+} | (Partial<Record<SortPath$1<C>, SortValue>> & {
+    $meta: "textScore" | "searchScore";
+});
+type SortByHasDate<C, S> = [
+    S
+] extends [undefined] ? false : true extends ({
+    [K in keyof S]: K extends keyof C ? C[K] extends Date ? true : false : false;
+}[keyof S]) ? true : false;
+type HasRangeWindowWithoutUnit<Output> = true extends ({
+    [K in keyof Output]: Output[K] extends {
+        window: {
+            range: any;
+        };
+    } ? Output[K] extends {
+        window: {
+            unit: any;
+        };
+    } ? false : true : false;
+}[keyof Output]) ? true : false;
+type RequiresSortBy<C, Output extends Dict<WindowOperatorSpec<C>>> = true extends ({
+    [K in keyof Output]: Output[K] extends ({
+        $rank: any;
+    } | {
+        $denseRank: any;
+    } | {
+        $percentRank: any;
+    }) ? true : false;
+}[keyof Output]) ? true : false;
+type RemoveNever<T> = {
+    [K in keyof T as T[K] extends never ? never : K]: T[K];
+};
+type UnwindPath<T extends string> = T extends `$${infer Field}` ? Field : never;
+type UnwindElement<T> = T extends readonly (infer E)[] ? E : T extends (infer E)[] ? E : T;
+type UnwindResult<C, P extends string> = {
+    [K in keyof C]: K extends UnwindPath<P> ? UnwindElement<C[K]> : C[K];
+};
+type UnwindResultWithPreserve<C, P extends string, Preserve extends boolean | undefined> = {
+    [K in keyof C]: K extends UnwindPath<P> ? Preserve extends true ? UnwindElement<C[K]> | null | undefined : UnwindElement<C[K]> : C[K];
+};
+type IndexStatsResult = {
+    name: string;
+    key: Dict<number>;
+    host: string;
+    accesses: {
+        ops: number;
+        since: Date;
+    };
+    shard?: string;
+    spec?: AnyDict;
+};
+type SortByCountResult<T> = {
+    _id: T;
+    count: number;
+};
+type UnsetResult<C, Fields extends string[]> = Omit<C, Fields[number]>;
+type CollectionOf<T> = T extends Collection ? T : T extends {
+    coll: infer C;
+} ? C extends Collection ? C : never : never;
+type CollectionConstraint<C, TTarget extends Collection> = C extends CollectionType<TTarget> ? {} : CallbackOnlyError<"Collection type mismatch">;
+type MergeIntoConstraint<C, TInto extends Collection> = CollectionConstraint<C, TInto>;
+type OutIntoConstraint<C, T> = CollectionConstraint<C, CollectionOf<T>>;
+type ValidateNoRawOperators<T extends Dict<any>> = {
+    [K in keyof T]: T[K] extends {
+        readonly __context: any;
+        readonly __type: any;
+    } ? T[K] : T[K] extends {
+        [key: `$${string}`]: any;
+    } ? OpaqueError<"Invalid MongoDB operator object - use builder API instead (e.g., $.sum(...))"> : T[K];
+};
+type WindowFieldsOptions<C, T extends {
+    partitionBy?: ExpressionIn<C> | Dict<ExpressionIn<C> | Ret<C>> | Ret<C>;
+    sortBy?: SortBySpec$1<C>;
+    output: Dict<WindowOperatorSpec<C>>;
+}> = SortByHasDate<C, T["sortBy"]> extends true ? HasRangeWindowWithoutUnit<T["output"]> extends true ? OpaqueError<"$setWindowFields range window with date sortBy requires unit"> & T : RequiresSortBy<C, T["output"]> extends true ? T & {
+    sortBy: SortBySingle<C>;
+} : T : RequiresSortBy<C, T["output"]> extends true ? T & {
+    sortBy: SortBySingle<C>;
+} : T;
+type ReplaceRootScalar<C> = SmartAnyPathFieldRef<C> | Ret<C> | "$$ROOT" | "$$CURRENT";
+type ReplaceRootValue<C> = ReplaceRootScalar<C> | {
+    [K in string]: ReplaceRootValue<C>;
+};
+type ReplaceRootResolved<C, R> = R extends "$$ROOT" | "$$CURRENT" ? C : R extends Ret<any, infer T> ? T : R extends object ? ResolveSpec<C, R> : ResolveType<C, R>;
+type IsStrictlyAscending<T extends readonly number[]> = T extends (readonly [infer A extends number, infer B extends number, ...infer Rest extends number[]]) ? number extends A | B ? true : GreaterThan<B, A> extends false ? false : IsStrictlyAscending<[B, ...Rest]> : true;
+type AscendingBoundaries<T extends readonly number[]> = IsStrictlyAscending<T> extends true ? T : OpaqueError<"$bucket boundaries must be strictly increasing">;
+/** Adds new fields to documents. Alias for `$set`.
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/addFields/ */
+declare const $addFields: <C, const T>(fieldsBuilder: ($: ExprBuilder<Simplify<C>>) => T) => UpdateStageFunction<C, Simplify<C & ResolveSpec<C, T>>>;
+/** Groups documents into discrete buckets by a specified expression and boundaries.
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/bucket/ */
+declare const $bucket: {
+    <C, const B extends readonly number[], const D extends string | number = never, const O extends AnyDict = Dict<never>>(options: {
+        groupBy: ExpressionIn<C>;
+        boundaries: B & AscendingBoundaries<B>;
+        default?: D;
+        output: ($: AccumulatorBuilder<Simplify<C>>) => O & ValidateNoRawOperators<O>;
+    }): <TIn>(agg: Agg<TIn, C>) => Agg<TIn, {
+        _id: B[number] | D;
+    } & ResolveSpec<C, O>>;
+    <C, const B extends readonly number[], const D extends string | number = never>(options: {
+        groupBy: ExpressionIn<C>;
+        boundaries: B & AscendingBoundaries<B>;
+        default?: D;
+    }): <TIn>(agg: Agg<TIn, C>) => Agg<TIn, {
+        _id: B[number] | D;
+        count: number;
+    }>;
+};
+/** Automatically groups documents into a specified number of buckets.
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/bucketAuto/ */
+declare const $bucketAuto: <C, const G extends ExpressionIn<C>, const O extends Dict<ExpressionIn<C>> | undefined = undefined>(options: {
+    groupBy: G;
+    buckets: number;
+    output?: O;
+    granularity?: "R5" | "R10" | "R20" | "R40" | "R80" | "1-2-5" | "E6" | "E12" | "E24" | "E48" | "E96" | "E192" | "POWERSOF2";
+}) => <TIn>(agg: Agg<TIn, C>) => Agg<TIn, {
+    _id: {
+        min: ResolveType<C, G>;
+        max: ResolveType<C, G>;
+    };
+    count: number;
+} & (O extends AnyDict ? { [K in keyof O]: ResolveType<C, O[K]>; } : {})>;
+/** Returns statistics about the collection (latency, storage, count, query exec stats).
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/collStats/ */
+declare const $collStats: {
+    <C, const T extends {
+        latencyStats?: {
+            histograms?: boolean;
+        };
+        storageStats?: {
+            scale?: number;
+        };
+        count: Dict<never>;
+        queryExecStats?: Dict<never>;
+    }>(options: T): <TIn>(agg: Agg<TIn, C>) => Agg<TIn, {
+        ns: string;
+        localTime: Date;
+    } & (T extends {
+        latencyStats: any;
+    } ? {
+        latencyStats: {
+            reads: Dict<number>;
+            writes: Dict<number>;
+            commands: Dict<number>;
+        };
+    } : {
+        latencyStats?: {
+            reads: Dict<number>;
+            writes: Dict<number>;
+            commands: Dict<number>;
+        };
+    }) & (T extends {
+        storageStats: any;
+    } ? {
+        storageStats: {
+            size: number;
+            count: number;
+            avgObjSize: number;
+            storageSize: number;
+        };
+    } : {
+        storageStats?: {
+            size: number;
+            count: number;
+            avgObjSize: number;
+            storageSize: number;
+        };
+    }) & {
+        count: number;
+    } & (T extends {
+        queryExecStats: any;
+    } ? {
+        queryExecStats: Dict<number>;
+    } : {
+        queryExecStats?: Dict<number>;
+    })>;
+    <C, const T extends {
+        latencyStats?: {
+            histograms?: boolean;
+        };
+        storageStats?: {
+            scale?: number;
+        };
+        count?: Dict<never>;
+        queryExecStats?: Dict<never>;
+    }>(options: T): <TIn>(agg: Agg<TIn, C>) => Agg<TIn, {
+        ns: string;
+        localTime: Date;
+    } & (T extends {
+        latencyStats: any;
+    } ? {
+        latencyStats: {
+            reads: Dict<number>;
+            writes: Dict<number>;
+            commands: Dict<number>;
+        };
+    } : {
+        latencyStats?: {
+            reads: Dict<number>;
+            writes: Dict<number>;
+            commands: Dict<number>;
+        };
+    }) & (T extends {
+        storageStats: any;
+    } ? {
+        storageStats: {
+            size: number;
+            count: number;
+            avgObjSize: number;
+            storageSize: number;
+        };
+    } : {
+        storageStats?: {
+            size: number;
+            count: number;
+            avgObjSize: number;
+            storageSize: number;
+        };
+    }) & {
+        count?: number;
+    } & (T extends {
+        queryExecStats: any;
+    } ? {
+        queryExecStats: Dict<number>;
+    } : {
+        queryExecStats?: Dict<number>;
+    })>;
+};
+/** Replaces the input documents with a count of the documents at this stage.
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/count/ */
+declare const $count: <C, const T extends string>(field: T) => <TIn>(agg: Agg<TIn, C>) => Agg<TIn, { [K in T]: number; }>;
+/** Creates new documents in a sequence of documents where gaps exist.
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/densify/ */
+declare const $densify: <C, const T extends {
+    field: keyof C & string;
+    partitionByFields?: (keyof C & string)[];
+    range: {
+        step: number;
+        unit?: TimeUnit;
+        bounds: "full" | "partition" | [__, __];
+    };
+}>(options: NoInfer<T>) => <TIn>(agg: Agg<TIn, C>) => Agg<TIn, C>;
+/** Returns literal documents from input values (no collection required).
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/documents/ */
+declare const $documents: <const T extends readonly Dict<unknown>[]>(documents: T) => Agg<T[number], T[number]>;
+/** Processes multiple aggregation pipelines on the same input documents in a single stage.
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/facet/ */
+declare const $facet: <C, const T extends Dict<TypedPipeline<C, __>>>(pipelines: ($: ExprBuilder<Simplify<C>>) => T) => <TIn>(agg: Agg<TIn, C>) => Agg<TIn, { [K in keyof T]: T[K] extends TypedPipeline<any, infer R> ? R[] : T[K] extends readonly [...any[], (agg: any) => Agg<any, infer R>] ? R[] : __[]; }>;
+/** Populates null and missing field values using linear interpolation or last-observed carry-forward.
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/fill/ */
+declare const $fill: <C, const T extends {
+    partitionBy?: ExpressionIn<C>;
+    partitionByFields?: (keyof C & string)[];
+    sortBy: SortBySpec$1<C>;
+    output: { [K in keyof C]?: {
+        method: "linear" | "locf";
+    } | {
+        value: ExpressionIn<C>;
+    }; };
+}>(options: T) => <TIn>(agg: Agg<TIn, C>) => Agg<TIn, C>;
+/** Returns documents ordered by proximity to a geospatial point.
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/geoNear/ */
+declare const $geoNear: <C, const TDistanceField extends string, const TIncludeLocs extends string | undefined = undefined>(options: {
+    near: {
+        type: "Point";
+        coordinates: [number, number];
+    };
+    distanceField: TDistanceField;
+    spherical?: boolean;
+    maxDistance?: number;
+    minDistance?: number;
+    query?: AnyDict;
+    distanceMultiplier?: number;
+    includeLocs?: TIncludeLocs;
+    uniqueDocs?: boolean;
+    key?: string;
+}) => <TIn>(agg: Agg<TIn, C>) => Agg<TIn, C & DeepMerge<DotPathToObject<TDistanceField, number>, TIncludeLocs extends string ? DotPathToObject<TIncludeLocs, {
+    type: "Point";
+    coordinates: [number, number];
+}> : {}>>;
+/** Performs a recursive search on a collection following references between documents.
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/graphLookup/ */
+declare const $graphLookup: <C, const TFrom extends Collection, const TAs extends string, const TDF extends string | undefined = undefined>(options: {
+    from: TFrom;
+    startWith: ExpressionIn<C>;
+    connectFromField: keyof ForeignType<TFrom> & string;
+    connectToField: keyof ForeignType<TFrom> & string;
+    as: TAs;
+    maxDepth?: number;
+    depthField?: TDF;
+    restrictSearchWithMatch?: AnyDict;
+}) => <TIn>(agg: Agg<TIn, C>) => Agg<TIn, C & Record<TAs, (ForeignType<TFrom> & Record<TDF & string, number>)[]>>;
+type GroupIdSpec<C> = ExpressionIn<C> | Ret<C> | null | Dict<ExpressionIn<C> | Ret<C>>;
+type ValidateGroupOutput<C, T extends {
+    _id: GroupIdSpec<C>;
+}> = {
+    [K in keyof T]: K extends "_id" ? T[K] : T[K] extends Ret<C, any> ? T[K] : OpaqueError<"Invalid $group output - use builder API (e.g., $.sum(...))">;
+};
+/** Groups documents by a specified expression and applies accumulator expressions.
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/group/ */
+declare const $group: <C, const T extends {
+    _id: GroupIdSpec<C>;
+}>(spec: ($: AccumulatorBuilder<Simplify<C>>) => ValidateGroupOutput<C, T>) => <TIn>(agg: Agg<TIn, C>) => Agg<TIn, ResolveSpec<C, T>>;
+/** Returns statistics about index usage for the collection.
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/indexStats/ */
+declare const $indexStats: <C>() => <TIn>(agg: Agg<TIn, C>) => Agg<TIn, IndexStatsResult>;
+/** Limits the number of documents passed to the next stage.
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/limit/ */
+declare const $limit: <C, const T extends number>(n: T) => <TIn>(agg: Agg<TIn, C>) => Agg<TIn, C>;
+type LetToContext<C, Let extends Dict<ExpressionIn<C>>> = {
+    [K in keyof Let as `$${K & string}`]: ResolveType<C, Let[K]>;
+};
+type StripLookupVars<T> = {
+    [K in keyof T as K extends `$${string}` ? never : K]: T[K];
+};
+type LookupContext<TFrom extends Collection, C, TLet extends Dict<ExpressionIn<C>> | undefined> = TLet extends Dict<ExpressionIn<C>> ? ForeignType<TFrom> & LetToContext<C, TLet> : ForeignType<TFrom>;
+/** Performs a left outer join with another collection.
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/lookup/ */
+declare const $lookup: {
+    <C, TFrom extends Collection, const TAs extends string, const TLet extends Dict<ExpressionIn<C>> | undefined = undefined, TPipelineOut = ForeignType<TFrom>>(options: {
+        from: TFrom;
+        localField?: PathType<C>;
+        foreignField?: PathType<ForeignType<TFrom>>;
+        let?: TLet;
+        pipeline?: ($: ExprBuilder<LookupContext<TFrom, C, TLet>>) => TypedPipeline<LookupContext<TFrom, C, TLet>, TPipelineOut>;
+        as: TAs;
+    }): <TIn>(agg: Agg<TIn, C>) => Agg<TIn, Simplify<C & Record<TAs, StripLookupVars<TPipelineOut>[]>>>;
+    <C, TFrom extends Collection, const TAs extends string>(options: {
+        from: TFrom;
+        localField?: PathType<C>;
+        foreignField?: PathType<ForeignType<TFrom>>;
+        pipeline: readonly object[];
+        as: TAs;
+    }): <TIn>(agg: Agg<TIn, C>) => Agg<TIn, CallbackOnlyError<"$lookup.pipeline">>;
+};
+/** Filters documents to pass only those that match the specified conditions.
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/match/ */
+declare const $match: <C, const R extends NoInfer<ValidMatchFilterWithBuilder<C>>>(filter: ($: ExprBuilder<Simplify<C>>) => R) => <TIn>(agg: Agg<TIn, C>) => Agg<TIn, C>;
+/** Writes pipeline results to a collection, merging with existing documents. Terminal stage.
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/merge/ */
+declare const $merge: <C, const T extends {
+    into: Collection;
+    on?: (keyof C & string) | readonly (keyof C & string)[];
+    let?: Dict<ExpressionIn<C>>;
+    whenMatched?: "replace" | "keepExisting" | "merge" | "fail" | readonly AnyDict[];
+    whenNotMatched?: "insert" | "discard" | "fail";
+}>(options: T & MergeIntoConstraint<C, T["into"]>) => <TIn>(agg: Agg<TIn, C>) => Agg<TIn, never>;
+/** Writes pipeline results to a collection, replacing existing content. Terminal stage.
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/out/ */
+declare const $out: <C, const T extends Collection | {
+    db: string;
+    coll: Collection;
+}>(options: T & OutIntoConstraint<C, T>) => <TIn>(agg: Agg<TIn, C>) => Agg<TIn, never>;
+/** Reshapes documents by including, excluding, or computing new fields.
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/project/ */
+declare const $project: <C, const T extends Dict<0 | 1 | ExpressionIn<C> | Ret<C>>>(spec: ($: ExprBuilder<Simplify<C>>) => ValidateProjectRules<ValidateSpec<C, T>>) => UpdateStageFunction<C, RemoveNever<ProjectResult<C, T>>>;
+/** Restricts document content based on access-control expressions ($$DESCEND, $$PRUNE, $$KEEP).
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/redact/ */
+declare const $redact: {
+    <C>(expression: ($: ExprBuilder<Simplify<C>>) => Ret<C, "$$DESCEND" | "$$PRUNE" | "$$KEEP">): <TIn>(agg: Agg<TIn, C>) => Agg<TIn, C>;
+    <C, const T extends "$$DESCEND" | "$$PRUNE" | "$$KEEP" | Ret<C, "$$DESCEND" | "$$PRUNE" | "$$KEEP">>(expression: T): <TIn>(agg: Agg<TIn, C>) => Agg<TIn, C>;
+};
+/** Replaces the input document with the specified document (via `newRoot`).
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/replaceRoot/ */
+declare const $replaceRoot: {
+    <C, const T extends {
+        newRoot: ReplaceRootValue<C>;
+    }>(options: T): UpdateStageFunction<C, ReplaceRootResolved<C, T["newRoot"]>>;
+    <C, const T extends {
+        newRoot: ReplaceRootValue<Simplify<C>>;
+    }>(options: ($: ExprBuilder<Simplify<C>>) => T): UpdateStageFunction<C, ReplaceRootResolved<C, T["newRoot"]>>;
+    <C, const T extends ReplaceRootValue<C>>(expression: T): UpdateStageFunction<C, ReplaceRootResolved<C, T>>;
+    <C, const T extends ReplaceRootValue<Simplify<C>>>(expression: ($: ExprBuilder<Simplify<C>>) => T): UpdateStageFunction<C, ReplaceRootResolved<C, T>>;
+};
+/** Replaces the input document with the specified expression. Shorthand for `$replaceRoot`.
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/replaceWith/ */
+declare const $replaceWith: {
+    <C, const T extends ReplaceRootValue<C>>(expression: T): UpdateStageFunction<C, ReplaceRootResolved<C, T>>;
+    <C, const T extends ReplaceRootValue<Simplify<C>>>(expression: ($: ExprBuilder<Simplify<C>>) => T): UpdateStageFunction<C, ReplaceRootResolved<C, T>>;
+};
+/** Randomly selects the specified number of documents from input.
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/sample/ */
+declare const $sample: <C, const T extends number>(options: {
+    size: T;
+}) => <TIn>(agg: Agg<TIn, C>) => Agg<TIn, C>;
+/** Adds new fields to documents. Alias for `$addFields`.
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/set/ */
+declare const $set: {
+    <C, const T extends Dict<ExpressionIn<C> | Ret<C>>>(fields: NoInfer<T>): UpdateStageFunction<C, Simplify<C & { [K in keyof T]: ResolveType<C, T[K]>; }>>;
+    <C, const T extends Dict<ExpressionIn<Simplify<C>> | Ret<Simplify<C>>>>(fields: ($: ExprBuilder<Simplify<C>>) => T): UpdateStageFunction<C, Simplify<C & { [K in keyof T]: ResolveType<C, T[K]>; }>>;
+};
+/** Performs window function calculations across a specified span of documents.
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/setWindowFields/ */
+declare const $setWindowFields: <C, const T extends {
+    partitionBy?: ExpressionIn<C> | Dict<ExpressionIn<C> | Ret<C>> | Ret<C>;
+    sortBy?: SortBySpec$1<C>;
+    output: Dict<WindowOperatorSpec<C>>;
+}>(options: ($: WindowBuilder<Simplify<C>>) => WindowFieldsOptions<C, T>) => <TIn>(agg: Agg<TIn, C>) => Agg<TIn, C & { [K in keyof T["output"]]: WindowOperatorResult<C, T["output"][K]>; }>;
+/** Skips the first N documents.
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/skip/ */
+declare const $skip: <C, const T extends number>(n: T) => <TIn>(agg: Agg<TIn, C>) => Agg<TIn, C>;
+/** Sorts all input documents and returns them in the specified order.
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/sort/ */
+declare const $sort: <C>(spec: SortSpec$1<C>) => <TIn>(agg: Agg<TIn, C>) => Agg<TIn, C>;
+/** Groups documents by an expression and sorts by count.
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/sortByCount/ */
+declare const $sortByCount: <C, const T extends ExpressionIn<C>>(expression: T) => <TIn>(agg: Agg<TIn, C>) => Agg<TIn, SortByCountResult<ResolveType<C, T>>>;
+/** Combines pipeline results from another collection into the current pipeline.
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/unionWith/ */
+declare const $unionWith: <C, const T extends {
+    coll: Collection;
+    pipeline?: TypedPipeline<ForeignType<T["coll"]>, __> | readonly ((agg: Agg<ForeignType<T["coll"]>, ForeignType<T["coll"]>>) => any)[];
+}>(options: T) => <TIn>(agg: Agg<TIn, C>) => Agg<TIn, C | ForeignType<T["coll"]>>;
+/** Removes specified fields from documents.
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/unset/ */
+declare const $unset: <C, const T extends readonly (keyof C & string)[]>(...fields: T) => UpdateStageFunction<C, UnsetResult<C, T extends readonly string[] ? [...T] : never>>;
+/** Deconstructs an array field, outputting one document per array element.
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/unwind/ */
+declare const $unwind: {
+    <C, const P extends `$${ArrayRootPath<C>}`>(path: P): <TIn>(agg: Agg<TIn, C>) => Agg<TIn, UnwindResult<C, P>>;
+    <C, const P extends `$${ArrayRootPath<C>}`, const TPreserve extends boolean | undefined = undefined, const TIndexField extends string | undefined = undefined>(options: {
+        path: P;
+        includeArrayIndex?: TIndexField;
+        preserveNullAndEmptyArrays?: TPreserve;
+    }): <TIn>(agg: Agg<TIn, C>) => Agg<TIn, UnwindResultWithPreserve<C, P, TPreserve> & (TIndexField extends string ? Record<TIndexField, number> : {})>;
+};
+type SanitizeAny<T> = IsAny<T> extends true ? never : IsUnknown<T> extends true ? never : T extends Date ? T : T extends readonly (infer E)[] ? readonly SanitizeAny<E>[] : T extends object ? {
+    [K in keyof T]: SanitizeAny<T[K]>;
+} : T;
+type ChangeStreamDocumentSafe<T extends Document> = SanitizeAny<ChangeStreamDocument<T>>;
+/** Opens a change stream cursor on a collection. Must be the first stage.
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/changeStream/ */
+declare const $changeStream: <C extends Document, const T extends {
+    allChangesForCluster?: boolean;
+    fullDocument?: "default" | "required" | "updateLookup" | "whenAvailable";
+    fullDocumentBeforeChange?: "off" | "whenAvailable" | "required";
+    resumeAfter?: AnyDict;
+    startAfter?: AnyDict;
+    startAtOperationTime?: Date;
+    showExpandedEvents?: boolean;
+}>(options: NoInfer<T>) => <TIn>(agg: Agg<TIn, C>) => Agg<TIn, Simplify<ChangeStreamDocumentSafe<C>>>;
+/** Returns information on active and queued operations. For `db.aggregate()` only.
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/currentOp/ */
+declare const $currentOp: <C, const T extends {
+    allUsers?: boolean;
+    idleConnections?: boolean;
+    idleCursors?: boolean;
+    idleSessions?: boolean;
+    localOps?: boolean;
+}>(options: NoInfer<T>) => <TIn>(agg: Agg<TIn, C>) => Agg<TIn, {
+    host: string;
+    desc: string;
+    connectionId: number;
+    client: string;
+    appName?: string;
+    clientMetadata?: AnyDict;
+    active: boolean;
+    currentOpTime: Date;
+    opid: number;
+    secs_running: number;
+    microsecs_running: number;
+    op: string;
+    ns: string;
+    command: AnyDict;
+    planSummary?: string;
+    cursor?: {
+        cursorId: number;
+        createdDate: Date;
+        lastAccessDate: Date;
+    };
+    lsid?: {
+        id: ObjectId;
+        uid: string;
+    };
+    transaction?: AnyDict;
+    locking?: AnyDict;
+    waitingForLock?: boolean;
+    msg?: string;
+    progress?: {
+        done: number;
+        total: number;
+    };
+    killPending?: boolean;
+    numYields?: number;
+    dataThroughputLastSecond?: number;
+    dataThroughputAverage?: number;
+}>;
+/** Lists sessions cached in memory by the `mongod` or `mongos` instance.
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/listLocalSessions/ */
+declare const $listLocalSessions: <C, const T extends {
+    allUsers?: boolean;
+    users?: {
+        user: string;
+        db: string;
+    }[];
+}>(options: NoInfer<T>) => <TIn>(agg: Agg<TIn, C>) => Agg<TIn, {
+    _id: {
+        id: ObjectId;
+        uid: string;
+    };
+    lastUse: Date;
+    user?: {
+        user: string;
+        db: string;
+    };
+    client?: string;
+    connections?: number;
+    activeTransactions?: AnyDict;
+}>;
+/** Lists all sessions stored in the `system.sessions` collection.
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/listSessions/ */
+declare const $listSessions: <C, const T extends {
+    allUsers?: boolean;
+    users?: {
+        user: string;
+        db: string;
+    }[];
+}>(options: NoInfer<T>) => <TIn>(agg: Agg<TIn, C>) => Agg<TIn, {
+    _id: {
+        id: ObjectId;
+        uid: string;
+    };
+    lastUse: Date;
+    user?: {
+        user: string;
+        db: string;
+    };
+    client?: string;
+    connections?: number;
+    activeTransactions?: AnyDict;
+}>;
+/** Returns plan cache information for a collection.
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/planCacheStats/ */
+declare const $planCacheStats: <C>() => <TIn>(agg: Agg<TIn, C>) => Agg<TIn, {
+    version: string;
+    created: Date;
+    planCacheKey: string;
+    queryHash: string;
+    planCacheKeyWithQueryHash: string;
+    isActive: boolean;
+    works: number;
+    timeOfCreation: Date;
+    timeOfCreationMicros: number;
+    lastSeenDate: Date;
+    lastSeenDateMicros: number;
+    creationExecStats?: AnyDict;
+    cachedPlan?: AnyDict;
+    winningPlan?: AnyDict;
+    candidatePlans?: AnyDict[];
+}>;
+/** Returns data distribution information for sharded collections.
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/shardedDataDistribution/ */
+declare const $shardedDataDistribution: <C>() => <TIn>(agg: Agg<TIn, C>) => Agg<TIn, {
+    ns: string;
+    shards: Record<string, {
+        numOrphanedDocs: number;
+        numOwnedDocuments: number;
+        ownedSizeBytes: number;
+        orphanedSizeBytes: number;
+    }>;
+    numShards: number;
+    collections: Record<string, {
+        numOrphanedDocs: number;
+        numOwnedDocuments: number;
+        ownedSizeBytes: number;
+        orphanedSizeBytes: number;
+    }>;
+    totalSizeBytes: number;
+    totalOrphanedSizeBytes: number;
+    totalOwnedSizeBytes: number;
+    totalNumOrphanedDocs: number;
+    totalNumOwnedDocuments: number;
+}>;
+
+/**
+ * Update pipeline stages - unified with aggregation pipeline stages
+ *
+ * All stages are imported from sluice-stages.ts for single source of truth.
+ * Update pipelines use the exact same StageFunction types as aggregation pipelines.
+ */
+
+/**
+ * Type for the context-aware update operators passed as `$` to update pipeline callbacks.
+ *
+ * Members are named without the `$` prefix so callback usage reads naturally:
+ * `$ => $.pipe($.set(...), $.unset(...))`
+ */
+type UpdateOperators<C> = {
+    set: typeof $set;
+    unset: typeof $unset;
+    replaceRoot: typeof $replaceRoot;
+    replaceWith: typeof $replaceWith;
+    addFields: typeof $addFields;
+    project: typeof $project;
+    pipe: UpdatePipelineBuilder<C>;
+};
+/**
+ * Callback type for update pipelines that receives context-aware operators
+ */
+type UpdatePipelineCallback<C> = ($: UpdateOperators<C>) => TypedPipeline<C, unknown>;
+
+/**
+ * Validation types for MongoDB update operations
+ * Provides three categories of compile-time errors:
+ * 1. Invalid path (including $, $[], $[id] syntax)
+ * 2. Invalid value type for the path
+ * 3. Invalid or missing arrayFilters
+ */
+
+/**
+ * Extract all $[identifier] from a path string
+ */
+type ExtractIdentifier<P extends string> = P extends `${string}$[${infer Id}]${infer Rest}` ? Id extends "" ? ExtractIdentifier<Rest> : Id | ExtractIdentifier<Rest> : never;
+/**
+ * Extract all identifiers from all paths in an operator spec
+ */
+type ExtractIdentifiersFromSpec<Spec extends object> = {
+    [K in keyof Spec]: K extends string ? ExtractIdentifier<K> : never;
+}[keyof Spec];
+/**
+ * Extract all identifiers from entire update spec
+ */
+type ExtractRequiredIdentifiers<UpdateSpec> = UpdateSpec extends object ? {
+    [Op in keyof UpdateSpec]: Op extends `$${string}` ? UpdateSpec[Op] extends object ? ExtractIdentifiersFromSpec<UpdateSpec[Op]> : never : never;
+}[keyof UpdateSpec] : never;
+type NormalizePaths<Paths extends readonly string[]> = Paths extends readonly [infer Head extends string, ...infer Tail extends readonly string[]] ? readonly [NormalizeArrayFilterPath<Head>, ...NormalizePaths<Tail>] : readonly [];
+type HasDuplicates<T extends readonly string[]> = T extends readonly [infer Head extends string, ...infer Tail extends readonly string[]] ? Head extends Tail[number] ? true : HasDuplicates<Tail> : false;
+type HasPathConflict<T extends readonly string[], U extends T[number] = T[number]> = HasDuplicates<T> extends true ? true : (U extends string ? IsPrefix<U, Exclude<T[number], U>> : never) extends infer Result ? [
+    Result
+] extends [never] ? false : true : never;
+type ValidatePathConflicts<Paths extends readonly string[]> = [
+    HasPathConflict<NormalizePaths<Paths>>
+] extends [true] ? OpaqueError<"Conflicting update paths (duplicate or parent/child)"> : Paths;
+
+/**
+ * Strict type definitions for MongoDB update operators
+ * Each operator has precise path and value constraints
+ */
+
+type Nil = null | undefined;
+type ValueOrExpr<C, T> = T | Ret<C, T>;
+type EmptyArrayLiteral = readonly [] | never[];
+type AllowEmptyArray<T> = [T] extends [readonly unknown[]] ? T | EmptyArrayLiteral : T;
+type AllPaths<T> = UpdatePathType<T> | ArrayRootPath<T>;
+type ValidPath<T, P extends AllPaths<T>> = P extends string ? ValidPositionalPath<P> : P;
+type SetSpec<T> = {
+    [P in AllPaths<T> as ValidPath<T, P>]?: ValueOrExpr<T, AllowEmptyArray<ResolveValue<T, P>>>;
+};
+type UnsetSpec<T> = {
+    [P in AllPaths<T> as ValidPath<T, P>]?: "" | 1 | true;
+};
+type IncSpec<T> = UpdateSpecOfType<T, number | Nil, ValueOrExpr<T, number>>;
+type MulSpec<T> = UpdateSpecOfType<T, number | Nil, ValueOrExpr<T, number>>;
+type MinMaxSpec<T> = {
+    [P in UpdatePathType<T> as ResolveValue<T, P> extends string | number | Date ? P : never]?: ValueOrExpr<T, ResolveUpdatePath<T, P>>;
+};
+type RenameSpec<T> = {
+    [P in AllPaths<T>]?: string;
+};
+type CurrentDateSpec<T> = UpdateSpecOfType<T, Date | Nil, true | {
+    $type: "date" | "timestamp";
+}>;
+type PushModifiers<C, Elem> = {
+    $each: readonly ValueOrExpr<C, Elem>[];
+    $position?: ValueOrExpr<C, number>;
+    $slice?: ValueOrExpr<C, number>;
+    $sort?: 1 | -1 | (Elem extends object ? Partial<Record<keyof Elem, 1 | -1>> : never);
+};
+type PushSpec<T> = {
+    [P in UpdateArrayPath<T>]?: ValueOrExpr<T, UpdateArrayElementType<T, P>> | (UpdateArrayElementType<T, P> extends infer Elem ? {
+        $each: readonly ValueOrExpr<T, Elem>[];
+    } | Partial<PushModifiers<T, Elem>> : never);
+};
+type AddToSetSpec<T> = {
+    [P in UpdateArrayPath<T>]?: ValueOrExpr<T, UpdateArrayElementType<T, P>> | {
+        $each: readonly ValueOrExpr<T, UpdateArrayElementType<T, P>>[];
+    };
+};
+type PullMatch<T, V> = {
+    $eq?: ValueOrExpr<T, V>;
+    $ne?: ValueOrExpr<T, V>;
+    $gt?: ValueOrExpr<T, V>;
+    $gte?: ValueOrExpr<T, V>;
+    $lt?: ValueOrExpr<T, V>;
+    $lte?: ValueOrExpr<T, V>;
+    $in?: readonly ValueOrExpr<T, V>[];
+    $nin?: readonly ValueOrExpr<T, V>[];
+    $regex?: string | RegExp;
+    $exists?: boolean;
+};
+type PullCondition<T, Elem> = {
+    [K in keyof Elem]?: ValueOrExpr<T, Elem[K]> | PullMatch<T, Elem[K]> | (Elem[K] extends readonly (infer Item)[] ? ValueOrExpr<T, Item> | PullMatch<T, Item> : never);
+} & {
+    $and?: readonly PullCondition<T, Elem>[];
+    $or?: readonly PullCondition<T, Elem>[];
+    $nor?: readonly PullCondition<T, Elem>[];
+};
+type PullSpec<T> = {
+    [P in UpdateArrayPath<T>]?: ValueOrExpr<T, UpdateArrayElementType<T, P>> | PullMatch<T, UpdateArrayElementType<T, P>> | (UpdateArrayElementType<T, P> extends object ? PullCondition<T, UpdateArrayElementType<T, P>> : never);
+};
+type PopSpec<T> = {
+    [P in UpdateArrayPath<T>]?: 1 | -1;
+};
+type PullAllSpec<T> = {
+    [P in UpdateArrayPath<T>]?: readonly ValueOrExpr<T, UpdateArrayElementType<T, P>>[];
+};
+type BitSpec<T> = UpdateSpecOfType<T, number | Nil, {
+    and: ValueOrExpr<T, number>;
+} | {
+    or: ValueOrExpr<T, number>;
+} | {
+    xor: ValueOrExpr<T, number>;
+}>;
+
+/**
+ * Strict typing for MongoDB update operations
+ * Ensures type safety for update specs, array filters, and positional operators
+ */
+
+/**
+ * StrictUpdateSpec - Type-safe MongoDB update document
+ * Each operator validates paths and values against the document schema
+ */
+type StrictUpdateSpec<T> = {
+    $set?: SetSpec<T>;
+    $setOnInsert?: SetSpec<T>;
+    $unset?: UnsetSpec<T>;
+    $inc?: IncSpec<T>;
+    $mul?: MulSpec<T>;
+    $min?: MinMaxSpec<T>;
+    $max?: MinMaxSpec<T>;
+    $rename?: RenameSpec<T>;
+    $currentDate?: CurrentDateSpec<T>;
+    $push?: PushSpec<T>;
+    $addToSet?: AddToSetSpec<T>;
+    $pull?: PullSpec<T>;
+    $pop?: PopSpec<T>;
+    $pullAll?: PullAllSpec<T>;
+    $bit?: BitSpec<T>;
+};
+type ValidateOperatorSpec<Spec, Expected> = {
+    [P in keyof Spec]: P extends keyof Expected ? Spec[P] : never;
+};
+type ValidateUpdateSpec<T, Spec extends StrictUpdateSpec<T>> = {
+    [K in keyof Spec]: K extends "$set" ? ValidateOperatorSpec<Spec[K], SetSpec<T>> : K extends "$setOnInsert" ? ValidateOperatorSpec<Spec[K], SetSpec<T>> : K extends "$unset" ? ValidateOperatorSpec<Spec[K], UnsetSpec<T>> : K extends "$inc" ? ValidateOperatorSpec<Spec[K], IncSpec<T>> : K extends "$mul" ? ValidateOperatorSpec<Spec[K], MulSpec<T>> : K extends "$min" ? ValidateOperatorSpec<Spec[K], MinMaxSpec<T>> : K extends "$max" ? ValidateOperatorSpec<Spec[K], MinMaxSpec<T>> : K extends "$rename" ? ValidateOperatorSpec<Spec[K], RenameSpec<T>> : K extends "$currentDate" ? ValidateOperatorSpec<Spec[K], CurrentDateSpec<T>> : K extends "$push" ? ValidateOperatorSpec<Spec[K], PushSpec<T>> : K extends "$addToSet" ? ValidateOperatorSpec<Spec[K], AddToSetSpec<T>> : K extends "$pull" ? ValidateOperatorSpec<Spec[K], PullSpec<T>> : K extends "$pop" ? ValidateOperatorSpec<Spec[K], PopSpec<T>> : K extends "$pullAll" ? ValidateOperatorSpec<Spec[K], PullAllSpec<T>> : K extends "$bit" ? ValidateOperatorSpec<Spec[K], BitSpec<T>> : never;
+} & (ValidatePathConflicts<ExtractPaths<Spec>> extends infer Conflict ? Conflict extends OpaqueError<string> ? Conflict : unknown : unknown);
+type RecordToTupleType<T extends Dict<any>> = UnionToTuple<ValueOf<{
+    [K in keyof T]: [K, T[K]];
+}>>;
+type FlattenPaths<T extends readonly any[], Acc extends readonly string[] = readonly []> = T extends readonly [readonly [any, infer Paths extends readonly string[]], ...infer Rest] ? FlattenPaths<Rest, readonly [...Acc, ...Paths]> : Acc;
+type ExtractPaths<UpdateSpec extends Dict<any>> = FlattenPaths<RecordToTupleType<{
+    [Op in keyof UpdateSpec]: UnionToTuple<keyof UpdateSpec[Op] & string>;
+}>>;
+type UnionToIntersection<U> = (U extends unknown ? (value: U) => void : never) extends (value: infer I) => void ? I : never;
+type ArrayIndexPath<Elem> = Elem extends readonly (infer E)[] ? `${number}` | `${number}.${PathType<E>}` : never;
+type ArrayFilterKey<Elem, Id extends string> = Elem extends Dict<unknown> ? Id | `${Id}.${PathType<Elem>}` : Elem extends readonly unknown[] ? Id | `${Id}.${ArrayIndexPath<Elem>}` : Id;
+type ArrayFilterOperators<T> = {
+    $eq?: T;
+    $ne?: T;
+    $gt?: T extends number | Date | string ? T : never;
+    $gte?: T extends number | Date | string ? T : never;
+    $lt?: T extends number | Date | string ? T : never;
+    $lte?: T extends number | Date | string ? T : never;
+    $in?: readonly T[];
+    $nin?: readonly T[];
+    $regex?: T extends string ? string | RegExp : never;
+    $exists?: boolean;
+    $type?: string | number;
+    $size?: T extends readonly unknown[] ? number : never;
+};
+type ArrayFilterValue<Elem, Id extends string, K extends string> = K extends `${Id}.${infer P}` ? P extends PathType<Elem> ? ResolvePath<Elem, P> | ArrayFilterOperators<ResolvePath<Elem, P>> : never : Elem | ArrayFilterOperators<Elem>;
+type ArrayFilterSpecForId<Elem, Id extends string> = {
+    [K in ArrayFilterKey<Elem, Id>]?: ArrayFilterValue<Elem, Id, K>;
+};
+/**
+ * Extract array filter ID to path mapping recursively
+ * e.g., "tags.$[i]" => { i: "tags.$[i]" }
+ *       "items.$[i].$[j]" => { i: "items.$[i]", j: "items.$[i].$[j]" }
+ */
+type ExtractArrayFilterIdPaths<P extends string, Prefix extends string = "", Acc extends Dict<string> = {}> = P extends `${infer Before}.$[${infer Id}]${infer After}` ? Id extends "" ? ExtractArrayFilterIdPaths<After, `${Prefix}${Before}.$[]`, Acc> : ExtractArrayFilterIdPaths<After, `${Prefix}${Before}.$[${Id}]`, Acc & {
+    [K in Id]: `${Prefix}${Before}.$[${Id}]`;
+}> : Acc;
+/**
+ * Extract all update paths from a StrictUpdateSpec
+ */
+type ExtractPathsFromUpdateSpec<T, Spec extends StrictUpdateSpec<T>> = {
+    [K in keyof Spec]: K extends `$${string}` ? Spec[K] extends object ? keyof Spec[K] & string : never : never;
+}[keyof Spec] & UpdatePathType<T>;
+/**
+ * Convert ID->Path map to ID->Type map
+ * Handles union of paths by merging all ID->Type mappings via UnionToIntersection
+ */
+type ArrayFilterTypes<C, P extends UpdatePathType<C>> = Simplify<UnionToIntersection<P extends infer Path extends string ? ExtractArrayFilterIdPaths<Path> extends infer M ? {
+    [Id in keyof M]: ResolveUpdatePath<C, M[Id] & UpdatePathType<C>>;
+} : never : never>>;
+/**
+ * Infer array filter types from update spec
+ */
+type InferArrayFilters<T, Spec extends StrictUpdateSpec<T>> = ArrayFilterTypes<T, ExtractPathsFromUpdateSpec<T, Spec>>;
+/**
+ * Required array filters when positional operators are used
+ */
+type RequiredArrayFilters<T, Spec extends StrictUpdateSpec<T>> = ExtractRequiredIdentifiers<Spec> extends never ? {} : {
+    arrayFilters: InferArrayFilters<T, Spec> extends infer AF extends Dict<unknown> ? keyof AF extends never ? never : readonly Partial<{
+        [Id in keyof AF]: ArrayFilterSpecForId<AF[Id], Id & string>;
+    }[keyof AF]>[] : never;
+};
+/**
+ * UpdateOptions - Options for update operations with type-safe arrayFilters
+ */
+type UpdateOptions<T, Spec extends StrictUpdateSpec<T>> = {
+    upsert?: boolean;
+    hint?: string | Dict<1 | -1>;
+} & RequiredArrayFilters<T, Spec>;
+
+type CrudFilter<C> = ValidMatchFilterWithBuilder<C>;
+type SortSpec<C> = Partial<Record<string | (keyof C & string), 1 | -1>>;
+type ProjectionSpec<C> = Partial<Record<keyof C & string, 0 | 1>>;
+type FindOptions<C> = {
+    projection?: ProjectionSpec<C>;
+    sort?: SortSpec<C>;
+    limit?: number;
+    skip?: number;
+    hint?: string | Document;
+    collation?: CollationOptions;
+    maxTimeMS?: number;
+    comment?: string;
+};
+type FindBuilder<C> = {
+    readonly _filter: CrudFilter<C> | undefined;
+    readonly _options: FindOptions<C> | undefined;
+    toList(): Promise<C[]>;
+    toOne(): Promise<C | null>;
+};
+type InsertOneBuilder<C> = {
+    readonly _doc: C;
+    execute(): Promise<InsertOneResult>;
+};
+type InsertManyBuilder<C> = {
+    readonly _docs: readonly C[];
+    execute(): Promise<InsertManyResult>;
+};
+type UpdateOneBuilder<C extends Document, U extends StrictUpdateSpec<C> = StrictUpdateSpec<C>> = {
+    readonly _filter: CrudFilter<C>;
+    readonly _update: U | (($: ExprBuilder<C>) => U);
+    readonly _options: UpdateOptions<C, U> | undefined;
+    execute(): Promise<UpdateResult>;
+};
+type UpdateManyBuilder<C extends Document, U extends StrictUpdateSpec<C> = StrictUpdateSpec<C>> = {
+    readonly _filter: CrudFilter<C>;
+    readonly _update: U | (($: ExprBuilder<C>) => U);
+    readonly _options: UpdateOptions<C, U> | undefined;
+    execute(): Promise<UpdateResult>;
+};
+type ReplaceBuilder<C> = {
+    readonly _filter: CrudFilter<C>;
+    readonly _replacement: C;
+    readonly _options: unknown;
+    execute(): Promise<UpdateResult>;
+};
+type DeleteBuilder<C> = {
+    readonly _filter: CrudFilter<C>;
+    execute(): Promise<DeleteResult>;
+};
+type FindOneAndDeleteBuilder<C> = {
+    readonly _filter: CrudFilter<C>;
+    execute(): Promise<C | null>;
+};
+type FindOneAndReplaceBuilder<C> = {
+    readonly _filter: CrudFilter<C>;
+    readonly _replacement: C;
+    execute(): Promise<C | null>;
+};
+type FindOneAndUpdateBuilder<C extends Document, U extends StrictUpdateSpec<C> = StrictUpdateSpec<C>> = {
+    readonly _filter: CrudFilter<C>;
+    readonly _update: U;
+    execute(): Promise<C | null>;
+};
+type FindOneAndOptions<C> = {
+    sort?: SortSpec<C>;
+    projection?: ProjectionSpec<C>;
+    upsert?: boolean;
+    returnDocument?: "before" | "after";
+    hint?: string | Document;
+    collation?: CollationOptions;
+    maxTimeMS?: number;
+    comment?: string;
+};
+type CountOptions = {
+    limit?: number;
+    skip?: number;
+    maxTimeMS?: number;
+    hint?: string | Document;
+    collation?: CollationOptions;
+    comment?: string;
+};
+type CountBuilder = {
+    execute(): Promise<number>;
+};
+type BulkWriteOp<C extends Document> = {
+    insertOne: {
+        document: C;
+    };
+} | {
+    updateOne: {
+        filter: CrudFilter<C>;
+        update: StrictUpdateSpec<C>;
+        upsert?: boolean;
+        arrayFilters?: Document[];
+        hint?: string | Document;
+        collation?: CollationOptions;
+    };
+} | {
+    updateMany: {
+        filter: CrudFilter<C>;
+        update: StrictUpdateSpec<C>;
+        upsert?: boolean;
+        arrayFilters?: Document[];
+        hint?: string | Document;
+        collation?: CollationOptions;
+    };
+} | {
+    deleteOne: {
+        filter: CrudFilter<C>;
+        hint?: string | Document;
+        collation?: CollationOptions;
+    };
+} | {
+    deleteMany: {
+        filter: CrudFilter<C>;
+        hint?: string | Document;
+        collation?: CollationOptions;
+    };
+} | {
+    replaceOne: {
+        filter: CrudFilter<C>;
+        replacement: C;
+        upsert?: boolean;
+        hint?: string | Document;
+        collation?: CollationOptions;
+    };
+};
+type BulkWriteBuilder<C extends Document> = {
+    readonly _operations: readonly BulkWriteOp<C>[];
+    execute(options?: {
+        ordered?: boolean;
+    }): Promise<BulkWriteResult>;
+};
+type DistinctBuilder<T> = {
+    execute(): Promise<T[]>;
+};
+interface CrudCollection<C extends Document> {
+    find: {
+        (): FindBuilder<C>;
+        <const R extends NoInfer<ValidMatchFilterWithBuilder<C>>>(filter: ($: ExprBuilder<SimplifyWritable<C>>) => R, options?: FindOptions<C>): FindBuilder<C>;
+    };
+    findOne: <const R extends NoInfer<ValidMatchFilterWithBuilder<C>>>(filter?: ($: ExprBuilder<SimplifyWritable<C>>) => R, options?: FindOptions<C>) => FindBuilder<C>;
+    insertOne: (doc: C) => InsertOneBuilder<C>;
+    insertMany: (docs: readonly C[]) => InsertManyBuilder<C>;
+    updateOne: <const R extends NoInfer<ValidMatchFilterWithBuilder<C>>, const Update extends StrictUpdateSpec<C> | UpdatePipelineCallback<C>>(filter: ($: ExprBuilder<SimplifyWritable<C>>) => R, update: Update extends StrictUpdateSpec<C> ? Update & ValidateUpdateSpec<C, Update> : Update extends UpdatePipelineCallback<C> ? Update : never, ...options: NoInfer<Update extends StrictUpdateSpec<C> ? ExtractRequiredIdentifiers<Update> extends never ? [
+        UpdateOptions<C, Update>?
+    ] : [UpdateOptions<C, Update>] : []>) => UpdateOneBuilder<C, Update extends StrictUpdateSpec<C> ? Update : StrictUpdateSpec<C>>;
+    updateMany: <const R extends NoInfer<ValidMatchFilterWithBuilder<C>>, const Update extends StrictUpdateSpec<C> | UpdatePipelineCallback<C>>(filter: ($: ExprBuilder<SimplifyWritable<C>>) => R, update: Update extends StrictUpdateSpec<C> ? Update & ValidateUpdateSpec<C, Update> : Update extends UpdatePipelineCallback<C> ? Update : never, ...options: NoInfer<Update extends StrictUpdateSpec<C> ? ExtractRequiredIdentifiers<Update> extends never ? [
+        UpdateOptions<C, Update>?
+    ] : [UpdateOptions<C, Update>] : []>) => UpdateManyBuilder<C, Update extends StrictUpdateSpec<C> ? Update : StrictUpdateSpec<C>>;
+    replaceOne: <const R extends NoInfer<ValidMatchFilterWithBuilder<C>>>(filter: ($: ExprBuilder<SimplifyWritable<C>>) => R, replacement: C, options?: unknown) => ReplaceBuilder<C>;
+    deleteOne: <const R extends NoInfer<ValidMatchFilterWithBuilder<C>>>(filter: ($: ExprBuilder<SimplifyWritable<C>>) => R) => DeleteBuilder<C>;
+    deleteMany: <const R extends NoInfer<ValidMatchFilterWithBuilder<C>>>(filter: ($: ExprBuilder<SimplifyWritable<C>>) => R) => DeleteBuilder<C>;
+    findOneAndDelete: <const R extends NoInfer<ValidMatchFilterWithBuilder<C>>>(filter: ($: ExprBuilder<SimplifyWritable<C>>) => R, options?: FindOneAndOptions<C>) => FindOneAndDeleteBuilder<C>;
+    findOneAndReplace: <const R extends NoInfer<ValidMatchFilterWithBuilder<C>>>(filter: ($: ExprBuilder<SimplifyWritable<C>>) => R, replacement: C, options?: FindOneAndOptions<C>) => FindOneAndReplaceBuilder<C>;
+    findOneAndUpdate: <const R extends NoInfer<ValidMatchFilterWithBuilder<C>>, const Update extends StrictUpdateSpec<C>>(filter: ($: ExprBuilder<SimplifyWritable<C>>) => R, update: Update & ValidateUpdateSpec<C, Update>, ...options: NoInfer<ExtractRequiredIdentifiers<Update> extends never ? [
+        (UpdateOptions<C, Update> & FindOneAndOptions<C>)?
+    ] : [UpdateOptions<C, Update> & FindOneAndOptions<C>]>) => FindOneAndUpdateBuilder<C, Update>;
+    countDocuments: {
+        (): CountBuilder;
+        <const R extends NoInfer<ValidMatchFilterWithBuilder<C>>>(filter: ($: ExprBuilder<SimplifyWritable<C>>) => R, options?: CountOptions): CountBuilder;
+    };
+    estimatedDocumentCount: () => CountBuilder;
+    distinct: <K extends keyof C & string>(field: K, filter?: ($: ExprBuilder<SimplifyWritable<C>>) => ValidMatchFilterWithBuilder<C>) => DistinctBuilder<C[K]>;
+    bulkWrite: (operations: readonly BulkWriteOp<C>[], options?: {
+        ordered?: boolean;
+    }) => BulkWriteBuilder<C>;
+}
+
+/**
+ * A schema-like object from which a document TypeScript type can be extracted.
+ *
+ * Compatible with:
+ * - **Zod**: `z.object({ name: z.string() })` → inferred via `_output`
+ * - **Effect Schema**: `Schema.Struct({ name: Schema.String })` → inferred via `Type`
+ * - **Plain type marker**: `{ Type: MyType }` for manual schemas
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * const UserSchema = z.object({ name: z.string(), age: z.number() });
+ * const reg = registry("8.0", { users: UserSchema });
+ * ```
+ */
+type SchemaLike = {
+    readonly Type: Dict<unknown>;
+} | {
+    readonly _output: Dict<unknown>;
+} | {
+    readonly [schemaTypeKey]: Dict<unknown>;
+};
+declare const schemaTypeKey: unique symbol;
+/** Extract the inferred document type from a SchemaLike */
+type InferSchema<S extends SchemaLike> = S extends {
+    readonly Type: infer T extends Dict<unknown>;
+} ? T : S extends {
+    readonly _output: infer T extends Dict<unknown>;
+} ? T : S extends {
+    readonly [schemaTypeKey]: infer T extends Dict<unknown>;
+} ? T : Dict<unknown>;
+type MongoVersions = ["4.2", "4.4", "5.0", "5.1", "6.0", "6.1", "7.0", "7.1", "8.0"];
+/**
+ * Collection type that carries both name and schema information
+ * Used for type-safe collection references in $lookup, $unionWith, etc.
+ */
+type Collection<TName extends string = string, TSchema extends Dict<unknown> = Dict<unknown>> = {
+    readonly __collectionName: TName;
+    readonly __collectionType: SimplifyWritable<TSchema>;
+};
+type CollectionType<T extends Collection> = T["__collectionType"];
+type BoundCollection<TName extends string, TSchema extends Dict<unknown>> = Collection<TName, TSchema> & {
+    aggregate: AggregateBuilder<SimplifyWritable<TSchema>>;
+} & CrudCollection<SimplifyWritable<TSchema>>;
+/**
+ * Creates a bound collection with type-safe aggregate and CRUD methods.
+ *
+ * Wraps a MongoDB native collection with schema-aware operations.
+ * Typically called indirectly via {@link registry} rather than directly.
+ *
+ * @example
+ * ```ts
+ * const users = collection("users", userSchema, db.collection("users"));
+ * const result = await users.aggregate($match($ => ({ age: $.gte(18) }))).toList();
+ * ```
+ */
+declare const collection: <TName extends string, TSchema extends SchemaLike>(name: TName, _schema: TSchema, mongoCol: Collection$1<SimplifyWritable<InferSchema<TSchema>>>) => BoundCollection<TName, InferSchema<TSchema>>;
+/**
+ * Creates a type-safe registry of MongoDB collections from schema definitions.
+ *
+ * Returns a factory that binds schemas to a `Db` instance, producing
+ * collections with fully-typed aggregation pipelines and CRUD operations.
+ *
+ * @example
+ * ```ts
+ * const db = registry("8.0", {
+ *   users: userSchema,
+ *   orders: orderSchema,
+ * })(client.db("mydb"));
+ *
+ * const result = await db.users.aggregate(
+ *   $match($ => ({ active: true })),
+ *   $project($ => ({ name: 1 })),
+ * ).toList();
+ * ```
+ */
+declare const registry: <const TMap extends Dict<SchemaLike>, const TVersion extends MongoVersions[number]>(version: TVersion, // For later on when we have to deal with version-specific features
+schemas: { [K in keyof TMap]: TMap[K]; }) => (client: Db) => { [K in keyof TMap]: BoundCollection<K & string, InferSchema<TMap[K]>>; };
+
+type ResolvePathValue<C, P extends string> = P extends PathType<C> ? PathValueArrayProjection<C, P> extends never ? ResolveValue<C, P> : PathValueArrayProjection<C, P> : OpaqueError<`Invalid path: ${P}`>;
+type Geometry = {
+    type: "Point";
+    coordinates: [number, number];
+} | {
+    type: "LineString";
+    coordinates: [number, number][];
+} | {
+    type: "Polygon";
+    coordinates: [number, number][][];
+} | {
+    type: "MultiPoint";
+    coordinates: [number, number][];
+} | {
+    type: "MultiLineString";
+    coordinates: [number, number][][];
+} | {
+    type: "MultiPolygon";
+    coordinates: [number, number][][][];
+} | {
+    type: "GeometryCollection";
+    geometries: Geometry[];
+};
+
+type ForeignType<T extends Collection> = T["__collectionType"];
+
+type NumericArrayPath<T> = FilteredPath<T, readonly number[] | number[] | null | undefined>;
+type NumericArrayFieldRef<T> = `$${NumericArrayPath<T>}`;
+type AnyPathFieldRef$1<T> = `$${PathType<T>}`;
+type SmartFieldRef<C, StrictRef> = [
+    StrictRef
+] extends [never] ? OpaqueError<"Invalid field reference"> : StrictRef;
+type SmartNumericFieldRef<C> = SmartFieldRef<C, NumericFieldRef<C> | NumericArrayFieldRef<C>>;
+type SmartAnyPathFieldRef<C> = SmartFieldRef<C, AnyPathFieldRef$1<C>>;
+type ArrayIn<C> = SmartFieldRef<C, ArrayFieldRef<C>> | readonly unknown[];
+type NumericIn<C> = SmartFieldRef<C, NumericFieldRef<C>> | (number & {});
+type BooleanIn<C> = SmartFieldRef<C, BooleanFieldRef<C>> | (boolean & {});
+type StringIn<C> = SmartFieldRef<C, StringFieldRef<C>> | (string & {});
+type DateIn<C> = SmartFieldRef<C, DateFieldRef<C>> | (Date & {});
+type ExpressionIn<C> = ArrayIn<C> | NumericIn<C> | BooleanIn<C> | StringIn<C> | DateIn<C>;
+type ValidExpressionValue<C, T> = T extends `$${infer _Path}` ? T extends SmartAnyPathFieldRef<C> ? T : OpaqueError<`Invalid field path: ${T & string}`> : T;
+type ElemType<T> = T extends readonly (infer E)[] ? E : unknown;
+type ExtractThis<C> = C extends {
+    $this: infer ThisType;
+} ? ThisType : never;
+type ExtractValue<C> = C extends {
+    $value: infer ValueType;
+} ? ValueType : never;
+type ExtractVars<C> = C extends {
+    $vars: infer Vars;
+} ? Vars : never;
+type ResolveType<C, T> = T extends "$$this" ? ExtractThis<C> : T extends `$$this.${infer P}` ? ResolvePathValue<ExtractThis<C>, P> : T extends "$$value" ? ExtractValue<C> : T extends `$$value.${infer P}` ? ResolvePathValue<ExtractValue<C>, P> : T extends "$$ROOT" | "$$CURRENT" ? C : T extends `$$${"DESCEND" | "PRUNE" | "KEEP" | "NOW" | "CLUSTER_TIME"}` ? T : T extends `$$${infer Var}.${infer P}` ? Var extends "ROOT" | "CURRENT" ? ResolvePathValue<C, P> : `$${Var}` extends keyof C ? ResolvePathValue<C[`$${Var}`], P> : `$$${Var}` extends keyof C ? ResolvePathValue<C[`$$${Var}`], P> : ExtractVars<C> extends infer Vars ? Var extends keyof Vars ? ResolvePathValue<Vars[Var & keyof Vars], P> : unknown : unknown : T extends `$$${infer Var}` ? `$${Var}` extends keyof C ? C[`$${Var}`] : T extends keyof C ? C[T] : ExtractVars<C> extends infer Vars ? Var extends keyof Vars ? Vars[Var & keyof Vars] : ExtractThis<C> : ExtractThis<C> : T extends `$${infer P}` ? ResolvePathValue<C, P> : T extends Ret<any, infer R> ? R : T extends object ? ResolveObject<C, T> : T;
+type ResolveObjectValue<C, V> = V extends Ret<any, infer R> ? R : V extends `$${string}` ? ResolveType<C, V> : V extends object ? ResolveObject<C, V> : V;
+type ResolveObject<C, Obj> = {
+    [K in keyof Obj]: ResolveObjectValue<C, Obj[K]>;
+};
+type ResolveSpecValue<C, V> = V extends Ret<any, infer R> ? R : V extends (c: any) => infer R ? R : V extends `$${string}` ? ResolveType<C, V> : V extends {
+    [key: `$${string}`]: any;
+} ? OpaqueError<"Invalid MongoDB operator object - use builder API instead (e.g., $.sum(...))"> & never : V extends object ? ResolveObject<C, V> : V;
+type ResolveSpec<C, Spec> = {
+    [K in keyof Spec]: ResolveSpecValue<C, Spec[K]>;
+};
+type DeepSpecInput<C, Spec> = Spec extends Ret<any, any> ? Spec : Spec extends ExprArg<C> ? ExprArgInput<C, Spec> : Spec extends readonly (infer E)[] ? readonly DeepSpecInput<C, E>[] : Spec extends object ? {
+    [K in keyof Spec]: DeepSpecInput<C, Spec[K]>;
+} : Spec;
+type DeepSpecResolve<C, Spec> = Spec extends Ret<any, infer R> ? R : Spec extends ExprArg<C> ? ResolveType<C, Spec> : Spec extends readonly (infer E)[] ? DeepSpecResolve<C, E>[] : Spec extends object ? {
+    [K in keyof Spec]: DeepSpecResolve<C, Spec[K]>;
+} : Spec;
+type SystemVarName = "ROOT" | "CURRENT" | "DESCEND" | "PRUNE" | "KEEP" | "NOW" | "CLUSTER_TIME";
+type ThisValueVarName = "this" | "value";
+type VarsRecord<C> = C extends {
+    $vars: infer Vars extends Dict<unknown>;
+} ? Vars : Dict<never>;
+type VarsFromContext<C> = Extract<keyof VarsRecord<C>, string>;
+type VarName<C> = SystemVarName | ThisValueVarName | VarsFromContext<C>;
+type VarRef<C> = VarName<C> extends infer V extends string ? `$$${V}` : never;
+type VarPathRef<C> = (C extends {
+    $this: infer ThisType;
+} ? `$$this.${PathType<ThisType>}` : never) | (C extends {
+    $value: infer ValueType;
+} ? `$$value.${PathType<ValueType>}` : never) | {
+    [K in VarsFromContext<C>]: `$$${K}.${PathType<VarsRecord<C>[K]>}`;
+}[VarsFromContext<C>] | (C extends unknown ? `$$ROOT.${PathType<C>}` | `$$CURRENT.${PathType<C>}` : never);
+type KnownVar<C, V extends string> = V extends SystemVarName ? true : V extends ThisValueVarName ? true : `$${V}` extends keyof C ? true : `$$${V}` extends keyof C ? true : C extends {
+    $vars: infer Vars;
+} ? V extends keyof Vars ? true : false : false;
+type NumericArg<C> = NumericIn<C> | SmartNumericFieldRef<C> | Ret<C, number> | Ret<C, number | null> | Ret<C, number[]> | VarRef<C> | VarPathRef<C>;
+type BooleanArg<C> = BooleanIn<C> | Ret<C, boolean> | VarRef<C> | VarPathRef<C>;
+type StringArg<C> = SmartFieldRef<C, StringFieldRef<C>> | Ret<C, string> | VarRef<C> | VarPathRef<C> | (string & {});
+type DateArg<C> = DateIn<C> | Ret<C, Date> | VarRef<C> | VarPathRef<C>;
+type ArrayLiteral$1<C> = readonly ExprArg<C>[] | ExprArg<C>[];
+type ArrayProjectionFieldRef<T> = `$${ArrayProjectionPath<T>}`;
+type ArrayFieldRefLike<T> = ArrayFieldRef<T> | ArrayProjectionFieldRef<T>;
+type ArrayArg<C> = SmartFieldRef<C, ArrayFieldRefLike<C>> | Ret<C, unknown[]> | VarRef<C> | VarPathRef<C> | ArrayLiteral$1<C>;
+type ExprArg<C> = SmartAnyPathFieldRef<C> | Ret<C> | VarRef<C> | VarPathRef<C> | number | boolean | Date | (string & {}) | null;
+type AccumulatorExprArg<C> = SmartAnyPathFieldRef<C> | Ret<C> | VarRef<C> | VarPathRef<C> | number | boolean | Date | null;
+type ValidInput<C, T, FieldRefType, TypeName extends string> = T extends VarRef<C> | VarPathRef<C> ? T : T extends Ret<any, any> ? T : T extends `$${string}` ? T extends SmartFieldRef<C, FieldRefType> ? T : TypeError<`"${T}" is not a valid ${TypeName} field`, `${TypeName} | ${TypeName} field ref`, T> : T;
+type ValidStringInput<C, T> = ValidInput<C, T, StringFieldRef<C>, "string">;
+type ValidNumericInput<C, T> = T extends number ? T : ValidInput<C, T, SmartNumericFieldRef<C>, "numeric">;
+type ValidBooleanInput<C, T> = T extends boolean ? T : ValidInput<C, T, BooleanFieldRef<C>, "boolean">;
+type ValidDateInput<C, T> = T extends Date ? T : ValidInput<C, T, DateFieldRef<C>, "date">;
+type ValidArrayInput<C, T> = T extends readonly unknown[] ? T : ValidInput<C, T, ArrayFieldRefLike<C>, "array">;
+type ValidExprArg<C, T> = T extends `$$${infer Var}.${string}` ? KnownVar<C, Var> extends true ? T : OpaqueError<`Invalid variable: $$${Var}`> : T extends VarRef<C> | VarPathRef<C> ? T : T extends `$${string}` ? ValidExpressionValue<C, T> : T;
+type ValidAccumulatorArg<C, T> = T extends `$$${infer Var}.${string}` ? KnownVar<C, Var> extends true ? T : OpaqueError<`Invalid variable: $$${Var}`> : T extends VarRef<C> | VarPathRef<C> ? T : T extends `$${string}` ? ValidExpressionValue<C, T> : T extends string ? OpaqueError<`Bare string "${T}" is not valid in accumulator position — did you mean "$${T}"?`> : T;
+type StringArgInput<C, T extends StringArg<C>> = ValidStringInput<C, T>;
+type NumericArgInput<C, T extends NumericArg<C>> = ValidNumericInput<C, T>;
+type BooleanArgInput<C, T extends BooleanArg<C>> = ValidBooleanInput<C, T>;
+type DateArgInput<C, T extends DateArg<C>> = ValidDateInput<C, T>;
+type ArrayArgInput<C, T extends ArrayArg<C>> = ValidArrayInput<C, T>;
+type ExprArgInput<C, T extends ExprArg<C>> = ValidExprArg<C, T>;
+type ExprArgInputs<C, T extends readonly ExprArg<C>[]> = {
+    [K in keyof T]: ExprArgInput<C, T[K]>;
+};
+type AccumulatorArgInput<C, T extends AccumulatorExprArg<C>> = ValidAccumulatorArg<C, T>;
+type AccumulatorArgInputs<C, T extends readonly AccumulatorExprArg<C>[]> = {
+    [K in keyof T]: AccumulatorArgInput<C, T[K]>;
+};
+type ComparisonOps<T> = {
+    $eq?: T;
+    $ne?: T;
+    $exists?: boolean;
+    $type?: BSONTypeAlias;
+};
+/** Adds $not wrapper to any match operator base type */
+type WithNot<T> = T & {
+    $not?: T;
+};
+type MatchNumericIn = number & {};
+type MatchStringIn = string & {};
+type MatchDateIn = Date & {};
+type MatchBooleanIn = boolean & {};
+type NumericMatchOpsBase = ComparisonOps<MatchNumericIn> & {
+    $gt?: MatchNumericIn;
+    $gte?: MatchNumericIn;
+    $lt?: MatchNumericIn;
+    $lte?: MatchNumericIn;
+    $in?: MatchNumericIn[];
+    $nin?: MatchNumericIn[];
+    $mod?: [number, number];
+    $bitsAllClear?: number | number[];
+    $bitsAllSet?: number | number[];
+    $bitsAnyClear?: number | number[];
+    $bitsAnySet?: number | number[];
+};
+type NumericMatchOperators = WithNot<NumericMatchOpsBase>;
+type StringRegexOps = {
+    $regex: string | RegExp;
+    $options?: string;
+} | {
+    $regex?: undefined;
+    $options?: undefined;
+};
+type StringMatchOpsBase = ComparisonOps<MatchStringIn> & {
+    $gt?: MatchStringIn;
+    $gte?: MatchStringIn;
+    $lt?: MatchStringIn;
+    $lte?: MatchStringIn;
+    $in?: MatchStringIn[];
+    $nin?: MatchStringIn[];
+} & StringRegexOps;
+type StringMatchOperators = WithNot<StringMatchOpsBase>;
+type BooleanMatchOpsBase = ComparisonOps<MatchBooleanIn>;
+type BooleanMatchOperators = WithNot<BooleanMatchOpsBase>;
+type ElemMatchValue<E> = {
+    $elemMatch: ValidMatchFilterWithBuilder<E>;
+};
+type ArrayMatchOpsBase<E> = {
+    $size?: number;
+    $all?: readonly E[];
+    $elemMatch?: ElemMatchValue<E>;
+    $in?: readonly E[];
+    $nin?: readonly E[];
+    $exists?: boolean;
+    $type?: BSONTypeAlias;
+};
+type ArrayMatchOperators<E> = WithNot<ArrayMatchOpsBase<E>>;
+type GeoMatchOpsBase<C> = {
+    $geoIntersects?: {
+        $geometry: Geometry;
+    };
+    $geoWithin?: {
+        $geometry?: Geometry;
+        $box?: [[number, number], [number, number]];
+        $polygon?: [number, number][];
+        $center?: [[number, number], number];
+        $centerSphere?: [[number, number], number];
+    };
+    $near?: {
+        $geometry: Geometry;
+        $maxDistance?: number;
+        $minDistance?: number;
+    };
+    $nearSphere?: {
+        $geometry: Geometry;
+        $maxDistance?: number;
+        $minDistance?: number;
+    };
+};
+type GeoMatchOperators<C> = WithNot<GeoMatchOpsBase<C>>;
+type DateMatchOpsBase = ComparisonOps<MatchDateIn> & {
+    $gt?: MatchDateIn;
+    $gte?: MatchDateIn;
+    $lt?: MatchDateIn;
+    $lte?: MatchDateIn;
+};
+type DateMatchOperators = WithNot<DateMatchOpsBase>;
+type ValidMatchFilterWithBuilder<C> = {
+    [K in keyof C]?: C[K] | Ret<C, C[K]> | (C[K] extends number ? NumericMatchOperators : C[K] extends string ? StringMatchOperators : C[K] extends boolean ? BooleanMatchOperators : C[K] extends Date ? DateMatchOperators : C[K] extends readonly (infer E)[] ? E | Ret<C, E> | ArrayMatchOperators<E> : C[K] extends Geometry ? GeoMatchOperators<C> : ComparisonOps<never>);
+} & {
+    $expr?: BooleanArg<C>;
+    $or?: ValidMatchFilterWithBuilder<C>[];
+    $and?: ValidMatchFilterWithBuilder<C>[];
+    $nor?: ValidMatchFilterWithBuilder<C>[];
+    $text?: {
+        $search: string;
+        $language?: string;
+        $caseSensitive?: boolean;
+        $diacriticSensitive?: boolean;
+    };
+    /** @deprecated $where is a MongoDB escape hatch and bypasses type safety. */
+    $where?: string | ((...args: any[]) => boolean);
+    $jsonSchema?: JSONSchema;
+    $comment?: string;
+};
+type TimeUnit = "year" | "quarter" | "month" | "week" | "day" | "hour" | "minute" | "second" | "millisecond";
+type WindowBoundary = number | "current" | "unbounded";
+type WindowSpec = {
+    documents: [WindowBoundary, WindowBoundary];
+} | {
+    range: [WindowBoundary, WindowBoundary];
+    unit: TimeUnit;
+};
+
+type BuilderMode = "expression" | "accumulator";
+type ResolveTypes<C, T extends unknown[]> = {
+    [K in keyof T]: ResolveType<C, T[K]>;
+};
+type DeepObjectExpr<C> = ExprArg<C> | {
+    [K in string]: DeepObjectExpr<C>;
+} | readonly DeepObjectExpr<C>[];
+type DeepObjectInput<C, T> = T extends ExprArg<C> ? ExprArgInput<C, T> : T extends readonly (infer E)[] ? readonly DeepObjectInput<C, E>[] : T extends object ? {
+    [K in keyof T]: DeepObjectInput<C, T[K]>;
+} : T;
+type DeepObjectResolve<C, T> = T extends Ret<any, infer R> ? R : T extends ExprArg<C> ? ResolveType<C, T> : T extends readonly (infer E)[] ? DeepObjectResolve<C, E>[] : T extends object ? {
+    [K in keyof T]: DeepObjectResolve<C, T[K]>;
+} : T;
+type ArrayToObjectResult<Elem> = Elem extends {
+    k: infer K;
+    v: infer V;
+} ? [
+    K
+] extends [string] ? Record<K, V> : Dict<unknown> : Dict<unknown>;
+type UnaryNumericOp<C> = <const T extends NumericArg<C>>(arg: T & NumericArgInput<C, T>) => Ret<C, number>;
+type BinaryNumericOp<C> = <const L extends NumericArg<C>, const R extends NumericArg<C>>(left: L & NumericArgInput<C, L>, right: R & NumericArgInput<C, R>) => Ret<C, number>;
+type UnaryStringToNumber<C> = <const T extends StringArg<C>>(exp: StringArgInput<C, T>) => Ret<C, number>;
+type UnaryStringToString<C> = <const T extends StringArg<C>>(exp: StringArgInput<C, T>) => Ret<C, string>;
+type BinaryStringToNumber<C> = <const L extends StringArg<C>, const R extends StringArg<C>>(left: StringArgInput<C, L>, right: StringArgInput<C, R>) => Ret<C, -1 | 0 | 1>;
+type UnaryDateToNumber<C> = <const T extends DateArg<C>>(exp: T & DateArgInput<C, T>) => Ret<C, number>;
+type UnaryArrayToBool<C> = <const T extends ArrayArg<C>>(exp: T & ArrayArgInput<C, T>) => Ret<C, boolean>;
+type UnaryTypeConversion<C, Output> = <const T extends ExprArg<C>>(exp: ExprArgInput<C, T>) => Ret<C, NullishResult<C, T, Output>>;
+type HasNullish<T> = [Extract<T, null | undefined>] extends [never] ? false : true;
+type NullishResult<C, T, Output> = HasNullish<ResolveType<C, T>> extends true ? Output | null : Output;
+type NullishResultFromArgs<C, T extends readonly ExprArg<C>[], Output> = HasNullish<ResolveType<C, T[number]>> extends true ? Output | null : Output;
+type ConvertTo = "double" | "string" | "objectId" | "bool" | "date" | "int" | "long" | "decimal";
+type ConvertOutput<To extends ConvertTo> = To extends "double" | "int" ? number : To extends "long" ? number : To extends "decimal" ? Decimal128 : To extends "string" ? string : To extends "bool" ? boolean : To extends "objectId" ? ObjectId : Date;
+type BinaryArrayOp<C> = <const A extends ArrayArg<C>, const B extends ArrayArg<C>>(left: A & ArrayArgInput<C, A>, right: B & ArrayArgInput<C, B>) => Ret<C, boolean>;
+type UnaryArrayToNumber<C> = <const T extends ArrayArg<C>>(exp: T & ArrayArgInput<C, T>) => Ret<C, number>;
+type ComparisonOp<C> = <const L extends ExprArg<C>, const R extends CompatibleArg<C, ResolveType<C, L>>>(left: L extends `$${infer Rest}` ? Rest extends `$${string}` ? L : L extends AnyPathFieldRef<C> ? L : never : L, right: R extends `$${infer Rest}` ? Rest extends `$${string}` ? R : ResolveType<C, R> extends ResolveType<C, L> ? R : never : R) => Ret<C, boolean>;
+type VarargsBooleanOp<C> = <const T extends BooleanArg<C>[]>(...args: {
+    [K in keyof T]: T[K] & BooleanArgInput<C, T[K]>;
+}) => Ret<C, boolean>;
+type VarargsNumericOp<C> = <const T extends NumericArg<C>[]>(...args: T extends readonly NumericArg<C>[] ? T : never) => Ret<C, number>;
+type NumericArgs<C> = readonly [NumericArg<C>, NumericArg<C>, ...NumericArg<C>[]];
+type NumericArgsInput<C, T extends readonly NumericArg<C>[]> = {
+    [K in keyof T]: NumericArgInput<C, T[K]>;
+};
+type AddOp<C> = {
+    <const T extends NumericArgs<C>>(...args: NumericArgsInput<C, T>): Ret<C, number>;
+    <const D extends DateArg<C>, const T extends readonly [NumericArg<C>, ...NumericArg<C>[]]>(date: DateArgInput<C, D>, ...args: NumericArgsInput<C, T>): Ret<C, Date>;
+    <const T extends readonly [NumericArg<C>, ...NumericArg<C>[]], const D extends DateArg<C>>(...args: [...NumericArgsInput<C, T>, DateArgInput<C, D>]): Ret<C, Date>;
+};
+type SubtractOp<C> = {
+    <const L extends DateArg<C>, const R extends DateArg<C>>(left: DateArgInput<C, L>, right: DateArgInput<C, R>): Ret<C, number>;
+    <const L extends DateArg<C>, const R extends NumericArg<C>>(left: DateArgInput<C, L>, right: NumericArgInput<C, R>): Ret<C, Date>;
+    <const L extends NumericArg<C>, const R extends NumericArg<C>>(left: NumericArgInput<C, L>, right: NumericArgInput<C, R>): Ret<C, number>;
+};
+type SortPath<C> = PathType<C> | `_id.${string}`;
+type SortBySpec<C> = Partial<Record<SortPath<C>, 1 | -1>> | {
+    $meta: "textScore" | "searchScore";
+} | (Partial<Record<SortPath<C>, 1 | -1>> & {
+    $meta: "textScore" | "searchScore";
+});
+type ArrayLiteral<C> = readonly ExprArg<C>[] | ExprArg<C>[];
+type FirstNotNil<T extends unknown[]> = T extends [infer First, ...infer Rest] ? First extends null | undefined ? FirstNotNil<Rest> : First : never;
+type MergeTwo<A, B> = [
+    A
+] extends [null | undefined] ? B : [B] extends [null | undefined] ? A : MergeWithIndexOverride<A, B>;
+type MergeObjects<C, Objs extends unknown[], Acc = null> = Objs extends [infer First, ...infer Rest] ? MergeObjects<C, Rest, MergeTwo<ResolveType<C, First>, Acc>> : Acc;
+type MergeVars<C, Vars extends Dict<unknown>> = C extends {
+    $vars: infer Existing extends Dict<unknown>;
+} ? SimplifyWritable<Omit<C, "$vars"> & {
+    $vars: SimplifyWritable<Existing & Vars>;
+}> : SimplifyWritable<C & {
+    $vars: Vars;
+}>;
+type ResolveVarSpec<C, V extends Dict<ExprArg<C>>> = {
+    [K in keyof V]: ResolveType<C, V[K]>;
+};
+type ContextWithThis<C, ThisType, As extends string | undefined = undefined> = As extends string ? MergeVars<SimplifyWritable<C & {
+    $this: ThisType;
+}>, Record<As, ThisType>> : SimplifyWritable<C & {
+    $this: ThisType;
+}>;
+type ContextWithThisAndValue<C, ThisType, ValueType> = SimplifyWritable<C & {
+    $this: ThisType;
+    $value: ValueType;
+}>;
+type ConcatStrings<T extends readonly unknown[]> = T extends readonly [infer First, ...infer Rest] ? First extends string ? Rest extends readonly string[] ? `${First}${ConcatStrings<Rest>}` : string : string : "";
+type CompatibleArg<C, T> = [
+    T
+] extends [unknown] ? [
+    unknown
+] extends [T] ? ExprArg<C> : CompatibleArgKnown<C, T> : CompatibleArgKnown<C, T>;
+type CompatibleArgKnown<C, T> = Ret<C, T> | `$$${string}` | (T extends boolean ? BooleanArg<C> : T extends number ? NumericArg<C> : T extends string ? `$${string}` | Ret<C, string> | `$$${string}` : T extends Date ? DateArg<C> : never) | (T extends boolean ? boolean : T extends number ? number : T extends string ? string & {} : T extends Date ? Date : T extends null | undefined ? null | undefined : never) | (T extends (infer E)[] ? CompatibleArg<C, E> | ArrayArg<C> : never);
+type AnyPathFieldRef<C> = `$${string}`;
+declare class Ret<out Context = unknown, T = unknown> {
+    readonly __fn: unknown;
+    readonly __minVersion: string;
+    readonly __context: Context;
+    readonly __type: SimplifyWritable<T>;
+    readonly __tag: "Ret";
+    constructor(__fn: unknown, __minVersion?: string);
+}
+type AnyRet = Ret<never, never>;
+declare class BaseBuilder<C, Mode extends BuilderMode = "expression"> {
+    _resolve(value: unknown): unknown;
+    protected id: (op: string) => (arg: unknown) => AnyRet;
+    protected varargs: (op: string) => (...args: unknown[]) => AnyRet;
+    protected flexible: (op: string) => (...args: unknown[]) => AnyRet;
+    protected options: (op: string) => (options: unknown) => AnyRet;
+    protected nullary: (op: string) => () => AnyRet;
+    pipe: PipelineBuilder<C>;
+    elemMatch: <const E>(filter: ($: ExprBuilder<E>) => ValidMatchFilterWithBuilder<E>) => {
+        $elemMatch: ValidMatchFilterWithBuilder<E>;
+    };
+    add: AddOp<C>;
+    subtract: SubtractOp<C>;
+    multiply: VarargsNumericOp<C>;
+    divide: BinaryNumericOp<C>;
+    mod: BinaryNumericOp<C>;
+    abs: UnaryNumericOp<C>;
+    ceil: UnaryNumericOp<C>;
+    floor: UnaryNumericOp<C>;
+    ln: UnaryNumericOp<C>;
+    log: BinaryNumericOp<C>;
+    log10: UnaryNumericOp<C>;
+    pow: BinaryNumericOp<C>;
+    sqrt: UnaryNumericOp<C>;
+    trunc: <const T extends NumericArg<C>, const P extends NumericArg<C>>(num: T & NumericArgInput<C, T>, place?: P & NumericArgInput<C, P>) => Ret<C, number>;
+    round: <const T extends NumericArg<C>, const P extends NumericArg<C>>(num: T & NumericArgInput<C, T>, place?: P & NumericArgInput<C, P>) => Ret<C, number>;
+    exp: UnaryNumericOp<C>;
+    rand: () => Ret<C, number>;
+    arrayElemAt: <const A extends ArrayArg<C>, const I extends NumericArg<C>>(array: A & ArrayArgInput<C, A>, index: I & NumericArgInput<C, I>) => Ret<C, ElemType<ResolveType<C, A>>>;
+    arrayToObject: <const T extends ArrayArg<C>>(exp: T & ArrayArgInput<C, T>) => Ret<C, ArrayToObjectResult<ElemType<ResolveType<C, T>>>>;
+    concatArrays: <const T extends ArrayArg<C>[]>(...args: {
+        [K in keyof T]: T[K] & ArrayArgInput<C, T[K]>;
+    }) => Ret<C, ElemType<ResolveType<C, T[number]>>[]>;
+    /** Selects a subset of array elements that match a condition.
+     * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/filter/ */
+    filter: {
+        <const I extends ArrayArg<C>, const As extends string | undefined = undefined, const L extends NumericArg<C> = NumericArg<C>>(options: {
+            input: I & ArrayArgInput<C, I>;
+            cond: ($: BaseBuilder<ContextWithThis<C, ElemType<ResolveType<C, I>>, As>>) => BooleanArg<ContextWithThis<C, ElemType<ResolveType<C, I>>, As>>;
+            as?: As;
+            limit?: L & NumericArgInput<C, L>;
+        }): Ret<C, ResolveType<C, I>>;
+        <const I extends ArrayArg<C>, const As extends string | undefined = undefined, const B extends BooleanArg<ContextWithThis<C, ElemType<ResolveType<C, I>>, As>> = BooleanArg<ContextWithThis<C, ElemType<ResolveType<C, I>>, As>>, const L extends NumericArg<C> = NumericArg<C>>(options: {
+            input: I & ArrayArgInput<C, I>;
+            cond: B;
+            as?: As;
+            limit?: L & NumericArgInput<C, L>;
+        }): Ret<C, CallbackOnlyError<"filter">>;
+    };
+    first: <const T extends AccumulatorExprArg<C>>(exp: AccumulatorArgInput<C, T>) => Ret<C, Mode extends "accumulator" ? ResolveType<C, T> : ResolveType<C, T> extends readonly (infer E)[] ? E | null : ResolveType<C, T> | null>;
+    in: <const V extends ExprArg<C>, const A extends ArrayArg<C>>(value: ExprArgInput<C, V>, array: A & ArrayArgInput<C, A>) => Ret<C, boolean>;
+    indexOfArray: <const A extends ArrayArg<C>, const S extends ExprArg<C>, const N extends NumericArg<C>>(options: {
+        array: A & ArrayArgInput<C, A>;
+        search: ExprArgInput<C, S>;
+        start?: N & NumericArgInput<C, N>;
+        end?: N & NumericArgInput<C, N>;
+    }) => Ret<C, number>;
+    isArray: <const T extends ExprArg<C>>(exp: ExprArgInput<C, T>) => Ret<C, boolean>;
+    last: <const T extends AccumulatorExprArg<C>>(exp: AccumulatorArgInput<C, T>) => Ret<C, Mode extends "accumulator" ? ResolveType<C, T> : ResolveType<C, T> extends readonly (infer E)[] ? E | null : ResolveType<C, T> | null>;
+    /** Applies an expression to each element of an array and returns the results.
+     * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/map/ */
+    map: {
+        <const A extends ArrayArg<C>, const As extends string | undefined = undefined, const R extends DeepObjectExpr<ContextWithThis<C, ElemType<ResolveType<C, A>>, As>> = DeepObjectExpr<ContextWithThis<C, ElemType<ResolveType<C, A>>, As>>>(options: {
+            input: A & ArrayArgInput<C, A>;
+            as?: As;
+            in: ($: BaseBuilder<ContextWithThis<C, ElemType<ResolveType<C, A>>, As>>) => R;
+        }): Ret<C, DeepObjectResolve<ContextWithThis<C, ElemType<ResolveType<C, A>>, As>, R>[]>;
+        <const A extends ArrayArg<C>, const As extends string | undefined = undefined, const R extends DeepObjectExpr<ContextWithThis<C, ElemType<ResolveType<C, A>>, As>> = DeepObjectExpr<ContextWithThis<C, ElemType<ResolveType<C, A>>, As>>>(options: {
+            input: A & ArrayArgInput<C, A>;
+            as?: As;
+            in: DeepObjectInput<ContextWithThis<C, ElemType<ResolveType<C, A>>, As>, R>;
+        }): Ret<C, DeepObjectResolve<ContextWithThis<C, ElemType<ResolveType<C, A>>, As>, R>[]>;
+    };
+    maxN: <const T extends ArrayArg<C>, const N extends NumericArg<C>>(options: {
+        input: T & ArrayArgInput<C, T>;
+        n: N & NumericArgInput<C, N>;
+    }) => Ret<C, Mode extends "accumulator" ? ResolveType<C, T>[] : ResolveType<C, T>>;
+    minN: <const T extends ArrayArg<C>, const N extends NumericArg<C>>(options: {
+        input: T & ArrayArgInput<C, T>;
+        n: N & NumericArgInput<C, N>;
+    }) => Ret<C, Mode extends "accumulator" ? ResolveType<C, T>[] : ResolveType<C, T>>;
+    firstN: <const T extends ArrayArg<C>, const N extends NumericArg<C>>(options: {
+        input: T & ArrayArgInput<C, T>;
+        n: N & NumericArgInput<C, N>;
+    }) => Ret<C, Mode extends "accumulator" ? ResolveType<C, T>[] : ResolveType<C, T>>;
+    lastN: <const T extends ArrayArg<C>, const N extends NumericArg<C>>(options: {
+        input: T & ArrayArgInput<C, T>;
+        n: N & NumericArgInput<C, N>;
+    }) => Ret<C, Mode extends "accumulator" ? ResolveType<C, T>[] : ResolveType<C, T>>;
+    objectToArray: <const T extends ExprArg<C>>(expression: ExprArgInput<C, T>) => Ret<C, {
+        k: string;
+        v: ResolveType<C, T> extends Dict<infer V> ? V : unknown;
+    }[]>;
+    range: <const S extends NumericArg<C>, const E extends NumericArg<C>, const St extends NumericArg<C> = never>(start: S & NumericArgInput<C, S>, end: E & NumericArgInput<C, E>, step?: St & NumericArgInput<C, St>) => Ret<C, number[]>;
+    /** Applies an expression to each element of an array, accumulating into a single value.
+     * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/reduce/ */
+    reduce: {
+        <const A extends ArrayArg<C>, const Init extends ExprArg<C> | ArrayIn<C>, const R extends Exclude<ExprArg<ContextWithThisAndValue<C, ElemType<ResolveType<C, A>>, ResolveType<C, Init>>>, string>>(options: {
+            input: A & ArrayArgInput<C, A>;
+            initialValue: Init;
+            in: ($: BaseBuilder<ContextWithThisAndValue<C, ElemType<ResolveType<C, A>>, ResolveType<C, Init>>>) => R;
+        }): Ret<C, ResolveType<ContextWithThisAndValue<C, ElemType<ResolveType<C, A>>, ResolveType<C, Init>>, R>>;
+        <const A extends ArrayArg<C>, const Init extends ExprArg<C> | ArrayIn<C>, const R>(options: {
+            input: A & ArrayArgInput<C, A>;
+            initialValue: Init;
+            in: R;
+        }): Ret<C, CallbackOnlyError<"reduce">>;
+    };
+    reverseArray: <const T extends ArrayArg<C>>(exp: T & ArrayArgInput<C, T>) => Ret<C, ResolveType<C, T>>;
+    size: UnaryArrayToNumber<C>;
+    slice: <const A extends ArrayArg<C>, const N extends NumericArg<C>>(array: A & ArrayArgInput<C, A>, n: N & NumericArgInput<C, N>, position?: N & NumericArgInput<C, N>) => Ret<C, ResolveType<C, A>>;
+    sortArray: <const T extends {
+        input: ArrayArg<C>;
+        sortBy: Dict<1 | -1> | 1 | -1;
+    }>(options: T & {
+        input: T["input"] & ArrayArgInput<C, T["input"]>;
+    }) => Ret<C, ResolveType<C, T["input"]>>;
+    zip: {
+        <const T extends readonly ArrayArg<C>[]>(options: {
+            inputs: readonly [...T];
+            useLongestLength: true;
+            defaults: Readonly<{
+                [K in keyof T]: ElemType<ResolveType<C, T[K]>>;
+            }>;
+        }): Ret<C, {
+            -readonly [K in keyof T]: ElemType<ResolveType<C, T[K]>>;
+        }[]>;
+        <const T extends readonly ArrayArg<C>[]>(options: {
+            inputs: readonly [...T];
+            useLongestLength: true;
+            defaults?: Readonly<{
+                [K in keyof T]?: ElemType<ResolveType<C, T[K]>>;
+            }>;
+        }): Ret<C, {
+            -readonly [K in keyof T]: ElemType<ResolveType<C, T[K]>> | null;
+        }[]>;
+        <const T extends readonly ArrayArg<C>[]>(options: {
+            inputs: readonly [...T];
+            useLongestLength?: false;
+            defaults?: never;
+        }): Ret<C, {
+            -readonly [K in keyof T]: ElemType<ResolveType<C, T[K]>>;
+        }[]>;
+    };
+    cmp: <const T extends ExprArg<C>>(left: ExprArgInput<C, T>, right: ExprArgInput<C, T>) => Ret<C, -1 | 0 | 1>;
+    eq: ComparisonOp<C>;
+    gt: ComparisonOp<C>;
+    gte: ComparisonOp<C>;
+    lt: ComparisonOp<C>;
+    lte: ComparisonOp<C>;
+    ne: ComparisonOp<C>;
+    and: VarargsBooleanOp<C>;
+    or: VarargsBooleanOp<C>;
+    nor: VarargsBooleanOp<C>;
+    not: <const T extends ExprArg<C>>(exp: ExprArgInput<C, T>) => Ret<C, boolean>;
+    /** Evaluates a boolean expression and returns one of two values.
+     * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/cond/ */
+    cond: <const B extends BooleanArg<C>, const T extends ExprArg<C>, const E extends ExprArg<C>>(options: {
+        if: B & BooleanArgInput<C, B>;
+        then: T & ExprArgInput<C, T>;
+        else: E & ExprArgInput<C, E>;
+    }) => Ret<C, ResolveType<C, T> | ResolveType<C, E>>;
+    /** Returns the first non-null/non-missing expression (null coalescing).
+     * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/ifNull/ */
+    ifNull: <const T extends ExprArg<C>[]>(...args: {
+        [K in keyof T]: T[K] & ExprArgInput<C, T[K]>;
+    }) => Ret<C, FirstNotNil<ResolveTypes<C, T>>>;
+    /** Evaluates a series of case expressions, returning the value of the first match.
+     * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/switch/ */
+    switch: <const Br extends readonly {
+        case: BooleanArg<C>;
+        then: ExprArg<C>;
+    }[], const D extends ExprArg<C>>(options: {
+        branches: Br;
+        default: D;
+    }) => Ret<C, ResolveType<C, Br[number]["then"]> | ResolveType<C, D>>;
+    concat: <const T extends StringArg<C>[]>(...args: {
+        [K in keyof T]: StringArgInput<C, T[K]>;
+    }) => Ret<C, ConcatStrings<{
+        [K in keyof T]: ResolveType<C, T[K]>;
+    }>>;
+    indexOfBytes: <const S extends StringArg<C>, const Sub extends StringArg<C>, const N extends NumericArg<C>>(string: StringArgInput<C, S>, substring: StringArgInput<C, Sub>, start?: N & NumericArgInput<C, N>, end?: N & NumericArgInput<C, N>) => Ret<C, number>;
+    indexOfCP: <const S extends StringArg<C>, const Sub extends StringArg<C>, const N extends NumericArg<C>>(string: StringArgInput<C, S>, substring: StringArgInput<C, Sub>, start?: N & NumericArgInput<C, N>, end?: N & NumericArgInput<C, N>) => Ret<C, number>;
+    ltrim: <const T extends StringArg<C>>(options: {
+        input: StringArgInput<C, T>;
+        chars?: StringArgInput<C, StringArg<C>>;
+    }) => Ret<C, string>;
+    regexFind: <const T extends StringArg<C>>(options: {
+        input: StringArgInput<C, T>;
+        regex: StringArgInput<C, StringArg<C>> | RegExp;
+        options?: StringArgInput<C, StringArg<C>>;
+    }) => Ret<C, {
+        match: string;
+        idx: number;
+        captures: string[];
+    } | null>;
+    regexFindAll: <const T extends StringArg<C>>(options: {
+        input: StringArgInput<C, T>;
+        regex: StringArgInput<C, StringArg<C>> | RegExp;
+        options?: StringArgInput<C, StringArg<C>>;
+    }) => Ret<C, {
+        match: string;
+        idx: number;
+        captures: string[];
+    }[]>;
+    regexMatch: <const T extends StringArg<C>>(options: {
+        input: StringArgInput<C, T>;
+        regex: StringArgInput<C, StringArg<C>> | RegExp;
+        options?: StringArgInput<C, StringArg<C>>;
+    }) => Ret<C, boolean>;
+    replaceAll: <const T extends StringArg<C>>(options: {
+        input: StringArgInput<C, T>;
+        find: StringArgInput<C, StringArg<C>>;
+        replacement: StringArgInput<C, StringArg<C>>;
+    }) => Ret<C, string>;
+    replaceOne: <const T extends StringArg<C>>(options: {
+        input: StringArgInput<C, T>;
+        find: StringArgInput<C, StringArg<C>>;
+        replacement: StringArgInput<C, StringArg<C>>;
+    }) => Ret<C, string>;
+    rtrim: <const T extends StringArg<C>>(options: {
+        input: StringArgInput<C, T>;
+        chars?: StringArgInput<C, StringArg<C>>;
+    }) => Ret<C, string>;
+    split: <const S extends StringArg<C>, const D extends StringArg<C>>(string: StringArgInput<C, S>, delimiter: StringArgInput<C, D>) => Ret<C, string[]>;
+    strcasecmp: BinaryStringToNumber<C>;
+    strLenBytes: UnaryStringToNumber<C>;
+    strLenCP: UnaryStringToNumber<C>;
+    substr: <const S extends StringArg<C>, const N extends NumericArg<C>>(string: StringArgInput<C, S>, start: (N & NumericArgInput<C, N>) | number, length: (N & NumericArgInput<C, N>) | number) => Ret<C, string>;
+    substrBytes: <const S extends StringArg<C>, const N extends NumericArg<C>>(string: StringArgInput<C, S>, start: N & NumericArgInput<C, N>, length: N & NumericArgInput<C, N>) => Ret<C, string>;
+    substrCP: <const S extends StringArg<C>, const N extends NumericArg<C>>(string: StringArgInput<C, S>, start: N & NumericArgInput<C, N>, length: N & NumericArgInput<C, N>) => Ret<C, string>;
+    toLower: UnaryStringToString<C>;
+    toUpper: UnaryStringToString<C>;
+    trim: <const T extends StringArg<C>>(options: {
+        input: StringArgInput<C, T>;
+        chars?: StringArgInput<C, StringArg<C>>;
+    }) => Ret<C, string>;
+    allElementsTrue: UnaryArrayToBool<C>;
+    anyElementTrue: UnaryArrayToBool<C>;
+    setDifference: <const A extends ArrayArg<C>, const B extends ArrayArg<C>>(left: A & ArrayArgInput<C, A>, right: B & ArrayArgInput<C, B>) => Ret<C, ElemType<ResolveType<C, A>>[]>;
+    setEquals: <const T extends ArrayArg<C>[]>(...args: {
+        [K in keyof T]: T[K] & ArrayArgInput<C, T[K]>;
+    }) => Ret<C, boolean>;
+    setIntersection: <const T extends ArrayArg<C>[]>(...args: {
+        [K in keyof T]: T[K] & ArrayArgInput<C, T[K]>;
+    }) => Ret<C, ElemType<ResolveType<C, T[number]>>[]>;
+    setIsSubset: BinaryArrayOp<C>;
+    setUnion: <const T extends (ArrayArg<C> | ArrayLiteral<C>)[]>(...args: T) => Ret<C, ElemType<ResolveType<C, T[number]>>[]>;
+    dateAdd: <const T extends DateArg<C>, const N extends NumericArg<C>>(options: {
+        startDate: T & DateArgInput<C, T>;
+        unit: string;
+        amount: N & NumericArgInput<C, N>;
+        timezone?: StringArg<C>;
+    }) => Ret<C, Date>;
+    dateDiff: <const S extends DateArg<C>, const E extends DateArg<C>>(options: {
+        startDate: S & DateArgInput<C, S>;
+        endDate: E & DateArgInput<C, E>;
+        unit: string;
+        timezone?: StringArg<C>;
+        startOfWeek?: string;
+    }) => Ret<C, number>;
+    dateFromParts: <const T>(opts: T) => Ret<C, Date>;
+    dateFromString: <const D extends StringArg<C>>(options: {
+        dateString: D;
+        format?: StringArg<C>;
+        timezone?: StringArg<C>;
+        onError?: ExprArgInput<C, ExprArg<C>>;
+        onNull?: ExprArgInput<C, ExprArg<C>>;
+    }) => Ret<C, Date>;
+    dateSubtract: <const T extends DateArg<C>, const N extends NumericArg<C>>(options: {
+        startDate: T & DateArgInput<C, T>;
+        unit: string;
+        amount: N & NumericArgInput<C, N>;
+        timezone?: StringArg<C>;
+    }) => Ret<C, Date>;
+    dateToParts: <const T extends DateArg<C>, const I extends boolean | undefined = undefined>(options: {
+        date: T & DateArgInput<C, T>;
+        timezone?: StringArg<C>;
+        iso8601?: I;
+    }) => Ret<C, I extends true ? {
+        isoWeekYear: number;
+        isoWeek: number;
+        isoDayOfWeek: number;
+        hour: number;
+        minute: number;
+        second: number;
+        millisecond: number;
+    } : {
+        year: number;
+        month: number;
+        day: number;
+        hour: number;
+        minute: number;
+        second: number;
+        millisecond: number;
+    }>;
+    dateToString: <const T extends DateArg<C>>(options: {
+        date: T & DateArgInput<C, T>;
+        format?: StringArg<C>;
+        timezone?: StringArg<C>;
+        onNull?: ExprArgInput<C, ExprArg<C>>;
+    }) => Ret<C, string>;
+    dateTrunc: <const T extends DateArg<C>, const N extends NumericArg<C>>(options: {
+        date: T & DateArgInput<C, T>;
+        unit: string;
+        binSize?: N & NumericArgInput<C, N>;
+        timezone?: StringArg<C>;
+        startOfWeek?: string;
+    }) => Ret<C, Date>;
+    dayOfMonth: UnaryDateToNumber<C>;
+    dayOfWeek: UnaryDateToNumber<C>;
+    dayOfYear: UnaryDateToNumber<C>;
+    hour: UnaryDateToNumber<C>;
+    isoDayOfWeek: UnaryDateToNumber<C>;
+    isoWeek: UnaryDateToNumber<C>;
+    isoWeekYear: UnaryDateToNumber<C>;
+    millisecond: UnaryDateToNumber<C>;
+    minute: UnaryDateToNumber<C>;
+    month: UnaryDateToNumber<C>;
+    second: UnaryDateToNumber<C>;
+    week: UnaryDateToNumber<C>;
+    year: UnaryDateToNumber<C>;
+    convert: {
+        <const I extends ExprArg<C>, const To extends ConvertTo, const ON extends ExprArg<C>>(options: {
+            input: ExprArgInput<C, I>;
+            to: To;
+            onError?: ExprArgInput<C, ExprArg<C>>;
+            onNull: ExprArgInput<C, ON>;
+        }): Ret<C, ConvertOutput<To> | ResolveType<C, ON>>;
+        <const I extends ExprArg<C>, const To extends ConvertTo>(options: {
+            input: ExprArgInput<C, I>;
+            to: To;
+            onError?: ExprArgInput<C, ExprArg<C>>;
+            onNull?: undefined;
+        }): Ret<C, NullishResult<C, I, ConvertOutput<To>>>;
+    };
+    isNumber: UnaryTypeConversion<C, boolean>;
+    toBool: UnaryTypeConversion<C, boolean>;
+    toDate: UnaryTypeConversion<C, Date>;
+    toDecimal: UnaryTypeConversion<C, Decimal128>;
+    toDouble: UnaryTypeConversion<C, number>;
+    toInt: UnaryTypeConversion<C, number>;
+    toLong: UnaryTypeConversion<C, number>;
+    toObjectId: UnaryTypeConversion<C, ObjectId>;
+    toString: UnaryTypeConversion<C, string>;
+    type: <const T extends ExprArg<C>>(exp: ExprArgInput<C, T>) => Ret<C, "double" | "string" | "object" | "array" | "binData" | "undefined" | "objectId" | "bool" | "date" | "null" | "regex" | "dbPointer" | "javascript" | "javascriptWithScope" | "symbol" | "int" | "timestamp" | "long" | "decimal" | "missing" | "minKey" | "maxKey">;
+    getField: <const F extends string, const I extends ExprArg<C> = never>(options: F | {
+        field: F;
+        input?: ExprArgInput<C, I>;
+    }) => Ret<C, [
+        I
+    ] extends [never] ? F extends keyof C ? C[F] : never : F extends keyof ResolveType<C, I> ? ResolveType<C, I>[F] : never>;
+    mergeObjects: {
+        <const T extends [DeepSpecInput<C, any>, ...DeepSpecInput<C, any>[]]>(...args: T): Ret<C, MergeObjects<C, T>>;
+        <const T extends Dict<ExprArgInput<C, any>>[]>(...args: T): Ret<C, ShallowMergeObjectsOverride<{
+            [I in keyof T]: {
+                [K in keyof T[I]]: T[I][K] extends Ret<any, infer U> ? U : T[I][K];
+            };
+        }>>;
+        <const T extends [ExprArg<C>, ...ExprArg<C>[]]>(...args: ExprArgInputs<C, T>): Ret<C, MergeObjects<C, T>>;
+    };
+    setField: <const F extends string, const I extends ExprArg<C>, const V extends ExprArg<C>>(options: {
+        field: F;
+        input: ExprArgInput<C, I>;
+        value: ExprArgInput<C, V>;
+    }) => Ret<C, ResolveType<C, I> & Record<F, ResolveType<C, V>>>;
+    unsetField: <const F extends string, const I extends ExprArg<C>>(options: {
+        field: F;
+        input: ExprArgInput<C, I>;
+    }) => Ret<C, Omit<ResolveType<C, I>, F>>;
+    /** Binds variables for use within a scoped expression.
+     * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/let/ */
+    let: <const V extends Dict<ExprArg<C>>, const I extends ExprArg<MergeVars<C, ResolveVarSpec<C, V>>>>(options: {
+        vars: {
+            [K in keyof V]: ExprArgInput<C, V[K]>;
+        };
+        in: ($: BaseBuilder<MergeVars<C, ResolveVarSpec<C, V>>>) => I;
+    }) => Ret<C, ResolveType<MergeVars<C, ResolveVarSpec<C, V>>, I>>;
+    /** Returns a value without parsing — prevents field path or operator interpretation.
+     * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/literal/ */
+    literal: <const T>(value: T) => Ret<C, T>;
+    meta: <const T extends "textScore" | "searchScore" | "searchHighlights" | "indexKey">(metaType: T) => Ret<C, T extends "textScore" | "searchScore" ? number : T extends "searchHighlights" ? {
+        path: string;
+        texts: {
+            value: string;
+            type: "text" | "hit";
+        }[];
+    }[] : T extends "indexKey" ? Dict<string> : never>;
+    sampleRate: <const T extends NumericArg<C>>(rate: T & NumericArgInput<C, T>) => Ret<C, boolean>;
+    binarySize: UnaryTypeConversion<C, number>;
+    bsonSize: UnaryTypeConversion<C, number>;
+    bitAnd: VarargsNumericOp<C>;
+    bitOr: VarargsNumericOp<C>;
+    bitXor: VarargsNumericOp<C>;
+    bitNot: UnaryNumericOp<C>;
+    sin: UnaryNumericOp<C>;
+    cos: UnaryNumericOp<C>;
+    tan: UnaryNumericOp<C>;
+    asin: UnaryNumericOp<C>;
+    acos: UnaryNumericOp<C>;
+    atan: UnaryNumericOp<C>;
+    atan2: BinaryNumericOp<C>;
+    asinh: UnaryNumericOp<C>;
+    acosh: UnaryNumericOp<C>;
+    atanh: UnaryNumericOp<C>;
+    sinh: UnaryNumericOp<C>;
+    cosh: UnaryNumericOp<C>;
+    tanh: UnaryNumericOp<C>;
+    degreesToRadians: UnaryNumericOp<C>;
+    radiansToDegrees: UnaryNumericOp<C>;
+    sum: {
+        <const T extends AccumulatorExprArg<C>>(exp: AccumulatorArgInput<C, T>): Ret<C, number>;
+        <const T extends AccumulatorExprArg<C>[]>(...args: AccumulatorArgInputs<C, T>): Ret<C, number>;
+    };
+    avg: {
+        <const T extends AccumulatorExprArg<C>>(exp: AccumulatorArgInput<C, T>): Ret<C, NullishResult<C, T, number>>;
+        <const T extends AccumulatorExprArg<C>[]>(...args: AccumulatorArgInputs<C, T>): Ret<C, NullishResultFromArgs<C, T, number>>;
+    };
+    max: {
+        <const T extends AccumulatorExprArg<C>>(exp: AccumulatorArgInput<C, T>): Ret<C, ResolveType<C, T>>;
+        <const T extends AccumulatorExprArg<C>[]>(...args: AccumulatorArgInputs<C, T>): Ret<C, ResolveType<C, T[number]>>;
+    };
+    min: {
+        <const T extends AccumulatorExprArg<C>>(exp: AccumulatorArgInput<C, T>): Ret<C, ResolveType<C, T>>;
+        <const T extends AccumulatorExprArg<C>[]>(...args: AccumulatorArgInputs<C, T>): Ret<C, ResolveType<C, T[number]>>;
+    };
+    stdDevPop: {
+        <const T extends AccumulatorExprArg<C>>(exp: AccumulatorArgInput<C, T>): Ret<C, NullishResult<C, T, number>>;
+        <const T extends AccumulatorExprArg<C>[]>(...args: AccumulatorArgInputs<C, T>): Ret<C, NullishResultFromArgs<C, T, number>>;
+    };
+    stdDevSamp: {
+        <const T extends AccumulatorExprArg<C>>(exp: AccumulatorArgInput<C, T>): Ret<C, NullishResult<C, T, number>>;
+        <const T extends AccumulatorExprArg<C>[]>(...args: AccumulatorArgInputs<C, T>): Ret<C, NullishResultFromArgs<C, T, number>>;
+    };
+}
+/**
+ * Expression builder providing type-safe access to all MongoDB aggregation operators.
+ *
+ * Passed as `$` in stage callbacks (e.g., `$project($ => ...)`, `$match($ => ...)`).
+ * Exposes arithmetic, string, array, date, conditional, and comparison operators
+ * that mirror the MongoDB aggregation expression language with full type inference.
+ */
+declare class ExprBuilder<C> extends BaseBuilder<C> {
+    /** Include this field in `$project` output (equivalent to `1`). */
+    readonly include: 1;
+    /** Exclude this field from `$project` output (equivalent to `0`). */
+    readonly exclude: 0;
+}
+declare class AccumulatorBuilder<C> extends BaseBuilder<C, "accumulator"> {
+    addToSet: <const T extends ExprArg<C>>(exp: ExprArgInput<C, T>) => Ret<C, ResolveType<C, T>[]>;
+    count: <const T extends Dict<never>>(options: T) => Ret<C, number>;
+    push: <const T>(exp: T & DeepSpecInput<C, T>) => Ret<C, DeepSpecResolve<C, T>[]>;
+    bottom: <const TOutput extends ExprArg<C>, const TSort extends SortBySpec<C>>(options: {
+        output: ExprArgInput<C, TOutput>;
+        sortBy: TSort;
+    }) => Ret<C, ResolveType<C, TOutput>>;
+    bottomN: <const TOutput extends ExprArg<C>, const TSort extends SortBySpec<C>, const N extends NumericArg<C>>(options: {
+        output: ExprArgInput<C, TOutput>;
+        sortBy: TSort;
+        n: N & NumericArgInput<C, N>;
+    }) => Ret<C, ResolveType<C, TOutput>[]>;
+    top: <const T extends SortBySpec<C>, const O extends ExprArg<C>>(options: {
+        output: ExprArgInput<C, O>;
+        sortBy: T;
+    }) => Ret<C, ResolveType<C, O>>;
+    topN: <const T extends SortBySpec<C>, const N extends NumericArg<C>, const O extends ExprArg<C>>(options: {
+        output: ExprArgInput<C, O>;
+        sortBy: T;
+        n: N & NumericArgInput<C, N>;
+    }) => Ret<C, ResolveType<C, O>[]>;
+    accumulator: {
+        <const InitFn extends (...args: any[]) => any, const AccExprs extends readonly ExprArg<C>[], const Result>(options: TypedAccumulator<InitFn, {
+            [K in keyof AccExprs]: ResolveType<C, AccExprs[K]>;
+        }, Result> & Omit<TypedAccumulator<InitFn, {
+            [K in keyof AccExprs]: ResolveType<C, AccExprs[K]>;
+        }, Result>, "accumulate" | "accumulateArgs"> & {
+            accumulate: (state: ReturnType<InitFn>, ...args: {
+                [K in keyof AccExprs]: ResolveType<C, AccExprs[K]>;
+            }) => ReturnType<InitFn>;
+            accumulateArgs: readonly [...AccExprs] & {
+                [K in keyof AccExprs]: ExprArgInput<C, AccExprs[K]>;
+            };
+            finalize: (state: ReturnType<InitFn>) => Result;
+        }): Ret<C, Result>;
+        <InitFn extends (...args: any[]) => any, AccArgs extends readonly unknown[], Result>(options: TypedAccumulator<InitFn, AccArgs, Result> & {
+            finalize: (state: ReturnType<InitFn>) => Result;
+        }): Ret<C, Result>;
+        <InitFn extends (...args: any[]) => any, AccExprs extends readonly ExprArg<C>[]>(options: TypedAccumulator<InitFn, {
+            [K in keyof AccExprs]: ResolveType<C, AccExprs[K]>;
+        }, ReturnType<InitFn>> & Omit<TypedAccumulator<InitFn, {
+            [K in keyof AccExprs]: ResolveType<C, AccExprs[K]>;
+        }, ReturnType<InitFn>>, "accumulate" | "accumulateArgs"> & {
+            accumulate: (state: ReturnType<InitFn>, ...args: {
+                [K in keyof AccExprs]: ResolveType<C, AccExprs[K]>;
+            }) => ReturnType<InitFn>;
+            accumulateArgs: readonly [...AccExprs] & {
+                [K in keyof AccExprs]: ExprArgInput<C, AccExprs[K]>;
+            };
+            finalize?: undefined;
+        }): Ret<C, ReturnType<InitFn>>;
+        <InitFn extends (...args: any[]) => any, AccArgs extends readonly unknown[]>(options: TypedAccumulator<InitFn, AccArgs, ReturnType<InitFn>> & {
+            finalize?: undefined;
+        }): Ret<C, ReturnType<InitFn>>;
+    };
+    median: <const T extends NumericArg<C>>(options: {
+        input: T & NumericArgInput<C, T>;
+        method?: "approximate";
+    }) => Ret<C, number>;
+    percentile: <const T extends NumericArg<C>, const P extends readonly number[]>(options: {
+        input: T & NumericArgInput<C, T>;
+        p: P;
+        method?: "approximate";
+    }) => Ret<C, {
+        [K in keyof P]: number;
+    }>;
+}
+declare class WindowBuilder<C> extends AccumulatorBuilder<C> {
+    denseRank: () => Ret<C, number>;
+    covariancePop: <const X extends NumericArg<C>, const Y extends NumericArg<C>>(x: X & NumericArgInput<C, X>, y: Y & NumericArgInput<C, Y>) => Ret<C, number | null>;
+    covarianceSamp: <const X extends NumericArg<C>, const Y extends NumericArg<C>>(x: X & NumericArgInput<C, X>, y: Y & NumericArgInput<C, Y>) => Ret<C, number | null>;
+    derivative: <const T extends NumericArg<C>>(options: {
+        input: T & NumericArgInput<C, T>;
+        unit?: TimeUnit;
+        window?: WindowSpec;
+    }) => Ret<C, number>;
+    documentNumber: () => Ret<C, number>;
+    expMovingAvg: <const T extends NumericArg<C>>(options: {
+        input: T & NumericArgInput<C, T>;
+        N?: NumericArg<C>;
+        alpha?: NumericArg<C>;
+        window?: WindowSpec;
+    }) => Ret<C, number>;
+    integral: <const T extends NumericArg<C>>(options: {
+        input: T & NumericArgInput<C, T>;
+        unit?: TimeUnit;
+        window?: WindowSpec;
+    }) => Ret<C, number>;
+    linearFill: <const T extends ExprArg<C>>(exp: ExprArgInput<C, T>) => Ret<C, ResolveType<C, T>>;
+    locf: <const T extends ExprArg<C>>(exp: ExprArgInput<C, T>) => Ret<C, ResolveType<C, T>>;
+    percentRank: () => Ret<C, number>;
+    rank: () => Ret<C, number>;
+    shift: <const T extends ExprArg<C>, const B extends NumericArg<C>>(options: {
+        output: ExprArgInput<C, T>;
+        by: B & NumericArgInput<C, B>;
+        default?: ExprArgInput<C, ExprArg<C>>;
+    }) => Ret<C, ResolveType<C, T>>;
+}
+
+/**
+ * Migration tool — type-safe collection schema migrations via update pipelines.
+ *
+ * Usage:
+ *   const migration = migrate<OldUser, NewUser>();
+ *   const pipeline = migration.pipe(
+ *     $set({ newField: "default" }),
+ *     $unset("deprecatedField"),
+ *   );
+ *   // pipeline is only valid if the output matches NewUser
+ *   await collection.updateMany(() => ({}), $ => pipeline).execute();
+ */
+
+/**
+ * MigrationOperators — the migration context with pipe and stage references.
+ */
+type MigrationOperators<TFrom, TTo> = {
+    pipe: MigrationPipelineBuilder<TFrom, TTo>;
+};
+/**
+ * Creates a type-safe migration pipeline builder.
+ *
+ * The pipeline starts from TFrom (source schema) and validates that the
+ * final output is assignable to TTo (target schema).
+ *
+ * Only update-allowed stages ($set, $unset, $addFields, $project,
+ * $replaceRoot, $replaceWith) are accepted.
+ *
+ * @example
+ * ```ts
+ * type OldUser = { _id: ObjectId; name: string; age: number };
+ * type NewUser = { _id: ObjectId; name: string; age: number; email: string };
+ *
+ * const m = migrate<OldUser, NewUser>();
+ * const pipeline = m.pipe(
+ *   $set({ email: "unknown@example.com" }),
+ * );
+ * // ✅ compiles — output matches NewUser
+ *
+ * const bad = m.pipe(
+ *   $unset("age"),
+ * );
+ * // ❌ error — output { _id, name } doesn't match NewUser
+ * ```
+ */
+declare const migrate: <TFrom, TTo>() => MigrationOperators<SimplifyWritable<TFrom>, SimplifyWritable<TTo>>;
+
+export { $addFields, $bucket, $bucketAuto, $changeStream, $collStats, $count, $currentOp, $densify, $documents, $facet, $fill, $geoNear, $graphLookup, $group, $indexStats, $limit, $listLocalSessions, $listSessions, $lookup, $match, $merge, $out, $planCacheStats, $project, $redact, $replaceRoot, $replaceWith, $sample, $set, $setWindowFields, $shardedDataDistribution, $skip, $sort, $sortByCount, $unionWith, $unset, $unwind, AccumulatorBuilder, type Agg, type AggregateBuilder, type BoundCollection, type BulkWriteBuilder, type BulkWriteOp, type CallbackOnlyError, type Collection, type CollectionType, type CountBuilder, type CountOptions, type CrudCollection, type CrudFilter, type DeleteBuilder, type DistinctBuilder, ExprBuilder, type FindBuilder, type FindOneAndDeleteBuilder, type FindOneAndOptions, type FindOneAndReplaceBuilder, type FindOneAndUpdateBuilder, type FindOptions, type ForeignType, type Geometry, type InferSchema, type InsertManyBuilder, type InsertOneBuilder, type MigrationOperators, type MigrationPipelineBuilder, type PipelineBuilder, type ProjectionSpec, type ReplaceBuilder, Ret, type SchemaLike, type SortSpec, type StageFunction, type TimeUnit, type TypedAccumulator, type TypedPipeline, type UpdateManyBuilder, type UpdateOneBuilder, type UpdateOperators, type UpdatePipelineBuilder, type UpdatePipelineCallback, WindowBuilder, type WindowSpec, collection, functionToString, migrate, registry, resolveAccumulator };