@classytic/mongokit 3.15.0 → 3.16.0

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

@@ -1,4 +1,4 @@
-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 { 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-BWZILovv.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";
@@ -6,94 +6,6 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { OffsetPaginationResult } from "@classytic/repo-core/pagination";
 import { TenantConfig } from "@classytic/repo-core/tenant";
 
-//#region src/plugins/aggregate-helpers.plugin.d.ts
-/**
- * Aggregate helpers plugin
- *
- * @example
- * const repo = new Repository(Model, [
- *   methodRegistryPlugin(),
- *   aggregateHelpersPlugin(),
- * ]);
- *
- * const groups = await repo.groupBy('category');
- * const total = await repo.sum('amount', { status: 'completed' });
- */
-declare function aggregateHelpersPlugin(): Plugin;
-/**
- * Type interface for repositories using aggregateHelpersPlugin
- *
- * @example
- * ```typescript
- * import { Repository, methodRegistryPlugin, aggregateHelpersPlugin } from '@classytic/mongokit';
- * import type { AggregateHelpersMethods } from '@classytic/mongokit';
- *
- * class OrderRepo extends Repository<IOrder> {}
- *
- * type OrderRepoWithAggregates = OrderRepo & AggregateHelpersMethods;
- *
- * const repo = new OrderRepo(OrderModel, [
- *   methodRegistryPlugin(),
- *   aggregateHelpersPlugin(),
- * ]) as OrderRepoWithAggregates;
- *
- * // TypeScript autocomplete works!
- * const groups = await repo.groupBy('status');
- * const total = await repo.sum('amount', { status: 'completed' });
- * const avg = await repo.average('amount');
- * ```
- */
-interface AggregateHelpersMethods {
-  /**
-   * Group documents by field value and count occurrences
-   * @param field - Field to group by
-   * @param options - Operation options
-   * @returns Array of groups with _id and count
-   */
-  groupBy(field: string, options?: {
-    limit?: number;
-    session?: unknown;
-  }): Promise<Array<{
-    _id: unknown;
-    count: number;
-  }>>;
-  /**
-   * Calculate sum of field values
-   * @param field - Field to sum
-   * @param query - Filter query
-   * @param options - Operation options
-   * @returns Sum of field values
-   */
-  sum(field: string, query?: Record<string, unknown>, options?: Record<string, unknown>): Promise<number>;
-  /**
-   * Calculate average of field values
-   * @param field - Field to average
-   * @param query - Filter query
-   * @param options - Operation options
-   * @returns Average of field values
-   */
-  average(field: string, query?: Record<string, unknown>, options?: Record<string, unknown>): Promise<number>;
-  /**
-   * Get minimum field value
-   * @param field - Field to get minimum from
-   * @param query - Filter query
-   * @param options - Operation options
-   * @returns Minimum field value
-   */
-  min(field: string, query?: Record<string, unknown>, options?: Record<string, unknown>): Promise<number>;
-  /**
-   * Get maximum field value
-   * @param field - Field to get maximum from
-   * @param query - Filter query
-   * @param options - Operation options
-   * @returns Maximum field value
-   */
-  max(field: string, query?: Record<string, unknown>, options?: Record<string, unknown>): Promise<number>;
-}
-//#endregion
-//#region src/plugins/audit-log.plugin.d.ts
-declare function auditLogPlugin(logger: Logger): Plugin;
-//#endregion
 //#region src/plugins/audit-trail.plugin.d.ts
 interface AuditTrailOptions {
   /** Operations to track (default: ['create', 'update', 'delete']) */
@@ -256,53 +168,6 @@ interface AuditTrailMethods {
   }): Promise<AuditQueryResult>;
 }
 //#endregion
