@classytic/mongokit 3.12.0 → 3.13.0

package/dist/{update-CDxPtpsk.mjs → update-DLcSSa5b.mjs}

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "./chunk-CfYAbeIz.mjs";
-import { r as warn } from "./logger-8-VS1za6.mjs";
+import { n as warn } from "./logger-DprijP5h.mjs";
 import { t as createError } from "./error-B00pI7dV.mjs";
 import { isFilter } from "@classytic/repo-core/filter";
 //#region src/filter/compile.ts
@@ -475,17 +475,17 @@ async function aggregatePaginate(Model, pipeline, options = {}) {
 	const skip = (page - 1) * limit;
 	if (limit > 1e3) warn(`[mongokit] Large aggregation limit (${limit}). $facet results must be <16MB. Consider using Repository.aggregatePaginate() for safer handling of large datasets.`);
 	const facetPipeline = [...pipeline, { $facet: {
-		docs: [{ $skip: skip }, { $limit: limit }],
+		data: [{ $skip: skip }, { $limit: limit }],
 		total: [{ $count: "count" }]
 	} }];
 	const aggregation = Model.aggregate(facetPipeline);
 	if (options.session) aggregation.session(options.session);
 	const [result] = await aggregation.exec();
-	const docs = result.docs || [];
+	const data = result.data || [];
 	const total = result.total[0]?.count || 0;
 	const pages = Math.ceil(total / limit);
 	return {
-		docs,
+		data,
 		total,
 		page,
 		limit,
@@ -662,54 +662,49 @@ var delete_exports = /* @__PURE__ */ __exportAll({
 	softDelete: () => softDelete
 });
 /**
-* Delete by ID
+* Delete by ID. Returns `null` on miss (matches `update()` convention) —
+* a second delete on the same id is a no-op, not an error.
 */
 async function deleteById(Model, id, options = {}) {
 	const query = {
 		_id: id,
 		...options.query
 	};
-	if (!await Model.findOneAndDelete(query).session(options.session ?? null)) return {
-		success: false,
-		message: "Document not found",
-		id: String(id)
-	};
+	if (!await Model.findOneAndDelete(query).session(options.session ?? null)) return null;
 	return {
-		success: true,
 		message: "Deleted successfully",
 		id: String(id)
 	};
 }
 /**
-* Delete many documents
+* Delete many documents. Always returns a {@link DeleteResult} (never
+* null) — a deleteMany with zero matches is a successful op with
+* `count: 0`, not a miss.
 */
 async function deleteMany(Model, query, options = {}) {
 	return {
-		success: true,
 		count: (await Model.deleteMany(query).session(options.session ?? null)).deletedCount,
 		message: "Deleted successfully"
 	};
 }
 /**
-* Delete by query
+* Delete by query. Returns `null` on miss unless `throwOnNotFound: true`.
 */
 async function deleteByQuery(Model, query, options = {}) {
 	const document = await Model.findOneAndDelete(query).session(options.session ?? null);
 	if (!document) {
 		if (options.throwOnNotFound === true) throw createError(404, "Document not found");
-		return {
-			success: false,
-			message: "Document not found"
-		};
+		return null;
 	}
 	return {
-		success: true,
 		message: "Deleted successfully",
 		id: String(document._id)
 	};
 }
 /**
-* Soft delete (set deleted flag)
+* Soft delete (set deleted flag). Returns `null` on miss for parity with
+* `deleteById`; callers that prefer a throw can wrap or use `throwOnNotFound`
+* pattern at the call site.
 */
 async function softDelete(Model, id, options = {}) {
 	if (!await Model.findByIdAndUpdate(id, {
@@ -719,16 +714,15 @@ async function softDelete(Model, id, options = {}) {
 	}, {
 		returnDocument: "after",
 		session: options.session
-	})) throw createError(404, "Document not found");
+	})) return null;
 	return {
-		success: true,
 		message: "Soft deleted successfully",
 		id: String(id),
 		soft: true
 	};
 }
 /**
-* Restore soft deleted document
+* Restore soft-deleted document. Returns `null` on miss.
 */
 async function restore(Model, id, options = {}) {
 	if (!await Model.findByIdAndUpdate(id, {
@@ -738,9 +732,8 @@ async function restore(Model, id, options = {}) {
 	}, {
 		returnDocument: "after",
 		session: options.session
-	})) throw createError(404, "Document not found");
+	})) return null;
 	return {
-		success: true,
 		message: "Restored successfully",
 		id: String(id)
 	};
