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

package/dist/dist-Dyp05u64.mjs

@@ -0,0 +1,1546 @@
+import { r as MongoExistsExpr, t as MongoAndExpr } from "./filter-expressions-Uo8ZdzwB-53qnqceS.mjs";
+import { A as MongoLookupStage, B as MongoSetWindowFieldsStage, C as MongoDensifyStage, D as MongoGraphLookupStage, E as MongoGeoNearStage, F as MongoRedactStage, G as MongoUnwindStage, H as MongoSortByCountStage, I as MongoReplaceRootStage, K as MongoVectorSearchStage, L as MongoSampleStage, M as MongoMergeStage, N as MongoOutStage, O as MongoGroupStage, P as MongoProjectStage, R as MongoSearchMetaStage, S as MongoCountStage, T as MongoFillStage, U as MongoSortStage, V as MongoSkipStage, W as MongoUnionWithStage, _ as MongoAggOperator, a as FindOneAndUpdateCommand, at as freezeMongoResultShape, b as MongoBucketAutoStage, c as MongoAddFieldsStage, d as MongoAggCond, f as MongoAggFieldRef, i as FindOneAndDeleteCommand, it as freezeMongoFieldShape, j as MongoMatchStage, k as MongoLimitStage, l as MongoAggAccumulator, m as MongoAggLiteral, n as DeleteManyCommand, nt as UpdateManyCommand, o as InsertManyCommand, r as DeleteOneCommand, rt as UpdateOneCommand, s as InsertOneCommand, t as AggregateCommand, w as MongoFacetStage, x as MongoBucketStage, z as MongoSearchStage } from "./execution-D5XyZ5XS.mjs";
+import { i as resolveUpdaterResult, r as ormError, t as createFieldAccessor } from "./field-accessor-0oUt6RZC-B_Z30uAA.mjs";
+import { structuredError } from "@prisma/orm-framework/utils/structured-error";
+import { domainModelsAtDefaultNamespace } from "@prisma/orm-framework/contract/types";
+import { blindCast, castAs } from "@prisma/orm-framework/utils/casts";
+import { ifDefined } from "@prisma/orm-framework/utils/defined";
+import { InternalError } from "@prisma/orm-framework/utils/internal-error";
+//#region ../../../2-mongo-family/5-query-builders/query-builder/dist/index.mjs
+function namedAccumulatorArgs(args) {
+	const result = {};
+	for (const [key, val] of Object.entries(args)) if (val !== void 0) result[key] = val.node;
+	return result;
+}
+const acc = {
+	sum(expr) {
+		return {
+			_field: void 0,
+			node: MongoAggAccumulator.sum(expr.node)
+		};
+	},
+	avg(expr) {
+		return {
+			_field: void 0,
+			node: MongoAggAccumulator.avg(expr.node)
+		};
+	},
+	min(expr) {
+		return {
+			_field: void 0,
+			node: MongoAggAccumulator.min(expr.node)
+		};
+	},
+	max(expr) {
+		return {
+			_field: void 0,
+			node: MongoAggAccumulator.max(expr.node)
+		};
+	},
+	first(expr) {
+		return {
+			_field: void 0,
+			node: MongoAggAccumulator.first(expr.node)
+		};
+	},
+	last(expr) {
+		return {
+			_field: void 0,
+			node: MongoAggAccumulator.last(expr.node)
+		};
+	},
+	push(expr) {
+		return {
+			_field: void 0,
+			node: MongoAggAccumulator.push(expr.node)
+		};
+	},
+	addToSet(expr) {
+		return {
+			_field: void 0,
+			node: MongoAggAccumulator.addToSet(expr.node)
+		};
+	},
+	count() {
+		return {
+			_field: void 0,
+			node: MongoAggAccumulator.count()
+		};
+	},
+	stdDevPop(expr) {
+		return {
+			_field: void 0,
+			node: MongoAggAccumulator.stdDevPop(expr.node)
+		};
+	},
+	stdDevSamp(expr) {
+		return {
+			_field: void 0,
+			node: MongoAggAccumulator.stdDevSamp(expr.node)
+		};
+	},
+	firstN(args) {
+		return {
+			_field: void 0,
+			node: MongoAggAccumulator.of("$firstN", namedAccumulatorArgs(args))
+		};
+	},
+	lastN(args) {
+		return {
+			_field: void 0,
+			node: MongoAggAccumulator.of("$lastN", namedAccumulatorArgs(args))
+		};
+	},
+	maxN(args) {
+		return {
+			_field: void 0,
+			node: MongoAggAccumulator.of("$maxN", namedAccumulatorArgs(args))
+		};
+	},
+	minN(args) {
+		return {
+			_field: void 0,
+			node: MongoAggAccumulator.of("$minN", namedAccumulatorArgs(args))
+		};
+	},
+	top(args) {
+		return {
+			_field: void 0,
+			node: MongoAggAccumulator.of("$top", {
+				output: args.output.node,
+				sortBy: MongoAggLiteral.of(args.sortBy)
+			})
+		};
+	},
+	bottom(args) {
+		return {
+			_field: void 0,
+			node: MongoAggAccumulator.of("$bottom", {
+				output: args.output.node,
+				sortBy: MongoAggLiteral.of(args.sortBy)
+			})
+		};
+	},
+	topN(args) {
+		return {
+			_field: void 0,
+			node: MongoAggAccumulator.of("$topN", {
+				output: args.output.node,
+				sortBy: MongoAggLiteral.of(args.sortBy),
+				n: args.n.node
+			})
+		};
+	},
+	bottomN(args) {
+		return {
+			_field: void 0,
+			node: MongoAggAccumulator.of("$bottomN", {
+				output: args.output.node,
+				sortBy: MongoAggLiteral.of(args.sortBy),
+				n: args.n.node
+			})
+		};
+	}
+};
+/**
+* Construct the `from` callable for `PipelineChain.lookup`. The contract
+* is captured so `from(name)` can resolve `roots[name]` to the foreign
+* model name at runtime, look up the foreign collection name from
+* `models[modelName].storage.collection`, and assemble a `LookupResult`
+* for the outer `lookup` to consume.
+*
+* The `Shape`/`Nested` generics are erased at runtime — they exist only
+* to type the local accessor inside the user's `on(...)` callback. The
+* contract value at runtime carries the real model lookup table.
+*/
+function createLookupFrom(contract) {
+	const callable = ((rootName) => {
+		const modelName = contract.roots[rootName]?.model;
+		if (!modelName) throw ormError("ORM.MODEL_UNKNOWN", `lookup() unknown root: "${rootName}". Valid roots: ${Object.keys(contract.roots).join(", ")}`);
+		return createLookupBuilder({
+			rootName,
+			modelName,
+			foreignCollection: domainModelsAtDefaultNamespace(contract.domain)[modelName]?.storage?.collection ?? rootName
+		});
+	});
+	return callable;
+}
+function createLookupBuilder(state) {
+	return { on(cb) {
+		const result = cb(createFieldAccessor(), createFieldAccessor());
+		assertLeafExpression(result.local, "local");
+		assertLeafExpression(result.foreign, "foreign");
+		return createLookupBuilderWithKey({
+			...state,
+			localField: result.local._path,
+			foreignField: result.foreign._path
+		});
+	} };
+}
+function createLookupBuilderWithKey(state) {
+	return { as(name) {
+		return {
+			_brand: "mongo-query-builder/lookup-result@1",
+			_root: state.rootName,
+			_model: state.modelName,
+			_localField: state.localField,
+			_foreignField: state.foreignField,
+			_as: name
+		};
+	} };
+}
+/**
+* Defensive runtime guard catching the case where a user returns a
+* non-`LeafExpression` from the `on(...)` callback (e.g. by casting
+* around the type system, or threading a value in from outside the
+* callback). Compile-time gating via `LookupOnResult`'s `LeafExpression`
+* type already rejects `fn.<op>(…)` returns at the type level — this
+* guard is the runtime backstop matching the defensive style of
+* `deconstructFindAndModifyChain` in builder.ts.
+*/
+function assertLeafExpression(value, side) {
+	if (!value || typeof value._path !== "string" || value._path.length === 0) throw ormError("ORM.ARGUMENT_INVALID", `lookup().on() ${side} side must return a leaf field reference (e.g. \`${side}.<field>\`). Aggregation expressions and computed values are not supported.`);
+}
+/**
+* Extract the runtime metadata from a `LookupResult` for `PipelineChain
+* .lookup` to construct the `MongoLookupStage`. The internal fields are
+* intentionally underscore-prefixed and brand-checked here so user code
+* cannot synthesise a fake spec; this is the single ingress point.
+*/
+function extractLookupResult(result, contract) {
+	if (result?._brand !== "mongo-query-builder/lookup-result@1") throw ormError("ORM.ARGUMENT_INVALID", "lookup() callback must return the result of `from(name).on(cb).as(name)`. Returning a hand-rolled options object is not supported.");
+	return {
+		foreignCollection: domainModelsAtDefaultNamespace(contract.domain)[result._model]?.storage?.collection ?? result._root,
+		localField: result._localField,
+		foreignField: result._foreignField,
+		as: result._as,
+		modelName: result._model
+	};
+}
+const identityStageKinds = /* @__PURE__ */ new Set([
+	"match",
+	"sort",
+	"limit",
+	"skip",
+	"sample",
+	"vectorSearch"
+]);
+const unknownShape = { kind: "unknown" };
+function fieldShapeAtPath(shape, path) {
+	if (shape.kind !== "document" || path.includes(".")) return unknownShape;
+	return shape.fields[path] ?? unknownShape;
+}
+function shapeForExpr(currentShape, expr) {
+	if (expr instanceof MongoAggFieldRef) return fieldShapeAtPath(currentShape, expr.path);
+	return unknownShape;
+}
+function resultShapeAfterProject(currentShape, stage) {
+	if (currentShape.kind !== "document") return { kind: "unknown" };
+	const fields = {};
+	for (const [key, value] of Object.entries(stage.projection)) {
+		if (value === 0) continue;
+		if (value === 1) {
+			fields[key] = currentShape.fields[key] ?? unknownShape;
+			continue;
+		}
+		fields[key] = shapeForExpr(currentShape, value);
+	}
+	if (!Object.hasOwn(stage.projection, "_id") && currentShape.fields["_id"]) fields["_id"] = currentShape.fields["_id"];
+	return freezeMongoResultShape({
+		kind: "document",
+		fields
+	});
+}
+function resultShapeAfterAddFields(currentShape, stage) {
+	if (currentShape.kind !== "document") return { kind: "unknown" };
+	const fields = { ...currentShape.fields };
+	for (const [key, expr] of Object.entries(stage.fields)) fields[key] = shapeForExpr(currentShape, expr);
+	return freezeMongoResultShape({
+		kind: "document",
+		fields
+	});
+}
+function computePipelineResultShape(stages, startShape) {
+	let shape = startShape;
+	for (const stage of stages) {
+		if (shape.kind === "unknown") return { kind: "unknown" };
+		if (identityStageKinds.has(stage.kind)) continue;
+		if (stage instanceof MongoProjectStage) {
+			shape = resultShapeAfterProject(shape, stage);
+			continue;
+		}
+		if (stage instanceof MongoAddFieldsStage) {
+			shape = resultShapeAfterAddFields(shape, stage);
+			continue;
+		}
+		return { kind: "unknown" };
+	}
+	return shape;
+}
+function contractFieldToMongoFieldShape(field) {
+	const { type, nullable, many } = field;
+	if (type.kind === "valueObject" || type.kind === "union") return Object.freeze({ kind: "unknown" });
+	if (type.kind !== "scalar") return Object.freeze({ kind: "unknown" });
+	if (field.dict === true) return Object.freeze({ kind: "unknown" });
+	if (many === true) return freezeMongoFieldShape({
+		kind: "array",
+		nullable,
+		element: {
+			kind: "leaf",
+			codecId: type.codecId,
+			nullable: false
+		}
+	});
+	return freezeMongoFieldShape({
+		kind: "leaf",
+		codecId: type.codecId,
+		nullable
+	});
+}
+function contractModelToMongoResultShape(model, options) {
+	const fields = {};
+	for (const rel of options?.includeRelationNames ?? []) fields[rel] = Object.freeze({ kind: "unknown" });
+	const modelFields = model.fields;
+	const keys = options?.selection !== void 0 ? options.selection : Object.keys(modelFields);
+	for (const key of keys) {
+		if (Object.hasOwn(fields, key)) continue;
+		const cf = modelFields[key];
+		if (!cf) {
+			fields[key] = Object.freeze({ kind: "unknown" });
+			continue;
+		}
+		fields[key] = contractFieldToMongoFieldShape(cf);
+	}
+	return freezeMongoResultShape({
+		kind: "document",
+		fields
+	});
+}
+/**
+* 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`.
+*/
+var PipelineChain = class PipelineChain {
+	#contract;
+	#state;
+	constructor(contract, state) {
+		this.#contract = contract;
+		this.#state = state;
+	}
+	/**
+	* Internal helper that appends a pipeline stage and branches into a new
+	* state-type. The fifth type parameter `NewN` carries the nested-path
+	* shape forward. It defaults to `Record<string, never>` so stages that
+	* fundamentally rewrite the document (`$group`, `$project`,
+	* `$replaceRoot`, …) automatically disable the callable form of
+	* `FieldAccessor` downstream. Additive stages (`match`, `addFields`,
+	* `sort`, `lookup`, …) explicitly re-thread the current `N`.
+	*/
+	#withStage(stage) {
+		return new PipelineChain(this.#contract, {
+			...this.#state,
+			stages: [...this.#state.stages, stage]
+		});
+	}
+	#writeMeta() {
+		return {
+			target: "mongo",
+			storageHash: this.#state.storageHash,
+			lane: "mongo-query"
+		};
+	}
+	match(filterOrFn) {
+		const filter = typeof filterOrFn === "function" ? filterOrFn(createFieldAccessor()) : filterOrFn;
+		return this.#withStage(new MongoMatchStage(filter));
+	}
+	/**
+	* `$sort`. Clears `UpdateEnabled` (`update` has no per-document sort) but
+	* preserves `FindAndModifyEnabled` (`findAndModify` has a `sort` slot).
+	*/
+	sort(spec) {
+		return this.#withStage(new MongoSortStage(spec));
+	}
+	/**
+	* `$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) {
+		return this.#withStage(new MongoLimitStage(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) {
+		return this.#withStage(new MongoSkipStage(n));
+	}
+	sample(n) {
+		return this.#withStage(new MongoSampleStage(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(fn) {
+		const newFields = fn(createFieldAccessor());
+		const exprRecord = {};
+		for (const [key, typed] of Object.entries(newFields)) exprRecord[key] = typed.node;
+		return this.#withStage(new MongoAddFieldsStage(exprRecord));
+	}
+	/**
+	* `$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(fn) {
+		const extracted = extractLookupResult(fn(createLookupFrom(this.#contract)), this.#contract);
+		return this.#withStage(new MongoLookupStage({
+			from: extracted.foreignCollection,
+			localField: extracted.localField,
+			foreignField: extracted.foreignField,
+			as: extracted.as
+		}));
+	}
+	project(...args) {
+		if (args.length === 1 && typeof args[0] === "function") {
+			const fn = args[0];
+			const spec = fn(createFieldAccessor());
+			const projection = {};
+			for (const [key, val] of Object.entries(spec)) projection[key] = val === 1 ? 1 : val.node;
+			return this.#withStage(new MongoProjectStage(projection));
+		}
+		const keys = args;
+		const projection = {};
+		for (const key of keys) projection[key] = 1;
+		return this.#withStage(new MongoProjectStage(projection));
+	}
+	/**
+	* `$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(field, options) {
+		return this.#withStage(new MongoUnwindStage(`$${field}`, options?.preserveNullAndEmptyArrays ?? false));
+	}
+	/**
+	* `$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(fn) {
+		const { _id: groupIdExpr, ...rest } = fn(createFieldAccessor());
+		const groupId = groupIdExpr === null ? null : groupIdExpr.node;
+		const accumulators = {};
+		for (const [key, typed] of Object.entries(rest)) {
+			if (typed === null) throw ormError("ORM.ARGUMENT_INVALID", `group() field "${key}" must not be null. Only _id can be null.`);
+			if (typed.node.kind !== "accumulator") throw ormError("ORM.ARGUMENT_INVALID", `group() field "${key}" must use an accumulator (e.g. acc.sum(), acc.count()). Got "${typed.node.kind}" expression.`);
+			accumulators[key] = typed.node;
+		}
+		return this.#withStage(new MongoGroupStage(groupId, accumulators));
+	}
+	/**
+	* `$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(fn) {
+		const expr = fn(createFieldAccessor());
+		return this.#withStage(new MongoReplaceRootStage(expr.node));
+	}
+	count(field) {
+		return this.#withStage(new MongoCountStage(field));
+	}
+	sortByCount(fn) {
+		const expr = fn(createFieldAccessor());
+		return this.#withStage(new MongoSortByCountStage(expr.node));
+	}
+	/**
+	* `$redact`. Preserves `UpdateEnabled`; clears `FindAndModifyEnabled`.
+	* Shape- and nested-path-preserving (the document tree is unchanged).
+	*/
+	redact(fn) {
+		const expr = fn(createFieldAccessor());
+		return this.#withStage(new MongoRedactStage(expr.node));
+	}
+	/**
+	* `$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, db) {
+		return this.#writeTerminal(new MongoOutStage(collection, db));
+	}
+	/**
+	* `$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) {
+		return this.#writeTerminal(new MongoMergeStage(options));
+	}
+	#writeTerminal(stage) {
+		const pipeline = [...this.#state.stages, stage];
+		const command = new AggregateCommand(this.#state.collection, pipeline);
+		const meta = {
+			target: "mongo",
+			storageHash: this.#state.storageHash,
+			lane: "mongo-query"
+		};
+		return {
+			collection: this.#state.collection,
+			command,
+			meta
+		};
+	}
+	unionWith(collection, pipeline) {
+		return this.#withStage(new MongoUnionWithStage(collection, pipeline));
+	}
+	bucket(options) {
+		return this.#withStage(new MongoBucketStage(options));
+	}
+	bucketAuto(options) {
+		return this.#withStage(new MongoBucketAutoStage(options));
+	}
+	geoNear(options) {
+		return this.#withStage(new MongoGeoNearStage(options));
+	}
+	facet(facets) {
+		return this.#withStage(new MongoFacetStage(facets));
+	}
+	graphLookup(options) {
+		return this.#withStage(new MongoGraphLookupStage(options));
+	}
+	setWindowFields(options) {
+		return this.#withStage(new MongoSetWindowFieldsStage(options));
+	}
+	densify(options) {
+		return this.#withStage(new MongoDensifyStage(options));
+	}
+	fill(options) {
+		return this.#withStage(new MongoFillStage(options));
+	}
+	search(config, index) {
+		return this.#withStage(new MongoSearchStage(config, index));
+	}
+	searchMeta(config, index) {
+		return this.#withStage(new MongoSearchMetaStage(config, index));
+	}
+	vectorSearch(options) {
+		return this.#withStage(new MongoVectorSearchStage(options));
+	}
+	pipe(stage) {
+		return this.#withStage(stage);
+	}
+	/**
+	* 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(updaterFn) {
+		if (updaterFn !== void 0) throw ormError("ORM.ARGUMENT_INVALID", "updateMany() on a PipelineChain expects no arguments — the chain itself is the update pipeline. To update with an operator callback, call .updateMany(fn) on a FilteredCollection (i.e. after .match()).");
+		const { filter, updatePipeline } = deconstructUpdateChain(this.#state.stages);
+		const command = new UpdateManyCommand(this.#state.collection, filter, updatePipeline);
+		return {
+			collection: this.#state.collection,
+			command,
+			meta: this.#writeMeta()
+		};
+	}
+	/**
+	* 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(updaterFn) {
+		if (updaterFn !== void 0) throw ormError("ORM.ARGUMENT_INVALID", "updateOne() on a PipelineChain expects no arguments — the chain itself is the update pipeline. To update with an operator callback, call .updateOne(fn) on a FilteredCollection (i.e. after .match()).");
+		const { filter, updatePipeline } = deconstructUpdateChain(this.#state.stages);
+		const command = new UpdateOneCommand(this.#state.collection, filter, updatePipeline);
+		return {
+			collection: this.#state.collection,
+			command,
+			meta: this.#writeMeta()
+		};
+	}
+	/**
+	* 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(updaterFn, opts = {}) {
+		const { filter, sort } = deconstructFindAndModifyChain(this.#state.stages);
+		const update = resolveUpdaterResult(updaterFn(createFieldAccessor()));
+		const command = new FindOneAndUpdateCommand(this.#state.collection, filter, update, opts.upsert ?? false, sort, opts.returnDocument ?? "after");
+		const meta = {
+			target: "mongo",
+			storageHash: this.#state.storageHash,
+			lane: "mongo-query"
+		};
+		return {
+			collection: this.#state.collection,
+			command,
+			meta
+		};
+	}
+	/**
+	* Find a single document matching the accumulated pipeline and delete it.
+	* Same marker gating and deconstruction as `findOneAndUpdate`.
+	*/
+	findOneAndDelete() {
+		const { filter, sort } = deconstructFindAndModifyChain(this.#state.stages);
+		const command = new FindOneAndDeleteCommand(this.#state.collection, filter, sort);
+		const meta = {
+			target: "mongo",
+			storageHash: this.#state.storageHash,
+			lane: "mongo-query"
+		};
+		return {
+			collection: this.#state.collection,
+			command,
+			meta
+		};
+	}
+	/**
+	* Materialise the chain as a `MongoQueryPlan` wrapping an `AggregateCommand`.
+	*/
+	build() {
+		const command = new AggregateCommand(this.#state.collection, this.#state.stages);
+		const meta = {
+			target: "mongo",
+			storageHash: this.#state.storageHash,
+			lane: "mongo-query"
+		};
+		const modelName = this.#state.modelName;
+		const contractNarrow = this.#contract;
+		let resultShape;
+		if (modelName !== void 0) {
+			const model = castAs(domainModelsAtDefaultNamespace(contractNarrow.domain)[modelName]);
+			resultShape = model ? computePipelineResultShape(this.#state.stages, contractModelToMongoResultShape(model)) : { kind: "unknown" };
+		}
+		return {
+			collection: this.#state.collection,
+			command,
+			meta,
+			...ifDefined("resultShape", resultShape)
+		};
+	}
+	/**
+	* Alias for `build()` — surfaces the read intent at the call site.
+	*/
+	aggregate() {
+		return this.build();
+	}
+};
+/**
+* Walk the accumulated pipeline stages and extract the `filter` and `sort`
+* slots for a `findOneAndUpdate` / `findOneAndDelete` wire command.
+*
+* The helper accepts exactly the canonical shape `match+ -> sort?` and
+* nothing else:
+*
+*  - one or more `$match` stages (AND-folded into a single filter),
+*  - optionally followed by a single `$sort` stage.
+*
+* Anything else — a `$sort` before `$match`, multiple `$sort` stages, a
+* `$skip` stage, or any non-`$match`/`$sort` stage — is rejected with a
+* clear error. The type system already prevents most of these at compile
+* time via the `FindAndModifyEnabled` marker, but the runtime check
+* guards the escape hatches (e.g. `.pipe(...)`) and future marker gaps.
+*
+* `$skip` is rejected outright because MongoDB's `findAndModify` command
+* has no skip slot; a silently-dropped skip is a latent correctness bug
+* waiting to happen. (A02 removed skip from the typed AST for the same
+* reason.)
+*/
+function deconstructFindAndModifyChain(stages) {
+	const matchFilters = [];
+	let sort;
+	let seenNonMatch = false;
+	for (const stage of stages) if (stage instanceof MongoMatchStage) {
+		if (seenNonMatch) throw ormError("ORM.ARGUMENT_INVALID", "findOneAndUpdate/findOneAndDelete requires the canonical $match+ -> $sort? shape, but a $match stage was found after a $sort. Re-order the chain so every .match() call precedes the .sort() call.");
+		matchFilters.push(stage.filter);
+	} else if (stage instanceof MongoSortStage) {
+		if (sort !== void 0) throw ormError("ORM.ARGUMENT_INVALID", "findOneAndUpdate/findOneAndDelete accepts at most one $sort stage; drop the extra .sort() call or combine the keys into a single sort spec.");
+		sort = { ...stage.sort };
+		seenNonMatch = true;
+	} else if (stage instanceof MongoSkipStage) throw ormError("ORM.OPERATION_UNSUPPORTED", "findOneAndUpdate/findOneAndDelete does not support .skip() — MongoDB findAndModify has no skip slot. Remove the .skip() call, or use .aggregate()/.build() if the chain needs skip semantics.");
+	else throw ormError("ORM.ARGUMENT_INVALID", `findOneAndUpdate/findOneAndDelete requires the canonical \$match+ -> \$sort? shape, but encountered a '${stage.constructor.name}' stage. This is likely a bug — the type system should have prevented this chain.`);
+	if (matchFilters.length === 0) throw ormError("ORM.ARGUMENT_INVALID", "findOneAndUpdate/findOneAndDelete requires at least one .match() call.");
+	const first = matchFilters[0];
+	if (first === void 0) throw new InternalError("Unreachable: matchFilters.length > 0 but first is undefined");
+	return {
+		filter: matchFilters.length === 1 ? first : MongoAndExpr.of(matchFilters),
+		sort
+	};
+}
+/**
+* Walk the accumulated pipeline stages: leading `$match` stages become the
+* filter, remaining stages must all be valid `MongoUpdatePipelineStage`
+* members (currently `$addFields`, `$project`, `$replaceRoot`).
+*/
+function deconstructUpdateChain(stages) {
+	const matchFilters = [];
+	let boundary = 0;
+	for (const stage of stages) {
+		if (!(stage instanceof MongoMatchStage)) break;
+		matchFilters.push(stage.filter);
+		boundary++;
+	}
+	if (matchFilters.length === 0) throw ormError("ORM.ARGUMENT_INVALID", "No-arg updateMany/updateOne requires at least one .match() call.");
+	const remaining = stages.slice(boundary);
+	if (remaining.length === 0) throw ormError("ORM.ARGUMENT_INVALID", "No-arg updateMany/updateOne requires at least one pipeline-update stage (e.g. .addFields(), .project(), .replaceRoot()) after the .match() stages.");
+	const updatePipeline = [];
+	for (const stage of remaining) if (stage instanceof MongoAddFieldsStage || stage instanceof MongoProjectStage || stage instanceof MongoReplaceRootStage) updatePipeline.push(stage);
+	else throw ormError("ORM.ARGUMENT_INVALID", `No-arg updateMany/updateOne: encountered non-update stage '${stage.constructor.name}' after the leading \$match stages. Only \$addFields/\$set, \$project/\$unset, and \$replaceRoot/\$replaceWith stages are valid in an update pipeline.`);
+	const first = matchFilters[0];
+	if (first === void 0) throw new InternalError("Unreachable: matchFilters.length > 0 but first is undefined");
+	return {
+		filter: matchFilters.length === 1 ? first : MongoAndExpr.of(matchFilters),
+		updatePipeline
+	};
+}
+function numericExpr(op, args) {
+	return {
+		_field: {
+			codecId: "mongo/double@1",
+			nullable: false
+		},
+		node: MongoAggOperator.of(op, args.map((a) => a.node))
+	};
+}
+function numericUnaryExpr(op, arg) {
+	return {
+		_field: {
+			codecId: "mongo/double@1",
+			nullable: false
+		},
+		node: MongoAggOperator.of(op, arg.node)
+	};
+}
+function stringExpr(op, args) {
+	return {
+		_field: {
+			codecId: "mongo/string@1",
+			nullable: false
+		},
+		node: MongoAggOperator.of(op, args.map((a) => a.node))
+	};
+}
+function stringUnaryExpr(op, arg) {
+	return {
+		_field: {
+			codecId: "mongo/string@1",
+			nullable: false
+		},
+		node: MongoAggOperator.of(op, arg.node)
+	};
+}
+function booleanExpr(op, args) {
+	return {
+		_field: {
+			codecId: "mongo/bool@1",
+			nullable: false
+		},
+		node: MongoAggOperator.of(op, args.map((a) => a.node))
+	};
+}
+function booleanUnaryExpr(op, arg) {
+	return {
+		_field: {
+			codecId: "mongo/bool@1",
+			nullable: false
+		},
+		node: MongoAggOperator.of(op, arg.node)
+	};
+}
+function dateUnaryExpr(op, arg) {
+	return {
+		_field: {
+			codecId: "mongo/date@1",
+			nullable: false
+		},
+		node: MongoAggOperator.of(op, arg.node)
+	};
+}
+function arrayExpr(op, args) {
+	return {
+		_field: {
+			codecId: "mongo/array@1",
+			nullable: false
+		},
+		node: MongoAggOperator.of(op, args.map((a) => a.node))
+	};
+}
+function arrayUnaryExpr(op, arg) {
+	return {
+		_field: {
+			codecId: "mongo/array@1",
+			nullable: false
+		},
+		node: MongoAggOperator.of(op, arg.node)
+	};
+}
+function docUnaryExpr(op, arg) {
+	return {
+		_field: {
+			codecId: arg._field.codecId,
+			nullable: false
+		},
+		node: MongoAggOperator.of(op, arg.node)
+	};
+}
+function namedArgsExpr(op, args, _field) {
+	const nodeArgs = {};
+	for (const [key, val] of Object.entries(args)) if (val !== void 0) nodeArgs[key] = val.node;
+	return {
+		_field,
+		node: MongoAggOperator.of(op, nodeArgs)
+	};
+}
+const NUMERIC = {
+	codecId: "mongo/double@1",
+	nullable: false
+};
+const STRING = {
+	codecId: "mongo/string@1",
+	nullable: false
+};
+const BOOLEAN = {
+	codecId: "mongo/bool@1",
+	nullable: false
+};
+const DATE = {
+	codecId: "mongo/date@1",
+	nullable: false
+};
+const ARRAY = {
+	codecId: "mongo/array@1",
+	nullable: false
+};
+const DOC = {
+	codecId: "mongo/document@1",
+	nullable: false
+};
+function literal(value) {
+	return {
+		_field: void 0,
+		node: MongoAggLiteral.of(value)
+	};
+}
+const fn = {
+	add(...args) {
+		return numericExpr("$add", args);
+	},
+	subtract(a, b) {
+		return numericExpr("$subtract", [a, b]);
+	},
+	multiply(...args) {
+		return numericExpr("$multiply", args);
+	},
+	divide(a, b) {
+		return numericExpr("$divide", [a, b]);
+	},
+	concat(...args) {
+		return stringExpr("$concat", args);
+	},
+	toLower(a) {
+		return stringUnaryExpr("$toLower", a);
+	},
+	toUpper(a) {
+		return stringUnaryExpr("$toUpper", a);
+	},
+	size(a) {
+		return numericUnaryExpr("$size", a);
+	},
+	cond(condition, thenExpr, elseExpr) {
+		return {
+			_field: thenExpr._field,
+			node: new MongoAggCond(condition, thenExpr.node, elseExpr.node)
+		};
+	},
+	literal,
+	year(a) {
+		return numericUnaryExpr("$year", a);
+	},
+	month(a) {
+		return numericUnaryExpr("$month", a);
+	},
+	dayOfMonth(a) {
+		return numericUnaryExpr("$dayOfMonth", a);
+	},
+	hour(a) {
+		return numericUnaryExpr("$hour", a);
+	},
+	minute(a) {
+		return numericUnaryExpr("$minute", a);
+	},
+	second(a) {
+		return numericUnaryExpr("$second", a);
+	},
+	millisecond(a) {
+		return numericUnaryExpr("$millisecond", a);
+	},
+	dateToString(args) {
+		return namedArgsExpr("$dateToString", args, STRING);
+	},
+	dateFromString(args) {
+		return namedArgsExpr("$dateFromString", args, DATE);
+	},
+	dateDiff(args) {
+		return namedArgsExpr("$dateDiff", args, NUMERIC);
+	},
+	dateAdd(args) {
+		return namedArgsExpr("$dateAdd", args, DATE);
+	},
+	dateSubtract(args) {
+		return namedArgsExpr("$dateSubtract", args, DATE);
+	},
+	dateTrunc(args) {
+		return namedArgsExpr("$dateTrunc", args, DATE);
+	},
+	substr(str, start, length) {
+		return stringExpr("$substr", [
+			str,
+			start,
+			length
+		]);
+	},
+	substrBytes(str, start, count) {
+		return stringExpr("$substrBytes", [
+			str,
+			start,
+			count
+		]);
+	},
+	trim(args) {
+		return namedArgsExpr("$trim", args, STRING);
+	},
+	ltrim(args) {
+		return namedArgsExpr("$ltrim", args, STRING);
+	},
+	rtrim(args) {
+		return namedArgsExpr("$rtrim", args, STRING);
+	},
+	split(str, delimiter) {
+		return arrayExpr("$split", [str, delimiter]);
+	},
+	strLenCP(a) {
+		return numericUnaryExpr("$strLenCP", a);
+	},
+	strLenBytes(a) {
+		return numericUnaryExpr("$strLenBytes", a);
+	},
+	regexMatch(args) {
+		return namedArgsExpr("$regexMatch", args, BOOLEAN);
+	},
+	regexFind(args) {
+		return namedArgsExpr("$regexFind", args, DOC);
+	},
+	regexFindAll(args) {
+		return namedArgsExpr("$regexFindAll", args, ARRAY);
+	},
+	replaceOne(args) {
+		return namedArgsExpr("$replaceOne", args, STRING);
+	},
+	replaceAll(args) {
+		return namedArgsExpr("$replaceAll", args, STRING);
+	},
+	cmp(a, b) {
+		return numericExpr("$cmp", [a, b]);
+	},
+	eq(a, b) {
+		return booleanExpr("$eq", [a, b]);
+	},
+	ne(a, b) {
+		return booleanExpr("$ne", [a, b]);
+	},
+	gt(a, b) {
+		return booleanExpr("$gt", [a, b]);
+	},
+	gte(a, b) {
+		return booleanExpr("$gte", [a, b]);
+	},
+	lt(a, b) {
+		return booleanExpr("$lt", [a, b]);
+	},
+	lte(a, b) {
+		return booleanExpr("$lte", [a, b]);
+	},
+	arrayElemAt(arr, idx) {
+		return {
+			_field: {
+				codecId: DOC.codecId,
+				nullable: true
+			},
+			node: MongoAggOperator.of("$arrayElemAt", [arr.node, idx.node])
+		};
+	},
+	concatArrays(...args) {
+		return arrayExpr("$concatArrays", args);
+	},
+	firstElem(a) {
+		return {
+			_field: {
+				codecId: DOC.codecId,
+				nullable: true
+			},
+			node: MongoAggOperator.of("$first", a.node)
+		};
+	},
+	lastElem(a) {
+		return {
+			_field: {
+				codecId: DOC.codecId,
+				nullable: true
+			},
+			node: MongoAggOperator.of("$last", a.node)
+		};
+	},
+	isIn(elem, arr) {
+		return booleanExpr("$in", [elem, arr]);
+	},
+	indexOfArray(arr, value, ...rest) {
+		return numericExpr("$indexOfArray", [
+			arr,
+			value,
+			...rest
+		]);
+	},
+	isArray(a) {
+		return booleanUnaryExpr("$isArray", a);
+	},
+	reverseArray(a) {
+		return arrayUnaryExpr("$reverseArray", a);
+	},
+	slice(arr, ...rest) {
+		return arrayExpr("$slice", [arr, ...rest]);
+	},
+	zip(args) {
+		const nodeArgs = { inputs: args.inputs.map((a) => a.node) };
+		if (args.useLongestLength) nodeArgs["useLongestLength"] = args.useLongestLength.node;
+		if (args.defaults) nodeArgs["defaults"] = args.defaults.node;
+		return {
+			_field: ARRAY,
+			node: MongoAggOperator.of("$zip", nodeArgs)
+		};
+	},
+	range(start, end, step) {
+		return arrayExpr("$range", [
+			start,
+			end,
+			step
+		]);
+	},
+	setUnion(...args) {
+		return arrayExpr("$setUnion", args);
+	},
+	setIntersection(...args) {
+		return arrayExpr("$setIntersection", args);
+	},
+	setDifference(a, b) {
+		return arrayExpr("$setDifference", [a, b]);
+	},
+	setEquals(...args) {
+		return booleanExpr("$setEquals", args);
+	},
+	setIsSubset(a, b) {
+		return booleanExpr("$setIsSubset", [a, b]);
+	},
+	anyElementTrue(a) {
+		return booleanUnaryExpr("$anyElementTrue", a);
+	},
+	allElementsTrue(a) {
+		return booleanUnaryExpr("$allElementsTrue", a);
+	},
+	typeOf(a) {
+		return stringUnaryExpr("$type", a);
+	},
+	convert(args) {
+		return namedArgsExpr("$convert", args, DOC);
+	},
+	toInt(a) {
+		return numericUnaryExpr("$toInt", a);
+	},
+	toLong(a) {
+		return numericUnaryExpr("$toLong", a);
+	},
+	toDouble(a) {
+		return numericUnaryExpr("$toDouble", a);
+	},
+	toDecimal(a) {
+		return numericUnaryExpr("$toDecimal", a);
+	},
+	toString_(a) {
+		return stringUnaryExpr("$toString", a);
+	},
+	toObjectId(a) {
+		return docUnaryExpr("$toObjectId", a);
+	},
+	toBool(a) {
+		return booleanUnaryExpr("$toBool", a);
+	},
+	toDate(a) {
+		return dateUnaryExpr("$toDate", a);
+	},
+	objectToArray(a) {
+		return arrayUnaryExpr("$objectToArray", a);
+	},
+	arrayToObject(a) {
+		return {
+			_field: DOC,
+			node: MongoAggOperator.of("$arrayToObject", a.node)
+		};
+	},
+	getField(args) {
+		return namedArgsExpr("$getField", args, DOC);
+	},
+	setField(args) {
+		return namedArgsExpr("$setField", args, DOC);
+	}
+};
+function contractError(code, message, options) {
+	return structuredError(code, message, options);
+}
+/**
+* "Match-all" filter used by the unqualified-write terminals
+* (`updateAll`/`deleteAll`). The canonical representation is still
+* undecided — `MongoAndExpr` with an empty conjunction and a dedicated
+* `MongoMatchAllExpr` node are both candidates. For now we use
+* `_id $exists: true`, which is trivially true on every document and
+* avoids introducing a new AST node before the wider question is
+* resolved. Centralised so the eventual switch is a one-line change.
+*/
+function matchAllFilter() {
+	return MongoExistsExpr.exists("_id");
+}
+/**
+* Resolve an updater callback into a `MongoUpdateSpec` (either the folded
+* operator object or a pipeline-stage array). Centralised so all write
+* terminals share the same fold / dispatch semantics.
+*/
+function resolveUpdaterCallback(updaterFn) {
+	return resolveUpdaterResult(updaterFn(createFieldAccessor()));
+}
+/**
+* Build the `PlanMeta` envelope shared by every write terminal in this
+* package. Lane is `mongo-query` (single lane for all query-builder terminals)
+* so middleware can dispatch on intent without inspecting the command.
+*/
+function writeMeta(storageHash) {
+	return {
+		target: "mongo",
+		storageHash,
+		lane: "mongo-query"
+	};
+}
+/**
+* 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.
+*/
+var CollectionHandle = class extends PipelineChain {
+	#ctx;
+	#modelName;
+	constructor(ctx, modelName) {
+		super(ctx.contract, {
+			collection: ctx.collection,
+			stages: [],
+			storageHash: ctx.storageHash,
+			modelName
+		});
+		this.#ctx = ctx;
+		this.#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() {
+		return this.#modelName;
+	}
+	match(filterOrFn) {
+		const resolved = typeof filterOrFn === "function" ? filterOrFn(createFieldAccessor()) : filterOrFn;
+		return new FilteredCollection(this.#ctx, this.#modelName, [resolved]);
+	}
+	/**
+	* 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) {
+		const command = new InsertOneCommand(this.#ctx.collection, document);
+		return {
+			collection: this.#ctx.collection,
+			command,
+			meta: writeMeta(this.#ctx.storageHash)
+		};
+	}
+	/**
+	* Insert a batch of documents. Order is preserved in the returned
+	* `insertedIds` array.
+	*/
+	insertMany(documents) {
+		if (documents.length === 0) throw ormError("ORM.MUTATION_DATA_MISSING", "insertMany() requires at least one document.");
+		const command = new InsertManyCommand(this.#ctx.collection, documents);
+		return {
+			collection: this.#ctx.collection,
+			command,
+			meta: writeMeta(this.#ctx.storageHash)
+		};
+	}
+	/**
+	* 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) {
+		const update = resolveUpdaterCallback(updaterFn);
+		const command = new UpdateManyCommand(this.#ctx.collection, matchAllFilter(), update);
+		return {
+			collection: this.#ctx.collection,
+			command,
+			meta: writeMeta(this.#ctx.storageHash)
+		};
+	}
+	/**
+	* Delete *every* document in the collection. See `updateAll` for the
+	* rationale around the unqualified-write surface being limited to this
+	* state class.
+	*/
+	deleteAll() {
+		const command = new DeleteManyCommand(this.#ctx.collection, matchAllFilter());
+		return {
+			collection: this.#ctx.collection,
+			command,
+			meta: writeMeta(this.#ctx.storageHash)
+		};
+	}
+	/**
+	* 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, updaterFn) {
+		const filter = filterFn(createFieldAccessor());
+		const update = resolveUpdaterCallback(updaterFn);
+		const command = new UpdateOneCommand(this.#ctx.collection, filter, update, true);
+		return {
+			collection: this.#ctx.collection,
+			command,
+			meta: writeMeta(this.#ctx.storageHash)
+		};
+	}
+};
+/**
+* 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.
+*/
+var FilteredCollection = class FilteredCollection extends PipelineChain {
+	#ctx;
+	#modelName;
+	#filters;
+	constructor(ctx, modelName, filters) {
+		if (filters.length === 0) throw new InternalError("FilteredCollection requires at least one accumulated filter");
+		const first = filters[0];
+		if (first === void 0) throw new InternalError("FilteredCollection: unreachable empty-filters branch");
+		const leading = filters.length === 1 ? first : foldAnd(filters);
+		super(ctx.contract, {
+			collection: ctx.collection,
+			stages: [new MongoMatchStage(leading)],
+			storageHash: ctx.storageHash,
+			modelName
+		});
+		this.#ctx = ctx;
+		this.#modelName = modelName;
+		this.#filters = filters;
+	}
+	get _modelName() {
+		return this.#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() {
+		return this.#filters;
+	}
+	match(filterOrFn) {
+		const resolved = typeof filterOrFn === "function" ? filterOrFn(createFieldAccessor()) : filterOrFn;
+		return new FilteredCollection(this.#ctx, this.#modelName, [...this.#filters, resolved]);
+	}
+	/**
+	* AND-fold the accumulated filters into a single `MongoFilterExpr` for
+	* splatting into a write/find-and-modify wire command's `filter` slot.
+	* Length-1 short-circuits to avoid a redundant `$and` wrapper.
+	*/
+	#foldedFilter() {
+		const first = this.#filters[0];
+		if (first === void 0) throw new InternalError("FilteredCollection: invariant violated — empty filter accumulator");
+		return this.#filters.length === 1 ? first : foldAnd(this.#filters);
+	}
+	/**
+	* 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) {
+		const update = resolveUpdaterCallback(updaterFn);
+		const command = new UpdateManyCommand(this.#ctx.collection, this.#foldedFilter(), update);
+		return {
+			collection: this.#ctx.collection,
+			command,
+			meta: writeMeta(this.#ctx.storageHash)
+		};
+	}
+	/**
+	* 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) {
+		const update = resolveUpdaterCallback(updaterFn);
+		const command = new UpdateOneCommand(this.#ctx.collection, this.#foldedFilter(), update);
+		return {
+			collection: this.#ctx.collection,
+			command,
+			meta: writeMeta(this.#ctx.storageHash)
+		};
+	}
+	/**
+	* Delete every matching document.
+	*/
+	deleteMany() {
+		const command = new DeleteManyCommand(this.#ctx.collection, this.#foldedFilter());
+		return {
+			collection: this.#ctx.collection,
+			command,
+			meta: writeMeta(this.#ctx.storageHash)
+		};
+	}
+	/**
+	* Delete at most one matching document. See the `updateOne` note about
+	* driver-chosen victim selection.
+	*/
+	deleteOne() {
+		const command = new DeleteOneCommand(this.#ctx.collection, this.#foldedFilter());
+		return {
+			collection: this.#ctx.collection,
+			command,
+			meta: writeMeta(this.#ctx.storageHash)
+		};
+	}
+	/**
+	* 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) {
+		const update = resolveUpdaterCallback(updaterFn);
+		const command = new UpdateOneCommand(this.#ctx.collection, this.#foldedFilter(), update, true);
+		return {
+			collection: this.#ctx.collection,
+			command,
+			meta: writeMeta(this.#ctx.storageHash)
+		};
+	}
+	/**
+	* 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, opts = {}) {
+		const update = resolveUpdaterCallback(updaterFn);
+		const command = new FindOneAndUpdateCommand(this.#ctx.collection, this.#foldedFilter(), update, opts.upsert ?? false, void 0, opts.returnDocument ?? "after");
+		return {
+			collection: this.#ctx.collection,
+			command,
+			meta: writeMeta(this.#ctx.storageHash)
+		};
+	}
+	/**
+	* Find a single matching document and delete it. Returns the deleted
+	* document via the row stream.
+	*/
+	findOneAndDelete() {
+		const command = new FindOneAndDeleteCommand(this.#ctx.collection, this.#foldedFilter());
+		return {
+			collection: this.#ctx.collection,
+			command,
+			meta: writeMeta(this.#ctx.storageHash)
+		};
+	}
+};
+function foldAnd(filters) {
+	return MongoAndExpr.of(filters);
+}
+/**
+* Narrow a `MongoContractWithTypeMaps`-shaped value down to its underlying
+* `MongoContract` view. `MongoContractWithTypeMaps<C, ...>` is defined as
+* `C & { readonly [phantom]?: TTypeMaps }`, so every contract we accept is
+* structurally a `MongoContract` — the phantom is type-only. This helper
+* centralises that narrowing so callers don't reach for `as unknown as
+* MongoContract` double-casts.
+*/
+function asMongoContract(contract) {
+	return contract;
+}
+/**
+* Construct a `CollectionHandle` from a validated contract + root name.
+* Used by `mongoQuery(...).from(name)` to enter the state machine.
+*/
+function createCollectionHandle(contract, rootName) {
+	const c = asMongoContract(contract);
+	const modelName = c.roots[rootName]?.model;
+	if (!modelName) throw ormError("ORM.MODEL_UNKNOWN", `Unknown root: "${rootName}". Valid roots: ${Object.keys(c.roots).join(", ")}`);
+	const model = domainModelsAtDefaultNamespace(c.domain)[modelName];
+	if (!model) throw contractError("CONTRACT.MODEL_UNKNOWN", `Unknown model: "${modelName}" referenced by root "${rootName}".`);
+	const collectionName = model.storage.collection ?? rootName;
+	if (!c.storage?.storageHash) throw contractError("CONTRACT.VALIDATION_FAILED", "Contract is missing storage.storageHash. Pass a validated contract to mongoQuery().");
+	return new CollectionHandle({
+		contract,
+		collection: collectionName,
+		storageHash: String(c.storage.storageHash)
+	}, modelName);
+}
+function mongoQuery(options) {
+	const contract = blindCast(options.contractJson);
+	return {
+		from(rootName) {
+			return createCollectionHandle(contract, rootName);
+		},
+		rawCommand(command) {
+			const storageHash = asMongoContract(contract).storage?.storageHash;
+			if (!storageHash) throw contractError("CONTRACT.VALIDATION_FAILED", "Contract is missing storage.storageHash. Pass a validated contract to mongoQuery().");
+			const meta = {
+				target: "mongo",
+				storageHash: String(storageHash),
+				lane: "mongo-query"
+			};
+			return {
+				collection: command.collection,
+				command,
+				meta
+			};
+		}
+	};
+}
+//#endregion
+export { contractFieldToMongoFieldShape as a, mongoQuery as c, acc as i, FilteredCollection as n, contractModelToMongoResultShape as o, PipelineChain as r, fn as s, CollectionHandle as t };
+
+//# sourceMappingURL=dist-Dyp05u64.mjs.map