-//#region src/plugins/batch-operations.plugin.d.ts
-/**
- * Batch operations plugin.
- *
- * @example
- * const repo = new Repository(Model, [
- *   methodRegistryPlugin(),
- *   batchOperationsPlugin(),
- * ]);
- *
- * // updateMany + deleteMany are primitives on Repository — no plugin needed.
- * await repo.updateMany({ status: 'pending' }, { status: 'active' });
- * await repo.deleteMany({ status: 'deleted' });
- *
- * // bulkWrite is what this plugin contributes.
- * await repo.bulkWrite([...ops]);
- */
-declare function batchOperationsPlugin(): Plugin;
-interface BatchOperationsMethods {
-  /**
-   * Execute heterogeneous bulk write operations in a single database call.
-   * Supports insertOne, updateOne, updateMany, deleteOne, deleteMany, replaceOne.
-   *
-   * @param operations - Array of bulk write operations
-   * @param options - Options (session, ordered)
-   * @returns Bulk write result with counts per operation type
-   *
-   * @example
-   * const result = await repo.bulkWrite([
-   *   { insertOne: { document: { name: 'Item', price: 10 } } },
-   *   { updateOne: { filter: { _id: id }, update: { $inc: { views: 1 } } } },
-   *   { deleteOne: { filter: { _id: oldId } } },
-   * ]);
-   * console.log(result.insertedCount, result.modifiedCount, result.deletedCount);
-   */
-  bulkWrite(operations: Record<string, unknown>[], options?: {
-    session?: unknown;
-    ordered?: boolean;
-  }): Promise<BulkWriteResult>;
-}
-//#endregion
-//#region src/plugins/cascade.plugin.d.ts
-/**
- * Cascade delete plugin.
- */
-declare function cascadePlugin(options: CascadeOptions): Plugin;
-//#endregion
 //#region src/plugins/custom-id.plugin.d.ts
 /**
  * Generator function that produces a unique ID.
@@ -380,87 +245,382 @@ interface DateSequentialIdOptions {
   /** Mongoose model — used to derive the counter key */
   model: mongoose.Model<any>;
   /**
-   * Partition granularity — counter resets each period.
-   * - 'yearly'  → BILL-2026-0001, resets every January
-   * - 'monthly' → BILL-2026-02-0001, resets every month
-   * - 'daily'   → BILL-2026-02-20-0001, resets every day
+   * Partition granularity — counter resets each period.
+   * - 'yearly'  → BILL-2026-0001, resets every January
+   * - 'monthly' → BILL-2026-02-0001, resets every month
+   * - 'daily'   → BILL-2026-02-20-0001, resets every day
+   */
+  partition?: 'yearly' | 'monthly' | 'daily';
+  /** Number of digits to pad to (default: 4) */
+  padding?: number;
+  /** Separator (default: '-') */
+  separator?: string;
+}
+/**
+ * Generator: Date-partitioned sequential counter.
+ * Counter resets per period — great for invoice/bill numbering.
+ *
+ * Produces IDs like:
+ * - yearly:  `BILL-2026-0001`
+ * - monthly: `BILL-2026-02-0001`
+ * - daily:   `BILL-2026-02-20-0001`
+ *
+ * @example
+ * ```typescript
+ * customIdPlugin({
+ *   field: 'billNumber',
+ *   generator: dateSequentialId({
+ *     prefix: 'BILL',
+ *     model: BillModel,
+ *     partition: 'monthly',
+ *   }),
+ * })
+ * ```
+ */
+declare function dateSequentialId(options: DateSequentialIdOptions): IdGenerator;
+interface PrefixedIdOptions {
+  /** Prefix string (e.g., 'USR', 'TXN') */
+  prefix: string;
+  /** Separator (default: '_') */
+  separator?: string;
+  /** Length of the random suffix (default: 12) */
+  length?: number;
+}
+/**
+ * Generator: Prefix + random alphanumeric suffix.
+ * Does NOT require a database round-trip — purely in-memory.
+ *
+ * Produces IDs like: `USR_a7b3xk9m2p1q`
+ *
+ * Good for: user-facing IDs where ordering doesn't matter.
+ * Not suitable for sequential numbering.
+ *
+ * @example
+ * ```typescript
+ * customIdPlugin({
+ *   field: 'publicId',
+ *   generator: prefixedId({ prefix: 'USR', length: 10 }),
+ * })
+ * ```
+ */
+declare function prefixedId(options: PrefixedIdOptions): IdGenerator;
+/**
+ * Custom ID plugin — injects generated IDs into documents before creation.
+ *
+ * @param options - Configuration for ID generation
+ * @returns Plugin instance
+ *
+ * @example
+ * ```typescript
+ * import { Repository, customIdPlugin, sequentialId } from '@classytic/mongokit';
+ *
+ * const invoiceRepo = new Repository(InvoiceModel, [
+ *   customIdPlugin({
+ *     field: 'invoiceNumber',
+ *     generator: sequentialId({ prefix: 'INV', model: InvoiceModel }),
+ *   }),
+ * ]);
+ *
+ * const inv = await invoiceRepo.create({ amount: 100 });
+ * console.log(inv.invoiceNumber); // "INV-0001"
+ * ```
+ */
+declare function customIdPlugin(options: CustomIdOptions): Plugin;
+//#endregion
+//#region src/plugins/multi-tenant.plugin.d.ts
+/**
+ * Static tenant fields are picked from `@classytic/repo-core/tenant` so the
+ * vocabulary (`tenantField`, `contextKey`, `required`, `fieldType`) stays
+ * locked to the org-wide canonical source. Mongokit-specific runtime
+ * callbacks (`skipWhen`, `resolveContext`, `skipOperations`,
+ * `allowDataInjection`) extend on top — those genuinely differ from
+ * sqlitekit's runtime shape because mongokit's `RepositoryContext` carries
+ * Mongoose-specific bits the resolver may inspect.
+ *
+ * Mongokit defaults `fieldType` to `'string'` (not repo-core's `'objectId'`)
+ * for back-compat — pre-3.x stored tenant ids as raw strings; flipping the
+ * default would silently change cast behavior for existing apps.
+ */
+interface MultiTenantOptions extends Pick<TenantConfig, 'tenantField' | 'contextKey' | 'required' | 'fieldType'> {
+  /** Operations to skip tenant injection (e.g., for admin/system queries) */
+  skipOperations?: string[];
+  /**
+   * Dynamic skip — receives the context and operation name, returns true to
+   * bypass tenant scoping for this call. Use for role-based bypass (e.g.,
+   * super admin) without needing a separate repo instance.
+   *
+   * @example
+   * ```typescript
+   * skipWhen: (context) => context.role === 'superadmin'
+   * ```
+   */
+  skipWhen?: (context: RepositoryContext, operation: string) => boolean;
+  /**
+   * Resolve tenant ID from external source (e.g., AsyncLocalStorage, CLS).
+   * Called when tenant ID is not found in context. If it returns a value,
+   * that value is used as the tenant ID without requiring it in context.
+   *
+   * @example
+   * ```typescript
+   * resolveContext: () => asyncLocalStorage.getStore()?.tenantId
+   * ```
+   */
+  resolveContext?: () => string | undefined;
+  /**
+   * 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.
+   *
+   * **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.
+   *
+   * **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.
+   *
+   * 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;
+  /**
+   * What to do when the call's filter/payload ALREADY carries
+   * `tenantField` with a value that does NOT match the resolved tenant
+   * scope (a caller-supplied cross-tenant value — fat-fingered org id,
+   * stale client state, or an injection attempt).
+   *
+   * - `'throw'` (default, fail-closed): reject the call with a clear
+   *   error. A mismatch is never legitimate on a scoped call — callers
+   *   who genuinely need cross-tenant access use `bypassTenant: true`
+   *   (per-call) or `skipWhen` (plugin-level), both of which emit the
+   *   `after:tenant-bypass` audit event. Operator-shaped values
+   *   (`{ $in: [...] }`) on the tenant field can't be verified against
+   *   the scope and are rejected too — multi-value tenant scoping is
+   *   deliberately not supported (see CLAUDE.md); use an explicit
+   *   bypass + manual filter.
+   * - `'overwrite'` (legacy, pre-3.16 behavior): silently replace the
+   *   supplied value with the resolved scope. Still leak-safe (the
+   *   resolved scope always wins) but hides caller bugs.
+   *
+   * Matching values (same tenant, any representation — string vs
+   * ObjectId) are never a mismatch; the plugin normalizes them to the
+   * configured `fieldType`.
+   */
+  onMismatch?: 'throw' | 'overwrite';
+}
+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/aggregate-helpers.plugin.d.ts
+/**
+ * Aggregate helpers plugin
+ *
+ * @example
+ * const repo = new Repository(Model, [
+ *   methodRegistryPlugin(),
+ *   aggregateHelpersPlugin(),
+ * ]);
+ *
+ * const groups = await repo.groupBy('category');
+ * const total = await repo.sum('amount', { status: 'completed' });
+ */
+declare function aggregateHelpersPlugin(): Plugin;
+/**
+ * Type interface for repositories using aggregateHelpersPlugin
+ *
+ * @example
+ * ```typescript
+ * import { Repository, methodRegistryPlugin, aggregateHelpersPlugin } from '@classytic/mongokit';
+ * import type { AggregateHelpersMethods } from '@classytic/mongokit';
+ *
+ * class OrderRepo extends Repository<IOrder> {}
+ *
+ * type OrderRepoWithAggregates = OrderRepo & AggregateHelpersMethods;
+ *
+ * const repo = new OrderRepo(OrderModel, [
+ *   methodRegistryPlugin(),
+ *   aggregateHelpersPlugin(),
+ * ]) as OrderRepoWithAggregates;
+ *
+ * // TypeScript autocomplete works!
+ * const groups = await repo.groupBy('status');
+ * const total = await repo.sum('amount', { status: 'completed' });
+ * const avg = await repo.average('amount');
+ * ```
+ */
+interface AggregateHelpersMethods {
+  /**
+   * Group documents by field value and count occurrences
+   * @param field - Field to group by
+   * @param options - Operation options
+   * @returns Array of groups with _id and count
+   */
+  groupBy(field: string, options?: {
+    limit?: number;
+    session?: unknown;
+  }): Promise<Array<{
+    _id: unknown;
+    count: number;
+  }>>;
+  /**
+   * Calculate sum of field values
+   * @param field - Field to sum
+   * @param query - Filter query
+   * @param options - Operation options
+   * @returns Sum of field values
+   */
+  sum(field: string, query?: Record<string, unknown>, options?: Record<string, unknown>): Promise<number>;
+  /**
+   * Calculate average of field values
+   * @param field - Field to average
+   * @param query - Filter query
+   * @param options - Operation options
+   * @returns Average of field values
+   */
+  average(field: string, query?: Record<string, unknown>, options?: Record<string, unknown>): Promise<number>;
+  /**
+   * Get minimum field value
+   * @param field - Field to get minimum from
+   * @param query - Filter query
+   * @param options - Operation options
+   * @returns Minimum field value
+   */
+  min(field: string, query?: Record<string, unknown>, options?: Record<string, unknown>): Promise<number>;
+  /**
+   * Get maximum field value
+   * @param field - Field to get maximum from
+   * @param query - Filter query
+   * @param options - Operation options
+   * @returns Maximum field value
    */
-  partition?: 'yearly' | 'monthly' | 'daily';
-  /** Number of digits to pad to (default: 4) */
-  padding?: number;
-  /** Separator (default: '-') */
-  separator?: string;
+  max(field: string, query?: Record<string, unknown>, options?: Record<string, unknown>): Promise<number>;
 }
