@classytic/mongokit 3.15.0 → 3.16.0

package/dist/{validation-chain.plugin-CWhvBRej.mjs → validation-chain.plugin-Crl5nQAY.mjs}

@@ -1,76 +1,13 @@
 import { _ as upsert } from "./update-BXMnCvO6.mjs";
 import { n as warn } from "./logger-DprijP5h.mjs";
 import { t as createError } from "./error-B00pI7dV.mjs";
-import { l as OP_REGISTRY, s as ALL_OPERATIONS, t as HOOK_PRIORITY } from "./Repository-BGL1Pq8w.mjs";
-import { r as getFieldsForUser } from "./field-selection-Br3WPOEb.mjs";
+import { l as OP_REGISTRY, s as ALL_OPERATIONS, t as HOOK_PRIORITY } from "./Repository-DE7D2QeS.mjs";
+import { r as getFieldsForUser } from "./field-selection-CQW3WBiK.mjs";
 import mongoose from "mongoose";
 import { cachePlugin } from "@classytic/repo-core/cache";
 import { adminBypass, payloadHasTenantField } from "@classytic/repo-core/plugins";
+import { throwIfAborted, withRetry } from "@classytic/repo-core/repository";
 import { AsyncLocalStorage } from "node:async_hooks";
-//#region src/plugins/aggregate-helpers.plugin.ts
-/**
-* Aggregate helpers plugin
-*
-* @example
-* const repo = new Repository(Model, [
-*   methodRegistryPlugin(),
-*   aggregateHelpersPlugin(),
-* ]);
-*
-* const groups = await repo.groupBy('category');
-* const total = await repo.sum('amount', { status: 'completed' });
-*/
-function aggregateHelpersPlugin() {
-	return {
-		name: "aggregate-helpers",
-		apply(repo) {
-			if (!repo.registerMethod) throw new Error("aggregateHelpersPlugin requires methodRegistryPlugin");
-			/**
-			* Group by field
-			*/
-			repo.registerMethod("groupBy", async function(field, options = {}) {
-				const pipeline = [{ $group: {
-					_id: `$${field}`,
-					count: { $sum: 1 }
-				} }, { $sort: { count: -1 } }];
-				if (options.limit) pipeline.push({ $limit: options.limit });
-				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.aggregatePipeline(pipeline, options))[0]?.[resultKey] || 0;
-			};
-			/**
-			* Sum field values
-			*/
-			repo.registerMethod("sum", async function(field, query = {}, options = {}) {
-				return aggregateOperation.call(this, field, "$sum", "total", query, options);
-			});
-			/**
-			* Average field values
-			*/
-			repo.registerMethod("average", async function(field, query = {}, options = {}) {
-				return aggregateOperation.call(this, field, "$avg", "avg", query, options);
-			});
-			/**
-			* Get minimum value
-			*/
-			repo.registerMethod("min", async function(field, query = {}, options = {}) {
-				return aggregateOperation.call(this, field, "$min", "min", query, options);
-			});
-			/**
-			* Get maximum value
-			*/
-			repo.registerMethod("max", async function(field, query = {}, options = {}) {
-				return aggregateOperation.call(this, field, "$max", "max", query, options);
-			});
-		}
-	};
-}
-//#endregion
 //#region src/plugins/audit-log.plugin.ts
 /**
 * Audit log plugin that logs all repository operations
@@ -628,496 +565,1120 @@ function batchOperationsPlugin() {
 	};
 }
 //#endregion
-//#region src/plugins/cascade.plugin.ts
+//#region src/plugins/custom-id.plugin.ts
 /**
-* Cascade Delete Plugin
+* Custom ID Plugin
 *
-* Automatically deletes related documents when a parent document is deleted.
+* Generates custom document IDs using pluggable generators.
+* Supports atomic counters for sequential IDs (e.g., INV-2026-0001),
+* date-partitioned sequences, and fully custom generators.
 *
-* Two routing modes per relation:
+* Uses MongoDB's atomic `findOneAndUpdate` with `$inc` on a dedicated
+* counters collection — guaranteeing no duplicate IDs under concurrency.
 *
-*   1. **Repo-routed (preferred)** — pass `repo: targetRepo` on the relation.
-*      Cascade calls `targetRepo.delete(id, { mode })` / `targetRepo.deleteMany(
-*      query, { mode })`, so the target's `before:delete` / `before:deleteMany`
-*      hooks fire. Multi-tenant scoping, audit logging, cache invalidation,
-*      and the target's own `softDeletePlugin` (with its configured
-*      `deletedField`) all run correctly.
+* @example Basic sequential counter
+* ```typescript
+* const invoiceRepo = new Repository(InvoiceModel, [
+*   customIdPlugin({
+*     field: 'invoiceNumber',
+*     generator: sequentialId({
+*       prefix: 'INV',
+*       model: InvoiceModel,
+*     }),
+*   }),
+* ]);
 *
-*   2. **Model-routed (legacy)** — pass `model: 'TargetModelName'`. Cascade
-*      writes directly via `mongoose.models[name].updateMany / deleteMany`,
-*      **bypassing** the target's hooks. Safe only for trivial targets with
-*      no policy plugins. Retained for backwards compatibility — prefer the
-*      repo-routed form for new code.
+* const inv = await invoiceRepo.create({ amount: 100 });
+* // inv.invoiceNumber → "INV-0001"
+* ```
 *
-* The parent's delete mode propagates: a hard-deleted parent cascades hard,
-* a soft-deleted parent cascades soft — unless `relation.softDelete` overrides
-* the decision per-relation.
+* @example Date-partitioned counter (resets monthly)
+* ```typescript
+* const billRepo = new Repository(BillModel, [
+*   customIdPlugin({
+*     field: 'billNumber',
+*     generator: dateSequentialId({
+*       prefix: 'BILL',
+*       model: BillModel,
+*       partition: 'monthly',
+*       separator: '-',
+*       padding: 4,
+*     }),
+*   }),
+* ]);
 *
-* @example Repo-routed (new)
-* ```ts
-* const productRepo = new Repository(Product, [
-*   methodRegistryPlugin(),
-*   cascadePlugin({
-*     relations: [
-*       { repo: stockEntryRepo,    foreignKey: 'product' },
-*       { repo: stockMovementRepo, foreignKey: 'product' },
-*     ],
+* const bill = await billRepo.create({ total: 250 });
+* // bill.billNumber → "BILL-2026-02-0001"
+* ```
+*
+* @example Custom generator function
+* ```typescript
+* const orderRepo = new Repository(OrderModel, [
+*   customIdPlugin({
+*     field: 'orderRef',
+*     generator: async (context) => {
+*       const region = context.data?.region || 'US';
+*       const seq = await getNextSequence('orders');
+*       return `ORD-${region}-${seq}`;
+*     },
 *   }),
 * ]);
 * ```
+*/
+/** Schema for the internal counters collection */
+const counterSchema = new mongoose.Schema({
+	_id: {
+		type: String,
+		required: true
+	},
+	seq: {
+		type: Number,
+		default: 0
+	}
+}, {
+	collection: "_mongokit_counters",
+	versionKey: false
+});
+/**
+* Get or create the Counter model on the given connection.
+* Falls back to the default mongoose connection if none is provided.
+* Lazy-init to avoid model registration errors if mongoose isn't connected yet.
+*/
+function getCounterModel(connection) {
+	const conn = connection ?? mongoose.connection;
+	if (conn.models._MongoKitCounter) return conn.models._MongoKitCounter;
+	return conn.model("_MongoKitCounter", counterSchema);
+}
+/**
+* Atomically increment and return the next sequence value for a given key.
+* Uses `findOneAndUpdate` with `upsert` + `$inc` — fully atomic even under
+* heavy concurrency.
 *
-* @example Model-routed (legacy)
-* ```ts
-* cascadePlugin({
-*   relations: [
-*     { model: 'StockEntry', foreignKey: 'product' },
-*   ],
+* @param counterKey - Unique key identifying this counter (e.g., "Invoice" or "Invoice:2026-02")
+* @param increment - Value to increment by (default: 1)
+* @param connection - Mongoose connection to use (defaults to the default connection)
+* @param session - Optional client session. When provided, the counter bump
+*   participates in the caller's transaction — if the surrounding transaction
+*   aborts, the counter does NOT advance. Without a session, the bump commits
+*   immediately and is not rolled back if a sibling write fails.
+* @returns The next sequence number (after increment)
+*
+* @example
+* const seq = await getNextSequence('invoices');
+* // First call → 1, second → 2, ...
+*
+* @example Batch increment for createMany
+* const startSeq = await getNextSequence('invoices', 5);
+* // If current was 10, returns 15 (you use 11, 12, 13, 14, 15)
+*
+* @example Transactional counter bump
+* await withTransaction(conn, async (session) => {
+*   const seq = await getNextSequence('invoices', 1, conn, session);
+*   await invoiceRepo.create({ invoiceNumber: `INV-${seq}` }, { session });
+*   // if this throws, the counter is rolled back with the insert
 * });
-* ```
 */
+async function getNextSequence(counterKey, increment = 1, connection, session) {
+	const result = await getCounterModel(connection).findOneAndUpdate({ _id: counterKey }, { $inc: { seq: increment } }, {
+		upsert: true,
+		returnDocument: "after",
+		session
+	});
+	if (!result) throw new Error(`Failed to increment counter '${counterKey}'`);
+	return result.seq;
+}
 /**
-* Collect top-level parent-context fields that a target plugin (multi-tenant,
-* audit) will likely need. We can't know the target's contextKey, so we
-* forward a well-known allow-list: `organizationId`, `tenantId`, and `user`.
-* These are the conventions enforced by the built-in plugins.
+* Generator: Simple sequential counter.
+* Produces IDs like `INV-0001`, `INV-0002`, etc.
+*
+* Uses atomic MongoDB counters — safe under concurrency.
+*
+* @example
+* ```typescript
+* customIdPlugin({
+*   field: 'invoiceNumber',
+*   generator: sequentialId({ prefix: 'INV', model: InvoiceModel }),
+* })
+* ```
 */
