@classytic/mongokit 3.39.0 → 3.40.0

package/dist/{validation-chain.plugin-Bju1D1Sn.mjs → validation-chain.plugin-BLY2gLEk.mjs}

@@ -1,8 +1,9 @@
 import { n as collectIds, r as idChunks, t as DEFAULT_ID_CHUNK } from "./id-chunks-BmAwsqNk.mjs";
-import { c as ALL_OPERATIONS, u as OP_REGISTRY } from "./Repository-D7fDpyFx.mjs";
-import { S as upsert } from "./update-c_01A0if.mjs";
+import { i as ALL_OPERATIONS, o as OP_REGISTRY } from "./Repository-BMgPSkqZ.mjs";
+import { w as upsert } from "./update-DG0fCwRJ.mjs";
 import { n as warn } from "./logger-K7dPmu2U.mjs";
 import { t as createError } from "./error-BuByZwKU.mjs";
+import { c as tenantContextKeysOf, o as forwardScope } from "./timestamp.plugin-DF0gJB6p.mjs";
 import { r as getFieldsForUser } from "./field-selection-FSQFLpsU.mjs";
 import mongoose from "mongoose";
 import { HOOK_PRIORITY } from "@classytic/repo-core/hooks";
@@ -202,109 +203,121 @@ function appendOnlyPlugin(options = {}) {
 * });
 * ```
 */
+/** The repository's own id field — the default `parentKey`. */
+function idFieldOf(repo) {
+	return repo.idField || "_id";
+}
+const parentKeyOf = (relation, repo) => relation.parentKey ?? idFieldOf(repo);
+/** `{ fk: v }` for one parent (the shape a target's hooks expect), a sliced `$in` otherwise. */
+const referencing = (relation, chunk) => ({ [relation.foreignKey]: chunk.length === 1 ? chunk[0] : { $in: chunk } });
+const targetNameOf = (relation) => relation.repo?.Model?.modelName ?? relation.model ?? "<unknown>";
 /**
-* 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.
-*/
-/**
-* Count referencing documents through the target REPOSITORY, carrying the parent's session
-* and scope.
+* Parent key values for ONE id-addressed delete.
 *
-* Both are load-bearing and were missing in the first cut:
-*   - without `session`, the count reads OUTSIDE the parent's transaction, so children
-*     created in the same uncommitted transaction are invisible and the guard passes;
-*   - without the forwarded scope, a tenant-scoped target either reads unscoped (refusing a
-*     delete because ANOTHER tenant references the row) or relies on ambient context that a
-*     background job does not have.
-*
-* REFUSES rather than falling back to `Model.countDocuments` when the repository has no
-* `count`: a raw count silently bypasses the target's own policy, which is the thing this
-* guard exists to respect.
+* The key the call was addressed by is already known (`context.id`). Any other
+* key a relation needs (`parentKey: '_id'` on an `orderNumber` repo) is read from
+* the target document, before the delete, through `loadTarget` (shared with
+* every other hook, under the operation's session).
 */
-async function countReferencing(relation, filter, session, scopeForward) {
-	const targetRepo = relation.repo;
-	if (!targetRepo || typeof targetRepo.count !== "function") throw new Error(`cascadePlugin: onDelete:'restrict' on '${relation.foreignKey}' needs a repository with \`count()\` — a raw model count would bypass the target's tenant scoping and policy`);
-	const options = { ...scopeForward };
-	if (session) options.session = session;
-	return targetRepo.count(filter, options);
+async function parentKeysOfDelete(context, repo, keys) {
+	const out = /* @__PURE__ */ new Map();
+	const addressedBy = context.idField ?? idFieldOf(repo);
+	const target = [...keys].some((key) => key !== addressedBy) ? await context.loadTarget?.() ?? await repo.Model.findOne({ [addressedBy]: context.id }, null, { session: context.session }).lean() : null;
+	for (const key of keys) {
+		const value = key === addressedBy ? context.id : target?.[key];
+		out.set(key, value === void 0 || value === null ? [] : [value]);
+	}
+	return out;
+}
+/** Parent key values for a `deleteMany` — streamed from the (already tenant-scoped) filter. */
+async function parentKeysOfDeleteMany(context, repo, keys) {
+	const out = /* @__PURE__ */ new Map();
+	for (const key of keys) out.set(key, await collectIds(repo.Model, context.query, {
+		session: context.session,
+		idField: key
+	}));
+	return out;
 }
 /**
-* ENFORCE that a guarded foreign key is indexed.
+* RESTRICT — refuse while any child still references a parent being deleted.
 *
-* `restrict` and `detach` issue a query per relation on every delete. MongoDB gives no index
-* for free the way an FK constraint does, so an unindexed `foreignKey` turns each delete into
-* a COLLECTION SCAN of the child collection — invisible in tests (small fixtures) and
-* crippling in production, which is the shape of defect this codebase treats as the default
-* hazard.
+* Counted through the target REPOSITORY with the forwarded scope and session:
+* a raw model count would bypass the target's tenant scoping (refusing on
+* another tenant's evidence) or read outside the transaction (missing children
+* created in it). Sliced `$in`, SUMMED, so the refusal reports the true count.
 *
-* Documentation was not enough: a type comment saying the key "SHOULD" be indexed stops no
-* scan. This is checked at BIND time, where the declaration is, and THROWS — the policies are
-* opt-in and brand new, so nothing pre-existing can be broken by refusing.
+* ## An application delete GUARD, not `ON DELETE RESTRICT`
 *
-* Prefix rule, matching Mongo's own: an index on `{a:1, b:1}` serves a query on `a`, so the
-* foreign key qualifies when it is the FIRST key of any declared index. `schema.indexes()`
-* includes path-level `{index: true}` as well as explicit `schema.index(...)` calls.
+* This is count-then-delete. A child inserted between the two survives as a
+* dangling reference, and a transaction narrows but does not close that window
+* (Mongo has no predicate lock; the child's insert is not in this write set).
+* It stops the ordinary case, an operator deleting a referenced parent, and must
+* not be described as a concurrency-safe integrity guarantee.
 */