+//#endregion
+//#region src/plugins/audit-log.plugin.d.ts
+declare function auditLogPlugin(logger: Logger): Plugin;
+//#endregion
+//#region src/plugins/batch-operations.plugin.d.ts
 /**
- * Generator: Date-partitioned sequential counter.
- * Counter resets per period — great for invoice/bill numbering.
- *
- * Produces IDs like:
- * - yearly:  `BILL-2026-0001`
- * - monthly: `BILL-2026-02-0001`
- * - daily:   `BILL-2026-02-20-0001`
+ * Batch operations plugin.
  *
  * @example
- * ```typescript
- * customIdPlugin({
- *   field: 'billNumber',
- *   generator: dateSequentialId({
- *     prefix: 'BILL',
- *     model: BillModel,
- *     partition: 'monthly',
- *   }),
- * })
- * ```
- */
-declare function dateSequentialId(options: DateSequentialIdOptions): IdGenerator;
-interface PrefixedIdOptions {
-  /** Prefix string (e.g., 'USR', 'TXN') */
-  prefix: string;
-  /** Separator (default: '_') */
-  separator?: string;
-  /** Length of the random suffix (default: 12) */
-  length?: number;
-}
-/**
- * Generator: Prefix + random alphanumeric suffix.
- * Does NOT require a database round-trip — purely in-memory.
- *
- * Produces IDs like: `USR_a7b3xk9m2p1q`
+ * const repo = new Repository(Model, [
+ *   methodRegistryPlugin(),
+ *   batchOperationsPlugin(),
+ * ]);
  *
- * Good for: user-facing IDs where ordering doesn't matter.
- * Not suitable for sequential numbering.
+ * // updateMany + deleteMany are primitives on Repository — no plugin needed.
+ * await repo.updateMany({ status: 'pending' }, { status: 'active' });
+ * await repo.deleteMany({ status: 'deleted' });
  *
- * @example
- * ```typescript
- * customIdPlugin({
- *   field: 'publicId',
- *   generator: prefixedId({ prefix: 'USR', length: 10 }),
- * })
- * ```
+ * // bulkWrite is what this plugin contributes.
+ * await repo.bulkWrite([...ops]);
  */
