@prisma-next/mongo-query-builder 0.0.1

package/dist/index.d.mts

@@ -0,0 +1,1198 @@
+import { AggregateCommand, AnyMongoCommand, DeleteManyCommand, DeleteOneCommand, DeleteResult, DeleteResult as DeleteResult$1, FindOneAndDeleteCommand, FindOneAndUpdateCommand, InsertManyCommand, InsertManyResult, InsertManyResult as InsertManyResult$1, InsertOneCommand, InsertOneResult, InsertOneResult as InsertOneResult$1, MongoAggAccumulator, MongoAggExpr, MongoDensifyRange, MongoFillOutput, MongoFilterExpr, MongoPipelineStage, MongoQueryPlan, MongoUpdatePipelineStage, MongoWindowField, UpdateManyCommand, UpdateOneCommand, UpdateResult, UpdateResult as UpdateResult$1 } from "@prisma-next/mongo-query-ast/execution";
+import { ExtractMongoCodecTypes, MongoContract, MongoContractWithTypeMaps, MongoTypeMaps } from "@prisma-next/mongo-contract";
+import { MongoValue } from "@prisma-next/mongo-value";
+
+//#region src/types.d.ts
+interface DocField {
+  readonly codecId: string;
+  readonly nullable: boolean;
+}
+type NumericField = {
+  readonly codecId: 'mongo/double@1';
+  readonly nullable: false;
+};
+type NullableNumericField = {
+  readonly codecId: 'mongo/double@1';
+  readonly nullable: true;
+};
+type StringField = {
+  readonly codecId: 'mongo/string@1';
+  readonly nullable: false;
+};
+type ArrayField = {
+  readonly codecId: 'mongo/array@1';
+  readonly nullable: false;
+};
+type BooleanField = {
+  readonly codecId: 'mongo/bool@1';
+  readonly nullable: false;
+};
+type DateField = {
+  readonly codecId: 'mongo/date@1';
+  readonly nullable: false;
+};
+type NullableDocField = {
+  readonly codecId: string;
+  readonly nullable: true;
+};
+type LiteralValue<F extends DocField> = F extends StringField ? string : F extends NumericField ? number : F extends BooleanField ? boolean : F extends DateField ? Date : unknown;
+type DocShape = Record<string, DocField>;
+type ExtractCodecId<F> = F extends {
+  type: {
+    kind: 'scalar';
+    codecId: infer C;
+  };
+} ? C : F extends {
+  codecId: infer C extends string;
+} ? C : string;
+type ModelToDocShape<TContract extends MongoContract, ModelName extends string & keyof TContract['models']> = { [K in keyof TContract['models'][ModelName]['fields'] & string]: {
+  readonly codecId: ExtractCodecId<TContract['models'][ModelName]['fields'][K]>;
+  readonly nullable: TContract['models'][ModelName]['fields'][K]['nullable'];
+} };
+type ResolveRow<Shape extends DocShape, CodecTypes extends Record<string, {
+  readonly output: unknown;
+}>> = { -readonly [K in keyof Shape & string]: Shape[K]['codecId'] extends keyof CodecTypes ? Shape[K]['nullable'] extends true ? CodecTypes[Shape[K]['codecId']]['output'] | null : CodecTypes[Shape[K]['codecId']]['output'] : unknown };
+interface TypedAggExpr<F extends DocField> {
+  readonly _field: F;
+  readonly node: MongoAggExpr;
+}
+interface TypedAccumulatorExpr<F extends DocField> {
+  readonly _field: F;
+  readonly node: MongoAggAccumulator;
+}
+type ExtractDocShape<T extends Record<string, TypedAggExpr<DocField>>> = { [K in keyof T & string]: T[K]['_field'] };
+type SortSpec<S extends DocShape> = Partial<Record<keyof S & string, 1 | -1>>;
+type ProjectedShape<Shape extends DocShape, Spec extends Record<string, 1 | TypedAggExpr<DocField>>> = { [K in keyof Spec & string]: Spec[K] extends 1 ? K extends keyof Shape ? Shape[K] : DocField : Spec[K] extends TypedAggExpr<infer F> ? F : DocField } & ('_id' extends keyof Shape ? '_id' extends keyof Spec ? Record<keyof never, never> : Pick<Shape, '_id'> : Record<keyof never, never>);
+type GroupSpec = {
+  _id: TypedAggExpr<DocField> | null;
+  [key: string]: TypedAggExpr<DocField> | TypedAccumulatorExpr<DocField> | null;
+};
+type GroupedDocShape<Spec extends GroupSpec> = { [K in keyof Spec & string]: Spec[K] extends TypedAggExpr<infer F> ? F : Spec[K] extends TypedAccumulatorExpr<infer F> ? F : Spec[K] extends null ? {
+  readonly codecId: 'mongo/null@1';
+  readonly nullable: true;
+} : DocField };
+/**
+ * Intentionally identity — full array element type extraction is deferred.
+ * Used by `UnwoundShape` so the unwind result shape can be refined later
+ * without changing the public API.
+ */
+type UnwrapArrayDocField<F extends DocField> = F;
+type UnwoundShape<S extends DocShape, K$1 extends keyof S & string> = { [P in keyof S & string]: P extends K$1 ? UnwrapArrayDocField<S[P]> : S[P] };
+//#endregion
+//#region src/accumulator-helpers.d.ts
+declare const acc: {
+  sum<F extends DocField>(expr: TypedAggExpr<F>): TypedAccumulatorExpr<F>;
+  avg(expr: TypedAggExpr<DocField>): TypedAccumulatorExpr<NullableNumericField>;
+  min<F extends DocField>(expr: TypedAggExpr<F>): TypedAccumulatorExpr<{
+    readonly codecId: F["codecId"];
+    readonly nullable: true;
+  }>;
+  max<F extends DocField>(expr: TypedAggExpr<F>): TypedAccumulatorExpr<{
+    readonly codecId: F["codecId"];
+    readonly nullable: true;
+  }>;
+  first<F extends DocField>(expr: TypedAggExpr<F>): TypedAccumulatorExpr<{
+    readonly codecId: F["codecId"];
+    readonly nullable: true;
+  }>;
+  last<F extends DocField>(expr: TypedAggExpr<F>): TypedAccumulatorExpr<{
+    readonly codecId: F["codecId"];
+    readonly nullable: true;
+  }>;
+  push(expr: TypedAggExpr<DocField>): TypedAccumulatorExpr<ArrayField>;
+  addToSet(expr: TypedAggExpr<DocField>): TypedAccumulatorExpr<ArrayField>;
+  count(): TypedAccumulatorExpr<NumericField>;
+  stdDevPop(expr: TypedAggExpr<DocField>): TypedAccumulatorExpr<NullableNumericField>;
+  stdDevSamp(expr: TypedAggExpr<DocField>): TypedAccumulatorExpr<NullableNumericField>;
+  firstN(args: {
+    input: TypedAggExpr<DocField>;
+    n: TypedAggExpr<NumericField>;
+  }): TypedAccumulatorExpr<ArrayField>;
+  lastN(args: {
+    input: TypedAggExpr<DocField>;
+    n: TypedAggExpr<NumericField>;
+  }): TypedAccumulatorExpr<ArrayField>;
+  maxN(args: {
+    input: TypedAggExpr<DocField>;
+    n: TypedAggExpr<NumericField>;
+  }): TypedAccumulatorExpr<ArrayField>;
+  minN(args: {
+    input: TypedAggExpr<DocField>;
+    n: TypedAggExpr<NumericField>;
+  }): TypedAccumulatorExpr<ArrayField>;
+  top(args: {
+    output: TypedAggExpr<DocField>;
+    sortBy: Readonly<Record<string, 1 | -1>>;
+  }): TypedAccumulatorExpr<DocField>;
+  bottom(args: {
+    output: TypedAggExpr<DocField>;
+    sortBy: Readonly<Record<string, 1 | -1>>;
+  }): TypedAccumulatorExpr<DocField>;
+  topN(args: {
+    output: TypedAggExpr<DocField>;
+    sortBy: Readonly<Record<string, 1 | -1>>;
+    n: TypedAggExpr<NumericField>;
+  }): TypedAccumulatorExpr<ArrayField>;
+  bottomN(args: {
+    output: TypedAggExpr<DocField>;
+    sortBy: Readonly<Record<string, 1 | -1>>;
+    n: TypedAggExpr<NumericField>;
+  }): TypedAccumulatorExpr<ArrayField>;
+};
+//#endregion
+//#region src/resolve-path.d.ts
+/**
+ * Marker `DocField` variant representing a non-leaf (value-object) path in
+ * a [NestedDocShape]. Extends `DocField` with a `fields` property carrying
+ * the sub-shape so the pipeline builder can recurse into it.
+ *
+ * `codecId` is the reserved literal `'prisma/object@1'`; the accessor's
+ * runtime implementation does not serialize it — the codec id is a purely
+ * type-level sentinel used by `Expression<F>` to select the reduced
+ * operator surface for non-leaf paths.
+ *
+ * `nullable` tracks whether the value object itself may be absent/null on
+ * the parent document. The callable form currently does not propagate the
+ * parent's `nullable` flag onto leaves beneath it (path traversal under a
+ * nullable parent resolves to the leaf's own `nullable` — matching how
+ * MongoDB treats missing intermediate documents).
+ */
+interface ObjectField<N$1 extends NestedDocShape> extends DocField {
+  readonly codecId: 'prisma/object@1';
+  readonly nullable: boolean;
+  readonly fields: N$1;
+}
+/**
+ * Document shape that carries nested value-object sub-shapes.
+ *
+ * Structurally identical to a flat `DocShape` (`Record<string, DocField>`),
+ * but individual values may be `ObjectField<SubShape>` carrying a nested
+ * `NestedDocShape` sub-tree. The pipeline builder threads a
+ * `NestedDocShape` alongside the flat `DocShape` so the callable
+ * `f('a.b.c')` form can validate dot-paths at the type level.
+ *
+ * When a stage transforms the root shape in a way that invalidates nested
+ * paths (e.g. `$group`, `$project`, `$replaceRoot`), the thread is reset
+ * to the empty shape `Record<string, never>` — which makes `ValidPaths`
+ * resolve to `never` and so disables the callable form downstream.
+ */
+type NestedDocShape = Record<string, DocField>;
+type ContractHasValueObjects = {
+  readonly valueObjects?: Record<string, {
+    readonly fields: Record<string, unknown>;
+  }>;
+};
+type FieldToLeaf<F> = F extends {
+  readonly type: {
+    readonly kind: 'scalar';
+    readonly codecId: infer C extends string;
+  };
+  readonly nullable: infer N extends boolean;
+} ? {
+  readonly codecId: C;
+  readonly nullable: N;
+} : F extends {
+  readonly many: true;
+  readonly nullable: infer N extends boolean;
+} ? {
+  readonly codecId: 'mongo/array@1';
+  readonly nullable: N;
+} : DocField;
+/**
+ * Translate a single contract field to its nested-shape form. Scalars
+ * become `DocField` leaves; value-object fields become
+ * `ObjectField<Sub>`; `many: true` stops at a leaf; anything else falls
+ * through to the opaque `DocField` base.
+ *
+ * Kept as a per-field helper (rather than a `Fields → NestedShape` helper
+ * that maps over keys internally) so the parent mapped type stays
+ * homomorphic over the model/value-object `fields` record. Homomorphic
+ * mapped types preserve the literal keys of their source object through
+ * TypeScript's intersection-collapsing machinery, which keeps
+ * `ModelNestedShape` hover output and `keyof`/indexed-access resolution
+ * concrete instead of collapsing to `{ [x: string]: … }`.
+ */
+type TranslateField<TContract extends ContractHasValueObjects, F> = F extends {
+  readonly many: true;
+} ? FieldToLeaf<F> : F extends {
+  readonly type: {
+    readonly kind: 'valueObject';
+    readonly name: infer VOName extends string;
+  };
+  readonly nullable: infer Null extends boolean;
+} ? ObjectField<VONestedShape<TContract, VOName>> & {
+  readonly nullable: Null;
+} : F extends {
+  readonly type: {
+    readonly kind: 'scalar';
+    readonly codecId: string;
+  };
+} ? FieldToLeaf<F> : DocField;
+/**
+ * Resolve a named value object from the contract into its own
+ * `NestedDocShape`. The mapped iteration is inlined here (not delegated
+ * to a generic helper) so that the homomorphism over
+ * `VOs[VOName]['fields']` is preserved and the hover / indexed-access
+ * surface stays concrete at instantiation time.
+ */
+type VONestedShape<TContract extends ContractHasValueObjects, VOName$1 extends string> = TContract extends {
+  readonly valueObjects: infer VOs extends Record<string, {
+    readonly fields: Record<string, unknown>;
+  }>;
+} ? VOName$1 extends keyof VOs ? { readonly [K in keyof VOs[VOName$1]['fields'] & string]: TranslateField<TContract, VOs[VOName$1]['fields'][K]> } : never : never;
+/**
+ * Build the `NestedDocShape` for a model. Scalar leaves resolve to their
+ * concrete codec id; value-object fields recurse into the referenced
+ * `valueObjects[VOName].fields` table, producing a tree that
+ * `ResolvePath` / `ValidPaths` can walk.
+ *
+ * The mapped iteration is inlined (not hidden behind a helper type that
+ * takes `Fields` as a generic) so TypeScript recognises the mapped type
+ * as homomorphic over `TContract['models'][ModelName]['fields']`. That
+ * preserves the literal field-name keys at instantiation — without this,
+ * the intersection of `Record<string, ContractField>` and the specific
+ * literal field record collapses `keyof` to `string` and the result hover
+ * degrades to `{ readonly [x: string]: any }`.
+ */
+type ModelNestedShape<TContract extends MongoContract, ModelName extends string & keyof TContract['models']> = { readonly [K in keyof TContract['models'][ModelName]['fields'] & string]: TranslateField<TContract & ContractHasValueObjects, TContract['models'][ModelName]['fields'][K]> };
+/**
+ * Resolve a dot-path against a `NestedDocShape`. Returns:
+ *  - the leaf `DocField` when `Path` terminates on a scalar/array leaf,
+ *  - the `ObjectField<Sub>` when `Path` terminates on a value object (so
+ *    the caller can operate on the whole sub-document),
+ *  - `never` when the path is invalid (unknown segment, or a scalar
+ *    segment followed by further traversal).
+ *
+ * Paired with the constrained callable `<P extends ValidPaths<N>>(path: P)
+ * => Expression<ResolvePath<N, P>>` so the IDE offers completions and
+ * rejects bad paths with a clear error instead of silently resolving to
+ * `never`.
+ */
+type ResolvePath<N$1 extends NestedDocShape, Path extends string> = Path extends `${infer Head}.${infer Rest}` ? Head extends keyof N$1 & string ? N$1[Head] extends ObjectField<infer Sub> ? ResolvePath<Sub, Rest> : never : never : Path extends keyof N$1 & string ? N$1[Path] : never;
+/**
+ * Union of every valid dot-path within a `NestedDocShape`. Includes
+ * top-level keys (scalar leaves *and* value-object roots) and every
+ * recursive descent through `ObjectField` sub-shapes.
+ *
+ * Non-leaf paths are intentionally included — `f('address')` yields an
+ * `Expression<ObjectField<…>>` whose reduced operator surface (`set`,
+ * `unset`, `exists`, `eq(null)`, `ne(null)`) lets callers operate on the
+ * whole value object. Leaf paths like `f('address.city')` get the full
+ * leaf operator surface.
+ *
+ * The `string extends keyof N` guard short-circuits to `never` for
+ * open-ended index-signature shapes (e.g. the default
+ * `Record<string, never>` used to represent "no nested information" —
+ * notably downstream of replacement stages in the pipeline builder). An
+ * open-ended `keyof` cannot resolve a specific literal path, so the
+ * callable form must be disabled at the type level.
+ */
+type ValidPaths<N$1 extends NestedDocShape> = string extends keyof N$1 ? never : { [K in keyof N$1 & string]: N$1[K] extends ObjectField<infer Sub> ? K | `${K}.${ValidPaths<Sub>}` : K }[keyof N$1 & string];
+/**
+ * IDE-oriented alias for `ValidPaths`. Kept as a separate export so future
+ * refinements (e.g. ArkType-style lazy expansion for very deep shapes) can
+ * diverge from the strict `ValidPaths` constraint without breaking
+ * downstream consumers. For now the two are intentionally equivalent.
+ */
+type PathCompletions<N$1 extends NestedDocShape> = ValidPaths<N$1>;
+//#endregion
+//#region src/update-ops.d.ts
+/**
+ * Per-field update operations produced by `Expression`'s update methods
+ * (`set`, `inc`, `push`, …). A write terminal folds an array of these into a
+ * `MongoUpdateSpec` record (`{ $set: { … }, $inc: { … }, … }`) before
+ * constructing the underlying `UpdateManyCommand` / `UpdateOneCommand` AST node.
+ *
+ * One `TypedUpdateOp` value corresponds to one Mongo update operator applied
+ * to one field path. The `op` string is the wire-level operator name (`$set`,
+ * `$inc`, …); the `path` is the dot-path to the field (or its top-level name).
+ */
+type TypedUpdateOp = {
+  readonly op: '$set';
+  readonly path: string;
+  readonly value: MongoValue;
+} | {
+  readonly op: '$unset';
+  readonly path: string;
+} | {
+  readonly op: '$rename';
+  readonly path: string;
+  readonly newName: string;
+} | {
+  readonly op: '$inc';
+  readonly path: string;
+  readonly amount: number;
+} | {
+  readonly op: '$mul';
+  readonly path: string;
+  readonly factor: number;
+} | {
+  readonly op: '$min';
+  readonly path: string;
+  readonly value: MongoValue;
+} | {
+  readonly op: '$max';
+  readonly path: string;
+  readonly value: MongoValue;
+} | {
+  readonly op: '$push';
+  readonly path: string;
+  readonly value: MongoValue;
+} | {
+  readonly op: '$addToSet';
+  readonly path: string;
+  readonly value: MongoValue;
+} | {
+  readonly op: '$pop';
+  readonly path: string;
+  readonly direction: 1 | -1;
+} | {
+  readonly op: '$pull';
+  readonly path: string;
+  readonly value: MongoValue;
+} | {
+  readonly op: '$pullAll';
+  readonly path: string;
+  readonly values: ReadonlyArray<MongoValue>;
+} | {
+  readonly op: '$currentDate';
+  readonly path: string;
+} | {
+  readonly op: '$setOnInsert';
+  readonly path: string;
+  readonly value: MongoValue;
+};
+/**
+ * The return type for updater callbacks. Typed as a union of homogeneous
+ * arrays so mixed-shape updaters (operator + pipeline stage in the same
+ * array) are a compile error. The runtime guard in `resolveUpdaterResult`
+ * remains as defence-in-depth.
+ */
+type UpdaterResult = ReadonlyArray<TypedUpdateOp> | ReadonlyArray<MongoUpdatePipelineStage>;
+//#endregion
+//#region src/field-accessor.d.ts
+/**
+ * Operator surface for leaf (scalar) paths — today's full set: filter,
+ * update, and aggregation operators. Returned by `Expression<F>` for any
+ * `F extends DocField` that is not an `ObjectField<…>` sub-tree.
+ *
+ * Operator surfaces are intentionally not trait-gated by codec in this
+ * revision — tracked on Linear as TML-2259 (scope extended to cover the
+ * query-builder's `Expression<F>`). Calling, e.g. `.inc(1)` on a
+ * string-typed expression compiles; the runtime relies on Mongo to
+ * surface the error. Trait-gating can be tightened in a follow-up
+ * without changing the accessor's public shape.
+ */
+interface LeafExpression<F extends DocField> extends TypedAggExpr<F> {
+  readonly _path: string;
+  eq(value: MongoValue): MongoFilterExpr;
+  ne(value: MongoValue): MongoFilterExpr;
+  gt(value: MongoValue): MongoFilterExpr;
+  gte(value: MongoValue): MongoFilterExpr;
+  lt(value: MongoValue): MongoFilterExpr;
+  lte(value: MongoValue): MongoFilterExpr;
+  in(values: ReadonlyArray<MongoValue>): MongoFilterExpr;
+  nin(values: ReadonlyArray<MongoValue>): MongoFilterExpr;
+  exists(flag?: boolean): MongoFilterExpr;
+  set(value: MongoValue): TypedUpdateOp;
+  unset(): TypedUpdateOp;
+  rename(newName: string): TypedUpdateOp;
+  inc(amount: number): TypedUpdateOp;
+  mul(factor: number): TypedUpdateOp;
+  min(value: MongoValue): TypedUpdateOp;
+  max(value: MongoValue): TypedUpdateOp;
+  push(value: MongoValue): TypedUpdateOp;
+  addToSet(value: MongoValue): TypedUpdateOp;
+  pop(direction?: 1 | -1): TypedUpdateOp;
+  pull(value: MongoValue): TypedUpdateOp;
+  pullAll(values: ReadonlyArray<MongoValue>): TypedUpdateOp;
+  currentDate(): TypedUpdateOp;
+  setOnInsert(value: MongoValue): TypedUpdateOp;
+}
+/**
+ * Operator surface for non-leaf (value-object) paths — `f('address')`
+ * when `address` is a `ContractValueObject`. Intentionally minimal: the
+ * whole-value ops that make sense on a structured sub-document
+ * (`set`/`unset`/`exists`, null presence via `eq(null)`/`ne(null)`). Field-
+ * level ops belong on the constituent leaves (`f('address.city')`).
+ *
+ * The aggregation `node` is still present (`TypedAggExpr<ObjectField<N>>`)
+ * so the value object can be piped through `$addFields` /
+ * `$replaceRoot` / etc. as-is.
+ */
+interface ObjectExpression<N$1 extends NestedDocShape> extends TypedAggExpr<ObjectField<N$1>> {
+  readonly _path: string;
+  exists(flag?: boolean): MongoFilterExpr;
+  eq(value: null): MongoFilterExpr;
+  ne(value: null): MongoFilterExpr;
+  set(value: MongoValue): TypedUpdateOp;
+  unset(): TypedUpdateOp;
+}
+/**
+ * The unified field accessor expression returned by `FieldAccessor` (per
+ * [ADR 180](../../../../docs/architecture%20docs/adrs/ADR%20180%20-%20Dot-path%20field%20accessor.md)).
+ *
+ * Resolves to `ObjectExpression<Sub>` when `F` is an `ObjectField<Sub>`
+ * (non-leaf path), otherwise to `LeafExpression<F>` (the full operator
+ * surface). The conditional is driven off the `fields` marker that
+ * `ObjectField` adds to `DocField`, so existing code that uses plain
+ * `DocField` shapes continues to resolve to `LeafExpression`.
+ */
+type Expression<F extends DocField> = F extends ObjectField<infer N> ? ObjectExpression<N> : LeafExpression<F>;
+/**
+ * Emitters for MongoDB update-pipeline stages (`$addFields`/`$set`,
+ * `$project`/`$unset`, `$replaceRoot`/`$replaceWith`). These return
+ * `MongoUpdatePipelineStage` nodes and let an updater callback express
+ * the pipeline-form update as an alternative to the typed-operator form.
+ *
+ * The two forms are mutually exclusive per updater call: `resolveUpdaterResult`
+ * rejects arrays that mix `TypedUpdateOp` and `MongoUpdatePipelineStage`
+ * entries with a clear error — an updater callback must return either all
+ * typed ops or all pipeline stages. Pick the form that matches the update
+ * you want and commit to it for that call site.
+ *
+ * Accessible via `f.stage` on the `FieldAccessor`.
+ */
+interface StageEmitters {
+  set(fields: Record<string, MongoAggExpr>): MongoUpdatePipelineStage;
+  unset(...paths: ReadonlyArray<string>): MongoUpdatePipelineStage;
+  replaceRoot(newRoot: MongoAggExpr): MongoUpdatePipelineStage;
+  replaceWith(newRoot: MongoAggExpr): MongoUpdatePipelineStage;
+}
+/**
+ * The unified `FieldAccessor` per ADR 180.
+ *
+ * - Property access (`f.status`) returns an `Expression<F>` whose codec
+ *   comes from the current pipeline shape `S`.
+ * - Callable form (`f('address.city')`) returns an `Expression<ResolvePath<N, P>>`
+ *   where `N` is the nested shape carrying value-object sub-shapes.
+ *   Paths that don't exist in `N` are rejected with a compile-time error
+ *   (via `P extends ValidPaths<N>`). Non-leaf paths like `f('address')`
+ *   resolve to an `ObjectExpression` whose reduced surface covers the
+ *   whole-value operations (`set`, `unset`, `exists`, `eq(null)`,
+ *   `ne(null)`).
+ * - `f.rawPath('path')` is a deliberate escape hatch that skips path
+ *   validation and returns a `LeafExpression<F>` for the given string.
+ *   Intended for migration authoring where the target field is not yet
+ *   part of the typed contract (e.g. a backfill writing a newly-added
+ *   column before the contract hash rolls forward). The method name is
+ *   deliberately `rawPath` rather than `raw` so it does not shadow a
+ *   legitimate top-level `raw` field on a user model.
+ * - `f.stage` exposes pipeline-style update emitters (`$set`, `$unset`,
+ *   `$replaceRoot`, `$replaceWith`).
+ *
+ * When `N` is `Record<string, never>` (the default — e.g. after a
+ * replacement stage like `$group` / `$project` / `$replaceRoot`),
+ * `ValidPaths<N>` is `never` and the callable form is effectively
+ * disabled at the type level. This keeps the builder sound downstream of
+ * stages that invalidate the original document's nested-path tree.
+ * `f.rawPath(...)` remains available in that state for callers that need
+ * an explicit unvalidated path.
+ */
+type FieldAccessor<S extends DocShape, N$1 extends NestedDocShape = Record<string, never>> = { readonly [K in keyof S & string]: Expression<S[K]> } & (<P$1 extends ValidPaths<N$1>>(path: P$1) => Expression<ResolvePath<N$1, P$1>>) & {
+  readonly stage: StageEmitters;
+  /**
+   * Escape hatch: build a `LeafExpression<F>` for an unvalidated string
+   * path. Use only when the path is intentionally outside the typed
+   * model surface — data-migration authoring is the canonical case
+   * (e.g. backfilling a field that is not yet in the contract). Default
+   * `F` is the opaque `DocField`; callers can narrow via the explicit
+   * generic: `f.rawPath<StringField>("status").set("active")`.
+   *
+   * The method is named `rawPath` (not `raw`) so a user model with a
+   * top-level `raw` field still resolves `f.raw` to the field-expression
+   * property, not to this escape hatch. Does not participate in
+   * `ValidPaths<N>` / `ResolvePath<N, P>` — the path is passed through
+   * verbatim and no IDE autocomplete is offered.
+   */
+  rawPath<F extends DocField = DocField>(path: string): LeafExpression<F>;
+};
+/**
+ * Construct a unified `FieldAccessor<S, N>` proxy. Property access creates
+ * an `Expression` using the property name as the field path; callable
+ * form accepts a dot-path string validated against `N` at compile time.
+ *
+ * The proxy target is a function so the resulting object is both callable
+ * and indexable. Symbol-keyed accesses (e.g. `Symbol.toPrimitive`) return
+ * `undefined` to keep accidental coercion behaviour unsurprising —
+ * matching the previous `FieldProxy` / `FilterProxy` semantics.
+ */
+declare function createFieldAccessor<S extends DocShape, N$1 extends NestedDocShape = Record<string, never>>(): FieldAccessor<S, N$1>;
+//#endregion
+//#region src/markers.d.ts
+/**
+ * Phantom capability markers for `PipelineChain`.
+ *
+ * `UpdateEnabled`          — gates `.updateMany()` / `.updateOne()` no-arg form
+ *                            (consume accumulated pipeline as an update-with-pipeline spec).
+ * `FindAndModifyEnabled`   — gates `.findOneAndUpdate(...)` / `.findOneAndDelete(...)`
+ *                            (deconstruct pipeline into the wire command's filter/sort/skip slots).
+ * `LeadingMatch`           — internal marker tracking whether the chain is still
+ *                            in its leading-`$match` prefix. Flips to `'past-leading'`
+ *                            after the first non-`$match` stage, which lets
+ *                            `match()` clear `UpdateEnabled` on second `$match`
+ *                            stages that sit past the prefix (and would otherwise
+ *                            fail at runtime inside `deconstructUpdateChain`).
+ *
+ * Each pipeline-stage method either preserves or clears these markers per
+ * the marker table (and rationale per row) in
+ * `docs/architecture docs/adrs/ADR 201 - State-machine pattern for typed DSL builders.md`.
+ *
+ * The markers exist only at the type level; nothing reads them at runtime.
+ * Value literals are self-identifying so the slots are distinguishable in
+ * hover tooltips and error messages (e.g. `'update-ok'` vs `'fam-ok'`).
+ */
+type UpdateEnabled = 'update-ok' | 'update-cleared';
+type FindAndModifyEnabled = 'fam-ok' | 'fam-cleared';
+type LeadingMatch = 'leading' | 'past-leading';
+//#endregion
+//#region src/builder.d.ts
+interface PipelineChainState {
+  readonly collection: string;
+  readonly stages: ReadonlyArray<MongoPipelineStage>;
+  readonly storageHash: string;
+}
+/**
+ * The pipeline state in the query-builder state machine.
+ *
+ * Reached from `CollectionHandle` or `FilteredCollection` after the first
+ * pipeline-stage method call (or directly via `aggregate()` shortcuts). Holds
+ * the accumulated `MongoPipelineStage[]` and exposes pipeline-stage methods,
+ * the `merge`/`out` write terminals, and the `build`/`aggregate` read
+ * terminals.
+ *
+ * Two phantom type parameters gate the conditional terminals:
+ *
+ *  - `U extends UpdateEnabled` — when `'update-ok'`, the no-arg `updateMany()` /
+ *    `updateOne()` form is available (consume the chain as an
+ *    update-with-pipeline spec). Cleared by stages that produce content the
+ *    `update` AST cannot represent (e.g. `$group`, `$lookup`, `$limit`).
+ *  - `F extends FindAndModifyEnabled` — when `'fam-ok'`, the
+ *    `findOneAndUpdate(...)` / `findOneAndDelete(...)` terminals are
+ *    available. Cleared by stages incompatible with their wire-command slots
+ *    (`$limit`, `$group`, mutating stages, …).
+ *
+ * The marker semantics are encoded in the per-method return types — see the
+ * marker table (and rationale per row) in
+ * `docs/architecture docs/adrs/ADR 201 - State-machine pattern for typed DSL builders.md`.
+ */
+declare class PipelineChain<TContract extends MongoContractWithTypeMaps<MongoContract, MongoTypeMaps>, Shape extends DocShape, U extends UpdateEnabled = 'update-ok', F extends FindAndModifyEnabled = 'fam-ok', L extends LeadingMatch = 'leading', N$1 extends NestedDocShape = Record<string, never>> {
+  #private;
+  readonly __updateCompat: U;
+  readonly __findAndModifyCompat: F;
+  readonly __leadingMatch: L;
+  constructor(contract: TContract, state: PipelineChainState);
+  /**
+   * `$match`. `FindAndModifyEnabled` is always preserved. `UpdateEnabled` is
+   * preserved only while the chain is still in the leading-`$match` prefix
+   * (`L = 'leading'`); a `$match` that follows any non-`$match` stage
+   * transitions to `L = 'past-leading'` and clears `UpdateEnabled`, since
+   * `deconstructUpdateChain` can only peel leading `$match` stages into the
+   * wire-command filter.
+   */
+  match(filter: MongoFilterExpr): PipelineChain<TContract, Shape, L extends 'leading' ? U : 'update-cleared', F, L, N$1>;
+  match(fn: (fields: FieldAccessor<Shape, N$1>) => MongoFilterExpr): PipelineChain<TContract, Shape, L extends 'leading' ? U : 'update-cleared', F, L, N$1>;
+  /**
+   * `$sort`. Clears `UpdateEnabled` (`update` has no per-document sort) but
+   * preserves `FindAndModifyEnabled` (`findAndModify` has a `sort` slot).
+   */
+  sort(spec: SortSpec<Shape>): PipelineChain<TContract, Shape, 'update-cleared', F, 'past-leading', N$1>;
+  /**
+   * `$limit`. Clears both markers — `limit` is incompatible with the `update`
+   * wire command, and `findAndModify` already implies single-document
+   * semantics (so `.limit(...)` adds no meaning, only ambiguity).
+   */
+  limit(n: number): PipelineChain<TContract, Shape, 'update-cleared', 'fam-cleared', 'past-leading', N$1>;
+  /**
+   * `$skip`. Clears both markers — MongoDB's `findAndModify` wire command
+   * has no `skip` slot, so `deconstructFindAndModifyChain` rejects any
+   * `$skip` at runtime; keeping the marker `fam-cleared` makes the type
+   * system reflect the same constraint (see ADR 201 marker table).
+   */
+  skip(n: number): PipelineChain<TContract, Shape, 'update-cleared', 'fam-cleared', 'past-leading', N$1>;
+  sample(n: number): PipelineChain<TContract, Shape, 'update-cleared', 'fam-cleared', 'past-leading', N$1>;
+  /**
+   * `$addFields`. Preserves `UpdateEnabled` (representable as
+   * update-with-pipeline `$set`); clears `FindAndModifyEnabled` (no analogue
+   * in the find-and-modify wire commands). The nested-path shape `N` is
+   * preserved — newly added flat fields are reachable via property access
+   * (`f.newField`) but do not themselves carry nested structure.
+   */
+  addFields<NewFields extends Record<string, TypedAggExpr<DocField>>>(fn: (fields: FieldAccessor<Shape, N$1>) => NewFields): PipelineChain<TContract, Shape & ExtractDocShape<NewFields>, U, 'fam-cleared', 'past-leading', N$1>;
+  /**
+   * `$lookup`. Clears both markers — joins are not representable in either
+   * the `update` or `findAndModify` wire commands. The original document's
+   * nested-path shape `N` is preserved (the lookup adds a sidecar array
+   * field; existing keys are untouched).
+   */
+  lookup<ForeignRoot extends keyof TContract['roots'] & string, As extends string>(options: {
+    from: ForeignRoot;
+    localField: keyof Shape & string;
+    foreignField: string;
+    as: As;
+  }): PipelineChain<TContract, Shape & Record<As, {
+    readonly codecId: 'mongo/array@1';
+    readonly nullable: false;
+  }>, 'update-cleared', 'fam-cleared', 'past-leading', N$1>;
+  /**
+   * `$project`. Preserves `UpdateEnabled` (representable as update-with-pipeline
+   * `$project` / `$unset`); clears `FindAndModifyEnabled` (use `.project()` on
+   * the result of `.build()` if both projection and find-and-modify are
+   * needed — see spec).
+   *
+   * Resets the nested-path shape to `Record<string, never>` — projection
+   * fundamentally rewrites the document, so dot-paths into the *source*
+   * document are no longer meaningful downstream.
+   */
+  project<K$1 extends keyof Shape & string>(...keys: K$1[]): PipelineChain<TContract, Pick<Shape, K$1 | ('_id' extends keyof Shape ? '_id' : never)>, U, 'fam-cleared', 'past-leading'>;
+  project<Spec extends Record<string, 1 | TypedAggExpr<DocField>>>(fn: (fields: FieldAccessor<Shape, N$1>) => Spec): PipelineChain<TContract, ProjectedShape<Shape, Spec>, U, 'fam-cleared', 'past-leading'>;
+  /**
+   * `$unwind`. Clears both markers — array unrolling produces multiple output
+   * documents per input, incompatible with both single-document update and
+   * find-and-modify wire commands. The original `N` is preserved: unwind
+   * replaces the unwound array slot with its element but leaves the rest
+   * of the document structurally intact.
+   */
+  unwind<K$1 extends keyof Shape & string>(field: K$1, options?: {
+    preserveNullAndEmptyArrays?: boolean;
+  }): PipelineChain<TContract, UnwoundShape<Shape, K$1>, 'update-cleared', 'fam-cleared', 'past-leading', N$1>;
+  /**
+   * `$group`. Clears both markers — group output bears no relation to source
+   * documents; neither `update` nor `findAndModify` can consume it. Nested
+   * path shape is reset (the source document's path tree is gone).
+   */
+  group<Spec extends GroupSpec>(fn: (fields: FieldAccessor<Shape, N$1>) => Spec): PipelineChain<TContract, GroupedDocShape<Spec>, 'update-cleared', 'fam-cleared', 'past-leading'>;
+  /**
+   * `$replaceRoot`. Preserves `UpdateEnabled` (representable as
+   * update-with-pipeline `$replaceRoot`); clears `FindAndModifyEnabled`.
+   * Nested path shape is reset — the replaced root has no relation to
+   * the original document structure.
+   */
+  replaceRoot<NewShape extends DocShape>(fn: (fields: FieldAccessor<Shape, N$1>) => Expression<DocField> | TypedAggExpr<DocField>): PipelineChain<TContract, NewShape, U, 'fam-cleared', 'past-leading'>;
+  count<Field extends string>(field: Field): PipelineChain<TContract, Record<Field, {
+    readonly codecId: 'mongo/double@1';
+    readonly nullable: false;
+  }>, 'update-cleared', 'fam-cleared', 'past-leading'>;
+  sortByCount<F2 extends DocField>(fn: (fields: FieldAccessor<Shape, N$1>) => Expression<F2> | TypedAggExpr<F2>): PipelineChain<TContract, {
+    _id: F2;
+    count: {
+      readonly codecId: 'mongo/double@1';
+      readonly nullable: false;
+    };
+  }, 'update-cleared', 'fam-cleared', 'past-leading'>;
+  /**
+   * `$redact`. Preserves `UpdateEnabled`; clears `FindAndModifyEnabled`.
+   * Shape- and nested-path-preserving (the document tree is unchanged).
+   */
+  redact(fn: (fields: FieldAccessor<Shape, N$1>) => Expression<DocField> | TypedAggExpr<DocField>): PipelineChain<TContract, Shape, U, 'fam-cleared', 'past-leading', N$1>;
+  /**
+   * `$out` write terminal. Materialises the pipeline output into
+   * `collection` (optionally in `db`), replacing any prior contents. Unlike
+   * the other pipeline-stage methods, this **terminates** the chain — it
+   * returns a `MongoQueryPlan` rather than another `PipelineChain`, since
+   * `$out` must be the final stage and there is nothing further to chain.
+   *
+   * Lane is `mongo-query` (matching all other terminals in this package) so
+   * middleware can dispatch on intent without inspecting the command.
+   *
+   * The result row stream is empty (`unknown` row type) — the data lives
+   * in the destination collection, not the response.
+   */
+  out(collection: string, db?: string): MongoQueryPlan<unknown, AggregateCommand>;
+  /**
+   * `$merge` write terminal. Streams the pipeline output into the target
+   * collection per the supplied merge semantics (`whenMatched` /
+   * `whenNotMatched`). Like `out()`, terminates the chain — `$merge` must
+   * be the final stage.
+   */
+  merge(options: {
+    into: string | {
+      db: string;
+      coll: string;
+    };
+    on?: string | ReadonlyArray<string>;
+    whenMatched?: string | ReadonlyArray<MongoUpdatePipelineStage>;
+    whenNotMatched?: string;
+  }): MongoQueryPlan<unknown, AggregateCommand>;
+  unionWith(collection: string, pipeline?: ReadonlyArray<MongoPipelineStage>): PipelineChain<TContract, Shape, 'update-cleared', 'fam-cleared', 'past-leading', N$1>;
+  bucket(options: {
+    groupBy: MongoAggExpr;
+    boundaries: ReadonlyArray<unknown>;
+    default_?: unknown;
+    output?: Record<string, MongoAggAccumulator>;
+  }): PipelineChain<TContract, DocShape, 'update-cleared', 'fam-cleared', 'past-leading'>;
+  bucketAuto(options: {
+    groupBy: MongoAggExpr;
+    buckets: number;
+    output?: Record<string, MongoAggAccumulator>;
+    granularity?: string;
+  }): PipelineChain<TContract, DocShape, 'update-cleared', 'fam-cleared', 'past-leading'>;
+  geoNear(options: {
+    near: unknown;
+    distanceField: string;
+    spherical?: boolean;
+    maxDistance?: number;
+    minDistance?: number;
+    query?: MongoFilterExpr;
+    key?: string;
+    distanceMultiplier?: number;
+    includeLocs?: string;
+  }): PipelineChain<TContract, DocShape, 'update-cleared', 'fam-cleared', 'past-leading'>;
+  facet(facets: Record<string, ReadonlyArray<MongoPipelineStage>>): PipelineChain<TContract, DocShape, 'update-cleared', 'fam-cleared', 'past-leading'>;
+  graphLookup(options: {
+    from: string;
+    startWith: MongoAggExpr;
+    connectFromField: string;
+    connectToField: string;
+    as: string;
+    maxDepth?: number;
+    depthField?: string;
+    restrictSearchWithMatch?: MongoFilterExpr;
+  }): PipelineChain<TContract, DocShape, 'update-cleared', 'fam-cleared', 'past-leading'>;
+  setWindowFields(options: {
+    partitionBy?: MongoAggExpr;
+    sortBy?: Record<string, 1 | -1>;
+    output: Record<string, MongoWindowField>;
+  }): PipelineChain<TContract, DocShape, 'update-cleared', 'fam-cleared', 'past-leading'>;
+  densify(options: {
+    field: string;
+    partitionByFields?: ReadonlyArray<string>;
+    range: MongoDensifyRange;
+  }): PipelineChain<TContract, Shape, 'update-cleared', 'fam-cleared', 'past-leading', N$1>;
+  fill(options: {
+    partitionBy?: MongoAggExpr;
+    partitionByFields?: ReadonlyArray<string>;
+    sortBy?: Record<string, 1 | -1>;
+    output: Record<string, MongoFillOutput>;
+  }): PipelineChain<TContract, Shape, 'update-cleared', 'fam-cleared', 'past-leading', N$1>;
+  search(config: Record<string, unknown>, index?: string): PipelineChain<TContract, Shape, 'update-cleared', 'fam-cleared', 'past-leading', N$1>;
+  searchMeta(config: Record<string, unknown>, index?: string): PipelineChain<TContract, DocShape, 'update-cleared', 'fam-cleared', 'past-leading'>;
+  vectorSearch(options: {
+    index: string;
+    path: string;
+    queryVector: ReadonlyArray<number>;
+    numCandidates: number;
+    limit: number;
+    filter?: Record<string, unknown>;
+  }): PipelineChain<TContract, Shape, 'update-cleared', 'fam-cleared', 'past-leading', N$1>;
+  pipe(stage: MongoPipelineStage): PipelineChain<TContract, Shape, 'update-cleared', 'fam-cleared', 'past-leading'>;
+  pipe<NewShape extends DocShape>(stage: MongoPipelineStage): PipelineChain<TContract, NewShape, 'update-cleared', 'fam-cleared', 'past-leading'>;
+  /**
+   * No-arg `updateMany()`: deconstruct the chain into leading `$match`
+   * stages (folded into the filter) and remaining stages (which must all
+   * be valid pipeline-update stages). Available only when `U = 'update-ok'`.
+   *
+   * The optional callback parameter exists for subclass-override
+   * compatibility with `FilteredCollection.updateMany(updaterFn)` — TS's
+   * strict override check requires the parent's parameter to accept at
+   * least what the child's signature does. A runtime guard throws if a
+   * callback is actually passed on a bare `PipelineChain`. Note that
+   * because nothing in the public surface transitions `U` from
+   * `'update-cleared'` (the initial state on `CollectionHandle` /
+   * `FilteredCollection`) back to `'update-ok'`, the no-arg form is
+   * reachable only via explicit type casts in internal tests — the
+   * callback-form "type hole" is therefore not reachable from user
+   * code. See `docs/architecture docs/adrs/ADR 201 - State-machine
+   * pattern for typed DSL builders.md` for the marker-transition table.
+   */
+  updateMany(this: PipelineChain<TContract, Shape, 'update-ok', F, L, N$1>, updaterFn?: (fields: FieldAccessor<Shape, N$1>) => UpdaterResult): MongoQueryPlan<UpdateResult$1, UpdateManyCommand>;
+  /**
+   * No-arg `updateOne()`: same as `updateMany()` but maps to a single-doc
+   * update. Carries the same optional-callback/subclass-compat caveat
+   * documented above — the callback form is reachable only via forced
+   * casts in internal tests.
+   */
+  updateOne(this: PipelineChain<TContract, Shape, 'update-ok', F, L, N$1>, updaterFn?: (fields: FieldAccessor<Shape, N$1>) => UpdaterResult): MongoQueryPlan<UpdateResult$1, UpdateOneCommand>;
+  /**
+   * Find a single document matching the accumulated pipeline (which must
+   * consist solely of leading `$match` stages followed by at most one
+   * `$sort`) and apply `updaterFn`. Available only when
+   * `FindAndModifyEnabled` is `'fam-ok'` — stages that clear the marker
+   * (including `$skip`, which MongoDB's `findAndModify` has no slot for)
+   * make this method invisible at the type level.
+   *
+   * The pipeline stages are deconstructed into the wire command's `filter`
+   * and `sort` slots. If any non-deconstructable stage is present, a
+   * runtime error is thrown as a defensive check (the type system should
+   * prevent this).
+   */
+  findOneAndUpdate(this: PipelineChain<TContract, Shape, U, 'fam-ok', L, N$1>, updaterFn: (fields: FieldAccessor<Shape, N$1>) => UpdaterResult, opts?: {
+    readonly upsert?: boolean;
+    readonly returnDocument?: 'before' | 'after';
+  }): MongoQueryPlan<ResolveRow<Shape, ExtractMongoCodecTypes<TContract>> | null, FindOneAndUpdateCommand>;
+  /**
+   * Find a single document matching the accumulated pipeline and delete it.
+   * Same marker gating and deconstruction as `findOneAndUpdate`.
+   */
+  findOneAndDelete(this: PipelineChain<TContract, Shape, U, 'fam-ok', L, N$1>): MongoQueryPlan<ResolveRow<Shape, ExtractMongoCodecTypes<TContract>> | null, FindOneAndDeleteCommand>;
+  /**
+   * Materialise the chain as a `MongoQueryPlan` wrapping an `AggregateCommand`.
+   */
+  build(): MongoQueryPlan<ResolveRow<Shape, ExtractMongoCodecTypes<TContract>>, AggregateCommand>;
+  /**
+   * Alias for `build()` — surfaces the read intent at the call site.
+   */
+  aggregate(): MongoQueryPlan<ResolveRow<Shape, ExtractMongoCodecTypes<TContract>>, AggregateCommand>;
+}
+//#endregion
+//#region src/expression-helpers.d.ts
+declare function literal(value: string): TypedAggExpr<StringField>;
+declare function literal(value: number): TypedAggExpr<NumericField>;
+declare function literal(value: boolean): TypedAggExpr<BooleanField>;
+declare function literal(value: Date): TypedAggExpr<DateField>;
+declare function literal<F extends DocField>(value: LiteralValue<F>): TypedAggExpr<F>;
+declare const fn: {
+  add(...args: TypedAggExpr<DocField>[]): TypedAggExpr<NumericField>;
+  subtract(a: TypedAggExpr<DocField>, b: TypedAggExpr<DocField>): TypedAggExpr<NumericField>;
+  multiply(...args: TypedAggExpr<DocField>[]): TypedAggExpr<NumericField>;
+  divide(a: TypedAggExpr<DocField>, b: TypedAggExpr<DocField>): TypedAggExpr<NumericField>;
+  concat(...args: TypedAggExpr<DocField>[]): TypedAggExpr<StringField>;
+  toLower(a: TypedAggExpr<DocField>): TypedAggExpr<StringField>;
+  toUpper(a: TypedAggExpr<DocField>): TypedAggExpr<StringField>;
+  size(a: TypedAggExpr<DocField>): TypedAggExpr<NumericField>;
+  cond<F extends DocField>(condition: MongoAggExpr, thenExpr: TypedAggExpr<F>, elseExpr: TypedAggExpr<DocField>): TypedAggExpr<F>;
+  literal: typeof literal;
+  year(a: TypedAggExpr<DocField>): TypedAggExpr<NumericField>;
+  month(a: TypedAggExpr<DocField>): TypedAggExpr<NumericField>;
+  dayOfMonth(a: TypedAggExpr<DocField>): TypedAggExpr<NumericField>;
+  hour(a: TypedAggExpr<DocField>): TypedAggExpr<NumericField>;
+  minute(a: TypedAggExpr<DocField>): TypedAggExpr<NumericField>;
+  second(a: TypedAggExpr<DocField>): TypedAggExpr<NumericField>;
+  millisecond(a: TypedAggExpr<DocField>): TypedAggExpr<NumericField>;
+  dateToString(args: {
+    date: TypedAggExpr<DateField>;
+    format?: TypedAggExpr<StringField>;
+    timezone?: TypedAggExpr<StringField>;
+    onNull?: TypedAggExpr<DocField>;
+  }): TypedAggExpr<StringField>;
+  dateFromString(args: {
+    dateString: TypedAggExpr<StringField>;
+    format?: TypedAggExpr<StringField>;
+    timezone?: TypedAggExpr<StringField>;
+    onError?: TypedAggExpr<DocField>;
+    onNull?: TypedAggExpr<DocField>;
+  }): TypedAggExpr<DateField>;
+  dateDiff(args: {
+    startDate: TypedAggExpr<DateField>;
+    endDate: TypedAggExpr<DateField>;
+    unit: TypedAggExpr<StringField>;
+    timezone?: TypedAggExpr<StringField>;
+    startOfWeek?: TypedAggExpr<StringField>;
+  }): TypedAggExpr<NumericField>;
+  dateAdd(args: {
+    startDate: TypedAggExpr<DateField>;
+    unit: TypedAggExpr<StringField>;
+    amount: TypedAggExpr<NumericField>;
+    timezone?: TypedAggExpr<StringField>;
+  }): TypedAggExpr<DateField>;
+  dateSubtract(args: {
+    startDate: TypedAggExpr<DateField>;
+    unit: TypedAggExpr<StringField>;
+    amount: TypedAggExpr<NumericField>;
+    timezone?: TypedAggExpr<StringField>;
+  }): TypedAggExpr<DateField>;
+  dateTrunc(args: {
+    date: TypedAggExpr<DateField>;
+    unit: TypedAggExpr<StringField>;
+    binSize?: TypedAggExpr<NumericField>;
+    timezone?: TypedAggExpr<StringField>;
+    startOfWeek?: TypedAggExpr<StringField>;
+  }): TypedAggExpr<DateField>;
+  substr(str: TypedAggExpr<DocField>, start: TypedAggExpr<DocField>, length: TypedAggExpr<DocField>): TypedAggExpr<StringField>;
+  substrBytes(str: TypedAggExpr<DocField>, start: TypedAggExpr<DocField>, count: TypedAggExpr<DocField>): TypedAggExpr<StringField>;
+  trim(args: {
+    input: TypedAggExpr<StringField>;
+    chars?: TypedAggExpr<StringField>;
+  }): TypedAggExpr<StringField>;
+  ltrim(args: {
+    input: TypedAggExpr<StringField>;
+    chars?: TypedAggExpr<StringField>;
+  }): TypedAggExpr<StringField>;
+  rtrim(args: {
+    input: TypedAggExpr<StringField>;
+    chars?: TypedAggExpr<StringField>;
+  }): TypedAggExpr<StringField>;
+  split(str: TypedAggExpr<DocField>, delimiter: TypedAggExpr<DocField>): TypedAggExpr<ArrayField>;
+  strLenCP(a: TypedAggExpr<DocField>): TypedAggExpr<NumericField>;
+  strLenBytes(a: TypedAggExpr<DocField>): TypedAggExpr<NumericField>;
+  regexMatch(args: {
+    input: TypedAggExpr<StringField>;
+    regex: TypedAggExpr<StringField>;
+    options?: TypedAggExpr<StringField>;
+  }): TypedAggExpr<BooleanField>;
+  regexFind(args: {
+    input: TypedAggExpr<StringField>;
+    regex: TypedAggExpr<StringField>;
+    options?: TypedAggExpr<StringField>;
+  }): TypedAggExpr<DocField>;
+  regexFindAll(args: {
+    input: TypedAggExpr<StringField>;
+    regex: TypedAggExpr<StringField>;
+    options?: TypedAggExpr<StringField>;
+  }): TypedAggExpr<ArrayField>;
+  replaceOne(args: {
+    input: TypedAggExpr<StringField>;
+    find: TypedAggExpr<StringField>;
+    replacement: TypedAggExpr<StringField>;
+  }): TypedAggExpr<StringField>;
+  replaceAll(args: {
+    input: TypedAggExpr<StringField>;
+    find: TypedAggExpr<StringField>;
+    replacement: TypedAggExpr<StringField>;
+  }): TypedAggExpr<StringField>;
+  cmp(a: TypedAggExpr<DocField>, b: TypedAggExpr<DocField>): TypedAggExpr<NumericField>;
+  eq(a: TypedAggExpr<DocField>, b: TypedAggExpr<DocField>): TypedAggExpr<BooleanField>;
+  ne(a: TypedAggExpr<DocField>, b: TypedAggExpr<DocField>): TypedAggExpr<BooleanField>;
+  gt(a: TypedAggExpr<DocField>, b: TypedAggExpr<DocField>): TypedAggExpr<BooleanField>;
+  gte(a: TypedAggExpr<DocField>, b: TypedAggExpr<DocField>): TypedAggExpr<BooleanField>;
+  lt(a: TypedAggExpr<DocField>, b: TypedAggExpr<DocField>): TypedAggExpr<BooleanField>;
+  lte(a: TypedAggExpr<DocField>, b: TypedAggExpr<DocField>): TypedAggExpr<BooleanField>;
+  arrayElemAt(arr: TypedAggExpr<DocField>, idx: TypedAggExpr<DocField>): TypedAggExpr<NullableDocField>;
+  concatArrays(...args: TypedAggExpr<DocField>[]): TypedAggExpr<ArrayField>;
+  firstElem(a: TypedAggExpr<DocField>): TypedAggExpr<NullableDocField>;
+  lastElem(a: TypedAggExpr<DocField>): TypedAggExpr<NullableDocField>;
+  isIn(elem: TypedAggExpr<DocField>, arr: TypedAggExpr<DocField>): TypedAggExpr<BooleanField>;
+  indexOfArray(arr: TypedAggExpr<DocField>, value: TypedAggExpr<DocField>, ...rest: TypedAggExpr<DocField>[]): TypedAggExpr<NumericField>;
+  isArray(a: TypedAggExpr<DocField>): TypedAggExpr<BooleanField>;
+  reverseArray(a: TypedAggExpr<DocField>): TypedAggExpr<ArrayField>;
+  slice(arr: TypedAggExpr<DocField>, ...rest: TypedAggExpr<DocField>[]): TypedAggExpr<ArrayField>;
+  zip(args: {
+    inputs: TypedAggExpr<ArrayField>[];
+    useLongestLength?: TypedAggExpr<BooleanField>;
+    defaults?: TypedAggExpr<ArrayField>;
+  }): TypedAggExpr<ArrayField>;
+  range(start: TypedAggExpr<DocField>, end: TypedAggExpr<DocField>, step: TypedAggExpr<DocField>): TypedAggExpr<ArrayField>;
+  setUnion(...args: TypedAggExpr<DocField>[]): TypedAggExpr<ArrayField>;
+  setIntersection(...args: TypedAggExpr<DocField>[]): TypedAggExpr<ArrayField>;
+  setDifference(a: TypedAggExpr<DocField>, b: TypedAggExpr<DocField>): TypedAggExpr<ArrayField>;
+  setEquals(...args: TypedAggExpr<DocField>[]): TypedAggExpr<BooleanField>;
+  setIsSubset(a: TypedAggExpr<DocField>, b: TypedAggExpr<DocField>): TypedAggExpr<BooleanField>;
+  anyElementTrue(a: TypedAggExpr<DocField>): TypedAggExpr<BooleanField>;
+  allElementsTrue(a: TypedAggExpr<DocField>): TypedAggExpr<BooleanField>;
+  typeOf(a: TypedAggExpr<DocField>): TypedAggExpr<StringField>;
+  convert(args: {
+    input: TypedAggExpr<DocField>;
+    to: TypedAggExpr<StringField | NumericField>;
+    onError?: TypedAggExpr<DocField>;
+    onNull?: TypedAggExpr<DocField>;
+  }): TypedAggExpr<DocField>;
+  toInt(a: TypedAggExpr<DocField>): TypedAggExpr<NumericField>;
+  toLong(a: TypedAggExpr<DocField>): TypedAggExpr<NumericField>;
+  toDouble(a: TypedAggExpr<DocField>): TypedAggExpr<NumericField>;
+  toDecimal(a: TypedAggExpr<DocField>): TypedAggExpr<NumericField>;
+  toString_(a: TypedAggExpr<DocField>): TypedAggExpr<StringField>;
+  toObjectId(a: TypedAggExpr<DocField>): TypedAggExpr<DocField>;
+  toBool(a: TypedAggExpr<DocField>): TypedAggExpr<BooleanField>;
+  toDate(a: TypedAggExpr<DocField>): TypedAggExpr<DateField>;
+  objectToArray(a: TypedAggExpr<DocField>): TypedAggExpr<ArrayField>;
+  arrayToObject(a: TypedAggExpr<DocField>): TypedAggExpr<DocField>;
+  getField(args: {
+    field: TypedAggExpr<StringField>;
+    input?: TypedAggExpr<DocField>;
+  }): TypedAggExpr<DocField>;
+  setField(args: {
+    field: TypedAggExpr<StringField>;
+    input: TypedAggExpr<DocField>;
+    value: TypedAggExpr<DocField>;
+  }): TypedAggExpr<DocField>;
+};
+//#endregion
+//#region src/state-classes.d.ts
+/**
+ * Root state of the query-builder state machine. Returned from
+ * `mongoQuery(...).from(name)` and bound to a single collection.
+ *
+ * Inherits the entire pipeline-stage surface from `PipelineChain` (since an
+ * empty `CollectionHandle` is observably an empty pipeline). Adds:
+ *
+ *  - `match(...)` — overridden to transition to `FilteredCollection`, which
+ *    accumulates filters for eventual splatting into write/find-and-modify
+ *    wire commands.
+ *  - **Insert / unqualified-write methods** (M2): `insertOne`, `insertMany`,
+ *    `updateAll`, `deleteAll`. These live *only* here — the corresponding
+ *    methods are absent from `FilteredCollection`, so a caller cannot
+ *    accidentally produce an unqualified write by forgetting to `.match(...)`
+ *    later in the chain. Bodies land in M2.
+ */
+declare class CollectionHandle<TContract extends MongoContractWithTypeMaps<MongoContract, MongoTypeMaps>, ModelName extends keyof TContract['models'] & string> extends PipelineChain<TContract, ModelToDocShape<TContract, ModelName>, 'update-cleared', 'fam-cleared', 'leading', ModelNestedShape<TContract, ModelName>> {
+  #private;
+  constructor(ctx: BindingContext<TContract>, modelName: ModelName);
+  /**
+   * Bound model name. Exposed so type tests can assert the binding without
+   * flipping into a pipeline. Not part of the public-API contract.
+   */
+  get _modelName(): ModelName;
+  /**
+   * Begin accumulating a filter. Transitions to `FilteredCollection`.
+   *
+   * Overrides `PipelineChain.match` (which appends another `$match` stage
+   * and stays in the chain). The two implementations are semantically
+   * equivalent for the read terminal — multiple `$match` stages AND-fold in
+   * Mongo — but `FilteredCollection` makes the accumulated filter
+   * addressable for the write/find-and-modify terminals landing in M2/M3.
+   */
+  match(filter: MongoFilterExpr): FilteredCollection<TContract, ModelName>;
+  match(fn: (fields: FieldAccessor<ModelToDocShape<TContract, ModelName>, ModelNestedShape<TContract, ModelName>>) => MongoFilterExpr): FilteredCollection<TContract, ModelName>;
+  /**
+   * Insert a single document. Document fields are passed straight through to
+   * the wire `InsertOneCommand` — codec normalisation happens at the
+   * adapter/driver boundary, identically to the SQL builder (see Open Item
+   * #14 confirmation in the design conversation).
+   *
+   * Returns a `MongoQueryPlan<InsertOneResult>` whose row stream yields a
+   * single result document with the server-assigned `insertedId`.
+   */
+  insertOne(document: Record<string, MongoValue>): MongoQueryPlan<InsertOneResult$1, InsertOneCommand>;
+  /**
+   * Insert a batch of documents. Order is preserved in the returned
+   * `insertedIds` array.
+   */
+  insertMany(documents: ReadonlyArray<Record<string, MongoValue>>): MongoQueryPlan<InsertManyResult$1, InsertManyCommand>;
+  /**
+   * Update *every* document in the collection. Lives only on
+   * `CollectionHandle` — the corresponding method is intentionally absent
+   * from `FilteredCollection` so a caller cannot accidentally produce an
+   * unqualified write by forgetting to `.match(...)` first. Pair with
+   * `.match(...).updateMany(...)` for the filtered case.
+   */
+  updateAll(updaterFn: (fields: FieldAccessor<ModelToDocShape<TContract, ModelName>, ModelNestedShape<TContract, ModelName>>) => UpdaterResult): MongoQueryPlan<UpdateResult$1, UpdateManyCommand>;
+  /**
+   * Delete *every* document in the collection. See `updateAll` for the
+   * rationale around the unqualified-write surface being limited to this
+   * state class.
+   */
+  deleteAll(): MongoQueryPlan<DeleteResult$1, DeleteManyCommand>;
+  /**
+   * Insert-or-update the document matching `filterFn`. The filter is
+   * mandatory (vs. `updateAll`'s tautological match) because an upsert
+   * without a discriminating predicate would either match every existing
+   * document or insert an indistinguishable new one.
+   *
+   * Maps to `UpdateOneCommand` with `upsert: true`. The driver inserts a
+   * new document derived from the filter equality fields plus the update
+   * spec when no match is found; otherwise updates the matched document.
+   */
+  upsertOne(filterFn: (fields: FieldAccessor<ModelToDocShape<TContract, ModelName>, ModelNestedShape<TContract, ModelName>>) => MongoFilterExpr, updaterFn: (fields: FieldAccessor<ModelToDocShape<TContract, ModelName>, ModelNestedShape<TContract, ModelName>>) => UpdaterResult): MongoQueryPlan<UpdateResult$1, UpdateOneCommand>;
+}
+/**
+ * State reached after one or more `.match(...)` calls on `CollectionHandle`.
+ *
+ * Inherits the pipeline-stage surface from `PipelineChain`, with the
+ * accumulated filters baked in as a leading `$match` stage on the underlying
+ * pipeline state. This means read-terminal output (`.aggregate()` /
+ * `.build()`) and any subsequent pipeline-stage chain see the filtered
+ * collection as input — the read story works through pure inheritance.
+ *
+ * Adds:
+ *
+ *  - `match(...)` — pushes another `$match` stage *and* records the filter in
+ *    the accumulator, so the eventual write/find-and-modify terminal can
+ *    splat the AND-folded filter into the wire command's `filter` slot.
+ *  - **Filtered writes** (M2): `updateMany`, `updateOne`, `deleteMany`,
+ *    `deleteOne`, `upsertOne`. Stubbed in M1. (Upsert-many is an open
+ *    question in the spec — see TML-2267 — and is intentionally absent.)
+ *  - **Find-and-modify** (M3): `findOneAndUpdate`, `findOneAndDelete`.
+ *    Stubbed in M1.
+ *
+ * Notably *does not* expose `insertOne`/`insertMany`/`updateAll`/`deleteAll`
+ * — those are insert or unqualified-write operations that are nonsense
+ * after a filter has been applied.
+ */
+declare class FilteredCollection<TContract extends MongoContractWithTypeMaps<MongoContract, MongoTypeMaps>, ModelName extends keyof TContract['models'] & string> extends PipelineChain<TContract, ModelToDocShape<TContract, ModelName>, 'update-cleared', 'fam-cleared', 'leading', ModelNestedShape<TContract, ModelName>> {
+  #private;
+  constructor(ctx: BindingContext<TContract>, modelName: ModelName, filters: ReadonlyArray<MongoFilterExpr>);
+  get _modelName(): ModelName;
+  /**
+   * Accumulated filter list. Exposed for the M2/M3 write/find-and-modify
+   * terminals to splat into wire-command `filter` slots; not part of the
+   * public-API contract.
+   */
+  get _filters(): ReadonlyArray<MongoFilterExpr>;
+  /**
+   * Append another filter to the accumulator. Returns a new
+   * `FilteredCollection` whose underlying pipeline rebuilds the leading
+   * `$match` from the AND-folded accumulator (rather than appending a
+   * second `$match` stage), so the write/find-and-modify terminals see a
+   * single authoritative filter expression.
+   */
+  match(filter: MongoFilterExpr): FilteredCollection<TContract, ModelName>;
+  match(fn: (fields: FieldAccessor<ModelToDocShape<TContract, ModelName>, ModelNestedShape<TContract, ModelName>>) => MongoFilterExpr): FilteredCollection<TContract, ModelName>;
+  /**
+   * Update every matching document. `updaterFn` receives a `FieldAccessor`
+   * and returns an array of `TypedUpdateOp` (e.g. `[f.amount.inc(1),
+   * f.status.set('done')]`). Operators are folded into the wire-format
+   * update spec by `foldUpdateOps`, which throws on operator+path
+   * collisions.
+   */
+  updateMany(updaterFn: (fields: FieldAccessor<ModelToDocShape<TContract, ModelName>, ModelNestedShape<TContract, ModelName>>) => UpdaterResult): MongoQueryPlan<UpdateResult$1, UpdateManyCommand>;
+  /**
+   * Update at most one matching document. The driver picks the document
+   * (typically the first one matched by the underlying scan); no ordering
+   * guarantee is implied — chain `.sort(...)` and use the M3
+   * `.findOneAndUpdate(...)` terminal when ordering matters.
+   */
+  updateOne(updaterFn: (fields: FieldAccessor<ModelToDocShape<TContract, ModelName>, ModelNestedShape<TContract, ModelName>>) => UpdaterResult): MongoQueryPlan<UpdateResult$1, UpdateOneCommand>;
+  /**
+   * Delete every matching document.
+   */
+  deleteMany(): MongoQueryPlan<DeleteResult$1, DeleteManyCommand>;
+  /**
+   * Delete at most one matching document. See the `updateOne` note about
+   * driver-chosen victim selection.
+   */
+  deleteOne(): MongoQueryPlan<DeleteResult$1, DeleteOneCommand>;
+  /**
+   * Insert-or-update against the accumulated filter. Maps to
+   * `UpdateOneCommand` with `upsert: true`. Equivalent to
+   * `CollectionHandle.upsertOne(f => filter, updaterFn)` but reuses the
+   * already-accumulated `.match(...)` filter chain.
+   */
+  upsertOne(updaterFn: (fields: FieldAccessor<ModelToDocShape<TContract, ModelName>, ModelNestedShape<TContract, ModelName>>) => UpdaterResult): MongoQueryPlan<UpdateResult$1, UpdateOneCommand>;
+  /**
+   * Find a single matching document and apply `updaterFn` to it.
+   *
+   * `opts.upsert` (default `false`) toggles insert-on-miss behaviour.
+   * `opts.returnDocument` (default `'after'`) controls whether the row
+   * stream yields the document as it was before or after the update.
+   */
+  findOneAndUpdate(updaterFn: (fields: FieldAccessor<ModelToDocShape<TContract, ModelName>, ModelNestedShape<TContract, ModelName>>) => UpdaterResult, opts?: {
+    readonly upsert?: boolean;
+    readonly returnDocument?: 'before' | 'after';
+  }): MongoQueryPlan<ResolveRow<ModelToDocShape<TContract, ModelName>, ExtractMongoCodecTypes<TContract>> | null, FindOneAndUpdateCommand>;
+  /**
+   * Find a single matching document and delete it. Returns the deleted
+   * document via the row stream.
+   */
+  findOneAndDelete(): MongoQueryPlan<ResolveRow<ModelToDocShape<TContract, ModelName>, ExtractMongoCodecTypes<TContract>> | null, FindOneAndDeleteCommand>;
+}
+/**
+ * Bound execution context shared across the three state classes.
+ */
+interface BindingContext<TContract extends MongoContractWithTypeMaps<MongoContract, MongoTypeMaps>> {
+  readonly contract: TContract;
+  readonly collection: string;
+  readonly storageHash: string;
+}
+//#endregion
+//#region src/query.d.ts
+/**
+ * Public entry point of the query builder. `mongoQuery(...).from(rootName)`
+ * yields the root state of the three-state machine
+ * (`CollectionHandle` → `FilteredCollection` → `PipelineChain`).
+ *
+ * `rawCommand(cmd)` is the escape hatch for cases the typed surface does
+ * not cover (yet) — it accepts any `AnyMongoCommand` (typed CRUD or a
+ * `RawMongoCommand` of `Document`s) and packages it into a `MongoQueryPlan`
+ * with `lane: 'mongo-query'`. Row type is `unknown` because the runtime
+ * cannot know what the caller's command yields.
+ */
+interface QueryRoot<TContract extends MongoContractWithTypeMaps<MongoContract, MongoTypeMaps>> {
+  from<K$1 extends keyof TContract['roots'] & string>(rootName: K$1): CollectionHandle<TContract, TContract['roots'][K$1] & string & keyof TContract['models']>;
+  rawCommand<C$1 extends AnyMongoCommand>(command: C$1): MongoQueryPlan<unknown, C$1>;
+}
+declare function mongoQuery<TContract extends MongoContractWithTypeMaps<MongoContract, MongoTypeMaps>>(options: {
+  contractJson: unknown;
+}): QueryRoot<TContract>;
+//#endregion
+export { type ArrayField, type BooleanField, CollectionHandle, type DateField, type DeleteResult, type DocField, type DocShape, type Expression, type ExtractDocShape, type FieldAccessor, FilteredCollection, type FindAndModifyEnabled, type GroupSpec, type GroupedDocShape, type InsertManyResult, type InsertOneResult, type LeafExpression, type LiteralValue, type ModelNestedShape, type ModelToDocShape, type NestedDocShape, type NullableDocField, type NullableNumericField, type NumericField, type ObjectExpression, type ObjectField, type PathCompletions, PipelineChain, type ProjectedShape, type QueryRoot, type ResolvePath, type ResolveRow, type SortSpec, type StringField, type TypedAccumulatorExpr, type TypedAggExpr, type TypedUpdateOp, type UnwoundShape, type UpdateEnabled, type UpdateResult, type UpdaterResult, type ValidPaths, acc, createFieldAccessor, fn, mongoQuery };
+//# sourceMappingURL=index.d.mts.map