@classytic/mongokit 3.18.0 → 3.19.0

package/dist/index.d.mts

@@ -1,16 +1,14 @@
-import { $ as RepositoryEvent, A as KeysetPaginationOptions, B as ObjectId, C as FieldPreset, Ct as IControllerResponse, D as InferDocument, Dt as LookupOptions, E as HookMode, Et as LookupBuilder, F as MiddlewareContext, G as Plugin, H as OperationOptions, I as MinMaxResult, J as PopulateSpec, K as PluginFunction, L as MinimalRepoView, M as LookupPopulateOptions, N as LookupPopulateResult, O as InferRawDoc, P as Middleware, Q as RepositoryContext, R as MongoOperatorUpdate, S as EventPhase, St as IController, T as GroupResult, Tt as IResponseFormatter, U as PaginationConfig, V as OffsetPaginationOptions, W as PartialBy, X as ReadOptions, Y as PrioritizedHook, Z as ReadPreferenceType, _ as DeleteManyResult, _t as ValidationChainOptions, a as AnyModel, at as SessionOptions, b as EventHandlers, bt as WithPlugins, c as CacheableOptions, ct as SoftDeleteRepository, d as CollationOptions, dt as Strict, et as RepositoryInstance, f as CreateInput, ft as UpdateManyResult, g as DeepPartial, gt as UserContext, h as DecodedCursor, ht as UpdateWithValidationResult, i as AnyDocument, it as SelectSpec, j as Logger, k as KeysOfType, l as CascadeOptions, lt as SortDirection, m as CursorPayload, mt as UpdatePatch, n as AggregatePaginationOptions, nt as RepositoryOptions, o as BasePaginationOptions, ot as SoftDeleteFilterMode, p as CreateOptions, pt as UpdateOptions, q as PluginType, r as AllPluginMethods, rt as RequiredBy, s as CacheOperationOptions, st as SoftDeleteOptions, t as AggregateOptions, tt as RepositoryOperation, u as CascadeRelation, ut as SortSpec, v as DeleteResult, vt as ValidatorDefinition, w as FindOneAndUpdateOptions, wt as IRequestContext, x as EventPayload, xt as WithTransactionOptions, y as DocField, yt as ValueType, z as NonNullableFields } from "./types-CU3SEDbD.mjs";
-import { t as index_d_exports } from "./index-fi91ycQc.mjs";
-import { $ as AuditEntry, A as BulkWriteResult, B as IdGenerator, C as LeasePluginOptions, D as elasticSearchPlugin, E as ElasticSearchOptions, F as MultiTenantOptions, G as getNextSequence, H as SequentialIdOptions, I as adminBypass, J as CacheAdapter, K as prefixedId, L as multiTenantPlugin, M as auditLogPlugin, N as AggregateHelpersMethods, O as cascadePlugin, P as aggregateHelpersPlugin, Q as cachePlugin, R as CustomIdOptions, S as LeaseMethods, T as fieldFilterPlugin, U as customIdPlugin, V as PrefixedIdOptions, W as dateSequentialId, X as RepositoryCacheHandle, Y as CacheOptions, Z as RepositoryCachePluginOptions, _ as observabilityPlugin, a as uniqueField, at as AuditTrailQuery, c as TenantContext, d as SubdocumentMethods, et as AuditOperation, f as subdocumentPlugin, g as OperationMetric, h as ObservabilityOptions, i as requireField, it as AuditTrailOptions, j as batchOperationsPlugin, k as BatchOperationsMethods, l as TenantStore, m as softDeletePlugin, n as blockIf, nt as AuditQueryResult, o as validationChainPlugin, ot as auditTrailPlugin, p as SoftDeleteMethods, q as sequentialId, r as immutableField, rt as AuditTrailMethods, s as timestampPlugin, t as autoInject, tt as AuditQueryOptions, u as createTenantContext, v as MongoOperationsMethods, w as leasePlugin, x as methodRegistryPlugin, y as mongoOperationsPlugin, z as DateSequentialIdOptions } from "./validation-chain.plugin-BpMfy18N.mjs";
-import { PaginationEngine } from "./pagination/PaginationEngine.mjs";
-import { n as SchemaPathsLike, t as FieldType$1 } from "./coercion-TRMmR49h.mjs";
-import { n as SchemaIndexes } from "./indexes-CgOF7Wjd.mjs";
-import { d as filterResponseData, f as getFieldsForUser, g as parseDuplicateKeyError, h as isDuplicateKeyError, i as configureLogger, m as createError, n as buildCrudSchemasFromMongooseSchema, p as getMongooseProjection, r as createMemoryCache, s as idVariants, t as buildCrudSchemasFromModel, u as createFieldPreset } from "./mongooseToJsonSchema-BdQJU39w.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 { ClientSession, 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";
+import { $ as RepositoryEvent, A as KeysetPaginationOptions, B as ObjectId, C as FieldPreset, Ct as IControllerResponse, D as InferDocument, Dt as LookupOptions, E as HookMode, Et as LookupBuilder, F as MiddlewareContext, G as Plugin, H as OperationOptions, I as MinMaxResult, J as PopulateSpec, K as PluginFunction, L as MinimalRepoView, M as LookupPopulateOptions, N as LookupPopulateResult, O as InferRawDoc, P as Middleware, Q as RepositoryContext, R as MongoOperatorUpdate, S as EventPhase, St as IController, T as GroupResult, Tt as IResponseFormatter, U as PaginationConfig, V as OffsetPaginationOptions, W as PartialBy, X as ReadOptions, Y as PrioritizedHook, Z as ReadPreferenceType, _t as ValidationChainOptions, a as AnyModel, at as SessionOptions, b as EventHandlers, bt as WithPlugins, c as CacheableOptions, ct as SoftDeleteRepository, d as CollationOptions, dt as Strict, et as RepositoryInstance, f as CreateInput, ft as UpdateManyResult, g as DeepPartial, gt as UserContext, h as DecodedCursor, ht as UpdateWithValidationResult, i as AnyDocument, it as SelectSpec, j as Logger, k as KeysOfType, l as CascadeOptions, lt as SortDirection, m as CursorPayload, mt as UpdatePatch, n as AggregatePaginationOptions, nt as RepositoryOptions, o as BasePaginationOptions, ot as SoftDeleteFilterMode, p as CreateOptions, pt as UpdateOptions, q as PluginType, r as AllPluginMethods, rt as RequiredBy, s as CacheOperationOptions, st as SoftDeleteOptions, t as AggregateOptions, tt as RepositoryOperation, u as CascadeRelation, ut as SortSpec, v as DeleteResult, vt as ValidatorDefinition, w as FindOneAndUpdateOptions, wt as IRequestContext, x as EventPayload, xt as WithTransactionOptions, y as DocField, yt as ValueType, z as NonNullableFields } from "./types-BA8oXjFe.mjs";
+import { t as index_d_exports } from "./index-BgSBwlWu.mjs";
+import { C as AuditTrailMethods, E as auditTrailPlugin, S as AuditQueryResult, T as AuditTrailQuery, _ as RepositoryCachePluginOptions, a as DateSequentialIdOptions, b as AuditOperation, c as SequentialIdOptions, d as getNextSequence, f as prefixedId, g as RepositoryCacheHandle, h as CacheOptions, i as CustomIdOptions, l as customIdPlugin, m as CacheAdapter, n as adminBypass, o as IdGenerator, p as sequentialId, r as multiTenantPlugin, s as PrefixedIdOptions, t as MultiTenantOptions, u as dateSequentialId, v as cachePlugin, w as AuditTrailOptions, x as AuditQueryOptions, y as AuditEntry } from "./multi-tenant.plugin-D6lw3BsI.mjs";
+import { t as PaginationEngine } from "./PaginationEngine-4SjzfBQE.mjs";
+import { a as Repository, i as HOOK_PRIORITY, n as CreateRepositoryConfig, o as AggregationBuilder, r as createRepository, t as AuditConfig } from "./create-repository-K0yft2ht.mjs";
+import { A as BulkWriteResult, C as LeasePluginOptions, D as elasticSearchPlugin, E as ElasticSearchOptions, M as auditLogPlugin, N as AggregateHelpersMethods, O as cascadePlugin, P as aggregateHelpersPlugin, S as LeaseMethods, T as fieldFilterPlugin, _ as observabilityPlugin, a as uniqueField, c as TenantContext, d as SubdocumentMethods, f as subdocumentPlugin, g as OperationMetric, h as ObservabilityOptions, i as requireField, j as batchOperationsPlugin, k as BatchOperationsMethods, l as TenantStore, m as softDeletePlugin, n as blockIf, o as validationChainPlugin, p as SoftDeleteMethods, r as immutableField, s as timestampPlugin, t as autoInject, u as createTenantContext, v as MongoOperationsMethods, w as leasePlugin, x as methodRegistryPlugin, y as mongoOperationsPlugin } from "./validation-chain.plugin-CYOPfFGF.mjs";
+import { n as SchemaPathsLike, t as FieldType$1 } from "./coercion-BxxHyLjP.mjs";
+import { n as SchemaIndexes } from "./indexes-3eHBWNZ2.mjs";
+import { d as filterResponseData, f as getFieldsForUser, g as parseDuplicateKeyError, h as isDuplicateKeyError, i as configureLogger, m as createError, n as buildCrudSchemasFromMongooseSchema, p as getMongooseProjection, r as createMemoryCache, s as idVariants, t as buildCrudSchemasFromModel, u as createFieldPreset } from "./mongooseToJsonSchema-Bz47aMfH.mjs";
+import { RepoCapabilities } from "@classytic/repo-core/repository";
+import { ClientSession, PipelineStage } from "mongoose";
 
 //#region src/actions/cascade-references.d.ts
 type PurgeMode = 'hard' | 'soft' | 'anonymize';
@@ -93,1658 +91,6 @@ declare function cascadePurgeReferences(options: CascadePurgeReferencesOptions):
 //#region src/capabilities.d.ts
 declare const MONGOKIT_CAPABILITIES: RepoCapabilities;
 //#endregion
-//#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$2 = 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$2 | 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$2;
-    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$2;
-    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;
-  }): 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;
-  }): 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 | 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 | 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 | 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 | string | undefined): SortSpec;
-  /**
-   * 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
 //#region src/filter/compile.d.ts
 /**
  * Filter IR → MongoDB query compiler.