@prisma-next/mongo-query-builder 0.0.1

package/dist/index.mjs

@@ -0,0 +1,1591 @@
+import { AggregateCommand, DeleteManyCommand, DeleteOneCommand, FindOneAndDeleteCommand, FindOneAndUpdateCommand, InsertManyCommand, InsertOneCommand, MongoAddFieldsStage, MongoAggAccumulator, MongoAggCond, MongoAggFieldRef, MongoAggLiteral, MongoAggOperator, MongoAndExpr, MongoBucketAutoStage, MongoBucketStage, MongoCountStage, MongoDensifyStage, MongoExistsExpr, MongoFacetStage, MongoFieldFilter, MongoFillStage, MongoGeoNearStage, MongoGraphLookupStage, MongoGroupStage, MongoLimitStage, MongoLookupStage, MongoMatchStage, MongoMergeStage, MongoOutStage, MongoProjectStage, MongoRedactStage, MongoReplaceRootStage, MongoSampleStage, MongoSearchMetaStage, MongoSearchStage, MongoSetWindowFieldsStage, MongoSkipStage, MongoSortByCountStage, MongoSortStage, MongoUnionWithStage, MongoUnwindStage, MongoVectorSearchStage, UpdateManyCommand, UpdateOneCommand } from "@prisma-next/mongo-query-ast/execution";
+
+//#region src/accumulator-helpers.ts
+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
+			})
+		};
+	}
+};
+
+//#endregion
+//#region src/update-ops.ts
+const setOp = (path, value) => ({
+	op: "$set",
+	path,
+	value
+});
+const unsetOp = (path) => ({
+	op: "$unset",
+	path
+});
+const renameOp = (path, newName) => ({
+	op: "$rename",
+	path,
+	newName
+});
+const incOp = (path, amount) => ({
+	op: "$inc",
+	path,
+	amount
+});
+const mulOp = (path, factor) => ({
+	op: "$mul",
+	path,
+	factor
+});
+const minOp = (path, value) => ({
+	op: "$min",
+	path,
+	value
+});
+const maxOp = (path, value) => ({
+	op: "$max",
+	path,
+	value
+});
+const pushOp = (path, value) => ({
+	op: "$push",
+	path,
+	value
+});
+const addToSetOp = (path, value) => ({
+	op: "$addToSet",
+	path,
+	value
+});
+const popOp = (path, direction) => ({
+	op: "$pop",
+	path,
+	direction
+});
+const pullOp = (path, value) => ({
+	op: "$pull",
+	path,
+	value
+});
+const pullAllOp = (path, values) => ({
+	op: "$pullAll",
+	path,
+	values
+});
+const currentDateOp = (path) => ({
+	op: "$currentDate",
+	path
+});
+const setOnInsertOp = (path, value) => ({
+	op: "$setOnInsert",
+	path,
+	value
+});
+/**
+* Fold an array of `TypedUpdateOp` into the non-pipeline variant of
+* `MongoUpdateSpec` (`{ $set: { … }, $inc: { … }, … }`).
+*
+* Throws if the same operator targets the same path twice — a clear authoring
+* error that Mongo would otherwise silently coalesce.
+*/
+function foldUpdateOps(ops) {
+	const buckets = {};
+	const seen = /* @__PURE__ */ new Set();
+	const ensure = (key) => {
+		let bucket = buckets[key];
+		if (!bucket) {
+			bucket = {};
+			buckets[key] = bucket;
+		}
+		return bucket;
+	};
+	const claim = (op, path) => {
+		const k = `${op}::${path}`;
+		if (seen.has(k)) throw new Error(`Update spec collision: ${op} on '${path}' was specified more than once. Combine the operations into a single call site.`);
+		seen.add(k);
+	};
+	for (const entry of ops) {
+		claim(entry.op, entry.path);
+		switch (entry.op) {
+			case "$set":
+			case "$min":
+			case "$max":
+			case "$push":
+			case "$addToSet":
+			case "$pull":
+			case "$setOnInsert":
+				ensure(entry.op)[entry.path] = entry.value;
+				break;
+			case "$unset":
+				ensure("$unset")[entry.path] = "";
+				break;
+			case "$rename":
+				ensure("$rename")[entry.path] = entry.newName;
+				break;
+			case "$inc":
+				ensure("$inc")[entry.path] = entry.amount;
+				break;
+			case "$mul":
+				ensure("$mul")[entry.path] = entry.factor;
+				break;
+			case "$pop":
+				ensure("$pop")[entry.path] = entry.direction;
+				break;
+			case "$pullAll":
+				ensure("$pullAll")[entry.path] = entry.values;
+				break;
+			case "$currentDate":
+				ensure("$currentDate")[entry.path] = true;
+				break;
+		}
+	}
+	return buckets;
+}
+/**
+* Classify an array of updater items and produce a `MongoUpdateSpec`.
+*
+* - All `TypedUpdateOp` → fold via `foldUpdateOps` (classic `{ $set, $inc, … }`)
+* - All `MongoUpdatePipelineStage` → return as-is (pipeline-style update)
+* - Mixed → throw (also a type error at the call site via the union shape)
+*/
+function resolveUpdaterResult(items) {
+	if (items.length === 0) throw new Error("Updater returned no operations. Return at least one update from the callback (e.g. `[f.amount.set(0)]`).");
+	const isOp = (item) => "op" in item && typeof item.op === "string";
+	const first = items[0];
+	if (first === void 0) throw new Error("Unreachable: items.length > 0 but first is undefined");
+	const firstIsOp = isOp(first);
+	for (let i = 1; i < items.length; i++) {
+		const item = items[i];
+		if (item === void 0) continue;
+		if (isOp(item) !== firstIsOp) throw new Error("Cannot mix TypedUpdateOp values and pipeline stages in a single updater. Use either `[f.amount.set(0)]` (operator form) or `[f.stage.set({...})]` (pipeline form), not both.");
+	}
+	if (firstIsOp) return foldUpdateOps(items);
+	return items;
+}
+
+//#endregion
+//#region src/field-accessor.ts
+function buildStageEmitters() {
+	return {
+		set: (fields) => new MongoAddFieldsStage(fields),
+		unset: (...paths) => {
+			const spec = {};
+			for (const p of paths) spec[p] = 0;
+			return new MongoProjectStage(spec);
+		},
+		replaceRoot: (newRoot) => new MongoReplaceRootStage(newRoot),
+		replaceWith: (newRoot) => new MongoReplaceRootStage(newRoot)
+	};
+}
+function buildExpression(path) {
+	return {
+		_field: void 0,
+		_path: path,
+		node: MongoAggFieldRef.of(path),
+		eq: (value) => MongoFieldFilter.eq(path, value),
+		ne: (value) => MongoFieldFilter.neq(path, value),
+		gt: (value) => MongoFieldFilter.gt(path, value),
+		gte: (value) => MongoFieldFilter.gte(path, value),
+		lt: (value) => MongoFieldFilter.lt(path, value),
+		lte: (value) => MongoFieldFilter.lte(path, value),
+		in: (values) => MongoFieldFilter.in(path, values),
+		nin: (values) => MongoFieldFilter.nin(path, values),
+		exists: (flag) => flag === false ? MongoExistsExpr.notExists(path) : MongoExistsExpr.exists(path),
+		set: (value) => setOp(path, value),
+		unset: () => unsetOp(path),
+		rename: (newName) => renameOp(path, newName),
+		inc: (amount) => incOp(path, amount),
+		mul: (factor) => mulOp(path, factor),
+		min: (value) => minOp(path, value),
+		max: (value) => maxOp(path, value),
+		push: (value) => pushOp(path, value),
+		addToSet: (value) => addToSetOp(path, value),
+		pop: (direction = 1) => popOp(path, direction),
+		pull: (value) => pullOp(path, value),
+		pullAll: (values) => pullAllOp(path, values),
+		currentDate: () => currentDateOp(path),
+		setOnInsert: (value) => setOnInsertOp(path, value)
+	};
+}
+/**
+* Construct a unified `FieldAccessor<S, N>` proxy. Property access creates
+* an `Expression` using the property name as the field path; callable
+* form accepts a dot-path string validated against `N` at compile time.
+*
+* The proxy target is a function so the resulting object is both callable
+* and indexable. Symbol-keyed accesses (e.g. `Symbol.toPrimitive`) return
+* `undefined` to keep accidental coercion behaviour unsurprising —
+* matching the previous `FieldProxy` / `FilterProxy` semantics.
+*/
+function createFieldAccessor() {
+	const stageInstance = buildStageEmitters();
+	const callable = ((path) => buildExpression(path));
+	return new Proxy(callable, { get(target, prop, receiver) {
+		if (typeof prop === "symbol") return Reflect.get(target, prop, receiver);
+		if (prop === "stage") return stageInstance;
+		if (prop === "rawPath") return (path) => buildExpression(path);
+		return buildExpression(prop);
+	} });
+}
+
+//#endregion
+//#region src/builder.ts
+/**
+* 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",
+			paramDescriptors: []
+		};
+	}
+	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$1) {
+		const newFields = fn$1(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).
+	*/
+	lookup(options) {
+		const contract = this.#contract;
+		const modelName = contract.roots[options.from];
+		if (!modelName) {
+			const validRoots = Object.keys(contract.roots).join(", ");
+			throw new Error(`lookup() unknown root: "${options.from}". Valid roots: ${validRoots}`);
+		}
+		const collectionName = contract.models[modelName]?.storage?.collection ?? options.from;
+		return this.#withStage(new MongoLookupStage({
+			from: collectionName,
+			localField: options.localField,
+			foreignField: options.foreignField,
+			as: options.as
+		}));
+	}
+	project(...args) {
+		if (args.length === 1 && typeof args[0] === "function") {
+			const fn$1 = args[0];
+			const spec = fn$1(createFieldAccessor());
+			const projection$1 = {};
+			for (const [key, val] of Object.entries(spec)) projection$1[key] = val === 1 ? 1 : val.node;
+			return this.#withStage(new MongoProjectStage(projection$1));
+		}
+		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$1) {
+		const { _id: groupIdExpr, ...rest } = fn$1(createFieldAccessor());
+		const groupId = groupIdExpr === null ? null : groupIdExpr.node;
+		const accumulators = {};
+		for (const [key, typed] of Object.entries(rest)) {
+			if (typed === null) throw new Error(`group() field "${key}" must not be null. Only _id can be null.`);
+			if (typed.node.kind !== "accumulator") throw new Error(`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$1) {
+		const expr = fn$1(createFieldAccessor());
+		return this.#withStage(new MongoReplaceRootStage(expr.node));
+	}
+	count(field) {
+		return this.#withStage(new MongoCountStage(field));
+	}
+	sortByCount(fn$1) {
+		const expr = fn$1(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$1) {
+		const expr = fn$1(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",
+			paramDescriptors: []
+		};
+		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 new Error("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 new Error("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",
+			paramDescriptors: []
+		};
+		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",
+			paramDescriptors: []
+		};
+		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",
+			paramDescriptors: []
+		};
+		return {
+			collection: this.#state.collection,
+			command,
+			meta
+		};
+	}
+	/**
+	* 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 new Error("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 new Error("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 new Error("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 new Error(`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 new Error("findOneAndUpdate/findOneAndDelete requires at least one .match() call.");
+	const first = matchFilters[0];
+	if (first === void 0) throw new Error("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 new Error("No-arg updateMany/updateOne requires at least one .match() call.");
+	const remaining = stages.slice(boundary);
+	if (remaining.length === 0) throw new Error("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 new Error(`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 Error("Unreachable: matchFilters.length > 0 but first is undefined");
+	return {
+		filter: matchFilters.length === 1 ? first : MongoAndExpr.of(matchFilters),
+		updatePipeline
+	};
+}
+
+//#endregion
+//#region src/expression-helpers.ts
+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);
+	}
+};
+
+//#endregion
+//#region src/state-classes.ts
+/**
+* "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",
+		paramDescriptors: []
+	};
+}
+/**
+* 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
+		});
+		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 new Error("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 Error("FilteredCollection requires at least one accumulated filter");
+		const first = filters[0];
+		if (first === void 0) throw new Error("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
+		});
+		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 Error("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];
+	if (!modelName) {
+		const validRoots = Object.keys(c.roots).join(", ");
+		throw new Error(`Unknown root: "${rootName}". Valid roots: ${validRoots}`);
+	}
+	const model = c.models[modelName];
+	if (!model) throw new Error(`Unknown model: "${modelName}" referenced by root "${rootName}".`);
+	const collectionName = model.storage?.collection ?? rootName;
+	if (!c.storage?.storageHash) throw new Error("Contract is missing storage.storageHash. Pass a validated contract to mongoQuery().");
+	return new CollectionHandle({
+		contract,
+		collection: collectionName,
+		storageHash: String(c.storage.storageHash)
+	}, modelName);
+}
+
+//#endregion
+//#region src/query.ts
+function mongoQuery(options) {
+	const contract = options.contractJson;
+	return {
+		from(rootName) {
+			return createCollectionHandle(contract, rootName);
+		},
+		rawCommand(command) {
+			const storageHash = asMongoContract(contract).storage?.storageHash;
+			if (!storageHash) throw new Error("Contract is missing storage.storageHash. Pass a validated contract to mongoQuery().");
+			const meta = {
+				target: "mongo",
+				storageHash: String(storageHash),
+				lane: "mongo-query",
+				paramDescriptors: []
+			};
+			return {
+				collection: command.collection,
+				command,
+				meta
+			};
+		}
+	};
+}
+
+//#endregion
+export { CollectionHandle, FilteredCollection, PipelineChain, acc, createFieldAccessor, fn, mongoQuery };
+//# sourceMappingURL=index.mjs.map