-function assertForeignKeyIndexed(relation) {
-	const schema = relation.repo?.Model?.schema;
-	if (!schema || typeof schema.indexes !== "function") return;
-	if (schema.indexes().some(([keys]) => Object.keys(keys)[0] === relation.foreignKey)) return;
-	const target = relation.repo?.Model?.modelName ?? relation.model ?? "<unknown>";
-	throw new Error(`cascadePlugin: onDelete:'${relation.onDelete}' on '${relation.foreignKey}' requires an index on ${target}.${relation.foreignKey} — the guard queries it on every delete, and Mongo has no foreign-key index. Add \`index: true\` to the path or a leading \`schema.index(...)\`.`);
+async function assertUnreferenced(relation, values, scope, batchSize, context, single) {
+	const target = relation.repo;
+	if (typeof target?.count !== "function") throw new Error(`cascadePlugin: onDelete:'restrict' on '${relation.foreignKey}' needs a repository with \`count()\` — a raw model count would bypass the target's tenant scoping and policy`);
+	let remaining = 0;
+	for (const chunk of idChunks(values, batchSize)) remaining += await target.count(referencing(relation, chunk), { ...scope });
+	if (remaining === 0) return;
+	const referencedBy = targetNameOf(relation);
+	const err = /* @__PURE__ */ new Error(single ? `Cannot delete this ${context.model ?? "document"}: ${remaining} ${referencedBy} record(s) still reference it via '${relation.foreignKey}'. Remove or reassign them first.` : `Cannot delete these ${context.model ?? "documents"}: ${remaining} ${referencedBy} record(s) still reference ${values.length} of them via '${relation.foreignKey}'. Remove or reassign them first.`);
+	err.code = "REFERENCE_RESTRICTED";
+	err.details = {
+		model: context.model,
+		...single ? { id: String(context.id) } : { ids: values.map(String) },
+		referencedBy,
+		foreignKey: relation.foreignKey,
+		count: remaining
+	};
+	throw err;
 }
 /**
-* A TTL index on the PROTECTED parent makes `restrict` a promise the plugin cannot keep.
-*
-* `restrict` means "do not delete this document while anything references it". A TTL index
-* means "delete this document N seconds after its date field, server-side". Mongo's expiry
-* thread runs no application code — no repository, no hook, no count — so it will remove a
-* referenced parent and leave every child dangling, silently, at a time nobody chose.
-*
-* The two are a direct contradiction, so this THROWS rather than warns. Refusing at bind time
-* is the only point where anyone can see both declarations at once; at runtime the expiry
-* simply happens.
+* DETACH — the RDBMS `SET NULL`: clear the pointer, keep the child.
 *
-* NOTE this is about the PARENT (the repo declaring the relations). A TTL on the CHILD is
-* fine and even useful — expiring children is how references legitimately drain away.
+* Through the target repository's `updateMany`, so its tenant policy, audit,
+* cache and update hooks run. A repo without one is refused rather than written
+* raw; the legacy `model` route is documented as hook-bypassing.
 */
-function assertNoTtlOnProtectedParent(repo, relation) {
-	const schema = repo.Model?.schema;
-	if (!schema || typeof schema.indexes !== "function") return;
-	const ttl = schema.indexes().find(([, options]) => options?.expireAfterSeconds !== void 0);
-	if (!ttl) return;
-	const parent = repo.Model?.modelName ?? "<unknown>";
-	const key = Object.keys(ttl[0])[0];
-	throw new Error(`cascadePlugin: ${parent} declares onDelete:'restrict' on '${relation.foreignKey}' but also carries a TTL index on '${key}' (expireAfterSeconds). Mongo's expiry runs server-side and fires no hooks, so it would delete a referenced document and orphan its children — the restrict guarantee cannot hold. Remove the TTL, or use a retention sweep that deletes through the repository.`);
+async function detach(relation, values, scope, batchSize) {
+	const update = { $unset: { [relation.foreignKey]: "" } };
+	const target = relation.repo;
+	if (target && typeof target.updateMany !== "function") throw new Error(`cascadePlugin: onDelete:'detach' on '${relation.foreignKey}' needs a repository with \`updateMany()\` — a raw model update would skip the child's hooks and tenant policy`);
+	for (const chunk of idChunks(values, batchSize)) {
+		const filter = referencing(relation, chunk);
+		if (target?.updateMany) await target.updateMany(filter, update, { ...scope });
+		else await mongoose.models[relation.model]?.updateMany(filter, update, { session: scope.session }).exec();
+	}
 }
 /**
-* `detach` — clear the reference through the target REPOSITORY (`SET NULL`).
+* CASCADE — delete the children, soft when the parent was soft (or the relation
+* says so).
 *
-* Routed through `repo.updateMany`, not `repo.Model.updateMany`. The first cut used the raw
-* model while the comment beside it claimed the target's hooks ran: they did not, so tenant
-* policy, audit hooks, cache invalidation and update hooks were all skipped on a write that
-* mutates the child. A comment asserting a guarantee the code does not provide is worse than
-* no comment.
+* Repo-routed: `target.deleteMany` with the forwarded scope, so the target's own
+* tenant policy, audit and soft-delete plugin (with ITS `deletedField`) apply.
+* Legacy `model` route: a raw write that bypasses the target's hooks.
 */
-async function detachReferences(relation, filter, ctx) {
-	const update = { $unset: { [relation.foreignKey]: "" } };
-	const options = { ...ctx.scopeForward };
-	if (ctx.session) options.session = ctx.session;
-	const targetRepo = relation.repo;
-	if (targetRepo && typeof targetRepo.updateMany === "function") {
-		await targetRepo.updateMany(filter, update, options);
+async function cascade(relation, values, scope, batchSize, soft, logger) {
+	const target = relation.repo;
+	if (target && typeof target.deleteMany !== "function") throw new Error(`cascadePlugin: target repo for '${targetNameOf(relation)}' is missing deleteMany(). Ensure the target is a mongokit Repository or implements the StandardRepo deleteMany contract.`);
+	const RelatedModel = target ? void 0 : mongoose.models[relation.model];
+	if (!target && !RelatedModel) {
+		logger?.warn?.(`Cascade delete skipped: model '${relation.model}' not found`);
 		return;
 	}
-	if (targetRepo) throw new Error(`cascadePlugin: onDelete:'detach' on '${relation.foreignKey}' needs a repository with \`updateMany()\` — a raw model update would skip the child's hooks and tenant policy`);
-	await mongoose.models[relation.model]?.updateMany(filter, update, ctx.session ? { session: ctx.session } : {}).exec();
-}
-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;
+	const user = scope.user;
+	for (const chunk of idChunks(values, batchSize)) {
+		const filter = referencing(relation, chunk);
+		if (target?.deleteMany) await target.deleteMany(filter, {
+			...scope,
+			mode: soft ? "soft" : "hard"
+		});
+		else if (soft) await RelatedModel?.updateMany(filter, {
+			deletedAt: /* @__PURE__ */ new Date(),
+			...user ? { deletedBy: user._id || user.id } : {}
+		}, { session: scope.session });
+		else await RelatedModel?.deleteMany(filter, { session: scope.session });
+	}
 }
 /**
 * Cascade delete plugin.
@@ -317,233 +330,127 @@ function cascadePlugin(options) {
 		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`");
 		/**
-		* `restrict` must be able to COUNT the referencing documents before the parent goes,
-		* and the legacy model-routed path writes through `mongoose.models[...]` without the
-		* target's scoping. A restrict that counted unscoped rows would refuse a delete on
-		* evidence from another tenant, so it requires the repo-routed form.
+		* `restrict` must COUNT the referencing documents through the target's scoping;
+		* the legacy `model` route cannot, and would refuse on another tenant's evidence.
 		*/
 		if (rel.onDelete === "restrict" && !rel.repo) throw new Error(`cascadePlugin: relation on '${rel.foreignKey}' uses onDelete:'restrict', which requires \`repo\` (the legacy \`model\` route cannot apply the target's tenant scoping to the count)`);
 	}
 	const restrictions = relations.filter((r) => r.onDelete === "restrict");
 	const detachments = relations.filter((r) => r.onDelete === "detach");
-	/** Everything else keeps the historical behaviour — an absent `onDelete` is `cascade`. */
+	/** An absent `onDelete` is `cascade`, the historical behaviour. */
 	const cascades = relations.filter((r) => (r.onDelete ?? "cascade") === "cascade");
 	return {
 		name: "cascade",
 		apply(repo) {
-			/**
-			* Bind time, not construction time: the relation carries a repo whose Model (and
-			* therefore its schema) is only reliably available once the plugin is applied.
-			*/
 			for (const relation of [...restrictions, ...detachments]) assertForeignKeyIndexed(relation);
 			for (const relation of restrictions) assertNoTtlOnProtectedParent(repo, relation);
-			if (restrictions.length > 0) repo.on("before:delete", async (context) => {
-				const id = context.id;
-				if (!id) return;
-				const scopeForward = collectScopeForward(context);
+			const keys = new Set(relations.map((relation) => parentKeyOf(relation, repo)));
+			/** Tenant keys of the parent AND every target, so each hop carries what its plugin reads. */
+			const tenantKeys = tenantContextKeysOf(repo, ...relations.map((relation) => relation.repo));
+			const scopeOf = (context) => forwardScope(context, tenantKeys);
+			/**
+			* BEFORE the parent goes: capture the key values (they cannot be read after a
+			* hard delete) and refuse on a restrict. `before`, because a refusal issued
+			* once the parent is gone is not a refusal.
+			*/
+			const prepare = async (context, single) => {
+				const parentKeys = single ? await parentKeysOfDelete(context, repo, keys) : await parentKeysOfDeleteMany(context, repo, keys);
+				context._cascadeParentKeys = parentKeys;
+				const scope = scopeOf(context);
 				for (const relation of restrictions) {
-					const remaining = await countReferencing(relation, { [relation.foreignKey]: id }, context.session, scopeForward);
-					if (remaining > 0) {
-						const target = relation.repo?.Model?.modelName ?? relation.model ?? "<unknown>";
-						const err = /* @__PURE__ */ new Error(`Cannot delete this ${context.model ?? "document"}: ${remaining} ${target} record(s) still reference it via '${relation.foreignKey}'. Remove or reassign them first.`);
-						err.code = "REFERENCE_RESTRICTED";
-						err.details = {
-							model: context.model,
-							id: String(id),
-							referencedBy: target,
-							foreignKey: relation.foreignKey,
-							count: remaining
-						};
-						throw err;
-					}
-				}
-			});
-			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 values = parentKeys.get(parentKeyOf(relation, repo)) ?? [];
+					if (values.length > 0) await assertUnreferenced(relation, values, scope, batchSize, context, single);
 				}
-				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
-					};
+			};
+			/** AFTER: detach, then cascade — over the captured values, with the forwarded scope. */
+			const propagate = async (context) => {
+				const parentKeys = context._cascadeParentKeys;
+				if (!parentKeys) return;
+				const scope = scopeOf(context);
+				const soft = context.softDeleted === true;
+				const session = context.session;
+				const valuesOf = (relation) => parentKeys.get(parentKeyOf(relation, repo)) ?? [];
+				const guarded = (verb, fn) => async (relation) => {
+					if (valuesOf(relation).length === 0) return;
 					try {
-						if (relation.repo) await cascadeViaRepoBulk(relation, deletedId, cascadeCtx);
-						else await cascadeViaLegacyModel(relation, deletedId, cascadeCtx, logger);
+						await fn(relation);
 					} catch (error) {
-						logger?.error?.(`Cascade delete failed for '${cascadeCtx.targetModelName}'`, {
+						logger?.error?.(`Cascade ${verb} failed for '${targetNameOf(relation)}'`, {
 							parentModel: context.model,
-							parentId: String(deletedId),
-							relatedModel: cascadeCtx.targetModelName,
+							relatedModel: targetNameOf(relation),
 							foreignKey: relation.foreignKey,
 							error: error.message
 						});
 						throw error;
 					}
 				};
-				/**
-				* `detach` — the RDBMS `SET NULL`. Clear the pointer, keep the child.
-				*
-				* Runs beside the cascades and before them in intent: a detached child must not be
-				* reachable through a reference to a document that no longer exists. Routed through
-				* the target repo so its hooks and scoping apply, exactly as cascade is.
-				*/
-				const detachOne = async (relation) => detachReferences(relation, { [relation.foreignKey]: deletedId }, {
-					session: context.session,
-					scopeForward
-				});
-				const txSession = context.session;
-				if (detachments.length > 0) await runCascades(detachments, detachOne, parallel, txSession);
-				await runCascades(cascades, cascadeOne, parallel, txSession);
+				await runCascades(detachments, guarded("detach", (relation) => detach(relation, valuesOf(relation), scope, batchSize)), parallel, session);
+				await runCascades(cascades, guarded("delete", (relation) => cascade(relation, valuesOf(relation), scope, batchSize, relation.softDelete ?? soft, logger)), parallel, session);
+			};
+			repo.on("before:delete", (context) => {
+				if (context.id === void 0 || context.id === null) return;
+				return prepare(context, true);
+			});
+			repo.on("after:delete", async (payload) => {
+				if (!payload.result) return;
+				await propagate(payload.context);
 			});
-			repo.on("before:deleteMany", async (context) => {
+			repo.on("before:deleteMany", (context) => {
 				const query = context.query;
 				if (!query || Object.keys(query).length === 0) return;
-				const idField = repo.idField || "_id";
-				const ids = await collectIds(repo.Model, query, {
-					session: context.session,
-					idField
-				});
-				context._cascadeIds = ids;
-				/**
-				* RESTRICT applies to bulk too — and its absence here was a destructive bug.
-				*
-				* The first cut split the policies on the single-delete path only and then passed
-				* ALL relations to the bulk cascade, so `deleteMany` DELETED the children of a
-				* `restrict` relation (and of a `detach` one). Bulk was therefore strictly worse
-				* than declaring nothing at all. Checked in the same hook that snapshots the ids,
-				* so it cannot be reordered apart from them.
-				*/
-				if (restrictions.length > 0 && ids.length > 0) {
-					const scopeForward = collectScopeForward(context);
-					for (const relation of restrictions) {
-						let remaining = 0;
-						for (const chunk of idChunks(ids, batchSize)) remaining += await countReferencing(relation, { [relation.foreignKey]: { $in: chunk } }, context.session, scopeForward);
-						if (remaining > 0) {
-							const target = relation.repo?.Model?.modelName ?? relation.model ?? "<unknown>";
-							const err = /* @__PURE__ */ new Error(`Cannot delete these ${context.model ?? "documents"}: ${remaining} ${target} record(s) still reference ${ids.length} of them via '${relation.foreignKey}'. Remove or reassign them first.`);
-							err.code = "REFERENCE_RESTRICTED";
-							err.details = {
-								model: context.model,
-								ids: ids.map(String),
-								referencedBy: target,
-								foreignKey: relation.foreignKey,
-								count: remaining
-							};
-							throw err;
-						}
-					}
-				}
-			});
-			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, batchSize, cascadeCtx);
-						else await cascadeViaLegacyModelMany(relation, ids, batchSize, 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;
-					}
-				};
-				/** `detach` in bulk — the same `$unset`, routed through the target repository, sliced. */
-				const detachBulk = async (relation) => {
-					for (const chunk of idChunks(ids, batchSize)) await detachReferences(relation, { [relation.foreignKey]: { $in: chunk } }, {
-						session: context.session,
-						scopeForward
-					});
-				};
-				const txSession = context.session;
-				if (detachments.length > 0) await runCascades(detachments, detachBulk, parallel, txSession);
-				await runCascades(cascades, cascadeBulk, parallel, txSession);
+				return prepare(context, false);
 			});
+			repo.on("after:deleteMany", (payload) => propagate(payload.context));
 		}
 	};
 }
 /**
-* 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 — sliced `$in` over snapshot ids
-* (`batchSize` bounds each query document; see `utils/id-chunks.ts`).
+* ENFORCE that a guarded foreign key is indexed.
+*
+* `restrict` and `detach` issue a query per relation on every delete. MongoDB gives no index
+* for free the way an FK constraint does, so an unindexed `foreignKey` turns each delete into
+* a COLLECTION SCAN of the child collection — invisible in tests (small fixtures) and
+* crippling in production, which is the shape of defect this codebase treats as the default
+* hazard.
+*
+* Documentation was not enough: a type comment saying the key "SHOULD" be indexed stops no
+* scan. This is checked at BIND time, where the declaration is, and THROWS — the policies are
+* opt-in and brand new, so nothing pre-existing can be broken by refusing.
+*
+* Prefix rule, matching Mongo's own: an index on `{a:1, b:1}` serves a query on `a`, so the
+* foreign key qualifies when it is the FIRST key of any declared index. `schema.indexes()`
+* includes path-level `{index: true}` as well as explicit `schema.index(...)` calls.
 */
