@classytic/mongokit 3.11.1 → 3.13.0

package/dist/{types-Dc2aDVUi.d.mts → types-BbaPZleN.d.mts}

@@ -1,9 +1,13 @@
+import * as _$_classytic_repo_core_filter0 from "@classytic/repo-core/filter";
+import { Filter } from "@classytic/repo-core/filter";
 import * as _$mongoose from "mongoose";
 import { Document, Model, PipelineStage, PopulateOptions, Types } from "mongoose";
-import * as _$_classytic_repo_core_filter0 from "@classytic/repo-core/filter";
+import * as _$_classytic_repo_core_cache0 from "@classytic/repo-core/cache";
 import * as _$_classytic_repo_core_repository0 from "@classytic/repo-core/repository";
-import { DeleteManyResult, DeleteResult, LookupPopulateResult, UpdateManyResult } from "@classytic/repo-core/repository";
+import { DeleteManyResult, DeleteResult, LookupPopulateResult, RepositoryBase, UpdateManyResult } from "@classytic/repo-core/repository";
 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 {
@@ -17,8 +21,15 @@ interface LookupOptions {
   as?: string;
   /** Whether to unwrap array to single object */
   single?: boolean;
-  /** Field selection on the joined collection (shorthand for $project pipeline) */
-  select?: string | Record<string, 0 | 1>;
+  /**
+   * 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 */
@@ -31,6 +42,18 @@ interface LookupOptions {
   };
   /** 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
@@ -298,7 +321,7 @@ interface IController<TDoc> {
    *   success: true,
    *   data: {
    *     method: 'offset',
-   *     docs: [...],
+   *     data: [...],
    *     total: 100,
    *     page: 1,
    *     pages: 5
@@ -307,7 +330,7 @@ interface IController<TDoc> {
    * }
    * ```
    */
-  list(context: IRequestContext): Promise<IControllerResponse<PaginationResult<TDoc>>>;
+  list(context: IRequestContext): Promise<IControllerResponse<AnyPaginationResult<TDoc>>>;
   /**
    * Get single resource by ID
    *
@@ -457,7 +480,7 @@ interface IResponseFormatter {
    * Format paginated response
    * @param result - Pagination result from Repository.getAll()
    */
-  paginated<T>(result: PaginationResult<T>): IControllerResponse<PaginationResult<T>>;
+  paginated<T>(result: AnyPaginationResult<T>): IControllerResponse<AnyPaginationResult<T>>;
 }
 //#endregion
 //#region src/types.d.ts
@@ -567,14 +590,161 @@ type CreateInput<TDoc> = Omit<TDoc, '_id' | 'createdAt' | 'updatedAt' | '__v'>;
  */
 type UpdatePatch<TDoc> = Partial<Omit<TDoc, '_id' | 'createdAt' | '__v'>>;
 /**
- * @deprecated Renamed to {@link UpdatePatch} in 3.11.0. This alias exists
- * for one release only and will be removed in 3.12. If you actually wanted
- * the bulk/find-and-update union (`UpdateSpec | Record | Record[]`), import
- * `UpdateInput` from `@classytic/repo-core/update` instead.
+ * 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
+ * ```
  */
-type UpdateInput<TDoc> = UpdatePatch<TDoc>;
+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 */
@@ -612,6 +782,82 @@ interface RepositoryOptions {
    *     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
+   * new Repository(OrderModel, [
+   *   methodRegistryPlugin(),
+   *   multiTenantPlugin({ tenantField: 'organizationId' }),
+   *   softDeletePlugin(),
+   *   auditLogPlugin({ logger }),
+   * ], paginationConfig, {
+   *   requirePlugins: ['multiTenant', 'softDelete', '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 string[];
 }
 /** Pagination configuration */
 interface PaginationConfig {
@@ -732,69 +978,75 @@ interface AggregatePaginationOptions {
   /** Read preference for replica sets (e.g. 'secondaryPreferred') */
   readPreference?: ReadPreferenceType;
 }
-/** Offset pagination result */
-interface OffsetPaginationResult<T = unknown> {
-  /** Pagination method used */
-  method: 'offset';
-  /** Array of documents */
-  docs: T[];
-  /** Current page number */
-  page: number;
-  /** Documents per page */
-  limit: number;
-  /** Total document count */
-  total: number;
-  /** Total page count */
-  pages: number;
-  /** Whether next page exists */
-  hasNext: boolean;
-  /** Whether previous page exists */
-  hasPrev: boolean;
-  /** Performance warning for deep pagination */
-  warning?: string;
-}
-/** Keyset pagination result */
-interface KeysetPaginationResult<T = unknown> {
-  /** Pagination method used */
-  method: 'keyset';
-  /** Array of documents */
-  docs: T[];
-  /** Documents per page */
-  limit: number;
-  /** Whether more documents exist */
-  hasMore: boolean;
-  /** Cursor token for next page */
-  next: string | null;
-}
-/** Aggregate pagination result */
-interface AggregatePaginationResult<T = unknown> {
-  /** Pagination method used */
-  method: 'aggregate';
-  /** Array of documents */
-  docs: T[];
-  /** Current page number */
-  page: number;
-  /** Documents per page */
-  limit: number;
-  /** Total document count */
-  total: number;
-  /** Total page count */
-  pages: number;
-  /** Whether next page exists */
-  hasNext: boolean;
-  /** Whether previous page exists */
-  hasPrev: boolean;
-  /** Performance warning for deep pagination */
-  warning?: string;
-}
-/** Union type for all pagination results */
-type PaginationResult<T = unknown> = OffsetPaginationResult<T> | KeysetPaginationResult<T> | AggregatePaginationResult<T>;
 /** 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;
   /** Extensible — plugins can read custom fields from options */
   [key: string]: unknown;
 }
@@ -821,12 +1073,14 @@ interface OperationOptions extends ReadOptions {
   /** Additional query filters (e.g., for soft delete) */
   query?: Record<string, unknown>;
 }
-/** Cache-aware operation options — extends OperationOptions with cache controls */
+/**
+ * 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 {
-  /** Skip cache for this operation (read from DB directly) */
-  skipCache?: boolean;
-  /** Custom TTL for this operation in seconds */
-  cacheTtl?: number;
+  /** Per-call cache override forwarded to the unified cache plugin. */
+  cache?: _$_classytic_repo_core_cache0.CacheOptions;
 }
 /** withTransaction options */
 interface WithTransactionOptions {
@@ -1009,6 +1263,15 @@ interface RepositoryContext {
   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 */
@@ -1044,37 +1307,68 @@ interface RepositoryContext {
    *   is the only source of soft semantics.
    */
   deleteMode?: 'hard' | 'soft';
-  /** Skip cache for this operation */
-  skipCache?: boolean;
-  /** Custom TTL for this operation (seconds) */
-  cacheTtl?: number;
-  /** Whether result was served from cache (internal) */
+  /**
+   * 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?: _$_classytic_repo_core_cache0.CacheOptions;
+  /** Whether result was served from cache (internal — set by cache plugin) */
   _cacheHit?: boolean;
-  /** Cached result (internal) */
+  /** 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 */
-interface Plugin {
+/**
+ * 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: RepositoryInstance): void;
+  apply(repo: TRepo): void;
 }
-/** Plugin function signature */
-type PluginFunction = (repo: RepositoryInstance) => void;
-/** Plugin type (object or function) */
-type PluginType = Plugin | PluginFunction;
+/** 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 */
-interface RepositoryInstance {
+/**
+ * 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[]>;
@@ -1092,13 +1386,14 @@ interface RepositoryInstance {
   _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';
+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';
 /** Event lifecycle phases */
 type EventPhase = 'before' | 'after' | 'error';
 /** Repository event names (generated from template literals) */
@@ -1136,6 +1431,27 @@ interface FieldPreset {
   /** 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 */
@@ -1237,84 +1553,13 @@ interface MinMaxResult {
   max: unknown;
 }
 /**
- * Cache adapter interface — bring your own cache implementation.
- * Works with Redis, Memcached, in-memory, or any key-value store.
- *
- * Shape is aligned with `@classytic/repo-core/cache#CacheAdapter` and arc's
- * `CacheStore` so one adapter implementation satisfies every consumer. The
- * `delete` method is named for consistency with `Map.delete` / `Set.delete` /
- * `MinimalRepo.delete(id)` — your Redis wrapper translates to `redis.del`.
- *
- * @example Redis implementation:
- * ```typescript
- * const redisCache: CacheAdapter = {
- *   async get(key) { return JSON.parse(await redis.get(key) || 'null'); },
- *   async set(key, value, ttl) { await redis.setex(key, ttl, JSON.stringify(value)); },
- *   async delete(key) { await redis.del(key); },
- *   async clear(pattern) {
- *     const keys = await redis.keys(pattern || '*');
- *     if (keys.length) await redis.del(...keys);
- *   }
- * };
- * ```
+ * 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 CacheAdapter {
-  /** Get value by key, returns null if not found or expired */
-  get<T = unknown>(key: string): Promise<T | null>;
-  /** Set value with TTL in seconds */
-  set<T = unknown>(key: string, value: T, ttl: number): Promise<void>;
-  /** Delete a single key. No-op when the key doesn't exist. */
-  delete(key: string): Promise<void>;
-  /** Clear keys matching pattern (optional, used for bulk invalidation) */
-  clear?(pattern?: string): Promise<void>;
-}
-/** Cache plugin options */
-interface CacheOptions {
-  /** Cache adapter implementation (required) */
-  adapter: CacheAdapter;
-  /** Default TTL in seconds (default: 60) */
-  ttl?: number;
-  /** TTL for byId queries in seconds (default: same as ttl) */
-  byIdTtl?: number;
-  /** TTL for query/list results in seconds (default: same as ttl) */
-  queryTtl?: number;
-  /** Key prefix for namespacing (default: 'mk') */
-  prefix?: string;
-  /** Enable debug logging (default: false) */
-  debug?: boolean;
-  /**
-   * Skip caching for queries with these characteristics:
-   * - largeLimit: Skip if limit > value (default: 100)
-   */
-  skipIf?: {
-    largeLimit?: number;
-  };
-  /**
-   * TTL jitter to mitigate cache stampedes. When many entries share the same
-   * TTL and expire simultaneously, every concurrent reader misses and hammers
-   * the DB at once. Jitter spreads expirations over a window.
-   *
-   * - `number` in [0, 1]: fractional symmetric jitter. `0.1` multiplies the
-   *   TTL by a random factor in [0.9, 1.1]. Default: 0 (no jitter).
-   * - `function(ttl)`: full control — receive the configured TTL (seconds),
-   *   return the effective TTL (seconds) to store with.
-   */
-  jitter?: number | ((ttlSeconds: number) => number);
-}
-/** Options for cache-aware operations */
 interface CacheOperationOptions {
-  /** Skip cache for this operation (read from DB directly) */
-  skipCache?: boolean;
-  /** Custom TTL for this operation in seconds */
-  cacheTtl?: number;
-}
-/** Cache statistics (for debugging/monitoring) */
-interface CacheStats {
-  hits: number;
-  misses: number;
-  sets: number;
-  invalidations: number;
-  errors: number;
+  /** Per-call cache override forwarded to the unified cache plugin. */
+  cache?: _$_classytic_repo_core_cache0.CacheOptions;
 }
 /** Cascade relation definition */
 interface CascadeRelation {
@@ -1349,37 +1594,6 @@ interface CascadeOptions {
   /** Logger for cascade operations */
   logger?: Logger;
 }
-/** HTTP Error with status code */
-interface HttpError extends Error {
-  status: number;
-  /**
-   * Stable machine-readable error code. Hosts can switch on this in catch
-   * blocks instead of grepping the message string. Currently emitted for:
-   * - `SEARCH_NOT_CONFIGURED` — search requested on a repo with no text
-   *   index AND no `searchMode: 'regex' | 'auto'` + `searchFields` config.
-   */
-  code?: string;
-  /**
-   * Free-form structured metadata for diagnostics. Pairs with `code` so
-   * hosts can render a clearer message in their own UI without parsing
-   * the human-readable `message` string. Safe for logs.
-   */
-  meta?: Record<string, unknown>;
-  validationErrors?: Array<{
-    validator: string;
-    error: string;
-  }>;
-  /**
-   * Structured metadata for duplicate-key (E11000) errors. Safe to surface in
-   * logs/audit. Includes the offending field names and a boolean-only mirror
-   * of whether each field had a duplicate value — never the value itself
-   * unless `parseDuplicateKeyError` was called with `{ exposeValues: true }`.
-   */
-  duplicate?: {
-    fields: string[]; /** Only populated when parseDuplicateKeyError was called with exposeValues:true. */
-    values?: Record<string, unknown>;
-  };
-}
 /**
  * Combines all plugin method types into a single type
  * Useful when you're using all plugins and want full type safety
@@ -1396,7 +1610,7 @@ interface HttpError extends Error {
  * // TypeScript knows about all plugin methods!
  * await repo.increment(id, 'views', 1);
  * await repo.restore(id);
- * await repo.invalidateCache(id);
+ * await repo.cache?.invalidateByTags(['org:abc']);
  * ```
  *
  * Note: Import the individual plugin method types if you need them:
@@ -1407,7 +1621,6 @@ interface HttpError extends Error {
  *   AggregateHelpersMethods,
  *   SubdocumentMethods,
  *   SoftDeleteMethods,
- *   CacheMethods,
  * } from '@classytic/mongokit';
  * ```
  */
@@ -1478,11 +1691,12 @@ type AllPluginMethods<TDoc> = {
     lean?: boolean;
     session?: unknown;
   }): Promise<OffsetPaginationResult<TDoc>>;
-  invalidateCache(id: string): Promise<void>;
-  invalidateListCache(): Promise<void>;
-  invalidateAllCache(): Promise<void>;
-  getCacheStats(): CacheStats;
-  resetCacheStats(): void;
+  /**
+   * Cache plugin handle (set by `cachePlugin({ adapter })`). Exposes the
+   * `CacheEngine` plus convenience invalidation helpers. `undefined` when
+   * no cache plugin is wired.
+   */
+  cache?: _$_classytic_repo_core_cache0.RepositoryCacheHandle;
 };
 /**
  * Helper type to add all plugin methods to a repository class
@@ -1510,4 +1724,4 @@ type AllPluginMethods<TDoc> = {
  */
 type WithPlugins<TDoc, TRepo extends RepositoryInstance = RepositoryInstance> = TRepo & AllPluginMethods<TDoc>;
 //#endregion
-export { ReadPreferenceType as $, InferDocument as A, ObjectId as B, EventPayload as C, WithTransactionOptions as Ct, GroupResult as D, IResponseFormatter as Dt, FindOneAndUpdateOptions as E, IRequestContext as Et, Logger as F, PaginationResult as G, OffsetPaginationResult as H, LookupPopulateOptions as I, PluginFunction as J, PartialBy as K, LookupPopulateResult as L, KeysOfType as M, KeysetPaginationOptions as N, HookMode as O, LookupBuilder as Ot, KeysetPaginationResult as P, ReadOptions as Q, MinMaxResult as R, EventHandlers as S, WithPlugins as St, FieldPreset as T, IControllerResponse as Tt, OperationOptions as U, OffsetPaginationOptions as V, PaginationConfig as W, PopulateSpec as X, PluginType as Y, PrioritizedHook as Z, DecodedCursor as _, UpdatePatch as _t, AnyDocument as a, RequiredBy as at, DeleteResult as b, ValidationChainOptions as bt, CacheOperationOptions as c, SoftDeleteFilterMode as ct, CacheableOptions as d, SortDirection as dt, RepositoryContext as et, CascadeOptions as f, SortSpec as ft, CreateOptions as g, UpdateOptions as gt, CreateInput as h, UpdateManyResult as ht, AllPluginMethods as i, RepositoryOptions as it, InferRawDoc as j, HttpError as k, LookupOptions as kt, CacheOptions as l, SoftDeleteOptions as lt, CollationOptions as m, UpdateInput as mt, AggregatePaginationOptions as n, RepositoryInstance as nt, AnyModel as o, SelectSpec as ot, CascadeRelation as p, Strict as pt, Plugin as q, AggregatePaginationResult as r, RepositoryOperation as rt, CacheAdapter as s, SessionOptions as st, AggregateOptions as t, RepositoryEvent as tt, CacheStats as u, SoftDeleteRepository as ut, DeepPartial as v, UpdateWithValidationResult as vt, EventPhase as w, IController as wt, DocField as x, ValidatorDefinition as xt, DeleteManyResult as y, UserContext as yt, NonNullableFields as z };
+export { RepositoryEvent as $, KeysetPaginationOptions as A, ObjectId as B, FieldPreset as C, IControllerResponse as Ct, InferDocument as D, LookupOptions as Dt, HookMode as E, LookupBuilder 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, 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, 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 };