@classytic/mongokit 3.13.3 → 3.14.0

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

@@ -1,4 +1,4 @@
-import { a as count, b as LookupBuilder, c as getByQuery, d as deleteById, f as deleteByQuery, h as createMany, l as getOrCreate, m as create, n as update, o as exists, r as updateByQuery, s as getById, t as findOneAndUpdate, x as compileFilterToMongo, y as distinct } from "./update-C-3viiw1.mjs";
+import { a as count, b as LookupBuilder, c as getByQuery, d as deleteById, f as deleteByQuery, h as createMany, l as getOrCreate, m as create, n as update, o as exists, r as updateByQuery, s as getById, t as findOneAndUpdate, x as compileFilterToMongo, y as distinct } from "./update-BXMnCvO6.mjs";
 import { n as warn } from "./logger-DprijP5h.mjs";
 import { n as isDuplicateKeyError, r as parseDuplicateKeyError, t as createError } from "./error-B00pI7dV.mjs";
 import { t as PaginationEngine } from "./PaginationEngine-CfQRM1yz.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/actions/index.d.mts

@@ -1,2 +1,2 @@
-import { a as create_d_exports, i as delete_d_exports, n as update_d_exports, o as aggregate_d_exports, r as read_d_exports } from "../index-BbHaKwi5.mjs";
+import { a as create_d_exports, i as delete_d_exports, n as update_d_exports, o as aggregate_d_exports, r as read_d_exports } from "../index-Dccha9dw.mjs";
 export { aggregate_d_exports as aggregate, create_d_exports as create, delete_d_exports as deleteActions, read_d_exports as read, update_d_exports as update };