-async function cascadeViaRepoBulkMany(relation, parentIds, batchSize, 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.`);
-	for (const chunk of idChunks(parentIds, batchSize)) await targetRepo.deleteMany({ [relation.foreignKey]: { $in: chunk } }, {
-		...ctx.scopeForward,
-		mode: ctx.shouldSoftDelete ? "soft" : "hard",
-		session: ctx.session
-	});
+function assertForeignKeyIndexed(relation) {
+	const schema = relation.repo?.Model?.schema;
+	if (!schema || typeof schema.indexes !== "function") return;
+	if (schema.indexes().some(([keys]) => Object.keys(keys)[0] === relation.foreignKey)) return;
+	const target = relation.repo?.Model?.modelName ?? relation.model ?? "<unknown>";
+	throw new Error(`cascadePlugin: onDelete:'${relation.onDelete}' on '${relation.foreignKey}' requires an index on ${target}.${relation.foreignKey} — the guard queries it on every delete, and Mongo has no foreign-key index. Add \`index: true\` to the path or a leading \`schema.index(...)\`.`);
 }
 /**
-* Legacy cascade via `mongoose.models[name]`. Bypasses target hooks.
-* Retained for backwards compatibility with existing cascadePlugin consumers.
+* A TTL index on the PROTECTED parent makes `restrict` a promise the plugin cannot keep.
+*
+* `restrict` means "do not delete this document while anything references it". A TTL index
+* means "delete this document N seconds after its date field, server-side". Mongo's expiry
+* thread runs no application code — no repository, no hook, no count — so it will remove a
+* referenced parent and leave every child dangling, silently, at a time nobody chose.
+*
+* The two are a direct contradiction, so this THROWS rather than warns. Refusing at bind time
+* is the only point where anyone can see both declarations at once; at runtime the expiry
+* simply happens.
+*
+* NOTE this is about the PARENT (the repo declaring the relations). A TTL on the CHILD is
+* fine and even useful — expiring children is how references legitimately drain away.
 */
