@classytic/mongokit 3.24.0 → 3.25.0

package/dist/{mongooseToJsonSchema-CVnrKFDq.mjs → mongooseToJsonSchema-CByt1VhQ.mjs}

@@ -1,4 +1,4 @@
-import { r as isObjectIdInstance } from "./id-resolution-P2OzcyRl.mjs";
+import { r as isObjectIdInstance } from "./id-resolution-BqDrk0S2.mjs";
 import mongoose from "mongoose";
 import { applyFieldRules, collectFieldsToOmit } from "@classytic/repo-core/schema";
 //#region src/utils/mongooseToJsonSchema.ts

package/dist/{multi-tenant.plugin-BjXXuc_g.d.mts → multi-tenant.plugin-DVyVGREb.d.mts}

@@ -1,16 +1,62 @@
-import { B as ObjectId, G as Plugin, Q as RepositoryContext } from "./types-BtMuhoX5.mjs";
-import mongoose from "mongoose";
+import { i as ObjectId } from "./core-62oo3N1C.mjs";
+import { l as Plugin, p as RepositoryContext } from "./repository-DCHRWRXw.mjs";
+import mongoose, { Connection } from "mongoose";
 import { CacheAdapter as CacheAdapter$1, CacheOptions, RepositoryCacheHandle, RepositoryCachePluginOptions, cachePlugin } from "@classytic/repo-core/cache";
 import { TenantConfig } from "@classytic/repo-core/tenant";
 //#region src/plugins/audit-trail.plugin.d.ts