package/dist/actions/index.mjs

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "../chunk-CfYAbeIz.mjs";
-import { g as create_exports, i as update_exports, p as delete_exports, u as read_exports, v as aggregate_exports } from "../update-C-3viiw1.mjs";
+import { g as create_exports, i as update_exports, p as delete_exports, u as read_exports, v as aggregate_exports } from "../update-BXMnCvO6.mjs";
 //#region src/actions/index.ts
 var actions_exports = /* @__PURE__ */ __exportAll({
 	aggregate: () => aggregate_exports,

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.mjs

@@ -1,5 +1,5 @@
-import { n as Repository } from "../Repository-CNBTCVat.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
 /**

package/dist/{index-BbHaKwi5.d.mts → index-Dccha9dw.d.mts}

@@ -175,7 +175,9 @@ declare function getById<TDoc = AnyDocument>(Model: Model<TDoc>, id: string | Ob
  * @returns Document or null
  * @throws Error if document not found and throwOnNotFound is true
  */
-declare function getByQuery<TDoc = AnyDocument>(Model: Model<TDoc>, query: Record<string, unknown>, options?: OperationOptions): Promise<TDoc | null>;
+declare function getByQuery<TDoc = AnyDocument>(Model: Model<TDoc>, query: Record<string, unknown>, options?: OperationOptions & {
+  sort?: SortSpec;
+}): Promise<TDoc | null>;
 /**
  * Get document by query without throwing (returns null if not found)
  */

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { $ as RepositoryEvent, A as KeysetPaginationOptions, B as ObjectId, C as FieldPreset, Ct as IControllerResponse, D as InferDocument, Dt as LookupOptions, E as HookMode, Et as LookupBuilder, F as MiddlewareContext, G as Plugin, H as OperationOptions, I as MinMaxResult, J as PopulateSpec, K as PluginFunction, L as MinimalRepoView, M as LookupPopulateOptions, N as LookupPopulateResult, O as InferRawDoc, P as Middleware, Q as RepositoryContext, R as MongoOperatorUpdate, S as EventPhase, St as IController, T as GroupResult, Tt as IResponseFormatter, U as PaginationConfig, V as OffsetPaginationOptions, W as PartialBy, X as ReadOptions, Y as PrioritizedHook, Z as ReadPreferenceType, _ as DeleteManyResult, _t as ValidationChainOptions, a as AnyModel, at as SessionOptions, b as EventHandlers, bt as WithPlugins, c as CacheableOptions, ct as SoftDeleteRepository, d as CollationOptions, dt as Strict, et as RepositoryInstance, f as CreateInput, ft as UpdateManyResult, g as DeepPartial, gt as UserContext, h as DecodedCursor, ht as UpdateWithValidationResult, i as AnyDocument, it as SelectSpec, j as Logger, k as KeysOfType, l as CascadeOptions, lt as SortDirection, m as CursorPayload, mt as UpdatePatch, n as AggregatePaginationOptions, nt as RepositoryOptions, o as BasePaginationOptions, ot as SoftDeleteFilterMode, p as CreateOptions, pt as UpdateOptions, q as PluginType, r as AllPluginMethods, rt as RequiredBy, s as CacheOperationOptions, st as SoftDeleteOptions, t as AggregateOptions, tt as RepositoryOperation, u as CascadeRelation, ut as SortSpec, v as DeleteResult, vt as ValidatorDefinition, w as FindOneAndUpdateOptions, wt as IRequestContext, x as EventPayload, xt as WithTransactionOptions, y as DocField, yt as ValueType, z as NonNullableFields } from "./types-BbaPZleN.mjs";
-import { t as index_d_exports } from "./index-BbHaKwi5.mjs";
+import { t as index_d_exports } from "./index-Dccha9dw.mjs";
 import { PaginationEngine } from "./pagination/PaginationEngine.mjs";
 import { $ as AuditQueryResult, A as elasticSearchPlugin, B as sequentialId, D as leasePlugin, E as LeasePluginOptions, F as SequentialIdOptions, G as RepositoryCachePluginOptions, H as CacheAdapter, I as customIdPlugin, J as BulkWriteResult, K as cachePlugin, L as dateSequentialId, M as DateSequentialIdOptions, N as IdGenerator, O as fieldFilterPlugin, P as PrefixedIdOptions, Q as AuditQueryOptions, R as getNextSequence, S as mongoOperationsPlugin, T as LeaseMethods, U as CacheOptions, V as cascadePlugin, W as RepositoryCacheHandle, X as AuditEntry, Y as batchOperationsPlugin, Z as AuditOperation, _ as observabilityPlugin, a as uniqueField, at as AggregateHelpersMethods, b as multiTenantPlugin, c as TenantContext, d as SubdocumentMethods, et as AuditTrailMethods, f as subdocumentPlugin, g as OperationMetric, h as ObservabilityOptions, i as requireField, it as auditLogPlugin, j as CustomIdOptions, k as ElasticSearchOptions, l as TenantStore, m as softDeletePlugin, n as blockIf, nt as AuditTrailQuery, o as validationChainPlugin, ot as aggregateHelpersPlugin, p as SoftDeleteMethods, q as BatchOperationsMethods, r as immutableField, rt as auditTrailPlugin, s as timestampPlugin, t as autoInject, tt as AuditTrailOptions, u as createTenantContext, v as MultiTenantOptions, w as methodRegistryPlugin, x as MongoOperationsMethods, y as adminBypass, z as prefixedId } from "./validation-chain.plugin-CAPYCj_T.mjs";
 import { n as SchemaPathsLike, t as FieldType$1 } from "./coercion-TRMmR49h.mjs";
@@ -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";
@@ -1095,7 +1095,9 @@ declare class Repository<TDoc = unknown> extends RepositoryBase {
   /**
    * Get single document by query
    */
-  getByQuery(query: Record<string, unknown>, options?: CacheableOptions): Promise<TDoc | null>;
+  getByQuery(query: Record<string, unknown>, options?: CacheableOptions & {
+    sort?: SortSpec;
+  }): Promise<TDoc | null>;
   /**
    * Get single document by arbitrary filter.
    * Unlike getByQuery, this method is designed for Arc/controller use where
@@ -1104,7 +1106,9 @@ declare class Repository<TDoc = unknown> extends RepositoryBase {
    * @example
    * const product = await repo.getOne({ slug: 'laptop', organizationId: 'org_1' });
    */
-  getOne(query: Record<string, unknown>, options?: CacheableOptions): Promise<TDoc | null>;
+  getOne(query: Record<string, unknown>, options?: CacheableOptions & {
+    sort?: SortSpec;
+  }): Promise<TDoc | null>;
   /**
    * Fetch ALL documents matching filters without pagination.
    * Use for background jobs, exports, batch processing where you need every doc.
@@ -1226,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>;
   /**
@@ -1587,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`,
@@ -2137,6 +2238,80 @@ declare function repoOptionsFromCtx<TCtx extends Record<string, unknown>>(ctx: T
  *   options bag never erases inherited values).
  */
 declare function createOptionsExtractor<TCtx extends Record<string, unknown>>(fields: readonly (keyof TCtx & string)[]): (ctx: TCtx | undefined | null) => Record<string, unknown>;
+/**
+ * Canonical options bag for repo calls made OUTSIDE any request scope —
+ * event handlers, cron jobs, queue workers, migration scripts.
+ *
+ * `multiTenantPlugin` requires `organizationId` in the operation
+ * context so reads/writes can't leak across tenants from the request
+ * layer. Background work has no inherited request scope; calling a
+ * tenant-aware repo from an event subscriber without a bypass throws:
+ *
+ *   "[mongokit] Multi-tenant: Missing 'organizationId' in context for ..."
+ *
+ * Worse, if the call site is wrapped in `try/catch` (as event handlers
+ * routinely are — they fire-and-forget), the error is swallowed and
+ * the side effect silently doesn't happen. We've shipped that bug.
+ *
+ * `systemContext()` returns the canonical opts bag for that case —
+ * currently `{ bypassTenant: true }`. The multi-tenant plugin still
+ * emits an `after:tenant-bypass` audit event with `reason: 'option'`
+ * so observability sees these calls distinct from request-scoped ones.
+ *
+ * **Greppable on purpose.** A reviewer scanning the codebase can find
+ * every "I'm running outside any tenant scope" callsite by searching
+ * `systemContext(` — no chasing magic option spreads.
+ *
+ * **NOT a substitute for proper access control.** Same caveat as raw
+ * `bypassTenant`: this bypasses tenant scoping; it does NOT bypass
+ * authentication or RBAC. Use only at trusted boundaries — event
+ * handlers wired at startup, cron jobs scheduled in code, scripts
+ * running with admin credentials.
+ *
+ * The `extra` overload composes cleanly with transaction sessions and
+ * audit-attribution fields; the function's `bypassTenant: true` is
+ * applied last so it cannot be accidentally overridden.
+ *
+ * @example Event handler
+ * ```ts
+ * import { systemContext } from '@classytic/mongokit';
+ *
+ * order.events.subscribe('order:completed', async (event) => {
+ *   const matches = await enrollmentRepo.aggregatePipeline(
+ *     [{ $match: { orderId: event.payload.orderId, status: 'active' } }],
+ *     systemContext(),
+ *   );
+ *   for (const m of matches) {
+ *     await enrollmentRepo.update(m._id, { status: 'fulfilled' }, systemContext());
+ *   }
+ * });
+ * ```
+ *
+ * @example Composed with a transaction
+ * ```ts
+ * await withTransaction(conn, async (session) => {
+ *   await enrollmentRepo.update(id, data, systemContext({ session }));
+ *   await auditRepo.create(entry, systemContext({ session }));
+ * });
+ * ```
+ *
+ * @example Cron / scheduled cleanup
+ * ```ts
+ * for await (const doc of repo.cursor(
+ *   { expiresAt: { $lt: new Date() } },
+ *   systemContext(),
+ * )) {
+ *   await repo.delete(doc._id, systemContext());
+ * }
+ * ```
+ *
+ * @param extra - Optional extra options to merge in (e.g. `session`
+ *   for transactions, `userId` for audit attribution). Any
+ *   `bypassTenant` value here is overridden — the function name is
+ *   load-bearing.
+ * @returns A `SessionOptions` object with `bypassTenant: true` set.
+ */
+declare function systemContext(extra?: SessionOptions): SessionOptions;
 //#endregion
 //#region src/index.d.ts
 /**
@@ -2151,4 +2326,4 @@ declare function createOptionsExtractor<TCtx extends Record<string, unknown>>(fi
  */
 declare function createRepository<TDoc>(Model: _$mongoose.Model<TDoc, any, any, any>, plugins?: PluginType[], paginationConfig?: PaginationConfig, options?: RepositoryOptions): Repository<TDoc>;
 //#endregion
-export { ALL_OPERATIONS, type AggregateHelpersMethods, type AggregateOptions, type AggregatePaginationOptions, AggregationBuilder, type AllPluginMethods, type AnyDocument, type AnyModel, type AuditEntry, type AuditOperation, type AuditQueryOptions, type AuditQueryResult, type AuditTrailMethods, type AuditTrailOptions, AuditTrailQuery, type BasePaginationOptions, type BatchOperationsMethods, type BulkWriteResult, type CacheAdapter, type CacheOperationOptions, type CacheOptions, type CacheableOptions, type CascadeOptions, type CascadeRelation, type CollationOptions, type CreateInput, type CreateOptions, type CursorPayload, type CustomIdOptions, type DateSequentialIdOptions, type DecodedCursor, type DeepPartial, type DeleteResult, type DocField, type ElasticSearchOptions, type EventHandlers, type EventPayload, type EventPhase, type FieldPreset, type FieldType, type FilterQuery, type FindOneAndUpdateOptions, type GroupResult, HOOK_PRIORITY, type HookMode, type IController, type IControllerResponse, type IRequestContext, type IResponseFormatter, type IdGenerator, type InferDocument, type InferRawDoc, type KeysOfType, type KeysetPaginationOptions, type LeaseMethods, type LeasePluginOptions, type Logger, LookupBuilder, type LookupOptions, type LookupPopulateOptions, type LookupPopulateResult, MUTATING_OPERATIONS, type Middleware, type MiddlewareContext, type MinMaxResult, type MinimalRepoView, type MongoOperationsMethods, type MongoOperatorUpdate, type MultiTenantOptions, type NonNullableFields, OP_REGISTRY, type ObjectId, type ObservabilityOptions, type OffsetPaginationOptions, type OperationDescriptor, type OperationMetric, type OperationOptions, type PaginationConfig, PaginationEngine, type ParsedQuery, type PartialBy, type Plugin, type PluginFunction, type PluginType, type PolicyKey, type PopulateOption, type PopulateSpec, type PrefixedIdOptions, type PrioritizedHook, QueryParser, type QueryParserOptions, READ_OPERATIONS, type ReadOptions, type ReadPreferenceType, Repository, Repository as default, type RepositoryCacheHandle, type RepositoryCachePluginOptions, type RepositoryContext, type RepositoryEvent, type RepositoryInstance, type RepositoryOperation, type RepositoryOptions, type RequiredBy, type SchemaLike, type SearchMode, type SelectSpec, type SequentialIdOptions, type SessionOptions, type SoftDeleteFilterMode, type SoftDeleteMethods, type SoftDeleteOptions, type SoftDeleteRepository, type SortDirection, type SortSpec, type Strict, type SubdocumentMethods, type TenantContext, type TenantStore, type UpdateManyResult, type UpdateOptions, type UpdatePatch, type UpdateWithValidationResult, type UserContext, type ValidationChainOptions, type ValidatorDefinition, type ValueType, type WithPlugins, type WithTransactionOptions, index_d_exports as actions, adminBypass, aggregateHelpersPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, batchTransaction, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, cascadePlugin, compileFilterToMongo, configureLogger, createError, createFieldPreset, createMemoryCache, createOptionsExtractor, createRepository, createTenantContext, customIdPlugin, dateSequentialId, elasticSearchPlugin, fieldFilterPlugin, filterResponseData, getFieldsForUser, getMongooseProjection, getNextSequence, immutableField, isDuplicateKeyError, isTransactionUnsupported, leasePlugin, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, operationsByPolicyKey, parseDuplicateKeyError, prefixedId, repoOptionsFromCtx, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validationChainPlugin, withTransaction };
+export { ALL_OPERATIONS, type AggregateHelpersMethods, type AggregateOptions, type AggregatePaginationOptions, AggregationBuilder, type AllPluginMethods, type AnyDocument, type AnyModel, type AuditEntry, type AuditOperation, type AuditQueryOptions, type AuditQueryResult, type AuditTrailMethods, type AuditTrailOptions, AuditTrailQuery, type BasePaginationOptions, type BatchOperationsMethods, type BulkWriteResult, type CacheAdapter, type CacheOperationOptions, type CacheOptions, type CacheableOptions, type CascadeOptions, type CascadeRelation, type CollationOptions, type CreateInput, type CreateOptions, type CursorPayload, type CustomIdOptions, type DateSequentialIdOptions, type DecodedCursor, type DeepPartial, type DeleteResult, type DocField, type ElasticSearchOptions, type EventHandlers, type EventPayload, type EventPhase, type FieldPreset, type FieldType, type FilterQuery, type FindOneAndUpdateOptions, type GroupResult, HOOK_PRIORITY, type HookMode, type IController, type IControllerResponse, type IRequestContext, type IResponseFormatter, type IdGenerator, type InferDocument, type InferRawDoc, type KeysOfType, type KeysetPaginationOptions, type LeaseMethods, type LeasePluginOptions, type Logger, LookupBuilder, type LookupOptions, type LookupPopulateOptions, type LookupPopulateResult, MUTATING_OPERATIONS, type Middleware, type MiddlewareContext, type MinMaxResult, type MinimalRepoView, type MongoOperationsMethods, type MongoOperatorUpdate, type MultiTenantOptions, type NonNullableFields, OP_REGISTRY, type ObjectId, type ObservabilityOptions, type OffsetPaginationOptions, type OperationDescriptor, type OperationMetric, type OperationOptions, type PaginationConfig, PaginationEngine, type ParsedQuery, type PartialBy, type Plugin, type PluginFunction, type PluginType, type PolicyKey, type PopulateOption, type PopulateSpec, type PrefixedIdOptions, type PrioritizedHook, QueryParser, type QueryParserOptions, READ_OPERATIONS, type ReadOptions, type ReadPreferenceType, Repository, Repository as default, type RepositoryCacheHandle, type RepositoryCachePluginOptions, type RepositoryContext, type RepositoryEvent, type RepositoryInstance, type RepositoryOperation, type RepositoryOptions, type RequiredBy, type SchemaLike, type SearchMode, type SelectSpec, type SequentialIdOptions, type SessionOptions, type SoftDeleteFilterMode, type SoftDeleteMethods, type SoftDeleteOptions, type SoftDeleteRepository, type SortDirection, type SortSpec, type Strict, type SubdocumentMethods, type TenantContext, type TenantStore, type UpdateManyResult, type UpdateOptions, type UpdatePatch, type UpdateWithValidationResult, type UserContext, type ValidationChainOptions, type ValidatorDefinition, type ValueType, type WithPlugins, type WithTransactionOptions, index_d_exports as actions, adminBypass, aggregateHelpersPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, batchTransaction, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, cascadePlugin, compileFilterToMongo, configureLogger, createError, createFieldPreset, createMemoryCache, createOptionsExtractor, createRepository, createTenantContext, customIdPlugin, dateSequentialId, elasticSearchPlugin, fieldFilterPlugin, filterResponseData, getFieldsForUser, getMongooseProjection, getNextSequence, immutableField, isDuplicateKeyError, isTransactionUnsupported, leasePlugin, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, operationsByPolicyKey, parseDuplicateKeyError, prefixedId, repoOptionsFromCtx, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, systemContext, timestampPlugin, uniqueField, validationChainPlugin, withTransaction };

package/dist/index.mjs

@@ -1,10 +1,10 @@
-import { b as LookupBuilder, x as compileFilterToMongo } from "./update-C-3viiw1.mjs";
+import { b as LookupBuilder, x as compileFilterToMongo } from "./update-BXMnCvO6.mjs";
 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-CNBTCVat.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-Bbbnq8ay.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";
@@ -1207,6 +1207,85 @@ function createOptionsExtractor(fields) {
 		return out;
 	};
 }
+/**
+* Canonical options bag for repo calls made OUTSIDE any request scope —
+* event handlers, cron jobs, queue workers, migration scripts.
+*
+* `multiTenantPlugin` requires `organizationId` in the operation
+* context so reads/writes can't leak across tenants from the request
+* layer. Background work has no inherited request scope; calling a
+* tenant-aware repo from an event subscriber without a bypass throws:
+*
+*   "[mongokit] Multi-tenant: Missing 'organizationId' in context for ..."
+*
+* Worse, if the call site is wrapped in `try/catch` (as event handlers
+* routinely are — they fire-and-forget), the error is swallowed and
+* the side effect silently doesn't happen. We've shipped that bug.
+*
+* `systemContext()` returns the canonical opts bag for that case —
+* currently `{ bypassTenant: true }`. The multi-tenant plugin still
+* emits an `after:tenant-bypass` audit event with `reason: 'option'`
+* so observability sees these calls distinct from request-scoped ones.
+*
+* **Greppable on purpose.** A reviewer scanning the codebase can find
+* every "I'm running outside any tenant scope" callsite by searching
+* `systemContext(` — no chasing magic option spreads.
+*
+* **NOT a substitute for proper access control.** Same caveat as raw
+* `bypassTenant`: this bypasses tenant scoping; it does NOT bypass
+* authentication or RBAC. Use only at trusted boundaries — event
+* handlers wired at startup, cron jobs scheduled in code, scripts
+* running with admin credentials.
+*
+* The `extra` overload composes cleanly with transaction sessions and
+* audit-attribution fields; the function's `bypassTenant: true` is
+* applied last so it cannot be accidentally overridden.
+*
+* @example Event handler
+* ```ts
+* import { systemContext } from '@classytic/mongokit';
+*
+* order.events.subscribe('order:completed', async (event) => {
+*   const matches = await enrollmentRepo.aggregatePipeline(
+*     [{ $match: { orderId: event.payload.orderId, status: 'active' } }],
+*     systemContext(),
+*   );
+*   for (const m of matches) {
+*     await enrollmentRepo.update(m._id, { status: 'fulfilled' }, systemContext());
+*   }
+* });
+* ```
+*
+* @example Composed with a transaction
+* ```ts
+* await withTransaction(conn, async (session) => {
+*   await enrollmentRepo.update(id, data, systemContext({ session }));
+*   await auditRepo.create(entry, systemContext({ session }));
+* });
+* ```
+*
+* @example Cron / scheduled cleanup
+* ```ts
+* for await (const doc of repo.cursor(
+*   { expiresAt: { $lt: new Date() } },
+*   systemContext(),
+* )) {
+*   await repo.delete(doc._id, systemContext());
+* }
+* ```
+*
+* @param extra - Optional extra options to merge in (e.g. `session`
+*   for transactions, `userId` for audit attribution). Any
+*   `bypassTenant` value here is overridden — the function name is
+*   load-bearing.
+* @returns A `SessionOptions` object with `bypassTenant: true` set.
+*/
+function systemContext(extra) {
+	return {
+		...extra,
+		bypassTenant: true
+	};
+}
 //#endregion
 //#region src/index.ts
 /**
@@ -1224,4 +1303,4 @@ function createRepository(Model, plugins = [], paginationConfig = {}, options =
 }
 var src_default = Repository;
 //#endregion
-export { ALL_OPERATIONS, AggregationBuilder, AuditTrailQuery, HOOK_PRIORITY, LookupBuilder, MUTATING_OPERATIONS, OP_REGISTRY, PaginationEngine, QueryParser, READ_OPERATIONS, Repository, actions_exports as actions, adminBypass, aggregateHelpersPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, batchTransaction, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, cascadePlugin, compileFilterToMongo, configureLogger, createError, createFieldPreset, createMemoryCache, createOptionsExtractor, createRepository, createTenantContext, customIdPlugin, dateSequentialId, src_default as default, elasticSearchPlugin, fieldFilterPlugin, filterResponseData, getFieldsForUser, getMongooseProjection, getNextSequence, immutableField, isDuplicateKeyError, isTransactionUnsupported, leasePlugin, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, operationsByPolicyKey, parseDuplicateKeyError, prefixedId, repoOptionsFromCtx, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validationChainPlugin, withTransaction };
+export { ALL_OPERATIONS, AggregationBuilder, AuditTrailQuery, HOOK_PRIORITY, LookupBuilder, MUTATING_OPERATIONS, OP_REGISTRY, PaginationEngine, QueryParser, READ_OPERATIONS, Repository, actions_exports as actions, adminBypass, aggregateHelpersPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, batchTransaction, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, cascadePlugin, compileFilterToMongo, configureLogger, createError, createFieldPreset, createMemoryCache, createOptionsExtractor, createRepository, createTenantContext, customIdPlugin, dateSequentialId, src_default as default, elasticSearchPlugin, fieldFilterPlugin, filterResponseData, getFieldsForUser, getMongooseProjection, getNextSequence, immutableField, isDuplicateKeyError, isTransactionUnsupported, leasePlugin, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, operationsByPolicyKey, parseDuplicateKeyError, prefixedId, repoOptionsFromCtx, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, systemContext, timestampPlugin, uniqueField, validationChainPlugin, withTransaction };

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-Bbbnq8ay.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/{update-C-3viiw1.mjs → update-BXMnCvO6.mjs}

@@ -864,6 +864,7 @@ async function getByQuery(Model, query, options = {}) {
 	const mongoQuery = Model.findOne(query);
 	if (options.select) mongoQuery.select(options.select);
 	if (options.populate) mongoQuery.populate(parsePopulate$1(options.populate));
+	if (options.sort) mongoQuery.sort(options.sort);
 	if (options.lean) mongoQuery.lean();
 	if (options.session) mongoQuery.session(options.session);
 	if (options.readPreference) mongoQuery.read(options.readPreference);

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

@@ -1,7 +1,7 @@
-import { _ as upsert } from "./update-C-3viiw1.mjs";
+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-CNBTCVat.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.3",
+  "version": "3.14.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",