@prisma/orm-family-mongo 0.16.0-dev.36

package/dist/query-builder.d.mts

@@ -0,0 +1,836 @@
+import { C as MongoContract, V as MongoModelsMap, at as RootModelName, n as ExtractMongoCodecTypes, t as AnyMongoTypeMaps, w as MongoContractWithTypeMaps, z as MongoModelDefinition } from "./mongo-value-set-tNn9-pun-dJYx_rVD.mjs";
+import "./index-Cd2zLiU6.mjs";
+import { c as MongoValue } from "./index-wKMm41HC.mjs";
+import { B as MongoFilterExpr, L as MongoFieldShape, Mt as UpdateManyCommand, Nt as UpdateOneCommand, R as MongoFillOutput, a as DeleteOneCommand, c as InsertManyCommand, d as MongoAggAccumulator, et as MongoPipelineStage, i as DeleteManyCommand, j as MongoDensifyRange, l as InsertOneCommand, m as MongoAggExpr, n as AggregateCommand, o as FindOneAndDeleteCommand, ot as MongoResultShape, r as AnyMongoCommand, rt as MongoQueryPlan, s as FindOneAndUpdateCommand, vt as MongoUpdatePipelineStage, xt as MongoWindowField } from "./query-plan-C0-Yu8hf-DdilEdW6.mjs";
+import { a as InsertOneResult, c as UpdateResult, i as InsertManyResult, r as DeleteResult } from "./execution-CKnUiOfm.mjs";
+import { A as TypedUpdateOp, C as ProjectedShape, D as StringField, E as SortSpec, F as expr, M as UpdaterResult, N as ValidPaths, O as TypedAccumulatorExpr, P as createFieldAccessor, S as PathCompletions, T as ResolveRow, _ as NullableDocField, a as DocShape, b as ObjectExpression, c as FieldAccessor, d as LeafExpression, f as LiteralValue, g as NestedDocShape, h as ModelToDocShape, i as DocField, j as UnwoundShape, k as TypedAggExpr, l as GroupSpec, m as ModelNestedShape, n as BooleanField, o as Expression, p as ModelArrayField, r as DateField, s as ExtractDocShape, t as ArrayField, u as GroupedDocShape, v as NullableNumericField, w as ResolvePath, x as ObjectField, y as NumericField } from "./field-accessor-DHsAPiW3-BdYCspQC.mjs";
+import { ContractField } from "@prisma/orm-framework/contract/types";
+//#region ../../../2-mongo-family/5-query-builders/query-builder/dist/index.d.mts
+//#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/lookup-builder.d.ts
+/**
+ * Resolved foreign-model name for a contract root. Looks `RootName` up
+ * through `TContract['roots']` and extracts the referenced model name
+ * so it can be used as a `ModelName` index into `models`. Resolves to
+ * `never` when the root is not present (this surface should never be
+ * reachable through normal use because `from()` constrains its `R`
+ * parameter to `keyof TContract['roots']`).
+ */
+type ModelOf<TContract extends MongoContract, RootName extends keyof TContract['roots'] & string> = RootModelName<TContract, RootName>;
+/**
+ * Object returned by the user from the `on(...)` callback. Each side is
+ * a `LeafExpression` produced by property access on the corresponding
+ * `FieldAccessor` (`local._id`, `foreign.customerId`, etc.). Carrying
+ * `LeafExpression` rather than the broader `TypedAggExpr` is what makes
+ * non-leaf returns (e.g. `fn.toUpper(local._id)`) a compile-time error
+ * without per-field operator gating — `LeafExpression` carries `_path`,
+ * `TypedAggExpr` does not (see field-accessor.ts L47–L82).
+ */
+interface LookupOnResult {
+  readonly local: LeafExpression<DocField>;
+  readonly foreign: LeafExpression<DocField>;
+}
+/**
+ * Marker brand on the captured spec returned by the `lookup(...)`
+ * callback. The phantom `_brand` literal lets `PipelineChain.lookup`
+ * accept the result of `from(...).on(...).as(...)` without exposing the
+ * internal field shape to user code, and prevents accidental
+ * construction of a malformed spec by hand.
+ */
+type LookupResultBrand = 'mongo-query-builder/lookup-result@1';
+/**
+ * Captured output of the inner `from(name).on(cb).as(name)` chain. The
+ * contract is consumed by `PipelineChain.lookup` to construct the
+ * `MongoLookupStage` (collection name comes from `models[ModelName]
+ * .storage.collection`) and to thread `ModelArrayField<ModelName>` into
+ * the resulting `Shape` so the resolver yields `Array<ForeignRow>`.
+ *
+ * Type parameters carry the foreign-root literal `RootName`, the
+ * resolved foreign model name `ModelName`, and the `As` literal so
+ * `PipelineChain.lookup`'s return type can encode the result-row
+ * promotion precisely.
+ */
+interface LookupResult<RootName extends string, ModelName extends string, As extends string> {
+  readonly _brand: LookupResultBrand;
+  readonly _root: RootName;
+  readonly _model: ModelName;
+  readonly _localField: string;
+  readonly _foreignField: string;
+  readonly _as: As;
+}
+/**
+ * Builder returned by `from(name).on(cb)`. Carries the foreign root /
+ * model literals plus the captured local / foreign paths, and exposes
+ * `.as(name)` to finalise the spec with the user-chosen field name.
+ */
+interface LookupBuilderWithKey<RootName extends string, ModelName extends string> {
+  as<As extends string>(name: As): LookupResult<RootName, ModelName, As>;
+}
+/**
+ * Builder returned by `from(name)`. Carries the foreign root / model
+ * literals and the local pipeline's `Shape` / nested shape so the
+ * `on(...)` callback's `local` and `foreign` accessors are typed
+ * narrowly.
+ *
+ * `on(cb)` runs the user's callback to capture the leaf paths and
+ * returns a `LookupBuilderWithKey` that exposes `.as(name)`.
+ */
+interface LookupBuilder<TContract extends MongoContract, Shape extends DocShape, Nested extends Record<string, DocField>, RootName extends string, ModelName extends string> {
+  on(cb: (local: FieldAccessor<Shape, Nested>, foreign: ModelName extends keyof MongoModelsMap<TContract> & string ? FieldAccessor<ModelToDocShape<TContract, ModelName>, ModelNestedShape<TContract, ModelName>> : never) => LookupOnResult): LookupBuilderWithKey<RootName, ModelName>;
+}
+/**
+ * Type of the `from` callable passed to `PipelineChain.lookup`'s outer
+ * callback. The generic argument is inferred from a string-literal
+ * argument (the same pattern as `mongoQuery<TC>(...).from('orders')`),
+ * which grounds `RootName` into the returned `LookupBuilder` *before*
+ * the inner `on(...)` callback is type-checked. This sequential
+ * inference is what makes `foreign` resolve narrowly to the foreign
+ * model's `FieldAccessor` (verified in the R1.5 spike — see spec § Open
+ * Questions / Resolved decisions).
+ */
+type LookupFrom<TContract extends MongoContract, Shape extends DocShape, Nested extends Record<string, DocField>> = <RootName extends keyof TContract['roots'] & string>(name: RootName) => LookupBuilder<TContract, Shape, Nested, RootName, ModelOf<TContract, RootName>>;
+//#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;
+  readonly modelName?: 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, AnyMongoTypeMaps>, Shape extends DocShape, U extends UpdateEnabled = 'update-ok', F extends FindAndModifyEnabled = 'fam-ok', L extends LeadingMatch = 'leading', N 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>;
+  match(fn: (fields: FieldAccessor<Shape, N>) => MongoFilterExpr): PipelineChain<TContract, Shape, L extends 'leading' ? U : 'update-cleared', F, L, N>;
+  /**
+   * `$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>;
+  /**
+   * `$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>;
+  /**
+   * `$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>;
+  sample(n: number): PipelineChain<TContract, Shape, 'update-cleared', 'fam-cleared', 'past-leading', N>;
+  /**
+   * `$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>) => NewFields): PipelineChain<TContract, Shape & ExtractDocShape<NewFields>, U, 'fam-cleared', 'past-leading', N>;
+  /**
+   * `$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).
+   *
+   * The single callback receives a `from` callable that grounds the
+   * foreign-root literal sequentially before the inner `on(...)`
+   * callback is type-checked — see `lookup-builder.ts`. The resulting
+   * `Shape` gains the `As` key as a `ModelArrayField<ModelName>` so
+   * `ResolveRow` produces `Array<ForeignRow>` (with concrete leaf
+   * types) instead of the legacy `unknown[]`.
+   */
+  lookup<RootName extends string, ModelName extends string, As extends string>(fn: (from: LookupFrom<TContract, Shape, N>) => LookupResult<RootName, ModelName, As>): PipelineChain<TContract, Shape & Record<As, ModelArrayField<ModelName>>, 'update-cleared', 'fam-cleared', 'past-leading', N>;
+  /**
+   * `$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 extends keyof Shape & string>(...keys: K[]): PipelineChain<TContract, Pick<Shape, K | ('_id' extends keyof Shape ? '_id' : never)>, U, 'fam-cleared', 'past-leading'>;
+  project<Spec extends Record<string, 1 | TypedAggExpr<DocField>>>(fn: (fields: FieldAccessor<Shape, N>) => 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 extends keyof Shape & string>(field: K, options?: {
+    preserveNullAndEmptyArrays?: boolean;
+  }): PipelineChain<TContract, UnwoundShape<Shape, K>, 'update-cleared', 'fam-cleared', 'past-leading', N>;
+  /**
+   * `$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>) => 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>) => 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>) => 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>) => Expression<DocField> | TypedAggExpr<DocField>): PipelineChain<TContract, Shape, U, 'fam-cleared', 'past-leading', N>;
+  /**
+   * `$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>;
+  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>;
+  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>;
+  search(config: Record<string, unknown>, index?: string): PipelineChain<TContract, Shape, 'update-cleared', 'fam-cleared', 'past-leading', N>;
+  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>;
+  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>, updaterFn?: (fields: FieldAccessor<Shape, N>) => UpdaterResult): MongoQueryPlan<UpdateResult, 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>, updaterFn?: (fields: FieldAccessor<Shape, N>) => UpdaterResult): MongoQueryPlan<UpdateResult, 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>, updaterFn: (fields: FieldAccessor<Shape, N>) => UpdaterResult, opts?: {
+    readonly upsert?: boolean;
+    readonly returnDocument?: 'before' | 'after';
+  }): MongoQueryPlan<ResolveRow<Shape, ExtractMongoCodecTypes<TContract>, 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>): MongoQueryPlan<ResolveRow<Shape, ExtractMongoCodecTypes<TContract>, TContract> | null, FindOneAndDeleteCommand>;
+  /**
+   * Materialise the chain as a `MongoQueryPlan` wrapping an `AggregateCommand`.
+   */
+  build(): MongoQueryPlan<ResolveRow<Shape, ExtractMongoCodecTypes<TContract>, TContract>, AggregateCommand>;
+  /**
+   * Alias for `build()` — surfaces the read intent at the call site.
+   */
+  aggregate(): MongoQueryPlan<ResolveRow<Shape, ExtractMongoCodecTypes<TContract>, 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, AnyMongoTypeMaps>, ModelName extends keyof MongoModelsMap<TContract> & 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, InsertOneCommand>;
+  /**
+   * Insert a batch of documents. Order is preserved in the returned
+   * `insertedIds` array.
+   */
+  insertMany(documents: ReadonlyArray<Record<string, MongoValue>>): MongoQueryPlan<InsertManyResult, 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, 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, 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, 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, AnyMongoTypeMaps>, ModelName extends keyof MongoModelsMap<TContract> & 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, 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, UpdateOneCommand>;
+  /**
+   * Delete every matching document.
+   */
+  deleteMany(): MongoQueryPlan<DeleteResult, DeleteManyCommand>;
+  /**
+   * Delete at most one matching document. See the `updateOne` note about
+   * driver-chosen victim selection.
+   */
+  deleteOne(): MongoQueryPlan<DeleteResult, 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, 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>, 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>, TContract> | null, FindOneAndDeleteCommand>;
+}
+/**
+ * Bound execution context shared across the three state classes.
+ */
+interface BindingContext<TContract extends MongoContractWithTypeMaps<MongoContract, AnyMongoTypeMaps>> {
+  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, AnyMongoTypeMaps>> {
+  from<K extends keyof TContract['roots'] & string>(rootName: K): CollectionHandle<TContract, RootModelName<TContract, K>>;
+  rawCommand<C extends AnyMongoCommand>(command: C): MongoQueryPlan<unknown, C>;
+}
+declare function mongoQuery<TContract extends MongoContractWithTypeMaps<MongoContract, AnyMongoTypeMaps>>(options: {
+  contractJson: unknown;
+}): QueryRoot<TContract>;
+//#endregion
+//#region src/result-shape.d.ts
+declare function contractFieldToMongoFieldShape(field: ContractField): MongoFieldShape;
+declare function contractModelToMongoResultShape(model: MongoModelDefinition, options?: {
+  readonly selection?: readonly string[];
+  readonly includeRelationNames?: readonly string[];
+}): MongoResultShape;
+//#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 LookupBuilder, type LookupBuilderWithKey, type LookupFrom, type LookupOnResult, type LookupResult, type ModelArrayField, type ModelNestedShape, type ModelOf, 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, contractFieldToMongoFieldShape, contractModelToMongoResultShape, createFieldAccessor, expr, fn, mongoQuery };
+//# sourceMappingURL=query-builder.d.mts.map