@@ -834,16 +827,37 @@ async function getAll(Model, query = {}, options = {}) {
 	return mongoQuery.exec();
 }
 /**
-* Get or create document (upsert)
+* Get or create document (atomic upsert).
+*
+* Returns `{ doc, created }` so callers can disambiguate the two
+* outcomes without a follow-up read — load-bearing for race-detection
+* in idempotency stores, lock acquisition, and "ensure-exists" flows.
+*
+* `created: true` ⇔ this caller's `createData` won the race and was
+* just inserted; `created: false` ⇔ a doc matching `query` already
+* existed and was returned unchanged.
+*
+* Mongo: `includeResultMetadata: true` returns the raw `ModifyResult`
+* (`{ value, lastErrorObject, ok }`). `lastErrorObject.upserted` is
+* the `_id` of a freshly-inserted row — present iff this call inserted.
 */
 async function getOrCreate(Model, query, createData, options = {}) {
-	return Model.findOneAndUpdate(query, { $setOnInsert: createData }, {
+	const result = await Model.findOneAndUpdate(query, { $setOnInsert: createData }, {
 		upsert: true,
 		returnDocument: "after",
 		runValidators: true,
+		includeResultMetadata: true,
 		session: options.session,
 		...options.updatePipeline !== void 0 ? { updatePipeline: options.updatePipeline } : {}
 	});
+	if (result && typeof result === "object" && "value" in result) return {
+		doc: result.value,
+		created: result.lastErrorObject?.upserted != null
+	};
+	return {
+		doc: result,
+		created: false
+	};
 }
 /**
 * Count documents matching query

package/dist/utils/index.d.mts

@@ -1,94 +1,5 @@
-import { lt as SortSpec, q as PopulateSpec, rt as SelectSpec } from "../types-DXscZnLu.mjs";
-import { a as createFieldPreset, c as getMongooseProjection, i as configureLogger, l as createError, n as buildCrudSchemasFromMongooseSchema, o as filterResponseData, r as createMemoryCache, s as getFieldsForUser, t as buildCrudSchemasFromModel } from "../mongooseToJsonSchema-rtkdbBhf.mjs";
+import { a as createFieldPreset, c as getMongooseProjection, i as configureLogger, l as createError, n as buildCrudSchemasFromMongooseSchema, o as filterResponseData, r as createMemoryCache, s as getFieldsForUser, t as buildCrudSchemasFromModel } from "../mongooseToJsonSchema-BgRAaXX-.mjs";
 
-//#region src/utils/cache-keys.d.ts
-/**
- * Generate cache key for getById operations
- *
- * Includes select/populate/lean in the key so different query shapes
- * (e.g., plain vs populated, lean vs hydrated) never collide.
- *
- * Format: {prefix}:id:{model}:{documentId} (no options)
- * Format: {prefix}:id:{model}:{documentId}:{optionsHash} (with options)
- *
- * @example
- * byIdKey('mk', 'User', '507f1f77bcf86cd799439011')
- * // => 'mk:id:User:507f1f77bcf86cd799439011'
- * byIdKey('mk', 'User', '507f1f77bcf86cd799439011', { select: 'name email' })
- * // => 'mk:id:User:507f1f77bcf86cd799439011:a1b2c3d4'
- */
-declare function byIdKey(prefix: string, model: string, id: string, options?: {
-  select?: SelectSpec;
-  populate?: PopulateSpec;
-  lean?: boolean;
-}): string;
-/**
- * Generate cache key for single-document queries
- *
- * Format: {prefix}:one:{model}:{queryHash}
- *
- * @example
- * byQueryKey('mk', 'User', { email: 'john@example.com' })
- * // => 'mk:one:User:a1b2c3d4'
- */
-declare function byQueryKey(prefix: string, model: string, version: number, query: Record<string, unknown>, options?: {
-  select?: SelectSpec;
-  populate?: PopulateSpec;
-}): string;
-/**
- * Generate cache key for paginated list queries
- *
- * Format: {prefix}:list:{model}:{version}:{queryHash}
- *
- * The version component enables efficient bulk invalidation:
- * - On any mutation, bump the version
- * - All list cache keys become invalid without scanning/deleting each
- *
- * @example
- * listQueryKey('mk', 'User', 1, { filters: { status: 'active' }, page: 1, limit: 20 })
- * // => 'mk:list:User:1:e5f6g7h8'
- */
-declare function listQueryKey(prefix: string, model: string, version: number, params: {
-  filters?: Record<string, unknown>;
-  sort?: SortSpec;
-  page?: number;
-  limit?: number;
-  after?: string;
-  select?: SelectSpec;
-  populate?: PopulateSpec;
-  search?: string;
-  mode?: string;
-  lean?: boolean;
-  readPreference?: string;
-  hint?: string | Record<string, unknown>;
-  maxTimeMS?: number;
-  countStrategy?: string;
-}): string;
-/**
- * Generate cache key for collection version tag
- *
- * Format: {prefix}:ver:{model}
- *
- * Used to track mutation version for list invalidation
- */
-declare function versionKey(prefix: string, model: string): string;
-/**
- * Generate pattern for clearing all cache keys for a model
- *
- * Format: {prefix}:*:{model}:*
- *
- * @example
- * modelPattern('mk', 'User')
- * // => 'mk:*:User:*'
- */
-declare function modelPattern(prefix: string, model: string): string;
-/**
- * Generate pattern for clearing all list cache keys for a model
- *
- * Format: {prefix}:list:{model}:*
- */
-declare function listPattern(prefix: string, model: string): string;
-//#endregion
 //#region src/utils/id-resolution.d.ts
 /**
  * ID Resolution Primitive
@@ -146,4 +57,4 @@ declare function getSchemaIdType(schema?: SchemaLike | null): IdType;
  */
 declare function isValidIdForType(id: unknown, idType: IdType): boolean;
 //#endregion
-export { type IdType, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, byIdKey, byQueryKey, configureLogger, createError, createFieldPreset, createMemoryCache, filterResponseData, getFieldsForUser, getMongooseProjection, getSchemaIdType, isObjectIdInstance, isValidIdForType, listPattern, listQueryKey, modelPattern, versionKey };
+export { type IdType, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, configureLogger, createError, createFieldPreset, createMemoryCache, filterResponseData, getFieldsForUser, getMongooseProjection, getSchemaIdType, isObjectIdInstance, isValidIdForType };

package/dist/utils/index.mjs

@@ -1,6 +1,6 @@
-import { t as configureLogger } from "../logger-8-VS1za6.mjs";
+import { t as configureLogger } from "../logger-DprijP5h.mjs";
 import { t as createError } from "../error-B00pI7dV.mjs";
-import { n as isObjectIdInstance, r as isValidIdForType, t as getSchemaIdType } from "../id-resolution-e4BT9zAV.mjs";
-import { a as byIdKey, c as listQueryKey, i as getMongooseProjection, l as modelPattern, n as filterResponseData, o as byQueryKey, r as getFieldsForUser, s as listPattern, t as createFieldPreset, u as versionKey } from "../field-selection-dI0m4RBs.mjs";
-import { n as buildCrudSchemasFromMongooseSchema, r as createMemoryCache, t as buildCrudSchemasFromModel } from "../mongooseToJsonSchema-B187ufOP.mjs";
-export { buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, byIdKey, byQueryKey, configureLogger, createError, createFieldPreset, createMemoryCache, filterResponseData, getFieldsForUser, getMongooseProjection, getSchemaIdType, isObjectIdInstance, isValidIdForType, listPattern, listQueryKey, modelPattern, versionKey };
+import { i as getMongooseProjection, n as filterResponseData, r as getFieldsForUser, t as createFieldPreset } from "../field-selection-Br3WPOEb.mjs";
+import { n as isObjectIdInstance, r as isValidIdForType, t as getSchemaIdType } from "../id-resolution-B0Odvvou.mjs";
+import { n as buildCrudSchemasFromMongooseSchema, r as createMemoryCache, t as buildCrudSchemasFromModel } from "../mongooseToJsonSchema-BYbG894y.mjs";
+export { buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, configureLogger, createError, createFieldPreset, createMemoryCache, filterResponseData, getFieldsForUser, getMongooseProjection, getSchemaIdType, isObjectIdInstance, isValidIdForType };

package/dist/{validation-chain.plugin-CH-xPoKM.d.mts → validation-chain.plugin-CAPYCj_T.d.mts}

@@ -1,5 +1,6 @@
-import { $ as RepositoryInstance, E as FieldPreset, P as Logger, W as Plugin, Z as RepositoryContext, _t as ValidationChainOptions, f as CascadeOptions, l as CacheOptions, lt as SortSpec, ot as SoftDeleteOptions, q as PopulateSpec, rt as SelectSpec, u as CacheStats, vt as ValidatorDefinition, z as ObjectId } from "./types-DXscZnLu.mjs";
+import { B as ObjectId, C as FieldPreset, G as Plugin, J as PopulateSpec, Q as RepositoryContext, _t as ValidationChainOptions, et as RepositoryInstance, it as SelectSpec, j as Logger, l as CascadeOptions, st as SoftDeleteOptions, ut as SortSpec, vt as ValidatorDefinition } from "./types-BbaPZleN.mjs";
 import mongoose from "mongoose";
+import { CacheAdapter as CacheAdapter$1, CacheOptions, RepositoryCacheHandle, RepositoryCachePluginOptions, cachePlugin } from "@classytic/repo-core/cache";
 import { BulkWriteResult } from "@classytic/repo-core/repository";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { OffsetPaginationResult } from "@classytic/repo-core/pagination";
@@ -91,12 +92,6 @@ interface AggregateHelpersMethods {
 }
 //#endregion
 //#region src/plugins/audit-log.plugin.d.ts
-/**
- * Audit log plugin that logs all repository operations
- *
- * @example
- * const repo = new Repository(Model, [auditLogPlugin(console)]);
- */
 declare function auditLogPlugin(logger: Logger): Plugin;
 //#endregion
 //#region src/plugins/audit-trail.plugin.d.ts
@@ -121,6 +116,22 @@ interface AuditTrailOptions {
    * These fields are redacted in the `changes` diff.
    */
   excludeFields?: string[];
+  /**
+   * Custom callback fired when an audit write fails. Receives the error
+   * and the entry that failed to land. Default: `console.warn` only.
+   *
+   * **Use this for compliance-grade audit trails (SOC 2 / PCI / HIPAA)
+   * where missing entries must be surfaced upstream** — e.g. forward to
+   * a dead-letter queue, page on-call, or short-circuit the request.
+   * The default `warn` log is appropriate for development and
+   * eventually-consistent observability use cases but is invisible to
+   * compliance review.
+   *
+   * The callback runs on the same fire-and-forget microtask that wrote
+   * the entry, so throwing from here will surface as an unhandled
+   * rejection — handle (or rethrow into your error reporter) inside.
+   */
+  onWriteError?: (error: Error, entry: Omit<AuditEntry, 'timestamp'>) => void;
 }
 type AuditOperation = 'create' | 'update' | 'delete' | 'findOneAndUpdate';
 interface AuditEntry {
@@ -150,7 +161,7 @@ interface AuditQueryOptions {
   limit?: number;
 }
 interface AuditQueryResult {
-  docs: AuditEntry[];
+  data: AuditEntry[];
   page: number;
   limit: number;
   total: number;
@@ -286,64 +297,6 @@ interface BatchOperationsMethods {
   }): Promise<BulkWriteResult>;
 }
 //#endregion
-//#region src/plugins/cache.plugin.d.ts
-/**
- * Cache plugin factory
- *
- * @param options - Cache configuration
- * @returns Plugin instance
- */
-declare function cachePlugin(options: CacheOptions): Plugin;
-/**
- * TypeScript interface for cache plugin methods
- *
- * @example
- * ```typescript
- * import type { CacheMethods } from '@classytic/mongokit';
- *
- * type ProductRepoWithCache = ProductRepo & CacheMethods;
- *
- * const productRepo = new ProductRepo(ProductModel, [
- *   methodRegistryPlugin(),
- *   cachePlugin({ adapter: redisAdapter, ttl: 60 }),
- * ]) as ProductRepoWithCache;
- *
- * // TypeScript autocomplete for cache methods
- * await productRepo.invalidateCache(productId);
- * await productRepo.invalidateListCache();
- * await productRepo.invalidateAllCache();
- * const stats = productRepo.getCacheStats();
- * productRepo.resetCacheStats();
- * ```
- */
-interface CacheMethods {
-  /**
-   * Invalidate cache for a specific document
-   * Use when document was updated outside this service
-   * @param id - Document ID to invalidate
-   */
-  invalidateCache(id: string): Promise<void>;
-  /**
-   * Invalidate all list caches for this model
-   * Use when bulk changes happened outside this service
-   */
-  invalidateListCache(): Promise<void>;
-  /**
-   * Invalidate ALL cache entries for this model
-   * Nuclear option - use sparingly
-   */
-  invalidateAllCache(): Promise<void>;
-  /**
-   * Get cache statistics for monitoring
-   * @returns Cache statistics (hits, misses, sets, invalidations)
-   */
-  getCacheStats(): CacheStats;
-  /**
-   * Reset cache statistics
-   */
-  resetCacheStats(): void;
-}
-//#endregion
 //#region src/plugins/cascade.plugin.d.ts
 /**
  * Cascade delete plugin.
@@ -535,6 +488,85 @@ declare function elasticSearchPlugin(options: ElasticSearchOptions): Plugin;
  */
 declare function fieldFilterPlugin(fieldPreset: FieldPreset): Plugin;
 //#endregion
+//#region src/plugins/lease.plugin.d.ts
+interface LeasePluginOptions {
+  /** Field carrying the row's status. @default `'status'` */
+  statusField?: string;
+  /** Field stamping the lease holder. @default `'leasedBy'` */
+  leasedByField?: string;
+  /** Field carrying the lease expiry timestamp. @default `'leaseExpiresAt'` */
+  leaseExpiresAtField?: string;
+  /** Status value an unleased row carries. @default `'pending'` */
+  pendingStatus?: string;
+  /** Status value a leased row carries. @default `'processing'` */
+  processingStatus?: string;
+  /** Status value a successfully released row carries. @default `'done'` */
+  doneStatus?: string;
+  /** Sort fields used to pick the FIFO winner from the lease pool. @default `{ createdAt: 1 }` */
+  sort?: Record<string, 1 | -1>;
+}
+/**
+ * Methods contributed by `leasePlugin()`. Use as a type assertion when
+ * constructing the repo so call sites get autocomplete:
+ *
+ * ```ts
+ * type OutboxRepo = Repository<IOutboxRow> & LeaseMethods<IOutboxRow>;
+ * const repo = new Repository(OutboxModel, [
+ *   methodRegistryPlugin(),
+ *   leasePlugin({ pendingStatus: 'queued' }),
+ * ]) as OutboxRepo;
+ * ```
+ */
+interface LeaseMethods<TDoc> {
+  /**
+   * Atomically claim the next available row. Matches rows that are
+   * either in `pendingStatus` OR have an expired `leaseExpiresAt` (dead
+   * lease recovery). Sets status to `processingStatus`, stamps
+   * `leasedBy`, and pushes `leaseExpiresAt = now + leaseFor`.
+   *
+   * @returns The leased doc, or `null` when no row matches.
+   */
+  lease(opts: {
+    filter?: Record<string, unknown>;
+    leaseFor: number;
+    leasedBy: string;
+    options?: Record<string, unknown>;
+  }): Promise<TDoc | null>;
+  /**
+   * Push a held lease's expiry further. Only succeeds when the lease
+   * is still ours (`leasedBy === leasedBy && leaseExpiresAt > now`).
+   * Returns `null` if the lease was lost — caller should drop the
+   * work, since someone else has already started replaying it.
+   */
+  extend(id: string | ObjectId, opts: {
+    leasedBy: string;
+    leaseFor: number;
+    options?: Record<string, unknown>;
+  }): Promise<TDoc | null>;
+  /**
+   * Release a held lease. CAS-checks `leasedBy === opts.leasedBy` AND
+   * `leaseExpiresAt > now` so only the live lease holder may finalise
+   * the row — symmetrical with `extend()`. A worker whose lease has
+   * been recovered (lease lost) MUST NOT mark someone else's
+   * in-progress work as `done` / `failed`; this method returns `null`
+   * in that race rather than overwriting.
+   *
+   * Sets status to `opts.finalStatus` (default `doneStatus`), clears
+   * `leasedBy` and `leaseExpiresAt`. Use `{ finalStatus: 'failed' }`
+   * for error paths so terminal-status filters (next caller's
+   * `lease()` predicate) skip this row.
+   *
+   * Returns the released doc, or `null` when the CAS lost (lease
+   * expired / held by another worker / row gone).
+   */
+  release(id: string | ObjectId, opts: {
+    leasedBy: string;
+    finalStatus?: string;
+    options?: Record<string, unknown>;
+  }): Promise<TDoc | null>;
+}
+declare function leasePlugin(options?: LeasePluginOptions): Plugin;
+//#endregion
 //#region src/plugins/method-registry.plugin.d.ts
 /**
  * Extended repository interface with method registry
@@ -752,6 +784,33 @@ interface MongoOperationsMethods<TDoc> {
    * });
    */
   atomicUpdate(id: string | ObjectId, operators: Record<string, Record<string, unknown>>, options?: Record<string, unknown>): Promise<TDoc>;
+  /**
+   * Atomic conditional increment — increments the field only when it is
+   * strictly below `ceiling`. Returns the updated document on success,
+   * `null` when already at/above the ceiling.
+   *
+   * Single-round-trip CAS via `findOneAndUpdate({ _id, field: { $lt:
+   * ceiling }}, { $inc: { field: by }})`. Use for per-document
+   * concurrency limits, quotas, and capacity caps where a read-then-
+   * write loop would race.
+   *
+   * @param id - Document ID
+   * @param field - Numeric field to increment
+   * @param ceiling - Increment only when the field is `< ceiling`
+   * @param by - Increment delta (default `1`; pass negative to decrement-with-floor by inverting the predicate via the call site)
+   * @param options - Operation options (session, etc.)
+   * @returns The updated document, or `null` when at/above ceiling
+   *
+   * @example Per-tenant concurrency limit
+   * ```ts
+   * const claimed = await repo.incrementIfBelow(tenantId, 'activeRuns', 10);
+   * if (!claimed) throw new ConcurrencyLimitExceeded();
+   * try { await runWorkflow(); } finally {
+   *   await repo.decrement(tenantId, 'activeRuns');
+   * }
+   * ```
+   */
+  incrementIfBelow(id: string | ObjectId, field: string, ceiling: number, by?: number, options?: Record<string, unknown>): Promise<TDoc | null>;
 }
 //#endregion
 //#region src/plugins/multi-tenant.plugin.d.ts
@@ -794,28 +853,101 @@ interface MultiTenantOptions extends Pick<TenantConfig, 'tenantField' | 'context
    */
   resolveContext?: () => string | undefined;
   /**
-   * When `true` (default), bypass the `required` throw if the operation's
-   * policy target already carries the tenant field. This lets hosts that
-   * stamp the tenant into the payload themselves (e.g., `data[tenantField]`
+   * When `true`, bypass the `required` throw if the operation's policy
+   * target already carries the tenant field. This lets hosts that stamp
+   * the tenant into the payload themselves (e.g., `data[tenantField]`
    * on writes, `filters[tenantField]` on paginated reads) use the plugin
    * without having to hand-roll a `skipWhen` that duplicates this check.
    *
-   * Set to `false` to restore the pre-data-injection strict behavior: the
-   * tenant MUST come from `context` or `resolveContext`, otherwise the
-   * plugin throws (when `required: true`).
+   * **Default: `false` (secure / fail-closed).** Tenant scope MUST come
+   * from `context` or `resolveContext`, otherwise the plugin throws
+   * (when `required: true`). This is the right posture for a security-
+   * sensitive boundary: caller-supplied scope on the payload cannot be
+   * trusted as authentication. If a host control-plane has already
+   * authenticated the tenant out-of-band and stamps it onto every
+   * write/read, set this to `true` explicitly — making the trust model
+   * visible at the call site.
    *
-   * Composition: a user-supplied `skipWhen` still runs first and can always
-   * opt out. This option controls the behavior after `skipWhen` and
-   * `resolveContext` have had their turn.
+   * **Migration from < 4.0:** the prior default was `true`. To preserve
+   * the old behavior verbatim, set `allowDataInjection: true`. To get
+   * the new secure default, leave it unset.
    *
-   * Safety: when the payload supplies the tenant, the plugin skips its own
-   * injection (it does not overwrite). Cross-tenant isolation is therefore
-   * only as strong as the caller's own stamping — same guarantee as a
-   * hand-rolled `skipWhen`.
+   * Composition: a user-supplied `skipWhen` still runs first and can
+   * always opt out. This option controls the behavior after `skipWhen`
+   * and `resolveContext` have had their turn.
+   *
+   * Safety: when the payload supplies the tenant AND this is `true`,
+   * the plugin skips its own injection (it does not overwrite). Cross-
+   * tenant isolation is therefore only as strong as the caller's own
+   * stamping — same guarantee as a hand-rolled `skipWhen`.
    */
   allowDataInjection?: boolean;
 }
 declare function multiTenantPlugin(options?: MultiTenantOptions): Plugin;