-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, batchSize, ctx, logger) {
-	const RelatedModel = mongoose.models[relation.model];
-	if (!RelatedModel) {
-		logger?.warn?.(`Cascade deleteMany skipped: model '${relation.model}' not found`);
-		return;
-	}
-	for (const chunk of idChunks(parentIds, batchSize)) {
-		const query = { [relation.foreignKey]: { $in: chunk } };
-		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 });
-	}
+function assertNoTtlOnProtectedParent(repo, relation) {
+	const schema = repo.Model?.schema;
+	if (!schema || typeof schema.indexes !== "function") return;
+	const ttl = schema.indexes().find(([, options]) => options?.expireAfterSeconds !== void 0);
+	if (!ttl) return;
+	const parent = repo.Model?.modelName ?? "<unknown>";
+	const key = Object.keys(ttl[0])[0];
+	throw new Error(`cascadePlugin: ${parent} declares onDelete:'restrict' on '${relation.foreignKey}' but also carries a TTL index on '${key}' (expireAfterSeconds). Mongo's expiry runs server-side and fires no hooks, so it would delete a referenced document and orphan its children — the restrict guarantee cannot hold. Remove the TTL, or use a retention sweep that deletes through the repository.`);
 }
 /**
 * Execute a list of cascade operations, honoring the `parallel` flag.
@@ -682,6 +589,12 @@ function randomToken() {
 	globalThis.crypto.getRandomValues(bytes);
 	return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
 }
+/**
+* @deprecated Use `runIdempotent` from `@classytic/repo-core/idempotency` over
+* `createIdempotencyStore` from `@classytic/mongokit/idempotency` — one claim contract for every
+* layer (body fingerprint, transaction participation, recovery points, `maxAttempts`, ambiguous
+* failures, lapsed-claim sweeps). Removed in mongokit 4.
+*/
 function idempotencyStorePlugin(options = {}) {
 	const keyField = options.keyField ?? "key";
 	const statusField = options.statusField ?? "status";

package/dist/{validation-chain.plugin-DvrLJIbJ.d.mts → validation-chain.plugin-DYp9E7K2.d.mts}

@@ -1,6 +1,6 @@
 import { _ as PopulateSpec, g as ObjectId, x as SortSpec, y as SelectSpec } from "./pagination-BpIv2bdS.mjs";
-import { h as RepositoryInstance, l as Plugin, p as RepositoryContext } from "./repository-ZbLtL7Nk.mjs";
-import { c as ValidationChainOptions, i as Logger, l as ValidatorDefinition, o as SoftDeleteOptions, r as FieldPreset, t as CascadeOptions } from "./plugin-options-BuvtOSZf.mjs";
+import { h as RepositoryInstance, l as Plugin, p as RepositoryContext } from "./repository-odl03582.mjs";
+import { c as ValidationChainOptions, i as Logger, l as ValidatorDefinition, o as SoftDeleteOptions, r as FieldPreset, t as CascadeOptions } from "./plugin-options-Zk46lD6F.mjs";
 import { BulkWriteResult } from "@classytic/repo-core/repository";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { OffsetPaginationResult } from "@classytic/repo-core/pagination";
@@ -113,6 +113,19 @@ declare function appendOnlyPlugin(options?: AppendOnlyPluginOptions): Plugin;
 declare function auditLogPlugin(logger: Logger): Plugin;
 //#endregion
 //#region src/plugins/batch-operations.plugin.d.ts
+/** Options accepted by `repo.bulkWrite`. Plugin context may ride alongside. */
+interface BulkWriteOptions {
+  /** Stop at the first failure. Default `true`, matching the driver. */
+  ordered?: boolean;
+  session?: unknown;
+  writeConcern?: Record<string, unknown>;
+  bypassDocumentValidation?: boolean;
+  comment?: unknown;
+  let?: Record<string, unknown>;
+  ignoreUndefined?: boolean;
+  /** Plugin context (tenant id, actor, ...) - spread into the op context. */
+  [key: string]: unknown;
+}
 declare function batchOperationsPlugin(): Plugin;
 interface BatchOperationsMethods {
   /**
@@ -303,6 +316,12 @@ interface IdempotencyStoreMethods<TProgress = Record<string, unknown>, TResult =
     error?: string;
   }): Promise<boolean>;
 }
+/**
+ * @deprecated Use `runIdempotent` from `@classytic/repo-core/idempotency` over
+ * `createIdempotencyStore` from `@classytic/mongokit/idempotency` — one claim contract for every
+ * layer (body fingerprint, transaction participation, recovery points, `maxAttempts`, ambiguous
+ * failures, lapsed-claim sweeps). Removed in mongokit 4.
+ */
 declare function idempotencyStorePlugin(options?: IdempotencyStorePluginOptions): Plugin;
 //#endregion
 //#region src/plugins/immutable-states.plugin.d.ts
@@ -770,6 +789,9 @@ interface SoftDeleteMethods<TDoc> {
    */
   restore(id: string | ObjectId, options?: {
     session?: unknown;
+    organizationId?: unknown;
+    bypassTenant?: boolean;
+    [key: string]: unknown;
   }): Promise<TDoc>;
   /**
    * Get paginated list of soft-deleted documents
@@ -942,4 +964,4 @@ declare function immutableField(field: string): ValidatorDefinition;
  */
 declare function uniqueField(field: string, errorMessage?: string): ValidatorDefinition;
 //#endregion
-export { IdempotencyStoreMethods as A, auditLogPlugin as B, LeaseMethods as C, ImmutableStatesPluginOptions as D, ImmutableClaimView as E, elasticSearchPlugin as F, appendOnlyPlugin as H, cascadePlugin as I, BatchOperationsMethods as L, idempotencyStorePlugin as M, fieldFilterPlugin as N, immutableStatesPlugin as O, ElasticSearchOptions as P, BulkWriteResult as R, methodRegistryPlugin as S, leasePlugin as T, AggregateHelpersMethods as U, AppendOnlyPluginOptions as V, aggregateHelpersPlugin as W, OperationMetric as _, requireField as a, mongoOperationsPlugin as b, timestampPlugin as c, createTenantContext as d, SubdocumentMethods as f, ObservabilityOptions as g, softDeletePlugin as h, immutableField as i, IdempotencyStorePluginOptions as j, IdempotencyClaim as k, TenantContext as l, SoftDeleteMethods as m, autoInject as n, uniqueField as o, subdocumentPlugin as p, blockIf as r, validationChainPlugin as s, OperationType as t, TenantStore as u, observabilityPlugin as v, LeasePluginOptions as w, MethodRegistryRepository as x, MongoOperationsMethods as y, batchOperationsPlugin as z };
+export { IdempotencyStoreMethods as A, batchOperationsPlugin as B, LeaseMethods as C, ImmutableStatesPluginOptions as D, ImmutableClaimView as E, elasticSearchPlugin as F, aggregateHelpersPlugin as G, AppendOnlyPluginOptions as H, cascadePlugin as I, BatchOperationsMethods as L, idempotencyStorePlugin as M, fieldFilterPlugin as N, immutableStatesPlugin as O, ElasticSearchOptions as P, BulkWriteOptions as R, methodRegistryPlugin as S, leasePlugin as T, appendOnlyPlugin as U, auditLogPlugin as V, AggregateHelpersMethods as W, OperationMetric as _, requireField as a, mongoOperationsPlugin as b, timestampPlugin as c, createTenantContext as d, SubdocumentMethods as f, ObservabilityOptions as g, softDeletePlugin as h, immutableField as i, IdempotencyStorePluginOptions as j, IdempotencyClaim as k, TenantContext as l, SoftDeleteMethods as m, autoInject as n, uniqueField as o, subdocumentPlugin as p, blockIf as r, validationChainPlugin as s, OperationType as t, TenantStore as u, observabilityPlugin as v, LeasePluginOptions as w, MethodRegistryRepository as x, MongoOperationsMethods as y, BulkWriteResult as z };