@classytic/mongokit 3.38.1 → 3.40.0

package/dist/{validation-chain.plugin-DhNyxNCw.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-Ck5x43wF.mjs";
-import { _ as upsert } from "./update-jSXp3nu3.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";