@classytic/mongokit 3.12.0 → 3.13.0

package/dist/Repository-BY40uhcv.mjs

@@ -0,0 +1,3603 @@
+import { a as count, b as LookupBuilder, c as getByQuery, d as deleteById, f as deleteByQuery, h as createMany, l as getOrCreate, m as create, n as update, o as exists, r as updateByQuery, s as getById, t as findOneAndUpdate, x as compileFilterToMongo, y as distinct } from "./update-DLcSSa5b.mjs";
+import { n as warn } from "./logger-DprijP5h.mjs";
+import { n as isDuplicateKeyError, r as parseDuplicateKeyError, t as createError } from "./error-B00pI7dV.mjs";
+import { t as PaginationEngine } from "./PaginationEngine-CfQRM1yz.mjs";
+import { hasNearOperator, rewriteNearForCount } from "./query/primitives/geo.mjs";
+import { r as isValidIdForType, t as getSchemaIdType } from "./id-resolution-B0Odvvou.mjs";
+import { isFilter } from "@classytic/repo-core/filter";
+import mongoose from "mongoose";
+import { HOOK_PRIORITY } from "@classytic/repo-core/hooks";
+import { RepositoryBase, validatePluginOrder } from "@classytic/repo-core/repository";
+import { compileUpdateSpecToMongo, isUpdateSpec } from "@classytic/repo-core/update";
+import { decodeAggCursor, encodeAggCursor, isKeysetMode, normalizeGroupBy, validateMeasures } from "@classytic/repo-core/aggregate";
+//#region src/operations.ts
+/**
+* The registry. Order intentionally groups by category for readability.
+* Adding a new RepositoryOperation requires exactly one entry here, after
+* which every bundled plugin auto-classifies it correctly.
+*/
+const OP_REGISTRY = {
+	create: {
+		policyKey: "data",
+		mutates: true,
+		hasIdContext: false
+	},
+	update: {
+		policyKey: "query",
+		mutates: true,
+		hasIdContext: true
+	},
+	findOneAndUpdate: {
+		policyKey: "query",
+		mutates: true,
+		hasIdContext: false
+	},
+	claim: {
+		policyKey: "query",
+		mutates: true,
+		hasIdContext: true
+	},
+	claimVersion: {
+		policyKey: "query",
+		mutates: true,
+		hasIdContext: true
+	},
+	delete: {
+		policyKey: "query",
+		mutates: true,
+		hasIdContext: true
+	},
+	restore: {
+		policyKey: "query",
+		mutates: true,
+		hasIdContext: true
+	},
+	createMany: {
+		policyKey: "dataArray",
+		mutates: true,
+		hasIdContext: false
+	},
+	updateMany: {
+		policyKey: "query",
+		mutates: true,
+		hasIdContext: false
+	},
+	deleteMany: {
+		policyKey: "query",
+		mutates: true,
+		hasIdContext: false
+	},
+	bulkWrite: {
+		policyKey: "operations",
+		mutates: true,
+		hasIdContext: false
+	},
+	getById: {
+		policyKey: "query",
+		mutates: false,
+		hasIdContext: true
+	},
+	getByQuery: {
+		policyKey: "query",
+		mutates: false,
+		hasIdContext: false
+	},
+	getOne: {
+		policyKey: "query",
+		mutates: false,
+		hasIdContext: false
+	},
+	findAll: {
+		policyKey: "query",
+		mutates: false,
+		hasIdContext: false
+	},
+	getOrCreate: {
+		policyKey: "query",
+		mutates: false,
+		hasIdContext: false
+	},
+	count: {
+		policyKey: "query",
+		mutates: false,
+		hasIdContext: false
+	},
+	exists: {
+		policyKey: "query",
+		mutates: false,
+		hasIdContext: false
+	},
+	distinct: {
+		policyKey: "query",
+		mutates: false,
+		hasIdContext: false
+	},
+	aggregate: {
+		policyKey: "query",
+		mutates: false,
+		hasIdContext: false
+	},
+	aggregatePipeline: {
+		policyKey: "query",
+		mutates: false,
+		hasIdContext: false
+	},
+	cursor: {
+		policyKey: "query",
+		mutates: false,
+		hasIdContext: false
+	},
+	getAll: {
+		policyKey: "filters",
+		mutates: false,
+		hasIdContext: false
+	},
+	aggregatePaginate: {
+		policyKey: "filters",
+		mutates: false,
+		hasIdContext: false
+	},
+	aggregatePipelinePaginate: {
+		policyKey: "filters",
+		mutates: false,
+		hasIdContext: false
+	},
+	lookupPopulate: {
+		policyKey: "filters",
+		mutates: false,
+		hasIdContext: false
+	}
+};
+/** All known repository operations, in registry order. */
+const ALL_OPERATIONS = Object.keys(OP_REGISTRY);
+/** Operations that mutate the database. Drives audit + cache invalidation lists. */
+const MUTATING_OPERATIONS = ALL_OPERATIONS.filter((op) => OP_REGISTRY[op].mutates);
+/** Operations that don't mutate. Drives default cacheable ops. */
+const READ_OPERATIONS = ALL_OPERATIONS.filter((op) => !OP_REGISTRY[op].mutates);
+/** Filter ops by their policy injection key. */
+function operationsByPolicyKey(key) {
+	return ALL_OPERATIONS.filter((op) => OP_REGISTRY[op].policyKey === key);
+}
+//#endregion
+//#region src/actions/aggregate-ir/hints.ts
+function applyExecutionHints(aggregation, hints) {
+	if (!hints) return;
+	if (hints.allowDiskUse) aggregation.allowDiskUse(true);
+	if (typeof hints.maxTimeMs === "number" && hints.maxTimeMs > 0) aggregation.option({ maxTimeMS: hints.maxTimeMs });
+	if (hints.indexHint !== void 0) aggregation.option({ hint: hints.indexHint });
+}
+//#endregion
+//#region src/actions/aggregate-ir/normalize.ts
+/**
+* AggRequest → input normalization (mongokit binding).
+*
+* Re-exports the kit-neutral helpers from `@classytic/repo-core/aggregate`
+* with the mongokit error-prefix pre-bound, so call sites stay free of
+* boilerplate. The actual logic lives in repo-core — when the rules
+* for what a valid AggRequest looks like change, update the IR
+* contract there.
+*/
+function validateMeasures$1(measures) {
+	validateMeasures(measures, "mongokit");
+}
+//#endregion
+//#region src/actions/aggregate-ir/dateBucket.ts
+/**
+* Compile a `AggDateBucket` to the mongo expression that produces the
+* bucket label string for a single document. Used in two places:
+*
+*   1. Inside `$group._id` so the aggregator groups by the bucket
+*      label (one row per distinct bucket).
+*   2. Inside `$project` to flatten `_id.<alias>` into a top-level
+*      column on the output row — matches the cross-kit shape.
+*/
+function compileDateBucket(bucket) {
+	const dateExpr = { $toDate: `$${bucket.field}` };
+	if (typeof bucket.interval === "object") {
+		const { every, unit } = bucket.interval;
+		if (!Number.isInteger(every) || every <= 0) throw new Error(`mongokit/aggregate: dateBucket.interval.every must be a positive integer — got ${String(every)}`);
+		const truncated = { $dateTrunc: {
+			date: dateExpr,
+			unit,
+			binSize: every,
+			timezone: "UTC"
+		} };
+		return { $dateToString: {
+			format: formatForUnit(unit),
+			date: truncated,
+			timezone: "UTC"
+		} };
+	}
+	switch (bucket.interval) {
+		case "minute": return { $dateToString: {
+			format: "%Y-%m-%dT%H:%M",
+			date: dateExpr,
+			timezone: "UTC"
+		} };
+		case "hour": return { $dateToString: {
+			format: "%Y-%m-%dT%H:00",
+			date: dateExpr,
+			timezone: "UTC"
+		} };
+		case "day": return { $dateToString: {
+			format: "%Y-%m-%d",
+			date: dateExpr,
+			timezone: "UTC"
+		} };
+		case "week": return { $dateToString: {
+			format: "%G-W%V",
+			date: dateExpr,
+			timezone: "UTC"
+		} };
+		case "month": return { $dateToString: {
+			format: "%Y-%m",
+			date: dateExpr,
+			timezone: "UTC"
+		} };
+		case "quarter": return { $concat: [
+			{ $dateToString: {
+				format: "%Y",
+				date: dateExpr,
+				timezone: "UTC"
+			} },
+			"-Q",
+			{ $toString: { $ceil: { $divide: [{ $month: {
+				date: dateExpr,
+				timezone: "UTC"
+			} }, 3] } } }
+		] };
+		case "year": return { $dateToString: {
+			format: "%Y",
+			date: dateExpr,
+			timezone: "UTC"
+		} };
+	}
+}
+/**
+* Choose the canonical label format for a custom-bin unit. Matches
+* the named-bucket label when `every === 1` so the cross-kit row
+* shape stays consistent regardless of which surface form the caller
+* picked.
+*/
+function formatForUnit(unit) {
+	switch (unit) {
+		case "minute": return "%Y-%m-%dT%H:%M";
+		case "hour": return "%Y-%m-%dT%H:00";
+		case "day": return "%Y-%m-%d";
+		case "week": return "%G-W%V";
+		case "month": return "%Y-%m";
+		case "quarter":
+		case "year": return "%Y";
+	}
+}
+//#endregion
+//#region src/filter/compile-expr.ts
+/**
+* Compile a Filter IR node (or already-built expression) to a MongoDB
+* aggregation expression. Returns the literal `true` for empty `and`
+* / `true` nodes so callers can use the result as a `$cond`
+* predicate without special-casing — `$cond: [true, X, Y]` short-
+* circuits to `X` at planning time.
+*
+* The `input` is typed as `unknown` so callers can pass either a
+* Filter IR node or an already-built expression and we dispatch
+* appropriately. This mirrors `compileFilterToMongo`'s ergonomic
+* dispatch.
+*/
+function compileFilterToMongoExpr(input) {
+	if (input === void 0 || input === null) return true;
+	if (!isFilter(input)) return input;
+	return compile(input);
+}
+function compile(filter) {
+	switch (filter.op) {
+		case "true": return true;
+		case "false": return false;
+		case "eq": return { $eq: [`$${filter.field}`, filter.value] };
+		case "ne": return filter.value === null ? { $ne: [`$${filter.field}`, null] } : { $and: [{ $ne: [`$${filter.field}`, filter.value] }, { $ne: [`$${filter.field}`, null] }] };
+		case "gt": return { $gt: [`$${filter.field}`, filter.value] };
+		case "gte": return { $gte: [`$${filter.field}`, filter.value] };
+		case "lt": return { $lt: [`$${filter.field}`, filter.value] };
+		case "lte": return { $lte: [`$${filter.field}`, filter.value] };
+		case "in":
+			if (filter.values.length === 0) return false;
+			return { $in: [`$${filter.field}`, [...filter.values]] };
+		case "nin":
+			if (filter.values.length === 0) return true;
+			return { $not: [{ $in: [`$${filter.field}`, [...filter.values]] }] };
+		case "exists": return filter.exists ? { $ne: [`$${filter.field}`, null] } : { $eq: [`$${filter.field}`, null] };
+		case "like": return { $regexMatch: {
+			input: `$${filter.field}`,
+			regex: likeToRegexPattern(filter.pattern),
+			...filter.caseSensitivity === "sensitive" ? {} : { options: "i" }
+		} };
+		case "regex": return { $regexMatch: {
+			input: `$${filter.field}`,
+			regex: filter.pattern
+		} };
+		case "and": {
+			if (filter.children.length === 0) return true;
+			const parts = filter.children.map(compile);
+			if (parts.length === 1) return parts[0];
+			return { $and: parts };
+		}
+		case "or": {
+			if (filter.children.length === 0) return false;
+			const parts = filter.children.map(compile);
+			if (parts.length === 1) return parts[0];
+			return { $or: parts };
+		}
+		case "not": return { $not: [compile(filter.child)] };
+		case "raw": throw new Error("mongokit/filter: `raw` is a SQL escape hatch and has no safe MongoDB expression translation. Pass an aggregation expression directly instead.");
+	}
+}
+/**
+* Translate a SQL LIKE pattern to a regex pattern string (without
+* the `^$` anchors and `$options` field — those layer on top per
+* call site). Mirrors `likeToRegex` in the query compiler.
+*/
+function likeToRegexPattern(pattern) {
+	let out = "^";
+	for (let i = 0; i < pattern.length; i++) {
+		const ch = pattern[i];
+		if (ch === "\\" && i + 1 < pattern.length) {
+			const next = pattern[i + 1];
+			if (next === "%" || next === "_" || next === "\\") {
+				out += escapeRegexChar(next);
+				i++;
+				continue;
+			}
+		}
+		if (ch === "%") out += ".*";
+		else if (ch === "_") out += ".";
+		else out += escapeRegexChar(ch);
+	}
+	out += "$";
+	return out;
+}
+function escapeRegexChar(ch) {
+	return /[.*+?^${}()|[\]\\]/.test(ch) ? `\\${ch}` : ch;
+}
+//#endregion
+//#region src/actions/aggregate-ir/measure.ts
+function compileMeasure(measure) {
+	const whereExpr = measure.where !== void 0 ? compileFilterToMongoExpr(measure.where) : void 0;
+	switch (measure.op) {
+		case "count": {
+			const fieldName = measure.field;
+			const baseCondition = !fieldName || fieldName === "*" ? true : { $ne: [`$${fieldName}`, null] };
+			const condition = whereExpr === void 0 ? baseCondition : baseCondition === true ? whereExpr : { $and: [baseCondition, whereExpr] };
+			if (condition === true) return { groupExpr: { $sum: 1 } };
+			return { groupExpr: { $sum: { $cond: [
+				condition,
+				1,
+				0
+			] } } };
+		}
+		case "countDistinct": return {
+			groupExpr: { $addToSet: whereExpr === void 0 ? `$${measure.field}` : { $cond: [
+				whereExpr,
+				`$${measure.field}`,
+				"$$REMOVE"
+			] } },
+			projectExpr: { $size: { $ifNull: ["$$CURRENT", []] } }
+		};
+		case "sum": return { groupExpr: { $sum: whereExpr === void 0 ? `$${measure.field}` : { $cond: [
+			whereExpr,
+			`$${measure.field}`,
+			0
+		] } } };
+		case "avg": return { groupExpr: { $avg: whereExpr === void 0 ? `$${measure.field}` : { $cond: [
+			whereExpr,
+			`$${measure.field}`,
+			null
+		] } } };
+		case "min": return { groupExpr: { $min: whereExpr === void 0 ? `$${measure.field}` : { $cond: [
+			whereExpr,
+			`$${measure.field}`,
+			null
+		] } } };
+		case "max": return { groupExpr: { $max: whereExpr === void 0 ? `$${measure.field}` : { $cond: [
+			whereExpr,
+			`$${measure.field}`,
+			null
+		] } } };
+		case "stddev": return { groupExpr: { $stdDevSamp: whereExpr === void 0 ? `$${measure.field}` : { $cond: [
+			whereExpr,
+			`$${measure.field}`,
+			null
+		] } } };
+		case "stddevPop": return { groupExpr: { $stdDevPop: whereExpr === void 0 ? `$${measure.field}` : { $cond: [
+			whereExpr,
+			`$${measure.field}`,
+			null
+		] } } };
+		case "percentile":
+			if (typeof measure.p !== "number" || measure.p < 0 || measure.p > 1) throw new Error(`mongokit/aggregate: 'percentile' requires p in [0, 1] — got ${String(measure.p)}`);
+			return {
+				groupExpr: { $percentile: {
+					input: whereExpr === void 0 ? `$${measure.field}` : { $cond: [
+						whereExpr,
+						`$${measure.field}`,
+						null
+					] },
+					p: [measure.p],
+					method: "approximate"
+				} },
+				projectExpr: { $arrayElemAt: ["$$CURRENT", 0] }
+			};
+	}
+}
+//#endregion
+//#region src/actions/aggregate-ir/pipeline.ts
+function buildAggPipeline(req) {
+	validateMeasures$1(req.measures);
+	const groupCols = normalizeGroupBy(req.groupBy);
+	const bucketAliases = req.dateBuckets ? Object.keys(req.dateBuckets) : [];
+	validateBucketAliases(bucketAliases, groupCols, req.measures);
+	const stages = [];
+	const aliasSet = new Set((req.lookups ?? []).map((l) => l.as ?? l.from));
+	const { base: baseFilter, joined: joinedFilter } = splitFilterByAlias(req.filter, aliasSet);
+	if (baseFilter !== void 0) {
+		const match = compileFilterToMongo(baseFilter);
+		if (Object.keys(match).length > 0) stages.push({ $match: match });
+	}
+	if (req.lookups && req.lookups.length > 0) appendLookupStages(stages, req.lookups);
+	if (joinedFilter !== void 0) {
+		const match = compileFilterToMongo(joinedFilter);
+		if (Object.keys(match).length > 0) stages.push({ $match: match });
+	}
+	const bucketInternalKey = (alias) => `__bucket_${alias}`;
+	if (req.dateBuckets && bucketAliases.length > 0) {
+		const addFields = {};
+		for (const alias of bucketAliases) addFields[bucketInternalKey(alias)] = compileDateBucket(req.dateBuckets[alias]);
+		stages.push({ $addFields: addFields });
+	}
+	const groupStage = { _id: groupCols.length === 0 && bucketAliases.length === 0 ? null : (() => {
+		const id = {};
+		for (const field of groupCols) id[safeIdKey(field)] = `$${field}`;
+		for (const alias of bucketAliases) id[alias] = `$${bucketInternalKey(alias)}`;
+		return id;
+	})() };
+	const distinctSetAliases = [];
+	const percentileAliases = [];
+	for (const [alias, measure] of Object.entries(req.measures)) {
+		groupStage[alias] = compileMeasure(measure).groupExpr;
+		if (measure.op === "countDistinct") distinctSetAliases.push(alias);
+		else if (measure.op === "percentile") percentileAliases.push(alias);
+	}
+	stages.push({ $group: groupStage });
+	if (distinctSetAliases.length > 0) {
+		const addFields = {};
+		for (const alias of distinctSetAliases) addFields[alias] = { $size: { $ifNull: [`$${alias}`, []] } };
+		stages.push({ $addFields: addFields });
+	}
+	if (percentileAliases.length > 0) {
+		const addFields = {};
+		for (const alias of percentileAliases) addFields[alias] = { $arrayElemAt: [{ $ifNull: [`$${alias}`, [null]] }, 0] };
+		stages.push({ $addFields: addFields });
+	}
+	const projection = { _id: 0 };
+	for (const field of groupCols) projection[field] = `$_id.${safeIdKey(field)}`;
+	for (const alias of bucketAliases) projection[alias] = `$_id.${alias}`;
+	for (const alias of Object.keys(req.measures)) projection[alias] = 1;
+	stages.push({ $project: projection });
+	if (req.having) {
+		const match = compileFilterToMongo(req.having);
+		if (Object.keys(match).length > 0) stages.push({ $match: match });
+	}
+	if (req.topN) {
+		validateTopN(req.topN, groupCols, bucketAliases, req.measures);
+		appendTopNStages(stages, req.topN);
+	}
+	const prePaginationIndex = stages.length;
+	if (req.sort) stages.push({ $sort: req.sort });
+	if (typeof req.offset === "number" && req.offset > 0) stages.push({ $skip: req.offset });
+	if (typeof req.limit === "number") stages.push({ $limit: req.limit });
+	return {
+		pipeline: stages,
+		prePaginationIndex
+	};
+}
+/**
+* Validate the `topN` spec against the rest of the request:
+*
+*   1. `partitionBy` columns must each be a `groupBy` field, a
+*      `dateBuckets` alias, OR a measure alias — otherwise the
+*      partition resolves to the same key for every row and top-N
+*      becomes a global limit.
+*   2. `limit` must be a positive integer.
+*   3. `sortBy` must be non-empty (rank without an order is meaningless).
+*
+* All checks throw at request time with a message naming the bad
+* field — so the failure surface is the buggy AggRequest, not a
+* silent "no rows" downstream.
+*/
+function validateTopN(topN, groupCols, bucketAliases, measures) {
+	if (!Number.isInteger(topN.limit) || topN.limit <= 0) throw new Error(`mongokit/aggregate: topN.limit must be a positive integer — got ${String(topN.limit)}`);
+	if (!topN.sortBy || Object.keys(topN.sortBy).length === 0) throw new Error("mongokit/aggregate: topN.sortBy must declare at least one ranking field");
+	const partitionList = Array.isArray(topN.partitionBy) ? topN.partitionBy : [topN.partitionBy];
+	const validKeys = new Set([
+		...groupCols,
+		...bucketAliases,
+		...Object.keys(measures)
+	]);
+	for (const key of partitionList) if (!validKeys.has(key)) throw new Error(`mongokit/aggregate: topN.partitionBy "${key}" is not a groupBy field, dateBucket alias, or measure alias`);
+}
+/**
+* Append the `$setWindowFields` + `$match` + `$project` stages that
+* implement top-N-per-group. Runs after the post-group projection,
+* so partition / sort keys reference output column names directly
+* (no `_id.`-prefix juggling).
+*
+* Tie-breaking strategy maps:
+*   - `'rank'`        → `$rank`            (default; gaps after ties)
+*   - `'dense_rank'`  → `$denseRank`        (no gaps)
+*   - `'row_number'`  → `$documentNumber`   (each row unique)
+*/
+function appendTopNStages(stages, topN) {
+	const partitionList = Array.isArray(topN.partitionBy) ? topN.partitionBy : [topN.partitionBy];
+	const partitionExpr = partitionList.length === 1 ? `$${partitionList[0]}` : { $concat: partitionList.flatMap((field, i) => {
+		const ref = { $toString: { $ifNull: [`$${field}`, "__NULL__"] } };
+		return i === 0 ? [ref] : ["
", ref];
+	}) };
+	const tiesOp = topN.ties === "dense_rank" ? "$denseRank" : topN.ties === "row_number" ? "$documentNumber" : "$rank";
+	const RANK_FIELD = "__topNRank";
+	stages.push({ $setWindowFields: {
+		partitionBy: partitionExpr,
+		sortBy: topN.sortBy,
+		output: { [RANK_FIELD]: { [tiesOp]: {} } }
+	} });
+	stages.push({ $match: { [RANK_FIELD]: { $lte: topN.limit } } });
+	stages.push({ $project: { [RANK_FIELD]: 0 } });
+}
+/**
+* Fail loud when a date-bucket alias collides with a `groupBy` column
+* or measure alias. The output row would otherwise contain ambiguous
+* keys — last writer wins on the projection, silently swapping
+* group-key values for measure values (or vice versa).
+*
+* Caught at compile time so the failure surface is the buggy
+* AggRequest, not a downstream consumer reading the wrong column.
+*/
+function validateBucketAliases(bucketAliases, groupCols, measures) {
+	if (bucketAliases.length === 0) return;
+	const groupSet = new Set(groupCols);
+	const measureSet = new Set(Object.keys(measures));
+	for (const alias of bucketAliases) {
+		if (groupSet.has(alias)) throw new Error(`mongokit/aggregate: dateBuckets alias "${alias}" collides with a groupBy field of the same name`);
+		if (measureSet.has(alias)) throw new Error(`mongokit/aggregate: dateBuckets alias "${alias}" collides with a measure of the same name`);
+	}
+}
+/**
+* Compile `LookupSpec[]` into mongo `$lookup` stages and append them
+* to the running pipeline. Mirrors the lookup section of
+* `lookupPopulate()` so cross-operation behavior stays identical:
+*
+*   - Each lookup contributes one `$lookup` stage (pipeline-form when
+*     `where` / `select` is set, simple form otherwise).
+*   - `single: true` lookups also emit an `$addFields` coalesce so
+*     the joined value becomes `null` instead of `[]` when no row
+*     matches (so `$group._id` keys are stable instead of falling
+*     into a single empty-array bucket).
+*/
+/**
+* Convert a (potentially dotted) groupBy field name into a safe key
+* for use inside `$group._id`. BSON disallows `.` in field names
+* anywhere — including the `_id` document — so dotted paths get the
+* `.` replaced with `__`. Plain field names pass through unchanged.
+*
+* Pairs with the `$project` stage that rebuilds the original dotted
+* key on the OUTPUT row, which Mongo then nests automatically (e.g.
+* projection key `'department.code'` produces `{ department: { code }}`).
+*
+* Cross-kit shape contract: see repo-core's `AggRow` doc and
+* `nestDottedKeys` helper.
+*/
+function safeIdKey(field) {
+	return field.includes(".") ? field.replace(/\./g, "__") : field;
+}
+function appendLookupStages(stages, lookups) {
+	const asLookupOptions = lookups;
+	stages.push(...LookupBuilder.multiple(asLookupOptions));
+	for (const lookup of lookups) if (lookup.single) {
+		const asField = lookup.as ?? lookup.from;
+		stages.push({ $addFields: { [asField]: { $ifNull: [`$${asField}`, null] } } });
+	}
+}
+/**
+* Split a filter into base-side and joined-side predicates so the
+* caller can emit two `$match` stages — one BEFORE `$lookup` (for
+* base columns, leveraging indexes) and one AFTER `$lookup` (for
+* joined-alias references that don't exist pre-lookup).
+*
+* Behavior by input shape:
+*
+*   - **`undefined`** → both sides `undefined`.
+*   - **Plain record** (Mongo-style query object) → keys split by
+*     prefix: `'<alias>.<col>'` → joined; everything else → base.
+*     Top-level mongo operators (`$or`, `$and`) that mix base + joined
+*     references can't be cleanly split — the whole record routes
+*     post-lookup so semantics stay correct (at the cost of losing
+*     pre-lookup index usage on those branches).
+*   - **Filter IR** — top-level `and(...)` splits children by joined-
+*     alias presence; non-AND nodes route entirely to one side based
+*     on whether any leaf references an alias.
+*
+* No lookups (`aliasSet` empty) — short-circuit: entire filter is
+* base-side. Matches the no-join legacy behavior exactly.
+*/
+function splitFilterByAlias(filter, aliasSet) {
+	if (filter === void 0 || filter === null) return {
+		base: void 0,
+		joined: void 0
+	};
+	if (aliasSet.size === 0) return {
+		base: filter,
+		joined: void 0
+	};
+	if (!isFilter(filter)) return splitRecordByAlias(filter, aliasSet);
+	return splitIRByAlias(filter, aliasSet);
+}
+function splitRecordByAlias(record, aliasSet) {
+	const base = {};
+	const joined = {};
+	let hasMixedTopOp = false;
+	for (const [key, value] of Object.entries(record)) {
+		if (key.startsWith("$") && Array.isArray(value)) {
+			if (value.some((branch) => recordReferencesAlias(branch, aliasSet))) {
+				hasMixedTopOp = true;
+				continue;
+			}
+			base[key] = value;
+			continue;
+		}
+		const dot = key.indexOf(".");
+		const prefix = dot > 0 ? key.slice(0, dot) : null;
+		if (prefix && aliasSet.has(prefix)) joined[key] = value;
+		else base[key] = value;
+	}
+	if (hasMixedTopOp) return {
+		base: void 0,
+		joined: record
+	};
+	return {
+		base: Object.keys(base).length > 0 ? base : void 0,
+		joined: Object.keys(joined).length > 0 ? joined : void 0
+	};
+}
+function recordReferencesAlias(record, aliasSet) {
+	for (const key of Object.keys(record)) {
+		const dot = key.indexOf(".");
+		if (dot > 0 && aliasSet.has(key.slice(0, dot))) return true;
+	}
+	return false;
+}
+function splitIRByAlias(filter, aliasSet) {
+	if (filter.op === "and") {
+		const baseChildren = [];
+		const joinedChildren = [];
+		for (const child of filter.children) if (irReferencesAlias(child, aliasSet)) joinedChildren.push(child);
+		else baseChildren.push(child);
+		return {
+			base: andOrSingle(baseChildren),
+			joined: andOrSingle(joinedChildren)
+		};
+	}
+	if (irReferencesAlias(filter, aliasSet)) return {
+		base: void 0,
+		joined: filter
+	};
+	return {
+		base: filter,
+		joined: void 0
+	};
+}
+function andOrSingle(children) {
+	if (children.length === 0) return void 0;
+	if (children.length === 1) return children[0];
+	return {
+		op: "and",
+		children: Object.freeze(children)
+	};
+}
+function irReferencesAlias(filter, aliasSet) {
+	const node = filter;
+	if (typeof node.field === "string") {
+		const dot = node.field.indexOf(".");
+		if (dot > 0 && aliasSet.has(node.field.slice(0, dot))) return true;
+	}
+	if (Array.isArray(node.children)) return node.children.some((c) => irReferencesAlias(c, aliasSet));
+	if (node.child) return irReferencesAlias(node.child, aliasSet);
+	return false;
+}
+//#endregion
+//#region src/actions/aggregate-ir/count.ts
+async function countAggGroups(Model, req, options = {}) {
+	const session = options.session;
+	const groupCols = normalizeGroupBy(req.groupBy);
+	const hasDottedGroupBy = groupCols.some((f) => f.includes("."));
+	const hasDateBuckets = !!req.dateBuckets && Object.keys(req.dateBuckets).length > 0;
+	if (req.having !== void 0 || req.lookups !== void 0 && req.lookups.length > 0 || hasDottedGroupBy || hasDateBuckets) {
+		const { pipeline, prePaginationIndex } = buildAggPipeline(req);
+		const finalPipeline = [...pipeline.slice(0, prePaginationIndex), { $count: "n" }];
+		const aggregation = Model.aggregate(finalPipeline);
+		if (session) aggregation.session(session);
+		applyExecutionHints(aggregation, req.executionHints);
+		const [row] = await aggregation.exec();
+		return row?.n ?? 0;
+	}
+	const match = req.filter ? compileFilterToMongo(req.filter) : {};
+	if (groupCols.length === 0) {
+		const pipeline = [];
+		if (Object.keys(match).length > 0) pipeline.push({ $match: match });
+		pipeline.push({ $limit: 1 });
+		pipeline.push({ $count: "n" });
+		const aggregation = Model.aggregate(pipeline);
+		if (session) aggregation.session(session);
+		applyExecutionHints(aggregation, req.executionHints);
+		const [row] = await aggregation.exec();
+		return row?.n ?? 0;
+	}
+	const groupId = groupCols.reduce((acc, field) => {
+		acc[field] = `$${field}`;
+		return acc;
+	}, {});
+	const pipeline = [];
+	if (Object.keys(match).length > 0) pipeline.push({ $match: match });
+	pipeline.push({ $group: { _id: groupId } });
+	pipeline.push({ $count: "n" });
+	const aggregation = Model.aggregate(pipeline);
+	if (session) aggregation.session(session);
+	const [row] = await aggregation.exec();
+	return row?.n ?? 0;
+}
+//#endregion
+//#region src/actions/aggregate-ir/execute.ts
+async function executeAgg(Model, req, options = {}) {
+	const session = options.session;
+	const { pipeline } = buildAggPipeline(req);
+	const aggregation = Model.aggregate(pipeline);
+	if (session) aggregation.session(session);
+	applyExecutionHints(aggregation, req.executionHints);
+	return await aggregation.exec();
+}
+//#endregion
+//#region src/actions/aggregate-ir/keyset.ts
+/**
+* Keyset (cursor) pagination helpers — mongokit binding.
+*
+* The kit-neutral half (cursor encode/decode + mode detection) lives
+* in `@classytic/repo-core/aggregate`. This file re-exports those bits
+* with the mongokit error prefix pre-bound, then layers on the
+* mongo-specific `buildKeysetPredicate` (emits a `$match` PipelineStage)
+* which has no SQL counterpart.
+*
+* **Sort keys reference OUTPUT columns** — `groupBy` field names,
+* `dateBuckets` aliases, and `measures` aliases all qualify. The
+* keyset predicate runs AFTER the post-group `$project` stage, which
+* is when the output column names exist.
+*/
+function decodeAggCursor$1(cursor) {
+	return decodeAggCursor(cursor, "mongokit");
+}
+/**
+* Build a `$match` stage that selects rows AFTER the cursor row given
+* the sort spec. Encodes the row-tuple comparison as a left-leaning
+* `$or` of progressively-deeper equality + tail inequality:
+*
+*   sort: { a: 1, b: -1, c: 1 }, after: { a, b, c }
+*   →  a > $a
+*      OR (a == $a AND b < $b)
+*      OR (a == $a AND b == $b AND c > $c)
+*
+* Returns `undefined` when the sort spec is empty or every cursor key
+* is missing — caller should reject those upstream rather than ship a
+* no-op stage.
+*/
+function buildKeysetPredicate(sort, cursor) {
+	const sortKeys = Object.keys(sort);
+	if (sortKeys.length === 0) return void 0;
+	const branches = [];
+	for (let i = 0; i < sortKeys.length; i++) {
+		const tailKey = sortKeys[i];
+		const tailOp = sort[tailKey] === 1 ? "$gt" : "$lt";
+		const branch = {};
+		for (let j = 0; j < i; j++) {
+			const eqKey = sortKeys[j];
+			branch[eqKey] = cursor[eqKey] ?? null;
+		}
+		branch[tailKey] = { [tailOp]: cursor[tailKey] ?? null };
+		branches.push(branch);
+	}
+	return { $match: branches.length === 1 ? branches[0] : { $or: branches } };
+}
+//#endregion
+//#region src/query/AggregationBuilder.ts
+/**
+* Normalize SortSpec to MongoDB's strict format (1 | -1)
+* Converts 'asc' -> 1, 'desc' -> -1
+*/
+function normalizeSortSpec(sortSpec) {
+	const normalized = {};
+	for (const [field, order] of Object.entries(sortSpec)) if (order === "asc") normalized[field] = 1;
+	else if (order === "desc") normalized[field] = -1;
+	else normalized[field] = order;
+	return normalized;
+}
+/**
+* Fluent builder for MongoDB aggregation pipelines
+* Optimized for complex queries at scale
+*/
+var AggregationBuilder = class AggregationBuilder {
+	pipeline = [];
+	_diskUse = false;
+	/**
+	* Get the current pipeline
+	*/
+	get() {
+		return [...this.pipeline];
+	}
+	/**
+	* Build and return the final pipeline
+	*/
+	build() {
+		return this.get();
+	}
+	/**
+	* Build pipeline with execution options (allowDiskUse, etc.)
+	*/
+	plan() {
+		return {
+			pipeline: this.get(),
+			allowDiskUse: this._diskUse
+		};
+	}
+	/**
+	* Build and execute the pipeline against a model
+	*
+	* @example
+	* ```typescript
+	* const results = await new AggregationBuilder()
+	*   .match({ status: 'active' })
+	*   .allowDiskUse()
+	*   .exec(MyModel);
+	* ```
+	*/
+	async exec(model, session) {
+		const agg = model.aggregate(this.build());
+		if (this._diskUse) agg.allowDiskUse(true);
+		if (session) agg.session(session);
+		return agg.exec();
+	}
+	/**
+	* Reset the pipeline
+	*/
+	reset() {
+		this.pipeline = [];
+		this._diskUse = false;
+		return this;
+	}
+	/**
+	* Add a raw pipeline stage
+	*/
+	addStage(stage) {
+		this.pipeline.push(stage);
+		return this;
+	}
+	/**
+	* Add multiple raw pipeline stages
+	*/
+	addStages(stages) {
+		this.pipeline.push(...stages);
+		return this;
+	}
+	/**
+	* $match - Filter documents
+	* IMPORTANT: Place $match as early as possible for performance
+	*/
+	match(query) {
+		this.pipeline.push({ $match: query });
+		return this;
+	}
+	/**
+	* $project - Include/exclude fields or compute new fields
+	*/
+	project(projection) {
+		this.pipeline.push({ $project: projection });
+		return this;
+	}
+	/**
+	* $group - Group documents and compute aggregations
+	*
+	* @example
+	* ```typescript
+	* .group({
+	*   _id: '$department',
+	*   count: { $sum: 1 },
+	*   avgSalary: { $avg: '$salary' }
+	* })
+	* ```
+	*/
+	group(groupSpec) {
+		this.pipeline.push({ $group: groupSpec });
+		return this;
+	}
+	/**
+	* $sort - Sort documents
+	*/
+	sort(sortSpec) {
+		if (typeof sortSpec === "string") {
+			const order = sortSpec.startsWith("-") ? -1 : 1;
+			const field = sortSpec.startsWith("-") ? sortSpec.substring(1) : sortSpec;
+			this.pipeline.push({ $sort: { [field]: order } });
+		} else this.pipeline.push({ $sort: normalizeSortSpec(sortSpec) });
+		return this;
+	}
+	/**
+	* $limit - Limit number of documents
+	*/
+	limit(count) {
+		this.pipeline.push({ $limit: count });
+		return this;
+	}
+	/**
+	* $skip - Skip documents
+	*/
+	skip(count) {
+		this.pipeline.push({ $skip: count });
+		return this;
+	}
+	/**
+	* $unwind - Deconstruct array field
+	*/
+	unwind(path, preserveNullAndEmptyArrays = false) {
+		this.pipeline.push({ $unwind: {
+			path: path.startsWith("$") ? path : `$${path}`,
+			preserveNullAndEmptyArrays
+		} });
+		return this;
+	}
+	/**
+	* $addFields - Add new fields or replace existing fields
+	*/
+	addFields(fields) {
+		this.pipeline.push({ $addFields: fields });
+		return this;
+	}
+	/**
+	* $set - Alias for $addFields
+	*/
+	set(fields) {
+		return this.addFields(fields);
+	}
+	/**
+	* $unset - Remove fields
+	*/
+	unset(fields) {
+		this.pipeline.push({ $unset: fields });
+		return this;
+	}
+	/**
+	* $replaceRoot - Replace the root document
+	*/
+	replaceRoot(newRoot) {
+		this.pipeline.push({ $replaceRoot: { newRoot: typeof newRoot === "string" ? `$${newRoot}` : newRoot } });
+		return this;
+	}
+	/**
+	* $lookup - Join with another collection (simple form)
+	*
+	* @param from - Collection to join with
+	* @param localField - Field from source collection
+	* @param foreignField - Field from target collection
+	* @param as - Output field name
+	* @param single - Unwrap array to single object
+	*
+	* @example
+	* ```typescript
+	* // Join employees with departments by slug
+	* .lookup('departments', 'deptSlug', 'slug', 'department', true)
+	* ```
+	*/
+	lookup(from, localField, foreignField, as, single) {
+		const stages = new LookupBuilder(from).localField(localField).foreignField(foreignField).as(as || from).single(single || false).build();
+		this.pipeline.push(...stages);
+		return this;
+	}
+	/**
+	* $lookup - Join with another collection (advanced form with pipeline)
+	*
+	* @example
+	* ```typescript
+	* .lookupWithPipeline({
+	*   from: 'products',
+	*   localField: 'productIds',
+	*   foreignField: 'sku',
+	*   as: 'products',
+	*   pipeline: [
+	*     { $match: { status: 'active' } },
+	*     { $project: { name: 1, price: 1 } }
+	*   ]
+	* })
+	* ```
+	*/
+	lookupWithPipeline(options) {
+		const builder = new LookupBuilder(options.from).localField(options.localField).foreignField(options.foreignField);
+		if (options.as) builder.as(options.as);
+		if (options.single) builder.single(options.single);
+		if (options.pipeline) builder.pipeline(options.pipeline);
+		if (options.let) builder.let(options.let);
+		this.pipeline.push(...builder.build());
+		return this;
+	}
+	/**
+	* Multiple lookups at once
+	*
+	* @example
+	* ```typescript
+	* .multiLookup([
+	*   { from: 'departments', localField: 'deptSlug', foreignField: 'slug', single: true },
+	*   { from: 'managers', localField: 'managerId', foreignField: '_id', single: true }
+	* ])
+	* ```
+	*/
+	multiLookup(lookups) {
+		const stages = LookupBuilder.multiple(lookups);
+		this.pipeline.push(...stages);
+		return this;
+	}
+	/**
+	* $facet - Process multiple aggregation pipelines in a single stage
+	* Useful for computing multiple aggregations in parallel
+	*
+	* @example
+	* ```typescript
+	* .facet({
+	*   totalCount: [{ $count: 'count' }],
+	*   avgPrice: [{ $group: { _id: null, avg: { $avg: '$price' } } }],
+	*   topProducts: [{ $sort: { sales: -1 } }, { $limit: 10 }]
+	* })
+	* ```
+	*/
+	facet(facets) {
+		this.pipeline.push({ $facet: facets });
+		return this;
+	}
+	/**
+	* $bucket - Categorize documents into buckets
+	*
+	* @example
+	* ```typescript
+	* .bucket({
+	*   groupBy: '$price',
+	*   boundaries: [0, 50, 100, 200],
+	*   default: 'Other',
+	*   output: {
+	*     count: { $sum: 1 },
+	*     products: { $push: '$name' }
+	*   }
+	* })
+	* ```
+	*/
+	bucket(options) {
+		this.pipeline.push({ $bucket: options });
+		return this;
+	}
+	/**
+	* $bucketAuto - Automatically determine bucket boundaries
+	*/
+	bucketAuto(options) {
+		this.pipeline.push({ $bucketAuto: options });
+		return this;
+	}
+	/**
+	* $setWindowFields - Perform window functions (MongoDB 5.0+)
+	* Useful for rankings, running totals, moving averages
+	*
+	* @example
+	* ```typescript
+	* .setWindowFields({
+	*   partitionBy: '$department',
+	*   sortBy: { salary: -1 },
+	*   output: {
+	*     rank: { $rank: {} },
+	*     runningTotal: { $sum: '$salary', window: { documents: ['unbounded', 'current'] } }
+	*   }
+	* })
+	* ```
+	*/
+	setWindowFields(options) {
+		const normalizedOptions = {
+			...options,
+			sortBy: options.sortBy ? normalizeSortSpec(options.sortBy) : void 0
+		};
+		this.pipeline.push({ $setWindowFields: normalizedOptions });
+		return this;
+	}
+	/**
+	* $unionWith - Combine results from multiple collections (MongoDB 4.4+)
+	*
+	* @example
+	* ```typescript
+	* .unionWith({
+	*   coll: 'archivedOrders',
+	*   pipeline: [{ $match: { year: 2024 } }]
+	* })
+	* ```
+	*/
+	unionWith(options) {
+		this.pipeline.push({ $unionWith: options });
+		return this;
+	}
+	/**
+	* $densify - Fill gaps in data (MongoDB 5.1+)
+	* Useful for time series data with missing points
+	*/
+	densify(options) {
+		this.pipeline.push({ $densify: options });
+		return this;
+	}
+	/**
+	* $fill - Fill null or missing field values (MongoDB 5.3+)
+	*/
+	fill(options) {
+		const normalizedOptions = {
+			...options,
+			sortBy: options.sortBy ? normalizeSortSpec(options.sortBy) : void 0
+		};
+		this.pipeline.push({ $fill: normalizedOptions });
+		return this;
+	}
+	/**
+	* Enable allowDiskUse for large aggregations that exceed 100MB memory limit
+	*
+	* @example
+	* ```typescript
+	* const results = await new AggregationBuilder()
+	*   .match({ status: 'active' })
+	*   .group({ _id: '$category', total: { $sum: '$amount' } })
+	*   .allowDiskUse()
+	*   .exec(Model);
+	* ```
+	*/
+	allowDiskUse(enable = true) {
+		this._diskUse = enable;
+		return this;
+	}
+	/**
+	* Paginate - Add skip and limit for offset-based pagination
+	*/
+	paginate(page, limit) {
+		const skip = (page - 1) * limit;
+		return this.skip(skip).limit(limit);
+	}
+	/**
+	* Count total documents (useful with $facet for pagination metadata)
+	*/
+	count(outputField = "count") {
+		this.pipeline.push({ $count: outputField });
+		return this;
+	}
+	/**
+	* Sample - Randomly select N documents
+	*/
+	sample(size) {
+		this.pipeline.push({ $sample: { size } });
+		return this;
+	}
+	/**
+	* Out - Write results to a collection
+	*/
+	out(collection) {
+		this.pipeline.push({ $out: collection });
+		return this;
+	}
+	/**
+	* Merge - Merge results into a collection
+	*/
+	merge(options) {
+		this.pipeline.push({ $merge: typeof options === "string" ? { into: options } : options });
+		return this;
+	}
+	/**
+	* GeoNear - Perform geospatial queries
+	*/
+	geoNear(options) {
+		this.pipeline.push({ $geoNear: options });
+		return this;
+	}
+	/**
+	* GraphLookup - Perform recursive search (graph traversal)
+	*/
+	graphLookup(options) {
+		this.pipeline.push({ $graphLookup: options });
+		return this;
+	}
+	/**
+	* $search - Atlas Search full-text search (Atlas only)
+	*
+	* @example
+	* ```typescript
+	* .search({
+	*   index: 'default',
+	*   text: {
+	*     query: 'laptop computer',
+	*     path: ['title', 'description'],
+	*     fuzzy: { maxEdits: 2 }
+	*   }
+	* })
+	* ```
+	*/
+	search(options) {
+		this.pipeline.push({ $search: options });
+		return this;
+	}
+	/**
+	* $searchMeta - Get Atlas Search metadata (Atlas only)
+	*/
+	searchMeta(options) {
+		this.pipeline.push({ $searchMeta: options });
+		return this;
+	}
+	/**
+	* $vectorSearch - Semantic similarity search using vector embeddings (Atlas only)
+	*
+	* Requires an Atlas Vector Search index on the target field.
+	* Must be the first stage in the pipeline.
+	*
+	* @example
+	* ```typescript
+	* const results = await new AggregationBuilder()
+	*   .vectorSearch({
+	*     index: 'vector_index',
+	*     path: 'embedding',
+	*     queryVector: await getEmbedding('running shoes'),
+	*     limit: 10,
+	*     numCandidates: 100,
+	*     filter: { category: 'footwear' }
+	*   })
+	*   .project({ embedding: 0, score: { $meta: 'vectorSearchScore' } })
+	*   .exec(ProductModel);
+	* ```
+	*/
+	vectorSearch(options) {
+		if (this.pipeline.length > 0) throw new Error("[mongokit] $vectorSearch must be the first stage in the pipeline");
+		const rawCandidates = options.numCandidates ?? Math.max(options.limit * 10, 100);
+		const numCandidates = Math.min(Math.max(rawCandidates, options.limit), 1e4);
+		this.pipeline.push({ $vectorSearch: {
+			index: options.index,
+			path: options.path,
+			queryVector: options.queryVector,
+			numCandidates,
+			limit: options.limit,
+			...options.filter && { filter: options.filter },
+			...options.exact && { exact: options.exact }
+		} });
+		return this;
+	}
+	/**
+	* Add vectorSearchScore as a field after $vectorSearch
+	* Convenience for `.addFields({ score: { $meta: 'vectorSearchScore' } })`
+	*/
+	withVectorScore(fieldName = "score") {
+		return this.addFields({ [fieldName]: { $meta: "vectorSearchScore" } });
+	}
+	/**
+	* Create a builder from an existing pipeline
+	*/
+	static from(pipeline) {
+		const builder = new AggregationBuilder();
+		builder.pipeline = [...pipeline];
+		return builder;
+	}
+	/**
+	* Create a builder with initial match stage
+	*/
+	static startWith(query) {
+		return new AggregationBuilder().match(query);
+	}
+};
+/**
+* Optimized Aggregation Patterns for Scale
+*
+* 1. **Early Filtering** - Always place $match as early as possible:
+*    ```typescript
+*    new AggregationBuilder()
+*      .match({ status: 'active' })  // ✅ Filter first
+*      .lookup(...)                  // Then join
+*      .sort(...)
+*    ```
+*
+* 2. **Index Usage** - Ensure indexes on:
+*    - Fields in $match
+*    - Fields in $sort (especially with $limit)
+*    - Fields in $lookup (both local and foreign)
+*
+* 3. **Projection** - Remove unnecessary fields early:
+*    ```typescript
+*    .project({ password: 0, internalNotes: 0 })  // Remove before joins
+*    .lookup(...)
+*    ```
+*
+* 4. **Faceted Pagination** - Get count and data in one query:
+*    ```typescript
+*    .facet({
+*      metadata: [{ $count: 'total' }],
+*      data: [{ $skip: skip }, { $limit: limit }]
+*    })
+*    ```
+*
+* 5. **allowDiskUse** - For large datasets:
+*    ```typescript
+*    new AggregationBuilder()
+*      .match({ status: 'active' })
+*      .allowDiskUse()
+*      .exec(Model)
+*    ```
+*
+* 6. **Vector Search** - Semantic similarity (Atlas only):
+*    ```typescript
+*    new AggregationBuilder()
+*      .vectorSearch({ index: 'vec_idx', path: 'embedding', queryVector: vec, limit: 10 })
+*      .withVectorScore()
+*      .exec(Model)
+*    ```
+*/
+//#endregion
+//#region src/tx-bound.ts
+/**
+* Map of session-aware method name → positional index of the `{ session }`
+* options bag. Keep this list in sync with the method signatures in
+* `Repository.ts` and the plugin method definitions. Unknown plugin
+* methods pass through unwrapped (callers use the standalone helper).
+*/
+const SESSION_OPTIONS_INDEX = Object.freeze({
+	create: 1,
+	update: 2,
+	delete: 1,
+	getById: 1,
+	getAll: 1,
+	createMany: 1,
+	findAll: 1,
+	getOrCreate: 2,
+	count: 1,
+	exists: 1,
+	getByQuery: 1,
+	getOne: 1,
+	findOneAndUpdate: 2,
+	distinct: 2,
+	aggregate: 1,
+	aggregatePaginate: 0,
+	lookupPopulate: 0,
+	upsert: 2,
+	increment: 3,
+	decrement: 3,
+	multiplyField: 3,
+	setMin: 3,
+	setMax: 3,
+	pushToArray: 3,
+	pullFromArray: 3,
+	addToSet: 3,
+	setField: 3,
+	unsetField: 2,
+	renameField: 3,
+	atomicUpdate: 2,
+	updateMany: 2,
+	deleteMany: 1,
+	bulkWrite: 1,
+	restore: 1,
+	getDeleted: 1,
+	addSubdocument: 3,
+	getSubdocument: 3,
+	updateSubdocument: 4,
+	deleteSubdocument: 3,
+	groupBy: 1,
+	sum: 2,
+	average: 2,
+	min: 2,
+	max: 2
+});
+/**
+* Build a session-threaded proxy over `outer`. The returned object has the
+* same method signatures, but every CRUD call auto-injects the supplied
+* session into the options bag. Non-CRUD properties (Model, modelName,
+* hook API, utility helpers) pass through.
+*/
+function createTxBoundRepo(outer, session) {
+	return new Proxy(outer, { get(target, prop, receiver) {
+		if (prop === "withTransaction") return () => {
+			throw new Error("[mongokit] Nested withTransaction is not supported on a tx-bound repository. Reuse the outer `txRepo` directly, or collapse the nesting.");
+		};
+		const value = Reflect.get(target, prop, receiver);
+		if (typeof value !== "function") return value;
+		if (prop === "Model") return value;
+		if (typeof prop === "symbol") return value.bind(target);
+		if (prop.startsWith("_")) return value.bind(target);
+		const optionsIndex = SESSION_OPTIONS_INDEX[prop];
+		if (optionsIndex === void 0) return value.bind(target);
+		return function txBoundMethod(...args) {
+			while (args.length <= optionsIndex) args.push(void 0);
+			const current = args[optionsIndex];
+			if (current === void 0) args[optionsIndex] = { session };
+			else if (typeof current === "object" && current !== null && !Array.isArray(current)) args[optionsIndex] = {
+				...current,
+				session
+			};
+			else return value.apply(target, args);
+			return value.apply(target, args);
+		};
+	} });
+}
+//#endregion
+//#region src/transaction.ts
+/**
+* Run a callback inside a MongoDB transaction on the given connection.
+*
+* - Starts a session, runs `session.withTransaction(callback)` (which auto-retries
+*   on `TransientTransactionError` and `UnknownTransactionCommitResult`), and
+*   always ends the session in `finally`.
+* - When `allowFallback` is true and the deployment doesn't support transactions
+*   (e.g. standalone MongoDB in dev), the callback runs once without a
+*   transaction on the same session. `onFallback` is invoked with the original
+*   error so hosts can log the degradation.
+*
+* @example
+* ```ts
+* import mongoose from 'mongoose';
+* import { withTransaction } from '@classytic/mongokit';
+*
+* await withTransaction(mongoose.connection, async (session) => {
+*   const order  = await orderRepo.create(data, { session });
+*   await inventoryRepo.decrement(order.items, { session });
+*   return order;
+* });
+* ```
+*/
+async function withTransaction(connection, callback, options = {}) {
+	const session = await connection.startSession();
+	try {
+		return await session.withTransaction(() => callback(session), options.transactionOptions);
+	} catch (error) {
+		const err = error;
+		if (options.allowFallback && isTransactionUnsupported(err)) {
+			options.onFallback?.(err);
+			return await callback(session);
+		}
+		throw err;
+	} finally {
+		await session.endSession();
+	}
+}
+/**
+* Multi-repo transactional batch — every repo in `repos` becomes a
+* session-bound proxy inside the callback. Eliminates the per-call
+* `{ session }` threading that was repeated across ~20 call sites
+* (be-prod outbox writes, order placement, transfer source/dest pairs,
+* payrun saga steps).
+*
+* Same retry + fallback semantics as `withTransaction`: the
+* `transactionOptions` / `allowFallback` / `onFallback` knobs apply.
+*
+* Each property of the input `repos` map is rebound via the
+* `createTxBoundRepo` proxy — every CRUD method on the bound repo
+* auto-injects `session` into its options bag, including
+* `claim` / `claimVersion` / `findOneAndUpdate` and plugin-contributed
+* methods. Non-CRUD properties (Model, modelName, hook engine,
+* idField) pass through to the underlying repo. Nested
+* `boundRepo.withTransaction(...)` throws — reuse the outer bound
+* repos.
+*
+* @example Order placement across three repos in one transaction
+* ```ts
+* import { batchTransaction } from '@classytic/mongokit';
+*
+* const order = await batchTransaction(
+*   mongoose.connection,
+*   { orders: orderRepo, events: eventRepo, inventory: inventoryRepo },
+*   async ({ orders, events, inventory }) => {
+*     const created = await orders.create(orderData);          // session auto-injected
+*     await events.create({ type: 'order.placed', orderId: created._id });
+*     await inventory.claim(skuId, { from: 'available', to: 'reserved' });
+*     return created;
+*   },
+* );
+* ```
+*
+* @example With fallback for standalone-mongo dev environments
+* ```ts
+* await batchTransaction(
+*   mongoose.connection,
+*   { orders, events },
+*   async ({ orders, events }) => { ... },
+*   { allowFallback: true, onFallback: (err) => log.warn(err) },
+* );
+* ```
+*
+* @param connection - Mongoose connection (or anything with
+*   `startSession()`). Single source of session truth — every bound
+*   repo shares this session.
+* @param repos - Map of repo instances to rebind. Keys become the
+*   property names on the callback's argument.
+* @param callback - Receives the bound repo map. Return value flows
+*   through to the outer `Promise`.
+*/
+async function batchTransaction(connection, repos, callback, options = {}) {
+	return withTransaction(connection, async (session) => {
+		const bound = {};
+		for (const key of Object.keys(repos)) {
+			const repo = repos[key];
+			bound[key] = createTxBoundRepo(repo, session);
+		}
+		return callback(bound);
+	}, options);
+}
+/**
+* Detect whether an error indicates the MongoDB deployment does not support
+* multi-document transactions (standalone server, older topology, etc.).
+*
+* Checks MongoDB error codes first — 263 (standalone) and 20 (unsupported
+* topology) — with a message-matching fallback for edge cases surfaced by
+* driver versions that throw before the proper code lands.
+*
+* **Driver-version drift:** modern mongoose / mongodb-driver versions hit
+* the standalone case via the retryable-writes precondition rather than
+* the transaction precondition (`retryWrites=true` is on by default,
+* standalone Mongo rejects it before the transaction is even attempted).
+* So we accept that message as equivalent — the underlying topology
+* problem is the same, and the fallback semantics are correct either way.
+*/
+function isTransactionUnsupported(error) {
+	const code = error.code;
+	if (code === 263 || code === 20) return true;
+	const message = (error.message || "").toLowerCase();
+	return message.includes("transaction numbers are only allowed on a replica set member") || message.includes("transaction is not supported") || message.includes("does not support retryable writes");
+}
+//#endregion
+//#region src/Repository.ts
+function ensureLookupProjectionIncludesCursorFields(projection, sort) {
+	if (!projection || !sort) return projection;
+	if (!Object.values(projection).some((value) => value === 1)) return projection;
+	const nextProjection = { ...projection };
+	for (const field of [...Object.keys(sort), "_id"]) nextProjection[field] = 1;
+	return nextProjection;
+}
+/**
+* Validates that an update patch is homogeneous — either all top-level
+* keys are `$`-prefixed Mongo operators OR none are. Mixed shapes (e.g.
+* `{ $set: {...}, status: 'x' }`) cause Mongo to **silently drop** the
+* flat keys, which is the kind of write-loss bug we won't ship.
+*
+* Hoisted into a named helper so the error stack trace points directly
+* at this function — debugging a "patch mixes operators" failure is now
+* trivial without needing to read the call site.
+*
+* @throws TypeError-style HttpError(400) when the patch is mixed.
+*/
+function assertNoMixedPatchShape(opName, patch) {
+	const patchKeys = Object.keys(patch);
+	const operatorKeys = patchKeys.filter((k) => k.startsWith("$"));
+	if (operatorKeys.length === 0 || operatorKeys.length === patchKeys.length) return;
+	const flatKeys = patchKeys.filter((k) => !k.startsWith("$"));
+	throw createError(400, `[${opName}] assertNoMixedPatchShape: patch mixes Mongo operators (${operatorKeys.join(", ")}) with raw field keys (${flatKeys.join(", ")}). Mongo would silently DROP the flat keys — that's a write-loss bug we refuse to forward. Either wrap the flat keys in $set explicitly, or remove the operator keys.`);
+}
+/**
+* Plugin phase priorities (lower = runs first).
+*
+* Re-exported from `@classytic/repo-core/hooks` so mongokit 3.10 callers see
+* the same constant whether they import from mongokit or directly from
+* repo-core — priorities are identical (POLICY=100, CACHE=200,
+* OBSERVABILITY=300, DEFAULT=500) and the two refs are reference-equal.
+*/
+const HOOK_PRIORITY$1 = HOOK_PRIORITY;
+/**
+* Production-grade repository for MongoDB.
+*
+* Extends `@classytic/repo-core/repository`'s `RepositoryBase` for the
+* driver-agnostic hook + plugin plumbing (context builder, priority-sorted
+* event engine, plugin-order validator) while layering every Mongo-specific
+* concern — populate, aggregate, lookup, keyset + cursor pagination, $near
+* rewriting — on top.
+*
+* Public surface is byte-stable with mongokit 3.9 (the `_hooks` property is
+* preserved as a live read-through getter; all CRUD, event, and plugin method
+* signatures unchanged). 3.10 is an internal re-plumbing release; consumers
+* upgrading from 3.9 need no code changes.
+*/
+var Repository = class extends RepositoryBase {
+	Model;
+	/**
+	* Mongoose model name. Duplicated on the instance for BC — arc / catalog /
+	* user code read `repo.model`. `RepositoryBase.modelName` points to the
+	* same string; prefer `modelName` in new code.
+	*/
+	model;
+	_pagination;
+	idField;
+	searchMode;
+	searchFields;
+	_hasTextIndex = null;
+	/**
+	* Wrap-style middleware chain. Composed around every `_runOp`
+	* invocation in registration order — earlier-registered middlewares
+	* are outer (run first / unwind last). See `useMiddleware()` and
+	* the `Middleware<TDoc>` type for the protocol.
+	*/
+	_middlewares = [];
+	constructor(Model, plugins = [], paginationConfig = {}, options = {}) {
+		super({
+			name: Model.modelName,
+			hooks: options.hooks ?? "async",
+			pluginOrderChecks: "off"
+		});
+		validatePluginOrder(plugins, Model.modelName, options.pluginOrderChecks ?? "warn", (m) => {
+			warn(m);
+		});
+		this.Model = Model;
+		this.model = Model.modelName;
+		this._pagination = new PaginationEngine(Model, paginationConfig);
+		this.idField = options.idField ?? "_id";
+		this.searchMode = options.searchMode ?? "text";
+		this.searchFields = options.searchFields;
+		this._wireStrictQueryStripDiagnostic(options.warnOnStrictQueryStrip === true);
+		if (this.searchMode === "regex" && (!this.searchFields || this.searchFields.length === 0)) warn(`[mongokit] Repository "${this.model}" configured with searchMode: 'regex' but no searchFields provided. getAll({ search }) will throw until searchFields is set.`);
+		for (const plugin of plugins) this.use(plugin);
+		if (options.requirePlugins && options.requirePlugins.length > 0) {
+			const installedNames = new Set(plugins.map((p) => p?.name).filter(Boolean));
+			const missing = options.requirePlugins.filter((name) => !installedNames.has(name));
+			if (missing.length > 0) throw new TypeError(`[mongokit] Repository "${Model.modelName}" requires plugin(s) that are not installed: ${missing.join(", ")}. Add the missing plugin(s) to the constructor's \`plugins\` array, or remove the name from \`options.requirePlugins\`. Installed plugins: ${[...installedNames].join(", ") || "(none)"}.`);
+		}
+	}
+	/**
+	* Live read-through view of the hook engine's listener registry.
+	*
+	* Preserved as a public field on the Repository for back-compat with
+	* mongokit ≤3.9 — existing tests and observability code pattern-match
+	* `repo._hooks.get('before:getAll')` / `repo._hooks.size`. Each access
+	* returns a fresh snapshot of the underlying HookEngine state.
+	*
+	* Read-only. To register listeners use `repo.on(event, listener, { priority })`.
+	*/
+	get _hooks() {
+		return this.hooks.listeners();
+	}
+	/**
+	* Fire-and-forget emit aliased through RepositoryBase's async path so
+	* error hooks converted to/from sync mode still route uniformly. Mongokit
+	* ≤3.9 made this a private method on its subclass; the base class exposes
+	* it publicly and wraps it in `_emitHook` below for internal use.
+	*/
+	async _emitHook(event, data) {
+		await this.hooks.emitAccordingToMode(event, data);
+	}
+	async _emitErrorHook(event, data) {
+		try {
+			await this._emitHook(event, data);
+		} catch (hookError) {
+			warn(`[${this.model}] Error hook '${event}' threw: ${hookError instanceof Error ? hookError.message : String(hookError)}`);
+		}
+	}
+	/**
+	* Wire the `warnOnStrictQueryStrip` diagnostic. When enabled, every
+	* filter-shaped op (`getById`, `getByQuery`, `getOne`, `findAll`,
+	* `count`, `exists`, `update`, `delete`, `findOneAndUpdate`,
+	* `updateMany`, `deleteMany`, `claim`, `claimVersion`, `cursor`)
+	* checks its `context.query` keys against the cached set of schema
+	* paths. Top-level keys not on the schema get logged once per
+	* `(model, key)` pair — so a single bad caller surfaces in dev /
+	* staging instead of returning the wrong row in prod.
+	*
+	* Only runs when `strictQuery !== false` is in effect — if mongoose's
+	* strictQuery is off, unknown keys flow through to the driver and
+	* the trap doesn't apply.
+	*/
+	_wireStrictQueryStripDiagnostic(enabled) {
+		if (!enabled) return;
+		const schema = this.Model.schema;
+		const declaredPaths = new Set(["_id"]);
+		for (const path of Object.keys(schema.paths)) {
+			declaredPaths.add(path);
+			const segments = path.split(".");
+			for (let i = 1; i < segments.length; i++) declaredPaths.add(segments.slice(0, i).join("."));
+		}
+		const warned = /* @__PURE__ */ new Set();
+		const modelName = this.model;
+		const checkFilter = (filter) => {
+			if ((schema.options.strictQuery ?? mongoose.get?.("strictQuery")) === false) return;
+			if (!filter || typeof filter !== "object") return;
+			for (const key of Object.keys(filter)) {
+				if (key.startsWith("$")) continue;
+				const head = key.split(".")[0];
+				if (declaredPaths.has(head) || declaredPaths.has(key)) continue;
+				const dedupeKey = `${modelName}.${key}`;
+				if (warned.has(dedupeKey)) continue;
+				warned.add(dedupeKey);
+				warn(`[mongokit] '${modelName}.${key}' filter key not on schema — strictQuery will silently strip it. Add the field to the schema, or use 'strict: false' / 'strictQuery: false' if you intend dynamic keys.`);
+			}
+		};
+		const observabilityPriority = { priority: 300 };
+		for (const op of operationsByPolicyKey("query")) this.on(`before:${op}`, (context) => {
+			checkFilter(context.query);
+		}, observabilityPriority);
+		for (const op of operationsByPolicyKey("filters")) this.on(`before:${op}`, (context) => {
+			checkFilter(context.filters);
+		}, observabilityPriority);
+	}
+	/**
+	* Register a wrap-style middleware. Middleware composes AROUND every
+	* `_runOp` invocation — it sees the operation name, the live
+	* `RepositoryContext`, and a `next()` continuation that runs the
+	* remaining chain + the actual op + after/error hooks.
+	*
+	* **Composes with `repo.on()` and plugins, doesn't replace them.**
+	* Middleware is for ergonomics (timing, short-circuit, input/output
+	* mutation in a single closure) — NOT for security policy. Use the
+	* `before:*` hook engine for tenant scope, soft-delete filtering,
+	* cache invalidation, and audit; those plugins MUST run before
+	* middleware sees the op.
+	*
+	* **Execution order on every call** (build/before hooks fire BEFORE
+	* the middleware chain dispatches, so middleware cannot wrap a
+	* before-hook failure):
+	*
+	* ```text
+	*   _buildContext + before:<op>   ← repo.on('before:*') hooks
+	*     [outer middleware pre]      ← repo.useMiddleware() registrations
+	*       [...inner middleware pre]
+	*         fn (driver call)
+	*         after:<op> | error:<op> ← repo.on('after:*' / 'error:*')
+	*       [...inner middleware post]
+	*     [outer middleware post]
+	* ```
+	*
+	* Why this order matters: a `before:create` hook that injects a
+	* tenant filter into `context.query` runs BEFORE the middleware chain
+	* is composed. Middleware sees a context that was already scoped by
+	* the policy plugins — it never has the authority to short-circuit a
+	* tenant check, because the throw from a `before:*` policy hook
+	* unwinds before middleware ever fires. That's by design — middleware
+	* as a security boundary would be impossible to audit, since
+	* registration order would determine whether scope wins.
+	*
+	* Practical consequence: if you want middleware to observe a policy
+	* failure (e.g. metric a tenant-scope rejection), use `repo.on('error:
+	* <op>', ...)` instead — that fires from inside the middleware chain
+	* and is reachable.
+	*
+	* Registration order = composition order: the first middleware
+	* registered runs outermost (wraps everything else).
+	*
+	* @example Time every op
+	* ```ts
+	* repo.useMiddleware(async ({ operation, next }) => {
+	*   const start = performance.now();
+	*   try { return await next(); }
+	*   finally { metrics.record(operation, performance.now() - start); }
+	* });
+	* ```
+	*
+	* @example Inject `tenantId` on every create
+	* ```ts
+	* repo.useMiddleware(async ({ operation, context, next }) => {
+	*   if (operation === 'create' && context.data) {
+	*     context.data.tenantId = currentTenant();
+	*   }
+	*   return next();
+	* });
+	* ```
+	*
+	* @example Short-circuit (return without `next()` to skip the actual op)
+	* ```ts
+	* repo.useMiddleware(async ({ operation, context, next }) => {
+	*   if (operation === 'getById' && readOnlyMaintenance) {
+	*     return cachedReadOnlyResponse(context.id);
+	*   }
+	*   return next();
+	* });
+	* ```
+	*/
+	useMiddleware(middleware) {
+		this._middlewares.push(middleware);
+		return this;
+	}
+	/**
+	* Compose the registered middleware chain around `exec`. Outermost
+	* middleware (first registered) wraps innermost. Each middleware sees
+	* the live `RepositoryContext` (already populated + run through
+	* `before:*` hooks at the call site — see `useMiddleware` JSDoc for
+	* the exact order). `after:` / `error:` hooks fire from inside
+	* `exec`, so middleware composes WITH plugins, not instead of them.
+	*
+	* `_runOp` calls this with its standard try/catch envelope; inline-try
+	* methods (`getById`, `update`, `delete`, `deleteMany`, `aggregatePaginate`,
+	* `lookupPopulate`, plus `getOne`/`getAll` cache-hit branches) call it
+	* directly so middleware sees every op — including cached reads — not
+	* just the ones routed through `_runOp`.
+	*/
+	_composeMiddleware(op, context, exec) {
+		if (this._middlewares.length === 0) return exec();
+		let chain = exec;
+		for (let i = this._middlewares.length - 1; i >= 0; i--) {
+			const mw = this._middlewares[i];
+			const next = chain;
+			chain = async () => await mw({
+				operation: op,
+				context,
+				repo: this,
+				next
+			});
+		}
+		return chain();
+	}
+	/**
+	* Standard operation envelope: compose middleware around an exec that
+	* runs `fn`, emits `after:<op>` on success or `error:<op>` on failure.
+	* Methods with branched in-try logic that emit `after:*` from multiple
+	* paths (`getById`, `update`, `delete`, `deleteMany`, `aggregatePaginate`,
+	* `lookupPopulate`) keep their inline try/catch and call
+	* `_composeMiddleware` directly instead of being forced through this
+	* single-result helper.
+	*/
+	async _runOp(op, context, fn) {
+		return this._composeMiddleware(op, context, async () => {
+			try {
+				const result = await fn();
+				await this._emitHook(`after:${op}`, {
+					context,
+					result
+				});
+				return result;
+			} catch (error) {
+				await this._emitErrorHook(`error:${op}`, {
+					context,
+					error
+				});
+				throw this._handleError(error);
+			}
+		});
+	}
+	/**
+	* Create single document
+	*/
+	async create(data, options = {}) {
+		const context = await this._buildContext("create", {
+			data,
+			...options
+		});
+		return this._runOp("create", context, () => create(this.Model, context.data || data, options));
+	}
+	/**
+	* Create multiple documents
+	*/
+	async createMany(dataArray, options = {}) {
+		const context = await this._buildContext("createMany", {
+			dataArray,
+			...options
+		});
+		return this._runOp("createMany", context, () => createMany(this.Model, context.dataArray || dataArray, options));
+	}
+	/**
+	* Get document by ID
+	*/
+	async getById(id, options = {}) {
+		const populateSpec = options.populateOptions || options.populate;
+		const context = await this._buildContext("getById", {
+			id,
+			...options,
+			populate: populateSpec
+		});
+		return this._composeMiddleware("getById", context, async () => {
+			if (context._cacheHit) {
+				const cachedResult = context._cachedResult;
+				await this._emitHook("after:getById", {
+					context,
+					result: cachedResult,
+					fromCache: true
+				});
+				return cachedResult;
+			}
+			try {
+				const effectiveIdField = options.idField ?? this.idField;
+				if (effectiveIdField !== "_id") {
+					const result = await getByQuery(this.Model, {
+						[effectiveIdField]: id,
+						...context.query || {}
+					}, context);
+					await this._emitHook("after:getById", {
+						context,
+						result
+					});
+					return result;
+				}
+				const wantsThrow = context.throwOnNotFound === true || options.throwOnNotFound === true;
+				if (!isValidIdForType(id, getSchemaIdType(this.Model.schema))) {
+					if (wantsThrow) throw createError(404, "Document not found");
+					return null;
+				}
+				const result = await getById(this.Model, id, context);
+				if (!result && wantsThrow) throw createError(404, "Document not found");
+				await this._emitHook("after:getById", {
+					context,
+					result
+				});
+				return result;
+			} catch (error) {
+				await this._emitErrorHook("error:getById", {
+					context,
+					error
+				});
+				throw this._handleError(error);
+			}
+		});
+	}
+	/**
+	* Get single document by query
+	*/
+	async getByQuery(query, options = {}) {
+		const populateSpec = options.populateOptions || options.populate;
+		const context = await this._buildContext("getByQuery", {
+			query,
+			...options,
+			populate: populateSpec
+		});
+		if (context._cacheHit) {
+			const cachedResult = context._cachedResult;
+			await this._emitHook("after:getByQuery", {
+				context,
+				result: cachedResult,
+				fromCache: true
+			});
+			return cachedResult;
+		}
+		const finalQuery = context.query || query;
+		return this._runOp("getByQuery", context, () => getByQuery(this.Model, finalQuery, context));
+	}
+	/**
+	* Get single document by arbitrary filter.
+	* Unlike getByQuery, this method is designed for Arc/controller use where
+	* compound filters (org scope + policy + id) are pre-built.
+	*
+	* @example
+	* const product = await repo.getOne({ slug: 'laptop', organizationId: 'org_1' });
+	*/
+	async getOne(query, options = {}) {
+		const populateSpec = options.populateOptions || options.populate;
+		const context = await this._buildContext("getOne", {
+			query,
+			...options,
+			populate: populateSpec
+		});
+		return this._composeMiddleware("getOne", context, async () => {
+			if (context._cacheHit) {
+				const cachedResult = context._cachedResult;
+				await this._emitHook("after:getOne", {
+					context,
+					result: cachedResult,
+					fromCache: true
+				});
+				return cachedResult;
+			}
+			const finalQuery = context.query || query;
+			try {
+				const result = await getByQuery(this.Model, finalQuery, context);
+				await this._emitHook("after:getOne", {
+					context,
+					result
+				});
+				return result;
+			} catch (error) {
+				await this._emitErrorHook("error:getOne", {
+					context,
+					error
+				});
+				throw this._handleError(error);
+			}
+		});
+	}
+	/**
+	* Fetch ALL documents matching filters without pagination.
+	* Use for background jobs, exports, batch processing where you need every doc.
+	*
+	* @example
+	* const all = await repo.findAll({ status: 'active' });
+	* const allLean = await repo.findAll({}, { select: 'name email', lean: true });
+	*/
+	async findAll(filters = {}, options = {}) {
+		const context = await this._buildContext("findAll", {
+			query: filters,
+			...options
+		});
+		const resolvedFilters = context.query ?? filters;
+		return this._runOp("findAll", context, async () => {
+			const query = this.Model.find(resolvedFilters);
+			const sortSpec = context.sort || options.sort;
+			if (sortSpec) query.sort(this._parseSort(sortSpec));
+			const selectSpec = context.select || options.select;
+			if (selectSpec) query.select(selectSpec);
+			if (options.populate || context.populate) query.populate(this._parsePopulate(context.populate || options.populate));
+			if (context.lean ?? options.lean ?? true) query.lean();
+			if (options.session) query.session(options.session);
+			if (options.readPreference) query.read(options.readPreference);
+			return await query.exec();
+		});
+	}
+	/**
+	* Streaming reads — async iterator over data, suitable for migrations,
+	* backfills, schema audits, and any once-a-quarter "touch every row"
+	* job. Goes through the standard `before:cursor` hook pipeline so
+	* multi-tenant scope, soft-delete filter, and access-control plugins
+	* inject scope BEFORE the underlying mongoose cursor is built.
+	*
+	* Replaces direct `Model.find().cursor()` usage which bypasses every
+	* plugin — that's how cross-tenant data ends up in migrations.
+	*
+	* Returns an `AsyncIterableIterator<TDoc>` — drive it with `for await`.
+	* The mongoose cursor is closed when iteration completes or breaks.
+	*
+	* @example Backfill a missing field across the whole tenant scope
+	* ```ts
+	* for await (const doc of repo.cursor({ filter: { migrated: { $ne: true }}}, { batchSize: 1000 })) {
+	*   await transformer(doc);
+	*   await repo.update(doc._id, { migrated: true });
+	* }
+	* ```
+	*
+	* @example Audit unscoped — opt out of multi-tenant for global sweeps
+	* ```ts
+	* for await (const doc of repo.cursor({}, { batchSize: 500, organizationId: undefined })) {
+	*   audit(doc);
+	* }
+	* ```
+	*/
+	async *cursor(filter = {}, options = {}) {
+		const context = await this._buildContext("cursor", {
+			query: filter,
+			...options
+		});
+		const resolvedFilter = context.query ?? filter;
+		const query = this.Model.find(resolvedFilter);
+		const sortSpec = context.sort || options.sort;
+		if (sortSpec) query.sort(this._parseSort(sortSpec));
+		if (options.select) query.select(options.select);
+		if (options.batchSize) query.batchSize(options.batchSize);
+		if (context.lean ?? options.lean ?? true) query.lean();
+		if (options.session) query.session(options.session);
+		if (options.readPreference) query.read(options.readPreference);
+		const stream = query.cursor();
+		let yieldedCount = 0;
+		try {
+			for await (const doc of stream) {
+				yieldedCount++;
+				yield doc;
+			}
+			await this._emitHook("after:cursor", {
+				context,
+				result: { count: yieldedCount }
+			});
+		} catch (error) {
+			await this._emitErrorHook("error:cursor", {
+				context,
+				error
+			});
+			throw this._handleError(error);
+		} finally {
+			if (typeof stream.close === "function") await stream.close().catch(() => {});
+		}
+	}
+	/**
+	* Unified pagination - auto-detects offset vs keyset based on params
+	*
+	* Auto-detection logic:
+	* - If params has 'cursor' or 'after' → uses keyset pagination (stream)
+	* - If params has 'pagination' or 'page' → uses offset pagination (paginate)
+	* - Else → defaults to offset pagination with page=1
+	*
+	* @example
+	* // Offset pagination (page-based)
+	* await repo.getAll({ page: 1, limit: 50, filters: { status: 'active' } });
+	* await repo.getAll({ pagination: { page: 2, limit: 20 } });
+	*
+	* // Keyset pagination (cursor-based)
+	* await repo.getAll({ cursor: 'eyJ2Ij...', limit: 50 });
+	* await repo.getAll({ after: 'eyJ2Ij...', sort: { createdAt: -1 } });
+	*
+	* // Simple query (defaults to page 1)
+	* await repo.getAll({ filters: { status: 'active' } });
+	*
+	* // Skip cache for fresh data
+	* await repo.getAll({ filters: { status: 'active' } }, { skipCache: true });
+	*/
+	async getAll(params = {}, options = {}) {
+		const normalizedParams = {
+			...params,
+			page: params.page ?? params.pagination?.page,
+			limit: params.limit ?? params.pagination?.limit
+		};
+		const context = await this._buildContext("getAll", {
+			...normalizedParams,
+			...options
+		});
+		if (context._cacheHit) return this._composeMiddleware("getAll", context, async () => {
+			const cachedResult = context._cachedResult;
+			await this._emitHook("after:getAll", {
+				context,
+				result: cachedResult,
+				fromCache: true
+			});
+			return cachedResult;
+		});
+		if (params.noPagination) return this.findAll(context.filters ?? params.filters ?? {}, {
+			...options,
+			sort: context.sort ?? params.sort
+		});
+		const filters = context.filters ?? params.filters ?? {};
+		const search = context.search;
+		const isNearQuery = hasNearOperator(filters);
+		const sort = this._resolveSort(context, params, isNearQuery);
+		const limit = context.limit ?? params.limit ?? params.pagination?.limit ?? this._pagination.config.defaultLimit;
+		const page = context.page ?? params.pagination?.page ?? params.page;
+		const after = context.after ?? params.cursor ?? params.after;
+		const mode = context.mode ?? params.mode;
+		const useKeyset = this._detectPaginationMode(mode, page, after, sort, context, params);
+		const query = this._buildSearchQuery(filters, search);
+		const populateSpec = options.populateOptions || params.populateOptions || context.populate || options.populate;
+		const paginationOptions = {
+			filters: query,
+			sort: isNearQuery ? void 0 : this._parseSort(sort),
+			limit,
+			populate: this._parsePopulate(populateSpec),
+			select: context.select || options.select,
+			lean: context.lean ?? options.lean ?? true,
+			session: options.session,
+			hint: context.hint ?? params.hint,
+			maxTimeMS: context.maxTimeMS ?? params.maxTimeMS,
+			readPreference: context.readPreference ?? options.readPreference ?? params.readPreference,
+			collation: context.collation ?? params.collation
+		};
+		const lookups = context.lookups ?? params.lookups;
+		if (lookups && lookups.length > 0) return this._runOp("getAll", context, async () => {
+			return await this.lookupPopulate({
+				filters: query,
+				lookups,
+				sort: paginationOptions.sort,
+				page: useKeyset ? void 0 : page || 1,
+				after: useKeyset ? after : void 0,
+				limit,
+				select: paginationOptions.select,
+				session: options.session,
+				readPreference: paginationOptions.readPreference,
+				collation: paginationOptions.collation,
+				countStrategy: context.countStrategy ?? params.countStrategy
+			});
+		});
+		return this._runOp("getAll", context, async () => {
+			let result;
+			if (useKeyset) result = await this._pagination.stream({
+				...paginationOptions,
+				sort: paginationOptions.sort,
+				after
+			});
+			else {
+				let countFilters;
+				let forcedCountStrategy;
+				if (isNearQuery) {
+					const rewritten = rewriteNearForCount(query);
+					if (rewritten) countFilters = rewritten;
+					else forcedCountStrategy = "none";
+				}
+				result = await this._pagination.paginate({
+					...paginationOptions,
+					page: page || 1,
+					countFilters,
+					countStrategy: context.countStrategy ?? params.countStrategy ?? forcedCountStrategy
+				});
+			}
+			return result;
+		});
+	}
+	/**
+	* Atomic "look up by filter, insert `data` if missing, return the doc."
+	*
+	* Returns `{ doc, created }` so callers can tell whether *this* call
+	* inserted (race-win) or matched an existing row. Implements
+	* `StandardRepo.getOrCreate()` from `@classytic/repo-core/repository`
+	* — see that interface's JSDoc for the cross-kit contract.
+	*
+	* Routes through the hook system for policy enforcement (multi-tenant,
+	* soft-delete, audit). The hook context carries the resolved query +
+	* data; the action layer adds the `created` discriminator from the
+	* driver's `lastErrorObject.upserted`.
+	*/
+	async getOrCreate(query, createData, options = {}) {
+		const context = await this._buildContext("getOrCreate", {
+			query,
+			data: createData,
+			...options
+		});
+		return this._runOp("getOrCreate", context, () => {
+			const finalQuery = context.query || query;
+			const finalData = context.data || createData;
+			return getOrCreate(this.Model, finalQuery, finalData, options);
+		});
+	}
+	/**
+	* Count documents
+	* Routes through hook system for policy enforcement (multi-tenant, soft-delete)
+	*/
+	async count(query = {}, options = {}) {
+		const context = await this._buildContext("count", {
+			query,
+			...options
+		});
+		return this._runOp("count", context, () => count(this.Model, context.query || query, options));
+	}
+	/**
+	* Check if document exists
+	* Routes through hook system for policy enforcement (multi-tenant, soft-delete)
+	*/
+	async exists(query, options = {}) {
+		const context = await this._buildContext("exists", {
+			query,
+			...options
+		});
+		return this._runOp("exists", context, () => exists(this.Model, context.query || query, options));
+	}
+	/**
+	* Update document by ID
+	*/
+	async update(id, data, options = {}) {
+		const context = await this._buildContext("update", {
+			id,
+			data,
+			...options
+		});
+		return this._composeMiddleware("update", context, async () => {
+			try {
+				const wantsThrow = context.throwOnNotFound === true || options.throwOnNotFound === true;
+				const effectiveIdField = options.idField ?? this.idField;
+				if (effectiveIdField === "_id") {
+					if (!isValidIdForType(id, getSchemaIdType(this.Model.schema))) {
+						if (wantsThrow) throw createError(404, "Document not found");
+						await this._emitHook("after:update", {
+							context,
+							result: null
+						});
+						return null;
+					}
+				}
+				let result;
+				if (effectiveIdField !== "_id") result = await updateByQuery(this.Model, {
+					[effectiveIdField]: id,
+					...context.query || {}
+				}, context.data || data, context);
+				else result = await update(this.Model, id, context.data || data, context);
+				if (!result && wantsThrow) throw createError(404, "Document not found");
+				await this._emitHook("after:update", {
+					context,
+					result
+				});
+				return result;
+			} catch (error) {
+				await this._emitErrorHook("error:update", {
+					context,
+					error
+				});
+				throw this._handleError(error);
+			}
+		});
+	}
+	/**
+	* Atomic findOneAndUpdate (compare-and-set primitive).
+	*
+	* Single round-trip match-and-mutate for outbox relays, distributed locks,
+	* and workflow semaphores. Goes through the full hook pipeline so
+	* multi-tenant scope, soft-delete, audit, and cache plugins all apply.
+	*
+	* Returns the matched document (post-update by default) or `null` when no
+	* document matches and `upsert` is false.
+	*
+	* @example FIFO claim-lease for an outbox worker
+	* ```ts
+	* const claimed = await outboxRepo.findOneAndUpdate(
+	*   { status: 'pending', leaseExpiresAt: { $lt: new Date() } },
+	*   { $set: { status: 'processing', leaseExpiresAt: leaseUntil, leasedBy: workerId } },
+	*   { sort: { createdAt: 1 }, returnDocument: 'after' },
+	* );
+	* if (!claimed) return; // queue empty
+	* ```
+	*
+	* @example CAS upsert
+	* ```ts
+	* const lock = await locksRepo.findOneAndUpdate(
+	*   { _id: lockKey, ownerId: { $in: [null, workerId] } },
+	*   { $set: { ownerId: workerId, expiresAt: leaseUntil } },
+	*   { upsert: true },
+	* );
+	* ```
+	*/
+	async findOneAndUpdate(filter, update, options = {}) {
+		const normalizedUpdate = isUpdateSpec(update) ? compileUpdateSpecToMongo(update) : update;
+		const context = await this._buildContext("findOneAndUpdate", {
+			query: filter,
+			data: normalizedUpdate,
+			...options
+		});
+		return this._runOp("findOneAndUpdate", context, async () => {
+			const finalQuery = context.query || filter;
+			const finalUpdate = context.data || normalizedUpdate;
+			return await findOneAndUpdate(this.Model, finalQuery, finalUpdate, {
+				...options,
+				sort: options.sort,
+				returnDocument: options.returnDocument ?? "after",
+				upsert: options.upsert ?? false,
+				session: options.session
+			});
+		});
+	}
+	/**
+	* Atomic compare-and-swap state transition. Implements
+	* `StandardRepo.claim()` from `@classytic/repo-core/repository` (0.4+).
+	*
+	* Builds a `findOneAndUpdate({ _id, [field]: from, ...where }, { $set:
+	* { [field]: to, ...patch } })` in a single round-trip — race-free
+	* across concurrent callers. Returns the post-update doc on success,
+	* `null` when:
+	*   - the row exists but its current state isn't `from` (someone
+	*     else won the transition), OR
+	*   - any predicate in `transition.where` fails (paused guard,
+	*     retry-time guard, heartbeat-staleness, sub-document predicate),
+	*     OR
+	*   - no row matches the id at all.
+	*
+	* The caller can't distinguish "lost race" from "guard predicate
+	* failed" — both mean "don't proceed." That's by design: the only
+	* action either way is to back off.
+	*
+	* **Source-state — `from: T | T[]`.** Pass a literal for a single-
+	* source transition (`from: 'pending'`) or an array for the
+	* "transition from any of these states" pattern (`from: ['pending',
+	* 'approved']`). Compiles to `[stateField]: { $in: [...] }`. Real-
+	* world frequency: commission's `voidRecord` / `markClawedBack` /
+	* `endAgreement` / `_transition`, media-kit's error path,
+	* streamline's `cancelAt` — every state machine with more than one
+	* non-terminal source state hits this. Without array support those
+	* sites fall back to raw `findOneAndUpdate` and lose plugin routing.
+	*
+	* **`from` is value-only — no Mongo expressions.** `from` accepts a
+	* literal or an array of literals (`$in`-shaped). It does NOT
+	* accept `{ $ne: ... }`, `{ $lt: ... }`, `{ $exists: ... }`, or
+	* arbitrary expression objects. The CAS contract is "match if the
+	* state field equals one of these specific values" — admitting
+	* arbitrary predicates would collapse the contract into a generic
+	* filter, defeating the point of a state-machine primitive.
+	*
+	* For non-equality / range / existence predicates on the state
+	* field, use `where`:
+	*
+	* ```ts
+	* // ❌ from: { $ne: 'ended' }    — not supported, would silently work-as-filter
+	* // ✅ Use `where` for $ne / $lt / $exists / arbitrary mongo predicates:
+	* await repo.claim(id, {
+	*   from: 'active',                          // exact-match state
+	*   to: 'closed',
+	*   where: { closedAt: { $exists: false } }, // additional predicates
+	* });
+	* ```
+	*
+	* **Dotted-path `field` is supported** — `field: 'scheduling.status'`
+	* for nested state fields works. Mongo's filter and `$set` both
+	* honor dotted paths, and the from===to optimization handles them
+	* correctly (literal comparison on the path string). Use for
+	* domain models that nest the state under a sub-document
+	* (`lpn.state`, `package.condition.state`, `scheduling.status`).
+	*
+	* **`from === to` is allowed — idempotent re-claim.** Yard's
+	* `reviseDeparture` writes `departed → departed` to update the
+	* row's payload while asserting the row hasn't moved on. The CAS
+	* still returns `null` on race-loss (row left the source state),
+	* so the safety property holds. Use the same semantic as a "touch
+	* with state assertion" primitive.
+	*
+	* When `from === to` (and `from` is a literal, not an array), the
+	* implementation **skips the redundant `$set: { [stateField]: to }`
+	* write** — the filter has already pinned the state field to that
+	* exact value, so writing it again is a no-op disk operation.
+	* Workloads doing high-replay dedup (yard's `gate-event.append`,
+	* outbox replay storms, idempotent first-write CAS) save one disk
+	* write + one journal flush + one replication-log entry per replay.
+	* Three observable behaviours follow:
+	*
+	*   - With a non-empty patch: only the patch fields land in `$set`;
+	*     the redundant state-field key is dropped.
+	*   - With an empty patch and `upsert: false`: the call lowers to
+	*     a plain `findOne` round-trip — pure assertion, zero writes.
+	*     Plugin pipeline (before/after `claim` hooks) still fires
+	*     correctly — only the internal driver shape changes.
+	*   - With an empty patch and `upsert: true`: the update becomes
+	*     `{ $setOnInsert: { [stateField]: to } }` — no-op on match,
+	*     populates the inserted row's state field on miss. This is
+	*     the "pure dedup" insert-or-confirm path.
+	*
+	* For pure-dedup recipes (no real state column, just an external
+	* id used as both filter and `from`/`to`), see CLAUDE.md — yard's
+	* `gate-event.append` is the canonical worked example.
+	*
+	* **`upsert: true` — insert-or-claim.** Set `options.upsert: true`
+	* for the upsert-claim pattern: insert when the row doesn't exist,
+	* else CAS-transition the existing row. Yard's `gate-event.append`
+	* uses this for idempotent event landing. With `upsert` on, claim
+	* NEVER returns null on miss — it inserts. Pair with
+	* `$setOnInsert` in the operator patch for insert-only fields.
+	* The default (`upsert: false`) keeps the canonical "match
+	* exactly, else null" semantic.
+	*
+	* **Patch shape** — accepts BOTH flat (`{ field: value }`) and Mongo
+	* operator (`{ $set, $inc, $unset, $setOnInsert, ... }`) forms.
+	* Operator form is load-bearing for versioned docs (`$inc: {
+	* version: 1 }`) and upsert-claim (`$setOnInsert: { createdBy }`);
+	* flat form is the textbook ergonomic case. Mixing flat keys with
+	* `$`-keys throws — Mongo would silently drop the flat keys,
+	* which would mask data-loss bugs.
+	*
+	* Multi-tenant scope, soft-delete filter, cache invalidation, and
+	* audit hooks all flow through automatically — `claim` is registered
+	* in `OP_REGISTRY` (policyKey: 'query', mutates: true), so plugins
+	* that iterate the registry pick it up without changes.
+	*
+	* **Caller responsibility for tenant context.** When
+	* `multiTenantPlugin` is mounted, plugin-injected scoping reads the
+	* tenant key from the **options bag** — `claim(id, transition, patch,
+	* { organizationId: '...' })`. Without it, the plugin throws
+	* `'Missing organizationId'` at runtime. Use
+	* `repoOptionsFromCtx(ctx)` (or your own context helper) to forward
+	* request-scoped tenant fields; do not assume the plugin reads them
+	* from a global.
+	*
+	* @example Textbook transition (flat patch)
+	* ```ts
+	* const claimed = await runRepo.claim(runId, { from: 'waiting', to: 'running' }, {
+	*   lastHeartbeat: new Date(),
+	*   workerId: 'worker-12',
+	* });
+	* if (!claimed) return; // someone else got it (or no match)
+	* ```
+	*
+	* @example Versioned doc — operator patch with `$inc`
+	* ```ts
+	* const claimed = await orderRepo.claim(
+	*   orderId,
+	*   { from: 'pending', to: 'shipped' },
+	*   {
+	*     $set: { shippedAt: new Date() },
+	*     $inc: { version: 1 },
+	*   },
+	* );
+	* ```
+	*
+	* @example Compound-filter claim (paused guard + retry timer)
+	* ```ts
+	* const claimed = await runRepo.claim(
+	*   runId,
+	*   {
+	*     from: 'waiting',
+	*     to: 'running',
+	*     where: {
+	*       paused: { $ne: true },
+	*       'scheduling.retryAfter': { $lte: new Date() },
+	*     },
+	*   },
+	*   { lastHeartbeat: new Date() },
+	*   { organizationId: ctx.orgId }, // tenant fwd — see note above
+	* );
+	* ```
+	*
+	* Pairs with `defineStateMachine()` from
+	* `@classytic/primitives/state-machine`:
+	*   - State machine validates "is from→to legal in the model?"
+	*   - `claim()` performs the atomic "did we win?"
+	*/
+	async claim(id, transition, patch = {}, options = {}) {
+		const stateField = transition.field ?? "status";
+		const effectiveIdField = options.idField ?? this.idField;
+		const fromSpec = Array.isArray(transition.from) ? { $in: transition.from } : transition.from;
+		const filter = {
+			...transition.where ?? {},
+			[effectiveIdField]: id,
+			[stateField]: fromSpec
+		};
+		assertNoMixedPatchShape("claim", patch);
+		const patchKeys = Object.keys(patch);
+		const operatorPatchKeys = patchKeys.filter((k) => k.startsWith("$"));
+		const isStateNoop = !Array.isArray(transition.from) && transition.from === transition.to;
+		let update;
+		if (operatorPatchKeys.length === 0) {
+			const patchKeysCount = patchKeys.length;
+			if (isStateNoop) update = patchKeysCount === 0 ? {} : { $set: { ...patch } };
+			else update = { $set: {
+				...patch,
+				[stateField]: transition.to
+			} };
+		} else {
+			const callerSet = patch.$set ?? {};
+			if (isStateNoop) if (Object.keys(callerSet).length === 0) {
+				const { $set, ...rest } = patch;
+				update = rest;
+			} else update = {
+				...patch,
+				$set: { ...callerSet }
+			};
+			else update = {
+				...patch,
+				$set: {
+					...callerSet,
+					[stateField]: transition.to
+				}
+			};
+		}
+		if (Object.keys(update).length === 0 && options.upsert) update = { $setOnInsert: { [stateField]: transition.to } };
+		const context = await this._buildContext("claim", {
+			id,
+			query: filter,
+			data: update,
+			transition,
+			...options
+		});
+		return this._runOp("claim", context, async () => {
+			const finalQuery = context.query || filter;
+			const finalUpdate = context.data || update;
+			if (effectiveIdField === "_id" && !options.upsert) {
+				if (!isValidIdForType(id, getSchemaIdType(this.Model.schema))) return null;
+			}
+			if (Object.keys(finalUpdate).length === 0) return await this.Model.findOne(finalQuery, null, { session: options.session });
+			return await findOneAndUpdate(this.Model, finalQuery, finalUpdate, {
+				returnDocument: "after",
+				upsert: options.upsert ?? false,
+				session: options.session
+			});
+		});
+	}
+	/**
+	* Optimistic-concurrency CAS via a version stamp.
+	*
+	* Sibling to `claim()` — distinct mental model:
+	*   - `claim()` is a state machine: "move from status A to status B, atomically"
+	*   - `claimVersion()` is optimistic locking: "I expect version N; if it
+	*     still is, apply this update and increment the version"
+	*
+	* Builds `findOneAndUpdate({ _id, [versionField]: from, ...where },
+	* { ...update, $inc: { [versionField]: by ?? 1 } })` in one
+	* round-trip. Returns the post-update doc on success, `null` when:
+	*   - the row doesn't exist, OR
+	*   - the row's version isn't `from` (someone else committed first —
+	*     standard race-loss signal), OR
+	*   - any predicate in `transition.where` fails (state guard, tenant
+	*     guard expressed inline, etc.)
+	*
+	* **`from: undefined` is tolerated.** Lean reads return `version:
+	* number | undefined` because the field defaults are absent on
+	* fresh-from-mongo POJOs. Passing `from: undefined` matches docs
+	* whose version field is *missing entirely* — exactly what you want
+	* on a first-write CAS. Callers no longer need `?? 0` at every site.
+	*
+	* The caller's `update` is freeform — pass either a Mongo operator
+	* shape (`{ $set: { status: 'submitted', updatedAt: now } }`) or a
+	* field-shape object (auto-wrapped in `$set`). The version `$inc` is
+	* MERGED into the update, so callers don't have to remember to bump
+	* the counter.
+	*
+	* **Compound CAS via `where`.** State machines that key on both
+	* version AND status (yard's `transition()`, every package whose
+	* "ready to commit" gate is more than a version stamp) need to
+	* AND-merge additional predicates. Pass them via
+	* `transition.where` — same shape and semantics as `claim`'s
+	* `where` field. Without this, claimVersion was forced back to raw
+	* `findOneAndUpdate` for every state-AND-version site.
+	*
+	* Multi-tenant scope, soft-delete filter, cache invalidation, and
+	* audit hooks all fire — `claimVersion` is in `OP_REGISTRY`
+	* (policyKey: 'query', mutates: true) so plugins iterate the registry
+	* and pick it up automatically.
+	*
+	* **Caller responsibility for tenant context.** When
+	* `multiTenantPlugin` is mounted, the plugin reads the tenant key
+	* from the **options bag** (`{ organizationId: '...' }`). Without it,
+	* the plugin throws `'Missing organizationId'` at runtime. Use
+	* `repoOptionsFromCtx(ctx)` to forward — same as `claim()` and every
+	* other repo op.
+	*
+	* @example Order submission with version check
+	* ```ts
+	* const submitted = await orderRepo.claimVersion(
+	*   orderId,
+	*   { from: order.version },
+	*   { $set: { status: 'submitted', submittedAt: new Date() } },
+	* );
+	* if (!submitted) throw new ConcurrentEditError();
+	* ```
+	*
+	* @example Compound CAS — version + status
+	* ```ts
+	* const transitioned = await yardRepo.claimVersion(
+	*   loadId,
+	*   {
+	*     from: load.version, // number | undefined OK
+	*     where: { status: 'queued' },
+	*   },
+	*   { $set: { status: 'in-progress', startedAt: new Date() } },
+	* );
+	* if (!transitioned) throw new ConcurrentEditError();
+	* ```
+	*
+	* @example Custom version field name + step
+	* ```ts
+	* await runRepo.claimVersion(
+	*   runId,
+	*   { field: 'rev', from: 12, by: 1 },
+	*   { lastHeartbeat: new Date() },  // field-shape auto-wraps in $set
+	* );
+	* ```
+	*/
+	async claimVersion(id, transition, update, options = {}) {
+		const versionField = transition.field ?? "version";
+		const versionStep = transition.by ?? 1;
+		const effectiveIdField = options.idField ?? this.idField;
+		assertNoMixedPatchShape("claimVersion", update);
+		const operatorUpdate = Object.keys(update).filter((k) => k.startsWith("$")).length > 0 ? { ...update } : { $set: { ...update } };
+		const callerInc = operatorUpdate.$inc ?? {};
+		if (transition.from === void 0) {
+			const callerSet = operatorUpdate.$set ?? {};
+			if (Object.hasOwn(callerSet, versionField)) throw createError(400, `[claimVersion] first-write CAS (from: undefined) initializes the version field via $set, but the caller's update also writes $set.${versionField}. The implicit init would silently clobber the caller's value. Either remove ${versionField} from your $set, or pass a numeric \`from\` to use the standard $inc path.`);
+			if (Object.hasOwn(callerInc, versionField)) throw createError(400, `[claimVersion] first-write CAS (from: undefined) initializes the version field via $set, which can't coexist with $inc on the same field in one update. Remove ${versionField} from your $inc, or pass a numeric \`from\` to use the standard $inc path.`);
+			if (Object.keys(callerInc).length > 0) operatorUpdate.$inc = callerInc;
+			else delete operatorUpdate.$inc;
+			operatorUpdate.$set = {
+				...callerSet,
+				[versionField]: versionStep
+			};
+		} else operatorUpdate.$inc = {
+			...callerInc,
+			[versionField]: versionStep
+		};
+		const versionMatch = transition.from === void 0 ? null : transition.from;
+		const filter = {
+			...transition.where ?? {},
+			[effectiveIdField]: id,
+			[versionField]: versionMatch
+		};
+		const context = await this._buildContext("claimVersion", {
+			id,
+			query: filter,
+			data: operatorUpdate,
+			transition,
+			...options
+		});
+		return this._runOp("claimVersion", context, async () => {
+			const finalQuery = context.query || filter;
+			const finalUpdate = context.data || operatorUpdate;
+			if (effectiveIdField === "_id") {
+				if (!isValidIdForType(id, getSchemaIdType(this.Model.schema))) return null;
+			}
+			return await findOneAndUpdate(this.Model, finalQuery, finalUpdate, {
+				returnDocument: "after",
+				upsert: false,
+				session: options.session
+			});
+		});
+	}
+	/**
+	* Delete a document by ID.
+	*
+	* By default the behavior is decided by the plugin stack:
+	*   - With `softDeletePlugin` wired → soft delete (sets `deletedAt`)
+	*   - Without the plugin → physical delete
+	*
+	* Pass `mode: 'hard'` to force physical deletion regardless of plugins.
+	* All policy hooks (multi-tenant scope, audit trails, cache invalidation,
+	* cascade) still fire — only the soft-delete interception is skipped. This
+	* is the GDPR / admin-cleanup path.
+	*
+	* @example
+	* ```ts
+	* // Respects softDeletePlugin — soft if wired
+	* await userRepo.delete(userId);
+	*
+	* // GDPR erasure — physical delete, audit hooks still fire
+	* await userRepo.delete(userId, { mode: 'hard', organizationId: 'org_123' });
+	* ```
+	*/
+	async delete(id, options = {}) {
+		const context = await this._buildContext("delete", {
+			id,
+			...options,
+			...options.mode ? { deleteMode: options.mode } : {}
+		});
+		return this._composeMiddleware("delete", context, async () => {
+			try {
+				if (context.softDeleted) {
+					const result = {
+						message: "Soft deleted successfully",
+						id: String(id),
+						soft: true
+					};
+					await this._emitHook("after:delete", {
+						context,
+						result
+					});
+					return result;
+				}
+				const effectiveIdField = options.idField ?? this.idField;
+				const wantsThrow = context.throwOnNotFound === true || options.throwOnNotFound === true;
+				if (effectiveIdField === "_id") {
+					if (!isValidIdForType(id, getSchemaIdType(this.Model.schema))) {
+						if (wantsThrow) throw createError(404, "Document not found");
+						await this._emitHook("after:delete", {
+							context,
+							result: null
+						});
+						return null;
+					}
+				}
+				const deleteQuery = effectiveIdField !== "_id" ? {
+					[effectiveIdField]: id,
+					...context.query || {}
+				} : void 0;
+				const result = deleteQuery ? await deleteByQuery(this.Model, deleteQuery, { session: options.session }) : await deleteById(this.Model, id, {
+					session: options.session,
+					query: context.query
+				});
+				if (!result && wantsThrow) throw createError(404, "Document not found");
+				await this._emitHook("after:delete", {
+					context,
+					result
+				});
+				return result;
+			} catch (error) {
+				await this._emitErrorHook("error:delete", {
+					context,
+					error
+				});
+				throw this._handleError(error);
+			}
+		});
+	}
+	/**
+	* Update every document matching the filter.
+	*
+	* Promoted from `batchOperationsPlugin` to a class primitive in 3.11.0 so
+	* the surface matches sqlitekit's always-available `updateMany`. Consumers
+	* who forget to wire `batchOperationsPlugin` no longer get a runtime
+	* `TypeError: repo.updateMany is not a function` — the method is always
+	* here.
+	*
+	* Accepts three `update` forms via `UpdateInput`:
+	*   - Portable `UpdateSpec` from `@classytic/repo-core/update` (compiled to
+	*     `$set`/`$unset`/`$inc`/`$setOnInsert` before hooks run).
+	*   - Raw Mongo operator record (`{ $set, $inc, ... }`) — passed through.
+	*   - Mongo aggregation pipeline (`[...]`) — requires `updatePipeline: true`
+	*     to guard against accidental pipeline updates.
+	*
+	* Refuses empty filters (defense-in-depth against mass-update accidents)
+	* both before and after policy hooks inject tenant scope.
+	*/
+	async updateMany(filter, update, options = {}) {
+		const normalizedData = isUpdateSpec(update) ? compileUpdateSpecToMongo(update) : update;
+		const context = await this._buildContext("updateMany", {
+			query: filter,
+			data: normalizedData,
+			...options
+		});
+		return this._runOp("updateMany", context, async () => {
+			const finalQuery = context.query || filter;
+			if (!finalQuery || Object.keys(finalQuery).length === 0) throw createError(400, "updateMany requires a non-empty query filter. Pass an explicit filter to prevent accidental mass updates.");
+			if (Array.isArray(normalizedData) && options.updatePipeline !== true) throw createError(400, "Update pipelines (array updates) are disabled by default; pass `{ updatePipeline: true }` to explicitly allow pipeline-style updates.");
+			const finalData = context.data || normalizedData;
+			return await this.Model.updateMany(finalQuery, finalData, {
+				runValidators: true,
+				session: options.session,
+				...options.updatePipeline !== void 0 ? { updatePipeline: options.updatePipeline } : {}
+			}).exec();
+		});
+	}
+	/**
+	* Delete every document matching the filter.
+	*
+	* Promoted from `batchOperationsPlugin` to a class primitive in 3.11.0 for
+	* the same reason as `updateMany` — sqlitekit parity and no silent "method
+	* is undefined" footgun when the batch plugin isn't wired.
+	*
+	* Behavior mirrors `delete()`: defaults to soft delete when
+	* `softDeletePlugin` is wired, physical delete otherwise. Pass
+	* `{ mode: 'hard' }` to bypass soft-delete — multi-tenant scoping, audit,
+	* and cache hooks still fire.
+	*
+	* Rejects empty filters up front AND after policy hooks, so a policy-plugin
+	* bug that zeroes out the query can't be exploited to wipe a collection.
+	*/
+	async deleteMany(filter, options = {}) {
+		if (!filter || Object.keys(filter).length === 0) throw createError(400, "deleteMany requires a non-empty query filter. Pass an explicit filter to prevent accidental mass deletes.");
+		const mode = options.mode;
+		const context = await this._buildContext("deleteMany", {
+			query: filter,
+			...options,
+			...mode ? { deleteMode: mode } : {}
+		});
+		return this._composeMiddleware("deleteMany", context, async () => {
+			try {
+				if (context.softDeleted) {
+					const result = {
+						acknowledged: true,
+						deletedCount: context.softDeletedCount ?? 0,
+						soft: true
+					};
+					await this._emitHook("after:deleteMany", {
+						context,
+						result
+					});
+					return result;
+				}
+				const finalQuery = context.query || filter;
+				if (!finalQuery || Object.keys(finalQuery).length === 0) throw createError(400, "deleteMany requires a non-empty query filter after policy hooks.");
+				const result = await this.Model.deleteMany(finalQuery, { session: options.session }).exec();
+				await this._emitHook("after:deleteMany", {
+					context,
+					result
+				});
+				return result;
+			} catch (error) {
+				await this._emitErrorHook("error:deleteMany", {
+					context,
+					error
+				});
+				throw this._handleError(error);
+			}
+		});
+	}
+	/**
+	* Kit-native aggregation pipeline — takes a MongoDB stage array and
+	* returns the raw pipeline output. Use this for `$lookup`, `$unwind`,
+	* `$facet`, `$graphLookup`, and any other mongo-specific power
+	* features that don't translate to SQL.
+	*
+	* For backend-portable aggregations (filter + group + measures +
+	* sort + limit) use `aggregate(req: AggRequest)` instead — it
+	* compiles the repo-core IR to the equivalent pipeline internally
+	* and produces the same row shape sqlitekit emits.
+	*
+	* Routes through the hook system for policy enforcement
+	* (multi-tenant, soft-delete).
+	*
+	* @param pipeline - MongoDB aggregation stage array
+	* @param options  - Aggregation options including governance controls
+	*/
+	async aggregatePipeline(pipeline, options = {}) {
+		const context = await this._buildContext("aggregatePipeline", {
+			pipeline,
+			...options
+		});
+		const maxStages = options.maxPipelineStages;
+		if (maxStages && pipeline.length > maxStages) throw createError(400, `Aggregation pipeline exceeds maximum allowed stages (${pipeline.length} > ${maxStages})`);
+		return this._runOp("aggregatePipeline", context, async () => {
+			const finalPipeline = [...pipeline];
+			if (context.query && Object.keys(context.query).length > 0) finalPipeline.unshift({ $match: context.query });
+			const aggregation = this.Model.aggregate(finalPipeline);
+			if (options.session) aggregation.session(options.session);
+			if (options.allowDiskUse) aggregation.allowDiskUse(true);
+			if (options.readPreference) aggregation.read(options.readPreference);
+			if (options.maxTimeMS) aggregation.option({ maxTimeMS: options.maxTimeMS });
+			if (options.comment) aggregation.option({ comment: options.comment });
+			if (options.readConcern) aggregation.option({ readConcern: options.readConcern });
+			if (options.collation) aggregation.collation(options.collation);
+			return await aggregation.exec();
+		});
+	}
+	/**
+	* Paginated kit-native aggregation pipeline. Same mongo-specific
+	* scope as `aggregatePipeline` — reach for this when you need
+	* `$lookup` / `$unwind` / `$facet` alongside pagination.
+	*
+	* Prefer `aggregatePaginate(req: AggPaginationRequest)` for
+	* cross-backend dashboard code; that method compiles the portable
+	* IR to an equivalent pipeline.
+	*
+	* Policy hooks (multi-tenant, soft-delete) inject context.filters
+	* which are prepended as a `$match` stage.
+	*/
+	async aggregatePipelinePaginate(options = {}) {
+		const context = await this._buildContext("aggregatePipelinePaginate", options);
+		const finalPipeline = [...context.pipeline || options.pipeline || []];
+		if (context.filters && Object.keys(context.filters).length > 0) finalPipeline.unshift({ $match: context.filters });
+		const aggOptions = {
+			...context,
+			pipeline: finalPipeline
+		};
+		return this._runOp("aggregatePipelinePaginate", context, () => this._pagination.aggregatePaginate(aggOptions));
+	}
+	/**
+	* Portable aggregation. Compiles the repo-core `AggRequest` IR to
+	* `[{$match}, {$group}, {$addFields}, {$project}, {$match}, {$sort},
+	* {$skip}, {$limit}]` against this repo's collection. Output rows
+	* carry one key per `groupBy` column plus one key per measure alias
+	* — identical shape to sqlitekit's `aggregate(req)`, so dashboards
+	* work unchanged across backends.
+	*
+	* Without `groupBy`: returns a single-row result with just the
+	* measures (scalar aggregation). Pass
+	* `{ measures: { total: { op: 'sum', field: 'amount' } } }` for a
+	* simple summary.
+	*
+	* For mongo-specific power features (`$lookup`, `$unwind`, `$facet`,
+	* `$graphLookup`, window operators) reach for `aggregatePipeline`
+	* — that's the kit-native escape hatch.
+	*
+	* Routes through the hook system for policy enforcement
+	* (multi-tenant, soft-delete) — plugins inject their scope into
+	* `context.filter`, which is merged into the pre-aggregate `$match`
+	* before compilation.
+	*/
+	async aggregate(req) {
+		const context = await this._buildContext("aggregate", { aggRequest: req });
+		const cached = this._cachedValue(context);
+		if (cached !== void 0) {
+			await this._emitHook("after:aggregate", {
+				context,
+				result: cached,
+				fromCache: true
+			});
+			return cached;
+		}
+		return this._runOp("aggregate", context, async () => {
+			const finalReq = this._injectPolicyScopeIntoAgg(req, context);
+			return { rows: await executeAgg(this.Model, finalReq, { session: context.session }) };
+		});
+	}
+	/**
+	* Invalidate every aggregate-cache entry tagged with ANY of the
+	* given tags. Delegates to the unified cache plugin's handle
+	* (`repo.cache.invalidateByTags`) — wired by `cachePlugin({ adapter })`.
+	*
+	* Pass no tags to wipe the entire cache namespace (requires the
+	* adapter to implement `clear`).
+	*
+	* Returns the count of distinct entries cleared (`-1` when the call
+	* routed through `adapter.clear()` and the adapter doesn't report a
+	* count). No-op (returns `0`) when no cache plugin is wired.
+	*/
+	async invalidateAggregateCache(tags) {
+		const handle = this.cache;
+		if (!handle) return 0;
+		if (!tags || tags.length === 0) {
+			await handle.clear();
+			return -1;
+		}
+		return handle.invalidateByTags(tags);
+	}
+	/**
+	* Paginated portable aggregation. Two pagination modes, picked by
+	* the request shape:
+	*
+	* - **Offset (default)** — `page` + `limit`. Returns the standard
+	*   `{ method: 'offset', data, total, pages, hasNext, hasPrev, ... }`
+	*   envelope. `countStrategy: 'none'` skips the second round-trip
+	*   that computes `total`; the envelope reports `total: 0`,
+	*   `pages: 0`, and derives `hasNext` from a `LIMIT N+1` peek on
+	*   the data pipeline.
+	* - **Keyset** — `pagination: 'keyset'` (or `after` set). Returns
+	*   `{ method: 'keyset', data, hasMore, next, limit }`. `sort` is
+	*   required — the cursor encodes the sort-key tuple of the last
+	*   row. Each subsequent page passes the previous `next` back as
+	*   `after`. Scales to arbitrary group counts because the planner
+	*   uses `(sort_keys) > (cursor)` instead of `OFFSET N`.
+	*/
+	async aggregatePaginate(req) {
+		const context = await this._buildContext("aggregatePaginate", { aggRequest: req });
+		const limit = Math.max(1, Math.min(req.limit ?? 20, 1e3));
+		const session = context.session;
+		const useKeyset = isKeysetMode(req);
+		const cachedEnvelope = this._cachedValue(context);
+		if (cachedEnvelope !== void 0) {
+			await this._emitHook("after:aggregatePaginate", {
+				context,
+				result: cachedEnvelope,
+				fromCache: true
+			});
+			return cachedEnvelope;
+		}
+		return this._composeMiddleware("aggregatePaginate", context, async () => {
+			try {
+				const finalReq = this._injectPolicyScopeIntoAgg(req, context);
+				const result = await this._executeAggregatePaginate(finalReq, useKeyset, limit, session);
+				await this._emitHook("after:aggregatePaginate", {
+					context,
+					result
+				});
+				return result;
+			} catch (error) {
+				await this._emitErrorHook("error:aggregatePaginate", {
+					context,
+					error
+				});
+				throw this._handleError(error);
+			}
+		});
+	}
+	/**
+	* Internal: the actual aggregate-paginate execution body. Extracted
+	* so `aggregatePaginate` can wrap it in the cache layer without
+	* duplicating the keyset / offset branch logic.
+	*
+	* Receives `finalReq` (already policy-scoped) so the cache key
+	* built by the outer wrapper matches the request the executor
+	* sees — no cross-tenant cache poisoning.
+	*/
+	async _executeAggregatePaginate(finalReq, useKeyset, limit, session) {
+		if (useKeyset) {
+			if (!finalReq.sort || Object.keys(finalReq.sort).length === 0) throw new Error("mongokit/aggregatePaginate: keyset pagination requires `sort` — the cursor anchors on the sort-key tuple");
+			const cursor = finalReq.after ? decodeAggCursor$1(finalReq.after) : void 0;
+			const keysetMatch = cursor ? buildKeysetPredicate(finalReq.sort, cursor) : void 0;
+			const { pipeline, prePaginationIndex } = buildAggPipeline(finalReq);
+			const headStages = pipeline.slice(0, prePaginationIndex);
+			const tailStages = [];
+			if (keysetMatch) tailStages.push(keysetMatch);
+			tailStages.push({ $sort: finalReq.sort });
+			tailStages.push({ $limit: limit + 1 });
+			const aggregation = this.Model.aggregate([...headStages, ...tailStages]);
+			if (session) aggregation.session(session);
+			applyExecutionHints(aggregation, finalReq.executionHints);
+			const peeked = await aggregation.exec();
+			const hasMore = peeked.length > limit;
+			const data = hasMore ? peeked.slice(0, limit) : peeked;
+			return {
+				method: "keyset",
+				data,
+				limit,
+				hasMore,
+				next: hasMore && data.length > 0 ? encodeAggCursor(data[data.length - 1], finalReq.sort) : null
+			};
+		}
+		const page = Math.max(1, finalReq.page ?? 1);
+		const countStrategy = finalReq.countStrategy ?? "exact";
+		const offset = (page - 1) * limit;
+		if (countStrategy === "none") {
+			const peek = await executeAgg(this.Model, {
+				...finalReq,
+				limit: limit + 1,
+				offset
+			}, session ? { session } : {});
+			const hasNext = peek.length > limit;
+			return {
+				method: "offset",
+				data: hasNext ? peek.slice(0, limit) : peek,
+				page,
+				limit,
+				total: 0,
+				pages: 0,
+				hasNext,
+				hasPrev: page > 1
+			};
+		}
+		const [data, total] = await Promise.all([executeAgg(this.Model, {
+			...finalReq,
+			limit,
+			offset
+		}, session ? { session } : {}), countAggGroups(this.Model, finalReq, session ? { session } : {})]);
+		return {
+			method: "offset",
+			data,
+			page,
+			limit,
+			total,
+			pages: Math.max(1, Math.ceil(total / limit)),
+			hasNext: page * limit < total,
+			hasPrev: page > 1
+		};
+	}
+	/**
+	* Merge policy-hook-injected filters (multi-tenant scope,
+	* soft-delete) into the pre-aggregate `filter` slot of the request.
+	* Plugins speak mongo-query shape (`context.query` / `context.filters`);
+	* the caller's `req.filter` may be either Filter IR or a mongo query.
+	*
+	* Each part is compiled through `compileFilterToMongo` BEFORE the
+	* `$and` merge — otherwise an IR node like `eq('status', 'paid')`
+	* (`{ op, field, value }`) gets nested inside `$and` as a literal,
+	* `compileFilterToMongo` of the merged value finds no top-level `op`
+	* (so `isFilter` is false), and Mongo receives the IR object as a
+	* raw query clause that matches no real document. Symptom: aggregates
+	* silently return 0 rows whenever a callerpasses IR + a policy
+	* plugin is installed.
+	*/
+	_injectPolicyScopeIntoAgg(req, context) {
+		const scopeCandidates = [];
+		for (const candidate of [context.filters, context.query]) if (candidate && typeof candidate === "object" && Object.keys(candidate).length > 0) scopeCandidates.push(candidate);
+		if (scopeCandidates.length === 0) return req;
+		const parts = [];
+		for (const c of scopeCandidates) {
+			const compiled = compileFilterToMongo(c);
+			if (Object.keys(compiled).length > 0) parts.push(compiled);
+		}
+		if (req.filter) {
+			const compiled = compileFilterToMongo(req.filter);
+			if (Object.keys(compiled).length > 0) parts.push(compiled);
+		}
+		if (parts.length === 0) return req;
+		const merged = parts.length === 1 ? parts[0] : { $and: parts };
+		return {
+			...req,
+			filter: merged
+		};
+	}
+	/**
+	* Get distinct values
+	* Routes through hook system for policy enforcement (multi-tenant, soft-delete)
+	*/
+	async distinct(field, query = {}, options = {}) {
+		const context = await this._buildContext("distinct", {
+			query,
+			...options
+		});
+		return this._runOp("distinct", context, () => {
+			const finalQuery = context.query || query;
+			const readPreference = context.readPreference ?? options.readPreference;
+			return distinct(this.Model, field, finalQuery, {
+				session: options.session,
+				readPreference
+			});
+		});
+	}
+	/**
+	* Query with custom field lookups ($lookup)
+	* Best for: Joins on slugs, SKUs, codes, or other indexed custom fields
+	*
+	* @example
+	* ```typescript
+	* // Join employees with departments using slug instead of ObjectId
+	* const employees = await employeeRepo.lookupPopulate({
+	*   filters: { status: 'active' },
+	*   lookups: [
+	*     {
+	*       from: 'departments',
+	*       localField: 'departmentSlug',
+	*       foreignField: 'slug',
+	*       as: 'department',
+	*       single: true
+	*     }
+	*   ],
+	*   sort: '-createdAt',
+	*   page: 1,
+	*   limit: 50
+	* });
+	* ```
+	*/
+	async lookupPopulate(options) {
+		const context = await this._buildContext("lookupPopulate", options);
+		return this._composeMiddleware("lookupPopulate", context, async () => {
+			try {
+				const MAX_LOOKUPS = 10;
+				const lookups = context.lookups ?? options.lookups;
+				if (lookups.length > MAX_LOOKUPS) throw createError(400, `Too many lookups (${lookups.length}). Maximum is ${MAX_LOOKUPS}.`);
+				const filters = context.filters ?? options.filters;
+				const sort = context.sort ?? options.sort;
+				const limit = context.limit ?? options.limit ?? this._pagination.config.defaultLimit ?? 20;
+				const readPref = context.readPreference ?? options.readPreference;
+				const session = context.session ?? options.session;
+				const collation = context.collation ?? options.collation;
+				const after = context.after ?? options.after;
+				const pageFromContext = context.page ?? options.page;
+				const isKeyset = !!after || !pageFromContext && !!sort;
+				const countStrategy = context.countStrategy ?? options.countStrategy ?? "exact";
+				const selectSpec = context.select ?? options.select;
+				let projection;
+				if (selectSpec) {
+					if (typeof selectSpec === "string") {
+						projection = {};
+						for (const field of selectSpec.split(",").map((f) => f.trim())) if (field.startsWith("-")) projection[field.substring(1)] = 0;
+						else projection[field] = 1;
+					} else if (Array.isArray(selectSpec)) {
+						projection = {};
+						for (const field of selectSpec) if (field.startsWith("-")) projection[field.substring(1)] = 0;
+						else projection[field] = 1;
+					} else projection = { ...selectSpec };
+					if (projection) {
+						if (Object.values(projection).some((v) => v === 1)) for (const lookup of lookups) {
+							const asField = lookup.as || lookup.from;
+							if (!(asField in projection)) projection[asField] = 1;
+						}
+					}
+				}
+				const appendLookupStages = (pipeline) => {
+					pipeline.push(...LookupBuilder.multiple(lookups));
+					for (const lookup of lookups) if (lookup.single) {
+						const asField = lookup.as || lookup.from;
+						pipeline.push({ $addFields: { [asField]: { $ifNull: [`$${asField}`, null] } } });
+					}
+					const finalProjection = ensureLookupProjectionIncludesCursorFields(projection, isKeyset && sort ? this._parseSort(sort) : void 0);
+					if (finalProjection) pipeline.push({ $project: finalProjection });
+				};
+				if (isKeyset && sort) {
+					const parsedSort = this._parseSort(sort);
+					const { validateKeysetSort } = await import("./sort-CrZjTK25.mjs").then((n) => n.n);
+					const { encodeCursor, resolveCursorFilter } = await import("./cursor-J84rR6wG.mjs").then((n) => n.t);
+					const { getPrimaryField } = await import("./sort-CrZjTK25.mjs").then((n) => n.n);
+					const normalizedSort = validateKeysetSort(parsedSort, this._pagination.config.strictKeysetSortFields);
+					const cursorVersion = this._pagination.config.cursorVersion ?? 1;
+					const minCursorVersion = this._pagination.config.minCursorVersion ?? 1;
+					const matchFilters = after ? resolveCursorFilter(after, normalizedSort, cursorVersion, { ...filters || {} }, minCursorVersion) : { ...filters || {} };
+					if (projection) {
+						if (Object.values(projection).some((v) => v === 1)) {
+							for (const sortField of Object.keys(normalizedSort)) if (!(sortField in projection)) projection[sortField] = 1;
+						}
+					}
+					const pipeline = [];
+					if (Object.keys(matchFilters).length > 0) pipeline.push({ $match: matchFilters });
+					pipeline.push({ $sort: normalizedSort });
+					pipeline.push({ $limit: limit + 1 });
+					appendLookupStages(pipeline);
+					const aggregation = this.Model.aggregate(pipeline).session(session || null);
+					if (collation) aggregation.collation(collation);
+					if (readPref) aggregation.read(readPref);
+					const data = await aggregation;
+					const hasMore = data.length > limit;
+					if (hasMore) data.pop();
+					const primaryField = getPrimaryField(normalizedSort);
+					const result = {
+						method: "keyset",
+						data,
+						limit,
+						hasMore,
+						next: hasMore && data.length > 0 ? encodeCursor(data[data.length - 1], primaryField, normalizedSort, cursorVersion) : null
+					};
+					await this._emitHook("after:lookupPopulate", {
+						context,
+						result
+					});
+					return result;
+				}
+				const page = pageFromContext ?? 1;
+				const skip = (page - 1) * limit;
+				if (skip > 1e4) warn(`[mongokit] Large offset (${skip}) in lookupPopulate. Consider using keyset pagination: getAll({ sort, after, limit, lookups })`);
+				const dataPipeline = [];
+				if (filters && Object.keys(filters).length > 0) dataPipeline.push({ $match: filters });
+				if (sort) dataPipeline.push({ $sort: this._parseSort(sort) });
+				if (countStrategy === "none") {
+					dataPipeline.push({ $skip: skip }, { $limit: limit + 1 });
+					appendLookupStages(dataPipeline);
+					const aggregation = this.Model.aggregate(dataPipeline).session(session || null);
+					if (collation) aggregation.collation(collation);
+					if (readPref) aggregation.read(readPref);
+					const data = await aggregation;
+					const hasNext = data.length > limit;
+					if (hasNext) data.pop();
+					const result = {
+						method: "offset",
+						data,
+						page,
+						limit,
+						total: 0,
+						pages: 0,
+						hasNext,
+						hasPrev: page > 1
+					};
+					await this._emitHook("after:lookupPopulate", {
+						context,
+						result
+					});
+					return result;
+				}
+				dataPipeline.push({ $skip: skip }, { $limit: limit });
+				appendLookupStages(dataPipeline);
+				const countPipeline = [];
+				if (filters && Object.keys(filters).length > 0) countPipeline.push({ $match: filters });
+				countPipeline.push({ $count: "total" });
+				const pipeline = [{ $facet: {
+					metadata: countPipeline,
+					data: dataPipeline
+				} }];
+				const aggregation = this.Model.aggregate(pipeline).session(session || null);
+				if (collation) aggregation.collation(collation);
+				if (readPref) aggregation.read(readPref);
+				const facetResult = (await aggregation)[0] || {
+					metadata: [],
+					data: []
+				};
+				const total = facetResult.metadata[0]?.total || 0;
+				const result = {
+					method: "offset",
+					data: facetResult.data || [],
+					page,
+					limit,
+					total,
+					pages: Math.max(1, Math.ceil(total / limit)),
+					hasNext: page * limit < total,
+					hasPrev: page > 1
+				};
+				await this._emitHook("after:lookupPopulate", {
+					context,
+					result
+				});
+				return result;
+			} catch (error) {
+				await this._emitErrorHook("error:lookupPopulate", {
+					context,
+					error
+				});
+				throw this._handleError(error);
+			}
+		});
+	}
+	/**
+	* Create an aggregation builder for this model
+	* Useful for building complex custom aggregations
+	*
+	* @example
+	* ```typescript
+	* const pipeline = repo.buildAggregation()
+	*   .match({ status: 'active' })
+	*   .lookup('departments', 'deptSlug', 'slug', 'department', true)
+	*   .group({ _id: '$department', count: { $sum: 1 } })
+	*   .sort({ count: -1 })
+	*   .build();
+	*
+	* const results = await repo.Model.aggregate(pipeline);
+	* ```
+	*/
+	buildAggregation() {
+		return new AggregationBuilder();
+	}
+	/**
+	* Create a lookup builder
+	* Useful for building $lookup stages independently
+	*
+	* @example
+	* ```typescript
+	* const lookupStages = repo.buildLookup('departments')
+	*   .localField('deptSlug')
+	*   .foreignField('slug')
+	*   .as('department')
+	*   .single()
+	*   .build();
+	*
+	* const pipeline = [
+	*   { $match: { status: 'active' } },
+	*   ...lookupStages
+	* ];
+	* ```
+	*/
+	buildLookup(from) {
+		return new LookupBuilder(from);
+	}
+	/**
+	* Execute callback within a MongoDB transaction with automatic retry on
+	* transient failures.
+	*
+	* **BREAKING (3.10):** the callback now receives a **tx-bound repository**,
+	* not a raw `ClientSession`. This matches repo-core's `StandardRepo.withTransaction`
+	* contract that every kit (sqlitekit, pgkit, prismakit) already implements
+	* — so cross-kit plugins and apps are portable. Session threading happens
+	* transparently: every CRUD call on `txRepo` auto-injects the session into
+	* its options bag, including plugin-added methods (`upsert`, `increment`,
+	* `updateMany`, `restore`, ...). Nested `txRepo.withTransaction(...)` throws.
+	*
+	* For raw-session cross-repo workflows — multiple repositories coordinating
+	* writes — use the standalone `withTransaction(connection, fn)` export
+	* from `@classytic/mongokit`. That helper remains session-based by design.
+	*
+	* @param callback - Receives a tx-bound `Repository<TDoc>` — call its
+	*                   methods directly, no need to pass `{ session }` manually
+	* @param options.allowFallback - Run without transaction on standalone MongoDB (default: false)
+	* @param options.onFallback - Called when falling back to non-transactional execution
+	* @param options.transactionOptions - MongoDB driver transaction options (readConcern, writeConcern, etc.)
+	*
+	* @example
+	* ```typescript
+	* const order = await repo.withTransaction(async (txRepo) => {
+	*   const created = await txRepo.create({ total: 100 });
+	*   await txRepo.update(created._id, { confirmed: true });
+	*   return created;
+	* });
+	*
+	* // With fallback for standalone/dev environments
+	* await repo.withTransaction(
+	*   async (txRepo) => {
+	*     await txRepo.create(doc);
+	*   },
+	*   {
+	*     allowFallback: true,
+	*     onFallback: (err) => logger.warn('Running without transaction', err),
+	*   },
+	* );
+	*
+	* // Cross-repo with explicit session:
+	* import { withTransaction } from '@classytic/mongokit';
+	* await withTransaction(mongoose.connection, async (session) => {
+	*   const order = await orderRepo.create(data, { session });
+	*   await inventoryRepo.decrement(..., { session });
+	* });
+	* ```
+	*/
+	async withTransaction(callback, options = {}) {
+		return withTransaction(this.Model.db, async (session) => {
+			return callback(createTxBoundRepo(this, session));
+		}, options);
+	}
+	/**
+	* Execute custom query with event emission
+	*/
+	async _executeQuery(buildQuery) {
+		const operation = buildQuery.name || "custom";
+		const context = await this._buildContext(operation, {});
+		return this._runOp(operation, context, () => buildQuery(this.Model));
+	}
+	/**
+	* Build operation context and run before-hooks (sorted by priority).
+	*
+	* Narrows `RepositoryBase._buildContext`'s return type to mongokit's
+	* richer `RepositoryContext` (which carries `softDeleted`, `_cacheHit`,
+	* populate / readPreference / session, etc.). Runtime is inherited from
+	* the base class — this override is purely a type-narrowing shim.
+	*
+	* Hook execution order is deterministic:
+	* 1. POLICY (100) — tenant isolation, soft-delete filtering, validation
+	* 2. CACHE  (200) — cache lookup (after policy filters are injected)
+	* 3. OBSERVABILITY (300) — audit logging, metrics
+	* 4. DEFAULT (500) — user-registered hooks
+	*/
+	async _buildContext(operation, options) {
+		const normalized = this._normalizeFilterSlots(options);
+		return await super._buildContext(operation, normalized);
+	}
+	/**
+	* Walk the well-known filter-carrying keys (`query`, `filters`,
+	* `having`) and route any Filter IR through `compileFilterToMongo`.
+	* Plain Mongo queries pass through untouched — `isFilter` is the
+	* discriminator. Returns a shallow clone; never mutates input.
+	*/
+	_normalizeFilterSlots(options) {
+		let cloned = null;
+		for (const key of [
+			"query",
+			"filters",
+			"having"
+		]) {
+			const value = options[key];
+			if (value === void 0 || value === null) continue;
+			if (!isFilter(value)) continue;
+			cloned ??= { ...options };
+			cloned[key] = compileFilterToMongo(value);
+		}
+		return cloned ?? options;
+	}
+	/**
+	* Resolve the effective sort for getAll. Handles $near conflict detection
+	* (warns + drops explicit sort when $near is in filters).
+	*/
+	_resolveSort(context, params, isNearQuery) {
+		const explicitSort = context.sort ?? params.sort;
+		if (isNearQuery) {
+			if (explicitSort !== void 0) warn(`[mongokit] Repository "${this.model}" dropping explicit sort (${JSON.stringify(explicitSort)}) because the filter contains $near / $nearSphere. MongoDB forbids explicit sort with $near. Use [withinRadius] instead of [near] if you need a custom sort.`);
+			return;
+		}
+		return explicitSort ?? "-createdAt";
+	}
+	/**
+	* Detect whether to use keyset (cursor) or offset (page) pagination.
+	*/
+	_detectPaginationMode(mode, page, after, sort, context, params) {
+		if (mode) return mode === "keyset";
+		return !page && !!(after || sort !== "-createdAt" && (context.sort ?? params.sort));
+	}
+	/**
+	* Build the MongoDB query filter with search merged in. Handles text
+	* search ($text), regex search ($or of $regex), and the search-resolver
+	* plugin contract (search already cleared by a before:getAll hook).
+	*/
+	_buildSearchQuery(filters, search) {
+		const query = { ...filters };
+		if (!search) return query;
+		if (this._hasTextIndex === null) this._hasTextIndex = this.Model.schema.indexes().some((idx) => idx[0] && Object.values(idx[0]).includes("text"));
+		let effectiveMode = this.searchMode === "regex" ? "regex" : "text";
+		if (this.searchMode === "auto") effectiveMode = this._hasTextIndex ? "text" : "regex";
+		if (effectiveMode === "regex") {
+			if (!this.searchFields || this.searchFields.length === 0) throw createError(400, `Repository "${this.model}" configured with searchMode: '${this.searchMode}' but no searchFields provided.`);
+			const escaped = String(search).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+			const orConds = this.searchFields.map((field) => ({ [field]: {
+				$regex: escaped,
+				$options: "i"
+			} }));
+			if (Array.isArray(query.$or)) {
+				const existingOr = query.$or;
+				delete query.$or;
+				query.$and = [
+					...Array.isArray(query.$and) ? query.$and : [],
+					{ $or: existingOr },
+					{ $or: orConds }
+				];
+			} else query.$or = orConds;
+		} else if (this._hasTextIndex) query.$text = { $search: search };
+		else {
+			const modelName = String(this.model);
+			throw createError(400, `No text index found for ${modelName}. Cannot perform text search. Configure ${modelName}'s Repository with { searchMode: 'regex', searchFields: [...] } to enable index-free search, or create a text index on the collection for searchMode: 'text'. See https://github.com/classytic/mongokit/blob/main/docs/README.md#queryparser-url--filter`, {
+				code: "SEARCH_NOT_CONFIGURED",
+				meta: {
+					model: modelName,
+					configuredMode: this.searchMode,
+					availableModes: [
+						"text",
+						"regex",
+						"auto"
+					],
+					data: "https://github.com/classytic/mongokit/blob/main/docs/README.md#queryparser-url--filter"
+				}
+			});
+		}
+		return query;
+	}
+	/**
+	* Parse sort string or object
+	*/
+	_parseSort(sort) {
+		if (!sort) return { createdAt: -1 };
+		if (typeof sort === "object") {
+			if (Object.keys(sort).length === 0) return { createdAt: -1 };
+			return sort;
+		}
+		const sortObj = {};
+		const fields = sort.split(",").map((s) => s.trim());
+		for (const field of fields) if (field.startsWith("-")) sortObj[field.substring(1)] = -1;
+		else sortObj[field] = 1;
+		return sortObj;
+	}
+	/**
+	* Parse populate specification
+	*/
+	_parsePopulate(populate) {
+		if (!populate) return [];
+		if (typeof populate === "string") return populate.split(",").map((p) => p.trim());
+		if (Array.isArray(populate)) return populate.map((p) => typeof p === "string" ? p.trim() : p);
+		return [populate];
+	}
+	/**
+	* Classify a driver error as an authoritative duplicate-key conflict.
+	*
+	* Used by arc's outbox / idempotency adapters to distinguish
+	* "write already landed (idempotent no-op)" from "transient DB error
+	* (must retry)". Every backend signals duplicate keys differently —
+	* MongoDB `code: 11000`, Prisma `P2002`, Postgres `23505` — so this
+	* predicate lives on the kit that knows its driver. Cross-driver
+	* adapters then depend only on the boolean outcome, not the shape of
+	* the underlying error.
+	*
+	* Deliberately narrow: matches ONLY `code === 11000` and
+	* `codeName === 'DuplicateKey'`. Does NOT match
+	* `err.name === 'MongoServerError'`, which is also true for
+	* WriteConflict, NotWritablePrimary, ExceededTimeLimit, and every
+	* other server-side error — treating those as duplicate keys would
+	* silently swallow transactional retries.
+	*
+	* @example
+	* try {
+	*   await outboxRepo.create(event);
+	* } catch (err) {
+	*   if (outboxRepo.isDuplicateKeyError(err)) {
+	*     // Idempotent no-op — event was already written by a prior attempt.
+	*     return;
+	*   }
+	*   throw err; // transient DB error — upstream retries
+	* }
+	*/
+	isDuplicateKeyError(err) {
+		return isDuplicateKeyError(err);
+	}
+	/**
+	* Handle errors with proper HTTP status codes
+	*/
+	_handleError(error) {
+		if (error instanceof mongoose.Error.ValidationError) return createError(400, `Validation Error: ${Object.values(error.errors).map((err) => err.message).join(", ")}`);
+		if (error instanceof mongoose.Error.CastError) return createError(400, `Invalid ${error.path}: ${error.value}`);
+		const duplicateErr = parseDuplicateKeyError(error);
+		if (duplicateErr) return duplicateErr;
+		if (error.status && error.message) return error;
+		return createError(500, error.message || "Internal Server Error");
+	}
+};
+//#endregion
+export { withTransaction as a, MUTATING_OPERATIONS as c, operationsByPolicyKey as d, isTransactionUnsupported as i, OP_REGISTRY as l, Repository as n, AggregationBuilder as o, batchTransaction as r, ALL_OPERATIONS as s, HOOK_PRIORITY$1 as t, READ_OPERATIONS as u };