-declare function prefixedId(options: PrefixedIdOptions): IdGenerator;
+declare function batchOperationsPlugin(): Plugin;
+interface BatchOperationsMethods {
+  /**
+   * Execute heterogeneous bulk write operations in a single database call.
+   * Supports insertOne, updateOne, updateMany, deleteOne, deleteMany, replaceOne.
+   *
+   * @param operations - Array of bulk write operations
+   * @param options - Options (session, ordered)
+   * @returns Bulk write result with counts per operation type
+   *
+   * @example
+   * const result = await repo.bulkWrite([
+   *   { insertOne: { document: { name: 'Item', price: 10 } } },
+   *   { updateOne: { filter: { _id: id }, update: { $inc: { views: 1 } } } },
+   *   { deleteOne: { filter: { _id: oldId } } },
+   * ]);
+   * console.log(result.insertedCount, result.modifiedCount, result.deletedCount);
+   */
+  bulkWrite(operations: Record<string, unknown>[], options?: {
+    session?: unknown;
+    ordered?: boolean;
+  }): Promise<BulkWriteResult>;
+}
+//#endregion
+//#region src/plugins/cascade.plugin.d.ts
 /**
- * Custom ID plugin — injects generated IDs into documents before creation.
- *
- * @param options - Configuration for ID generation
- * @returns Plugin instance
- *
- * @example
- * ```typescript
- * import { Repository, customIdPlugin, sequentialId } from '@classytic/mongokit';
- *
- * const invoiceRepo = new Repository(InvoiceModel, [
- *   customIdPlugin({
- *     field: 'invoiceNumber',
- *     generator: sequentialId({ prefix: 'INV', model: InvoiceModel }),
- *   }),
- * ]);
- *
- * const inv = await invoiceRepo.create({ amount: 100 });
- * console.log(inv.invoiceNumber); // "INV-0001"
- * ```
+ * Cascade delete plugin.
  */
