@classytic/mongokit 3.7.0 → 3.10.0

package/dist/{validation-chain.plugin-CEyJssZl.mjs → validation-chain.plugin-Ccu6irtx.mjs}

@@ -1,12 +1,149 @@
 import { n as debug, r as warn } from "./logger-DJ7egMnd.mjs";
-import { a as exists, c as getOrCreate, d as deleteByQuery, g as upsert, i as count, m as createMany, n as updateByQuery, o as getById, p as create, s as getByQuery, t as update, u as deleteById, v as distinct, y as LookupBuilder } from "./update-BDsQ3cdy.mjs";
-import { n as parseDuplicateKeyError, t as createError } from "./error-Lw9GEAro.mjs";
-import { t as PaginationEngine } from "./PaginationEngine-CPmZv7Ds.mjs";
+import { _ as upsert, 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, y as distinct } from "./update-CWXfFC6O.mjs";
+import { n as isDuplicateKeyError, r as parseDuplicateKeyError, t as createError } from "./error-CzYwrfUP.mjs";
+import { t as PaginationEngine } from "./PaginationEngine-B93fLCcO.mjs";
 import { hasNearOperator, rewriteNearForCount } from "./query/primitives/geo.mjs";
 import { r as isValidIdForType, t as getSchemaIdType } from "./id-resolution-e4BT9zAV.mjs";
 import { a as byIdKey, c as listQueryKey, l as modelPattern, o as byQueryKey, r as getFieldsForUser, u as versionKey } from "./field-selection-dI0m4RBs.mjs";
 import mongoose from "mongoose";
+import { isFilter } from "@classytic/repo-core/filter";
+import { HOOK_PRIORITY } from "@classytic/repo-core/hooks";
+import { RepositoryBase, validatePluginOrder } from "@classytic/repo-core/repository";
 import { AsyncLocalStorage } from "node:async_hooks";
