@classytic/mongokit 3.23.0 → 3.25.0

package/dist/types-BtMuhoX5.d.mts

@@ -1,1830 +0,0 @@
-import { DeleteManyResult, DeleteResult, LookupPopulateResult, RepositoryBase, UpdateManyResult } from "@classytic/repo-core/repository";
-import { Document, Model, PipelineStage, PopulateOptions, Types } from "mongoose";
-import { Filter } from "@classytic/repo-core/filter";
-import { ValidationResult } from "@classytic/repo-core/schema";
-import { AnyPaginationResult, OffsetPaginationResult } from "@classytic/repo-core/pagination";
-import { HttpError } from "@classytic/repo-core/errors";
-//#region src/query/LookupBuilder.d.ts
-interface LookupOptions {
-  /** Collection to join with */
-  from: string;
-  /** Field from the input documents */
-  localField: string;
-  /** Field from the documents of the "from" collection */
-  foreignField: string;
-  /** Name of the new array field to add to the input documents */
-  as?: string;
-  /** Whether to unwrap array to single object */
-  single?: boolean;
-  /**
-   * Field selection on the joined collection (shorthand for `$project`).
-   * Three accepted shapes — all map to a single `$project` stage:
-   *   - `string` — CSV form (`'name,price'`); leading `-` marks an exclusion.
-   *   - `readonly string[]` — array form (`['name', 'price']` / `['-status']`);
-   *     mirrors `repo-core/lookup` `LookupSpec.select` for cross-kit parity.
-   *   - `Record<string, 0 | 1>` — explicit Mongo projection map.
-   */
-  select?: string | readonly string[] | Record<string, 0 | 1>;
-  /** Additional pipeline to run on the joined collection */
-  pipeline?: PipelineStage[];
-  /** Optional let variables for pipeline */
-  let?: Record<string, string>;
-  /** Query filter to apply before join (legacy, for aggregate.ts compatibility) */
-  query?: Record<string, unknown>;
-  /** Query options (legacy, for aggregate.ts compatibility) */
-  options?: {
-    session?: unknown;
-  };
-  /** Sanitize pipeline stages (default: true). Set false only for trusted server-side pipelines */
-  sanitize?: boolean;
-  /**
-   * Joined-side filter, compiled into a `$match` stage inside the lookup
-   * pipeline AFTER the auto-generated join correlation. Mirrors
-   * `repo-core/lookup/types.ts#LookupSpec.where` and sqlitekit's
-   * predicate-on-the-JOIN behavior, so cross-kit code that narrows the
-   * foreign side (`where: eq('status', 'active')`) gets identical rows
-   * from both backends.
-   *
-   * Accepts Filter IR or a plain mongo query — `compileFilterToMongo`
-   * routes each correctly.
-   */
-  where?: Filter | Record<string, unknown>;
-}
-/**
- * Fluent builder for MongoDB $lookup aggregation stage
- * Optimized for custom field joins at scale
- */
-declare class LookupBuilder {
-  private options;
-  constructor(from?: string);
-  /**
-   * Set the collection to join with
-   */
-  from(collection: string): this;
-  /**
-   * Set the local field (source collection)
-   * IMPORTANT: This field should be indexed for optimal performance
-   */
-  localField(field: string): this;
-  /**
-   * Set the foreign field (target collection)
-   * IMPORTANT: This field should be indexed (preferably unique) for optimal performance
-   */
-  foreignField(field: string): this;
-  /**
-   * Set the output field name
-   * Defaults to the collection name if not specified
-   */
-  as(fieldName: string): this;
-  /**
-   * Mark this lookup as returning a single document
-   * Automatically unwraps the array result to a single object or null
-   */
-  single(isSingle?: boolean): this;
-  /**
-   * Add a pipeline to filter/transform joined documents
-   * Useful for filtering, sorting, or limiting joined results
-   *
-   * @example
-   * ```typescript
-   * lookup.pipeline([
-   *   { $match: { status: 'active' } },
-   *   { $sort: { priority: -1 } },
-   *   { $limit: 5 }
-   * ]);
-   * ```
-   */
-  pipeline(stages: PipelineStage[]): this;
-  /**
-   * Set let variables for use in pipeline
-   * Allows referencing local document fields in the pipeline
-   */
-  let(variables: Record<string, string>): this;
-  /**
-   * Control pipeline sanitization (default: true)
-   * Set to false for auto-generated pipelines that are known safe
-   */
-  sanitize(enabled: boolean): this;
-  /**
-   * Build the $lookup aggregation stage(s)
-   * Returns an array of pipeline stages including $lookup and optional $unwind
-   *
-   * IMPORTANT: MongoDB $lookup has two mutually exclusive forms:
-   * 1. Simple form: { from, localField, foreignField, as }
-   * 2. Pipeline form: { from, let, pipeline, as }
-   *
-   * When pipeline or let is specified, we use the pipeline form.
-   * Otherwise, we use the simpler localField/foreignField form.
-   */
-  build(): PipelineStage[];
-  /**
-   * Build and return only the $lookup stage (without $unwind)
-   * Useful when you want to handle unwrapping yourself
-   */
-  buildLookupOnly(): PipelineStage.Lookup;
-  /**
-   * Static helper: Create a simple lookup in one line
-   */
-  static simple(from: string, localField: string, foreignField: string, options?: {
-    as?: string;
-    single?: boolean;
-  }): PipelineStage[];
-  /**
-   * Static helper: Create multiple lookups at once
-   *
-   * @example
-   * ```typescript
-   * const pipeline = LookupBuilder.multiple([
-   *   { from: 'departments', localField: 'deptSlug', foreignField: 'slug', single: true },
-   *   { from: 'managers', localField: 'managerId', foreignField: '_id', single: true }
-   * ]);
-   * ```
-   */
-  static multiple(lookups: LookupOptions[]): PipelineStage[];
-  /**
-   * Static helper: Create a nested lookup (lookup within lookup)
-   * Useful for multi-level joins like Order -> Product -> Category
-   *
-   * @example
-   * ```typescript
-   * // Join orders with products, then products with categories
-   * const pipeline = LookupBuilder.nested([
-   *   { from: 'products', localField: 'productSku', foreignField: 'sku', as: 'product', single: true },
-   *   { from: 'categories', localField: 'product.categorySlug', foreignField: 'slug', as: 'product.category', single: true }
-   * ]);
-   * ```
-   */
-  static nested(lookups: LookupOptions[]): PipelineStage[];
-  /**
-   * Sanitize pipeline stages by blocking dangerous stages and operators.
-   * Used internally by build() and available for external use (e.g., aggregate.ts).
-   */
-  static sanitizePipeline(stages: PipelineStage[]): PipelineStage[];
-  /**
-   * Recursively remove dangerous operators from an expression object.
-   */
-  private static _sanitizeDeep;
-}
-/**
- * Performance Guidelines for $lookup at Scale:
- *
- * 1. **Index Requirements** (Critical for millions of records):
- *    - localField should be indexed on source collection
- *    - foreignField should be indexed on target collection (unique index preferred)
- *
- *    Example:
- *    ```typescript
- *    // Employee collection
- *    employeeSchema.index({ departmentSlug: 1 });
- *
- *    // Department collection
- *    departmentSchema.index({ slug: 1 }, { unique: true });
- *    ```
- *
- * 2. **Query Performance**:
- *    - With proper indexes: O(log n) per lookup
- *    - Without indexes: O(n * m) - AVOID THIS!
- *    - Use explain() to verify index usage: IXSCAN (good) vs COLLSCAN (bad)
- *
- * 3. **Pipeline Optimization**:
- *    - Place $match stages as early as possible
- *    - Use $project to reduce field size before lookups
- *    - Limit joined results with pipeline: [{ $match: {...} }, { $limit: n }]
- *
- * 4. **Memory Considerations**:
- *    - Each lookup creates a new field in memory
- *    - Use $project after lookup to remove unnecessary fields
- *    - Consider allowDiskUse: true for very large datasets
- *
- * 5. **Alternative Approaches**:
- *    - For 1:1 relationships with high read frequency: Consider storing ObjectId + slug
- *    - For read-heavy workloads: Consider caching or materialized views
- *    - For real-time dashboards: Consider separate aggregation collections
- */
-//#endregion
-//#region src/plugins/names.d.ts
-/**
- * Canonical identifiers exposed by mongokit's bundled plugins.
- *
- * Use these values with `RepositoryOptions.requirePlugins` and
- * `OperationOptions.skipPlugins` instead of repeating string literals.
- * The values intentionally preserve the plugins' existing public names.
- */
-declare const MONGOKIT_PLUGIN_NAMES: {
-  readonly aggregateHelpers: 'aggregate-helpers';
-  readonly appendOnly: 'appendOnly';
-  readonly auditLog: 'auditLog';
-  readonly auditTrail: 'auditTrail';
-  readonly batchOperations: 'batch-operations';
-  readonly cache: 'cache';
-  readonly cascade: 'cascade';
-  readonly changeLog: 'changeLog';
-  readonly customId: 'custom-id';
-  readonly elasticSearch: 'elastic-search';
-  readonly fieldFilter: 'fieldFilter';
-  readonly immutableStates: 'immutableStates';
-  readonly lease: 'lease';
-  readonly methodRegistry: 'method-registry';
-  readonly mongoOperations: 'mongo-operations';
-  readonly multiTenant: 'multi-tenant';
-  readonly observability: 'observability';
-  readonly softDelete: 'softDelete';
-  readonly subdocument: 'subdocument';
-  readonly timestamp: 'timestamp';
-  readonly validationChain: 'validation-chain';
-};
-type MongoKitPluginName = (typeof MONGOKIT_PLUGIN_NAMES)[keyof typeof MONGOKIT_PLUGIN_NAMES];
-/** Bundled-name autocomplete while remaining open to third-party plugins. */
-type RepositoryPluginName = MongoKitPluginName | (string & Record<never, never>);
-//#endregion
-//#region src/types/controller.types.d.ts
-/**
- * Framework-agnostic request context
- *
- * Extract this from your framework's request object:
- * - Express: { query: req.query, body: req.body, params: req.params, user: req.user }
- * - Fastify: { query: request.query, body: request.body, params: request.params, user: request.user }
- * - Next.js: { query: searchParams, body: await request.json(), params: params, user: await getUser() }
- *
- * @example
- * ```typescript
- * // Express
- * const context: IRequestContext = {
- *   query: req.query,
- *   body: req.body,
- *   params: req.params,
- *   user: req.user,
- *   context: { organizationId: req.headers['x-org-id'] }
- * };
- *
- * // Fastify
- * const context: IRequestContext = {
- *   query: request.query,
- *   body: request.body,
- *   params: request.params,
- *   user: request.user,
- * };
- *
- * // Next.js App Router
- * const context: IRequestContext = {
- *   query: Object.fromEntries(request.nextUrl.searchParams),
- *   body: await request.json(),
- *   params: params,
- *   user: await auth(),
- * };
- * ```
- */
-interface IRequestContext {
-  /** Query parameters (from URL query string) */
-  query: Record<string, unknown>;
-  /** Request body (parsed JSON) */
-  body: Record<string, unknown>;
-  /** Route parameters (dynamic segments in URL) */
-  params: Record<string, string>;
-  /**
-   * Authenticated user (from your auth middleware)
-   * Shape depends on your auth system
-   */
-  user?: {
-    id: string;
-    role?: string;
-    [key: string]: unknown;
-  };
-  /**
-   * Custom context (tenant ID, organization, locale, etc.)
-   * Use this for multi-tenant apps, feature flags, etc.
-   */
-  context?: Record<string, unknown>;
-}
-/**
- * Framework-agnostic controller response
- *
- * Your controller methods should return this shape.
- * Adapt it to your framework's response format in the handler layer.
- *
- * @example
- * ```typescript
- * // In controller method
- * async list(context: IRequestContext): Promise<IControllerResponse> {
- *   const result = await this.repository.getAll(context.query);
- *   return {
- *     success: true,
- *     data: result,
- *     status: 200,
- *   };
- * }
- *
- * // In Express handler
- * const response = await controller.list(context);
- * res.status(response.status).json(response);
- *
- * // In Fastify handler
- * const response = await controller.list(context);
- * return reply.code(response.status).send(response);
- *
- * // In Next.js handler
- * const response = await controller.list(context);
- * return NextResponse.json(response.data, { status: response.status });
- * ```
- */
-interface IControllerResponse<T = unknown> {
-  /** Whether the operation succeeded */
-  success: boolean;
-  /** Response data (undefined on error) */
-  data?: T;
-  /** Error message (only if success = false) */
-  error?: string;
-  /** Additional error details (validation errors, stack trace, etc.) */
-  details?: unknown;
-  /** HTTP status code */
-  status: number;
-  /** Optional metadata (pagination info, warnings, etc.) */
-  meta?: Record<string, unknown>;
-}
-/**
- * Framework-agnostic CRUD controller interface
- *
- * Implement this interface in your controller classes.
- * Each method receives a framework-agnostic context and returns a framework-agnostic response.
- *
- * @template TDoc - The Mongoose document type
- *
- * @example
- * ```typescript
- * import { IController, IRequestContext, IControllerResponse } from '@mongokit/core';
- *
- * class UserController implements IController<IUser> {
- *   async list(context: IRequestContext): Promise<IControllerResponse> {
- *     // Implementation
- *   }
- *
- *   async get(context: IRequestContext): Promise<IControllerResponse> {
- *     // Implementation
- *   }
- *
- *   // ... other methods
- * }
- * ```
- */
-interface IController<TDoc> {
-  /**
-   * List resources with filtering, pagination, sorting, lookups
-   *
-   * @param context - Framework-agnostic request context
-   * @returns Promise resolving to controller response with paginated data
-   *
-   * @example
-   * ```typescript
-   * // URL: GET /users?status=active&sort=-createdAt&limit=20
-   * const response = await controller.list({
-   *   query: { status: 'active', sort: '-createdAt', limit: '20' },
-   *   body: {},
-   *   params: {},
-   * });
-   *
-   * // Response:
-   * {
-   *   success: true,
-   *   data: {
-   *     method: 'offset',
-   *     data: [...],
-   *     total: 100,
-   *     page: 1,
-   *     pages: 5
-   *   },
-   *   status: 200
-   * }
-   * ```
-   */
-  list(context: IRequestContext): Promise<IControllerResponse<AnyPaginationResult<TDoc>>>;
-  /**
-   * Get single resource by ID
-   *
-   * @param context - Framework-agnostic request context (id in params)
-   * @returns Promise resolving to controller response with single document
-   *
-   * @example
-   * ```typescript
-   * // URL: GET /users/507f1f77bcf86cd799439011
-   * const response = await controller.get({
-   *   query: {},
-   *   body: {},
-   *   params: { id: '507f1f77bcf86cd799439011' },
-   * });
-   *
-   * // Success response:
-   * {
-   *   success: true,
-   *   data: { _id: '...', name: 'John', ... },
-   *   status: 200
-   * }
-   *
-   * // Not found response:
-   * {
-   *   success: false,
-   *   error: 'Resource not found',
-   *   status: 404
-   * }
-   * ```
-   */
-  get(context: IRequestContext): Promise<IControllerResponse<TDoc>>;
-  /**
-   * Create new resource
-   *
-   * @param context - Framework-agnostic request context (data in body)
-   * @returns Promise resolving to controller response with created document
-   *
-   * @example
-   * ```typescript
-   * // URL: POST /users
-   * // Body: { name: 'John', email: 'john@example.com' }
-   * const response = await controller.create({
-   *   query: {},
-   *   body: { name: 'John', email: 'john@example.com' },
-   *   params: {},
-   * });
-   *
-   * // Response:
-   * {
-   *   success: true,
-   *   data: { _id: '...', name: 'John', email: '...', createdAt: '...' },
-   *   status: 201
-   * }
-   * ```
-   */
-  create(context: IRequestContext): Promise<IControllerResponse<TDoc>>;
-  /**
-   * Update existing resource
-   *
-   * @param context - Framework-agnostic request context (id in params, updates in body)
-   * @returns Promise resolving to controller response with updated document
-   *
-   * @example
-   * ```typescript
-   * // URL: PATCH /users/507f1f77bcf86cd799439011
-   * // Body: { name: 'Jane' }
-   * const response = await controller.update({
-   *   query: {},
-   *   body: { name: 'Jane' },
-   *   params: { id: '507f1f77bcf86cd799439011' },
-   * });
-   *
-   * // Response:
-   * {
-   *   success: true,
-   *   data: { _id: '...', name: 'Jane', ... },
-   *   status: 200
-   * }
-   * ```
-   */
-  update(context: IRequestContext): Promise<IControllerResponse<TDoc>>;
-  /**
-   * Delete resource
-   *
-   * @param context - Framework-agnostic request context (id in params)
-   * @returns Promise resolving to controller response with deletion result
-   *
-   * @example
-   * ```typescript
-   * // URL: DELETE /users/507f1f77bcf86cd799439011
-   * const response = await controller.delete({
-   *   query: {},
-   *   body: {},
-   *   params: { id: '507f1f77bcf86cd799439011' },
-   * });
-   *
-   * // Response:
-   * {
-   *   success: true,
-   *   data: { message: 'Resource deleted successfully' },
-   *   status: 200
-   * }
-   * ```
-   */
-  delete(context: IRequestContext): Promise<IControllerResponse<{
-    message: string;
-  }>>;
-}
-/**
- * Optional: Response formatter utilities
- *
- * Helper functions to create standardized controller responses.
- * Use these to maintain consistent response shapes across your API.
- *
- * @example
- * ```typescript
- * class BaseController {
- *   protected success<T>(data: T, status = 200): IControllerResponse<T> {
- *     return { success: true, data, status };
- *   }
- *
- *   protected error(message: string, status = 500, details?: unknown): IControllerResponse {
- *     return { success: false, error: message, status, details };
- *   }
- *
- *   protected paginated<T>(result: PaginationResult<T>): IControllerResponse<PaginationResult<T>> {
- *     return { success: true, data: result, status: 200 };
- *   }
- * }
- * ```
- */
-interface IResponseFormatter {
-  /**
-   * Format successful response
-   * @param data - Response data
-   * @param status - HTTP status code (default: 200)
-   */
-  success<T>(data: T, status?: number): IControllerResponse<T>;
-  /**
-   * Format error response
-   * @param message - Error message
-   * @param status - HTTP status code (default: 500)
-   * @param details - Additional error details
-   */
-  error(message: string, status?: number, details?: unknown): IControllerResponse;
-  /**
-   * Format paginated response
-   * @param result - Pagination result from Repository.getAll()
-   */
-  paginated<T>(result: AnyPaginationResult<T>): IControllerResponse<AnyPaginationResult<T>>;
-}
-//#endregion
-//#region src/types.d.ts
-/**
- * MongoKit Type Definitions
- *
- * Production-grade types for MongoDB repository pattern with TypeScript
- *
- * @module @classytic/mongokit
- */
-/**
- * Global declaration merge: adds `softRequired` to Mongoose's SchemaTypeOptions
- * so consumers can annotate paths type-safely without importing anything.
- *
- * A path with `softRequired: true` keeps its DB-level `required: true`
- * invariant but is excluded from the auto-generated CRUD body `required[]`
- * array (see buildCrudSchemasFromModel).
- */
-declare module 'mongoose' {
-  interface SchemaTypeOptions<T, EnforcedDocType = any, THydratedDocumentType = HydratedDocument<EnforcedDocType>> {
-    /** mongokit: omit from auto-generated CRUD body `required` array. */
-    softRequired?: boolean;
-  }
-}
-/** Read Preference Type for replica sets */
-type ReadPreferenceType = 'primary' | 'primaryPreferred' | 'secondary' | 'secondaryPreferred' | 'nearest' | (string & {});
-/** Re-export mongoose ObjectId */
-type ObjectId = Types.ObjectId;
-/** Generic document type */
-type AnyDocument = Document & Record<string, unknown>;
-/** Generic model type */
-type AnyModel = Model<AnyDocument>;
-/** Sort direction */
-type SortDirection = 1 | -1;
-/** Sort specification for MongoDB queries */
-type SortSpec = Record<string, SortDirection>;
-/** Populate specification */
-type PopulateSpec = string | string[] | PopulateOptions | PopulateOptions[];
-/**
- * Select specification. `readonly string[]` widens the legacy `string[]`
- * form to also accept the immutable variant repo-core's contract uses
- * (`LookupPopulateOptions.select: readonly string[] | Record<string, 0
- * | 1>`), so `Repository<TDoc>` assigns to `StandardRepo<TDoc>` without
- * TS2322 on the `select` field. Any existing mutable-array caller stays
- * compatible — `string[]` is assignable to `readonly string[]`.
- */
-type SelectSpec = string | readonly string[] | Record<string, 0 | 1>;
-/** Filter query type for MongoDB queries (compatible with Mongoose 8 & 9) */
-type FilterQuery<_T = unknown> = Record<string, unknown>;
-/**
- * Infer document type from a Mongoose Model
- * @example
- * type UserDoc = InferDocument<typeof UserModel>;
- */
-type InferDocument<TModel> = TModel extends Model<infer TDoc> ? TDoc : never;
-/**
- * Infer raw document shape (without Mongoose Document methods)
- * @example
- * type User = InferRawDoc<typeof UserModel>;
- */
-type InferRawDoc<TModel> = TModel extends Model<infer TDoc> ? TDoc extends Document ? Omit<TDoc, keyof Document> : TDoc : never;
-/**
- * Make specific fields optional
- * @example
- * type CreateUser = PartialBy<User, 'createdAt' | 'updatedAt'>;
- */
-type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
-/**
- * Make specific fields required
- * @example
- * type UserWithId = RequiredBy<User, '_id'>;
- */
-type RequiredBy<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
-/**
- * Extract keys of type T that have values of type V
- * @example
- * type StringFields = KeysOfType<User, string>; // 'name' | 'email'
- */
-type KeysOfType<T, V> = { [K in keyof T]: T[K] extends V ? K : never; }[keyof T];
-/**
- * Deep partial - makes all nested properties optional
- */
-type DeepPartial<T> = T extends object ? { [P in keyof T]?: DeepPartial<T[P]>; } : T;
-/**
- * Strict object type - prevents excess properties
- * Use with `satisfies` for compile-time validation
- */
-type Strict<T> = T & { [K in Exclude<string, keyof T>]?: never; };
-/**
- * NonNullable fields extractor
- */
-type NonNullableFields<T> = { [K in keyof T]: NonNullable<T[K]>; };
-/**
- * Create/Update input types from document
- */
-type CreateInput<TDoc> = Omit<TDoc, '_id' | 'createdAt' | 'updatedAt' | '__v'>;
-/**
- * Partial-document update patch — the shape `repo.update(id, data)` accepts
- * for its `data` parameter. A `Partial<TDoc>` minus the fields a caller must
- * never set directly (`_id`, `createdAt`, `__v`).
- *
- * **Renamed from `UpdateInput<TDoc>` in 3.11.0** to eliminate a name
- * collision with `@classytic/repo-core/update`'s `UpdateInput` (the
- * `UpdateSpec | Record | Record[]` union consumed by `updateMany` /
- * `findOneAndUpdate`). The legacy name remains as a deprecated alias for
- * one release — remove in 3.12.
- */
-type UpdatePatch<TDoc> = Partial<Omit<TDoc, '_id' | 'createdAt' | '__v'>>;
-/**
- * Typed Mongo update document — the operator-shape that `findOneAndUpdate`
- * / `updateMany` accept on the wire (`{ $set, $inc, $unset, ... }`).
- *
- * The explicit operator keys give IDE autocomplete + per-operator value
- * typing; the trailing `[op: string]: unknown` index signature lets a
- * caller-built `MongoOperatorUpdate` value assign to `Record<string,
- * unknown>` without a cast — matching repo-core's `UpdateInput` slot
- * (`UpdateSpec | Record<string, unknown> | Record<string, unknown>[]`)
- * and unblocking the historic
- *
- *   `normalizeUpdate(update) as unknown as Record<string, unknown>`
- *
- * footgun every domain package eventually wrote.
- *
- * Trade-off: with the index signature, an operator typo (`$st` instead
- * of `$set`) won't fail TypeScript — Mongo would silently drop it. The
- * common operators are listed explicitly so `obj.$set` / `obj.$inc`
- * autocomplete stays useful; the escape hatch covers everything else
- * (`$min`, `$max`, `$rename`, `$pop`, etc.).
- *
- * @example
- * ```ts
- * import type { MongoOperatorUpdate } from '@classytic/mongokit';
- *
- * const patch: MongoOperatorUpdate = {
- *   $set: { status: 'paid', paidAt: new Date() },
- *   $inc: { revision: 1 },
- * };
- * await repo.findOneAndUpdate({ _id: id }, patch);  // no cast
- * ```
- */
-interface MongoOperatorUpdate {
-  /** Assign top-level or dotted-path values. */
-  $set?: Record<string, unknown>;
-  /** Set only on insert (upsert path). */
-  $setOnInsert?: Record<string, unknown>;
-  /** Remove fields (`Mongo` accepts `''`, `1`, or `true`). */
-  $unset?: Record<string, '' | 1 | true>;
-  /** Atomic numeric increment / decrement. */
-  $inc?: Record<string, number>;
-  /** Atomic numeric multiplication. */
-  $mul?: Record<string, number>;
-  /** Push to array (or `{ $each, $position, $slice, $sort }`). */
-  $push?: Record<string, unknown>;
-  /** Pull matching values from array. */
-  $pull?: Record<string, unknown>;
-  /** Pull a list of literals from array. */
-  $pullAll?: Record<string, unknown[]>;
-  /** Push only when not already present. */
-  $addToSet?: Record<string, unknown>;
-  /** Remove first / last element (`-1` / `1`). */
-  $pop?: Record<string, -1 | 1>;
-  /** Set only when the new value is smaller / larger. */
-  $min?: Record<string, unknown>;
-  $max?: Record<string, unknown>;
-  /** Rename top-level fields. */
-  $rename?: Record<string, string>;
-  /** Auto-set Date / Timestamp on this update. */
-  $currentDate?: Record<string, true | {
-    $type: 'date' | 'timestamp';
-  }>;
-  /** Bitwise ops on integer fields. */
-  $bit?: Record<string, {
-    and?: number;
-    or?: number;
-    xor?: number;
-  }>;
-  /**
-   * Escape hatch for any operator not explicitly listed above (e.g.
-   * positional-array operators like `$[<identifier>]` inside a path
-   * key). Index signature is what makes the type assign to
-   * `Record<string, unknown>` without a cast.
-   */
-  [op: string]: unknown;
-}
-/** Hook execution mode */
-type HookMode = 'sync' | 'async';
-/**
- * Minimal repo surface exposed to wrap-style middleware via the
- * `repo` field of `MiddlewareContext`. Intentionally narrow — middleware
- * shouldn't reach into the full `Repository` (that would couple every
- * middleware to the kit). The 5 floor methods plus `Model` cover every
- * legitimate middleware need (cross-doc reads, custom queries, type-
- * narrowing on `Model.modelName`).
- */
-interface MinimalRepoView<TDoc> {
-  readonly Model: Model<TDoc>;
-  readonly model: string;
-  getById(id: string | ObjectId, options?: Record<string, unknown>): Promise<TDoc | null>;
-  getAll?(params?: Record<string, unknown>, options?: Record<string, unknown>): Promise<unknown>;
-  create(data: Record<string, unknown>, options?: Record<string, unknown>): Promise<TDoc>;
-  update(id: string | ObjectId, data: Record<string, unknown>, options?: Record<string, unknown>): Promise<unknown>;
-  delete(id: string | ObjectId, options?: Record<string, unknown>): Promise<unknown>;
-}
-/**
- * Context passed to a wrap-style middleware. Middleware mutates
- * `context` before calling `await next()` to alter input; inspects /
- * transforms the resolved value to alter output; uses plain try/catch
- * around `next()` for error handling.
- *
- * The `before:` / `after:` / `error:` hook engine still fires from
- * within `next()` — hooks remain authoritative for policy / cache /
- * audit so security and correctness plugins keep working unchanged.
- * Middleware composes ergonomically on top.
- */
-interface MiddlewareContext<TDoc> {
-  /** Operation name (`'create'`, `'getById'`, ..., or any plugin op). */
-  readonly operation: string;
-  /** Live repository context — mutate fields before `next()` to alter input. */
-  readonly context: RepositoryContext;
-  /**
-   * Continue the chain — the next middleware (or, for the innermost
-   * middleware, the actual op + after/error hooks). The return value
-   * is the resolved op result; throwing propagates up the chain.
-   */
-  next: () => Promise<unknown>;
-  /** Narrow view of the repo for cross-doc reads / custom queries. */
-  readonly repo: MinimalRepoView<TDoc>;
-}
-/**
- * Wrap-style middleware — Prisma `$extends.query` / Express middleware
- * shape. Registered via `repo.useMiddleware(mw)`. Composes around every
- * `_runOp` invocation; runs in registration order (first-registered
- * runs outermost).
- *
- * @example Time every operation
- * ```ts
- * repo.useMiddleware(async ({ operation, next }) => {
- *   const start = performance.now();
- *   try { return await next(); }
- *   finally { console.log(`${operation} took ${performance.now() - start}ms`); }
- * });
- * ```
- *
- * @example Stamp tenant on every create
- * ```ts
- * repo.useMiddleware(async ({ operation, context, next }) => {
- *   if (operation === 'create' && context.data) {
- *     context.data.tenantId = currentTenant();
- *   }
- *   return next();
- * });
- * ```
- *
- * @example Short-circuit (skip the actual op) — return without calling next()
- * ```ts
- * repo.useMiddleware(async ({ operation, context, next }) => {
- *   if (operation === 'getById' && readOnlyMode) {
- *     return cachedReadOnlyResponse(context.id);
- *   }
- *   return next();
- * });
- * ```
- */
-type Middleware<TDoc = unknown> = (ctx: MiddlewareContext<TDoc>) => Promise<unknown>;
-/** Search strategy used by Repository.getAll when `search` is provided */
-type RepositorySearchMode = 'text' | 'regex' | 'auto';
-/** Repository options */
-interface RepositoryOptions {
-  /** Whether repository event hooks are awaited */
-  hooks?: HookMode;
-  /** Custom ID field used by getById/update/delete (default: '_id').
-   * Set to 'slug', 'code', 'chatId', etc. for non-ObjectId lookups. */
-  idField?: string;
-  /**
-   * How Repository.getAll handles the `search` parameter.
-   * - 'text' (default): uses MongoDB $text; requires a text index.
-   * - 'regex': builds case-insensitive $or of $regex across `searchFields`. No index required.
-   * - 'auto': uses 'text' if a text index exists, otherwise falls back to 'regex' when `searchFields` is set.
-   *
-   * Works standalone (Express/Nest/etc.) or alongside QueryParser — when the parser
-   * already consumed `search` into filters, Repository does nothing extra.
-   */
-  searchMode?: RepositorySearchMode;
-  /**
-   * Fields used when searchMode is 'regex' (or 'auto' falling back to regex).
-   * Required for regex mode to take effect.
-   */
-  searchFields?: string[];
-  /**
-   * How to react to a plugin composition that is known to be unsafe.
-   * - 'warn' (default): log a warning via the configured logger.
-   * - 'throw': fail fast at construction time — recommended for production.
-   * - 'off': disable the check entirely.
-   *
-   * Checks currently enforced:
-   *   - soft-delete must precede batch-operations (otherwise deleteMany /
-   *     updateMany skip the soft-delete filter injection).
-   *   - multi-tenant must precede cache (otherwise cache keys are computed
-   *     before tenant scoping → cross-tenant cache poisoning risk).
-   */
-  pluginOrderChecks?: 'warn' | 'throw' | 'off';
-  /**
-   * When `true` (default `false`), the repository checks every read/
-   * write op's filter against the schema's declared paths and warns
-   * once per `(modelName, fieldName)` pair if a filter key isn't on
-   * the schema AND `strictQuery: true` is in effect.
-   *
-   * **Why this exists.** With `mongoose.set('strictQuery', true)` (the
-   * mongoose 6 default; some projects pin it explicitly), filter keys
-   * not declared on the schema are SILENTLY STRIPPED before the query
-   * runs. `findOne({ code: 'X' })` on a schema without `code` becomes
-   * `findOne({})` — returns the first doc, not null — and the bug
-   * masquerades as "wrong row returned" without any error or log.
-   *
-   * The diagnostic catches the trap at runtime: log once per offending
-   * key per model, so a single bad call surfaces during dev/staging
-   * instead of in production. Costs O(filter keys) per call against
-   * a constructor-cached set; negligible.
-   *
-   * Hosts who route mongokit's `warn` into their own logger (via
-   * `configureLogger({ warn: ... })`) can ship this enabled in
-   * production without polluting stdout.
-   *
-   * @default false
-   */
-  warnOnStrictQueryStrip?: boolean;
-  /**
-   * Names of plugins that MUST be present in the plugin chain at
-   * construction time. Throws a `TypeError` from the constructor if
-   * any listed plugin is absent — eliminates the silent-misconfig
-   * shape where a host forgets to wire `multiTenantPlugin` and ships
-   * a tenant-leak to production.
-   *
-   * Names match each plugin's exported `name` property (the plugin's
-   * own canonical identifier, NOT the JavaScript function name).
-   * Bundled plugins as of 3.13:
-   *   - `'multi-tenant'` (from `multiTenantPlugin`)
-   *   - `'softDelete'` (from `softDeletePlugin`)
-   *   - `'auditLog'` (from `auditLogPlugin`)
-   *   - `'auditTrail'` (from `auditTrailPlugin`)
-   *   - `'cache'` (from `cachePlugin`)
-   *   - `'observability'` (from `observabilityPlugin`)
-   *   - `'method-registry'` (from `methodRegistryPlugin`)
-   *   - `'batch-operations'`, `'mongo-operations'`,
-   *     `'aggregate-helpers'`, `'subdocument'`, `'cascade'`,
-   *     `'custom-id'`, `'elastic-search'`, `'fieldFilter'`,
-   *     `'validation-chain'`, `'lease'`, `'timestamp'`
-   *
-   * Naming follows each plugin's `name` field — kebab-case for some,
-   * camelCase for others. The error message lists "Installed plugins"
-   * verbatim so a typo surfaces as a side-by-side diff.
-   *
-   * **Why this exists.** "Always wire `multiTenantPlugin`" and "always
-   * wire `softDeletePlugin`" are documented as conventions in 7+ and
-   * 9+ CLAUDE.md files across the classytic codebase respectively,
-   * but documentation drifts and convention-by-comment isn't
-   * enforceable. Listing the required plugins at the boot boundary
-   * fails closed — the constructor throws with the missing name, the
-   * bug surfaces on first run (or first test), not in production.
-   *
-   * @example
-   * ```ts
-   * import { MONGOKIT_PLUGIN_NAMES } from '@classytic/mongokit';
-   *
-   * new Repository(OrderModel, [
-   *   methodRegistryPlugin(),
-   *   multiTenantPlugin({ tenantField: 'organizationId' }),
-   *   softDeletePlugin(),
-   *   auditLogPlugin({ logger }),
-   * ], paginationConfig, {
-   *   requirePlugins: [
-   *     MONGOKIT_PLUGIN_NAMES.multiTenant,
-   *     MONGOKIT_PLUGIN_NAMES.softDelete,
-   *     MONGOKIT_PLUGIN_NAMES.auditLog,
-   *   ],
-   * });
-   * ```
-   *
-   * If any name in this list isn't matched by a plugin's `name`
-   * property in the chain, the constructor throws with the missing
-   * names listed.
-   */
-  requirePlugins?: readonly RepositoryPluginName[];
-  /**
-   * Standard Schema validator (Zod 3.24+, Valibot 1+, ArkType 2+, ...)
-   * for write payloads. Forwarded to `RepositoryBase`, which validates
-   * `create` data and every `createMany` doc at
-   * `HOOK_PRIORITY.VALIDATION` (150) — after policy plugins, before
-   * cache/observability. Failures throw an `HttpError` 400 with
-   * structured `validationErrors`. Validator output replaces the
-   * payload, so schema-declared coercions/defaults flow into the write.
-   */
-  schema?: import('@classytic/repo-core/schema').StandardSchemaV1;
-  /**
-   * Standard Schema validator for `update` payloads. Separate slot
-   * because updates are partial — derive one explicitly (e.g.
-   * `schema.partial()` in Zod).
-   */
-  updateSchema?: import('@classytic/repo-core/schema').StandardSchemaV1;
-  /**
-   * Domain-event emission. Pass any arc / `@classytic/primitives`-
-   * compatible transport and every mutating op publishes
-   * `<resource>.<verb>` events (`user.created`, `user.updated`, ...).
-   * Omit and the wiring is inert. See `@classytic/repo-core/events`.
-   */
-  events?: import('@classytic/repo-core/events').RepositoryEventsOptions;
-}
-/** Pagination configuration */
-interface PaginationConfig {
-  /** Default number of documents per page (default: 10) */
-  defaultLimit?: number;
-  /** Maximum allowed limit (default: 100) */
-  maxLimit?: number;
-  /** Maximum allowed page number (default: 10000) */
-  maxPage?: number;
-  /** Page number that triggers performance warning (default: 100) */
-  deepPageThreshold?: number;
-  /** Cursor version for forward compatibility (default: 1) */
-  cursorVersion?: number;
-  /**
-   * Minimum cursor version accepted. Bump alongside `cursorVersion` when a
-   * breaking format change ships so stale client cursors are rejected with a
-   * clear error instead of silently paginating from the wrong position.
-   * Default: 1 (accept any cursor <= cursorVersion).
-   */
-  minCursorVersion?: number;
-  /**
-   * Allowlist of primary sort fields for keyset pagination. When set, any
-   * `getAll({ sort })` whose primary (non-_id) field is not in this list
-   * throws at validation time.
-   *
-   * Use this to lock down keyset pagination to fields that are structurally
-   * guaranteed non-null in your schema — keyset sort across null/non-null
-   * boundaries is lossy (MongoDB's `$lt/$gt` semantics leave a gap at the
-   * type boundary, so not every doc is reachable).
-   *
-   * `_id` is always allowed regardless of this list.
-   * Undefined (default) = no allowlist, any sort field accepted.
-   */
-  strictKeysetSortFields?: string[];
-  /** Use estimatedDocumentCount for faster counts on large collections */
-  useEstimatedCount?: boolean;
-}
-/** MongoDB collation options for locale-aware string comparison */
-interface CollationOptions {
-  locale: string;
-  caseLevel?: boolean;
-  caseFirst?: 'upper' | 'lower' | 'off';
-  strength?: 1 | 2 | 3 | 4 | 5;
-  numericOrdering?: boolean;
-  alternate?: 'non-ignorable' | 'shifted';
-  maxVariable?: 'punct' | 'space';
-  backwards?: boolean;
-}
-/** Base pagination options */
-interface BasePaginationOptions {
-  /** Pagination mode (explicit override) */
-  mode?: 'offset' | 'keyset';
-  /** MongoDB query filters */
-  filters?: FilterQuery<AnyDocument>;
-  /** Sort specification */
-  sort?: SortSpec;
-  /** Number of documents per page */
-  limit?: number;
-  /** Fields to select */
-  select?: SelectSpec;
-  /** Fields to populate */
-  populate?: PopulateSpec;
-  /** Return plain JavaScript objects */
-  lean?: boolean;
-  /** MongoDB session for transactions */
-  session?: unknown;
-  /** Query hint (index name or document) */
-  hint?: string | Record<string, 1 | -1>;
-  /** Maximum execution time in milliseconds */
-  maxTimeMS?: number;
-  /** Read preference for replica sets (e.g. 'secondaryPreferred') */
-  readPreference?: ReadPreferenceType;
-  /** Collation for locale-aware string comparison and case-insensitive sorting */
-  collation?: CollationOptions;
-}
-/** Offset pagination options */
-interface OffsetPaginationOptions extends BasePaginationOptions {
-  /** Page number (1-indexed) */
-  page?: number;
-  /** Count strategy for filtered queries (default: 'exact') */
-  countStrategy?: 'exact' | 'estimated' | 'none';
-  /**
-   * Optional alternate filter used for the count query only. The primary
-   * `filters` is still used for `.find()`. Lets callers (Repository) run a
-   * sort-only query like `$near` for results while counting with a
-   * count-compatible rewrite (e.g. `$geoWithin: $centerSphere`) that
-   * returns the same document set but works with `countDocuments`.
-   */
-  countFilters?: FilterQuery<AnyDocument>;
-}
-/** Keyset (cursor) pagination options */
-interface KeysetPaginationOptions extends BasePaginationOptions {
-  /** Cursor token for next page */
-  after?: string;
-  /** Sort is required for keyset pagination */
-  sort: SortSpec;
-}
-/** Aggregate pagination options */
-interface AggregatePaginationOptions {
-  /** Aggregation pipeline stages */
-  pipeline?: PipelineStage[];
-  /** Page number (1-indexed) */
-  page?: number;
-  /** Number of documents per page */
-  limit?: number;
-  /** MongoDB session for transactions */
-  session?: unknown;
-  /** Query hint (index name or document) for aggregation */
-  hint?: string | Record<string, 1 | -1>;
-  /** Maximum execution time in milliseconds */
-  maxTimeMS?: number;
-  /** Count strategy (default: 'exact' via $facet).
-   * 'estimated' is accepted but treated as 'exact' in aggregation context
-   * since estimatedDocumentCount is not available inside pipelines. */
-  countStrategy?: 'exact' | 'estimated' | 'none';
-  /** Pagination mode (reserved for API consistency) */
-  mode?: 'offset';
-  /** Read preference for replica sets (e.g. 'secondaryPreferred') */
-  readPreference?: ReadPreferenceType;
-}
-/** Session-only options — shared base for lightweight operations */
-interface SessionOptions {
-  /** MongoDB session for transactions */
-  session?: unknown;
-  /** Organization/tenant ID for multi-tenant plugin scoping */
-  organizationId?: string | ObjectId;
-  /**
-   * Per-call escape hatch — plugins listed here that opt into the
-   * mechanism (`auditLog`, `auditTrail`, `observability`) read this
-   * from `RepositoryContext` and skip their work for this call. Use
-   * on hot paths (e.g. heartbeats / counters) where the audit overhead
-   * dominates.
-   *
-   * Plugins that enforce correctness or security (multi-tenant scope,
-   * cache invalidation, soft-delete filter) deliberately ignore this
-   * flag — security/correctness must not be skippable per-call.
-   *
-   * **Match exactly by `plugin.name`** (camelCase, NOT kebab-case):
-   *   - `'auditLog'` — see `auditLogPlugin()` in
-   *     `src/plugins/audit-log.plugin.ts` (`name: 'auditLog'`)
-   *   - `'auditTrail'` — see `auditTrailPlugin()` in
-   *     `src/plugins/audit-trail.plugin.ts` (`name: 'auditTrail'`)
-   *   - `'observability'` — see `observabilityPlugin()` in
-   *     `src/plugins/observability.plugin.ts` (`name: 'observability'`)
-   *
-   * Pre-3.13.0 docs referenced `'audit-log'` / `'audit-trail'` —
-   * those don't match any plugin's `name` field, so passing them
-   * silently fails to skip anything. The strings above are the
-   * authoritative ones.
-   */
-  skipPlugins?: readonly string[];
-  /**
-   * Per-call escape hatch for `multiTenantPlugin`. When `true`, the
-   * tenant scope hook returns without injecting `organizationId` (or
-   * the configured `tenantField`) into the operation's policy slot
-   * for THIS call only. The plugin emits `after:tenant-bypass` with
-   * `{ context, operation, reason: 'option' }` so audit / observability
-   * plugins can distinguish bypassed queries from tenant-scoped ones.
-   *
-   * Reach for this when:
-   *   - A super-admin / platform-admin user needs cross-tenant read
-   *     for support tooling.
-   *   - A migration script writes / backfills across tenants
-   *     deliberately.
-   *   - A scheduled job (TTL cleanup, cross-tenant aggregate, billing
-   *     rollup) needs the unscoped view.
-   *
-   * **`bypassTenant` is the most-specific decision** — runs before
-   * `skipWhen` (plugin-level callback) and `resolveContext` (CLS
-   * fallback). Distinct from `skipWhen` which fires for every call
-   * and reads context to decide; `bypassTenant: true` is a deliberate
-   * per-call opt-out with no role check, so the calling code carries
-   * the responsibility.
-   *
-   * **NOT a substitute for proper access control.** This flag bypasses
-   * tenant scoping; it does NOT bypass authentication, RBAC, or any
-   * other host-level access check. Wrap it with your auth boundary at
-   * the controller / service layer.
-   *
-   * @example
-   * ```ts
-   * // Support engineer pulling a customer's order across tenants:
-   * await orderRepo.findAll({}, { bypassTenant: true });
-   *
-   * // Migration backfill across the whole estate:
-   * for await (const doc of repo.cursor({}, { bypassTenant: true })) { ... }
-   * ```
-   */
-  bypassTenant?: boolean;
-  /**
-   * Per-call escape hatch for `appendOnlyPlugin` — deliberate
-   * maintenance on an immutable-facts collection (backfill repair,
-   * migration). Audited via `after:append-only-bypass`; grep for this
-   * flag the same way you grep `bypassTenant` / `mode: 'hard'`. NOT a
-   * substitute for access control — gate it at the host layer.
-   */
-  bypassAppendOnly?: boolean;
-  /** Extensible — plugins can read custom fields from options */
-  [key: string]: unknown;
-}
-/** Read options — session + readPreference for read-only operations */
-interface ReadOptions extends SessionOptions {
-  /** Read preference for replica sets (e.g. 'secondaryPreferred') */
-  readPreference?: ReadPreferenceType;
-}
-/** Repository operation options */
-interface OperationOptions extends ReadOptions {
-  /** Fields to select */
-  select?: SelectSpec;
-  /** Fields to populate */
-  populate?: PopulateSpec;
-  /** Advanced populate options (from QueryParser or Arc's BaseController) */
-  populateOptions?: PopulateOptions[];
-  /** Return plain JavaScript objects */
-  lean?: boolean;
-  /** Throw error if document not found (default: true) */
-  throwOnNotFound?: boolean;
-  /** Override the ID field for this call (default: repo.idField or '_id').
-   * Use when the same repo sometimes queries by _id and sometimes by slug/code. */
-  idField?: string;
-  /** Additional query filters (e.g., for soft delete) */
-  query?: Record<string, unknown>;
-}
-/**
- * Cache-aware operation options — extends OperationOptions with the
- * unified cache plugin's per-call shape. Pass `cache: { staleTime, swr,
- * tags, bypass, ... }` to override freshness for this call.
- */
-interface CacheableOptions extends OperationOptions {
-  /** Per-call cache override forwarded to the unified cache plugin. */
-  cache?: import('@classytic/repo-core/cache').CacheOptions;
-}
-/** withTransaction options */
-interface WithTransactionOptions {
-  /** Allow non-transactional fallback when transactions are unsupported */
-  allowFallback?: boolean;
-  /** Optional hook to observe fallback triggers */
-  onFallback?: (error: Error) => void;
-  /** MongoDB transaction options (readConcern, writeConcern, readPreference, maxCommitTimeMS) */
-  transactionOptions?: import('mongoose').mongo.TransactionOptions;
-}
-/** Create operation options */
-interface CreateOptions extends SessionOptions {
-  /** Keep insertion order on error (default: false).
-   * When false, all valid documents insert even if some fail (e.g. duplicates).
-   * Set to true to abort remaining inserts on first error. */
-  ordered?: boolean;
-}
-/** Update operation options */
-interface UpdateOptions extends OperationOptions {
-  /** Enable update pipeline syntax */
-  updatePipeline?: boolean;
-  /** Array filters for positional operator $[<identifier>] updates */
-  arrayFilters?: Record<string, unknown>[];
-}
-/**
- * Options for atomic findOneAndUpdate (compare-and-set primitive).
- *
- * Designed for outbox/lock/semaphore patterns that need a single round-trip
- * match-and-mutate. Goes through the full hook pipeline (multi-tenant scope,
- * soft-delete, audit) the same way `update()` does.
- */
-interface FindOneAndUpdateOptions extends OperationOptions {
-  /** Sort to disambiguate when filter matches multiple docs (e.g. FIFO claim). */
-  sort?: SortSpec;
-  /** Return doc state before or after the update. Default: 'after'. */
-  returnDocument?: 'before' | 'after';
-  /** Insert if no doc matches. Default: false. */
-  upsert?: boolean;
-  /** Array filters for positional `$[<identifier>]` updates. */
-  arrayFilters?: Record<string, unknown>[];
-  /** Allow aggregation-pipeline updates (array form). Default: false. */
-  updatePipeline?: boolean;
-  /** Run mongoose schema validators on the update. Default: true. */
-  runValidators?: boolean;
-  /** Collation for locale-aware string comparison. */
-  collation?: CollationOptions;
-  /** Maximum execution time in milliseconds. */
-  maxTimeMS?: number;
-}
-/** Aggregate operation options */
-interface AggregateOptions extends ReadOptions {
-  /** Allow aggregation to use disk for large sorts/groups */
-  allowDiskUse?: boolean;
-  /** Comment for profiler/logs */
-  comment?: string;
-  /** Maximum execution time in milliseconds */
-  maxTimeMS?: number;
-  /** Read concern level */
-  readConcern?: {
-    level: string;
-  };
-  /** Collation for locale-aware string comparison */
-  collation?: CollationOptions;
-  /** Maximum allowed pipeline stages (governance) */
-  maxPipelineStages?: number;
-}
-/** Lookup populate options */
-/**
- * Mongokit's `lookupPopulate` options — kit-native superset of the
- * portable `LookupPopulateOptions<TBase>` from repo-core. Widens three
- * slots so arc / mongoose consumers compose cleanly:
- *
- *   - `filters`: accepts Filter IR, a `Partial<TBase> & Record<string,
- *     unknown>` literal (same shape repo-core's contract uses), or a
- *     plain `Record<string, unknown>` for legacy callers.
- *   - `lookups`: accepts either the portable `LookupSpec[]` (works on
- *     every kit) or mongokit's `LookupOptions[]` (adds `pipeline` /
- *     `let` / `sanitize` for mongo-correlated joins).
- *   - `select`: accepts mongoose's space-separated string form
- *     (`'name email'`) in addition to the portable array / inclusion
- *     map. Kept for arc + existing controller convenience.
- *
- * `TBase` defaults to `unknown` so legacy non-generic usage still
- * compiles; pass the doc type for arc `RepositoryLike<TDoc>` structural
- * assignment — `LookupPopulateOptions<TDoc>` is bit-compatible with
- * `import('@classytic/repo-core/repository').LookupPopulateOptions<TDoc>`.
- */
-interface LookupPopulateOptions<TBase = unknown> {
-  /**
-   * Base-table filter. Accepts Filter IR from repo-core, a typed
-   * `Partial<TBase> & Record<string, unknown>` literal (what arc
-   * controllers produce when typed against `StandardRepo<TDoc>`), or
-   * a plain `Record<string, unknown>` for ad-hoc callers.
-   */
-  filters?: import('@classytic/repo-core/filter').Filter | (Partial<TBase> & Record<string, unknown>) | Record<string, unknown>;
-  /**
-   * Portable `LookupSpec[]` (cross-kit) or mongokit-native
-   * `LookupOptions[]` (with `pipeline` / `let` / `sanitize`). The
-   * portable shape is a structural subset, so callers can mix.
-   */
-  lookups: readonly import('@classytic/repo-core/repository').LookupSpec[] | LookupOptions[];
-  /** Sort specification */
-  sort?: SortSpec | string;
-  /** Page number (offset mode, 1-indexed) */
-  page?: number;
-  /** Cursor token for next page (keyset mode) */
-  after?: string;
-  /** Number of documents per page */
-  limit?: number;
-  /** Fields to select */
-  select?: SelectSpec;
-  /** Collation for locale-aware string comparison */
-  collation?: CollationOptions;
-  /** Count strategy for offset pagination */
-  countStrategy?: 'exact' | 'estimated' | 'none';
-  /**
-   * Transaction session. Typed `unknown` to match repo-core's
-   * `RepositorySession` contract — mongokit narrows to `ClientSession`
-   * internally. Not inherited from `ReadOptions` because the repo-core
-   * contract type has no `[key: string]: unknown` escape hatch, and
-   * arc's `Partial<StandardRepo<TDoc>>` boundary rejects index-signature
-   * drift under strict function-type variance.
-   */
-  session?: unknown;
-  /** Read preference for replica sets (e.g. 'secondaryPreferred') */
-  readPreference?: ReadPreferenceType;
-  /** Multi-tenant plugin scoping (applied via before:lookupPopulate hook). */
-  organizationId?: string | ObjectId;
-}
-/**
- * Union emitted by the validation-chain plugin. Keeps the violation shape
- * from `ValidationResult` without re-exporting the type — consumers that
- * need `ValidationResult`, `CrudSchemas`, `JsonSchema`, `SchemaBuilderOptions`,
- * `FieldRule` or `FieldRules` import them straight from
- * `@classytic/repo-core/schema`.
- */
-type UpdateWithValidationResult<T> = {
-  success: true;
-  data: T;
-} | {
-  success: false;
-  error: {
-    code: number;
-    message: string;
-    violations?: ValidationResult['violations'];
-  };
-};
-/** User context for operations */
-interface UserContext {
-  _id?: ObjectId | string;
-  id?: string;
-  roles?: string | string[];
-  [key: string]: unknown;
-}
-/** Repository operation context */
-interface RepositoryContext {
-  /** Operation name */
-  operation: string;
-  /** Model name */
-  model: string;
-  /** Document data (for create/update) */
-  data?: Record<string, unknown>;
-  /** Array of documents (for createMany) */
-  dataArray?: Record<string, unknown>[];
-  /** Document ID (for update/delete/getById) */
-  id?: string | ObjectId;
-  /** Query filters */
-  query?: FilterQuery<AnyDocument>;
-  /** User making the request */
-  user?: UserContext;
-  /** Organization ID for multi-tenancy */
-  organizationId?: string | ObjectId;
-  /** Fields to select */
-  select?: SelectSpec;
-  /** Fields to populate */
-  populate?: PopulateSpec;
-  /** Return lean documents */
-  lean?: boolean;
-  /** MongoDB session */
-  session?: unknown;
-  /** Read preference for replica sets */
-  readPreference?: ReadPreferenceType;
-  /**
-   * Per-call escape hatch — plugin names listed here that opt into the
-   * mechanism (`auditLog`, `auditTrail`, `observability`) skip their
-   * work for this call. Threaded from `OperationOptions.skipPlugins`
-   * via `_buildContext`. Security/correctness plugins (multi-tenant
-   * scope, cache invalidation, soft-delete filter) deliberately ignore
-   * this — those must not be skippable per-call.
-   */
-  skipPlugins?: readonly string[];
-  /** Pagination filters */
-  filters?: Record<string, unknown>;
-  /** Sort specification */
-  sort?: SortSpec;
-  /** Page number (offset pagination) */
-  page?: number;
-  /** Items per page */
-  limit?: number;
-  /** Cursor for next page (keyset pagination) */
-  after?: string;
-  /** Search query string */
-  search?: string;
-  /** Pagination mode */
-  mode?: 'offset' | 'keyset';
-  /** Query hint */
-  hint?: string | Record<string, 1 | -1>;
-  /** Maximum execution time in milliseconds */
-  maxTimeMS?: number;
-  /** Count strategy for offset pagination */
-  countStrategy?: 'exact' | 'estimated' | 'none';
-  /** Whether this is a soft delete operation (set by softDeletePlugin) */
-  softDeleted?: boolean;
-  /** Include soft-deleted documents in queries */
-  includeDeleted?: boolean;
-  /**
-   * Caller-requested delete semantics, read by softDeletePlugin.
-   *
-   * - `undefined` (default) — plugin decides: soft if wired, hard otherwise.
-   * - `'hard'` — bypass soft-delete and physically remove the document.
-   *   All policy hooks (multi-tenant scope, audit trails, cache invalidation)
-   *   still fire; only the soft-delete interception is skipped.
-   * - `'soft'` — reserved. Currently treated as default since softDeletePlugin
-   *   is the only source of soft semantics.
-   */
-  deleteMode?: 'hard' | 'soft';
-  /**
-   * Per-call cache options forwarded by the unified cache plugin
-   * (`@classytic/repo-core/cache`). Kits copy this from the caller's
-   * `options.cache` onto the context so the plugin's `before:<op>`
-   * hook can read it.
-   */
-  cache?: import('@classytic/repo-core/cache').CacheOptions;
-  /** Whether result was served from cache (internal — set by cache plugin) */
-  _cacheHit?: boolean;
-  /** Cached result (internal — set by cache plugin) */
-  _cachedResult?: unknown;
-  /** Resolved cache options stash (internal — set by cache plugin) */
-  _cacheKey?: string;
-  /** Resolved cache options stash (internal — set by cache plugin) */
-  _cacheResolved?: unknown;
-  /** Cache hit status (internal — `'fresh'` or `'stale'`) */
-  _cacheStatus?: 'fresh' | 'stale' | 'miss' | 'disabled' | 'bypass';
-  /** IDs to cascade delete (internal) */
-  _cascadeIds?: unknown[];
-  /** Custom context data from plugins */
-  [key: string]: unknown;
-}
-/**
- * Plugin interface — generic over the repo type so kit-internal plugins
- * can target the narrower `RepositoryInstance` while cross-package
- * plugins from `@classytic/repo-core/cache` etc. that target the
- * shared `RepositoryBase` flow through the same array.
- *
- * `RepositoryInstance` formally `extends RepositoryBase` (see below),
- * so `Plugin<RepositoryBase>` is structurally assignable to
- * `Plugin<RepositoryInstance>` via TypeScript's method-bivariance
- * rule for interface methods. No host-site casts required.
- */
-interface Plugin<TRepo extends RepositoryBase = RepositoryInstance> {
-  /** Plugin name */
-  name: string;
-  /** Apply plugin to repository */
-  apply(repo: TRepo): void;
-}
-/** Plugin function signature. Same TRepo widening as `Plugin`. */
-type PluginFunction<TRepo extends RepositoryBase = RepositoryInstance> = (repo: TRepo) => void;
-/** Plugin type (object or function). */
-type PluginType<TRepo extends RepositoryBase = RepositoryInstance> = Plugin<TRepo> | PluginFunction<TRepo>;
-/** Hook with priority for deterministic phase ordering */
-interface PrioritizedHook {
-  listener: (data: any) => void | Promise<void>;
-  priority: number;
-}
-/**
- * Repository instance for plugin type reference.
- *
- * Extends `@classytic/repo-core/repository`'s `RepositoryBase` so the
- * full hook + adapter contract is included. This keeps mongokit's
- * `Plugin<RepositoryInstance>` and repo-core's `Plugin<RepositoryBase>`
- * structurally aligned — cross-package plugins (`cachePlugin` from
- * `@classytic/repo-core/cache` etc.) flow into mongokit's `plugins[]`
- * array without per-call casts at the host site.
- *
- * The `[key: string]: unknown` index signature at the bottom keeps
- * dynamic plugin-method registration (`registerMethod`) compatible.
- */
-interface RepositoryInstance extends RepositoryBase {
-  Model: Model<any>;
-  model: string;
-  _hooks: Map<string, PrioritizedHook[]>;
-  _pagination: unknown;
-  use(plugin: PluginType): this;
-  on(event: RepositoryEvent | (string & {}), listener: (data: any) => void | Promise<void>, options?: {
-    priority?: number;
-  }): this;
-  off(event: RepositoryEvent | (string & {}), listener: (data: any) => void | Promise<void>): this;
-  removeAllListeners(event?: string): this;
-  emit(event: string, data: unknown): void;
-  emitAsync(event: string, data: unknown): Promise<void>;
-  registerMethod?(name: string, fn: (...args: any[]) => any): void;
-  hasMethod?(name: string): boolean;
-  _buildContext(operation: string, options: Record<string, unknown> | object): Promise<RepositoryContext>;
-  _handleError(error: Error): HttpError;
-  update(id: string | ObjectId, data: Record<string, unknown>, options?: Record<string, unknown>): Promise<unknown>;
-  findOneAndUpdate(filter: Record<string, unknown>, update: Record<string, unknown> | Record<string, unknown>[], options?: Record<string, unknown>): Promise<unknown>;
-  aggregatePipeline(pipeline: PipelineStage[], options?: Record<string, unknown>): Promise<unknown[]>;
-  getByQuery(query: Record<string, unknown>, options?: Record<string, unknown>): Promise<unknown>;
-  _executeQuery<T>(buildQuery: (Model: Model<any>) => Promise<T>): Promise<T>;
-  [key: string]: unknown;
-}
-/** Repository operation names */
-type RepositoryOperation = 'create' | 'createMany' | 'update' | 'updateMany' | 'findOneAndUpdate' | 'delete' | 'deleteMany' | 'restore' | 'getById' | 'getByQuery' | 'getOne' | 'getAll' | 'findAll' | 'getOrCreate' | 'count' | 'exists' | 'distinct' | 'aggregate' | 'aggregatePaginate' | 'aggregatePipeline' | 'aggregatePipelinePaginate' | 'lookupPopulate' | 'bulkWrite' | 'claim' | 'claimVersion' | 'cursor' | 'watch';
-/** Event lifecycle phases */
-type EventPhase = 'before' | 'after' | 'error';
-/** Repository event names (generated from template literals) */
-type RepositoryEvent = `${EventPhase}:${RepositoryOperation}` | 'method:registered' | 'error:hook';
-/**
- * Type-safe event handler map
- *
- * Hook signature contract:
- * - `before:*` — receives `context: RepositoryContext` directly (not wrapped).
- *   Plugins mutate context in-place to inject filters, data, etc.
- * - `after:*`  — receives `{ context, result }` where result is the operation output.
- * - `error:*`  — receives `{ context, error }` where error is the caught Error.
- */
-type EventHandlers<TDoc = unknown> = { [K in RepositoryEvent]?: K extends `before:${string}` ? (context: RepositoryContext) => void | Promise<void> : K extends `after:${string}` ? (payload: {
-  context: RepositoryContext;
-  result: TDoc | TDoc[];
-}) => void | Promise<void> : K extends `error:${string}` ? (payload: {
-  context: RepositoryContext;
-  error: Error;
-}) => void | Promise<void> : (payload: {
-  context: RepositoryContext;
-}) => void | Promise<void>; };
-/** Event payload */
-interface EventPayload {
-  context: RepositoryContext;
-  result?: unknown;
-  error?: Error;
-}
-/** Field preset configuration */
-interface FieldPreset {
-  /** Fields visible to everyone */
-  public: string[];
-  /** Additional fields for authenticated users */
-  authenticated?: string[];
-  /** Additional fields for admins */
-  admin?: string[];
-}
-/** Value type identifier for cursor serialization */
-type ValueType = 'date' | 'objectid' | 'boolean' | 'number' | 'string' | 'null' | 'unknown';
-/** Cursor payload */
-interface CursorPayload {
-  /** Primary sort field value (legacy single-field) */
-  v: string | number | boolean | null;
-  /** Value type identifier (legacy single-field) */
-  t: ValueType;
-  /** Document ID */
-  id: string;
-  /** ID type identifier */
-  idType: ValueType;
-  /** Sort specification */
-  sort: SortSpec;
-  /** Cursor version */
-  ver: number;
-  /** Compound sort field values (multi-field keyset) */
-  vals?: Record<string, string | number | boolean | null>;
-  /** Compound sort value types */
-  types?: Record<string, ValueType>;
-}
-/** Decoded cursor */
-interface DecodedCursor {
-  /** Primary sort field value (rehydrated) — legacy compat */
-  value: unknown;
-  /** Document ID (rehydrated) */
-  id: ObjectId | string;
-  /** Sort specification */
-  sort: SortSpec;
-  /** Cursor version */
-  version: number;
-  /** All sort field values (rehydrated) — for compound sort */
-  values?: Record<string, unknown>;
-}
-/** Validator definition */
-interface ValidatorDefinition {
-  /** Validator name */
-  name: string;
-  /** Operations to apply validator to */
-  operations?: Array<'create' | 'createMany' | 'update' | 'findOneAndUpdate' | 'delete'>;
-  /** Validation function */
-  validate: (context: RepositoryContext, repo?: RepositoryInstance) => void | Promise<void>;
-}
-/** Validation chain options */
-interface ValidationChainOptions {
-  /** Stop on first validation error (default: true) */
-  stopOnFirstError?: boolean;
-}
-/** Logger interface for audit plugin */
-interface Logger {
-  info?(message: string, meta?: Record<string, unknown>): void;
-  error?(message: string, meta?: Record<string, unknown>): void;
-  warn?(message: string, meta?: Record<string, unknown>): void;
-  debug?(message: string, meta?: Record<string, unknown>): void;
-}
-/** Filter mode for soft delete queries */
-type SoftDeleteFilterMode = 'null' | 'exists';
-/** Soft delete plugin options */
-interface SoftDeleteOptions {
-  /** Field name for deletion timestamp (default: 'deletedAt') */
-  deletedField?: string;
-  /** Field name for deleting user (default: 'deletedBy') */
-  deletedByField?: string;
-  /** Enable soft delete (default: true) */
-  soft?: boolean;
-  /**
-   * Filter mode for excluding deleted documents (default: 'null')
-   * - 'null': Filters where deletedField is null (works with `default: null` in schema)
-   * - 'exists': Filters where deletedField does not exist (legacy behavior)
-   */
-  filterMode?: SoftDeleteFilterMode;
-  /** Add restore method to repository (default: true) */
-  addRestoreMethod?: boolean;
-  /** Add getDeleted method to repository (default: true) */
-  addGetDeletedMethod?: boolean;
-  /**
-   * TTL in days for auto-cleanup of deleted documents.
-   * When set, creates a TTL index on the deletedField.
-   * Documents will be automatically removed after the specified days.
-   */
-  ttlDays?: number;
-}
-/** Repository with soft delete methods */
-interface SoftDeleteRepository<TDoc = unknown> {
-  /**
-   * Restore a soft-deleted document by setting deletedAt to null
-   * @param id - Document ID to restore
-   * @param options - Optional session for transactions
-   * @returns The restored document
-   */
-  restore(id: string | ObjectId, options?: {
-    session?: unknown;
-  }): Promise<TDoc>;
-  /**
-   * Get all soft-deleted documents
-   * @param params - Query parameters (filters, pagination, etc.)
-   * @param options - Query options (select, populate, etc.)
-   * @returns Paginated result of deleted documents
-   */
-  getDeleted(params?: {
-    filters?: Record<string, unknown>;
-    sort?: SortSpec | string;
-    page?: number;
-    limit?: number;
-  }, options?: {
-    select?: SelectSpec;
-    populate?: PopulateSpec;
-    lean?: boolean;
-    session?: unknown;
-  }): Promise<OffsetPaginationResult<TDoc>>;
-}
-/** Group result */
-interface GroupResult {
-  _id: unknown;
-  count: number;
-}
-/** Min/Max result */
-interface MinMaxResult {
-  min: unknown;
-  max: unknown;
-}
-/**
- * Per-call cache options — TanStack-shaped (`staleTime`, `gcTime`, `swr`,
- * `tags`, `bypass`, `enabled`, `key`). Threaded through read methods via
- * `options.cache` (CRUD) or `aggRequest.cache` (aggregate).
- */
-interface CacheOperationOptions {
-  /** Per-call cache override forwarded to the unified cache plugin. */
-  cache?: import('@classytic/repo-core/cache').CacheOptions;
-}
-/** Cascade relation definition */
-interface CascadeRelation {
-  /**
-   * Preferred: a Repository instance for the target collection. When present,
-   * cascade routes deletes through `repo.delete` / `repo.deleteMany`, so the
-   * target's `before:delete` / `before:deleteMany` hooks fire — meaning
-   * multi-tenant scoping, audit logging, cache invalidation, and the target's
-   * own soft-delete plugin (with its configured `deletedField`) all run
-   * correctly. Strongly recommended for any target that has policy plugins.
-   */
-  repo?: RepositoryInstance;
-  /**
-   * Legacy: a Mongoose model name. When set without `repo`, cascade writes
-   * directly via `RelatedModel.updateMany` / `RelatedModel.deleteMany`. This
-   * path bypasses the target's hooks — it will NOT enforce tenant scoping,
-   * fire audit events, or honor a custom `deletedField`. Only safe for
-   * trivial targets with no policy plugins. Prefer `repo` for new code.
-   */
-  model?: string;
-  /** Foreign key field in the related model that references the deleted document */
-  foreignKey: string;
-  /** Whether to use soft delete if available (default: follows parent behavior) */
-  softDelete?: boolean;
-}
-/** Cascade delete plugin options */
-interface CascadeOptions {
-  /** Relations to cascade delete */
-  relations: CascadeRelation[];
-  /** Run cascade deletes in parallel (default: true) */
-  parallel?: boolean;
-  /** Logger for cascade operations */
-  logger?: Logger;
-}
-/**
- * Combines all plugin method types into a single type
- * Useful when you're using all plugins and want full type safety
- *
- * @example
- * ```typescript
- * import { Repository } from '@classytic/mongokit';
- * import type { AllPluginMethods } from '@classytic/mongokit';
- *
- * class UserRepo extends Repository<IUser> {}
- *
- * const repo = new UserRepo(Model, [...allPlugins]) as UserRepo & AllPluginMethods<IUser>;
- *
- * // TypeScript knows about all plugin methods!
- * await repo.increment(id, 'views', 1);
- * await repo.restore(id);
- * await repo.cache?.invalidateByTags(['org:abc']);
- * ```
- *
- * Note: Import the individual plugin method types if you need them:
- * ```typescript
- * import type {
- *   MongoOperationsMethods,
- *   BatchOperationsMethods,
- *   AggregateHelpersMethods,
- *   SubdocumentMethods,
- *   SoftDeleteMethods,
- * } from '@classytic/mongokit';
- * ```
- */
-/**
- * Extract string keys from a document type, with `string` fallback for untyped usage.
- * Provides autocomplete for known fields while still accepting arbitrary strings
- * (e.g. for nested paths like 'address.city').
- */
-type DocField<TDoc> = (keyof TDoc & string) | (string & {});
-type AllPluginMethods<TDoc> = {
-  upsert(query: Record<string, unknown>, data: Record<string, unknown>, options?: Record<string, unknown>): Promise<TDoc>;
-  increment(id: string | ObjectId, field: DocField<TDoc>, value?: number, options?: Record<string, unknown>): Promise<TDoc>;
-  decrement(id: string | ObjectId, field: DocField<TDoc>, value?: number, options?: Record<string, unknown>): Promise<TDoc>;
-  pushToArray(id: string | ObjectId, field: DocField<TDoc>, value: unknown, options?: Record<string, unknown>): Promise<TDoc>;
-  pullFromArray(id: string | ObjectId, field: DocField<TDoc>, value: unknown, options?: Record<string, unknown>): Promise<TDoc>;
-  addToSet(id: string | ObjectId, field: DocField<TDoc>, value: unknown, options?: Record<string, unknown>): Promise<TDoc>;
-  setField(id: string | ObjectId, field: DocField<TDoc>, value: unknown, options?: Record<string, unknown>): Promise<TDoc>;
-  unsetField(id: string | ObjectId, fields: DocField<TDoc> | DocField<TDoc>[], options?: Record<string, unknown>): Promise<TDoc>;
-  renameField(id: string | ObjectId, oldName: DocField<TDoc>, newName: string, options?: Record<string, unknown>): Promise<TDoc>;
-  multiplyField(id: string | ObjectId, field: DocField<TDoc>, multiplier: number, options?: Record<string, unknown>): Promise<TDoc>;
-  setMin(id: string | ObjectId, field: DocField<TDoc>, value: unknown, options?: Record<string, unknown>): Promise<TDoc>;
-  setMax(id: string | ObjectId, field: DocField<TDoc>, value: unknown, options?: Record<string, unknown>): Promise<TDoc>;
-  atomicUpdate(id: string | ObjectId, operators: Record<string, Record<string, unknown>>, options?: Record<string, unknown>): Promise<TDoc>;
-  bulkWrite(operations: Record<string, unknown>[], options?: {
-    session?: unknown;
-    ordered?: boolean;
-  }): Promise<{
-    ok: number;
-    insertedCount: number;
-    upsertedCount: number;
-    matchedCount: number;
-    modifiedCount: number;
-    deletedCount: number;
-    insertedIds: Record<number, unknown>;
-    upsertedIds: Record<number, unknown>;
-  }>;
-  groupBy(field: DocField<TDoc>, options?: {
-    limit?: number;
-    session?: unknown;
-  }): Promise<Array<{
-    _id: unknown;
-    count: number;
-  }>>;
-  sum(field: DocField<TDoc>, query?: Record<string, unknown>, options?: Record<string, unknown>): Promise<number>;
-  average(field: DocField<TDoc>, query?: Record<string, unknown>, options?: Record<string, unknown>): Promise<number>;
-  min(field: DocField<TDoc>, query?: Record<string, unknown>, options?: Record<string, unknown>): Promise<number>;
-  max(field: DocField<TDoc>, query?: Record<string, unknown>, options?: Record<string, unknown>): Promise<number>;
-  addSubdocument(parentId: string | ObjectId, arrayPath: DocField<TDoc>, subData: Record<string, unknown>, options?: Record<string, unknown>): Promise<TDoc>;
-  getSubdocument(parentId: string | ObjectId, arrayPath: DocField<TDoc>, subId: string | ObjectId, options?: {
-    lean?: boolean;
-    session?: unknown;
-  }): Promise<Record<string, unknown>>;
-  updateSubdocument(parentId: string | ObjectId, arrayPath: DocField<TDoc>, subId: string | ObjectId, updateData: Record<string, unknown>, options?: {
-    session?: unknown;
-  }): Promise<TDoc>;
-  deleteSubdocument(parentId: string | ObjectId, arrayPath: DocField<TDoc>, subId: string | ObjectId, options?: Record<string, unknown>): Promise<TDoc>;
-  restore(id: string | ObjectId, options?: {
-    session?: unknown;
-  }): Promise<TDoc>;
-  getDeleted(params?: {
-    filters?: Record<string, unknown>;
-    sort?: SortSpec | string;
-    page?: number;
-    limit?: number;
-  }, options?: {
-    select?: SelectSpec;
-    populate?: PopulateSpec;
-    lean?: boolean;
-    session?: unknown;
-  }): Promise<OffsetPaginationResult<TDoc>>;
-  /**
-   * Cache plugin handle (set by `cachePlugin({ adapter })`). Exposes the
-   * `CacheEngine` plus convenience invalidation helpers. `undefined` when
-   * no cache plugin is wired.
-   */
-  cache?: import('@classytic/repo-core/cache').RepositoryCacheHandle;
-};
-/**
- * Helper type to add all plugin methods to a repository class
- * Cleaner than manually typing the intersection
- *
- * @example
- * ```typescript
- * import { Repository } from '@classytic/mongokit';
- * import type { WithPlugins } from '@classytic/mongokit';
- *
- * class OrderRepo extends Repository<IOrder> {
- *   async getCustomerOrders(customerId: string) {
- *     return this.getAll({ filters: { customerId } });
- *   }
- * }
- *
- * const orderRepo = new OrderRepo(Model, [
- *   ...allPlugins
- * ]) as WithPlugins<IOrder, OrderRepo>;
- *
- * // Works: custom methods + plugin methods
- * await orderRepo.getCustomerOrders('123');
- * await orderRepo.increment(orderId, 'total', 100);
- * ```
- */
-type WithPlugins<TDoc, TRepo extends RepositoryInstance = RepositoryInstance> = TRepo & AllPluginMethods<TDoc>;
-//#endregion
-export { RepositoryEvent as $, KeysetPaginationOptions as A, LookupOptions as At, ObjectId as B, FieldPreset as C, IControllerResponse as Ct, InferDocument as D, MongoKitPluginName as Dt, HookMode as E, MONGOKIT_PLUGIN_NAMES as Et, MiddlewareContext as F, Plugin as G, OperationOptions as H, MinMaxResult as I, PopulateSpec as J, PluginFunction as K, MinimalRepoView as L, LookupPopulateOptions as M, LookupPopulateResult as N, InferRawDoc as O, RepositoryPluginName as Ot, Middleware as P, RepositoryContext as Q, MongoOperatorUpdate as R, EventPhase as S, IController as St, GroupResult as T, IResponseFormatter as Tt, PaginationConfig as U, OffsetPaginationOptions as V, PartialBy as W, ReadOptions as X, PrioritizedHook as Y, ReadPreferenceType as Z, DeleteManyResult as _, ValidationChainOptions as _t, AnyModel as a, SessionOptions as at, EventHandlers as b, WithPlugins as bt, CacheableOptions as c, SoftDeleteRepository as ct, CollationOptions as d, Strict as dt, RepositoryInstance as et, CreateInput as f, UpdateManyResult as ft, DeepPartial as g, UserContext as gt, DecodedCursor as h, UpdateWithValidationResult as ht, AnyDocument as i, SelectSpec as it, Logger as j, KeysOfType as k, LookupBuilder as kt, CascadeOptions as l, SortDirection as lt, CursorPayload as m, UpdatePatch as mt, AggregatePaginationOptions as n, RepositoryOptions as nt, BasePaginationOptions as o, SoftDeleteFilterMode as ot, CreateOptions as p, UpdateOptions as pt, PluginType as q, AllPluginMethods as r, RequiredBy as rt, CacheOperationOptions as s, SoftDeleteOptions as st, AggregateOptions as t, RepositoryOperation as tt, CascadeRelation as u, SortSpec as ut, DeleteResult as v, ValidatorDefinition as vt, FindOneAndUpdateOptions as w, IRequestContext as wt, EventPayload as x, WithTransactionOptions as xt, DocField as y, ValueType as yt, NonNullableFields as z };