-declare function customIdPlugin(options: CustomIdOptions): Plugin;
+declare function cascadePlugin(options: CascadeOptions): Plugin;
 //#endregion
 //#region src/plugins/elastic.plugin.d.ts
 interface ElasticSearchOptions {
@@ -813,142 +973,6 @@ interface MongoOperationsMethods<TDoc> {
   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
-/**
- * Static tenant fields are picked from `@classytic/repo-core/tenant` so the
- * vocabulary (`tenantField`, `contextKey`, `required`, `fieldType`) stays
- * locked to the org-wide canonical source. Mongokit-specific runtime
- * callbacks (`skipWhen`, `resolveContext`, `skipOperations`,
- * `allowDataInjection`) extend on top — those genuinely differ from
- * sqlitekit's runtime shape because mongokit's `RepositoryContext` carries
- * Mongoose-specific bits the resolver may inspect.
- *
- * Mongokit defaults `fieldType` to `'string'` (not repo-core's `'objectId'`)
- * for back-compat — pre-3.x stored tenant ids as raw strings; flipping the
- * default would silently change cast behavior for existing apps.
- */
-interface MultiTenantOptions extends Pick<TenantConfig, 'tenantField' | 'contextKey' | 'required' | 'fieldType'> {
-  /** Operations to skip tenant injection (e.g., for admin/system queries) */
-  skipOperations?: string[];
-  /**
-   * Dynamic skip — receives the context and operation name, returns true to
-   * bypass tenant scoping for this call. Use for role-based bypass (e.g.,
-   * super admin) without needing a separate repo instance.
-   *
-   * @example
-   * ```typescript
-   * skipWhen: (context) => context.role === 'superadmin'
-   * ```
-   */
-  skipWhen?: (context: RepositoryContext, operation: string) => boolean;
-  /**
-   * Resolve tenant ID from external source (e.g., AsyncLocalStorage, CLS).
-   * Called when tenant ID is not found in context. If it returns a value,
-   * that value is used as the tenant ID without requiring it in context.
-   *
-   * @example
-   * ```typescript
-   * resolveContext: () => asyncLocalStorage.getStore()?.tenantId
-   * ```
-   */
-  resolveContext?: () => string | undefined;
-  /**
-   * 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.
-   *
-   * **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.
-   *
-   * **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.
-   *
-   * 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 {
   /** Operation name (e.g., 'create', 'getAll', 'update') */
@@ -1220,4 +1244,4 @@ declare function immutableField(field: string): ValidatorDefinition;
  */
 declare function uniqueField(field: string, errorMessage?: string): ValidatorDefinition;
 //#endregion
-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 };
+export { AuditEntry as $, BulkWriteResult as A, IdGenerator as B, LeasePluginOptions as C, elasticSearchPlugin as D, ElasticSearchOptions as E, MultiTenantOptions as F, getNextSequence as G, SequentialIdOptions as H, adminBypass as I, CacheAdapter$1 as J, prefixedId as K, multiTenantPlugin as L, auditLogPlugin as M, AggregateHelpersMethods as N, cascadePlugin as O, aggregateHelpersPlugin as P, cachePlugin as Q, CustomIdOptions as R, LeaseMethods as S, fieldFilterPlugin as T, customIdPlugin as U, PrefixedIdOptions as V, dateSequentialId as W, RepositoryCacheHandle as X, CacheOptions as Y, RepositoryCachePluginOptions as Z, observabilityPlugin as _, uniqueField as a, AuditTrailQuery as at, MethodRegistryRepository as b, TenantContext as c, SubdocumentMethods as d, AuditOperation as et, subdocumentPlugin as f, OperationMetric as g, ObservabilityOptions as h, requireField as i, AuditTrailOptions as it, batchOperationsPlugin as j, BatchOperationsMethods as k, TenantStore as l, softDeletePlugin as m, blockIf as n, AuditQueryResult as nt, validationChainPlugin as o, auditTrailPlugin as ot, SoftDeleteMethods as p, sequentialId as q, immutableField as r, AuditTrailMethods as rt, timestampPlugin as s, autoInject as t, AuditQueryOptions as tt, createTenantContext as u, MongoOperationsMethods as v, leasePlugin as w, methodRegistryPlugin as x, mongoOperationsPlugin as y, DateSequentialIdOptions as z };