+/**
+ * Audit write delivery mode.
+ *
+ * - `'best-effort'`: async fire-and-forget; never blocks or fails the
+ *   operation. Observability-grade.
+ * - `'transactional'`: awaited insert sharing the operation's session; a
+ *   failed audit write fails the operation.
+ *
+ * PRECISION: `'transactional'` is **atomic only when the operation actually
+ * runs inside a MongoDB transaction** (`withTransaction` / an explicit
+ * `session`). Without one, the mode still guarantees "the call does not
+ * return success unless the audit entry landed" — but the business write has
+ * already committed by the time the audit insert runs, so an audit failure
+ * rejects the call while leaving the business write in place. For
+ * compliance-grade "both or neither", wrap the operation in a transaction.
+ * Call {@link ensureAuditTrailReady} at boot so the collection and indexes
+ * are not created lazily inside the first transaction.
+ */
+type AuditTrailMode = 'best-effort' | 'transactional';
 interface AuditTrailOptions {
+  /**
+   * Delivery guarantee for audit writes (default: 'best-effort').
+   * See {@link AuditTrailMode}. `'transactional'` requires the repository's
+   * default `hooks: 'async'` mode — plugin registration throws on a
+   * `hooks: 'sync'` repository because awaited delivery cannot be honored.
+   */
+  mode?: AuditTrailMode;
+  /**
+   * Mongoose connection to register the audit model on. Defaults to the
+   * audited model's OWN connection (`repo.Model.db`), so
+   * `mongoose.createConnection()` apps get audit entries in the same database
+   * as their data automatically. Pass this explicitly only to centralize
+   * audit storage on a different connection than the model lives on. Mirrors
+   * the `connection` option on the lock and usage stores.
+   *
+   * Note: `AuditTrailQuery` / `ensureAuditTrailReady` have no repository to
+   * infer from and default to the global `mongoose.connection` — pass the
+   * same `connection` there for multi-DB apps.
+   */
+  connection?: Connection;
   /** Operations to track (default: ['create', 'update', 'delete']) */
   operations?: AuditOperation[];
   /** Store field-level before/after diff on updates (default: true) */
   trackChanges?: boolean;
   /** Store full document snapshot on create (default: false — can be heavy) */
   trackDocument?: boolean;
-  /** Auto-purge after N days via MongoDB TTL index (default: undefined — keep forever) */
+  /**
+   * Auto-purge after N days via MongoDB TTL index (default: undefined — keep
+   * forever). Retention is collection-level configuration: every plugin (and
+   * `AuditTrailQuery`) touching the same collection on the same connection
+   * must agree on `ttlDays`. A conflicting value throws at registration time
+   * instead of silently keeping whichever caller ran first.
+   */
   ttlDays?: number;
   /** MongoDB collection name (default: 'audit_trails') */
   collectionName?: string;
@@ -25,19 +71,19 @@ interface AuditTrailOptions {
    */
   excludeFields?: string[];
   /**
-   * Custom callback fired when an audit write fails. Receives the error
-   * and the entry that failed to land. Default: `console.warn` only.
+   * Callback fired when an audit write fails. Receives the error and the
+   * entry that failed to land.
    *
-   * **Use this for compliance-grade audit trails (SOC 2 / PCI / HIPAA)
-   * where missing entries must be surfaced upstream** — e.g. forward to
-   * a dead-letter queue, page on-call, or short-circuit the request.
-   * The default `warn` log is appropriate for development and
-   * eventually-consistent observability use cases but is invisible to
-   * compliance review.
-   *
-   * The callback runs on the same fire-and-forget microtask that wrote
-   * the entry, so throwing from here will surface as an unhandled
-   * rejection — handle (or rethrow into your error reporter) inside.
+   * - In `'best-effort'` mode this is the ONLY failure signal — the
+   *   operation has already succeeded. Forward to a dead-letter queue or
+   *   error reporter; the default is a `console.warn`-level log. Note that
+   *   a callback cannot make fire-and-forget writes atomic — if you need
+   *   "no business write without an audit entry", use `mode:
+   *   'transactional'` inside a transaction.
+   * - In `'transactional'` mode the callback observes the failure before
+   *   the operation itself rejects (and, inside a transaction, before the
+   *   transaction aborts). Throwing from the callback is safe — the
+   *   original write error still propagates.
    */
   onWriteError?: (error: Error, entry: Omit<AuditEntry, 'timestamp'>) => void;
 }
@@ -57,6 +103,38 @@ interface AuditEntry {
   timestamp: Date;
 }
 declare function auditTrailPlugin(options?: AuditTrailOptions): Plugin;
+/** Options for {@link ensureAuditTrailReady}. */
+interface EnsureAuditTrailReadyOptions {
+  /** Connection the audit model lives on (default: `mongoose.connection`). */
+  connection?: Connection;
+  /** MongoDB collection name (default: 'audit_trails'). */
+  collectionName?: string;
+  /**
+   * TTL in days. Omit to reuse whatever the plugin already registered;
+   * pass explicitly (before the plugin, e.g. in a migration script) to
+   * declare retention up front — conflicts with an existing registration
+   * throw.
+   */
+  ttlDays?: number;
+}
+/**
+ * Create the audit collection and build its indexes BEFORE traffic begins.
+ *
+ * Call once at boot (after the plugin is registered, before serving
+ * requests) — especially with `mode: 'transactional'`: creating the
+ * collection or building indexes lazily inside the first transaction
+ * forces MongoDB catalog locks and transient `TransientTransactionError`
+ * retries. Idempotent; safe to call on every boot.
+ *
+ * @example
+ * ```typescript
+ * const repo = new Repository(Model, [
+ *   auditTrailPlugin({ mode: 'transactional', ttlDays: 90 }),
+ * ]);
+ * await ensureAuditTrailReady(); // collection + indexes exist before traffic
+ * ```
+ */
+declare function ensureAuditTrailReady(options?: EnsureAuditTrailReadyOptions): Promise<void>;
 interface AuditQueryOptions {
   model?: string;
   documentId?: string | ObjectId;
@@ -77,6 +155,24 @@ interface AuditQueryResult {
   hasNext: boolean;
   hasPrev: boolean;
 }
+/** Constructor options for {@link AuditTrailQuery}. */
+interface AuditTrailQueryOptions {
+  /** MongoDB collection name (default: 'audit_trails') */
+  collectionName?: string;
+  /**
+   * TTL in days. Omit (recommended) to reuse whatever retention the writing
+   * plugin configured — readers don't need to know it. When passed
+   * explicitly it is conflict-checked against the existing registration and
+   * a mismatch throws.
+   */
+  ttlDays?: number;
+  /**
+   * Mongoose connection the audit model lives on. Defaults to the global
+   * `mongoose.connection`. Pass the same connection you gave
+   * `auditTrailPlugin` for multi-DB apps.
+   */
+  connection?: Connection;
+}
 /**
  * Standalone audit trail query utility.
  * Use this to query audits across all models — e.g., admin dashboards, audit APIs.
@@ -85,7 +181,10 @@ interface AuditQueryResult {
  * ```typescript
  * import { AuditTrailQuery } from '@classytic/mongokit';
  *
- * const auditQuery = new AuditTrailQuery(); // defaults to 'audit_trails' collection
+ * const auditQuery = new AuditTrailQuery(); // defaults to 'audit_trails' on mongoose.connection
+ *
+ * // Named connection (multi-DB apps)
+ * const tenantAudits = new AuditTrailQuery({ connection: tenantConnection });
  *
  * // All audits for an org
  * const orgAudits = await auditQuery.query({ orgId: '...' });
@@ -117,7 +216,7 @@ interface AuditQueryResult {
  */
 declare class AuditTrailQuery {
   private model;
-  constructor(collectionName?: string, ttlDays?: number);
+  constructor(options?: AuditTrailQueryOptions);
   /**
    * Get the underlying Mongoose model for custom queries
    */
@@ -483,4 +582,4 @@ declare function adminBypass(options: {
   adminRoles: readonly string[];
 }): (context: RepositoryContext, operation: string) => boolean;
 //#endregion
-export { AuditTrailMethods as C, auditTrailPlugin as E, AuditQueryResult as S, AuditTrailQuery as T, RepositoryCachePluginOptions as _, DateSequentialIdOptions as a, AuditOperation as b, SequentialIdOptions as c, getNextSequence as d, prefixedId as f, RepositoryCacheHandle as g, CacheOptions as h, CustomIdOptions as i, customIdPlugin as l, CacheAdapter$1 as m, adminBypass as n, IdGenerator as o, sequentialId as p, multiTenantPlugin as r, PrefixedIdOptions as s, MultiTenantOptions as t, dateSequentialId as u, cachePlugin as v, AuditTrailOptions as w, AuditQueryOptions as x, AuditEntry as y };
+export { ensureAuditTrailReady as A, AuditTrailMethods as C, AuditTrailQueryOptions as D, AuditTrailQuery as E, EnsureAuditTrailReadyOptions as O, AuditQueryResult as S, AuditTrailOptions as T, RepositoryCachePluginOptions as _, DateSequentialIdOptions as a, AuditOperation as b, SequentialIdOptions as c, getNextSequence as d, prefixedId as f, RepositoryCacheHandle as g, CacheOptions as h, CustomIdOptions as i, auditTrailPlugin as k, customIdPlugin as l, CacheAdapter$1 as m, adminBypass as n, IdGenerator as o, sequentialId as p, multiTenantPlugin as r, PrefixedIdOptions as s, MultiTenantOptions as t, dateSequentialId as u, cachePlugin as v, AuditTrailMode as w, AuditQueryOptions as x, AuditEntry as y };

package/dist/operations-C8IcCHF9.d.mts

@@ -0,0 +1,463 @@
+import { a as PopulateSpec, i as ObjectId, l as SortSpec, o as ReadPreferenceType, s as SelectSpec } from "./core-62oo3N1C.mjs";
+import { r as CollationOptions } from "./pagination-jSUdrACK.mjs";
+import { DeleteManyResult, DeleteResult, LookupPopulateResult, UpdateManyResult } from "@classytic/repo-core/repository";
+import { PipelineStage, PopulateOptions } from "mongoose";
+import { Filter } from "@classytic/repo-core/filter";
+//#region src/query/LookupBuilder.d.ts
+interface LookupOptions {
+  /** Collection to join with */
+  from: string;
+  /** Field from the input documents */
+  localField: string;
+  /** Field from the documents of the "from" collection */
+  foreignField: string;
+  /** Name of the new array field to add to the input documents */
+  as?: string;
+  /** Whether to unwrap array to single object */
+  single?: boolean;
+  /**
+   * Field selection on the joined collection (shorthand for `$project`).
+   * Three accepted shapes — all map to a single `$project` stage:
+   *   - `string` — CSV form (`'name,price'`); leading `-` marks an exclusion.
+   *   - `readonly string[]` — array form (`['name', 'price']` / `['-status']`);
+   *     mirrors `repo-core/lookup` `LookupSpec.select` for cross-kit parity.
+   *   - `Record<string, 0 | 1>` — explicit Mongo projection map.
+   */
+  select?: string | readonly string[] | Record<string, 0 | 1>;
+  /** Additional pipeline to run on the joined collection */
+  pipeline?: PipelineStage[];
+  /** Optional let variables for pipeline */
+  let?: Record<string, string>;
+  /** Query filter to apply before join (legacy, for aggregate.ts compatibility) */
+  query?: Record<string, unknown>;
+  /** Query options (legacy, for aggregate.ts compatibility) */
+  options?: {
+    session?: unknown;
+  };
+  /** Sanitize pipeline stages (default: true). Set false only for trusted server-side pipelines */
+  sanitize?: boolean;
+  /**
+   * Joined-side filter, compiled into a `$match` stage inside the lookup
+   * pipeline AFTER the auto-generated join correlation. Mirrors
+   * `repo-core/lookup/types.ts#LookupSpec.where` and sqlitekit's
+   * predicate-on-the-JOIN behavior, so cross-kit code that narrows the
+   * foreign side (`where: eq('status', 'active')`) gets identical rows
+   * from both backends.
+   *
+   * Accepts Filter IR or a plain mongo query — `compileFilterToMongo`
+   * routes each correctly.
+   */
+  where?: Filter | Record<string, unknown>;
+}
+/**
+ * Fluent builder for MongoDB $lookup aggregation stage
+ * Optimized for custom field joins at scale
+ */
+declare class LookupBuilder {
+  private options;
+  constructor(from?: string);
+  /**
+   * Set the collection to join with
+   */
+  from(collection: string): this;
+  /**
+   * Set the local field (source collection)
+   * IMPORTANT: This field should be indexed for optimal performance
+   */
+  localField(field: string): this;
+  /**
+   * Set the foreign field (target collection)
+   * IMPORTANT: This field should be indexed (preferably unique) for optimal performance
+   */
+  foreignField(field: string): this;
+  /**
+   * Set the output field name
+   * Defaults to the collection name if not specified
+   */
+  as(fieldName: string): this;
+  /**
+   * Mark this lookup as returning a single document
+   * Automatically unwraps the array result to a single object or null
+   */
+  single(isSingle?: boolean): this;
+  /**
+   * Add a pipeline to filter/transform joined documents
+   * Useful for filtering, sorting, or limiting joined results
+   *
+   * @example
+   * ```typescript
+   * lookup.pipeline([
+   *   { $match: { status: 'active' } },
+   *   { $sort: { priority: -1 } },
+   *   { $limit: 5 }
+   * ]);
+   * ```
+   */
+  pipeline(stages: PipelineStage[]): this;
+  /**
+   * Set let variables for use in pipeline
+   * Allows referencing local document fields in the pipeline
+   */
+  let(variables: Record<string, string>): this;
+  /**
+   * Control pipeline sanitization (default: true)
+   * Set to false for auto-generated pipelines that are known safe
+   */
+  sanitize(enabled: boolean): this;
+  /**
+   * Build the $lookup aggregation stage(s)
+   * Returns an array of pipeline stages including $lookup and optional $unwind
+   *
+   * IMPORTANT: MongoDB $lookup has two mutually exclusive forms:
+   * 1. Simple form: { from, localField, foreignField, as }
+   * 2. Pipeline form: { from, let, pipeline, as }
+   *
+   * When pipeline or let is specified, we use the pipeline form.
+   * Otherwise, we use the simpler localField/foreignField form.
+   */
+  build(): PipelineStage[];
+  /**
+   * Build and return only the $lookup stage (without $unwind)
+   * Useful when you want to handle unwrapping yourself
+   */
+  buildLookupOnly(): PipelineStage.Lookup;
+  /**
+   * Static helper: Create a simple lookup in one line
+   */
+  static simple(from: string, localField: string, foreignField: string, options?: {
+    as?: string;
+    single?: boolean;
+  }): PipelineStage[];
+  /**
+   * Static helper: Create multiple lookups at once
+   *
+   * @example
+   * ```typescript
+   * const pipeline = LookupBuilder.multiple([
+   *   { from: 'departments', localField: 'deptSlug', foreignField: 'slug', single: true },
+   *   { from: 'managers', localField: 'managerId', foreignField: '_id', single: true }
+   * ]);
+   * ```
+   */
+  static multiple(lookups: LookupOptions[]): PipelineStage[];
+  /**
+   * Static helper: Create a nested lookup (lookup within lookup)
+   * Useful for multi-level joins like Order -> Product -> Category
+   *
+   * @example
+   * ```typescript
+   * // Join orders with products, then products with categories
+   * const pipeline = LookupBuilder.nested([
+   *   { from: 'products', localField: 'productSku', foreignField: 'sku', as: 'product', single: true },
+   *   { from: 'categories', localField: 'product.categorySlug', foreignField: 'slug', as: 'product.category', single: true }
+   * ]);
+   * ```
+   */
+  static nested(lookups: LookupOptions[]): PipelineStage[];
+  /**
+   * Sanitize pipeline stages by blocking dangerous stages and operators.
+   * Used internally by build() and available for external use (e.g., aggregate.ts).
+   */
+  static sanitizePipeline(stages: PipelineStage[]): PipelineStage[];
+  /**
+   * Recursively remove dangerous operators from an expression object.
+   */
+  private static _sanitizeDeep;
+}
+/**
+ * Performance Guidelines for $lookup at Scale:
+ *
+ * 1. **Index Requirements** (Critical for millions of records):
+ *    - localField should be indexed on source collection
+ *    - foreignField should be indexed on target collection (unique index preferred)
+ *
+ *    Example:
+ *    ```typescript
+ *    // Employee collection
+ *    employeeSchema.index({ departmentSlug: 1 });
+ *
+ *    // Department collection
+ *    departmentSchema.index({ slug: 1 }, { unique: true });
+ *    ```
+ *
+ * 2. **Query Performance**:
+ *    - With proper indexes: O(log n) per lookup
+ *    - Without indexes: O(n * m) - AVOID THIS!
+ *    - Use explain() to verify index usage: IXSCAN (good) vs COLLSCAN (bad)
+ *
+ * 3. **Pipeline Optimization**:
+ *    - Place $match stages as early as possible
+ *    - Use $project to reduce field size before lookups
+ *    - Limit joined results with pipeline: [{ $match: {...} }, { $limit: n }]
+ *
+ * 4. **Memory Considerations**:
+ *    - Each lookup creates a new field in memory
+ *    - Use $project after lookup to remove unnecessary fields
+ *    - Consider allowDiskUse: true for very large datasets
+ *
+ * 5. **Alternative Approaches**:
+ *    - For 1:1 relationships with high read frequency: Consider storing ObjectId + slug
+ *    - For read-heavy workloads: Consider caching or materialized views
+ *    - For real-time dashboards: Consider separate aggregation collections
+ */
+//#endregion
+//#region src/types/operations.d.ts
+/** Session-only options — shared base for lightweight operations */
+interface SessionOptions {
+  /** MongoDB session for transactions */
+  session?: unknown;
+  /** Organization/tenant ID for multi-tenant plugin scoping */
+  organizationId?: string | ObjectId;
+  /**
+   * Per-call escape hatch — plugins listed here that opt into the
+   * mechanism (`auditLog`, `auditTrail`, `observability`) read this
+   * from `RepositoryContext` and skip their work for this call. Use
+   * on hot paths (e.g. heartbeats / counters) where the audit overhead
+   * dominates.
+   *
+   * Plugins that enforce correctness or security (multi-tenant scope,
+   * cache invalidation, soft-delete filter) deliberately ignore this
+   * flag — security/correctness must not be skippable per-call.
+   *
+   * **Match exactly by `plugin.name`** (camelCase, NOT kebab-case):
+   *   - `'auditLog'` — see `auditLogPlugin()` in
+   *     `src/plugins/audit-log.plugin.ts` (`name: 'auditLog'`)
+   *   - `'auditTrail'` — see `auditTrailPlugin()` in
+   *     `src/plugins/audit-trail.plugin.ts` (`name: 'auditTrail'`)
+   *   - `'observability'` — see `observabilityPlugin()` in
+   *     `src/plugins/observability.plugin.ts` (`name: 'observability'`)
+   */
+  skipPlugins?: readonly string[];
+  /**
+   * Per-call escape hatch for `multiTenantPlugin`. When `true`, the
+   * tenant scope hook returns without injecting `organizationId` (or
+   * the configured `tenantField`) into the operation's policy slot
+   * for THIS call only. The plugin emits `after:tenant-bypass` with
+   * `{ context, operation, reason: 'option' }` so audit / observability
+   * plugins can distinguish bypassed queries from tenant-scoped ones.
+   *
+   * Reach for this when:
+   *   - A super-admin / platform-admin user needs cross-tenant read
+   *     for support tooling.
+   *   - A migration script writes / backfills across tenants
+   *     deliberately.
+   *   - A scheduled job (TTL cleanup, cross-tenant aggregate, billing
+   *     rollup) needs the unscoped view.
+   *
+   * **`bypassTenant` is the most-specific decision** — runs before
+   * `skipWhen` (plugin-level callback) and `resolveContext` (CLS
+   * fallback). Distinct from `skipWhen` which fires for every call
+   * and reads context to decide; `bypassTenant: true` is a deliberate
+   * per-call opt-out with no role check, so the calling code carries
+   * the responsibility.
+   *
+   * **NOT a substitute for proper access control.** This flag bypasses
+   * tenant scoping; it does NOT bypass authentication, RBAC, or any
+   * other host-level access check. Wrap it with your auth boundary at
+   * the controller / service layer.
+   *
+   * @example
+   * ```ts
+   * // Support engineer pulling a customer's order across tenants:
+   * await orderRepo.findAll({}, { bypassTenant: true });
+   *
+   * // Migration backfill across the whole estate:
+   * for await (const doc of repo.cursor({}, { bypassTenant: true })) { ... }
+   * ```
+   */
+  bypassTenant?: boolean;
+  /**
+   * Per-call escape hatch for `appendOnlyPlugin` — deliberate
+   * maintenance on an immutable-facts collection (backfill repair,
+   * migration). Audited via `after:append-only-bypass`; grep for this
+   * flag the same way you grep `bypassTenant` / `mode: 'hard'`. NOT a
+   * substitute for access control — gate it at the host layer.
+   */
+  bypassAppendOnly?: boolean;
+  /** Extensible — plugins can read custom fields from options */
+  [key: string]: unknown;
+}
+/** Read options — session + readPreference for read-only operations */
+interface ReadOptions extends SessionOptions {
+  /** Read preference for replica sets (e.g. 'secondaryPreferred') */
+  readPreference?: ReadPreferenceType;
+}
+/** Repository operation options */
+interface OperationOptions extends ReadOptions {
+  /** Fields to select */
+  select?: SelectSpec;
+  /** Fields to populate */
+  populate?: PopulateSpec;
+  /** Advanced populate options (from QueryParser or Arc's BaseController) */
+  populateOptions?: PopulateOptions[];
+  /** Return plain JavaScript objects */
+  lean?: boolean;
+  /** Throw error if document not found (default: true) */
+  throwOnNotFound?: boolean;
+  /** Override the ID field for this call (default: repo.idField or '_id').
+   * Use when the same repo sometimes queries by _id and sometimes by slug/code. */
+  idField?: string;
+  /** Additional query filters (e.g., for soft delete) */
+  query?: Record<string, unknown>;
+}
+/**
+ * Cache-aware operation options — extends OperationOptions with the
+ * unified cache plugin's per-call shape. Pass `cache: { staleTime, swr,
+ * tags, bypass, ... }` to override freshness for this call.
+ */
+interface CacheableOptions extends OperationOptions {
+  /** Per-call cache override forwarded to the unified cache plugin. */
+  cache?: import('@classytic/repo-core/cache').CacheOptions;
+}
+/**
+ * Per-call cache options — TanStack-shaped (`staleTime`, `gcTime`, `swr`,
+ * `tags`, `bypass`, `enabled`, `key`). Threaded through read methods via
+ * `options.cache` (CRUD) or `aggRequest.cache` (aggregate).
+ *
+ * Mongokit 3.13+ delegates cache wiring to `@classytic/repo-core/cache` —
+ * the unified plugin owns the canonical `CacheAdapter` / `CacheOptions` /
+ * `RepositoryCacheHandle` types; kits import them directly.
+ */
+interface CacheOperationOptions {
+  /** Per-call cache override forwarded to the unified cache plugin. */
+  cache?: import('@classytic/repo-core/cache').CacheOptions;
+}
+/** withTransaction options */
+interface WithTransactionOptions {
+  /** Allow non-transactional fallback when transactions are unsupported */
+  allowFallback?: boolean;
+  /** Optional hook to observe fallback triggers */
+  onFallback?: (error: Error) => void;
+  /** MongoDB transaction options (readConcern, writeConcern, readPreference, maxCommitTimeMS) */
+  transactionOptions?: import('mongoose').mongo.TransactionOptions;
+}
+/** Create operation options */
+interface CreateOptions extends SessionOptions {
+  /** Keep insertion order on error (default: false).
+   * When false, all valid documents insert even if some fail (e.g. duplicates).
+   * Set to true to abort remaining inserts on first error. */
+  ordered?: boolean;
+}
+/** Update operation options */
+interface UpdateOptions extends OperationOptions {
+  /** Enable update pipeline syntax */
+  updatePipeline?: boolean;
+  /** Array filters for positional operator $[<identifier>] updates */
+  arrayFilters?: Record<string, unknown>[];
+}
+/**
+ * Options for atomic findOneAndUpdate (compare-and-set primitive).
+ *
+ * Designed for outbox/lock/semaphore patterns that need a single round-trip
+ * match-and-mutate. Goes through the full hook pipeline (multi-tenant scope,
+ * soft-delete, audit) the same way `update()` does.
+ */
+interface FindOneAndUpdateOptions extends OperationOptions {
+  /** Sort to disambiguate when filter matches multiple docs (e.g. FIFO claim). */
+  sort?: SortSpec;
+  /** Return doc state before or after the update. Default: 'after'. */
+  returnDocument?: 'before' | 'after';
+  /** Insert if no doc matches. Default: false. */
+  upsert?: boolean;
+  /** Array filters for positional `$[<identifier>]` updates. */
+  arrayFilters?: Record<string, unknown>[];
+  /** Allow aggregation-pipeline updates (array form). Default: false. */
+  updatePipeline?: boolean;
+  /** Run mongoose schema validators on the update. Default: true. */
+  runValidators?: boolean;
+  /** Collation for locale-aware string comparison. */
+  collation?: CollationOptions;
+  /** Maximum execution time in milliseconds. */
+  maxTimeMS?: number;
+}
+/** Aggregate operation options */
+interface AggregateOptions extends ReadOptions {
+  /** Allow aggregation to use disk for large sorts/groups */
+  allowDiskUse?: boolean;
+  /** Comment for profiler/logs */
+  comment?: string;
+  /** Maximum execution time in milliseconds */
+  maxTimeMS?: number;
+  /** Read concern level */
+  readConcern?: {
+    level: string;
+  };
+  /** Collation for locale-aware string comparison */
+  collation?: CollationOptions;
+  /** Maximum allowed pipeline stages (governance) */
+  maxPipelineStages?: number;
+}
+/**
+ * Mongokit's `lookupPopulate` options — kit-native superset of the
+ * portable `LookupPopulateOptions<TBase>` from repo-core. Widens three
+ * slots so arc / mongoose consumers compose cleanly:
+ *
+ *   - `filters`: accepts Filter IR, a `Partial<TBase> & Record<string,
+ *     unknown>` literal (same shape repo-core's contract uses), or a
+ *     plain `Record<string, unknown>` for legacy callers.
+ *   - `lookups`: accepts either the portable `LookupSpec[]` (works on
+ *     every kit) or mongokit's `LookupOptions[]` (adds `pipeline` /
+ *     `let` / `sanitize` for mongo-correlated joins).
+ *   - `select`: accepts mongoose's space-separated string form
+ *     (`'name email'`) in addition to the portable array / inclusion
+ *     map. Kept for arc + existing controller convenience.
+ *
+ * `TBase` defaults to `unknown` so legacy non-generic usage still
+ * compiles; pass the doc type for arc `RepositoryLike<TDoc>` structural
+ * assignment — `LookupPopulateOptions<TDoc>` is bit-compatible with
+ * `import('@classytic/repo-core/repository').LookupPopulateOptions<TDoc>`.
+ */
+interface LookupPopulateOptions<TBase = unknown> {
+  /**
+   * Base-table filter. Accepts Filter IR from repo-core, a typed
+   * `Partial<TBase> & Record<string, unknown>` literal (what arc
+   * controllers produce when typed against `StandardRepo<TDoc>`), or
+   * a plain `Record<string, unknown>` for ad-hoc callers.
+   */
+  filters?: import('@classytic/repo-core/filter').Filter | (Partial<TBase> & Record<string, unknown>) | Record<string, unknown>;
+  /**
+   * Portable `LookupSpec[]` (cross-kit) or mongokit-native
+   * `LookupOptions[]` (with `pipeline` / `let` / `sanitize`). The
+   * portable shape is a structural subset, so callers can mix.
+   */
+  lookups: readonly import('@classytic/repo-core/repository').LookupSpec[] | LookupOptions[];
+  /** Sort specification */
+  sort?: SortSpec | string;
+  /** Page number (offset mode, 1-indexed) */
+  page?: number;
+  /** Cursor token for next page (keyset mode) */
+  after?: string;
+  /** Number of documents per page */
+  limit?: number;
+  /** Fields to select */
+  select?: SelectSpec;
+  /** Collation for locale-aware string comparison */
+  collation?: CollationOptions;
+  /** Count strategy for offset pagination */
+  countStrategy?: 'exact' | 'estimated' | 'none';
+  /**
+   * Transaction session. Typed `unknown` to match repo-core's
+   * `RepositorySession` contract — mongokit narrows to `ClientSession`
+   * internally. Not inherited from `ReadOptions` because the repo-core
+   * contract type has no `[key: string]: unknown` escape hatch, and
+   * arc's `Partial<StandardRepo<TDoc>>` boundary rejects index-signature
+   * drift under strict function-type variance.
+   */
+  session?: unknown;
+  /** Read preference for replica sets (e.g. 'secondaryPreferred') */
+  readPreference?: ReadPreferenceType;
+  /** Multi-tenant plugin scoping (applied via before:lookupPopulate hook). */
+  organizationId?: string | ObjectId;
+}
+/** Group result */
+interface GroupResult {
+  _id: unknown;
+  count: number;
+}
+/** Min/Max result */
+interface MinMaxResult {
+  min: unknown;
+  max: unknown;
+}
+//#endregion
+export { WithTransactionOptions as _, DeleteManyResult as a, GroupResult as c, MinMaxResult as d, OperationOptions as f, UpdateOptions as g, UpdateManyResult as h, CreateOptions as i, LookupPopulateOptions as l, SessionOptions as m, CacheOperationOptions as n, DeleteResult as o, ReadOptions as p, CacheableOptions as r, FindOneAndUpdateOptions as s, AggregateOptions as t, LookupPopulateResult as u, LookupBuilder as v, LookupOptions as y };

package/dist/pagination/PaginationEngine.d.mts

@@ -1,2 +1,2 @@
-import { t as PaginationEngine } from "../PaginationEngine-BnZ24ehC.mjs";
+import { t as PaginationEngine } from "../PaginationEngine-CBS1XGzp.mjs";
 export { PaginationEngine };