+//#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
+	},
+	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
+	},
+	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/plugins/aggregate-helpers.plugin.ts
 /**
 * Aggregate helpers plugin
@@ -34,14 +171,14 @@ function aggregateHelpersPlugin() {
 					count: { $sum: 1 }
 				} }, { $sort: { count: -1 } }];
 				if (options.limit) pipeline.push({ $limit: options.limit });
-				return this.aggregate(pipeline, options);
+				return this.aggregatePipeline(pipeline, options);
 			});
 			const aggregateOperation = async function(field, operator, resultKey, query = {}, options = {}) {
 				const pipeline = [{ $match: query }, { $group: {
 					_id: null,
 					[resultKey]: { [operator]: `$${field}` }
 				} }];
-				return (await this.aggregate(pipeline, options))[0]?.[resultKey] || 0;
+				return (await this.aggregatePipeline(pipeline, options))[0]?.[resultKey] || 0;
 			};
 			/**
 			* Sum field values
@@ -99,6 +236,22 @@ function auditLogPlugin(logger) {
 					organizationId: context.organizationId
 				});
 			});
+			repo.on("after:findOneAndUpdate", ({ context, result }) => {
+				if (!result) return;
+				logger?.info?.("Document upserted/updated (findOneAndUpdate)", {
+					model: context.model || repo.model,
+					id: result?.[repo.idField || "_id"],
+					userId: context.user?._id || context.user?.id,
+					organizationId: context.organizationId
+				});
+			});
+			repo.on("error:findOneAndUpdate", ({ context, error }) => {
+				logger?.error?.("findOneAndUpdate failed", {
+					model: context.model || repo.model,
+					error: error.message,
+					userId: context.user?._id || context.user?.id
+				});
+			});
 			repo.on("after:delete", ({ context }) => {
 				logger?.info?.("Document deleted", {
 					model: context.model || repo.model,
@@ -178,6 +331,7 @@ function getAuditModel(collectionName, ttlDays) {
 			enum: [
 				"create",
 				"update",
+				"findOneAndUpdate",
 				"delete"
 			]
 		},
@@ -327,6 +481,19 @@ function auditTrailPlugin(options = {}) {
 					});
 				});
 			}
+			if (opsSet.has("findOneAndUpdate")) repo.on("after:findOneAndUpdate", ({ context, result }) => {
+				if (!result) return;
+				const doc = result;
+				const idKey = repo.idField || "_id";
+				writeAudit(AuditModel, {
+					model: context.model || repo.model,
+					operation: "findOneAndUpdate",
+					documentId: doc?.[idKey],
+					userId: getUserId(context),
+					orgId: context.organizationId,
+					metadata: metadata?.(context)
+				});
+			});
 			if (opsSet.has("delete")) repo.on("after:delete", ({ context }) => {
 				writeAudit(AuditModel, {
 					model: context.model || repo.model,
@@ -635,6 +802,231 @@ function batchOperationsPlugin() {
 	};
 }
 //#endregion
+//#region src/filter/compile.ts
+/**
+* Compile a Filter IR node to a MongoDB query object. Returns `{}`
+* when the node is `TRUE` (or an empty `and`) so callers can merge
+* with other scopes without special-casing.
+*
+* The `input` is typed as `unknown` so callers can pass either a
+* Filter IR node or an already-built Mongo query and we dispatch
+* appropriately. This keeps the portable API ergonomic for apps that
+* write Mongo queries directly today.
+*/
+function compileFilterToMongo(input) {
+	if (!input) return {};
+	if (!isFilter(input)) return input;
+	return compile(input);
+}
+function compile(filter) {
+	switch (filter.op) {
+		case "true": return {};
+		case "false": return { $expr: false };
+		case "eq": return { [filter.field]: filter.value };
+		case "ne": return filter.value === null ? { [filter.field]: { $ne: null } } : { $and: [{ [filter.field]: { $ne: filter.value } }, { [filter.field]: { $ne: null } }] };
+		case "gt": return { [filter.field]: { $gt: filter.value } };
+		case "gte": return { [filter.field]: { $gte: filter.value } };
+		case "lt": return { [filter.field]: { $lt: filter.value } };
+		case "lte": return { [filter.field]: { $lte: filter.value } };
+		case "in":
+			if (filter.values.length === 0) return { $expr: false };
+			return { [filter.field]: { $in: [...filter.values] } };
+		case "nin":
+			if (filter.values.length === 0) return {};
+			return { [filter.field]: { $nin: [...filter.values] } };
+		case "exists": return filter.exists ? { [filter.field]: { $ne: null } } : { [filter.field]: null };
+		case "like": return { [filter.field]: likeToRegex(filter.pattern, filter.caseSensitivity) };
+		case "regex": return { [filter.field]: { $regex: filter.pattern } };
+		case "and": {
+			if (filter.children.length === 0) return {};
+			const parts = filter.children.map(compile);
+			if (parts.length === 1) return parts[0];
+			return { $and: parts };
+		}
+		case "or": {
+			if (filter.children.length === 0) return { $expr: false };
+			const parts = filter.children.map(compile);
+			if (parts.length === 1) return parts[0];
+			return { $or: parts };
+		}
+		case "not": return { $nor: [compile(filter.child)] };
+		case "raw": throw new Error("mongokit/filter: `raw` is a SQL escape hatch and has no safe MongoDB translation. Pass a Mongo query object directly to the filter slot instead.");
+	}
+}
+/**
+* Translate a SQL-style LIKE pattern to a MongoDB regex.
+*
+* SQL semantics:
+*   - `%`  → match zero or more characters (`.*`)
+*   - `_`  → match exactly one character   (`.`)
+*   - `\%` → literal percent  (escape via backslash)
+*   - `\_` → literal underscore
+*   - `\\` → literal backslash
+*   - everything else is literal — regex metacharacters get escaped.
+*
+* The naive implementation `pattern.replace(/%/g, '.*')` is wrong:
+* it also expands escaped `\%` into a wildcard. We walk the pattern
+* char-by-char, honoring backslash escapes, so `like('notes', '50\\% off')`
+* matches the literal string `50% off` instead of `50<anything> off`.
+*
+* Anchored with `^` / `$` so LIKE matches the whole field value, the
+* same way sqlitekit's `LIKE` semantically does.
+*/
+function likeToRegex(pattern, caseSensitivity) {
+	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 caseSensitivity === "sensitive" ? { $regex: out } : {
+		$regex: out,
+		$options: "i"
+	};
+}
+function escapeRegexChar(ch) {
+	return /[.*+?^${}()|[\]\\]/.test(ch) ? `\\${ch}` : ch;
+}
+//#endregion
+//#region src/actions/aggregate-ir/normalize.ts
+/**
+* Normalize `AggRequest['groupBy']` into a readonly string array.
+* Returns `[]` for scalar aggregation (no groupBy). Downstream
+* compilers treat `[]` uniformly — one `$group: { _id: null, ... }`
+* stage, no per-key projection.
+*/
+function normalizeGroupBy(groupBy) {
+	if (!groupBy) return [];
+	if (typeof groupBy === "string") return [groupBy];
+	return groupBy;
+}
+/**
+* Fail loud on an empty measures bag — there's nothing to compute and
+* the caller's code path is almost certainly a wiring bug (conditional
+* collapsed, key renamed, etc.). Silently returning `{ rows: [] }`
+* would mask it.
+*/
+function validateMeasures(measures) {
+	if (!measures || Object.keys(measures).length === 0) throw new Error("mongokit/aggregate: AggRequest requires at least one measure — empty measures bag is a wiring bug");
+}
+//#endregion
+//#region src/actions/aggregate-ir/measure.ts
+function compileMeasure(measure) {
+	switch (measure.op) {
+		case "count":
+			if (!measure.field || measure.field === "*") return { groupExpr: { $sum: 1 } };
+			return { groupExpr: { $sum: { $cond: [
+				{ $ne: [`$${measure.field}`, null] },
+				1,
+				0
+			] } } };
+		case "countDistinct": return {
+			groupExpr: { $addToSet: `$${measure.field}` },
+			projectExpr: { $size: { $ifNull: ["$$CURRENT", []] } }
+		};
+		case "sum": return { groupExpr: { $sum: `$${measure.field}` } };
+		case "avg": return { groupExpr: { $avg: `$${measure.field}` } };
+		case "min": return { groupExpr: { $min: `$${measure.field}` } };
+		case "max": return { groupExpr: { $max: `$${measure.field}` } };
+	}
+}
+//#endregion
+//#region src/actions/aggregate-ir/pipeline.ts
+function buildAggPipeline(req) {
+	validateMeasures(req.measures);
+	const groupCols = normalizeGroupBy(req.groupBy);
+	const stages = [];
+	if (req.filter) {
+		const match = compileFilterToMongo(req.filter);
+		if (Object.keys(match).length > 0) stages.push({ $match: match });
+	}
+	const groupStage = { _id: groupCols.length === 0 ? null : groupCols.reduce((acc, field) => {
+		acc[field] = `$${field}`;
+		return acc;
+	}, {}) };
+	const distinctSetAliases = [];
+	for (const [alias, measure] of Object.entries(req.measures)) {
+		groupStage[alias] = compileMeasure(measure).groupExpr;
+		if (measure.op === "countDistinct") distinctSetAliases.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 });
+	}
+	const projection = { _id: 0 };
+	for (const field of groupCols) projection[field] = `$_id.${field}`;
+	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 });
+	}
+	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
+	};
+}
+//#endregion
+//#region src/actions/aggregate-ir/count.ts
+async function countAggGroups(Model, req, options = {}) {
+	const groupCols = normalizeGroupBy(req.groupBy);
+	if (req.having) {
+		const { pipeline, prePaginationIndex } = buildAggPipeline(req);
+		const finalPipeline = [...pipeline.slice(0, prePaginationIndex), { $count: "n" }];
+		const aggregation = Model.aggregate(finalPipeline);
+		if (options.session) aggregation.session(options.session);
+		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 (options.session) aggregation.session(options.session);
+		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 (options.session) aggregation.session(options.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 { pipeline } = buildAggPipeline(req);
+	const aggregation = Model.aggregate(pipeline);
+	if (options.session) aggregation.session(options.session);
+	return await aggregation.exec();
+}
+//#endregion
 //#region src/query/AggregationBuilder.ts
 /**
 * Normalize SortSpec to MongoDB's strict format (1 | -1)
@@ -1221,7 +1613,117 @@ function isTransactionUnsupported(error) {
 	return message.includes("transaction numbers are only allowed on a replica set member") || message.includes("transaction is not supported");
 }
 //#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 (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/Repository.ts
+/**
+* Repository Pattern - Data Access Layer
+*
+* Event-driven, plugin-based abstraction for MongoDB operations
+* Inspired by Meta & Stripe's repository patterns
+*
+* @example
+* ```typescript
+* const userRepo = new Repository(UserModel, [
+*   timestampPlugin(),
+*   softDeletePlugin(),
+* ]);
+*
+* // Create
+* const user = await userRepo.create({ name: 'John', email: 'john@example.com' });
+*
+* // Read with pagination
+* const users = await userRepo.getAll({ page: 1, limit: 20, filters: { status: 'active' } });
+*
+* // Update
+* const updated = await userRepo.update(user._id, { name: 'John Doe' });
+*
+* // Delete
+* await userRepo.delete(user._id);
+* ```
+*/
 function ensureLookupProjectionIncludesCursorFields(projection, sort) {
 	if (!projection || !sort) return projection;
 	if (!Object.values(projection).some((value) => value === 1)) return projection;
@@ -1230,163 +1732,80 @@ function ensureLookupProjectionIncludesCursorFields(projection, sort) {
 	return nextProjection;
 }
 /**
-* Ordered pairs that produce wrong behavior when registered out of order.
-* Each tuple is `[mustComeFirst, mustComeAfter, reason]`.
+* Plugin phase priorities (lower = runs first).
 *
-* Plugin names are read from `plugin.name` (Plugin objects). Plain-function
-* plugins without a name are skipped — no false positives.
+* 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 PLUGIN_ORDER_CONSTRAINTS = [[
-	"soft-delete",
-	"batch-operations",
-	"soft-delete must precede batch-operations so bulk deletes/updates see the soft-delete filter"
-], [
-	"multi-tenant",
-	"cache",
-	"multi-tenant must precede cache so tenant scoping is baked into cache keys (prevents cross-tenant cache poisoning)"
-]];
-function pluginName(plugin) {
-	if (!plugin || typeof plugin === "function") return void 0;
-	const name = plugin.name;
-	return typeof name === "string" ? name : void 0;
-}
-function validatePluginOrder(plugins, modelName, mode) {
-	if (mode === "off") return;
-	const names = plugins.map(pluginName);
-	for (const [first, after, reason] of PLUGIN_ORDER_CONSTRAINTS) {
-		const firstIdx = names.indexOf(first);
-		const afterIdx = names.indexOf(after);
-		if (firstIdx === -1 || afterIdx === -1) continue;
-		if (firstIdx < afterIdx) continue;
-		const message = `[mongokit] Repository "${modelName}": plugin order issue — ${reason}. Got: [..., '${after}' at index ${afterIdx}, '${first}' at index ${firstIdx}]. Swap them, or pass { pluginOrderChecks: 'off' } to silence.`;
-		if (mode === "throw") throw new Error(message);
-		warn(message);
-	}
-}
-/**
-* Plugin phase priorities (lower = runs first)
-* Policy hooks (multi-tenant, soft-delete, validation) MUST run before cache
-* to ensure filters are injected before cache keys are computed.
-*/
-const HOOK_PRIORITY = {
-	POLICY: 100,
-	CACHE: 200,
-	OBSERVABILITY: 300,
-	DEFAULT: 500
-};
+const HOOK_PRIORITY$1 = HOOK_PRIORITY;
 /**
-* Production-grade repository for MongoDB
-* Event-driven, plugin-based, with smart pagination
+* 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 {
+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;
-	_hooks;
 	_pagination;
-	_hookMode;
 	idField;
 	searchMode;
 	searchFields;
 	_hasTextIndex = null;
 	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._hooks = /* @__PURE__ */ new Map();
 		this._pagination = new PaginationEngine(Model, paginationConfig);
-		this._hookMode = options.hooks ?? "async";
 		this.idField = options.idField ?? "_id";
 		this.searchMode = options.searchMode ?? "text";
 		this.searchFields = options.searchFields;
 		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.`);
-		validatePluginOrder(plugins, this.model, options.pluginOrderChecks ?? "warn");
-		plugins.forEach((plugin) => {
-			this.use(plugin);
-		});
-	}
-	/**
-	* Register a plugin
-	*/
-	use(plugin) {
-		if (typeof plugin === "function") plugin(this);
-		else if (plugin && typeof plugin.apply === "function") plugin.apply(this);
-		return this;
+		for (const plugin of plugins) this.use(plugin);
 	}
 	/**
-	* Register event listener with optional priority for phase ordering.
+	* Live read-through view of the hook engine's listener registry.
 	*
-	* @param event - Event name (e.g. 'before:getAll')
-	* @param listener - Hook function
-	* @param options - Optional { priority } — use HOOK_PRIORITY constants.
-	*                  Lower priority numbers run first.
-	*                  Default: HOOK_PRIORITY.DEFAULT (500)
-	*/
-	on(event, listener, options) {
-		if (!this._hooks.has(event)) this._hooks.set(event, []);
-		const hooks = this._hooks.get(event) ?? [];
-		const priority = options?.priority ?? HOOK_PRIORITY.DEFAULT;
-		hooks.push({
-			listener,
-			priority
-		});
-		hooks.sort((a, b) => a.priority - b.priority);
-		return this;
-	}
-	/**
-	* Remove a specific event listener
-	*/
-	off(event, listener) {
-		const hooks = this._hooks.get(event);
-		if (hooks) {
-			const idx = hooks.findIndex((h) => h.listener === listener);
-			if (idx !== -1) hooks.splice(idx, 1);
-		}
-		return this;
-	}
-	/**
-	* Remove all listeners for an event, or all listeners entirely
+	* 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 })`.
 	*/
-	removeAllListeners(event) {
-		if (event) this._hooks.delete(event);
-		else this._hooks.clear();
-		return this;
+	get _hooks() {
+		return this.hooks.listeners();
 	}
 	/**
-	* Emit event (sync - for backwards compatibility)
+	* 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.
 	*/
-	emit(event, data) {
-		const hooks = this._hooks.get(event) || [];
-		for (const { listener } of hooks) try {
-			const result = listener(data);
-			if (result && typeof result.then === "function") result.catch((error) => {
-				if (event === "error:hook") return;
-				const err = error instanceof Error ? error : new Error(String(error));
-				this.emit("error:hook", {
-					event,
-					error: err
-				});
-			});
-		} catch (error) {
-			if (event === "error:hook") continue;
-			const err = error instanceof Error ? error : new Error(String(error));
-			this.emit("error:hook", {
-				event,
-				error: err
-			});
-		}
-	}
-	/**
-	* Emit event and await all async handlers (sorted by priority)
-	*/
-	async emitAsync(event, data) {
-		const hooks = this._hooks.get(event) || [];
-		for (const { listener } of hooks) await listener(data);
-	}
 	async _emitHook(event, data) {
-		if (this._hookMode === "async") {
-			await this.emitAsync(event, data);
-			return;
-		}
-		this.emit(event, data);
+		await this.hooks.emitAccordingToMode(event, data);
 	}
 	async _emitErrorHook(event, data) {
 		try {
@@ -1473,11 +1892,13 @@ var Repository = class {
 				});
 				return result;
 			}
+			const wantsThrow = context.throwOnNotFound === true || options.throwOnNotFound === true;
 			if (!isValidIdForType(id, getSchemaIdType(this.Model.schema))) {
-				if (context.throwOnNotFound === false || options.throwOnNotFound === false) return null;
-				throw createError(404, "Document not found");
+				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
@@ -1576,10 +1997,10 @@ var Repository = class {
 	*/
 	async findAll(filters = {}, options = {}) {
 		const context = await this._buildContext("findAll", {
-			filters,
+			query: filters,
 			...options
 		});
-		const resolvedFilters = context.filters ?? filters;
+		const resolvedFilters = context.query ?? filters;
 		try {
 			const query = this.Model.find(resolvedFilters);
 			const sortSpec = context.sort || options.sort;
@@ -1676,7 +2097,7 @@ var Repository = class {
 		};
 		const lookups = context.lookups ?? params.lookups;
 		if (lookups && lookups.length > 0) try {
-			const lookupResult = await this.lookupPopulate({
+			const result = await this.lookupPopulate({
 				filters: query,
 				lookups,
 				sort: paginationOptions.sort,
@@ -1689,31 +2110,6 @@ var Repository = class {
 				collation: paginationOptions.collation,
 				countStrategy: context.countStrategy ?? params.countStrategy
 			});
-			let result;
-			if (lookupResult.next !== void 0) result = {
-				method: "keyset",
-				docs: lookupResult.data,
-				limit: lookupResult.limit ?? limit,
-				hasMore: lookupResult.hasMore ?? false,
-				next: lookupResult.next ?? null
-			};
-			else {
-				const total = lookupResult.total ?? 0;
-				const resultLimit = lookupResult.limit ?? limit;
-				const totalPages = Math.ceil(total / resultLimit);
-				const currentPage = lookupResult.page ?? 1;
-				const hasNext = lookupResult.hasMore !== void 0 ? lookupResult.hasMore : currentPage < totalPages;
-				result = {
-					method: "offset",
-					docs: lookupResult.data,
-					page: currentPage,
-					limit: resultLimit,
-					total,
-					pages: totalPages,
-					hasNext,
-					hasPrev: currentPage > 1
-				};
-			}
 			await this._emitHook("after:getAll", {
 				context,
 				result
@@ -1848,16 +2244,25 @@ var Repository = class {
 			...options
 		});
 		try {
-			let result;
+			const wantsThrow = context.throwOnNotFound === true || options.throwOnNotFound === true;
 			const effectiveIdField = options.idField ?? this.idField;
-			if (effectiveIdField !== "_id") {
-				const updated = await updateByQuery(this.Model, {
-					[effectiveIdField]: id,
-					...context.query || {}
-				}, context.data || data, context);
-				if (!updated) throw createError(404, "Document not found");
-				result = updated;
-			} else result = await update(this.Model, id, context.data || data, context);
+			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
@@ -1872,6 +2277,64 @@ var Repository = class {
 		}
 	}
 	/**
+	* 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 context = await this._buildContext("findOneAndUpdate", {
+			query: filter,
+			data: update,
+			...options
+		});
+		try {
+			const finalQuery = context.query || filter;
+			const finalUpdate = context.data || update;
+			const result = await findOneAndUpdate(this.Model, finalQuery, finalUpdate, {
+				...options,
+				sort: options.sort,
+				returnDocument: options.returnDocument ?? "after",
+				upsert: options.upsert ?? false,
+				session: options.session
+			});
+			await this._emitHook("after:findOneAndUpdate", {
+				context,
+				result
+			});
+			return result;
+		} catch (error) {
+			await this._emitErrorHook("error:findOneAndUpdate", {
+				context,
+				error
+			});
+			throw this._handleError(error);
+		}
+	}
+	/**
 	* Delete a document by ID.
 	*
 	* By default the behavior is decided by the plugin stack:
@@ -1913,6 +2376,22 @@ var Repository = class {
 				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");
+					const result = {
+						success: false,
+						message: "Document not found",
+						id: String(id)
+					};
+					await this._emitHook("after:delete", {
+						context,
+						result
+					});
+					return result;
+				}
+			}
 			const deleteQuery = effectiveIdField !== "_id" ? {
 				[effectiveIdField]: id,
 				...context.query || {}
@@ -1921,6 +2400,7 @@ var Repository = class {
 				session: options.session,
 				query: context.query
 			});
+			if (!result.success && wantsThrow) throw createError(404, "Document not found");
 			await this._emitHook("after:delete", {
 				context,
 				result
@@ -1935,14 +2415,24 @@ var Repository = class {
 		}
 	}
 	/**
-	* Execute aggregation pipeline
-	* Routes through hook system for policy enforcement (multi-tenant, soft-delete)
+	* 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.
 	*
-	* @param pipeline - Aggregation pipeline stages
-	* @param options - Aggregation options including governance controls
+	* 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 aggregate(pipeline, options = {}) {
-		const context = await this._buildContext("aggregate", {
+	async aggregatePipeline(pipeline, options = {}) {
+		const context = await this._buildContext("aggregatePipeline", {
 			pipeline,
 			...options
 		});
@@ -1960,13 +2450,13 @@ var Repository = class {
 			if (options.readConcern) aggregation.option({ readConcern: options.readConcern });
 			if (options.collation) aggregation.collation(options.collation);
 			const result = await aggregation.exec();
-			await this._emitHook("after:aggregate", {
+			await this._emitHook("after:aggregatePipeline", {
 				context,
 				result
 			});
 			return result;
 		} catch (error) {
-			await this._emitErrorHook("error:aggregate", {
+			await this._emitErrorHook("error:aggregatePipeline", {
 				context,
 				error
 			});
@@ -1974,14 +2464,19 @@ var Repository = class {
 		}
 	}
 	/**
-	* Aggregate pipeline with pagination
-	* Best for: Complex queries, grouping, joins
+	* Paginated kit-native aggregation pipeline. Same mongo-specific
+	* scope as `aggregatePipeline` — reach for this when you need
+	* `$lookup` / `$unwind` / `$facet` alongside pagination.
 	*
-	* Policy hooks (multi-tenant, soft-delete) inject context.filters which are
-	* prepended as a $match stage to the pipeline, ensuring tenant isolation.
+	* 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 aggregatePaginate(options = {}) {
-		const context = await this._buildContext("aggregatePaginate", options);
+	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 = {
@@ -1990,6 +2485,116 @@ var Repository = class {
 		};
 		try {
 			const result = await this._pagination.aggregatePaginate(aggOptions);
+			await this._emitHook("after:aggregatePipelinePaginate", {
+				context,
+				result
+			});
+			return result;
+		} catch (error) {
+			await this._emitErrorHook("error:aggregatePipelinePaginate", {
+				context,
+				error
+			});
+			throw this._handleError(error);
+		}
+	}
+	/**
+	* 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 });
+		try {
+			const finalReq = this._injectPolicyScopeIntoAgg(req, context);
+			const result = { rows: await executeAgg(this.Model, finalReq, { session: context.session }) };
+			await this._emitHook("after:aggregate", {
+				context,
+				result
+			});
+			return result;
+		} catch (error) {
+			await this._emitErrorHook("error:aggregate", {
+				context,
+				error
+			});
+			throw this._handleError(error);
+		}
+	}
+	/**
+	* Offset-paginated portable aggregation. Same IR as `aggregate`,
+	* wrapped in the standard `OffsetPaginationResultCore` envelope so
+	* UI code paginates aggregated dashboards with the same primitives
+	* as raw document lists.
+	*
+	* `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.
+	*/
+	async aggregatePaginate(req) {
+		const context = await this._buildContext("aggregatePaginate", { aggRequest: req });
+		const page = Math.max(1, req.page ?? 1);
+		const limit = Math.max(1, Math.min(req.limit ?? 20, 1e3));
+		const countStrategy = req.countStrategy ?? "exact";
+		const offset = (page - 1) * limit;
+		const session = context.session;
+		try {
+			const finalReq = this._injectPolicyScopeIntoAgg(req, context);
+			if (countStrategy === "none") {
+				const peek = await executeAgg(this.Model, {
+					...finalReq,
+					limit: limit + 1,
+					offset
+				}, session ? { session } : {});
+				const hasNext = peek.length > limit;
+				const result = {
+					method: "offset",
+					docs: hasNext ? peek.slice(0, limit) : peek,
+					page,
+					limit,
+					total: 0,
+					pages: 0,
+					hasNext,
+					hasPrev: page > 1
+				};
+				await this._emitHook("after:aggregatePaginate", {
+					context,
+					result
+				});
+				return result;
+			}
+			const [docs, total] = await Promise.all([executeAgg(this.Model, {
+				...finalReq,
+				limit,
+				offset
+			}, session ? { session } : {}), countAggGroups(this.Model, finalReq, session ? { session } : {})]);
+			const result = {
+				method: "offset",
+				docs,
+				page,
+				limit,
+				total,
+				pages: Math.max(1, Math.ceil(total / limit)),
+				hasNext: page * limit < total,
+				hasPrev: page > 1
+			};
 			await this._emitHook("after:aggregatePaginate", {
 				context,
 				result
@@ -2004,6 +2609,29 @@ var Repository = class {
 		}
 	}
 	/**
+	* 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`);
+	* we merge those with the portable `req.filter` using `$and`.
+	*
+	* When the caller's filter is a Filter IR node we don't unwrap it —
+	* the pipeline compiler does Filter→mongo translation. Merging here
+	* as a mongo-shaped `$and` is safe because `compileFilterToMongo`
+	* passes through already-mongo queries unchanged.
+	*/
+	_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 = [...scopeCandidates];
+		if (req.filter) parts.push(req.filter);
+		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)
 	*/
@@ -2100,9 +2728,9 @@ var Repository = class {
 			};
 			if (isKeyset && sort) {
 				const parsedSort = this._parseSort(sort);
-				const { validateKeysetSort } = await import("./sort-ffe-9JBg.mjs").then((n) => n.n);
-				const { encodeCursor, resolveCursorFilter } = await import("./cursor-DZ9JSoMM.mjs").then((n) => n.t);
-				const { getPrimaryField } = await import("./sort-ffe-9JBg.mjs").then((n) => n.n);
+				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;
@@ -2124,18 +2752,18 @@ var Repository = class {
 				const hasMore = docs.length > limit;
 				if (hasMore) docs.pop();
 				const primaryField = getPrimaryField(normalizedSort);
-				const nextCursor = hasMore && docs.length > 0 ? encodeCursor(docs[docs.length - 1], primaryField, normalizedSort, cursorVersion) : null;
+				const result = {
+					method: "keyset",
+					docs,
+					limit,
+					hasMore,
+					next: hasMore && docs.length > 0 ? encodeCursor(docs[docs.length - 1], primaryField, normalizedSort, cursorVersion) : null
+				};
 				await this._emitHook("after:lookupPopulate", {
 					context,
-					result: docs
+					result
 				});
-				return {
-					data: docs,
-					total: 0,
-					limit,
-					next: nextCursor,
-					hasMore
-				};
+				return result;
 			}
 			const page = pageFromContext ?? 1;
 			const skip = (page - 1) * limit;
@@ -2152,17 +2780,21 @@ var Repository = class {
 				const docs = await aggregation;
 				const hasNext = docs.length > limit;
 				if (hasNext) docs.pop();
-				await this._emitHook("after:lookupPopulate", {
-					context,
-					result: docs
-				});
-				return {
-					data: docs,
-					total: 0,
+				const result = {
+					method: "offset",
+					docs,
 					page,
 					limit,
-					hasMore: hasNext
+					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);
@@ -2176,22 +2808,26 @@ var Repository = class {
 			const aggregation = this.Model.aggregate(pipeline).session(session || null);
 			if (collation) aggregation.collation(collation);
 			if (readPref) aggregation.read(readPref);
-			const result = (await aggregation)[0] || {
+			const facetResult = (await aggregation)[0] || {
 				metadata: [],
 				data: []
 			};
-			const total = result.metadata[0]?.total || 0;
-			const data = result.data || [];
+			const total = facetResult.metadata[0]?.total || 0;
+			const result = {
+				method: "offset",
+				docs: 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: data
+				result
 			});
-			return {
-				data,
-				total,
-				page,
-				limit
-			};
+			return result;
 		} catch (error) {
 			await this._emitErrorHook("error:lookupPopulate", {
 				context,
@@ -2242,37 +2878,58 @@ var Repository = class {
 		return new LookupBuilder(from);
 	}
 	/**
-	* Execute callback within a transaction with automatic retry on transient failures.
+	* Execute callback within a MongoDB transaction with automatic retry on
+	* transient failures.
 	*
-	* Uses the MongoDB driver's `session.withTransaction()` which automatically retries
-	* on `TransientTransactionError` and `UnknownTransactionCommitResult`.
+	* **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.
 	*
-	* The callback always receives a `ClientSession`. When `allowFallback` is true
-	* and the MongoDB deployment doesn't support transactions (e.g., standalone),
-	* the callback runs without a transaction on the same session.
+	* 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 `ClientSession` to pass to repository operations
+	* @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 result = await repo.withTransaction(async (session) => {
-	*   const order = await repo.create({ total: 100 }, { session });
-	*   await paymentRepo.create({ orderId: order._id }, { session });
-	*   return order;
+	* 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(callback, {
-	*   allowFallback: true,
-	*   onFallback: (err) => logger.warn('Running without transaction', err),
+	* 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, callback, options);
+		return withTransaction(this.Model.db, async (session) => {
+			return callback(createTxBoundRepo(this, session));
+		}, options);
 	}
 	/**
 	* Execute custom query with event emission
@@ -2296,7 +2953,12 @@ var Repository = class {
 		}
 	}
 	/**
-	* Build operation context and run before hooks (sorted by priority).
+	* 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
@@ -2305,15 +2967,29 @@ var Repository = class {
 	* 4. DEFAULT (500) — user-registered hooks
 	*/
 	async _buildContext(operation, options) {
-		const context = {
-			operation,
-			model: this.model,
-			...options
-		};
-		const event = `before:${operation}`;
-		const hooks = this._hooks.get(event) || [];
-		for (const { listener } of hooks) await listener(context);
-		return context;
+		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
@@ -2390,6 +3066,38 @@ var Repository = class {
 		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) {
@@ -2428,7 +3136,7 @@ var Repository = class {
 *     adapter: {
 *       async get(key) { return JSON.parse(await redis.get(key) || 'null'); },
 *       async set(key, value, ttl) { await redis.setex(key, ttl, JSON.stringify(value)); },
-*       async del(key) { await redis.del(key); },
+*       async delete(key) { await redis.del(key); },
 *       async clear(pattern) {
 *         const keys = await redis.keys(pattern || '*');
 *         if (keys.length) await redis.del(...keys);
@@ -2538,16 +3246,16 @@ function cachePlugin(options) {
 			}
 			/**
 			* Invalidate a specific document by ID (all shape variants).
-			* Deletes every tracked shape-variant key individually via del(),
+			* Deletes every tracked shape-variant key individually via delete(),
 			* so adapters without pattern-based clear() still get full invalidation.
 			*/
 			async function invalidateById(id) {
 				try {
 					const baseKey = byIdKey(config.prefix, model, id);
-					await config.adapter.del(baseKey);
+					await config.adapter.delete(baseKey);
 					const trackedKeys = byIdKeyRegistry.get(id);
 					if (trackedKeys) {
-						for (const key of trackedKeys) if (key !== baseKey) await config.adapter.del(key);
+						for (const key of trackedKeys) if (key !== baseKey) await config.adapter.delete(key);
 						byIdKeyRegistry.delete(id);
 					}
 					stats.invalidations++;
@@ -2586,7 +3294,7 @@ function cachePlugin(options) {
 					log(`Cache error for getById:`, e);
 					stats.errors++;
 				}
-			}, { priority: HOOK_PRIORITY.CACHE });
+			}, { priority: HOOK_PRIORITY$1.CACHE });
 			/**
 			* before:getByQuery - Check cache for single-doc query
 			* Runs at CACHE priority (200) — after policy hooks inject filters
@@ -2617,7 +3325,7 @@ function cachePlugin(options) {
 					log(`Cache error for getByQuery:`, e);
 					stats.errors++;
 				}
-			}, { priority: HOOK_PRIORITY.CACHE });
+			}, { priority: HOOK_PRIORITY$1.CACHE });
 			/**
 			* before:getOne - Same cache logic as getByQuery (single-doc)
 			*/
@@ -2645,7 +3353,7 @@ function cachePlugin(options) {
 					log(`Cache error for getOne:`, e);
 					stats.errors++;
 				}
-			}, { priority: HOOK_PRIORITY.CACHE });
+			}, { priority: HOOK_PRIORITY$1.CACHE });
 			/**
 			* before:getAll - Check cache for list query
 			* Runs at CACHE priority (200) — after policy hooks inject filters
@@ -2693,7 +3401,7 @@ function cachePlugin(options) {
 					log(`Cache error for getAll:`, e);
 					stats.errors++;
 				}
-			}, { priority: HOOK_PRIORITY.CACHE });
+			}, { priority: HOOK_PRIORITY$1.CACHE });
 			/**
 			* after:getById - Cache the result
 			*/
@@ -2823,6 +3531,22 @@ function cachePlugin(options) {
 				await bumpVersion();
 			});
 			/**
+			* after:findOneAndUpdate — atomic CAS may insert (upsert) or mutate.
+			* Result carries the matched/inserted doc; invalidate that ID and bump
+			* version. Null result (no match, no upsert) is a no-op.
+			*/
+			repo.on("after:findOneAndUpdate", async (payload) => {
+				const { result } = payload;
+				if (!result) return;
+				const idKey = repo.idField || "_id";
+				const id = result?.[idKey];
+				if (id == null) {
+					await bumpVersion();
+					return;
+				}
+				await Promise.all([invalidateById(String(id)), bumpVersion()]);
+			});
+			/**
 			* after:delete - Invalidate by ID and bump version
 			*/
 			repo.on("after:delete", async (payload) => {
@@ -3781,45 +4505,20 @@ function mongoOperationsPlugin() {
 */
 function multiTenantPlugin(options = {}) {
 	const { tenantField = "organizationId", contextKey = "organizationId", required = true, skipOperations = [], skipWhen, resolveContext, fieldType = "string" } = options;
-	const filterOps = [
-		"getAll",
-		"findAll",
-		"aggregatePaginate",
-		"lookupPopulate"
-	];
-	const queryReadOps = [
-		"getById",
-		"getByQuery",
-		"getOne",
-		"count",
-		"exists",
-		"getOrCreate",
-		"distinct",
-		"aggregate"
-	];
-	const constrainedWriteOps = [
-		"update",
-		"delete",
-		"restore"
-	];
-	const filterReadOps = ["getDeleted"];
-	const createOps = ["create", "createMany"];
-	const batchQueryOps = ["updateMany", "deleteMany"];
-	const bulkOps = ["bulkWrite"];
-	const allOps = [
-		...filterOps,
-		...filterReadOps,
-		...queryReadOps,
-		...constrainedWriteOps,
-		...createOps,
-		...batchQueryOps,
-		...bulkOps
-	];
+	const extraOps = [{
+		op: "getDeleted",
+		policyKey: "filters"
+	}];
 	return {
 		name: "multi-tenant",
 		apply(repo) {
-			for (const op of allOps) {
+			const allOps = [...ALL_OPERATIONS.map((op) => ({
+				op,
+				policyKey: OP_REGISTRY[op].policyKey
+			})), ...extraOps];
+			for (const { op, policyKey } of allOps) {
 				if (skipOperations.includes(op)) continue;
+				if (policyKey === "none") continue;
 				repo.on(`before:${op}`, (context) => {
 					if (skipWhen?.(context, op)) return;
 					let tenantId = context[contextKey];
@@ -3830,71 +4529,77 @@ function multiTenantPlugin(options = {}) {
 					if (!tenantId && required) throw new Error(`[mongokit] Multi-tenant: Missing '${contextKey}' in context for '${op}'. Pass it via options or set required: false.`);
 					if (!tenantId) return;
 					const castId = fieldType === "objectId" ? new mongoose.Types.ObjectId(tenantId) : tenantId;
-					if (filterOps.includes(op) || filterReadOps.includes(op)) context.filters = {
-						...context.filters,
-						[tenantField]: castId
-					};
-					if (queryReadOps.includes(op)) context.query = {
-						...context.query,
-						[tenantField]: castId
-					};
-					if (op === "create" && context.data) context.data[tenantField] = castId;
-					if (op === "createMany" && context.dataArray) {
-						for (const doc of context.dataArray) if (doc && typeof doc === "object") doc[tenantField] = castId;
-					}
-					if (constrainedWriteOps.includes(op)) context.query = {
-						...context.query,
-						[tenantField]: castId
-					};
-					if (batchQueryOps.includes(op)) context.query = {
-						...context.query,
-						[tenantField]: castId
-					};
-					if (op === "bulkWrite" && context.operations) {
-						const ops = context.operations;
-						for (const subOp of ops) {
-							for (const key of [
-								"updateOne",
-								"updateMany",
-								"deleteOne",
-								"deleteMany",
-								"replaceOne"
-							]) {
-								const opBody = subOp[key];
-								if (opBody?.filter) opBody.filter = {
-									...opBody.filter,
-									[tenantField]: castId
-								};
+					switch (policyKey) {
+						case "filters":
+							context.filters = {
+								...context.filters,
+								[tenantField]: castId
+							};
+							break;
+						case "query":
+							context.query = {
+								...context.query,
+								[tenantField]: castId
+							};
+							break;
+						case "data":
+							if (context.data) context.data[tenantField] = castId;
+							break;
+						case "dataArray":
+							if (context.dataArray) {
+								for (const doc of context.dataArray) if (doc && typeof doc === "object") doc[tenantField] = castId;
+							}
+							break;
+						case "operations":
+							if (context.operations) {
+								const ops = context.operations;
+								for (const subOp of ops) {
+									for (const key of [
+										"updateOne",
+										"updateMany",
+										"deleteOne",
+										"deleteMany",
+										"replaceOne"
+									]) {
+										const opBody = subOp[key];
+										if (opBody?.filter) opBody.filter = {
+											...opBody.filter,
+											[tenantField]: castId
+										};
+									}
+									const insertBody = subOp.insertOne;
+									if (insertBody?.document) insertBody.document[tenantField] = castId;
+								}
 							}
-							const insertBody = subOp.insertOne;
-							if (insertBody?.document) insertBody.document[tenantField] = castId;
-						}
+							break;
 					}
-				}, { priority: HOOK_PRIORITY.POLICY });
+				}, { priority: HOOK_PRIORITY$1.POLICY });
 			}
 		}
 	};
 }
 //#endregion
 //#region src/plugins/observability.plugin.ts
-const DEFAULT_OPS = [
-	"create",
-	"createMany",
-	"update",
-	"delete",
-	"getById",
-	"getByQuery",
-	"getOne",
-	"getAll",
-	"findAll",
-	"getOrCreate",
-	"count",
-	"exists",
-	"distinct",
-	"aggregate",
-	"aggregatePaginate",
-	"lookupPopulate"
-];
+/**
+* Observability Plugin
+*
+* Adds operation timing, structured metrics, and APM hook points.
+* Works with any monitoring system — just provide an onMetric callback.
+*
+* @example
+* ```typescript
+* const repo = new Repository(User, [
+*   observabilityPlugin({
+*     onMetric: (metric) => {
+*       // Send to DataDog, New Relic, OpenTelemetry, or console
+*       console.log(`${metric.operation} took ${metric.durationMs}ms`);
+*       statsd.histogram('mongokit.operation', metric.durationMs, { op: metric.operation });
+*     },
+*   }),
+* ]);
+* ```
+*/
+const DEFAULT_OPS = ALL_OPERATIONS;
 const timers = /* @__PURE__ */ new WeakMap();
 function observabilityPlugin(options) {
 	const { onMetric, slowThresholdMs } = options;
@@ -4046,7 +4751,7 @@ function softDeletePlugin(options = {}) {
 					}
 					context.softDeleted = true;
 				}
-			}, { priority: HOOK_PRIORITY.POLICY });
+			}, { priority: HOOK_PRIORITY$1.POLICY });
 			const injectDeleteFilterToFilters = (context) => {
 				if (options.soft !== false) {
 					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
@@ -4065,22 +4770,19 @@ function softDeletePlugin(options = {}) {
 					};
 				}
 			};
-			for (const op of [
-				"getAll",
-				"findAll",
-				"aggregatePaginate",
-				"lookupPopulate"
-			]) repo.on(`before:${op}`, injectDeleteFilterToFilters, { priority: HOOK_PRIORITY.POLICY });
-			for (const op of [
-				"getById",
-				"getOne",
-				"getByQuery",
-				"count",
-				"exists",
-				"getOrCreate",
-				"distinct",
-				"aggregate"
-			]) repo.on(`before:${op}`, injectDeleteFilterToQuery, { priority: HOOK_PRIORITY.POLICY });
+			const SOFT_DELETE_SPECIAL = new Set([
+				"updateMany",
+				"deleteMany",
+				"bulkWrite"
+			]);
+			for (const op of ALL_OPERATIONS) {
+				if (SOFT_DELETE_SPECIAL.has(op)) continue;
+				const desc = OP_REGISTRY[op];
+				const isFilterableMutation = op === "findOneAndUpdate";
+				if (desc.mutates && !isFilterableMutation) continue;
+				if (desc.policyKey === "filters") repo.on(`before:${op}`, injectDeleteFilterToFilters, { priority: HOOK_PRIORITY$1.POLICY });
+				else if (desc.policyKey === "query") repo.on(`before:${op}`, injectDeleteFilterToQuery, { priority: HOOK_PRIORITY$1.POLICY });
+			}
 			repo.on("before:updateMany", (context) => {
 				if (options.soft !== false) {
 					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
@@ -4089,7 +4791,7 @@ function softDeletePlugin(options = {}) {
 						...deleteFilter
 					};
 				}
-			}, { priority: HOOK_PRIORITY.POLICY });
+			}, { priority: HOOK_PRIORITY$1.POLICY });
 			repo.on("before:deleteMany", async (context) => {
 				if (context.deleteMode === "hard") return;
 				if (options.soft !== false) {
@@ -4101,25 +4803,7 @@ function softDeletePlugin(options = {}) {
 					await repo.Model.updateMany(finalQuery, { $set: { [deletedField]: /* @__PURE__ */ new Date() } }, { session: context.session });
 					context.softDeleted = true;
 				}
-			}, { priority: HOOK_PRIORITY.POLICY });
-			repo.on("before:aggregate", (context) => {
-				if (options.soft !== false) {
-					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
-					if (Object.keys(deleteFilter).length > 0) context.query = {
-						...context.query || {},
-						...deleteFilter
-					};
-				}
-			}, { priority: HOOK_PRIORITY.POLICY });
-			repo.on("before:aggregatePaginate", (context) => {
-				if (options.soft !== false) {
-					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
-					if (Object.keys(deleteFilter).length > 0) context.filters = {
-						...context.filters || {},
-						...deleteFilter
-					};
-				}
-			}, { priority: HOOK_PRIORITY.POLICY });
+			}, { priority: HOOK_PRIORITY$1.POLICY });
 			if (addRestoreMethod) {
 				const restoreMethod = async function(id, restoreOptions = {}) {
 					const context = await this._buildContext("restore", {
@@ -4348,6 +5032,20 @@ function timestampPlugin() {
 				if (!context.data) return;
 				context.data.updatedAt = /* @__PURE__ */ new Date();
 			});
+			repo.on("before:findOneAndUpdate", (context) => {
+				if (!context.data) return;
+				const now = /* @__PURE__ */ new Date();
+				if (Array.isArray(context.data)) return;
+				const update = context.data;
+				if (Object.keys(update).some((k) => k.startsWith("$"))) {
+					const set = update.$set || {};
+					set.updatedAt = now;
+					update.$set = set;
+					const setOnInsert = update.$setOnInsert || {};
+					if (!("createdAt" in setOnInsert)) setOnInsert.createdAt = now;
+					update.$setOnInsert = setOnInsert;
+				} else update.updatedAt = now;
+			});
 		}
 	};
 }
@@ -4374,6 +5072,7 @@ function validationChainPlugin(validators = [], options = {}) {
 	const validatorsByOperation = {
 		create: [],
 		update: [],
+		findOneAndUpdate: [],
 		delete: [],
 		createMany: []
 	};
@@ -4412,6 +5111,7 @@ function validationChainPlugin(validators = [], options = {}) {
 			repo.on("before:create", async (context) => runValidators("create", context));
 			repo.on("before:createMany", async (context) => runValidators("createMany", context));
 			repo.on("before:update", async (context) => runValidators("update", context));
+			repo.on("before:findOneAndUpdate", async (context) => runValidators("findOneAndUpdate", context));
 			repo.on("before:delete", async (context) => runValidators("delete", context));
 		}
 	};
@@ -4500,4 +5200,4 @@ function uniqueField(field, errorMessage) {
 	};
 }
 //#endregion
-export { AuditTrailQuery as A, cachePlugin as C, withTransaction as D, isTransactionUnsupported as E, auditLogPlugin as M, aggregateHelpersPlugin as N, AggregationBuilder as O, cascadePlugin as S, Repository as T, customIdPlugin as _, uniqueField as a, prefixedId as b, createTenantContext as c, observabilityPlugin as d, multiTenantPlugin as f, elasticSearchPlugin as g, fieldFilterPlugin as h, requireField as i, auditTrailPlugin as j, batchOperationsPlugin as k, subdocumentPlugin as l, methodRegistryPlugin as m, blockIf as n, validationChainPlugin as o, mongoOperationsPlugin as p, immutableField as r, timestampPlugin as s, autoInject as t, softDeletePlugin as u, dateSequentialId as v, HOOK_PRIORITY as w, sequentialId as x, getNextSequence as y };
+export { AuditTrailQuery as A, cachePlugin as C, withTransaction as D, isTransactionUnsupported as E, MUTATING_OPERATIONS as F, OP_REGISTRY as I, READ_OPERATIONS as L, auditLogPlugin as M, aggregateHelpersPlugin as N, AggregationBuilder as O, ALL_OPERATIONS as P, operationsByPolicyKey as R, cascadePlugin as S, Repository as T, customIdPlugin as _, uniqueField as a, prefixedId as b, createTenantContext as c, observabilityPlugin as d, multiTenantPlugin as f, elasticSearchPlugin as g, fieldFilterPlugin as h, requireField as i, auditTrailPlugin as j, batchOperationsPlugin as k, subdocumentPlugin as l, methodRegistryPlugin as m, blockIf as n, validationChainPlugin as o, mongoOperationsPlugin as p, immutableField as r, timestampPlugin as s, autoInject as t, softDeletePlugin as u, dateSequentialId as v, HOOK_PRIORITY$1 as w, sequentialId as x, getNextSequence as y };