@classytic/mongokit 3.13.4 → 3.15.0

package/dist/{Repository-BZrU_nXs.mjs → Repository-BGL1Pq8w.mjs}

@@ -7,7 +7,7 @@ import { r as isValidIdForType, t as getSchemaIdType } from "./id-resolution-B0O
 import { isFilter } from "@classytic/repo-core/filter";
 import mongoose from "mongoose";
 import { HOOK_PRIORITY } from "@classytic/repo-core/hooks";
-import { RepositoryBase, validatePluginOrder } from "@classytic/repo-core/repository";
+import { RepositoryBase, runChunkedPurge, validatePluginOrder } from "@classytic/repo-core/repository";
 import { compileUpdateSpecToMongo, isUpdateSpec } from "@classytic/repo-core/update";
 import { decodeAggCursor, encodeAggCursor, isKeysetMode, normalizeGroupBy, validateMeasures } from "@classytic/repo-core/aggregate";
 //#region src/operations.ts
@@ -813,6 +813,74 @@ function buildKeysetPredicate(sort, cursor) {
 	return { $match: branches.length === 1 ? branches[0] : { $or: branches } };
 }
 //#endregion
+//#region src/actions/purge.ts
+/**
+* Build a `PurgePort` bound to a repository + the `field = value`
+* predicate the purge targets.
+*/
+function createMongoPurgePort(repo, field, value, session) {
+	const filter = { [field]: value };
+	const baseOpts = {
+		session,
+		bypassTenant: true
+	};
+	return { async purgeChunk(strategy, limit) {
+		if (strategy.type === "anonymize") {
+			if (Object.values(strategy.fields).some((v) => typeof v === "function")) return purgeAnonymizeFunctional(repo, filter, strategy.fields, limit, session);
+		}
+		const idDocs = await repo.Model.find(filter, { _id: 1 }).limit(limit).session(session ?? null).lean().exec();
+		if (idDocs.length === 0) return 0;
+		const chunkFilter = {
+			_id: { $in: idDocs.map((d) => d._id) },
+			[field]: value
+		};
+		switch (strategy.type) {
+			case "hard":
+				await repo.deleteMany(chunkFilter, {
+					...baseOpts,
+					mode: "hard"
+				});
+				return idDocs.length;
+			case "soft":
+				await repo.updateMany(chunkFilter, { $set: {
+					[strategy.deletedField ?? "deleted"]: true,
+					[strategy.deletedAtField ?? "deletedAt"]: /* @__PURE__ */ new Date()
+				} }, baseOpts);
+				return idDocs.length;
+			case "anonymize":
+				await repo.updateMany(chunkFilter, { $set: strategy.fields }, baseOpts);
+				return idDocs.length;
+		}
+	} };
+}
+/**
+* Anonymize with at least one function-form field replacer. Fetches the
+* full docs (function needs the row) and issues ONE `bulkWrite` with N
+* heterogeneous `updateOne` ops. Two round-trips per chunk regardless
+* of N — vs the N+1 of per-doc `update()` fan-out.
+*
+* Mongo's `bulkWrite` is ordered: false → independent failures don't
+* abort the batch. For idempotent anonymize (same row anonymized twice
+* is the same write), this matches the at-least-once contract.
+*/
+async function purgeAnonymizeFunctional(repo, filter, fields, limit, session) {
+	const docs = await repo.Model.find(filter).limit(limit).session(session ?? null).lean().exec();
+	if (docs.length === 0) return 0;
+	const operations = docs.map((doc) => {
+		const set = {};
+		for (const [k, v] of Object.entries(fields)) set[k] = typeof v === "function" ? v(doc) : v;
+		return { updateOne: {
+			filter: { _id: doc._id },
+			update: { $set: set }
+		} };
+	});
+	await repo.Model.bulkWrite(operations, {
+		ordered: false,
+		session: session ?? void 0
+	});
+	return docs.length;
+}
+//#endregion
 //#region src/query/AggregationBuilder.ts
 /**
 * Normalize SortSpec to MongoDB's strict format (1 | -1)
@@ -2249,7 +2317,95 @@ var Repository = class extends RepositoryBase {
 		return this._runOp("exists", context, () => exists(this.Model, context.query || query, options));
 	}
 	/**
-	* Update document by ID
+	* Update a document by id and return the post-update doc.
+	*
+	* Compiles to `Model.findOneAndUpdate(filter, { $set: data }, { new:
+	* true, runValidators: true })` under the hood and routes through the
+	* full plugin pipeline — `multiTenantPlugin` injects the tenant scope,
+	* `auditTrailPlugin` records the change, `cachePlugin` invalidates,
+	* `softDeletePlugin` etc. all compose. Returns `null` on miss (the
+	* `MinimalRepo` contract; pass `throwOnNotFound: true` for the legacy
+	* throw path).
+	*
+	* **Anti-pattern to avoid** — calling `Model.findOneAndUpdate()`
+	* directly on the raw mongoose model bypasses every plugin:
+	*
+	* ```ts
+	* // ❌ Bypasses multi-tenant scope, audit, cache invalidation:
+	* const doc = await CampaignModel.findOneAndUpdate(
+	*   { _id: id, organizationId: ctx.orgId },     // hand-rolled tenant filter
+	*   { $set: patch, $currentDate: { updatedAt: 1 } },
+	*   { new: true, runValidators: true }
+	* );
+	* return doc ? toEntity(doc) : null;
+	*
+	* // ✅ Plugin-routed; tenant + audit + cache auto-applied:
+	* const doc = await campaignRepo.update(id, patch, repoOptionsFromCtx(ctx));
+	* return doc ? toEntity(doc) : null;
+	* ```
+	*
+	* The raw-mongoose path is a recurring source of cross-tenant leaks
+	* (tenant filter forgotten on the next refactor), audit gaps (changes
+	* invisible to the compliance trail), and stale-cache bugs (cache
+	* invalidation skipped). Always route mutations through this method —
+	* the `repo.update()` keystroke count beats raw mongoose AND composes
+	* with the policy stack.
+	*
+	* **CAS / status-precondition writes — use `repo.claim()`, not `update()`.**
+	* A `findOneAndUpdate` whose filter includes an expected-state check
+	* (`{ _id, status: 'pending' }` → `{ $set: { status: 'shipped' } }`)
+	* is a compare-and-set, not a plain update. Reach for the `claim()`
+	* primitive — it expresses the transition as `{ from, to }`, returns
+	* `null` on race-loss (so callers can branch on retry), and routes
+	* through the same plugin pipeline:
+	*
+	* ```ts
+	* // ❌ Hand-rolled CAS — bypasses plugins, no typed race-loss signal:
+	* const doc = await CampaignModel.findOneAndUpdate(
+	*   { _id: id, organizationId: ctx.orgId, status: 'pending' },
+	*   { $set: { status: 'sent', sentAt: new Date() } },
+	*   { new: true }
+	* );
+	* if (!doc) throw new ConcurrentTransitionError(id);
+	*
+	* // ✅ Plugin-routed CAS with explicit transition + race-loss = null:
+	* const doc = await campaignRepo.claim(
+	*   id,
+	*   { from: 'pending', to: 'sent' },
+	*   { sentAt: new Date() },
+	*   repoOptionsFromCtx(ctx),
+	* );
+	* if (!doc) throw new ConcurrentTransitionError(id, 'pending', 'sent');
+	* ```
+	*
+	* Pair `claim()` with `defineStateMachine()` from
+	* `@classytic/primitives/state-machine` for the modelling layer
+	* (`assertTransition` catches illegal transitions sync, `claim` enforces
+	* the race-safe write) — see mongokit's CLAUDE.md "State-machine +
+	* claim() pairing" recipe. For pure dedup-on-id without a state
+	* transition (idempotency keys, webhook receivers), use `getOrCreate()`
+	* — `claim()` with `from === to === id` works too but is heavier.
+	*
+	* Domain-layer mapping (`doc → entity`) belongs on top of this call,
+	* not inside mongokit. The canonical pattern is a 3-line host helper:
+	*
+	* ```ts
+	* async function updateAndMap<TDoc, TEntity>(
+	*   repo: Repository<TDoc>,
+	*   id: string,
+	*   patch: Partial<TDoc>,
+	*   ctx: RequestContext,
+	*   mapper: (doc: TDoc) => TEntity,
+	* ): Promise<TEntity | null> {
+	*   const doc = await repo.update(id, patch, repoOptionsFromCtx(ctx));
+	*   return doc ? mapper(doc) : null;
+	* }
+	* ```
+	*
+	* Mongokit deliberately doesn't ship `updateAndMap` — host mapper
+	* signatures vary (`Result<T, E>`, throw-on-miss, audit-stamped
+	* mappers that take `ctx`, tx-scoped mappers, …) and absorbing a
+	* single shape would lock every consumer into it.
 	*/
 	async update(id, data, options = {}) {
 		const context = await this._buildContext("update", {
@@ -2859,6 +3015,17 @@ var Repository = class extends RepositoryBase {
 		});
 	}
 	/**
+	* Compliance-grade cleanup primitive — see `StandardRepo.purgeByField`
+	* for the cross-kit contract. Mongokit composes the kit-agnostic
+	* `runChunkedPurge` orchestrator (loop, signal, progress, result
+	* envelope) with `createMongoPurgePort` (driver-specific id selection
+	* + strategy writes). See [actions/purge.ts](./actions/purge.ts) for
+	* the port implementation.
+	*/
+	async purgeByField(field, value, strategy, options = {}) {
+		return runChunkedPurge(strategy, options, createMongoPurgePort(this, field, value, options.session));
+	}
+	/**
 	* Kit-native aggregation pipeline — takes a MongoDB stage array and
 	* returns the raw pipeline output. Use this for `$lookup`, `$unwind`,
 	* `$facet`, `$graphLookup`, and any other mongo-specific power

package/dist/adapter/index.mjs

@@ -1,2 +1,2 @@
-import { n as createMongooseAdapter, r as isMongooseModel, t as MongooseAdapter } from "../adapter-DTDMnUOH.mjs";
+import { n as createMongooseAdapter, r as isMongooseModel, t as MongooseAdapter } from "../adapter-gG_uyFSZ.mjs";
 export { MongooseAdapter, createMongooseAdapter, isMongooseModel };

package/dist/{adapter-DTDMnUOH.mjs → adapter-gG_uyFSZ.mjs}

@@ -10,6 +10,58 @@ function isMongooseModel(value) {
 }
 //#endregion
 //#region src/adapter/mongoose-adapter.ts
+const REQUIRED_REPO_METHODS = [
+	"getAll",
+	"getById",
+	"create",
+	"update",
+	"delete"
+];
+function describeValue(value) {
+	if (value === null) return "null";
+	if (value === void 0) return "undefined";
+	const t = typeof value;
+	if (t !== "object" && t !== "function") return t;
+	const ctor = value.constructor?.name;
+	return ctor && ctor !== "Object" ? `${t} (${ctor})` : t;
+}
+function formatInvalidModelError(model) {
+	const got = describeValue(model);
+	const hint = typeof model === "object" && model !== null && "paths" in model ? "Got a Schema — pass the value returned by mongoose.model('Name', schema), not the schema itself." : "Pass the value returned by mongoose.model('Name', schema).";
+	return [
+		"MongooseAdapter: invalid `model` — expected a Mongoose Model.",
+		`Got: ${got}`,
+		hint,
+		"",
+		"Example:",
+		"  import { Repository, createMongooseAdapter } from '@classytic/mongokit';",
+		"  const ProductModel = mongoose.model('Product', schema);",
+		"  const adapter = createMongooseAdapter({",
+		"    model: ProductModel,",
+		"    repository: new Repository(ProductModel),",
+		"  });"
+	].join("\n");
+}
+function formatInvalidRepositoryError(repository, model) {
+	const passedTheModel = repository != null && typeof repository === "object" && repository === model;
+	const looksLikeMongooseModel = isMongooseModel(repository);
+	const missing = repository && typeof repository === "object" ? REQUIRED_REPO_METHODS.filter((m) => typeof repository[m] !== "function") : [...REQUIRED_REPO_METHODS];
+	const cause = passedTheModel ? "Got the same Mongoose Model that was passed as `model` — a Model is not a Repository." : looksLikeMongooseModel ? "Got a Mongoose Model — wrap it in a Repository first." : `Got: ${describeValue(repository)}` + (missing.length && missing.length < REQUIRED_REPO_METHODS.length ? ` (missing method${missing.length === 1 ? "" : "s"}: ${missing.join(", ")})` : "");
+	return [
+		"MongooseAdapter: invalid `repository` — expected a Repository instance",
+		`(or any object implementing ${REQUIRED_REPO_METHODS.join(", ")}).`,
+		cause,
+		"",
+		"Fix: pass `new Repository(model)` from @classytic/mongokit.",
+		"",
+		"Example:",
+		"  import { Repository, createMongooseAdapter } from '@classytic/mongokit';",
+		"  const adapter = createMongooseAdapter({",
+		"    model: ProductModel,",
+		"    repository: new Repository(ProductModel),",
+		"  });"
+	].join("\n");
+}
 /**
 * Mongoose data adapter — implements the `DataAdapter<TDoc>` contract from
 * `@classytic/repo-core/adapter`.
@@ -21,8 +73,8 @@ var MongooseAdapter = class {
 	repository;
 	schemaGenerator;
 	constructor(options) {
-		if (!isMongooseModel(options.model)) throw new TypeError("MongooseAdapter: Invalid model. Expected Mongoose Model instance.\nUsage: createMongooseAdapter({ model: YourModel, repository: yourRepo })");
-		if (!isRepository(options.repository)) throw new TypeError("MongooseAdapter: Invalid repository. Expected MinimalRepo instance.\nUsage: createMongooseAdapter({ model: YourModel, repository: yourRepo })");
+		if (!isMongooseModel(options.model)) throw new TypeError(formatInvalidModelError(options.model));
+		if (!isRepository(options.repository)) throw new TypeError(formatInvalidRepositoryError(options.repository, options.model));
 		this.model = options.model;
 		this.repository = asRepositoryLike(options.repository);
 		this.schemaGenerator = options.schemaGenerator;
@@ -146,7 +198,15 @@ var MongooseAdapter = class {
 };
 function createMongooseAdapter(modelOrOptions, repository) {
 	if (isMongooseModel(modelOrOptions)) {
-		if (!repository) throw new TypeError("createMongooseAdapter: repository is required when using 2-arg form.\nUsage: createMongooseAdapter(Model, repository)");
+		if (!repository) throw new TypeError([
+			"createMongooseAdapter: `repository` argument is required.",
+			"",
+			"Fix: pass `new Repository(model)` from @classytic/mongokit.",
+			"",
+			"Example:",
+			"  import { Repository, createMongooseAdapter } from '@classytic/mongokit';",
+			"  const adapter = createMongooseAdapter(ProductModel, new Repository(ProductModel));"
+		].join("\n"));
 		return new MongooseAdapter({
 			model: modelOrOptions,
 			repository

package/dist/better-auth/index.d.mts

@@ -145,5 +145,44 @@ interface BetterAuthOverlayOptions<TDoc = Record<string, unknown>> {
  *         would silently drop this call's `additionalFields` / `indexes`).
  */
 declare function createBetterAuthOverlay<TDoc = Record<string, unknown>>(options: BetterAuthOverlayOptions<TDoc>): Promise<DataAdapter<TDoc>>;
+/**
+ * Minimal structural surface for the one write we need. Satisfied by BOTH a
+ * native MongoDB `Collection` (`db.collection('session')`) and a Mongoose
+ * `Model` — so the host passes whichever it has, and mongokit keeps mongoose +
+ * the mongodb driver as peer deps with zero runtime import.
+ */
+interface SessionUpdaterLike {
+  updateMany(filter: Record<string, unknown>, update: Record<string, unknown>): Promise<{
+    modifiedCount?: number;
+  }>;
+}
+/**
+ * Clear a dangling `activeOrganizationId` from Better Auth `session` rows.
+ *
+ * WHY THIS EXISTS: Better Auth purges its `member` / `invitation` rows when an
+ * org is deleted (or a member removed), but it NEVER clears
+ * `session.activeOrganizationId`. A session left pointing at an org the user is
+ * no longer a member of makes `organization.getActiveMember()` return
+ * `MEMBER_NOT_FOUND`, and any frontend that trusts that stale pointer hangs —
+ * amplified by `session.cookieCache`, which serves the dead pointer for minutes.
+ *
+ * This is intentionally a host-invoked helper, NOT part of the arc org-delete
+ * cascade: arc is DB-agnostic (it purges through `@classytic/repo-core`
+ * adapters and must not reach a raw collection), whereas the `session`
+ * collection is a Better-Auth/mongo concern this kit already owns. Hosts wire
+ * it into their `organizationHooks`:
+ *   - `afterDeleteOrganization` → org-wide (omit `userId`)
+ *   - `afterRemoveMember`       → one user (pass `userId`)
+ *
+ * The mongodb adapter stores `activeOrganizationId` as a STRING, so the org id
+ * is matched as-is (no ObjectId construction). `session.userId` is an ObjectId,
+ * so for the member-removal path pass `userId` already in the form your driver
+ * compares against (a constructed ObjectId) — it's matched verbatim.
+ *
+ * @returns the number of sessions whose pointer was cleared.
+ */
+declare function clearActiveOrganizationFromSessions(sessions: SessionUpdaterLike, organizationId: string, options?: {
+  userId?: unknown;
+}): Promise<number>;
 //#endregion
-export { BetterAuthInstance, BetterAuthOverlayOptions, type BetterAuthPluginKey, MongooseLike, RegisterBetterAuthStubsOptions, createBetterAuthOverlay, registerBetterAuthStubs };
+export { BetterAuthInstance, BetterAuthOverlayOptions, type BetterAuthPluginKey, MongooseLike, RegisterBetterAuthStubsOptions, SessionUpdaterLike, clearActiveOrganizationFromSessions, createBetterAuthOverlay, registerBetterAuthStubs };

package/dist/better-auth/index.mjs

@@ -1,5 +1,5 @@
-import { n as Repository } from "../Repository-BZrU_nXs.mjs";
-import { n as createMongooseAdapter } from "../adapter-DTDMnUOH.mjs";
+import { n as Repository } from "../Repository-BGL1Pq8w.mjs";
+import { n as createMongooseAdapter } from "../adapter-gG_uyFSZ.mjs";
 import { pluralizeBetterAuthCollection, resolveBetterAuthCollections } from "@classytic/repo-core/better-auth";
 //#region src/better-auth/index.ts
 /**
@@ -77,5 +77,35 @@ async function createBetterAuthOverlay(options) {
 		schemaGenerator
 	});
 }
+/**
+* Clear a dangling `activeOrganizationId` from Better Auth `session` rows.
+*
+* WHY THIS EXISTS: Better Auth purges its `member` / `invitation` rows when an
+* org is deleted (or a member removed), but it NEVER clears
+* `session.activeOrganizationId`. A session left pointing at an org the user is
+* no longer a member of makes `organization.getActiveMember()` return
+* `MEMBER_NOT_FOUND`, and any frontend that trusts that stale pointer hangs —
+* amplified by `session.cookieCache`, which serves the dead pointer for minutes.
+*
+* This is intentionally a host-invoked helper, NOT part of the arc org-delete
+* cascade: arc is DB-agnostic (it purges through `@classytic/repo-core`
+* adapters and must not reach a raw collection), whereas the `session`
+* collection is a Better-Auth/mongo concern this kit already owns. Hosts wire
+* it into their `organizationHooks`:
+*   - `afterDeleteOrganization` → org-wide (omit `userId`)
+*   - `afterRemoveMember`       → one user (pass `userId`)
+*
+* The mongodb adapter stores `activeOrganizationId` as a STRING, so the org id
+* is matched as-is (no ObjectId construction). `session.userId` is an ObjectId,
+* so for the member-removal path pass `userId` already in the form your driver
+* compares against (a constructed ObjectId) — it's matched verbatim.
+*
+* @returns the number of sessions whose pointer was cleared.
+*/
+async function clearActiveOrganizationFromSessions(sessions, organizationId, options) {
+	const filter = { activeOrganizationId: organizationId };
+	if (options?.userId != null) filter.userId = options.userId;
+	return (await sessions.updateMany(filter, { $set: { activeOrganizationId: null } })).modifiedCount ?? 0;
+}
 //#endregion
-export { createBetterAuthOverlay, registerBetterAuthStubs };
+export { clearActiveOrganizationFromSessions, createBetterAuthOverlay, registerBetterAuthStubs };

package/dist/index.d.mts

@@ -7,7 +7,7 @@ import { n as SchemaIndexes } from "./indexes-CgOF7Wjd.mjs";
 import { a as createFieldPreset, c as getMongooseProjection, d as parseDuplicateKeyError, i as configureLogger, l as createError, n as buildCrudSchemasFromMongooseSchema, o as filterResponseData, r as createMemoryCache, s as getFieldsForUser, t as buildCrudSchemasFromModel, u as isDuplicateKeyError } from "./mongooseToJsonSchema-BgRAaXX-.mjs";
 import * as _$mongoose from "mongoose";
 import { ClientSession, Expression, Model, PipelineStage, PopulateOptions } from "mongoose";
-import { AggPaginationRequest, AggRequest, AggResult, KeysetAggPaginationResult, QueryOptions, RepositoryBase } from "@classytic/repo-core/repository";
+import { AggPaginationRequest, AggRequest, AggResult, KeysetAggPaginationResult, QueryOptions, RepositoryBase, TenantPurgeOptions, TenantPurgeResult, TenantPurgeStrategy } from "@classytic/repo-core/repository";
 import { UpdateInput } from "@classytic/repo-core/update";
 import { AggregatePaginationResult, KeysetPaginationResult, OffsetPaginationResult, OffsetPaginationResultCore } from "@classytic/repo-core/pagination";
 import { HttpError } from "@classytic/repo-core/errors";
@@ -1230,7 +1230,95 @@ declare class Repository<TDoc = unknown> extends RepositoryBase {
     _id: unknown;
   } | null>;
   /**
-   * Update document by ID
+   * Update a document by id and return the post-update doc.
+   *
+   * Compiles to `Model.findOneAndUpdate(filter, { $set: data }, { new:
+   * true, runValidators: true })` under the hood and routes through the
+   * full plugin pipeline — `multiTenantPlugin` injects the tenant scope,
+   * `auditTrailPlugin` records the change, `cachePlugin` invalidates,
+   * `softDeletePlugin` etc. all compose. Returns `null` on miss (the
+   * `MinimalRepo` contract; pass `throwOnNotFound: true` for the legacy
+   * throw path).
+   *
+   * **Anti-pattern to avoid** — calling `Model.findOneAndUpdate()`
+   * directly on the raw mongoose model bypasses every plugin:
+   *
+   * ```ts
+   * // ❌ Bypasses multi-tenant scope, audit, cache invalidation:
+   * const doc = await CampaignModel.findOneAndUpdate(
+   *   { _id: id, organizationId: ctx.orgId },     // hand-rolled tenant filter
+   *   { $set: patch, $currentDate: { updatedAt: 1 } },
+   *   { new: true, runValidators: true }
+   * );
+   * return doc ? toEntity(doc) : null;
+   *
+   * // ✅ Plugin-routed; tenant + audit + cache auto-applied:
+   * const doc = await campaignRepo.update(id, patch, repoOptionsFromCtx(ctx));
+   * return doc ? toEntity(doc) : null;
+   * ```
+   *
+   * The raw-mongoose path is a recurring source of cross-tenant leaks
+   * (tenant filter forgotten on the next refactor), audit gaps (changes
+   * invisible to the compliance trail), and stale-cache bugs (cache
+   * invalidation skipped). Always route mutations through this method —
+   * the `repo.update()` keystroke count beats raw mongoose AND composes
+   * with the policy stack.
+   *
+   * **CAS / status-precondition writes — use `repo.claim()`, not `update()`.**
+   * A `findOneAndUpdate` whose filter includes an expected-state check
+   * (`{ _id, status: 'pending' }` → `{ $set: { status: 'shipped' } }`)
+   * is a compare-and-set, not a plain update. Reach for the `claim()`
+   * primitive — it expresses the transition as `{ from, to }`, returns
+   * `null` on race-loss (so callers can branch on retry), and routes
+   * through the same plugin pipeline:
+   *
+   * ```ts
+   * // ❌ Hand-rolled CAS — bypasses plugins, no typed race-loss signal:
+   * const doc = await CampaignModel.findOneAndUpdate(
+   *   { _id: id, organizationId: ctx.orgId, status: 'pending' },
+   *   { $set: { status: 'sent', sentAt: new Date() } },
+   *   { new: true }
+   * );
+   * if (!doc) throw new ConcurrentTransitionError(id);
+   *
+   * // ✅ Plugin-routed CAS with explicit transition + race-loss = null:
+   * const doc = await campaignRepo.claim(
+   *   id,
+   *   { from: 'pending', to: 'sent' },
+   *   { sentAt: new Date() },
+   *   repoOptionsFromCtx(ctx),
+   * );
+   * if (!doc) throw new ConcurrentTransitionError(id, 'pending', 'sent');
+   * ```
+   *
+   * Pair `claim()` with `defineStateMachine()` from
+   * `@classytic/primitives/state-machine` for the modelling layer
+   * (`assertTransition` catches illegal transitions sync, `claim` enforces
+   * the race-safe write) — see mongokit's CLAUDE.md "State-machine +
+   * claim() pairing" recipe. For pure dedup-on-id without a state
+   * transition (idempotency keys, webhook receivers), use `getOrCreate()`
+   * — `claim()` with `from === to === id` works too but is heavier.
+   *
+   * Domain-layer mapping (`doc → entity`) belongs on top of this call,
+   * not inside mongokit. The canonical pattern is a 3-line host helper:
+   *
+   * ```ts
+   * async function updateAndMap<TDoc, TEntity>(
+   *   repo: Repository<TDoc>,
+   *   id: string,
+   *   patch: Partial<TDoc>,
+   *   ctx: RequestContext,
+   *   mapper: (doc: TDoc) => TEntity,
+   * ): Promise<TEntity | null> {
+   *   const doc = await repo.update(id, patch, repoOptionsFromCtx(ctx));
+   *   return doc ? mapper(doc) : null;
+   * }
+   * ```
+   *
+   * Mongokit deliberately doesn't ship `updateAndMap` — host mapper
+   * signatures vary (`Result<T, E>`, throw-on-miss, audit-stamped
+   * mappers that take `ctx`, tx-scoped mappers, …) and absorbing a
+   * single shape would lock every consumer into it.
    */
   update(id: string | ObjectId, data: Record<string, unknown>, options?: UpdateOptions): Promise<TDoc | null>;
   /**
@@ -1591,6 +1679,15 @@ declare class Repository<TDoc = unknown> extends RepositoryBase {
     mode?: 'hard' | 'soft';
     [key: string]: unknown;
   }): Promise<DeleteManyResult>;
+  /**
+   * Compliance-grade cleanup primitive — see `StandardRepo.purgeByField`
+   * for the cross-kit contract. Mongokit composes the kit-agnostic
+   * `runChunkedPurge` orchestrator (loop, signal, progress, result
+   * envelope) with `createMongoPurgePort` (driver-specific id selection
+   * + strategy writes). See [actions/purge.ts](./actions/purge.ts) for
+   * the port implementation.
+   */
+  purgeByField(field: string, value: unknown, strategy: TenantPurgeStrategy, options?: TenantPurgeOptions): Promise<TenantPurgeResult>;
   /**
    * Kit-native aggregation pipeline — takes a MongoDB stage array and
    * returns the raw pipeline output. Use this for `$lookup`, `$unwind`,

package/dist/index.mjs

@@ -2,9 +2,9 @@ import { b as LookupBuilder, x as compileFilterToMongo } from "./update-BXMnCvO6
 import { n as warn, t as configureLogger } from "./logger-DprijP5h.mjs";
 import { n as isDuplicateKeyError, r as parseDuplicateKeyError, t as createError } from "./error-B00pI7dV.mjs";
 import { t as actions_exports } from "./actions/index.mjs";
-import { a as withTransaction, c as MUTATING_OPERATIONS, d as operationsByPolicyKey, i as isTransactionUnsupported, l as OP_REGISTRY, n as Repository, o as AggregationBuilder, r as batchTransaction, s as ALL_OPERATIONS, t as HOOK_PRIORITY, u as READ_OPERATIONS } from "./Repository-BZrU_nXs.mjs";
+import { a as withTransaction, c as MUTATING_OPERATIONS, d as operationsByPolicyKey, i as isTransactionUnsupported, l as OP_REGISTRY, n as Repository, o as AggregationBuilder, r as batchTransaction, s as ALL_OPERATIONS, t as HOOK_PRIORITY, u as READ_OPERATIONS } from "./Repository-BGL1Pq8w.mjs";
 import { t as PaginationEngine } from "./PaginationEngine-CfQRM1yz.mjs";
-import { A as aggregateHelpersPlugin, C as sequentialId, D as AuditTrailQuery, E as batchOperationsPlugin, O as auditTrailPlugin, S as prefixedId, T as cachePlugin, _ as fieldFilterPlugin, a as uniqueField, b as dateSequentialId, c as createTenantContext, d as observabilityPlugin, f as adminBypass, g as leasePlugin, h as methodRegistryPlugin, i as requireField, k as auditLogPlugin, l as subdocumentPlugin, m as mongoOperationsPlugin, n as blockIf, o as validationChainPlugin, p as multiTenantPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as softDeletePlugin, v as elasticSearchPlugin, w as cascadePlugin, x as getNextSequence, y as customIdPlugin } from "./validation-chain.plugin-BJwwV9jQ.mjs";
+import { A as aggregateHelpersPlugin, C as sequentialId, D as AuditTrailQuery, E as batchOperationsPlugin, O as auditTrailPlugin, S as prefixedId, T as cachePlugin, _ as fieldFilterPlugin, a as uniqueField, b as dateSequentialId, c as createTenantContext, d as observabilityPlugin, f as adminBypass, g as leasePlugin, h as methodRegistryPlugin, i as requireField, k as auditLogPlugin, l as subdocumentPlugin, m as mongoOperationsPlugin, n as blockIf, o as validationChainPlugin, p as multiTenantPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as softDeletePlugin, v as elasticSearchPlugin, w as cascadePlugin, x as getNextSequence, y as customIdPlugin } from "./validation-chain.plugin-CWhvBRej.mjs";
 import { i as getMongooseProjection, n as filterResponseData, r as getFieldsForUser, t as createFieldPreset } from "./field-selection-Br3WPOEb.mjs";
 import { isGeoOperator, parseGeoFilter } from "./query/primitives/geo.mjs";
 import { buildFieldTypeMap, coerceFieldValue, coerceHeuristic } from "./query/primitives/coercion.mjs";

package/dist/plugins/index.mjs

@@ -1,2 +1,2 @@
-import { A as aggregateHelpersPlugin, C as sequentialId, D as AuditTrailQuery, E as batchOperationsPlugin, O as auditTrailPlugin, S as prefixedId, T as cachePlugin, _ as fieldFilterPlugin, a as uniqueField, b as dateSequentialId, c as createTenantContext, d as observabilityPlugin, g as leasePlugin, h as methodRegistryPlugin, i as requireField, k as auditLogPlugin, l as subdocumentPlugin, m as mongoOperationsPlugin, n as blockIf, o as validationChainPlugin, p as multiTenantPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as softDeletePlugin, v as elasticSearchPlugin, w as cascadePlugin, x as getNextSequence, y as customIdPlugin } from "../validation-chain.plugin-BJwwV9jQ.mjs";
+import { A as aggregateHelpersPlugin, C as sequentialId, D as AuditTrailQuery, E as batchOperationsPlugin, O as auditTrailPlugin, S as prefixedId, T as cachePlugin, _ as fieldFilterPlugin, a as uniqueField, b as dateSequentialId, c as createTenantContext, d as observabilityPlugin, g as leasePlugin, h as methodRegistryPlugin, i as requireField, k as auditLogPlugin, l as subdocumentPlugin, m as mongoOperationsPlugin, n as blockIf, o as validationChainPlugin, p as multiTenantPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as softDeletePlugin, v as elasticSearchPlugin, w as cascadePlugin, x as getNextSequence, y as customIdPlugin } from "../validation-chain.plugin-CWhvBRej.mjs";
 export { AuditTrailQuery, aggregateHelpersPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, blockIf, cachePlugin, cascadePlugin, createTenantContext, customIdPlugin, dateSequentialId, elasticSearchPlugin, fieldFilterPlugin, getNextSequence, immutableField, leasePlugin, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, prefixedId, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validationChainPlugin };

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

@@ -1,7 +1,7 @@
 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-BZrU_nXs.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 mongoose from "mongoose";
 import { cachePlugin } from "@classytic/repo-core/cache";
@@ -1651,7 +1651,23 @@ function multiTenantPlugin(options = {}) {
 						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}'. Pass it via options or set required: false. For deliberate cross-tenant access (admin / migration / support), pass \`bypassTenant: true\` in the options bag for this call, or wire \`skipWhen: adminBypass({...})\` at plugin construction.`);
+					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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/mongokit",
-  "version": "3.13.4",
+  "version": "3.15.0",
   "description": "Production-grade MongoDB repositories - smart pagination, events, and plugins. Built on @classytic/repo-core.",
   "type": "module",
   "sideEffects": false,
@@ -105,7 +105,7 @@
   },
   "homepage": "https://github.com/classytic/mongokit#readme",
   "peerDependencies": {
-    "@classytic/repo-core": "^0.4.2",
+    "@classytic/repo-core": "^0.5.0",
     "better-auth": ">=1.6.0",
     "mongoose": ">=9.4.1"
   },
@@ -149,7 +149,7 @@
     "@better-auth/mongo-adapter": "^1.6.9",
     "@biomejs/biome": "^2.4.10",
     "@classytic/dev-tools": "^0.2.0",
-    "@classytic/repo-core": "0.4.2",
+    "@classytic/repo-core": "0.5.0",
     "@types/node": "^22.0.0",
     "@vitest/coverage-v8": "^3.2.4",
     "ajv": "^8.18.0",