+/**
+ * Build the canonical `skipWhen` callback for role-based tenant
+ * bypass — replaces the hand-rolled
+ * `(ctx) => ctx.role === 'superadmin'` callback that ~6 packages
+ * across the classytic codebase carry as boilerplate. Eliminates the
+ * "I forgot to include 'platform_admin'" drift class — the role
+ * vocabulary lives in one place.
+ *
+ * **Composes with `bypassTenant: true` per-call**, doesn't replace
+ * it. `bypassTenant` is the deliberate per-call form for migration
+ * scripts and one-off admin queries; `adminBypass` is the
+ * always-on role-based bypass for users whose JWT / session carries
+ * a privileged role.
+ *
+ * **NOT a substitute for authentication or RBAC.** This factory only
+ * answers "should the tenant scope hook fire for this call?" — it
+ * does NOT validate that the caller is authenticated, that their
+ * role claim is genuine, or that the requested operation is
+ * permitted. Always run auth + RBAC before the call reaches the
+ * repository layer; this is the LAST gate, not the only one.
+ *
+ * @example Single role
+ * ```ts
+ * import { adminBypass, multiTenantPlugin } from '@classytic/mongokit';
+ *
+ * const repo = new Repository(InvoiceModel, [
+ *   multiTenantPlugin({
+ *     tenantField: 'organizationId',
+ *     skipWhen: adminBypass({ adminRoles: ['superadmin'] }),
+ *   }),
+ * ]);
+ *
+ * await repo.getAll({}, { role: 'superadmin' }); // sees all orgs
+ * await repo.getAll({}, { role: 'user', organizationId: 'org-1' }); // scoped
+ * ```
+ *
+ * @example Multiple admin roles + custom field name
+ * ```ts
+ * skipWhen: adminBypass({
+ *   roleField: 'principalRole',                  // ctx.principalRole, not ctx.role
+ *   adminRoles: ['superadmin', 'platform_admin', 'support'],
+ * }),
+ * ```
+ *
+ * @example Composing with custom logic
+ * ```ts
+ * // adminBypass for the role check, then your own additional logic:
+ * const adminCheck = adminBypass({ adminRoles: ['superadmin'] });
+ * skipWhen: (ctx, op) => adminCheck(ctx, op) || ctx.internalSystemFlag === true,
+ * ```
+ *
+ * @param options.roleField - Path on the context to read the role
+ *   from. Defaults to `'role'`. Top-level keys only — for nested
+ *   shapes (e.g. `ctx.user.role`), wrap your own `(ctx) => …` callback
+ *   instead.
+ * @param options.adminRoles - Role values that grant the bypass. The
+ *   factory does an exact-match `includes` check — case-sensitive,
+ *   no fuzzy matching. Lowercase your role vocabulary upstream.
+ * @returns A `skipWhen`-compatible callback `(ctx, op) → boolean`.
+ */
+declare function adminBypass(options: {
+  roleField?: string;
+  adminRoles: readonly string[];
+}): (context: RepositoryContext, operation: string) => boolean;
 //#endregion
 //#region src/plugins/observability.plugin.d.ts
 interface OperationMetric {
@@ -1088,4 +1220,4 @@ declare function immutableField(field: string): ValidatorDefinition;
  */
 declare function uniqueField(field: string, errorMessage?: string): ValidatorDefinition;
 //#endregion
-export { aggregateHelpersPlugin as $, PrefixedIdOptions as A, BatchOperationsMethods as B, methodRegistryPlugin as C, CustomIdOptions as D, elasticSearchPlugin as E, prefixedId as F, AuditQueryOptions as G, batchOperationsPlugin as H, sequentialId as I, AuditTrailOptions as J, AuditQueryResult as K, cascadePlugin as L, customIdPlugin as M, dateSequentialId as N, DateSequentialIdOptions as O, getNextSequence as P, AggregateHelpersMethods as Q, CacheMethods as R, MethodRegistryRepository as S, ElasticSearchOptions as T, AuditEntry as U, BulkWriteResult as V, AuditOperation as W, auditTrailPlugin as X, AuditTrailQuery as Y, auditLogPlugin as Z, observabilityPlugin as _, uniqueField as a, MongoOperationsMethods as b, TenantContext as c, SubdocumentMethods as d, subdocumentPlugin as f, OperationMetric as g, ObservabilityOptions as h, requireField as i, SequentialIdOptions as j, IdGenerator as k, TenantStore as l, softDeletePlugin as m, blockIf as n, validationChainPlugin as o, SoftDeleteMethods as p, AuditTrailMethods as q, immutableField as r, timestampPlugin as s, autoInject as t, createTenantContext as u, MultiTenantOptions as v, fieldFilterPlugin as w, mongoOperationsPlugin as x, multiTenantPlugin as y, cachePlugin as z };
+export { AuditQueryResult as $, elasticSearchPlugin as A, sequentialId as B, MethodRegistryRepository as C, leasePlugin as D, LeasePluginOptions as E, SequentialIdOptions as F, RepositoryCachePluginOptions as G, CacheAdapter$1 as H, customIdPlugin as I, BulkWriteResult as J, cachePlugin as K, dateSequentialId as L, DateSequentialIdOptions as M, IdGenerator as N, fieldFilterPlugin as O, PrefixedIdOptions as P, AuditQueryOptions as Q, getNextSequence as R, mongoOperationsPlugin as S, LeaseMethods as T, CacheOptions as U, cascadePlugin as V, RepositoryCacheHandle as W, AuditEntry as X, batchOperationsPlugin as Y, AuditOperation as Z, observabilityPlugin as _, uniqueField as a, AggregateHelpersMethods as at, multiTenantPlugin as b, TenantContext as c, SubdocumentMethods as d, AuditTrailMethods as et, subdocumentPlugin as f, OperationMetric as g, ObservabilityOptions as h, requireField as i, auditLogPlugin as it, CustomIdOptions as j, ElasticSearchOptions as k, TenantStore as l, softDeletePlugin as m, blockIf as n, AuditTrailQuery as nt, validationChainPlugin as o, aggregateHelpersPlugin as ot, SoftDeleteMethods as p, BatchOperationsMethods as q, immutableField as r, auditTrailPlugin as rt, timestampPlugin as s, autoInject as t, AuditTrailOptions as tt, createTenantContext as u, MultiTenantOptions as v, methodRegistryPlugin as w, MongoOperationsMethods as x, adminBypass as y, prefixedId as z };