-function collectScopeForward(context) {
-	const out = {};
-	if (context.organizationId !== void 0) out.organizationId = context.organizationId;
-	if (context.tenantId !== void 0) out.tenantId = context.tenantId;
-	if (context.user !== void 0) out.user = context.user;
-	return out;
+function sequentialId(options) {
+	const { prefix, model, padding = 4, separator = "-", counterKey } = options;
+	const key = counterKey || model.modelName;
+	return async (context) => {
+		const seq = await getNextSequence(key, 1, context._counterConnection, context.session);
+		return `${prefix}${separator}${String(seq).padStart(padding, "0")}`;
+	};
 }
 /**
-* Cascade delete plugin.
+* Generator: Date-partitioned sequential counter.
+* Counter resets per period — great for invoice/bill numbering.
+*
+* Produces IDs like:
+* - yearly:  `BILL-2026-0001`
+* - monthly: `BILL-2026-02-0001`
+* - daily:   `BILL-2026-02-20-0001`
+*
+* @example
+* ```typescript
+* customIdPlugin({
+*   field: 'billNumber',
+*   generator: dateSequentialId({
+*     prefix: 'BILL',
+*     model: BillModel,
+*     partition: 'monthly',
+*   }),
+* })
+* ```
 */
-function cascadePlugin(options) {
-	const { relations, parallel = true, logger } = options;
-	if (!relations || relations.length === 0) throw new Error("cascadePlugin requires at least one relation");
-	for (const rel of relations) {
-		if (!rel.repo && !rel.model) throw new Error("cascadePlugin: each relation needs either `repo` (preferred) or `model` (legacy)");
-		if (!rel.foreignKey) throw new Error("cascadePlugin: each relation needs `foreignKey`");
-	}
-	return {
-		name: "cascade",
-		apply(repo) {
-			repo.on("after:delete", async (payload) => {
-				const { context } = payload;
-				const deletedId = context.id;
-				if (!deletedId) {
-					logger?.warn?.("Cascade delete skipped: no document ID in context", { model: context.model });
-					return;
-				}
-				const isSoftParent = context.softDeleted === true;
-				const scopeForward = collectScopeForward(context);
-				const cascadeOne = async (relation) => {
-					const shouldSoftDelete = relation.softDelete ?? isSoftParent;
-					const cascadeCtx = {
-						targetModelName: relation.repo ? relation.repo.Model?.modelName ?? "<unknown>" : relation.model ?? "<unknown>",
-						session: context.session,
-						shouldSoftDelete,
-						user: context.user,
-						scopeForward
-					};
-					try {
-						if (relation.repo) await cascadeViaRepoBulk(relation, deletedId, cascadeCtx);
-						else await cascadeViaLegacyModel(relation, deletedId, cascadeCtx, logger);
-					} catch (error) {
-						logger?.error?.(`Cascade delete failed for '${cascadeCtx.targetModelName}'`, {
-							parentModel: context.model,
-							parentId: String(deletedId),
-							relatedModel: cascadeCtx.targetModelName,
-							foreignKey: relation.foreignKey,
-							error: error.message
-						});
-						throw error;
-					}
-				};
-				await runCascades(relations, cascadeOne, parallel);
-			});
-			repo.on("before:deleteMany", async (context) => {
-				const query = context.query;
-				if (!query || Object.keys(query).length === 0) return;
-				const idField = repo.idField || "_id";
-				context._cascadeIds = (await repo.Model.find(query, { [idField]: 1 }).lean().session(context.session ?? null)).map((doc) => doc[idField]);
-			});
-			repo.on("after:deleteMany", async (payload) => {
-				const { context } = payload;
-				const ids = context._cascadeIds;
-				if (!ids || ids.length === 0) return;
-				const isSoftParent = context.softDeleted === true;
-				const scopeForward = collectScopeForward(context);
-				const cascadeBulk = async (relation) => {
-					const shouldSoftDelete = relation.softDelete ?? isSoftParent;
-					const cascadeCtx = {
-						targetModelName: relation.repo ? relation.repo.Model?.modelName ?? "<unknown>" : relation.model ?? "<unknown>",
-						session: context.session,
-						shouldSoftDelete,
-						user: context.user,
-						scopeForward
-					};
-					try {
-						if (relation.repo) await cascadeViaRepoBulkMany(relation, ids, cascadeCtx);
-						else await cascadeViaLegacyModelMany(relation, ids, cascadeCtx, logger);
-					} catch (error) {
-						logger?.error?.(`Cascade deleteMany failed for '${cascadeCtx.targetModelName}'`, {
-							parentModel: context.model,
-							relatedModel: cascadeCtx.targetModelName,
-							foreignKey: relation.foreignKey,
-							error: error.message
-						});
-						throw error;
-					}
-				};
-				await runCascades(relations, cascadeBulk, parallel);
-			});
+function dateSequentialId(options) {
+	const { prefix, model, partition = "monthly", padding = 4, separator = "-" } = options;
+	return async (context) => {
+		const now = /* @__PURE__ */ new Date();
+		const year = String(now.getFullYear());
+		const month = String(now.getMonth() + 1).padStart(2, "0");
+		const day = String(now.getDate()).padStart(2, "0");
+		let datePart;
+		let counterKey;
+		switch (partition) {
+			case "yearly":
+				datePart = year;
+				counterKey = `${model.modelName}:${year}`;
+				break;
+			case "daily":
+				datePart = `${year}${separator}${month}${separator}${day}`;
+				counterKey = `${model.modelName}:${year}-${month}-${day}`;
+				break;
+			default:
+				datePart = `${year}${separator}${month}`;
+				counterKey = `${model.modelName}:${year}-${month}`;
+				break;
 		}
+		const seq = await getNextSequence(counterKey, 1, context._counterConnection, context.session);
+		return `${prefix}${separator}${datePart}${separator}${String(seq).padStart(padding, "0")}`;
 	};
 }
 /**
-* Repo-routed cascade for a single parent delete.
-* Calls `repo.deleteMany({ [fk]: parentId }, { mode })` — respects all target
-* hooks (multi-tenant, audit, target's own soft-delete plugin).
-*/
-async function cascadeViaRepoBulk(relation, parentId, ctx) {
-	const targetRepo = relation.repo;
-	if (typeof targetRepo.deleteMany !== "function") throw new Error(`cascadePlugin: target repo for '${ctx.targetModelName}' is missing deleteMany(). Ensure the target is a mongokit Repository or implements the StandardRepo deleteMany contract.`);
-	await targetRepo.deleteMany({ [relation.foreignKey]: parentId }, {
-		...ctx.scopeForward,
-		mode: ctx.shouldSoftDelete ? "soft" : "hard",
-		session: ctx.session
-	});
-}
-/**
-* Repo-routed cascade for a bulk parent deleteMany — `$in` over snapshot ids.
-*/
-async function cascadeViaRepoBulkMany(relation, parentIds, ctx) {
-	const targetRepo = relation.repo;
-	if (typeof targetRepo.deleteMany !== "function") throw new Error(`cascadePlugin: target repo for '${ctx.targetModelName}' is missing deleteMany(). Ensure the target is a mongokit Repository or implements the StandardRepo deleteMany contract.`);
-	await targetRepo.deleteMany({ [relation.foreignKey]: { $in: parentIds } }, {
-		...ctx.scopeForward,
-		mode: ctx.shouldSoftDelete ? "soft" : "hard",
-		session: ctx.session
-	});
-}
-/**
-* Legacy cascade via `mongoose.models[name]`. Bypasses target hooks.
-* Retained for backwards compatibility with existing cascadePlugin consumers.
-*/
-async function cascadeViaLegacyModel(relation, parentId, ctx, logger) {
-	const RelatedModel = mongoose.models[relation.model];
-	if (!RelatedModel) {
-		logger?.warn?.(`Cascade delete skipped: model '${relation.model}' not found`);
-		return;
-	}
-	const query = { [relation.foreignKey]: parentId };
-	if (ctx.shouldSoftDelete) await RelatedModel.updateMany(query, {
-		deletedAt: /* @__PURE__ */ new Date(),
-		...ctx.user ? { deletedBy: ctx.user._id || ctx.user.id } : {}
-	}, { session: ctx.session });
-	else await RelatedModel.deleteMany(query, { session: ctx.session });
-}
-async function cascadeViaLegacyModelMany(relation, parentIds, ctx, logger) {
-	const RelatedModel = mongoose.models[relation.model];
-	if (!RelatedModel) {
-		logger?.warn?.(`Cascade deleteMany skipped: model '${relation.model}' not found`);
-		return;
-	}
-	const query = { [relation.foreignKey]: { $in: parentIds } };
-	if (ctx.shouldSoftDelete) await RelatedModel.updateMany(query, {
-		deletedAt: /* @__PURE__ */ new Date(),
-		...ctx.user ? { deletedBy: ctx.user._id || ctx.user.id } : {}
-	}, { session: ctx.session });
-	else await RelatedModel.deleteMany(query, { session: ctx.session });
-}
-/**
-* Execute a list of cascade operations, honoring the `parallel` flag.
-* Uses `allSettled` so one failure doesn't abort siblings; throws the first
-* rejection (with a composite message if several failed) after all complete.
+* Generator: Prefix + random alphanumeric suffix.
+* Does NOT require a database round-trip — purely in-memory.
+*
+* Produces IDs like: `USR_a7b3xk9m2p1q`
+*
+* Good for: user-facing IDs where ordering doesn't matter.
+* Not suitable for sequential numbering.
+*
+* @example
+* ```typescript
+* customIdPlugin({
+*   field: 'publicId',
+*   generator: prefixedId({ prefix: 'USR', length: 10 }),
+* })
+* ```
 */
-async function runCascades(relations, fn, parallel) {
-	if (parallel) {
-		const failures = (await Promise.allSettled(relations.map(fn))).filter((r) => r.status === "rejected");
-		if (failures.length) {
-			const err = failures[0].reason;
-			if (failures.length > 1) err.message = `${failures.length} cascade deletes failed. First: ${err.message}`;
-			throw err;
-		}
-	} else for (const relation of relations) await fn(relation);
+function prefixedId(options) {
+	const { prefix, separator = "_", length = 12 } = options;
+	const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
+	return (_context) => {
+		let result = "";
+		const bytes = new Uint8Array(length);
+		if (typeof globalThis.crypto?.getRandomValues === "function") {
+			globalThis.crypto.getRandomValues(bytes);
+			for (let i = 0; i < length; i++) result += chars[bytes[i] % 36];
+		} else for (let i = 0; i < length; i++) result += chars[Math.floor(Math.random() * 36)];
+		return `${prefix}${separator}${result}`;
+	};
 }
-//#endregion
-//#region src/plugins/custom-id.plugin.ts
 /**
-* Custom ID Plugin
-*
-* Generates custom document IDs using pluggable generators.
-* Supports atomic counters for sequential IDs (e.g., INV-2026-0001),
-* date-partitioned sequences, and fully custom generators.
+* Custom ID plugin — injects generated IDs into documents before creation.
 *
-* Uses MongoDB's atomic `findOneAndUpdate` with `$inc` on a dedicated
-* counters collection — guaranteeing no duplicate IDs under concurrency.
+* @param options - Configuration for ID generation
+* @returns Plugin instance
 *
-* @example Basic sequential counter
+* @example
 * ```typescript
+* import { Repository, customIdPlugin, sequentialId } from '@classytic/mongokit';
+*
 * const invoiceRepo = new Repository(InvoiceModel, [
 *   customIdPlugin({
 *     field: 'invoiceNumber',
-*     generator: sequentialId({
-*       prefix: 'INV',
-*       model: InvoiceModel,
-*     }),
+*     generator: sequentialId({ prefix: 'INV', model: InvoiceModel }),
 *   }),
 * ]);
 *
 * const inv = await invoiceRepo.create({ amount: 100 });
-* // inv.invoiceNumber → "INV-0001"
-* ```
-*
-* @example Date-partitioned counter (resets monthly)
-* ```typescript
-* const billRepo = new Repository(BillModel, [
-*   customIdPlugin({
-*     field: 'billNumber',
-*     generator: dateSequentialId({
-*       prefix: 'BILL',
-*       model: BillModel,
-*       partition: 'monthly',
-*       separator: '-',
-*       padding: 4,
-*     }),
-*   }),
-* ]);
-*
-* const bill = await billRepo.create({ total: 250 });
-* // bill.billNumber → "BILL-2026-02-0001"
-* ```
-*
-* @example Custom generator function
-* ```typescript
-* const orderRepo = new Repository(OrderModel, [
-*   customIdPlugin({
-*     field: 'orderRef',
-*     generator: async (context) => {
-*       const region = context.data?.region || 'US';
-*       const seq = await getNextSequence('orders');
-*       return `ORD-${region}-${seq}`;
-*     },
-*   }),
-* ]);
+* console.log(inv.invoiceNumber); // "INV-0001"
 * ```
 */
-/** Schema for the internal counters collection */
-const counterSchema = new mongoose.Schema({
-	_id: {
-		type: String,
-		required: true
-	},
-	seq: {
-		type: Number,
-		default: 0
-	}
-}, {
-	collection: "_mongokit_counters",
-	versionKey: false
-});
-/**
-* Get or create the Counter model on the given connection.
-* Falls back to the default mongoose connection if none is provided.
-* Lazy-init to avoid model registration errors if mongoose isn't connected yet.
-*/
-function getCounterModel(connection) {
-	const conn = connection ?? mongoose.connection;
-	if (conn.models._MongoKitCounter) return conn.models._MongoKitCounter;
-	return conn.model("_MongoKitCounter", counterSchema);
+function customIdPlugin(options) {
+	const fieldName = options.field || "customId";
+	const generateOnlyIfEmpty = options.generateOnlyIfEmpty !== false;
+	return {
+		name: "custom-id",
+		apply(repo) {
+			const repoConnection = repo.Model.db;
+			repo.on("before:create", async (context) => {
+				if (!context.data) return;
+				if (generateOnlyIfEmpty && context.data[fieldName]) return;
+				context._counterConnection = repoConnection;
+				context.data[fieldName] = await options.generator(context);
+			});
+			repo.on("before:createMany", async (context) => {
+				if (!context.dataArray) return;
+				context._counterConnection = repoConnection;
+				const docsNeedingIds = [];
+				for (const doc of context.dataArray) {
+					if (generateOnlyIfEmpty && doc[fieldName]) continue;
+					docsNeedingIds.push(doc);
+				}
+				if (docsNeedingIds.length === 0) return;
+				for (const doc of docsNeedingIds) doc[fieldName] = await options.generator({
+					...context,
+					data: doc
+				});
+			});
+		}
+	};
 }
+//#endregion
+//#region src/plugins/method-registry.plugin.ts
 /**
-* Atomically increment and return the next sequence value for a given key.
-* Uses `findOneAndUpdate` with `upsert` + `$inc` — fully atomic even under
-* heavy concurrency.
-*
-* @param counterKey - Unique key identifying this counter (e.g., "Invoice" or "Invoice:2026-02")
-* @param increment - Value to increment by (default: 1)
-* @param connection - Mongoose connection to use (defaults to the default connection)
-* @param session - Optional client session. When provided, the counter bump
-*   participates in the caller's transaction — if the surrounding transaction
-*   aborts, the counter does NOT advance. Without a session, the bump commits
-*   immediately and is not rolled back if a sibling write fails.
-* @returns The next sequence number (after increment)
-*
-* @example
-* const seq = await getNextSequence('invoices');
-* // First call → 1, second → 2, ...
-*
-* @example Batch increment for createMany
-* const startSeq = await getNextSequence('invoices', 5);
-* // If current was 10, returns 15 (you use 11, 12, 13, 14, 15)
-*
-* @example Transactional counter bump
-* await withTransaction(conn, async (session) => {
-*   const seq = await getNextSequence('invoices', 1, conn, session);
-*   await invoiceRepo.create({ invoiceNumber: `INV-${seq}` }, { session });
-*   // if this throws, the counter is rolled back with the insert
-* });
+* Method registry plugin that enables dynamic method registration
 */
-async function getNextSequence(counterKey, increment = 1, connection, session) {
-	const result = await getCounterModel(connection).findOneAndUpdate({ _id: counterKey }, { $inc: { seq: increment } }, {
-		upsert: true,
-		returnDocument: "after",
-		session
-	});
-	if (!result) throw new Error(`Failed to increment counter '${counterKey}'`);
-	return result.seq;
+function methodRegistryPlugin() {
+	return {
+		name: "method-registry",
+		apply(repo) {
+			const registeredMethods = [];
+			/**
+			* Register a new method on the repository instance
+			*/
+			repo.registerMethod = (name, fn) => {
+				if (repo[name]) throw new Error(`Cannot register method '${name}': Method already exists on repository. Choose a different name or use a plugin that doesn't conflict.`);
+				if (!name || typeof name !== "string") throw new Error("Method name must be a non-empty string");
+				if (typeof fn !== "function") throw new Error(`Method '${name}' must be a function`);
+				repo[name] = fn.bind(repo);
+				registeredMethods.push(name);
+				repo.emit("method:registered", {
+					name,
+					fn
+				});
+			};
+			/**
+			* Check if a method is registered
+			*/
+			repo.hasMethod = (name) => typeof repo[name] === "function";
+			/**
+			* Get list of all dynamically registered methods
+			*/
+			repo.getRegisteredMethods = () => [...registeredMethods];
+		}
+	};
 }
+//#endregion
+//#region src/plugins/multi-tenant.plugin.ts
 /**
-* Generator: Simple sequential counter.
-* Produces IDs like `INV-0001`, `INV-0002`, etc.
+* Multi-Tenant Plugin
 *
-* Uses atomic MongoDB counters — safe under concurrency.
+* Automatically injects tenant isolation filters into all queries.
+* Ensures data isolation by adding organizationId (or custom tenant field)
+* to every read and write operation.
+*
+* Uses HOOK_PRIORITY.POLICY (100) to ensure tenant filters are injected
+* BEFORE cache keys are computed (HOOK_PRIORITY.CACHE = 200).
 *
 * @example
 * ```typescript
-* customIdPlugin({
-*   field: 'invoiceNumber',
-*   generator: sequentialId({ prefix: 'INV', model: InvoiceModel }),
-* })
-* ```
-*/
-function sequentialId(options) {
-	const { prefix, model, padding = 4, separator = "-", counterKey } = options;
-	const key = counterKey || model.modelName;
-	return async (context) => {
-		const seq = await getNextSequence(key, 1, context._counterConnection, context.session);
-		return `${prefix}${separator}${String(seq).padStart(padding, "0")}`;
-	};
-}
-/**
-* Generator: Date-partitioned sequential counter.
-* Counter resets per period — great for invoice/bill numbering.
+* // Basic — scopes every operation by organizationId from context
+* const repo = new Repository(Invoice, [
+*   multiTenantPlugin({ tenantField: 'organizationId' }),
+* ]);
 *
-* Produces IDs like:
-* - yearly:  `BILL-2026-0001`
-* - monthly: `BILL-2026-02-0001`
-* - daily:   `BILL-2026-02-20-0001`
+* const invoices = await repo.getAll(
+*   { filters: { status: 'paid' } },
+*   { organizationId: 'org_123' }
+* );
+* // Actual query: { status: 'paid', organizationId: 'org_123' }
 *
-* @example
-* ```typescript
-* customIdPlugin({
-*   field: 'billNumber',
-*   generator: dateSequentialId({
-*     prefix: 'BILL',
-*     model: BillModel,
-*     partition: 'monthly',
+* // Super admin bypass — skip scoping based on context
+* const repo = new Repository(Invoice, [
+*   multiTenantPlugin({
+*     tenantField: 'organizationId',
+*     skipWhen: (context) => context.role === 'superadmin',
 *   }),
-* })
+* ]);
+*
+* // Admin sees all orgs
+* await repo.getAll({ page: 1, limit: 10 }, { role: 'superadmin' });
+*
+* // Automatic context — resolve tenant from AsyncLocalStorage
+* const repo = new Repository(Invoice, [
+*   multiTenantPlugin({
+*     tenantField: 'organizationId',
+*     resolveContext: () => asyncLocalStorage.getStore()?.tenantId,
+*   }),
+* ]);
 * ```
 */
-function dateSequentialId(options) {
-	const { prefix, model, partition = "monthly", padding = 4, separator = "-" } = options;
-	return async (context) => {
-		const now = /* @__PURE__ */ new Date();
-		const year = String(now.getFullYear());
-		const month = String(now.getMonth() + 1).padStart(2, "0");
-		const day = String(now.getDate()).padStart(2, "0");
-		let datePart;
-		let counterKey;
-		switch (partition) {
-			case "yearly":
-				datePart = year;
-				counterKey = `${model.modelName}:${year}`;
-				break;
-			case "daily":
-				datePart = `${year}${separator}${month}${separator}${day}`;
-				counterKey = `${model.modelName}:${year}-${month}-${day}`;
-				break;
-			default:
-				datePart = `${year}${separator}${month}`;
-				counterKey = `${model.modelName}:${year}-${month}`;
-				break;
+function multiTenantPlugin(options = {}) {
+	const { tenantField = "organizationId", contextKey = "organizationId", required = true, skipOperations = [], skipWhen, resolveContext, fieldType = "string", allowDataInjection = false, onMismatch = "throw" } = options;
+	const extraOps = [{
+		op: "getDeleted",
+		policyKey: "filters"
+	}];
+	return {
+		name: "multi-tenant",
+		apply(repo) {
+			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) => {
+					const perCallBypass = context.bypassTenant === true;
+					const callbackBypass = !perCallBypass && skipWhen?.(context, op) === true;
+					if (perCallBypass || callbackBypass) {
+						repo.emit("after:tenant-bypass", {
+							context,
+							operation: op,
+							reason: perCallBypass ? "option" : "callback"
+						});
+						return;
+					}
+					let tenantId = context[contextKey];
+					if (!tenantId && resolveContext) {
+						tenantId = resolveContext();
+						if (tenantId) context[contextKey] = tenantId;
+					}
+					if (!tenantId && allowDataInjection && payloadHasTenantField(context, policyKey, tenantField)) return;
+					if (!tenantId && required) throw new Error([
+						`[mongokit] Multi-tenant: Missing '${contextKey}' in context for '${op}'.`,
+						"",
+						"Three ways to provide it — pick the one that fits the call site:",
+						"",
+						`  1. Per-call:        repo.${op}(..., { ${contextKey}: '<id>' })`,
+						"  2. Ambient (ALS):   `createTenantContext()` + `resolveContext` —",
+						"                       wrap the request in `tenantContext.run({ tenantId }, fn)`,",
+						"                       then every repo call inside the closure inherits the",
+						"                       tenant with no options-bag plumbing. See",
+						"                       `createTenantContext` in @classytic/mongokit.",
+						"  3. Cross-tenant:    `bypassTenant: true` per-call (admin / migration /",
+						"                       support), or `skipWhen: adminBypass({...})` at plugin",
+						"                       construction for an always-on role-based bypass.",
+						"",
+						"Or set `required: false` if this collection is genuinely not tenant-scoped."
+					].join("\n"));
+					if (!tenantId) return;
+					const castId = fieldType === "objectId" ? new mongoose.Types.ObjectId(tenantId) : tenantId;
+					const assertTenantValue = (supplied, where) => {
+						if (onMismatch === "overwrite") return;
+						if (supplied === void 0 || supplied === null) return;
+						if ((typeof supplied !== "object" || supplied instanceof mongoose.Types.ObjectId) && String(supplied) === String(castId)) return;
+						throw new Error(`[mongokit] Multi-tenant: '${tenantField}' in ${where} for '${op}' does not match the resolved tenant scope ('${String(tenantId)}'). Caller-supplied cross-tenant values are rejected (fail-closed). For legitimate cross-tenant access use bypassTenant: true (per-call) or skipWhen (plugin-level) — both emit 'after:tenant-bypass' for audit. To restore the legacy silent-overwrite behavior, construct the plugin with onMismatch: 'overwrite'.`);
+					};
+					switch (policyKey) {
+						case "filters":
+							assertTenantValue(context.filters?.[tenantField], "filters");
+							context.filters = {
+								...context.filters,
+								[tenantField]: castId
+							};
+							break;
+						case "query":
+							assertTenantValue(context.query?.[tenantField], "query");
+							context.query = {
+								...context.query,
+								[tenantField]: castId
+							};
+							break;
+						case "data":
+							if (context.data) {
+								assertTenantValue(context.data[tenantField], "data");
+								context.data[tenantField] = castId;
+							}
+							break;
+						case "dataArray":
+							if (context.dataArray) {
+								for (const doc of context.dataArray) if (doc && typeof doc === "object") {
+									assertTenantValue(doc[tenantField], "dataArray");
+									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) {
+											assertTenantValue(opBody.filter[tenantField], `bulkWrite ${key}.filter`);
+											opBody.filter = {
+												...opBody.filter,
+												[tenantField]: castId
+											};
+										}
+									}
+									const insertBody = subOp.insertOne;
+									if (insertBody?.document) {
+										assertTenantValue(insertBody.document[tenantField], "bulkWrite insertOne.document");
+										insertBody.document[tenantField] = castId;
+									}
+								}
+							}
+							break;
+					}
+				}, { priority: HOOK_PRIORITY.POLICY });
+			}
+		}
+	};
+}
+/**
+* Build the canonical `skipWhen` callback for role-based tenant
+* bypass — replaces the hand-rolled
+* `(ctx) => ctx.role === 'superadmin'` callback that ~6 packages
+* across the classytic codebase carry as boilerplate. Eliminates the
+* "I forgot to include 'platform_admin'" drift class — the role
+* vocabulary lives in one place.
+*
+* **Composes with `bypassTenant: true` per-call**, doesn't replace
+* it. `bypassTenant` is the deliberate per-call form for migration
+* scripts and one-off admin queries; `adminBypass` is the
+* always-on role-based bypass for users whose JWT / session carries
+* a privileged role.
+*
+* **NOT a substitute for authentication or RBAC.** This factory only
+* answers "should the tenant scope hook fire for this call?" — it
+* does NOT validate that the caller is authenticated, that their
+* role claim is genuine, or that the requested operation is
+* permitted. Always run auth + RBAC before the call reaches the
+* repository layer; this is the LAST gate, not the only one.
+*
+* @example Single role
+* ```ts
+* import { adminBypass, multiTenantPlugin } from '@classytic/mongokit';
+*
+* const repo = new Repository(InvoiceModel, [
+*   multiTenantPlugin({
+*     tenantField: 'organizationId',
+*     skipWhen: adminBypass({ adminRoles: ['superadmin'] }),
+*   }),
+* ]);
+*
+* await repo.getAll({}, { role: 'superadmin' }); // sees all orgs
+* await repo.getAll({}, { role: 'user', organizationId: 'org-1' }); // scoped
+* ```
+*
+* @example Multiple admin roles + custom field name
+* ```ts
+* skipWhen: adminBypass({
+*   roleField: 'principalRole',                  // ctx.principalRole, not ctx.role
+*   adminRoles: ['superadmin', 'platform_admin', 'support'],
+* }),
+* ```
+*
+* @example Composing with custom logic
+* ```ts
+* // adminBypass for the role check, then your own additional logic:
+* const adminCheck = adminBypass({ adminRoles: ['superadmin'] });
+* skipWhen: (ctx, op) => adminCheck(ctx, op) || ctx.internalSystemFlag === true,
+* ```
+*
+* @param options.roleField - Path on the context to read the role
+*   from. Defaults to `'role'`. Top-level keys only — for nested
+*   shapes (e.g. `ctx.user.role`), wrap your own `(ctx) => …` callback
+*   instead.
+* @param options.adminRoles - Role values that grant the bypass. The
+*   factory does an exact-match `includes` check — case-sensitive,
+*   no fuzzy matching. Lowercase your role vocabulary upstream.
+* @returns A `skipWhen`-compatible callback `(ctx, op) → boolean`.
+*/
+function adminBypass$1(options) {
+	return adminBypass(options);
+}
+//#endregion
+//#region src/plugins/soft-delete.plugin.ts
+/**
+* Build the deletion-state filter for either side of the soft-delete
+* boundary. One parameterized helper covers both directions so the two
+* predicates can't drift:
+*
+*   - `'live'`: docs NOT soft-deleted — `null` mode matches
+*     `{ field: null }` (works with `default: null` schemas), `'exists'`
+*     mode matches `{ field: { $exists: false } }` (legacy behavior).
+*   - `'deleted'`: docs that ARE soft-deleted — the exact complement of
+*     the corresponding `'live'` predicate in each mode.
+*/
+function buildDeletionStateFilter(deletedField, filterMode, state) {
+	if (filterMode === "exists") return state === "live" ? { [deletedField]: { $exists: false } } : { [deletedField]: {
+		$exists: true,
+		$ne: null
+	} };
+	return state === "live" ? { [deletedField]: null } : { [deletedField]: { $ne: null } };
+}
+/**
+* Live-docs filter honoring the per-call `includeDeleted` escape hatch
+* (returns an empty filter — no deletion-state predicate at all).
+*/
+function buildDeletedFilter(deletedField, filterMode, includeDeleted) {
+	if (includeDeleted) return {};
+	return buildDeletionStateFilter(deletedField, filterMode, "live");
+}
+/**
+* Soft delete plugin
+*
+* @example Basic usage
+* ```typescript
+* const repo = new Repository(Model, [
+*   softDeletePlugin({ deletedField: 'deletedAt' })
+* ]);
+*
+* // Delete (soft)
+* await repo.delete(id);
+*
+* // Restore
+* await repo.restore(id);
+*
+* // Get deleted documents
+* await repo.getDeleted({ page: 1, limit: 20 });
+* ```
+*
+* @example With null filter mode (for schemas with default: null)
+* ```typescript
+* // Schema: { deletedAt: { type: Date, default: null } }
+* const repo = new Repository(Model, [
+*   softDeletePlugin({
+*     deletedField: 'deletedAt',
+*     filterMode: 'null', // default - works with default: null
+*   })
+* ]);
+* ```
+*
+* @example With TTL for auto-cleanup
+* ```typescript
+* const repo = new Repository(Model, [
+*   softDeletePlugin({
+*     deletedField: 'deletedAt',
+*     ttlDays: 30, // Auto-delete after 30 days
+*   })
+* ]);
+* ```
+*/
+function softDeletePlugin(options = {}) {
+	const deletedField = options.deletedField || "deletedAt";
+	const deletedByField = options.deletedByField || "deletedBy";
+	const filterMode = options.filterMode || "null";
+	const addRestoreMethod = options.addRestoreMethod !== false;
+	const addGetDeletedMethod = options.addGetDeletedMethod !== false;
+	const ttlDays = options.ttlDays;
+	return {
+		name: "softDelete",
+		apply(repo) {
+			try {
+				const schemaPaths = repo.Model.schema.paths;
+				for (const [pathName, schemaType] of Object.entries(schemaPaths)) {
+					if (pathName === "_id" || pathName === deletedField) continue;
+					if (schemaType.options?.unique) warn(`[softDeletePlugin] Field '${pathName}' on model '${repo.Model.modelName}' has a unique index. With soft-delete enabled, deleted documents will block new documents with the same '${pathName}'. Fix: change to a compound partial index — { ${pathName}: 1 }, { unique: true, partialFilterExpression: { ${deletedField}: null } }`);
+				}
+			} catch (err) {
+				warn(`[softDeletePlugin] Schema introspection failed for ${repo.Model.modelName}: ${err instanceof Error ? err.message : String(err)}`);
+			}
+			if (ttlDays !== void 0 && ttlDays > 0) {
+				const ttlSeconds = ttlDays * 24 * 60 * 60;
+				repo.Model.collection.createIndex({ [deletedField]: 1 }, {
+					expireAfterSeconds: ttlSeconds,
+					partialFilterExpression: { [deletedField]: { $type: "date" } }
+				}).catch((err) => {
+					if (err.code !== 85 && err.code !== 86 && !err.message.includes("already exists")) warn(`[softDeletePlugin] Failed to create TTL index: ${err.message}`);
+				});
+			}
+			repo.on("before:delete", async (context) => {
+				if (context.deleteMode === "hard") return;
+				if (options.soft !== false) {
+					const updateData = { [deletedField]: /* @__PURE__ */ new Date() };
+					if (context.user) updateData[deletedByField] = context.user._id || context.user.id;
+					const deleteQuery = {
+						[repo.idField || "_id"]: context.id,
+						...context.query || {}
+					};
+					const signal = context.signal;
+					const retryPolicy = context.retryPolicy;
+					throwIfAborted(signal);
+					if (!await withRetry(() => repo.Model.findOneAndUpdate(deleteQuery, updateData, { session: context.session }), retryPolicy, signal)) {
+						const error = /* @__PURE__ */ new Error(`Document with id '${context.id}' not found`);
+						error.status = 404;
+						throw error;
+					}
+					context.softDeleted = true;
+				}
+			}, { priority: HOOK_PRIORITY.POLICY });
+			const injectDeleteFilterToFilters = (context) => {
+				if (options.soft !== false) {
+					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
+					if (Object.keys(deleteFilter).length > 0) context.filters = {
+						...context.filters || {},
+						...deleteFilter
+					};
+				}
+			};
+			const injectDeleteFilterToQuery = (context) => {
+				if (options.soft !== false) {
+					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
+					if (Object.keys(deleteFilter).length > 0) context.query = {
+						...context.query || {},
+						...deleteFilter
+					};
+				}
+			};
+			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.POLICY });
+				else if (desc.policyKey === "query") repo.on(`before:${op}`, injectDeleteFilterToQuery, { priority: HOOK_PRIORITY.POLICY });
+			}
+			repo.on("before:updateMany", (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:deleteMany", async (context) => {
+				if (context.deleteMode === "hard") return;
+				if (options.soft !== false) {
+					const deleteFilter = buildDeletedFilter(deletedField, filterMode, false);
+					const finalQuery = {
+						...context.query || {},
+						...deleteFilter
+					};
+					const signal = context.signal;
+					const retryPolicy = context.retryPolicy;
+					throwIfAborted(signal);
+					const updateRes = await withRetry(() => repo.Model.updateMany(finalQuery, { $set: { [deletedField]: /* @__PURE__ */ new Date() } }, { session: context.session }), retryPolicy, signal);
+					context.softDeleted = true;
+					context.softDeletedCount = updateRes?.modifiedCount ?? 0;
+				}
+			}, { priority: HOOK_PRIORITY.POLICY });
+			if (addRestoreMethod) {
+				const restoreMethod = async function(id, restoreOptions = {}) {
+					const context = await this._buildContext("restore", {
+						id,
+						...restoreOptions
+					});
+					const updateData = {
+						[deletedField]: null,
+						[deletedByField]: null
+					};
+					const restoreQuery = {
+						_id: id,
+						...context.query || {}
+					};
+					const result = await this.Model.findOneAndUpdate(restoreQuery, { $set: updateData }, {
+						returnDocument: "after",
+						session: restoreOptions.session
+					});
+					if (!result) {
+						const error = /* @__PURE__ */ new Error(`Document with id '${id}' not found`);
+						error.status = 404;
+						throw error;
+					}
+					await this.emitAsync("after:restore", {
+						context,
+						result
+					});
+					return result;
+				};
+				if (typeof repo.registerMethod === "function") repo.registerMethod("restore", restoreMethod);
+				else repo.restore = restoreMethod.bind(repo);
+			}
+			if (addGetDeletedMethod) {
+				const getDeletedMethod = async function(params = {}, getDeletedOptions = {}) {
+					const context = await this._buildContext("getDeleted", {
+						...params,
+						...getDeletedOptions
+					});
+					const deletedFilter = buildDeletionStateFilter(deletedField, filterMode, "deleted");
+					const combinedFilters = {
+						...params.filters || {},
+						...deletedFilter,
+						...context.filters || {},
+						...context.query || {}
+					};
+					const page = params.page || 1;
+					const limit = params.limit || 20;
+					const skip = (page - 1) * limit;
+					let sortSpec = { [deletedField]: -1 };
+					if (params.sort) if (typeof params.sort === "string") {
+						const sortOrder = params.sort.startsWith("-") ? -1 : 1;
+						sortSpec = { [params.sort.startsWith("-") ? params.sort.substring(1) : params.sort]: sortOrder };
+					} else sortSpec = params.sort;
+					let query = this.Model.find(combinedFilters).sort(sortSpec).skip(skip).limit(limit);
+					if (getDeletedOptions.session) query = query.session(getDeletedOptions.session);
+					if (getDeletedOptions.select) {
+						const selectValue = Array.isArray(getDeletedOptions.select) ? getDeletedOptions.select.join(" ") : getDeletedOptions.select;
+						query = query.select(selectValue);
+					}
+					if (getDeletedOptions.populate) {
+						const populateSpec = getDeletedOptions.populate;
+						if (typeof populateSpec === "string") query = query.populate(populateSpec.split(",").map((p) => p.trim()));
+						else if (Array.isArray(populateSpec)) query = query.populate(populateSpec);
+						else query = query.populate(populateSpec);
+					}
+					if (getDeletedOptions.lean !== false) query = query.lean();
+					const [data, total] = await Promise.all([query.exec(), this.Model.countDocuments(combinedFilters)]);
+					const pages = Math.ceil(total / limit);
+					return {
+						method: "offset",
+						data,
+						page,
+						limit,
+						total,
+						pages,
+						hasNext: page < pages,
+						hasPrev: page > 1
+					};
+				};
+				if (typeof repo.registerMethod === "function") repo.registerMethod("getDeleted", getDeletedMethod);
+				else repo.getDeleted = getDeletedMethod.bind(repo);
+			}
+		}
+	};
+}
+//#endregion
+//#region src/plugins/timestamp.plugin.ts
+/**
+* Timestamp plugin that auto-injects timestamps
+*
+* @example
+* const repo = new Repository(Model, [timestampPlugin()]);
+*/
+function timestampPlugin() {
+	return {
+		name: "timestamp",
+		apply(repo) {
+			repo.on("before:create", (context) => {
+				if (!context.data) return;
+				const now = /* @__PURE__ */ new Date();
+				if (!context.data.createdAt) context.data.createdAt = now;
+				if (!context.data.updatedAt) context.data.updatedAt = now;
+			});
+			repo.on("before:update", (context) => {
+				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;
+			});
+		}
+	};
+}
+//#endregion
+//#region src/plugins/aggregate-helpers.plugin.ts
+/**
+* Aggregate helpers plugin
+*
+* @example
+* const repo = new Repository(Model, [
+*   methodRegistryPlugin(),
+*   aggregateHelpersPlugin(),
+* ]);
+*
+* const groups = await repo.groupBy('category');
+* const total = await repo.sum('amount', { status: 'completed' });
+*/
+function aggregateHelpersPlugin() {
+	return {
+		name: "aggregate-helpers",
+		apply(repo) {
+			if (!repo.registerMethod) throw new Error("aggregateHelpersPlugin requires methodRegistryPlugin");
+			/**
+			* Group by field
+			*/
+			repo.registerMethod("groupBy", async function(field, options = {}) {
+				const pipeline = [{ $group: {
+					_id: `$${field}`,
+					count: { $sum: 1 }
+				} }, { $sort: { count: -1 } }];
+				if (options.limit) pipeline.push({ $limit: options.limit });
+				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.aggregatePipeline(pipeline, options))[0]?.[resultKey] || 0;
+			};
+			/**
+			* Sum field values
+			*/
+			repo.registerMethod("sum", async function(field, query = {}, options = {}) {
+				return aggregateOperation.call(this, field, "$sum", "total", query, options);
+			});
+			/**
+			* Average field values
+			*/
+			repo.registerMethod("average", async function(field, query = {}, options = {}) {
+				return aggregateOperation.call(this, field, "$avg", "avg", query, options);
+			});
+			/**
+			* Get minimum value
+			*/
+			repo.registerMethod("min", async function(field, query = {}, options = {}) {
+				return aggregateOperation.call(this, field, "$min", "min", query, options);
+			});
+			/**
+			* Get maximum value
+			*/
+			repo.registerMethod("max", async function(field, query = {}, options = {}) {
+				return aggregateOperation.call(this, field, "$max", "max", query, options);
+			});
 		}
-		const seq = await getNextSequence(counterKey, 1, context._counterConnection, context.session);
-		return `${prefix}${separator}${datePart}${separator}${String(seq).padStart(padding, "0")}`;
 	};
 }
+//#endregion
+//#region src/plugins/cascade.plugin.ts
 /**
-* Generator: Prefix + random alphanumeric suffix.
-* Does NOT require a database round-trip — purely in-memory.
+* Cascade Delete Plugin
 *
-* Produces IDs like: `USR_a7b3xk9m2p1q`
+* Automatically deletes related documents when a parent document is deleted.
 *
-* Good for: user-facing IDs where ordering doesn't matter.
-* Not suitable for sequential numbering.
+* Two routing modes per relation:
 *
-* @example
-* ```typescript
-* customIdPlugin({
-*   field: 'publicId',
-*   generator: prefixedId({ prefix: 'USR', length: 10 }),
-* })
-* ```
-*/
-function prefixedId(options) {
-	const { prefix, separator = "_", length = 12 } = options;
-	const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
-	return (_context) => {
-		let result = "";
-		const bytes = new Uint8Array(length);
-		if (typeof globalThis.crypto?.getRandomValues === "function") {
-			globalThis.crypto.getRandomValues(bytes);
-			for (let i = 0; i < length; i++) result += chars[bytes[i] % 36];
-		} else for (let i = 0; i < length; i++) result += chars[Math.floor(Math.random() * 36)];
-		return `${prefix}${separator}${result}`;
-	};
-}
-/**
-* Custom ID plugin — injects generated IDs into documents before creation.
+*   1. **Repo-routed (preferred)** — pass `repo: targetRepo` on the relation.
+*      Cascade calls `targetRepo.delete(id, { mode })` / `targetRepo.deleteMany(
+*      query, { mode })`, so the target's `before:delete` / `before:deleteMany`
+*      hooks fire. Multi-tenant scoping, audit logging, cache invalidation,
+*      and the target's own `softDeletePlugin` (with its configured
+*      `deletedField`) all run correctly.
 *
-* @param options - Configuration for ID generation
-* @returns Plugin instance
+*   2. **Model-routed (legacy)** — pass `model: 'TargetModelName'`. Cascade
+*      writes directly via `mongoose.models[name].updateMany / deleteMany`,
+*      **bypassing** the target's hooks. Safe only for trivial targets with
+*      no policy plugins. Retained for backwards compatibility — prefer the
+*      repo-routed form for new code.
 *
-* @example
-* ```typescript
-* import { Repository, customIdPlugin, sequentialId } from '@classytic/mongokit';
+* The parent's delete mode propagates: a hard-deleted parent cascades hard,
+* a soft-deleted parent cascades soft — unless `relation.softDelete` overrides
+* the decision per-relation.
 *
-* const invoiceRepo = new Repository(InvoiceModel, [
-*   customIdPlugin({
-*     field: 'invoiceNumber',
-*     generator: sequentialId({ prefix: 'INV', model: InvoiceModel }),
+* @example Repo-routed (new)
+* ```ts
+* const productRepo = new Repository(Product, [
+*   methodRegistryPlugin(),
+*   cascadePlugin({
+*     relations: [
+*       { repo: stockEntryRepo,    foreignKey: 'product' },
+*       { repo: stockMovementRepo, foreignKey: 'product' },
+*     ],
 *   }),
 * ]);
+* ```
 *
-* const inv = await invoiceRepo.create({ amount: 100 });
-* console.log(inv.invoiceNumber); // "INV-0001"
+* @example Model-routed (legacy)
+* ```ts
+* cascadePlugin({
+*   relations: [
+*     { model: 'StockEntry', foreignKey: 'product' },
+*   ],
+* });
 * ```
 */
-function customIdPlugin(options) {
-	const fieldName = options.field || "customId";
-	const generateOnlyIfEmpty = options.generateOnlyIfEmpty !== false;
+/**
+* Collect top-level parent-context fields that a target plugin (multi-tenant,
+* audit) will likely need. We can't know the target's contextKey, so we
+* forward a well-known allow-list: `organizationId`, `tenantId`, and `user`.
+* These are the conventions enforced by the built-in plugins.
+*/
+function collectScopeForward(context) {
+	const out = {};
+	if (context.organizationId !== void 0) out.organizationId = context.organizationId;
+	if (context.tenantId !== void 0) out.tenantId = context.tenantId;
+	if (context.user !== void 0) out.user = context.user;
+	return out;
+}
+/**
+* Cascade delete plugin.
+*/
+function cascadePlugin(options) {
+	const { relations, parallel = true, logger } = options;
+	if (!relations || relations.length === 0) throw new Error("cascadePlugin requires at least one relation");
+	for (const rel of relations) {
+		if (!rel.repo && !rel.model) throw new Error("cascadePlugin: each relation needs either `repo` (preferred) or `model` (legacy)");
+		if (!rel.foreignKey) throw new Error("cascadePlugin: each relation needs `foreignKey`");
+	}
 	return {
-		name: "custom-id",
+		name: "cascade",
 		apply(repo) {
-			const repoConnection = repo.Model.db;
-			repo.on("before:create", async (context) => {
-				if (!context.data) return;
-				if (generateOnlyIfEmpty && context.data[fieldName]) return;
-				context._counterConnection = repoConnection;
-				context.data[fieldName] = await options.generator(context);
-			});
-			repo.on("before:createMany", async (context) => {
-				if (!context.dataArray) return;
-				context._counterConnection = repoConnection;
-				const docsNeedingIds = [];
-				for (const doc of context.dataArray) {
-					if (generateOnlyIfEmpty && doc[fieldName]) continue;
-					docsNeedingIds.push(doc);
+			repo.on("after:delete", async (payload) => {
+				const { context } = payload;
+				const deletedId = context.id;
+				if (!deletedId) {
+					logger?.warn?.("Cascade delete skipped: no document ID in context", { model: context.model });
+					return;
 				}
-				if (docsNeedingIds.length === 0) return;
-				for (const doc of docsNeedingIds) doc[fieldName] = await options.generator({
-					...context,
-					data: doc
-				});
+				const isSoftParent = context.softDeleted === true;
+				const scopeForward = collectScopeForward(context);
+				const cascadeOne = async (relation) => {
+					const shouldSoftDelete = relation.softDelete ?? isSoftParent;
+					const cascadeCtx = {
+						targetModelName: relation.repo ? relation.repo.Model?.modelName ?? "<unknown>" : relation.model ?? "<unknown>",
+						session: context.session,
+						shouldSoftDelete,
+						user: context.user,
+						scopeForward
+					};
+					try {
+						if (relation.repo) await cascadeViaRepoBulk(relation, deletedId, cascadeCtx);
+						else await cascadeViaLegacyModel(relation, deletedId, cascadeCtx, logger);
+					} catch (error) {
+						logger?.error?.(`Cascade delete failed for '${cascadeCtx.targetModelName}'`, {
+							parentModel: context.model,
+							parentId: String(deletedId),
+							relatedModel: cascadeCtx.targetModelName,
+							foreignKey: relation.foreignKey,
+							error: error.message
+						});
+						throw error;
+					}
+				};
+				await runCascades(relations, cascadeOne, parallel);
+			});
+			repo.on("before:deleteMany", async (context) => {
+				const query = context.query;
+				if (!query || Object.keys(query).length === 0) return;
+				const idField = repo.idField || "_id";
+				context._cascadeIds = (await repo.Model.find(query, { [idField]: 1 }).lean().session(context.session ?? null)).map((doc) => doc[idField]);
+			});
+			repo.on("after:deleteMany", async (payload) => {
+				const { context } = payload;
+				const ids = context._cascadeIds;
+				if (!ids || ids.length === 0) return;
+				const isSoftParent = context.softDeleted === true;
+				const scopeForward = collectScopeForward(context);
+				const cascadeBulk = async (relation) => {
+					const shouldSoftDelete = relation.softDelete ?? isSoftParent;
+					const cascadeCtx = {
+						targetModelName: relation.repo ? relation.repo.Model?.modelName ?? "<unknown>" : relation.model ?? "<unknown>",
+						session: context.session,
+						shouldSoftDelete,
+						user: context.user,
+						scopeForward
+					};
+					try {
+						if (relation.repo) await cascadeViaRepoBulkMany(relation, ids, cascadeCtx);
+						else await cascadeViaLegacyModelMany(relation, ids, cascadeCtx, logger);
+					} catch (error) {
+						logger?.error?.(`Cascade deleteMany failed for '${cascadeCtx.targetModelName}'`, {
+							parentModel: context.model,
+							relatedModel: cascadeCtx.targetModelName,
+							foreignKey: relation.foreignKey,
+							error: error.message
+						});
+						throw error;
+					}
+				};
+				await runCascades(relations, cascadeBulk, parallel);
 			});
 		}
-	};
+	};
+}
+/**
+* Repo-routed cascade for a single parent delete.
+* Calls `repo.deleteMany({ [fk]: parentId }, { mode })` — respects all target
+* hooks (multi-tenant, audit, target's own soft-delete plugin).
+*/
+async function cascadeViaRepoBulk(relation, parentId, ctx) {
+	const targetRepo = relation.repo;
+	if (typeof targetRepo.deleteMany !== "function") throw new Error(`cascadePlugin: target repo for '${ctx.targetModelName}' is missing deleteMany(). Ensure the target is a mongokit Repository or implements the StandardRepo deleteMany contract.`);
+	await targetRepo.deleteMany({ [relation.foreignKey]: parentId }, {
+		...ctx.scopeForward,
+		mode: ctx.shouldSoftDelete ? "soft" : "hard",
+		session: ctx.session
+	});
+}
+/**
+* Repo-routed cascade for a bulk parent deleteMany — `$in` over snapshot ids.
+*/
+async function cascadeViaRepoBulkMany(relation, parentIds, ctx) {
+	const targetRepo = relation.repo;
+	if (typeof targetRepo.deleteMany !== "function") throw new Error(`cascadePlugin: target repo for '${ctx.targetModelName}' is missing deleteMany(). Ensure the target is a mongokit Repository or implements the StandardRepo deleteMany contract.`);
+	await targetRepo.deleteMany({ [relation.foreignKey]: { $in: parentIds } }, {
+		...ctx.scopeForward,
+		mode: ctx.shouldSoftDelete ? "soft" : "hard",
+		session: ctx.session
+	});
+}
+/**
+* Legacy cascade via `mongoose.models[name]`. Bypasses target hooks.
+* Retained for backwards compatibility with existing cascadePlugin consumers.
+*/
+async function cascadeViaLegacyModel(relation, parentId, ctx, logger) {
+	const RelatedModel = mongoose.models[relation.model];
+	if (!RelatedModel) {
+		logger?.warn?.(`Cascade delete skipped: model '${relation.model}' not found`);
+		return;
+	}
+	const query = { [relation.foreignKey]: parentId };
+	if (ctx.shouldSoftDelete) await RelatedModel.updateMany(query, {
+		deletedAt: /* @__PURE__ */ new Date(),
+		...ctx.user ? { deletedBy: ctx.user._id || ctx.user.id } : {}
+	}, { session: ctx.session });
+	else await RelatedModel.deleteMany(query, { session: ctx.session });
+}
+async function cascadeViaLegacyModelMany(relation, parentIds, ctx, logger) {
+	const RelatedModel = mongoose.models[relation.model];
+	if (!RelatedModel) {
+		logger?.warn?.(`Cascade deleteMany skipped: model '${relation.model}' not found`);
+		return;
+	}
+	const query = { [relation.foreignKey]: { $in: parentIds } };
+	if (ctx.shouldSoftDelete) await RelatedModel.updateMany(query, {
+		deletedAt: /* @__PURE__ */ new Date(),
+		...ctx.user ? { deletedBy: ctx.user._id || ctx.user.id } : {}
+	}, { session: ctx.session });
+	else await RelatedModel.deleteMany(query, { session: ctx.session });
+}
+/**
+* Execute a list of cascade operations, honoring the `parallel` flag.
+* Uses `allSettled` so one failure doesn't abort siblings; throws the first
+* rejection (with a composite message if several failed) after all complete.
+*/
+async function runCascades(relations, fn, parallel) {
+	if (parallel) {
+		const failures = (await Promise.allSettled(relations.map(fn))).filter((r) => r.status === "rejected");
+		if (failures.length) {
+			const err = failures[0].reason;
+			if (failures.length > 1) err.message = `${failures.length} cascade deletes failed. First: ${err.message}`;
+			throw err;
+		}
+	} else for (const relation of relations) await fn(relation);
 }
 //#endregion
 //#region src/plugins/elastic.plugin.ts
@@ -1301,41 +1862,6 @@ function leasePlugin(options = {}) {
 	};
 }
 //#endregion
-//#region src/plugins/method-registry.plugin.ts
-/**
-* Method registry plugin that enables dynamic method registration
-*/
-function methodRegistryPlugin() {
-	return {
-		name: "method-registry",
-		apply(repo) {
-			const registeredMethods = [];
-			/**
-			* Register a new method on the repository instance
-			*/
-			repo.registerMethod = (name, fn) => {
-				if (repo[name]) throw new Error(`Cannot register method '${name}': Method already exists on repository. Choose a different name or use a plugin that doesn't conflict.`);
-				if (!name || typeof name !== "string") throw new Error("Method name must be a non-empty string");
-				if (typeof fn !== "function") throw new Error(`Method '${name}' must be a function`);
-				repo[name] = fn.bind(repo);
-				registeredMethods.push(name);
-				repo.emit("method:registered", {
-					name,
-					fn
-				});
-			};
-			/**
-			* Check if a method is registered
-			*/
-			repo.hasMethod = (name) => typeof repo[name] === "function";
-			/**
-			* Get list of all dynamically registered methods
-			*/
-			repo.getRegisteredMethods = () => [...registeredMethods];
-		}
-	};
-}
-//#endregion
 //#region src/plugins/mongo-operations.plugin.ts
 /**
 * MongoDB Operations Plugin
@@ -1497,291 +2023,82 @@ function mongoOperationsPlugin() {
 			*   maxConcurrent,
 			* );
 			* if (!claimed) return; // already at limit; another caller won
-			* ```
-			*/
-			repo.registerMethod("incrementIfBelow", async function(id, field, ceiling, by = 1, options = {}) {
-				if (typeof ceiling !== "number") throw createError(400, "incrementIfBelow ceiling must be a number");
-				if (typeof by !== "number") throw createError(400, "incrementIfBelow `by` must be a number");
-				if (typeof field !== "string" || field.length === 0) throw createError(400, "incrementIfBelow field must be a non-empty string");
-				for (const segment of field.split(".")) {
-					if (segment.length === 0) throw createError(400, `incrementIfBelow field has an empty segment ("${field}")`);
-					if (segment.startsWith("$")) throw createError(400, `incrementIfBelow field segment cannot start with '$' ("${segment}") — Mongo would treat it as an operator`);
-					if (segment === "__proto__" || segment === "constructor" || segment === "prototype") throw createError(400, `incrementIfBelow field segment "${segment}" is reserved (prototype-pollution guard)`);
-				}
-				const idField = this.idField || "_id";
-				return this.findOneAndUpdate({
-					[idField]: id,
-					[field]: { $lt: ceiling }
-				}, { $inc: { [field]: by } }, {
-					...options,
-					returnDocument: "after"
-				});
-			});
-			/**
-			* Atomic update with multiple MongoDB operators in a single call
-			*
-			* Combines $inc, $set, $push, $pull, $addToSet, $unset, $setOnInsert, $min, $max, $mul, $rename
-			* into one atomic database operation.
-			*
-			* @example
-			* // Combine $inc + $set in one atomic call
-			* await repo.atomicUpdate(id, {
-			*   $inc: { views: 1, commentCount: 1 },
-			*   $set: { lastActiveAt: new Date() }
-			* });
-			*
-			* // Multiple operators: $inc + $set + $push
-			* await repo.atomicUpdate(id, {
-			*   $inc: { 'metrics.total': 1 },
-			*   $set: { updatedAt: new Date() },
-			*   $push: { history: { action: 'update', at: new Date() } }
-			* });
-			*
-			* // $push with $each modifier
-			* await repo.atomicUpdate(id, {
-			*   $push: { tags: { $each: ['featured', 'popular'] } },
-			*   $inc: { tagCount: 2 }
-			* });
-			*
-			* // With arrayFilters for positional updates
-			* await repo.atomicUpdate(id, {
-			*   $set: { 'items.$[elem].quantity': 5 }
-			* }, { arrayFilters: [{ 'elem._id': itemId }] });
-			*/
-			repo.registerMethod("atomicUpdate", async function(id, operators, options = {}) {
-				const validOperators = new Set([
-					"$inc",
-					"$set",
-					"$unset",
-					"$push",
-					"$pull",
-					"$addToSet",
-					"$pop",
-					"$rename",
-					"$min",
-					"$max",
-					"$mul",
-					"$setOnInsert",
-					"$bit",
-					"$currentDate"
-				]);
-				const keys = Object.keys(operators);
-				if (keys.length === 0) throw createError(400, "atomicUpdate requires at least one operator");
-				for (const key of keys) if (!validOperators.has(key)) throw createError(400, `Invalid update operator: '${key}'. Valid operators: ${[...validOperators].join(", ")}`);
-				return this.update(id, operators, options);
-			});
-		}
-	};
-}
-//#endregion
-//#region src/plugins/multi-tenant.plugin.ts
-/**
-* Multi-Tenant Plugin
-*
-* Automatically injects tenant isolation filters into all queries.
-* Ensures data isolation by adding organizationId (or custom tenant field)
-* to every read and write operation.
-*
-* Uses HOOK_PRIORITY.POLICY (100) to ensure tenant filters are injected
-* BEFORE cache keys are computed (HOOK_PRIORITY.CACHE = 200).
-*
-* @example
-* ```typescript
-* // Basic — scopes every operation by organizationId from context
-* const repo = new Repository(Invoice, [
-*   multiTenantPlugin({ tenantField: 'organizationId' }),
-* ]);
-*
-* const invoices = await repo.getAll(
-*   { filters: { status: 'paid' } },
-*   { organizationId: 'org_123' }
-* );
-* // Actual query: { status: 'paid', organizationId: 'org_123' }
-*
-* // Super admin bypass — skip scoping based on context
-* const repo = new Repository(Invoice, [
-*   multiTenantPlugin({
-*     tenantField: 'organizationId',
-*     skipWhen: (context) => context.role === 'superadmin',
-*   }),
-* ]);
-*
-* // Admin sees all orgs
-* await repo.getAll({ page: 1, limit: 10 }, { role: 'superadmin' });
-*
-* // Automatic context — resolve tenant from AsyncLocalStorage
-* const repo = new Repository(Invoice, [
-*   multiTenantPlugin({
-*     tenantField: 'organizationId',
-*     resolveContext: () => asyncLocalStorage.getStore()?.tenantId,
-*   }),
-* ]);
-* ```
-*/
-function multiTenantPlugin(options = {}) {
-	const { tenantField = "organizationId", contextKey = "organizationId", required = true, skipOperations = [], skipWhen, resolveContext, fieldType = "string", allowDataInjection = false } = options;
-	const extraOps = [{
-		op: "getDeleted",
-		policyKey: "filters"
-	}];
-	return {
-		name: "multi-tenant",
-		apply(repo) {
-			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) => {
-					const perCallBypass = context.bypassTenant === true;
-					const callbackBypass = !perCallBypass && skipWhen?.(context, op) === true;
-					if (perCallBypass || callbackBypass) {
-						repo.emit("after:tenant-bypass", {
-							context,
-							operation: op,
-							reason: perCallBypass ? "option" : "callback"
-						});
-						return;
-					}
-					let tenantId = context[contextKey];
-					if (!tenantId && resolveContext) {
-						tenantId = resolveContext();
-						if (tenantId) context[contextKey] = tenantId;
-					}
-					if (!tenantId && allowDataInjection && payloadHasTenantField(context, policyKey, tenantField)) return;
-					if (!tenantId && required) throw new Error([
-						`[mongokit] Multi-tenant: Missing '${contextKey}' in context for '${op}'.`,
-						"",
-						"Three ways to provide it — pick the one that fits the call site:",
-						"",
-						`  1. Per-call:        repo.${op}(..., { ${contextKey}: '<id>' })`,
-						"  2. Ambient (ALS):   `createTenantContext()` + `resolveContext` —",
-						"                       wrap the request in `tenantContext.run({ tenantId }, fn)`,",
-						"                       then every repo call inside the closure inherits the",
-						"                       tenant with no options-bag plumbing. See",
-						"                       `createTenantContext` in @classytic/mongokit.",
-						"  3. Cross-tenant:    `bypassTenant: true` per-call (admin / migration /",
-						"                       support), or `skipWhen: adminBypass({...})` at plugin",
-						"                       construction for an always-on role-based bypass.",
-						"",
-						"Or set `required: false` if this collection is genuinely not tenant-scoped."
-					].join("\n"));
-					if (!tenantId) return;
-					const castId = fieldType === "objectId" ? new mongoose.Types.ObjectId(tenantId) : tenantId;
-					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;
-								}
-							}
-							break;
-					}
-				}, { priority: HOOK_PRIORITY.POLICY });
-			}
+			* ```
+			*/
+			repo.registerMethod("incrementIfBelow", async function(id, field, ceiling, by = 1, options = {}) {
+				if (typeof ceiling !== "number") throw createError(400, "incrementIfBelow ceiling must be a number");
+				if (typeof by !== "number") throw createError(400, "incrementIfBelow `by` must be a number");
+				if (typeof field !== "string" || field.length === 0) throw createError(400, "incrementIfBelow field must be a non-empty string");
+				for (const segment of field.split(".")) {
+					if (segment.length === 0) throw createError(400, `incrementIfBelow field has an empty segment ("${field}")`);
+					if (segment.startsWith("$")) throw createError(400, `incrementIfBelow field segment cannot start with '$' ("${segment}") — Mongo would treat it as an operator`);
+					if (segment === "__proto__" || segment === "constructor" || segment === "prototype") throw createError(400, `incrementIfBelow field segment "${segment}" is reserved (prototype-pollution guard)`);
+				}
+				const idField = this.idField || "_id";
+				return this.findOneAndUpdate({
+					[idField]: id,
+					[field]: { $lt: ceiling }
+				}, { $inc: { [field]: by } }, {
+					...options,
+					returnDocument: "after"
+				});
+			});
+			/**
+			* Atomic update with multiple MongoDB operators in a single call
+			*
+			* Combines $inc, $set, $push, $pull, $addToSet, $unset, $setOnInsert, $min, $max, $mul, $rename
+			* into one atomic database operation.
+			*
+			* @example
+			* // Combine $inc + $set in one atomic call
+			* await repo.atomicUpdate(id, {
+			*   $inc: { views: 1, commentCount: 1 },
+			*   $set: { lastActiveAt: new Date() }
+			* });
+			*
+			* // Multiple operators: $inc + $set + $push
+			* await repo.atomicUpdate(id, {
+			*   $inc: { 'metrics.total': 1 },
+			*   $set: { updatedAt: new Date() },
+			*   $push: { history: { action: 'update', at: new Date() } }
+			* });
+			*
+			* // $push with $each modifier
+			* await repo.atomicUpdate(id, {
+			*   $push: { tags: { $each: ['featured', 'popular'] } },
+			*   $inc: { tagCount: 2 }
+			* });
+			*
+			* // With arrayFilters for positional updates
+			* await repo.atomicUpdate(id, {
+			*   $set: { 'items.$[elem].quantity': 5 }
+			* }, { arrayFilters: [{ 'elem._id': itemId }] });
+			*/
+			repo.registerMethod("atomicUpdate", async function(id, operators, options = {}) {
+				const validOperators = new Set([
+					"$inc",
+					"$set",
+					"$unset",
+					"$push",
+					"$pull",
+					"$addToSet",
+					"$pop",
+					"$rename",
+					"$min",
+					"$max",
+					"$mul",
+					"$setOnInsert",
+					"$bit",
+					"$currentDate"
+				]);
+				const keys = Object.keys(operators);
+				if (keys.length === 0) throw createError(400, "atomicUpdate requires at least one operator");
+				for (const key of keys) if (!validOperators.has(key)) throw createError(400, `Invalid update operator: '${key}'. Valid operators: ${[...validOperators].join(", ")}`);
+				return this.update(id, operators, options);
+			});
 		}
 	};
 }
-/**
-* Build the canonical `skipWhen` callback for role-based tenant
-* bypass — replaces the hand-rolled
-* `(ctx) => ctx.role === 'superadmin'` callback that ~6 packages
-* across the classytic codebase carry as boilerplate. Eliminates the
-* "I forgot to include 'platform_admin'" drift class — the role
-* vocabulary lives in one place.
-*
-* **Composes with `bypassTenant: true` per-call**, doesn't replace
-* it. `bypassTenant` is the deliberate per-call form for migration
-* scripts and one-off admin queries; `adminBypass` is the
-* always-on role-based bypass for users whose JWT / session carries
-* a privileged role.
-*
-* **NOT a substitute for authentication or RBAC.** This factory only
-* answers "should the tenant scope hook fire for this call?" — it
-* does NOT validate that the caller is authenticated, that their
-* role claim is genuine, or that the requested operation is
-* permitted. Always run auth + RBAC before the call reaches the
-* repository layer; this is the LAST gate, not the only one.
-*
-* @example Single role
-* ```ts
-* import { adminBypass, multiTenantPlugin } from '@classytic/mongokit';
-*
-* const repo = new Repository(InvoiceModel, [
-*   multiTenantPlugin({
-*     tenantField: 'organizationId',
-*     skipWhen: adminBypass({ adminRoles: ['superadmin'] }),
-*   }),
-* ]);
-*
-* await repo.getAll({}, { role: 'superadmin' }); // sees all orgs
-* await repo.getAll({}, { role: 'user', organizationId: 'org-1' }); // scoped
-* ```
-*
-* @example Multiple admin roles + custom field name
-* ```ts
-* skipWhen: adminBypass({
-*   roleField: 'principalRole',                  // ctx.principalRole, not ctx.role
-*   adminRoles: ['superadmin', 'platform_admin', 'support'],
-* }),
-* ```
-*
-* @example Composing with custom logic
-* ```ts
-* // adminBypass for the role check, then your own additional logic:
-* const adminCheck = adminBypass({ adminRoles: ['superadmin'] });
-* skipWhen: (ctx, op) => adminCheck(ctx, op) || ctx.internalSystemFlag === true,
-* ```
-*
-* @param options.roleField - Path on the context to read the role
-*   from. Defaults to `'role'`. Top-level keys only — for nested
-*   shapes (e.g. `ctx.user.role`), wrap your own `(ctx) => …` callback
-*   instead.
-* @param options.adminRoles - Role values that grant the bypass. The
-*   factory does an exact-match `includes` check — case-sensitive,
-*   no fuzzy matching. Lowercase your role vocabulary upstream.
-* @returns A `skipWhen`-compatible callback `(ctx, op) → boolean`.
-*/
-function adminBypass$1(options) {
-	return adminBypass(options);
-}
 //#endregion
 //#region src/plugins/observability.plugin.ts
 /**
@@ -1798,305 +2115,62 @@ function adminBypass$1(options) {
 *       // 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;
-	const ops = options.operations ?? DEFAULT_OPS;
-	const isSkipped = (context) => {
-		const list = context.skipPlugins;
-		return Array.isArray(list) && list.includes("observability");
-	};
-	return {
-		name: "observability",
-		apply(repo) {
-			for (const op of ops) {
-				repo.on(`before:${op}`, (context) => {
-					if (isSkipped(context)) return;
-					timers.set(context, performance.now());
-				}, { priority: 300 });
-				repo.on(`after:${op}`, ({ context }) => {
-					if (isSkipped(context)) return;
-					const start = timers.get(context);
-					if (start == null) return;
-					const durationMs = Math.round((performance.now() - start) * 100) / 100;
-					timers.delete(context);
-					if (slowThresholdMs != null && durationMs < slowThresholdMs) return;
-					onMetric({
-						operation: op,
-						model: context.model || repo.model,
-						durationMs,
-						success: true,
-						startedAt: new Date(Date.now() - durationMs),
-						userId: context.user?._id?.toString() || context.user?.id?.toString(),
-						organizationId: context.organizationId?.toString()
-					});
-				});
-				repo.on(`error:${op}`, ({ context, error }) => {
-					if (isSkipped(context)) return;
-					const start = timers.get(context);
-					if (start == null) return;
-					const durationMs = Math.round((performance.now() - start) * 100) / 100;
-					timers.delete(context);
-					onMetric({
-						operation: op,
-						model: context.model || repo.model,
-						durationMs,
-						success: false,
-						error: error.message,
-						startedAt: new Date(Date.now() - durationMs),
-						userId: context.user?._id?.toString() || context.user?.id?.toString(),
-						organizationId: context.organizationId?.toString()
-					});
-				});
-			}
-		}
-	};
-}
-//#endregion
-//#region src/plugins/soft-delete.plugin.ts
-/**
-* Build filter condition based on filter mode
-*/
-function buildDeletedFilter(deletedField, filterMode, includeDeleted) {
-	if (includeDeleted) return {};
-	if (filterMode === "exists") return { [deletedField]: { $exists: false } };
-	return { [deletedField]: null };
-}
-/**
-* Build filter condition for finding deleted documents
-*/
-function buildGetDeletedFilter(deletedField, filterMode) {
-	if (filterMode === "exists") return { [deletedField]: {
-		$exists: true,
-		$ne: null
-	} };
-	return { [deletedField]: { $ne: null } };
-}
-/**
-* Soft delete plugin
-*
-* @example Basic usage
-* ```typescript
-* const repo = new Repository(Model, [
-*   softDeletePlugin({ deletedField: 'deletedAt' })
-* ]);
-*
-* // Delete (soft)
-* await repo.delete(id);
-*
-* // Restore
-* await repo.restore(id);
-*
-* // Get deleted documents
-* await repo.getDeleted({ page: 1, limit: 20 });
-* ```
-*
-* @example With null filter mode (for schemas with default: null)
-* ```typescript
-* // Schema: { deletedAt: { type: Date, default: null } }
-* const repo = new Repository(Model, [
-*   softDeletePlugin({
-*     deletedField: 'deletedAt',
-*     filterMode: 'null', // default - works with default: null
-*   })
-* ]);
-* ```
-*
-* @example With TTL for auto-cleanup
-* ```typescript
-* const repo = new Repository(Model, [
-*   softDeletePlugin({
-*     deletedField: 'deletedAt',
-*     ttlDays: 30, // Auto-delete after 30 days
-*   })
-* ]);
-* ```
-*/
-function softDeletePlugin(options = {}) {
-	const deletedField = options.deletedField || "deletedAt";
-	const deletedByField = options.deletedByField || "deletedBy";
-	const filterMode = options.filterMode || "null";
-	const addRestoreMethod = options.addRestoreMethod !== false;
-	const addGetDeletedMethod = options.addGetDeletedMethod !== false;
-	const ttlDays = options.ttlDays;
+*     },
+*   }),
+* ]);
+* ```
+*/
+const DEFAULT_OPS = ALL_OPERATIONS;
+const timers = /* @__PURE__ */ new WeakMap();
+function observabilityPlugin(options) {
+	const { onMetric, slowThresholdMs } = options;
+	const ops = options.operations ?? DEFAULT_OPS;
+	const isSkipped = (context) => {
+		const list = context.skipPlugins;
+		return Array.isArray(list) && list.includes("observability");
+	};
 	return {
-		name: "softDelete",
+		name: "observability",
 		apply(repo) {
-			try {
-				const schemaPaths = repo.Model.schema.paths;
-				for (const [pathName, schemaType] of Object.entries(schemaPaths)) {
-					if (pathName === "_id" || pathName === deletedField) continue;
-					if (schemaType.options?.unique) warn(`[softDeletePlugin] Field '${pathName}' on model '${repo.Model.modelName}' has a unique index. With soft-delete enabled, deleted documents will block new documents with the same '${pathName}'. Fix: change to a compound partial index — { ${pathName}: 1 }, { unique: true, partialFilterExpression: { ${deletedField}: null } }`);
-				}
-			} catch (err) {
-				warn(`[softDeletePlugin] Schema introspection failed for ${repo.Model.modelName}: ${err instanceof Error ? err.message : String(err)}`);
-			}
-			if (ttlDays !== void 0 && ttlDays > 0) {
-				const ttlSeconds = ttlDays * 24 * 60 * 60;
-				repo.Model.collection.createIndex({ [deletedField]: 1 }, {
-					expireAfterSeconds: ttlSeconds,
-					partialFilterExpression: { [deletedField]: { $type: "date" } }
-				}).catch((err) => {
-					if (err.code !== 85 && err.code !== 86 && !err.message.includes("already exists")) warn(`[softDeletePlugin] Failed to create TTL index: ${err.message}`);
-				});
-			}
-			repo.on("before:delete", async (context) => {
-				if (context.deleteMode === "hard") return;
-				if (options.soft !== false) {
-					const updateData = { [deletedField]: /* @__PURE__ */ new Date() };
-					if (context.user) updateData[deletedByField] = context.user._id || context.user.id;
-					const deleteQuery = {
-						[repo.idField || "_id"]: context.id,
-						...context.query || {}
-					};
-					if (!await repo.Model.findOneAndUpdate(deleteQuery, updateData, { session: context.session })) {
-						const error = /* @__PURE__ */ new Error(`Document with id '${context.id}' not found`);
-						error.status = 404;
-						throw error;
-					}
-					context.softDeleted = true;
-				}
-			}, { priority: HOOK_PRIORITY.POLICY });
-			const injectDeleteFilterToFilters = (context) => {
-				if (options.soft !== false) {
-					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
-					if (Object.keys(deleteFilter).length > 0) context.filters = {
-						...context.filters || {},
-						...deleteFilter
-					};
-				}
-			};
-			const injectDeleteFilterToQuery = (context) => {
-				if (options.soft !== false) {
-					const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
-					if (Object.keys(deleteFilter).length > 0) context.query = {
-						...context.query || {},
-						...deleteFilter
-					};
-				}
-			};
-			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.POLICY });
-				else if (desc.policyKey === "query") repo.on(`before:${op}`, injectDeleteFilterToQuery, { priority: HOOK_PRIORITY.POLICY });
-			}
-			repo.on("before:updateMany", (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:deleteMany", async (context) => {
-				if (context.deleteMode === "hard") return;
-				if (options.soft !== false) {
-					const deleteFilter = buildDeletedFilter(deletedField, filterMode, false);
-					const finalQuery = {
-						...context.query || {},
-						...deleteFilter
-					};
-					const updateRes = await repo.Model.updateMany(finalQuery, { $set: { [deletedField]: /* @__PURE__ */ new Date() } }, { session: context.session });
-					context.softDeleted = true;
-					context.softDeletedCount = updateRes?.modifiedCount ?? 0;
-				}
-			}, { priority: HOOK_PRIORITY.POLICY });
-			if (addRestoreMethod) {
-				const restoreMethod = async function(id, restoreOptions = {}) {
-					const context = await this._buildContext("restore", {
-						id,
-						...restoreOptions
-					});
-					const updateData = {
-						[deletedField]: null,
-						[deletedByField]: null
-					};
-					const restoreQuery = {
-						_id: id,
-						...context.query || {}
-					};
-					const result = await this.Model.findOneAndUpdate(restoreQuery, { $set: updateData }, {
-						returnDocument: "after",
-						session: restoreOptions.session
-					});
-					if (!result) {
-						const error = /* @__PURE__ */ new Error(`Document with id '${id}' not found`);
-						error.status = 404;
-						throw error;
-					}
-					await this.emitAsync("after:restore", {
-						context,
-						result
+			for (const op of ops) {
+				repo.on(`before:${op}`, (context) => {
+					if (isSkipped(context)) return;
+					timers.set(context, performance.now());
+				}, { priority: 300 });
+				repo.on(`after:${op}`, ({ context }) => {
+					if (isSkipped(context)) return;
+					const start = timers.get(context);
+					if (start == null) return;
+					const durationMs = Math.round((performance.now() - start) * 100) / 100;
+					timers.delete(context);
+					if (slowThresholdMs != null && durationMs < slowThresholdMs) return;
+					onMetric({
+						operation: op,
+						model: context.model || repo.model,
+						durationMs,
+						success: true,
+						startedAt: new Date(Date.now() - durationMs),
+						userId: context.user?._id?.toString() || context.user?.id?.toString(),
+						organizationId: context.organizationId?.toString()
 					});
-					return result;
-				};
-				if (typeof repo.registerMethod === "function") repo.registerMethod("restore", restoreMethod);
-				else repo.restore = restoreMethod.bind(repo);
-			}
-			if (addGetDeletedMethod) {
-				const getDeletedMethod = async function(params = {}, getDeletedOptions = {}) {
-					const context = await this._buildContext("getDeleted", {
-						...params,
-						...getDeletedOptions
+				});
+				repo.on(`error:${op}`, ({ context, error }) => {
+					if (isSkipped(context)) return;
+					const start = timers.get(context);
+					if (start == null) return;
+					const durationMs = Math.round((performance.now() - start) * 100) / 100;
+					timers.delete(context);
+					onMetric({
+						operation: op,
+						model: context.model || repo.model,
+						durationMs,
+						success: false,
+						error: error.message,
+						startedAt: new Date(Date.now() - durationMs),
+						userId: context.user?._id?.toString() || context.user?.id?.toString(),
+						organizationId: context.organizationId?.toString()
 					});
-					const deletedFilter = buildGetDeletedFilter(deletedField, filterMode);
-					const combinedFilters = {
-						...params.filters || {},
-						...deletedFilter,
-						...context.filters || {},
-						...context.query || {}
-					};
-					const page = params.page || 1;
-					const limit = params.limit || 20;
-					const skip = (page - 1) * limit;
-					let sortSpec = { [deletedField]: -1 };
-					if (params.sort) if (typeof params.sort === "string") {
-						const sortOrder = params.sort.startsWith("-") ? -1 : 1;
-						sortSpec = { [params.sort.startsWith("-") ? params.sort.substring(1) : params.sort]: sortOrder };
-					} else sortSpec = params.sort;
-					let query = this.Model.find(combinedFilters).sort(sortSpec).skip(skip).limit(limit);
-					if (getDeletedOptions.session) query = query.session(getDeletedOptions.session);
-					if (getDeletedOptions.select) {
-						const selectValue = Array.isArray(getDeletedOptions.select) ? getDeletedOptions.select.join(" ") : getDeletedOptions.select;
-						query = query.select(selectValue);
-					}
-					if (getDeletedOptions.populate) {
-						const populateSpec = getDeletedOptions.populate;
-						if (typeof populateSpec === "string") query = query.populate(populateSpec.split(",").map((p) => p.trim()));
-						else if (Array.isArray(populateSpec)) query = query.populate(populateSpec);
-						else query = query.populate(populateSpec);
-					}
-					if (getDeletedOptions.lean !== false) query = query.lean();
-					const [data, total] = await Promise.all([query.exec(), this.Model.countDocuments(combinedFilters)]);
-					const pages = Math.ceil(total / limit);
-					return {
-						method: "offset",
-						data,
-						page,
-						limit,
-						total,
-						pages,
-						hasNext: page < pages,
-						hasPrev: page > 1
-					};
-				};
-				if (typeof repo.registerMethod === "function") repo.registerMethod("getDeleted", getDeletedMethod);
-				else repo.getDeleted = getDeletedMethod.bind(repo);
+				});
 			}
 		}
 	};
@@ -2223,45 +2297,6 @@ function createTenantContext() {
 	};
 }
 //#endregion
-//#region src/plugins/timestamp.plugin.ts
-/**
-* Timestamp plugin that auto-injects timestamps
-*
-* @example
-* const repo = new Repository(Model, [timestampPlugin()]);
-*/
-function timestampPlugin() {
-	return {
-		name: "timestamp",
-		apply(repo) {
-			repo.on("before:create", (context) => {
-				if (!context.data) return;
-				const now = /* @__PURE__ */ new Date();
-				if (!context.data.createdAt) context.data.createdAt = now;
-				if (!context.data.updatedAt) context.data.updatedAt = now;
-			});
-			repo.on("before:update", (context) => {
-				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;
-			});
-		}
-	};
-}
-//#endregion
 //#region src/plugins/validation-chain.plugin.ts
 /**
 * Validation chain plugin
@@ -2412,4 +2447,4 @@ function uniqueField(field, errorMessage) {
 	};
 }
 //#endregion
-export { aggregateHelpersPlugin as A, sequentialId as C, AuditTrailQuery as D, batchOperationsPlugin as E, auditTrailPlugin as O, prefixedId as S, cachePlugin as T, fieldFilterPlugin as _, uniqueField as a, dateSequentialId as b, createTenantContext as c, observabilityPlugin as d, adminBypass$1 as f, leasePlugin as g, methodRegistryPlugin as h, requireField as i, auditLogPlugin as k, subdocumentPlugin as l, mongoOperationsPlugin as m, blockIf as n, validationChainPlugin as o, multiTenantPlugin as p, immutableField as r, timestampPlugin as s, autoInject as t, softDeletePlugin as u, elasticSearchPlugin as v, cascadePlugin as w, getNextSequence as x, customIdPlugin as y };
+export { auditLogPlugin as A, getNextSequence as C, batchOperationsPlugin as D, cachePlugin as E, AuditTrailQuery as O, dateSequentialId as S, sequentialId as T, softDeletePlugin as _, uniqueField as a, methodRegistryPlugin as b, subdocumentPlugin as c, leasePlugin as d, fieldFilterPlugin as f, timestampPlugin as g, aggregateHelpersPlugin as h, requireField as i, auditTrailPlugin as k, observabilityPlugin as l, cascadePlugin as m, blockIf as n, validationChainPlugin as o, elasticSearchPlugin as p, immutableField as r, createTenantContext as s, autoInject as t, mongoOperationsPlugin as u, adminBypass$1 as v, prefixedId as w, customIdPlugin as x, multiTenantPlugin as y };