@classytic/mongokit 3.17.0 → 3.19.0

package/dist/create-repository-K0yft2ht.d.mts

@@ -0,0 +1,1663 @@
+import { B as ObjectId, Dt as LookupOptions, Et as LookupBuilder, H as OperationOptions, J as PopulateSpec, M as LookupPopulateOptions, N as LookupPopulateResult, P as Middleware, Q as RepositoryContext, U as PaginationConfig, X as ReadOptions, Y as PrioritizedHook, Z as ReadPreferenceType, _ as DeleteManyResult, at as SessionOptions, c as CacheableOptions, d as CollationOptions, ft as UpdateManyResult, it as SelectSpec, j as Logger, n as AggregatePaginationOptions, nt as RepositoryOptions, p as CreateOptions, pt as UpdateOptions, q as PluginType, st as SoftDeleteOptions, t as AggregateOptions, ut as SortSpec$1, v as DeleteResult, w as FindOneAndUpdateOptions, xt as WithTransactionOptions } from "./types-BA8oXjFe.mjs";
+import { _ as RepositoryCachePluginOptions, i as CustomIdOptions, t as MultiTenantOptions, w as AuditTrailOptions } from "./multi-tenant.plugin-D6lw3BsI.mjs";
+import { t as PaginationEngine } from "./PaginationEngine-4SjzfBQE.mjs";
+import { AggPaginationRequest, AggRequest, AggResult, ChangeEvent, FilterInput, KeysetAggPaginationResult, QueryOptions, RepoCapabilities, RepositoryBase, TenantPurgeOptions, TenantPurgeResult, TenantPurgeStrategy, WatchOptions } from "@classytic/repo-core/repository";
+import * as _$mongoose from "mongoose";
+import { Expression, Model, PipelineStage, PopulateOptions } from "mongoose";
+import { UpdateInput } from "@classytic/repo-core/update";
+import { AggregatePaginationResult, KeysetPaginationResult, OffsetPaginationResult, OffsetPaginationResultCore } from "@classytic/repo-core/pagination";
+import { HttpError } from "@classytic/repo-core/errors";
+
+//#region src/query/AggregationBuilder.d.ts
+/** Options for $vectorSearch stage (Atlas only) */
+interface VectorSearchOptions {
+  /** Atlas Search index name */
+  index: string;
+  /** Field path containing the vector embedding */
+  path: string;
+  /** Query vector to search against */
+  queryVector: number[];
+  /** Number of candidates to consider (higher = more accurate, slower) */
+  numCandidates?: number;
+  /** Max results to return */
+  limit: number;
+  /** Pre-filter documents before vector search */
+  filter?: Record<string, unknown>;
+  /** Use exact search instead of ANN (slower but precise) */
+  exact?: boolean;
+}
+/** Result from build() including execution options */
+interface AggregationPlan {
+  pipeline: PipelineStage[];
+  allowDiskUse: boolean;
+}
+type SortOrder = 1 | -1 | 'asc' | 'desc';
+type SortSpec = Record<string, SortOrder>;
+type ProjectionSpec = Record<string, 0 | 1 | Expression>;
+type GroupSpec = {
+  _id: string | Record<string, unknown> | null;
+  [key: string]: unknown;
+};
+/**
+ * Fluent builder for MongoDB aggregation pipelines
+ * Optimized for complex queries at scale
+ */
+declare class AggregationBuilder {
+  private pipeline;
+  private _diskUse;
+  /**
+   * Get the current pipeline
+   */
+  get(): PipelineStage[];
+  /**
+   * Build and return the final pipeline
+   */
+  build(): PipelineStage[];
+  /**
+   * Build pipeline with execution options (allowDiskUse, etc.)
+   */
+  plan(): AggregationPlan;
+  /**
+   * Build and execute the pipeline against a model
+   *
+   * @example
+   * ```typescript
+   * const results = await new AggregationBuilder()
+   *   .match({ status: 'active' })
+   *   .allowDiskUse()
+   *   .exec(MyModel);
+   * ```
+   */
+  exec<T = unknown>(model: Model<any>, session?: _$mongoose.ClientSession): Promise<T[]>;
+  /**
+   * Reset the pipeline
+   */
+  reset(): this;
+  /**
+   * Add a raw pipeline stage
+   */
+  addStage(stage: PipelineStage): this;
+  /**
+   * Add multiple raw pipeline stages
+   */
+  addStages(stages: PipelineStage[]): this;
+  /**
+   * $match - Filter documents
+   * IMPORTANT: Place $match as early as possible for performance
+   */
+  match(query: Record<string, unknown>): this;
+  /**
+   * $project - Include/exclude fields or compute new fields
+   */
+  project(projection: ProjectionSpec): this;
+  /**
+   * $group - Group documents and compute aggregations
+   *
+   * @example
+   * ```typescript
+   * .group({
+   *   _id: '$department',
+   *   count: { $sum: 1 },
+   *   avgSalary: { $avg: '$salary' }
+   * })
+   * ```
+   */
+  group(groupSpec: GroupSpec): this;
+  /**
+   * $sort - Sort documents
+   */
+  sort(sortSpec: SortSpec | string): this;
+  /**
+   * $limit - Limit number of documents
+   */
+  limit(count: number): this;
+  /**
+   * $skip - Skip documents
+   */
+  skip(count: number): this;
+  /**
+   * $unwind - Deconstruct array field
+   */
+  unwind(path: string, preserveNullAndEmptyArrays?: boolean): this;
+  /**
+   * $addFields - Add new fields or replace existing fields
+   */
+  addFields(fields: Record<string, unknown>): this;
+  /**
+   * $set - Alias for $addFields
+   */
+  set(fields: Record<string, unknown>): this;
+  /**
+   * $unset - Remove fields
+   */
+  unset(fields: string | string[]): this;
+  /**
+   * $replaceRoot - Replace the root document
+   */
+  replaceRoot(newRoot: string | Record<string, unknown>): this;
+  /**
+   * $lookup - Join with another collection (simple form)
+   *
+   * @param from - Collection to join with
+   * @param localField - Field from source collection
+   * @param foreignField - Field from target collection
+   * @param as - Output field name
+   * @param single - Unwrap array to single object
+   *
+   * @example
+   * ```typescript
+   * // Join employees with departments by slug
+   * .lookup('departments', 'deptSlug', 'slug', 'department', true)
+   * ```
+   */
+  lookup(from: string, localField: string, foreignField: string, as?: string, single?: boolean): this;
+  /**
+   * $lookup - Join with another collection (advanced form with pipeline)
+   *
+   * @example
+   * ```typescript
+   * .lookupWithPipeline({
+   *   from: 'products',
+   *   localField: 'productIds',
+   *   foreignField: 'sku',
+   *   as: 'products',
+   *   pipeline: [
+   *     { $match: { status: 'active' } },
+   *     { $project: { name: 1, price: 1 } }
+   *   ]
+   * })
+   * ```
+   */
+  lookupWithPipeline(options: LookupOptions): this;
+  /**
+   * Multiple lookups at once
+   *
+   * @example
+   * ```typescript
+   * .multiLookup([
+   *   { from: 'departments', localField: 'deptSlug', foreignField: 'slug', single: true },
+   *   { from: 'managers', localField: 'managerId', foreignField: '_id', single: true }
+   * ])
+   * ```
+   */
+  multiLookup(lookups: LookupOptions[]): this;
+  /**
+   * $facet - Process multiple aggregation pipelines in a single stage
+   * Useful for computing multiple aggregations in parallel
+   *
+   * @example
+   * ```typescript
+   * .facet({
+   *   totalCount: [{ $count: 'count' }],
+   *   avgPrice: [{ $group: { _id: null, avg: { $avg: '$price' } } }],
+   *   topProducts: [{ $sort: { sales: -1 } }, { $limit: 10 }]
+   * })
+   * ```
+   */
+  facet(facets: Record<string, PipelineStage[]>): this;
+  /**
+   * $bucket - Categorize documents into buckets
+   *
+   * @example
+   * ```typescript
+   * .bucket({
+   *   groupBy: '$price',
+   *   boundaries: [0, 50, 100, 200],
+   *   default: 'Other',
+   *   output: {
+   *     count: { $sum: 1 },
+   *     products: { $push: '$name' }
+   *   }
+   * })
+   * ```
+   */
+  bucket(options: {
+    groupBy: string | Expression;
+    boundaries: unknown[];
+    default?: string;
+    output?: Record<string, unknown>;
+  }): this;
+  /**
+   * $bucketAuto - Automatically determine bucket boundaries
+   */
+  bucketAuto(options: {
+    groupBy: string | Expression;
+    buckets: number;
+    output?: Record<string, unknown>;
+    granularity?: string;
+  }): this;
+  /**
+   * $setWindowFields - Perform window functions (MongoDB 5.0+)
+   * Useful for rankings, running totals, moving averages
+   *
+   * @example
+   * ```typescript
+   * .setWindowFields({
+   *   partitionBy: '$department',
+   *   sortBy: { salary: -1 },
+   *   output: {
+   *     rank: { $rank: {} },
+   *     runningTotal: { $sum: '$salary', window: { documents: ['unbounded', 'current'] } }
+   *   }
+   * })
+   * ```
+   */
+  setWindowFields(options: {
+    partitionBy?: string | Expression;
+    sortBy?: SortSpec;
+    output: Record<string, unknown>;
+  }): this;
+  /**
+   * $unionWith - Combine results from multiple collections (MongoDB 4.4+)
+   *
+   * @example
+   * ```typescript
+   * .unionWith({
+   *   coll: 'archivedOrders',
+   *   pipeline: [{ $match: { year: 2024 } }]
+   * })
+   * ```
+   */
+  unionWith(options: {
+    coll: string;
+    pipeline?: PipelineStage[];
+  }): this;
+  /**
+   * $densify - Fill gaps in data (MongoDB 5.1+)
+   * Useful for time series data with missing points
+   */
+  densify(options: {
+    field: string;
+    range: {
+      step: number;
+      unit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+      bounds: 'full' | 'partition' | [unknown, unknown];
+    };
+  }): this;
+  /**
+   * $fill - Fill null or missing field values (MongoDB 5.3+)
+   */
+  fill(options: {
+    sortBy?: SortSpec;
+    output: Record<string, {
+      method: 'linear' | 'locf' | 'value';
+      value?: unknown;
+    }>;
+  }): this;
+  /**
+   * Enable allowDiskUse for large aggregations that exceed 100MB memory limit
+   *
+   * @example
+   * ```typescript
+   * const results = await new AggregationBuilder()
+   *   .match({ status: 'active' })
+   *   .group({ _id: '$category', total: { $sum: '$amount' } })
+   *   .allowDiskUse()
+   *   .exec(Model);
+   * ```
+   */
+  allowDiskUse(enable?: boolean): this;
+  /**
+   * Paginate - Add skip and limit for offset-based pagination
+   */
+  paginate(page: number, limit: number): this;
+  /**
+   * Count total documents (useful with $facet for pagination metadata)
+   */
+  count(outputField?: string): this;
+  /**
+   * Sample - Randomly select N documents
+   */
+  sample(size: number): this;
+  /**
+   * Out - Write results to a collection
+   */
+  out(collection: string): this;
+  /**
+   * Merge - Merge results into a collection
+   */
+  merge(options: string | {
+    into: string;
+    on?: string | string[];
+    whenMatched?: string;
+    whenNotMatched?: string;
+  }): this;
+  /**
+   * GeoNear - Perform geospatial queries
+   */
+  geoNear(options: {
+    near: {
+      type: 'Point';
+      coordinates: [number, number];
+    };
+    distanceField: string;
+    maxDistance?: number;
+    query?: Record<string, unknown>;
+    spherical?: boolean;
+  }): this;
+  /**
+   * GraphLookup - Perform recursive search (graph traversal)
+   */
+  graphLookup(options: {
+    from: string;
+    startWith: string | Expression;
+    connectFromField: string;
+    connectToField: string;
+    as: string;
+    maxDepth?: number;
+    depthField?: string;
+    restrictSearchWithMatch?: Record<string, unknown>;
+  }): this;
+  /**
+   * $search - Atlas Search full-text search (Atlas only)
+   *
+   * @example
+   * ```typescript
+   * .search({
+   *   index: 'default',
+   *   text: {
+   *     query: 'laptop computer',
+   *     path: ['title', 'description'],
+   *     fuzzy: { maxEdits: 2 }
+   *   }
+   * })
+   * ```
+   */
+  search(options: {
+    index?: string;
+    text?: {
+      query: string;
+      path: string | string[];
+      fuzzy?: {
+        maxEdits?: number;
+        prefixLength?: number;
+      };
+      score?: {
+        boost?: {
+          value?: number;
+        };
+      };
+    };
+    compound?: {
+      must?: unknown[];
+      mustNot?: unknown[];
+      should?: unknown[];
+      filter?: unknown[];
+    };
+    autocomplete?: unknown;
+    near?: unknown;
+    range?: unknown;
+  }): this;
+  /**
+   * $searchMeta - Get Atlas Search metadata (Atlas only)
+   */
+  searchMeta(options: Record<string, unknown>): this;
+  /**
+   * $vectorSearch - Semantic similarity search using vector embeddings (Atlas only)
+   *
+   * Requires an Atlas Vector Search index on the target field.
+   * Must be the first stage in the pipeline.
+   *
+   * @example
+   * ```typescript
+   * const results = await new AggregationBuilder()
+   *   .vectorSearch({
+   *     index: 'vector_index',
+   *     path: 'embedding',
+   *     queryVector: await getEmbedding('running shoes'),
+   *     limit: 10,
+   *     numCandidates: 100,
+   *     filter: { category: 'footwear' }
+   *   })
+   *   .project({ embedding: 0, score: { $meta: 'vectorSearchScore' } })
+   *   .exec(ProductModel);
+   * ```
+   */
+  vectorSearch(options: VectorSearchOptions): this;
+  /**
+   * Add vectorSearchScore as a field after $vectorSearch
+   * Convenience for `.addFields({ score: { $meta: 'vectorSearchScore' } })`
+   */
+  withVectorScore(fieldName?: string): this;
+  /**
+   * Create a builder from an existing pipeline
+   */
+  static from(pipeline: PipelineStage[]): AggregationBuilder;
+  /**
+   * Create a builder with initial match stage
+   */
+  static startWith(query: Record<string, unknown>): AggregationBuilder;
+}
+//#endregion
+//#region src/Repository.d.ts
+/**
+ * Plugin phase priorities (lower = runs first).
+ *
+ * Re-exported from `@classytic/repo-core/hooks` so mongokit 3.10 callers see
+ * the same constant whether they import from mongokit or directly from
+ * repo-core — priorities are identical (POLICY=100, CACHE=200,
+ * OBSERVABILITY=300, DEFAULT=500) and the two refs are reference-equal.
+ */
+declare const HOOK_PRIORITY: {
+  readonly POLICY: 100;
+  readonly VALIDATION: 150;
+  readonly CACHE: 200;
+  readonly OBSERVABILITY: 300;
+  readonly DEFAULT: 500;
+};
+/**
+ * Production-grade repository for MongoDB.
+ *
+ * Extends `@classytic/repo-core/repository`'s `RepositoryBase` for the
+ * driver-agnostic hook + plugin plumbing (context builder, priority-sorted
+ * event engine, plugin-order validator) while layering every Mongo-specific
+ * concern — populate, aggregate, lookup, keyset + cursor pagination, $near
+ * rewriting — on top.
+ *
+ * Public surface is byte-stable with mongokit 3.9 (the `_hooks` property is
+ * preserved as a live read-through getter; all CRUD, event, and plugin method
+ * signatures unchanged). 3.10 is an internal re-plumbing release; consumers
+ * upgrading from 3.9 need no code changes.
+ */
+declare class Repository<TDoc = unknown> extends RepositoryBase {
+  /**
+   * Runtime capability descriptor required by `StandardRepo<TDoc>`
+   * (repo-core 0.6.0). Hosts feature-detect once at boot instead of
+   * try/catching `UnsupportedOperationError` per call.
+   */
+  readonly capabilities: RepoCapabilities;
+  readonly Model: Model<TDoc>;
+  /**
+   * Mongoose model name. Duplicated on the instance for BC — arc / catalog /
+   * user code read `repo.model`. `RepositoryBase.modelName` points to the
+   * same string; prefer `modelName` in new code.
+   */
+  readonly model: string;
+  readonly _pagination: PaginationEngine<TDoc>;
+  readonly idField: string;
+  readonly searchMode: 'text' | 'regex' | 'auto';
+  readonly searchFields: string[] | undefined;
+  [key: string]: unknown;
+  private _hasTextIndex;
+  /**
+   * Wrap-style middleware chain. Composed around every `_runOp`
+   * invocation in registration order — earlier-registered middlewares
+   * are outer (run first / unwind last). See `useMiddleware()` and
+   * the `Middleware<TDoc>` type for the protocol.
+   */
+  private readonly _middlewares;
+  constructor(Model: Model<TDoc, any, any, any>, plugins?: PluginType[], paginationConfig?: PaginationConfig, options?: RepositoryOptions);
+  /**
+   * Live read-through view of the hook engine's listener registry.
+   *
+   * Preserved as a public field on the Repository for back-compat with
+   * mongokit ≤3.9 — existing tests and observability code pattern-match
+   * `repo._hooks.get('before:getAll')` / `repo._hooks.size`. Each access
+   * returns a fresh snapshot of the underlying HookEngine state.
+   *
+   * Read-only. To register listeners use `repo.on(event, listener, { priority })`.
+   */
+  get _hooks(): Map<string, PrioritizedHook[]>;
+  /**
+   * Fire-and-forget emit aliased through RepositoryBase's async path so
+   * error hooks converted to/from sync mode still route uniformly. Mongokit
+   * ≤3.9 made this a private method on its subclass; the base class exposes
+   * it publicly and wraps it in `_emitHook` below for internal use.
+   */
+  private _emitHook;
+  private _emitErrorHook;
+  /**
+   * Wire the `warnOnStrictQueryStrip` diagnostic. When enabled, every
+   * filter-shaped op (`getById`, `getByQuery`, `getOne`, `findAll`,
+   * `count`, `exists`, `update`, `delete`, `findOneAndUpdate`,
+   * `updateMany`, `deleteMany`, `claim`, `claimVersion`, `cursor`)
+   * checks its `context.query` keys against the cached set of schema
+   * paths. Top-level keys not on the schema get logged once per
+   * `(model, key)` pair — so a single bad caller surfaces in dev /
+   * staging instead of returning the wrong row in prod.
+   *
+   * Only runs when `strictQuery !== false` is in effect — if mongoose's
+   * strictQuery is off, unknown keys flow through to the driver and
+   * the trap doesn't apply.
+   */
+  private _wireStrictQueryStripDiagnostic;
+  /**
+   * Register a wrap-style middleware. Middleware composes AROUND every
+   * `_runOp` invocation — it sees the operation name, the live
+   * `RepositoryContext`, and a `next()` continuation that runs the
+   * remaining chain + the actual op + after/error hooks.
+   *
+   * **Composes with `repo.on()` and plugins, doesn't replace them.**
+   * Middleware is for ergonomics (timing, short-circuit, input/output
+   * mutation in a single closure) — NOT for security policy. Use the
+   * `before:*` hook engine for tenant scope, soft-delete filtering,
+   * cache invalidation, and audit; those plugins MUST run before
+   * middleware sees the op.
+   *
+   * **Execution order on every call** (build/before hooks fire BEFORE
+   * the middleware chain dispatches, so middleware cannot wrap a
+   * before-hook failure):
+   *
+   * ```text
+   *   _buildContext + before:<op>   ← repo.on('before:*') hooks
+   *     [outer middleware pre]      ← repo.useMiddleware() registrations
+   *       [...inner middleware pre]
+   *         fn (driver call)
+   *         after:<op> | error:<op> ← repo.on('after:*' / 'error:*')
+   *       [...inner middleware post]
+   *     [outer middleware post]
+   * ```
+   *
+   * Why this order matters: a `before:create` hook that injects a
+   * tenant filter into `context.query` runs BEFORE the middleware chain
+   * is composed. Middleware sees a context that was already scoped by
+   * the policy plugins — it never has the authority to short-circuit a
+   * tenant check, because the throw from a `before:*` policy hook
+   * unwinds before middleware ever fires. That's by design — middleware
+   * as a security boundary would be impossible to audit, since
+   * registration order would determine whether scope wins.
+   *
+   * Practical consequence: if you want middleware to observe a policy
+   * failure (e.g. metric a tenant-scope rejection), use `repo.on('error:
+   * <op>', ...)` instead — that fires from inside the middleware chain
+   * and is reachable.
+   *
+   * Registration order = composition order: the first middleware
+   * registered runs outermost (wraps everything else).
+   *
+   * @example Time every op
+   * ```ts
+   * repo.useMiddleware(async ({ operation, next }) => {
+   *   const start = performance.now();
+   *   try { return await next(); }
+   *   finally { metrics.record(operation, performance.now() - start); }
+   * });
+   * ```
+   *
+   * @example Inject `tenantId` on every create
+   * ```ts
+   * repo.useMiddleware(async ({ operation, context, next }) => {
+   *   if (operation === 'create' && context.data) {
+   *     context.data.tenantId = currentTenant();
+   *   }
+   *   return next();
+   * });
+   * ```
+   *
+   * @example Short-circuit (return without `next()` to skip the actual op)
+   * ```ts
+   * repo.useMiddleware(async ({ operation, context, next }) => {
+   *   if (operation === 'getById' && readOnlyMaintenance) {
+   *     return cachedReadOnlyResponse(context.id);
+   *   }
+   *   return next();
+   * });
+   * ```
+   */
+  useMiddleware(middleware: Middleware<TDoc>): this;
+  /**
+   * Compose the registered middleware chain around `exec`. Outermost
+   * middleware (first registered) wraps innermost. Each middleware sees
+   * the live `RepositoryContext` (already populated + run through
+   * `before:*` hooks at the call site — see `useMiddleware` JSDoc for
+   * the exact order). `after:` / `error:` hooks fire from inside
+   * `exec`, so middleware composes WITH plugins, not instead of them.
+   *
+   * `_runOp` calls this with its standard try/catch envelope; inline-try
+   * methods (`getById`, `update`, `delete`, `deleteMany`, `aggregatePaginate`,
+   * `lookupPopulate`, plus `getOne`/`getAll` cache-hit branches) call it
+   * directly so middleware sees every op — including cached reads — not
+   * just the ones routed through `_runOp`.
+   */
+  private _composeMiddleware;
+  /**
+   * Standard operation envelope: compose middleware around an exec that
+   * runs `fn`, emits `after:<op>` on success or `error:<op>` on failure.
+   * Methods with branched in-try logic that emit `after:*` from multiple
+   * paths (`getById`, `update`, `delete`, `deleteMany`, `aggregatePaginate`,
+   * `lookupPopulate`) keep their inline try/catch and call
+   * `_composeMiddleware` directly instead of being forced through this
+   * single-result helper.
+   */
+  private _runOp;
+  /**
+   * Resilience envelope around the DRIVER round-trip only — the repo-core
+   * 0.6.0 `QueryOptions.signal` / `QueryOptions.retryPolicy` contract.
+   *
+   * `throwIfAborted` stops a cancelled request before the next driver call;
+   * `withRetry` retries transient failures with exponential backoff (and is
+   * a zero-cost passthrough when no policy was passed, so we wrap
+   * unconditionally). Crucially this wraps `fn` AFTER `_buildContext` ran —
+   * before-hooks (validation, tenant scope, audit, events) execute exactly
+   * once per logical call and are NEVER re-run on retry; only the driver
+   * call repeats.
+   *
+   * Both knobs are read from the context (the options bag is spread into
+   * `_buildContext` inputs), so every op routed through `_runOp` — and the
+   * inline-try methods that call this directly — honors them uniformly.
+   */
+  private _withResilience;
+  /**
+   * Create single document
+   */
+  create(data: Record<string, unknown>, options?: CreateOptions): Promise<TDoc>;
+  /**
+   * Create multiple documents
+   */
+  createMany(dataArray: Record<string, unknown>[], options?: CreateOptions): Promise<TDoc[]>;
+  /**
+   * Get document by ID
+   */
+  getById(id: string | ObjectId, options?: CacheableOptions): Promise<TDoc | null>;
+  /**
+   * Get single document by query
+   */
+  getByQuery(query: Record<string, unknown>, options?: CacheableOptions & {
+    sort?: SortSpec$1;
+  }): Promise<TDoc | null>;
+  /**
+   * Get single document by arbitrary filter.
+   * Unlike getByQuery, this method is designed for Arc/controller use where
+   * compound filters (org scope + policy + id) are pre-built.
+   *
+   * @example
+   * const product = await repo.getOne({ slug: 'laptop', organizationId: 'org_1' });
+   */
+  getOne(query: Record<string, unknown>, options?: CacheableOptions & {
+    sort?: SortSpec$1;
+  }): Promise<TDoc | null>;
+  /**
+   * Fetch ALL documents matching filters without pagination.
+   * Use for background jobs, exports, batch processing where you need every doc.
+   *
+   * @example
+   * const all = await repo.findAll({ status: 'active' });
+   * const allLean = await repo.findAll({}, { select: 'name email', lean: true });
+   */
+  findAll(filters?: Record<string, unknown>, options?: OperationOptions & {
+    sort?: SortSpec$1 | string;
+    limit?: number;
+  }): Promise<TDoc[]>;
+  /**
+   * Streaming reads — async iterator over data, suitable for migrations,
+   * backfills, schema audits, and any once-a-quarter "touch every row"
+   * job. Goes through the standard `before:cursor` hook pipeline so
+   * multi-tenant scope, soft-delete filter, and access-control plugins
+   * inject scope BEFORE the underlying mongoose cursor is built.
+   *
+   * Replaces direct `Model.find().cursor()` usage which bypasses every
+   * plugin — that's how cross-tenant data ends up in migrations.
+   *
+   * Returns an `AsyncIterableIterator<TDoc>` — drive it with `for await`.
+   * The mongoose cursor is closed when iteration completes or breaks.
+   *
+   * @example Backfill a missing field across the whole tenant scope
+   * ```ts
+   * for await (const doc of repo.cursor({ filter: { migrated: { $ne: true }}}, { batchSize: 1000 })) {
+   *   await transformer(doc);
+   *   await repo.update(doc._id, { migrated: true });
+   * }
+   * ```
+   *
+   * @example Audit unscoped — opt out of multi-tenant for global sweeps
+   * ```ts
+   * for await (const doc of repo.cursor({}, { batchSize: 500, organizationId: undefined })) {
+   *   audit(doc);
+   * }
+   * ```
+   */
+  cursor(filter?: Record<string, unknown>, options?: ReadOptions & {
+    sort?: SortSpec$1 | string;
+    batchSize?: number;
+    select?: SelectSpec;
+    lean?: boolean;
+  }): AsyncIterableIterator<TDoc>;
+  /**
+   * Portable change feed — `StandardRepo.watch()` over Mongo change
+   * streams (`Model.watch`). Requires a replica set (or mongos); a
+   * standalone mongod rejects change streams at open time — gate on
+   * `repo.capabilities.changeStreams` plus your deployment topology.
+   *
+   * Semantics:
+   *   - **Plugin-routed like every other read.** The filter goes through
+   *     the standard `before:watch` hook pipeline (`OP_REGISTRY.watch`,
+   *     policyKey `'query'`) BEFORE the change-stream pipeline is built —
+   *     `multiTenantPlugin` injects the tenant scope (and throws under
+   *     `required: true` exactly like other reads), `softDeletePlugin`
+   *     injects the deletion-state predicate. A tenant-scoped repo never
+   *     streams cross-tenant changes.
+   *   - `fullDocument: 'updateLookup'` — update events carry the post-
+   *     image document when it still exists at lookup time.
+   *   - `filter` (record or Filter IR) is compiled with the standard
+   *     filter compiler and applied against `fullDocument.*` paths, so
+   *     `watch({ status: 'pending' })` matches the post-image. Delete
+   *     events have no `fullDocument` and therefore don't match a
+   *     non-empty post-policy filter — use `bypassTenant` / an unscoped
+   *     repo without a filter to observe deletes.
+   *   - `options.signal` ends the iterator (closes the stream). A
+   *     pre-aborted signal rejects at the op boundary like every other op.
+   *   - `options.resumeAfter` forwards a previously captured Mongo
+   *     resume token for at-least-once consumption across restarts.
+   *
+   * Context keys for policy plugins (`organizationId`, `bypassTenant`,
+   * `includeDeleted`, ...) ride the options bag at runtime — same as every
+   * other op. The contract's `WatchOptions` type doesn't declare an index
+   * signature, so typed callers widen at the call site (or rely on an
+   * ALS `resolveContext` so no per-call tenant key is needed).
+   *
+   * @example
+   * ```ts
+   * const ac = new AbortController();
+   * for await (const change of repo.watch({ status: 'pending' }, { signal: ac.signal })) {
+   *   if (change.operation === 'create') enqueue(change.doc!);
+   * }
+   * ```
+   */
+  watch(filter?: FilterInput, options?: WatchOptions): AsyncIterable<ChangeEvent<TDoc>>;
+  /**
+   * Unified pagination - auto-detects offset vs keyset based on params
+   *
+   * Auto-detection logic:
+   * - If params has 'cursor' or 'after' → uses keyset pagination (stream)
+   * - If params has 'pagination' or 'page' → uses offset pagination (paginate)
+   * - Else → defaults to offset pagination with page=1
+   *
+   * @example
+   * // Offset pagination (page-based)
+   * await repo.getAll({ page: 1, limit: 50, filters: { status: 'active' } });
+   * await repo.getAll({ pagination: { page: 2, limit: 20 } });
+   *
+   * // Keyset pagination (cursor-based)
+   * await repo.getAll({ cursor: 'eyJ2Ij...', limit: 50 });
+   * await repo.getAll({ after: 'eyJ2Ij...', sort: { createdAt: -1 } });
+   *
+   * // Simple query (defaults to page 1)
+   * await repo.getAll({ filters: { status: 'active' } });
+   *
+   * // Skip cache for fresh data
+   * await repo.getAll({ filters: { status: 'active' } }, { skipCache: true });
+   */
+  getAll(params?: {
+    filters?: Record<string, unknown>;
+    sort?: SortSpec$1 | string;
+    cursor?: string;
+    after?: string;
+    page?: number;
+    pagination?: {
+      page?: number;
+      limit?: number;
+    };
+    limit?: number;
+    search?: string;
+    mode?: 'offset' | 'keyset';
+    hint?: string | Record<string, 1 | -1>;
+    maxTimeMS?: number;
+    countStrategy?: 'exact' | 'estimated' | 'none';
+    readPreference?: ReadPreferenceType; /** Advanced populate options (from QueryParser or Arc's BaseController) */
+    populateOptions?: PopulateOptions[]; /** Collation for locale-aware string comparison */
+    collation?: CollationOptions; /** Lookup configurations for $lookup joins (from QueryParser or manual) */
+    lookups?: LookupOptions[]; /** Skip pagination entirely — returns raw TDoc[] (same as findAll) */
+    noPagination?: boolean;
+  }, options?: CacheableOptions): Promise<OffsetPaginationResult<TDoc> | KeysetPaginationResult<TDoc> | TDoc[]>;
+  /**
+   * Atomic "look up by filter, insert `data` if missing, return the doc."
+   *
+   * Returns `{ doc, created }` so callers can tell whether *this* call
+   * inserted (race-win) or matched an existing row. Implements
+   * `StandardRepo.getOrCreate()` from `@classytic/repo-core/repository`
+   * — see that interface's JSDoc for the cross-kit contract.
+   *
+   * Routes through the hook system for policy enforcement (multi-tenant,
+   * soft-delete, audit). The hook context carries the resolved query +
+   * data; the action layer adds the `created` discriminator from the
+   * driver's `lastErrorObject.upserted`.
+   */
+  getOrCreate(query: Record<string, unknown>, createData: Record<string, unknown>, options?: SessionOptions): Promise<{
+    doc: TDoc;
+    created: boolean;
+  }>;
+  /**
+   * Count documents
+   * Routes through hook system for policy enforcement (multi-tenant, soft-delete)
+   */
+  count(query?: Record<string, unknown>, options?: ReadOptions): Promise<number>;
+  /**
+   * Check if document exists
+   * Routes through hook system for policy enforcement (multi-tenant, soft-delete)
+   */
+  exists(query: Record<string, unknown>, options?: ReadOptions): Promise<{
+    _id: unknown;
+  } | null>;
+  /**
+   * Update a document by id and return the post-update doc.
+   *
+   * Compiles to `Model.findOneAndUpdate(filter, { $set: data }, { new:
+   * true, runValidators: true })` under the hood and routes through the
+   * full plugin pipeline — `multiTenantPlugin` injects the tenant scope,
+   * `auditTrailPlugin` records the change, `cachePlugin` invalidates,
+   * `softDeletePlugin` etc. all compose. Returns `null` on miss (the
+   * `MinimalRepo` contract; pass `throwOnNotFound: true` for the legacy
+   * throw path).
+   *
+   * **Anti-pattern to avoid** — calling `Model.findOneAndUpdate()`
+   * directly on the raw mongoose model bypasses every plugin:
+   *
+   * ```ts
+   * // ❌ Bypasses multi-tenant scope, audit, cache invalidation:
+   * const doc = await CampaignModel.findOneAndUpdate(
+   *   { _id: id, organizationId: ctx.orgId },     // hand-rolled tenant filter
+   *   { $set: patch, $currentDate: { updatedAt: 1 } },
+   *   { new: true, runValidators: true }
+   * );
+   * return doc ? toEntity(doc) : null;
+   *
+   * // ✅ Plugin-routed; tenant + audit + cache auto-applied:
+   * const doc = await campaignRepo.update(id, patch, repoOptionsFromCtx(ctx));
+   * return doc ? toEntity(doc) : null;
+   * ```
+   *
+   * The raw-mongoose path is a recurring source of cross-tenant leaks
+   * (tenant filter forgotten on the next refactor), audit gaps (changes
+   * invisible to the compliance trail), and stale-cache bugs (cache
+   * invalidation skipped). Always route mutations through this method —
+   * the `repo.update()` keystroke count beats raw mongoose AND composes
+   * with the policy stack.
+   *
+   * **CAS / status-precondition writes — use `repo.claim()`, not `update()`.**
+   * A `findOneAndUpdate` whose filter includes an expected-state check
+   * (`{ _id, status: 'pending' }` → `{ $set: { status: 'shipped' } }`)
+   * is a compare-and-set, not a plain update. Reach for the `claim()`
+   * primitive — it expresses the transition as `{ from, to }`, returns
+   * `null` on race-loss (so callers can branch on retry), and routes
+   * through the same plugin pipeline:
+   *
+   * ```ts
+   * // ❌ Hand-rolled CAS — bypasses plugins, no typed race-loss signal:
+   * const doc = await CampaignModel.findOneAndUpdate(
+   *   { _id: id, organizationId: ctx.orgId, status: 'pending' },
+   *   { $set: { status: 'sent', sentAt: new Date() } },
+   *   { new: true }
+   * );
+   * if (!doc) throw new ConcurrentTransitionError(id);
+   *
+   * // ✅ Plugin-routed CAS with explicit transition + race-loss = null:
+   * const doc = await campaignRepo.claim(
+   *   id,
+   *   { from: 'pending', to: 'sent' },
+   *   { sentAt: new Date() },
+   *   repoOptionsFromCtx(ctx),
+   * );
+   * if (!doc) throw new ConcurrentTransitionError(id, 'pending', 'sent');
+   * ```
+   *
+   * Pair `claim()` with `defineStateMachine()` from
+   * `@classytic/primitives/state-machine` for the modelling layer
+   * (`assertTransition` catches illegal transitions sync, `claim` enforces
+   * the race-safe write) — see mongokit's CLAUDE.md "State-machine +
+   * claim() pairing" recipe. For pure dedup-on-id without a state
+   * transition (idempotency keys, webhook receivers), use `getOrCreate()`
+   * — `claim()` with `from === to === id` works too but is heavier.
+   *
+   * Domain-layer mapping (`doc → entity`) belongs on top of this call,
+   * not inside mongokit. The canonical pattern is a 3-line host helper:
+   *
+   * ```ts
+   * async function updateAndMap<TDoc, TEntity>(
+   *   repo: Repository<TDoc>,
+   *   id: string,
+   *   patch: Partial<TDoc>,
+   *   ctx: RequestContext,
+   *   mapper: (doc: TDoc) => TEntity,
+   * ): Promise<TEntity | null> {
+   *   const doc = await repo.update(id, patch, repoOptionsFromCtx(ctx));
+   *   return doc ? mapper(doc) : null;
+   * }
+   * ```
+   *
+   * Mongokit deliberately doesn't ship `updateAndMap` — host mapper
+   * signatures vary (`Result<T, E>`, throw-on-miss, audit-stamped
+   * mappers that take `ctx`, tx-scoped mappers, …) and absorbing a
+   * single shape would lock every consumer into it.
+   */
+  update(id: string | ObjectId, data: Record<string, unknown>, options?: UpdateOptions): Promise<TDoc | null>;
+  /**
+   * Atomic findOneAndUpdate (compare-and-set primitive).
+   *
+   * Single round-trip match-and-mutate for outbox relays, distributed locks,
+   * and workflow semaphores. Goes through the full hook pipeline so
+   * multi-tenant scope, soft-delete, audit, and cache plugins all apply.
+   *
+   * Returns the matched document (post-update by default) or `null` when no
+   * document matches and `upsert` is false.
+   *
+   * @example FIFO claim-lease for an outbox worker
+   * ```ts
+   * const claimed = await outboxRepo.findOneAndUpdate(
+   *   { status: 'pending', leaseExpiresAt: { $lt: new Date() } },
+   *   { $set: { status: 'processing', leaseExpiresAt: leaseUntil, leasedBy: workerId } },
+   *   { sort: { createdAt: 1 }, returnDocument: 'after' },
+   * );
+   * if (!claimed) return; // queue empty
+   * ```
+   *
+   * @example CAS upsert
+   * ```ts
+   * const lock = await locksRepo.findOneAndUpdate(
+   *   { _id: lockKey, ownerId: { $in: [null, workerId] } },
+   *   { $set: { ownerId: workerId, expiresAt: leaseUntil } },
+   *   { upsert: true },
+   * );
+   * ```
+   */
+  findOneAndUpdate<TResult = TDoc>(filter: Record<string, unknown>, update: UpdateInput, options?: FindOneAndUpdateOptions): Promise<TResult | null>;
+  /**
+   * Atomic compare-and-swap state transition. Implements
+   * `StandardRepo.claim()` from `@classytic/repo-core/repository` (0.4+).
+   *
+   * Builds a `findOneAndUpdate({ _id, [field]: from, ...where }, { $set:
+   * { [field]: to, ...patch } })` in a single round-trip — race-free
+   * across concurrent callers. Returns the post-update doc on success,
+   * `null` when:
+   *   - the row exists but its current state isn't `from` (someone
+   *     else won the transition), OR
+   *   - any predicate in `transition.where` fails (paused guard,
+   *     retry-time guard, heartbeat-staleness, sub-document predicate),
+   *     OR
+   *   - no row matches the id at all.
+   *
+   * The caller can't distinguish "lost race" from "guard predicate
+   * failed" — both mean "don't proceed." That's by design: the only
+   * action either way is to back off.
+   *
+   * **Source-state — `from: T | T[]`.** Pass a literal for a single-
+   * source transition (`from: 'pending'`) or an array for the
+   * "transition from any of these states" pattern (`from: ['pending',
+   * 'approved']`). Compiles to `[stateField]: { $in: [...] }`. Real-
+   * world frequency: commission's `voidRecord` / `markClawedBack` /
+   * `endAgreement` / `_transition`, media-kit's error path,
+   * streamline's `cancelAt` — every state machine with more than one
+   * non-terminal source state hits this. Without array support those
+   * sites fall back to raw `findOneAndUpdate` and lose plugin routing.
+   *
+   * **`from` is value-only — no Mongo expressions.** `from` accepts a
+   * literal or an array of literals (`$in`-shaped). It does NOT
+   * accept `{ $ne: ... }`, `{ $lt: ... }`, `{ $exists: ... }`, or
+   * arbitrary expression objects. The CAS contract is "match if the
+   * state field equals one of these specific values" — admitting
+   * arbitrary predicates would collapse the contract into a generic
+   * filter, defeating the point of a state-machine primitive.
+   *
+   * For non-equality / range / existence predicates on the state
+   * field, use `where`:
+   *
+   * ```ts
+   * // ❌ from: { $ne: 'ended' }    — not supported, would silently work-as-filter
+   * // ✅ Use `where` for $ne / $lt / $exists / arbitrary mongo predicates:
+   * await repo.claim(id, {
+   *   from: 'active',                          // exact-match state
+   *   to: 'closed',
+   *   where: { closedAt: { $exists: false } }, // additional predicates
+   * });
+   * ```
+   *
+   * **Dotted-path `field` is supported** — `field: 'scheduling.status'`
+   * for nested state fields works. Mongo's filter and `$set` both
+   * honor dotted paths, and the from===to optimization handles them
+   * correctly (literal comparison on the path string). Use for
+   * domain models that nest the state under a sub-document
+   * (`lpn.state`, `package.condition.state`, `scheduling.status`).
+   *
+   * **`from === to` is allowed — idempotent re-claim.** Yard's
+   * `reviseDeparture` writes `departed → departed` to update the
+   * row's payload while asserting the row hasn't moved on. The CAS
+   * still returns `null` on race-loss (row left the source state),
+   * so the safety property holds. Use the same semantic as a "touch
+   * with state assertion" primitive.
+   *
+   * When `from === to` (and `from` is a literal, not an array), the
+   * implementation **skips the redundant `$set: { [stateField]: to }`
+   * write** — the filter has already pinned the state field to that
+   * exact value, so writing it again is a no-op disk operation.
+   * Workloads doing high-replay dedup (yard's `gate-event.append`,
+   * outbox replay storms, idempotent first-write CAS) save one disk
+   * write + one journal flush + one replication-log entry per replay.
+   * Three observable behaviours follow:
+   *
+   *   - With a non-empty patch: only the patch fields land in `$set`;
+   *     the redundant state-field key is dropped.
+   *   - With an empty patch and `upsert: false`: the call lowers to
+   *     a plain `findOne` round-trip — pure assertion, zero writes.
+   *     Plugin pipeline (before/after `claim` hooks) still fires
+   *     correctly — only the internal driver shape changes.
+   *   - With an empty patch and `upsert: true`: the update becomes
+   *     `{ $setOnInsert: { [stateField]: to } }` — no-op on match,
+   *     populates the inserted row's state field on miss. This is
+   *     the "pure dedup" insert-or-confirm path.
+   *
+   * For pure-dedup recipes (no real state column, just an external
+   * id used as both filter and `from`/`to`), see CLAUDE.md — yard's
+   * `gate-event.append` is the canonical worked example.
+   *
+   * **`upsert: true` — insert-or-claim.** Set `options.upsert: true`
+   * for the upsert-claim pattern: insert when the row doesn't exist,
+   * else CAS-transition the existing row. Yard's `gate-event.append`
+   * uses this for idempotent event landing. With `upsert` on, claim
+   * NEVER returns null on miss — it inserts. Pair with
+   * `$setOnInsert` in the operator patch for insert-only fields.
+   * The default (`upsert: false`) keeps the canonical "match
+   * exactly, else null" semantic.
+   *
+   * **Patch shape** — accepts BOTH flat (`{ field: value }`) and Mongo
+   * operator (`{ $set, $inc, $unset, $setOnInsert, ... }`) forms.
+   * Operator form is load-bearing for versioned docs (`$inc: {
+   * version: 1 }`) and upsert-claim (`$setOnInsert: { createdBy }`);
+   * flat form is the textbook ergonomic case. Mixing flat keys with
+   * `$`-keys throws — Mongo would silently drop the flat keys,
+   * which would mask data-loss bugs.
+   *
+   * Multi-tenant scope, soft-delete filter, cache invalidation, and
+   * audit hooks all flow through automatically — `claim` is registered
+   * in `OP_REGISTRY` (policyKey: 'query', mutates: true), so plugins
+   * that iterate the registry pick it up without changes.
+   *
+   * **Caller responsibility for tenant context.** When
+   * `multiTenantPlugin` is mounted, plugin-injected scoping reads the
+   * tenant key from the **options bag** — `claim(id, transition, patch,
+   * { organizationId: '...' })`. Without it, the plugin throws
+   * `'Missing organizationId'` at runtime. Use
+   * `repoOptionsFromCtx(ctx)` (or your own context helper) to forward
+   * request-scoped tenant fields; do not assume the plugin reads them
+   * from a global.
+   *
+   * @example Textbook transition (flat patch)
+   * ```ts
+   * const claimed = await runRepo.claim(runId, { from: 'waiting', to: 'running' }, {
+   *   lastHeartbeat: new Date(),
+   *   workerId: 'worker-12',
+   * });
+   * if (!claimed) return; // someone else got it (or no match)
+   * ```
+   *
+   * @example Versioned doc — operator patch with `$inc`
+   * ```ts
+   * const claimed = await orderRepo.claim(
+   *   orderId,
+   *   { from: 'pending', to: 'shipped' },
+   *   {
+   *     $set: { shippedAt: new Date() },
+   *     $inc: { version: 1 },
+   *   },
+   * );
+   * ```
+   *
+   * @example Compound-filter claim (paused guard + retry timer)
+   * ```ts
+   * const claimed = await runRepo.claim(
+   *   runId,
+   *   {
+   *     from: 'waiting',
+   *     to: 'running',
+   *     where: {
+   *       paused: { $ne: true },
+   *       'scheduling.retryAfter': { $lte: new Date() },
+   *     },
+   *   },
+   *   { lastHeartbeat: new Date() },
+   *   { organizationId: ctx.orgId }, // tenant fwd — see note above
+   * );
+   * ```
+   *
+   * Pairs with `defineStateMachine()` from
+   * `@classytic/primitives/state-machine`:
+   *   - State machine validates "is from→to legal in the model?"
+   *   - `claim()` performs the atomic "did we win?"
+   */
+  claim(id: string | ObjectId, transition: {
+    field?: string;
+    from: unknown | readonly unknown[];
+    to: unknown;
+    where?: Record<string, unknown>;
+  }, patch?: Record<string, unknown>, options?: SessionOptions & {
+    idField?: string;
+    upsert?: boolean;
+  }): Promise<TDoc | null>;
+  /**
+   * Optimistic-concurrency CAS via a version stamp.
+   *
+   * Sibling to `claim()` — distinct mental model:
+   *   - `claim()` is a state machine: "move from status A to status B, atomically"
+   *   - `claimVersion()` is optimistic locking: "I expect version N; if it
+   *     still is, apply this update and increment the version"
+   *
+   * Builds `findOneAndUpdate({ _id, [versionField]: from, ...where },
+   * { ...update, $inc: { [versionField]: by ?? 1 } })` in one
+   * round-trip. Returns the post-update doc on success, `null` when:
+   *   - the row doesn't exist, OR
+   *   - the row's version isn't `from` (someone else committed first —
+   *     standard race-loss signal), OR
+   *   - any predicate in `transition.where` fails (state guard, tenant
+   *     guard expressed inline, etc.)
+   *
+   * **`from: undefined` is tolerated.** Lean reads return `version:
+   * number | undefined` because the field defaults are absent on
+   * fresh-from-mongo POJOs. Passing `from: undefined` matches docs
+   * whose version field is *missing entirely* — exactly what you want
+   * on a first-write CAS. Callers no longer need `?? 0` at every site.
+   *
+   * The caller's `update` is freeform — pass either a Mongo operator
+   * shape (`{ $set: { status: 'submitted', updatedAt: now } }`) or a
+   * field-shape object (auto-wrapped in `$set`). The version `$inc` is
+   * MERGED into the update, so callers don't have to remember to bump
+   * the counter.
+   *
+   * **Compound CAS via `where`.** State machines that key on both
+   * version AND status (yard's `transition()`, every package whose
+   * "ready to commit" gate is more than a version stamp) need to
+   * AND-merge additional predicates. Pass them via
+   * `transition.where` — same shape and semantics as `claim`'s
+   * `where` field. Without this, claimVersion was forced back to raw
+   * `findOneAndUpdate` for every state-AND-version site.
+   *
+   * Multi-tenant scope, soft-delete filter, cache invalidation, and
+   * audit hooks all fire — `claimVersion` is in `OP_REGISTRY`
+   * (policyKey: 'query', mutates: true) so plugins iterate the registry
+   * and pick it up automatically.
+   *
+   * **Caller responsibility for tenant context.** When
+   * `multiTenantPlugin` is mounted, the plugin reads the tenant key
+   * from the **options bag** (`{ organizationId: '...' }`). Without it,
+   * the plugin throws `'Missing organizationId'` at runtime. Use
+   * `repoOptionsFromCtx(ctx)` to forward — same as `claim()` and every
+   * other repo op.
+   *
+   * @example Order submission with version check
+   * ```ts
+   * const submitted = await orderRepo.claimVersion(
+   *   orderId,
+   *   { from: order.version },
+   *   { $set: { status: 'submitted', submittedAt: new Date() } },
+   * );
+   * if (!submitted) throw new ConcurrentEditError();
+   * ```
+   *
+   * @example Compound CAS — version + status
+   * ```ts
+   * const transitioned = await yardRepo.claimVersion(
+   *   loadId,
+   *   {
+   *     from: load.version, // number | undefined OK
+   *     where: { status: 'queued' },
+   *   },
+   *   { $set: { status: 'in-progress', startedAt: new Date() } },
+   * );
+   * if (!transitioned) throw new ConcurrentEditError();
+   * ```
+   *
+   * @example Custom version field name + step
+   * ```ts
+   * await runRepo.claimVersion(
+   *   runId,
+   *   { field: 'rev', from: 12, by: 1 },
+   *   { lastHeartbeat: new Date() },  // field-shape auto-wraps in $set
+   * );
+   * ```
+   */
+  claimVersion(id: string | ObjectId, transition: {
+    field?: string;
+    from: number | undefined;
+    by?: number;
+    where?: Record<string, unknown>;
+  }, update: Record<string, unknown>, options?: SessionOptions & {
+    idField?: string;
+  }): Promise<TDoc | null>;
+  /**
+   * Delete a document by ID.
+   *
+   * By default the behavior is decided by the plugin stack:
+   *   - With `softDeletePlugin` wired → soft delete (sets `deletedAt`)
+   *   - Without the plugin → physical delete
+   *
+   * Pass `mode: 'hard'` to force physical deletion regardless of plugins.
+   * All policy hooks (multi-tenant scope, audit trails, cache invalidation,
+   * cascade) still fire — only the soft-delete interception is skipped. This
+   * is the GDPR / admin-cleanup path.
+   *
+   * @example
+   * ```ts
+   * // Respects softDeletePlugin — soft if wired
+   * await userRepo.delete(userId);
+   *
+   * // GDPR erasure — physical delete, audit hooks still fire
+   * await userRepo.delete(userId, { mode: 'hard', organizationId: 'org_123' });
+   * ```
+   */
+  delete(id: string | ObjectId, options?: SessionOptions & {
+    idField?: string;
+    mode?: 'hard' | 'soft'; /** Legacy opt-in: throw a 404 error on miss instead of returning `null`. */
+    throwOnNotFound?: boolean;
+  }): Promise<DeleteResult | null>;
+  /**
+   * Update every document matching the filter.
+   *
+   * Promoted from `batchOperationsPlugin` to a class primitive in 3.11.0 so
+   * the surface matches sqlitekit's always-available `updateMany`. Consumers
+   * who forget to wire `batchOperationsPlugin` no longer get a runtime
+   * `TypeError: repo.updateMany is not a function` — the method is always
+   * here.
+   *
+   * Accepts three `update` forms via `UpdateInput`:
+   *   - Portable `UpdateSpec` from `@classytic/repo-core/update` (compiled to
+   *     `$set`/`$unset`/`$inc`/`$setOnInsert` before hooks run).
+   *   - Raw Mongo operator record (`{ $set, $inc, ... }`) — passed through.
+   *   - Mongo aggregation pipeline (`[...]`) — requires `updatePipeline: true`
+   *     to guard against accidental pipeline updates.
+   *
+   * Refuses empty filters (defense-in-depth against mass-update accidents)
+   * both before and after policy hooks inject tenant scope.
+   */
+  updateMany(filter: Record<string, unknown>, update: UpdateInput, options?: SessionOptions & {
+    updatePipeline?: boolean;
+    [key: string]: unknown;
+  }): Promise<UpdateManyResult>;
+  /**
+   * Delete every document matching the filter.
+   *
+   * Promoted from `batchOperationsPlugin` to a class primitive in 3.11.0 for
+   * the same reason as `updateMany` — sqlitekit parity and no silent "method
+   * is undefined" footgun when the batch plugin isn't wired.
+   *
+   * Behavior mirrors `delete()`: defaults to soft delete when
+   * `softDeletePlugin` is wired, physical delete otherwise. Pass
+   * `{ mode: 'hard' }` to bypass soft-delete — multi-tenant scoping, audit,
+   * and cache hooks still fire.
+   *
+   * Rejects empty filters up front AND after policy hooks, so a policy-plugin
+   * bug that zeroes out the query can't be exploited to wipe a collection.
+   */
+  deleteMany(filter: Record<string, unknown>, options?: SessionOptions & {
+    mode?: 'hard' | 'soft';
+    [key: string]: unknown;
+  }): Promise<DeleteManyResult>;
+  /**
+   * Compliance-grade cleanup primitive — see `StandardRepo.purgeByField`
+   * for the cross-kit contract. Mongokit composes the kit-agnostic
+   * `runChunkedPurge` orchestrator (loop, signal, progress, result
+   * envelope) with `createMongoPurgePort` (driver-specific id selection
+   * + strategy writes). See [actions/purge.ts](./actions/purge.ts) for
+   * the port implementation.
+   */
+  purgeByField(field: string, value: unknown, strategy: TenantPurgeStrategy, options?: TenantPurgeOptions): Promise<TenantPurgeResult>;
+  /**
+   * Kit-native aggregation pipeline — takes a MongoDB stage array and
+   * returns the raw pipeline output. Use this for `$lookup`, `$unwind`,
+   * `$facet`, `$graphLookup`, and any other mongo-specific power
+   * features that don't translate to SQL.
+   *
+   * For backend-portable aggregations (filter + group + measures +
+   * sort + limit) use `aggregate(req: AggRequest)` instead — it
+   * compiles the repo-core IR to the equivalent pipeline internally
+   * and produces the same row shape sqlitekit emits.
+   *
+   * Routes through the hook system for policy enforcement
+   * (multi-tenant, soft-delete).
+   *
+   * @param pipeline - MongoDB aggregation stage array
+   * @param options  - Aggregation options including governance controls
+   */
+  aggregatePipeline<TResult = unknown>(pipeline: PipelineStage[], options?: AggregateOptions): Promise<TResult[]>;
+  /**
+   * Paginated kit-native aggregation pipeline. Same mongo-specific
+   * scope as `aggregatePipeline` — reach for this when you need
+   * `$lookup` / `$unwind` / `$facet` alongside pagination.
+   *
+   * Prefer `aggregatePaginate(req: AggPaginationRequest)` for
+   * cross-backend dashboard code; that method compiles the portable
+   * IR to an equivalent pipeline.
+   *
+   * Policy hooks (multi-tenant, soft-delete) inject context.filters
+   * which are prepended as a `$match` stage.
+   */
+  aggregatePipelinePaginate(options?: AggregatePaginationOptions): Promise<AggregatePaginationResult<TDoc>>;
+  /**
+   * Portable aggregation. Compiles the repo-core `AggRequest` IR to
+   * `[{$match}, {$group}, {$addFields}, {$project}, {$match}, {$sort},
+   * {$skip}, {$limit}]` against this repo's collection. Output rows
+   * carry one key per `groupBy` column plus one key per measure alias
+   * — identical shape to sqlitekit's `aggregate(req)`, so dashboards
+   * work unchanged across backends.
+   *
+   * Without `groupBy`: returns a single-row result with just the
+   * measures (scalar aggregation). Pass
+   * `{ measures: { total: { op: 'sum', field: 'amount' } } }` for a
+   * simple summary.
+   *
+   * For mongo-specific power features (`$lookup`, `$unwind`, `$facet`,
+   * `$graphLookup`, window operators) reach for `aggregatePipeline`
+   * — that's the kit-native escape hatch.
+   *
+   * Routes through the hook system for policy enforcement
+   * (multi-tenant, soft-delete) — plugins inject their scope into
+   * `context.filter`, which is merged into the pre-aggregate `$match`
+   * before compilation.
+   */
+  aggregate<TRow extends Record<string, unknown> = Record<string, unknown>>(req: AggRequest, options?: QueryOptions): Promise<AggResult<TRow>>;
+  /**
+   * Invalidate every aggregate-cache entry tagged with ANY of the
+   * given tags. Delegates to the unified cache plugin's handle
+   * (`repo.cache.invalidateByTags`) — wired by `cachePlugin({ adapter })`.
+   *
+   * Pass no tags to wipe the entire cache namespace (requires the
+   * adapter to implement `clear`).
+   *
+   * Returns the count of distinct entries cleared (`-1` when the call
+   * routed through `adapter.clear()` and the adapter doesn't report a
+   * count). No-op (returns `0`) when no cache plugin is wired.
+   */
+  invalidateAggregateCache(tags?: readonly string[]): Promise<number>;
+  /**
+   * Paginated portable aggregation. Two pagination modes, picked by
+   * the request shape:
+   *
+   * - **Offset (default)** — `page` + `limit`. Returns the standard
+   *   `{ method: 'offset', data, total, pages, hasNext, hasPrev, ... }`
+   *   envelope. `countStrategy: 'none'` skips the second round-trip
+   *   that computes `total`; the envelope reports `total: 0`,
+   *   `pages: 0`, and derives `hasNext` from a `LIMIT N+1` peek on
+   *   the data pipeline.
+   * - **Keyset** — `pagination: 'keyset'` (or `after` set). Returns
+   *   `{ method: 'keyset', data, hasMore, next, limit }`. `sort` is
+   *   required — the cursor encodes the sort-key tuple of the last
+   *   row. Each subsequent page passes the previous `next` back as
+   *   `after`. Scales to arbitrary group counts because the planner
+   *   uses `(sort_keys) > (cursor)` instead of `OFFSET N`.
+   */
+  aggregatePaginate<TRow extends Record<string, unknown> = Record<string, unknown>>(req: AggPaginationRequest, options?: QueryOptions): Promise<OffsetPaginationResultCore<TRow> | KeysetAggPaginationResult<TRow>>;
+  /**
+   * Internal: the actual aggregate-paginate execution body. Extracted
+   * so `aggregatePaginate` can wrap it in the cache layer without
+   * duplicating the keyset / offset branch logic.
+   *
+   * Receives `finalReq` (already policy-scoped) so the cache key
+   * built by the outer wrapper matches the request the executor
+   * sees — no cross-tenant cache poisoning.
+   */
+  private _executeAggregatePaginate;
+  /**
+   * Merge policy-hook-injected filters (multi-tenant scope,
+   * soft-delete) into the pre-aggregate `filter` slot of the request.
+   * Plugins speak mongo-query shape (`context.query` / `context.filters`);
+   * the caller's `req.filter` may be either Filter IR or a mongo query.
+   *
+   * Each part is compiled through `compileFilterToMongo` BEFORE the
+   * `$and` merge — otherwise an IR node like `eq('status', 'paid')`
+   * (`{ op, field, value }`) gets nested inside `$and` as a literal,
+   * `compileFilterToMongo` of the merged value finds no top-level `op`
+   * (so `isFilter` is false), and Mongo receives the IR object as a
+   * raw query clause that matches no real document. Symptom: aggregates
+   * silently return 0 rows whenever a callerpasses IR + a policy
+   * plugin is installed.
+   */
+  private _injectPolicyScopeIntoAgg;
+  /**
+   * Get distinct values
+   * Routes through hook system for policy enforcement (multi-tenant, soft-delete)
+   */
+  distinct<T = unknown>(field: string, query?: Record<string, unknown>, options?: ReadOptions): Promise<T[]>;
+  /**
+   * Query with custom field lookups ($lookup)
+   * Best for: Joins on slugs, SKUs, codes, or other indexed custom fields
+   *
+   * @example
+   * ```typescript
+   * // Join employees with departments using slug instead of ObjectId
+   * const employees = await employeeRepo.lookupPopulate({
+   *   filters: { status: 'active' },
+   *   lookups: [
+   *     {
+   *       from: 'departments',
+   *       localField: 'departmentSlug',
+   *       foreignField: 'slug',
+   *       as: 'department',
+   *       single: true
+   *     }
+   *   ],
+   *   sort: '-createdAt',
+   *   page: 1,
+   *   limit: 50
+   * });
+   * ```
+   */
+  lookupPopulate<TExtra extends Record<string, unknown> = Record<string, unknown>>(options: LookupPopulateOptions<TDoc>): Promise<LookupPopulateResult<TDoc, TExtra>>;
+  /**
+   * Create an aggregation builder for this model
+   * Useful for building complex custom aggregations
+   *
+   * @example
+   * ```typescript
+   * const pipeline = repo.buildAggregation()
+   *   .match({ status: 'active' })
+   *   .lookup('departments', 'deptSlug', 'slug', 'department', true)
+   *   .group({ _id: '$department', count: { $sum: 1 } })
+   *   .sort({ count: -1 })
+   *   .build();
+   *
+   * const results = await repo.Model.aggregate(pipeline);
+   * ```
+   */
+  buildAggregation(): AggregationBuilder;
+  /**
+   * Create a lookup builder
+   * Useful for building $lookup stages independently
+   *
+   * @example
+   * ```typescript
+   * const lookupStages = repo.buildLookup('departments')
+   *   .localField('deptSlug')
+   *   .foreignField('slug')
+   *   .as('department')
+   *   .single()
+   *   .build();
+   *
+   * const pipeline = [
+   *   { $match: { status: 'active' } },
+   *   ...lookupStages
+   * ];
+   * ```
+   */
+  buildLookup(from?: string): LookupBuilder;
+  /**
+   * Execute callback within a MongoDB transaction with automatic retry on
+   * transient failures.
+   *
+   * **BREAKING (3.10):** the callback now receives a **tx-bound repository**,
+   * not a raw `ClientSession`. This matches repo-core's `StandardRepo.withTransaction`
+   * contract that every kit (sqlitekit, pgkit, prismakit) already implements
+   * — so cross-kit plugins and apps are portable. Session threading happens
+   * transparently: every CRUD call on `txRepo` auto-injects the session into
+   * its options bag, including plugin-added methods (`upsert`, `increment`,
+   * `updateMany`, `restore`, ...). Nested `txRepo.withTransaction(...)` throws.
+   *
+   * For raw-session cross-repo workflows — multiple repositories coordinating
+   * writes — use the standalone `withTransaction(connection, fn)` export
+   * from `@classytic/mongokit`. That helper remains session-based by design.
+   *
+   * @param callback - Receives a tx-bound `Repository<TDoc>` — call its
+   *                   methods directly, no need to pass `{ session }` manually
+   * @param options.allowFallback - Run without transaction on standalone MongoDB (default: false)
+   * @param options.onFallback - Called when falling back to non-transactional execution
+   * @param options.transactionOptions - MongoDB driver transaction options (readConcern, writeConcern, etc.)
+   *
+   * @example
+   * ```typescript
+   * const order = await repo.withTransaction(async (txRepo) => {
+   *   const created = await txRepo.create({ total: 100 });
+   *   await txRepo.update(created._id, { confirmed: true });
+   *   return created;
+   * });
+   *
+   * // With fallback for standalone/dev environments
+   * await repo.withTransaction(
+   *   async (txRepo) => {
+   *     await txRepo.create(doc);
+   *   },
+   *   {
+   *     allowFallback: true,
+   *     onFallback: (err) => logger.warn('Running without transaction', err),
+   *   },
+   * );
+   *
+   * // Cross-repo with explicit session:
+   * import { withTransaction } from '@classytic/mongokit';
+   * await withTransaction(mongoose.connection, async (session) => {
+   *   const order = await orderRepo.create(data, { session });
+   *   await inventoryRepo.decrement(..., { session });
+   * });
+   * ```
+   */
+  withTransaction<T>(callback: (txRepo: this) => Promise<T>, options?: WithTransactionOptions): Promise<T>;
+  /**
+   * Execute custom query with event emission
+   */
+  _executeQuery<T>(buildQuery: (Model: Model<TDoc>) => Promise<T>): Promise<T>;
+  /**
+   * Build operation context and run before-hooks (sorted by priority).
+   *
+   * Narrows `RepositoryBase._buildContext`'s return type to mongokit's
+   * richer `RepositoryContext` (which carries `softDeleted`, `_cacheHit`,
+   * populate / readPreference / session, etc.). Runtime is inherited from
+   * the base class — this override is purely a type-narrowing shim.
+   *
+   * Hook execution order is deterministic:
+   * 1. POLICY (100) — tenant isolation, soft-delete filtering, validation
+   * 2. CACHE  (200) — cache lookup (after policy filters are injected)
+   * 3. OBSERVABILITY (300) — audit logging, metrics
+   * 4. DEFAULT (500) — user-registered hooks
+   */
+  _buildContext(operation: string, options: Record<string, unknown> | object): Promise<RepositoryContext>;
+  /**
+   * Walk the well-known filter-carrying keys (`query`, `filters`,
+   * `having`) and route any Filter IR through `compileFilterToMongo`.
+   * Plain Mongo queries pass through untouched — `isFilter` is the
+   * discriminator. Returns a shallow clone; never mutates input.
+   */
+  private _normalizeFilterSlots;
+  /**
+   * Resolve the effective sort for getAll. Handles $near conflict detection
+   * (warns + drops explicit sort when $near is in filters).
+   */
+  private _resolveSort;
+  /**
+   * Detect whether to use keyset (cursor) or offset (page) pagination.
+   */
+  private _detectPaginationMode;
+  /**
+   * Build the MongoDB query filter with search merged in. Handles text
+   * search ($text), regex search ($or of $regex), and the search-resolver
+   * plugin contract (search already cleared by a before:getAll hook).
+   */
+  private _buildSearchQuery;
+  /**
+   * Parse sort string or object
+   */
+  _parseSort(sort: SortSpec$1 | string | undefined): SortSpec$1;
+  /**
+   * Parse populate specification
+   */
+  _parsePopulate(populate: PopulateSpec | undefined): string[] | PopulateOptions[];
+  /**
+   * Classify a driver error as an authoritative duplicate-key conflict.
+   *
+   * Used by arc's outbox / idempotency adapters to distinguish
+   * "write already landed (idempotent no-op)" from "transient DB error
+   * (must retry)". Every backend signals duplicate keys differently —
+   * MongoDB `code: 11000`, Prisma `P2002`, Postgres `23505` — so this
+   * predicate lives on the kit that knows its driver. Cross-driver
+   * adapters then depend only on the boolean outcome, not the shape of
+   * the underlying error.
+   *
+   * Deliberately narrow: matches ONLY `code === 11000` and
+   * `codeName === 'DuplicateKey'`. Does NOT match
+   * `err.name === 'MongoServerError'`, which is also true for
+   * WriteConflict, NotWritablePrimary, ExceededTimeLimit, and every
+   * other server-side error — treating those as duplicate keys would
+   * silently swallow transactional retries.
+   *
+   * @example
+   * try {
+   *   await outboxRepo.create(event);
+   * } catch (err) {
+   *   if (outboxRepo.isDuplicateKeyError(err)) {
+   *     // Idempotent no-op — event was already written by a prior attempt.
+   *     return;
+   *   }
+   *   throw err; // transient DB error — upstream retries
+   * }
+   */
+  isDuplicateKeyError(err: unknown): boolean;
+  /**
+   * Handle errors with proper HTTP status codes.
+   *
+   * **Transactional retry signal preservation.** MongoDB driver errors
+   * carry `errorLabels` (e.g. `'TransientTransactionError'`,
+   * `'UnknownTransactionCommitResult'`) that `mongoose.Connection.
+   * withTransaction()` reads via `error.hasErrorLabel(label)` to decide
+   * whether to auto-retry the transaction. Wrapping such an error in a
+   * fresh `Error` via `createError(...)` strips both the labels and the
+   * `hasErrorLabel` method — the retry signal vanishes and concurrent
+   * writers see WriteConflicts surface to userland instead of being
+   * retried by the driver. To keep the standard MongoDB transaction-
+   * retry mechanism intact, we re-throw any error that carries
+   * `errorLabels` exactly as we received it. The caller still sees a
+   * thrown error — only the wrapping layer is skipped.
+   */
+  _handleError(error: Error): HttpError;
+}
+//#endregion
+//#region src/create-repository.d.ts
+/**
+ * Audit config — either a `Logger` (routes to `auditLogPlugin`, which
+ * writes structured log lines through your logger) or an
+ * `AuditTrailOptions` object (routes to `auditTrailPlugin`, which
+ * persists a queryable compliance ledger in its own collection).
+ *
+ * Discrimination: a value carrying any of the `Logger` function members
+ * (`info` / `warn` / `error` / `debug`) is treated as a logger; anything
+ * else is treated as `AuditTrailOptions` (all of whose members are
+ * data-shaped except `metadata` / `onError`, which don't overlap with
+ * the logger member names).
+ */
+type AuditConfig = Logger | AuditTrailOptions;
+/**
+ * Declarative repository config. Every key is optional; a feature's
+ * plugin is installed only when its key is present. The remaining
+ * `RepositoryOptions` keys (`idField`, `hooks`, `schema`, `updateSchema`,
+ * `events`, `requirePlugins`, ...) pass through to the `Repository`
+ * constructor unchanged.
+ */
+interface CreateRepositoryConfig extends RepositoryOptions {
+  /** Multi-tenant scoping — forwarded to `multiTenantPlugin`. */
+  tenant?: MultiTenantOptions;
+  /** Soft-delete — `true` for defaults, or `SoftDeleteOptions`. */
+  softDelete?: boolean | SoftDeleteOptions;
+  /** createdAt/updatedAt stamping — `timestampPlugin` takes no options. */
+  timestamps?: boolean;
+  /** Batch ops (`updateMany`/`deleteMany`/`bulkWrite`) via `batchOperationsPlugin`. */
+  batch?: boolean;
+  /** Read-through cache — forwarded to `cachePlugin`. */
+  cache?: RepositoryCachePluginOptions;
+  /** Audit — `Logger` → `auditLogPlugin`; `AuditTrailOptions` → `auditTrailPlugin`. */
+  audit?: AuditConfig;
+  /** Custom ID generation — forwarded to `customIdPlugin`. */
+  customId?: CustomIdOptions;
+  /** Extra plugins appended AFTER the canonical stack. */
+  plugins?: PluginType[];
+  /** Pagination engine config (defaultLimit, maxLimit, ...). */
+  pagination?: PaginationConfig;
+}
+/**
+ * Build a `Repository` from a declarative config. See module JSDoc for
+ * ordering guarantees and an example.
+ */
+declare function createRepository<TDoc>(model: Model<TDoc, any, any, any>, config?: CreateRepositoryConfig): Repository<TDoc>;
+//#endregion
+export { Repository as a, HOOK_PRIORITY as i, CreateRepositoryConfig as n, AggregationBuilder as o, createRepository as r, AuditConfig as t };