@classytic/mongokit 3.43.1 → 3.45.0

package/dist/usage/index.d.mts

@@ -1,8 +1,7 @@
 import { Connection } from "mongoose";
 import { UsageStore } from "@classytic/repo-core/usage";
-//#region src/usage/index.d.ts
 /** Adapter-construction options. */
-interface MongoUsageStoreOptions {
+export interface MongoUsageStoreOptions {
   /**
    * Mongoose connection. Defaults to `mongoose.connection` (the
    * default global connection). Apps using a named connection pass
@@ -18,6 +17,4 @@ interface MongoUsageStoreOptions {
  * Build a Mongo-backed usage store. Idempotent — the underlying model
  * is registered once per `(connection, modelName)` pair.
  */
-declare function createMongoUsageStore(options?: MongoUsageStoreOptions): UsageStore;
-//#endregion
-export { MongoUsageStoreOptions, createMongoUsageStore };
+export declare function createMongoUsageStore(options?: MongoUsageStoreOptions): UsageStore;

package/dist/usage/index.mjs

@@ -1,6 +1,6 @@
-import { n as isDuplicateKeyError } from "../error-BuByZwKU.mjs";
+import { n as isDuplicateKeyError } from "../error-DjdmPLWO.mjs";
 import mongoose, { Schema } from "mongoose";
-//#region src/usage/index.ts
+// src/usage/index.ts
 /**
 * Build a Mongo-backed usage store. Idempotent — the underlying model
 * is registered once per `(connection, modelName)` pair.
@@ -8,9 +8,12 @@ import mongoose, { Schema } from "mongoose";
 function createMongoUsageStore(options = {}) {
 	const { connection, collectionName = "usage_counters", modelName = "MongoUsageCounter" } = options;
 	const model = getOrCreateModel(connection ?? mongoose, modelName, collectionName);
+	const ready = model.init();
+	ready.catch(() => void 0);
 	return {
 		name: "mongo",
 		async increment(bucket, amount) {
+			await ready;
 			const filter = {
 				actor: bucket.actor,
 				period: bucket.period,
@@ -28,9 +31,9 @@ function createMongoUsageStore(options = {}) {
 				actor,
 				period
 			}).select("kind count").lean();
-			const out = {};
-			for (const row of rows) out[row.kind] = row.count;
-			return out;
+			const sums = /* @__PURE__ */ new Map();
+			for (const row of rows) sums.set(row.kind, (sums.get(row.kind) ?? 0) + row.count);
+			return Object.fromEntries(sums);
 		}
 	};
 }
@@ -63,5 +66,4 @@ function getOrCreateModel(conn, modelName, collectionName) {
 	}, { unique: true });
 	return conn.model(modelName, schema, collectionName);
 }
-//#endregion
 export { createMongoUsageStore };

package/dist/utils/index.d.mts

@@ -1,19 +1,18 @@
-import { _ as getMongooseProjection, a as createMemoryCache, b as createError, c as IdType, d as isObjectIdInstance, f as isValidIdForType, g as getFieldsForUser, h as filterResponseData, i as buildCrudSchemasFromMongooseSchema, l as getSchemaIdType, m as createFieldPreset, n as CrudSchemasFramework, o as LoggerConfig, p as toObjectId, r as buildCrudSchemasFromModel, s as configureLogger, t as toPlain, v as CreateErrorOptions, y as ParseDuplicateKeyOptions } from "../to-plain-o5tUY2nV.mjs";
+import { _ as getMongooseProjection, a as createMemoryCache, b as createError, c as IdType, d as isObjectIdInstance, f as isValidIdForType, g as getFieldsForUser, h as filterResponseData, i as buildCrudSchemasFromMongooseSchema, l as getSchemaIdType, m as createFieldPreset, n as CrudSchemasFramework, o as LoggerConfig, p as toObjectId, r as buildCrudSchemasFromModel, s as configureLogger, t as toPlain, v as CreateErrorOptions, y as ParseDuplicateKeyOptions } from "../to-plain-Do-8jTKC.mjs";
 import { ClientSession, Model } from "mongoose";
-//#region src/utils/id-chunks.d.ts
 /**
  * Default slice for `$in` fan-out. Larger than `runChunkedPurge`'s 1000 on purpose:
  * a purge chunk bounds the WRITE LOCK SCOPE of each progressive strategy step, while a
  * snapshot slice bounds only the query-document size and the per-call working set —
  * 10k ObjectIds is ~120 KB of `$in`, far under every limit, at 10× fewer round trips.
  */
-declare const DEFAULT_ID_CHUNK = 10000;
+export declare const DEFAULT_ID_CHUNK = 10000;
 /**
  * Collect the bare id values matching `filter`, streaming via a driver cursor so the
  * only O(n) allocation is the returned array itself (a `find().lean()` materializes an
  * intermediate array of `{_id}` documents first — roughly double the peak for large n).
  */
-declare function collectIds(model: Model<unknown>, filter: Record<string, unknown>, options?: {
+export declare function collectIds(model: Model<unknown>, filter: Record<string, unknown>, options?: {
   session?: ClientSession | undefined;
   idField?: string;
 }): Promise<unknown[]>;
@@ -22,7 +21,7 @@ declare function collectIds(model: Model<unknown>, filter: Record<string, unknow
  * array. `size` must be a positive integer — sliced `$in` correctness depends on it,
  * so a nonsense size throws instead of silently degrading to one giant slice.
  */
-declare function idChunks<T>(ids: readonly T[], size: number): Generator<T[], void, undefined>;
+export declare function idChunks<T>(ids: readonly T[], size: number): Generator<T[], void, undefined>;
 /**
  * Compose the keyset-progressed select filter: the base predicate, narrowed to rows past
  * the last committed `_id`. `cursor == null` means "from the start". Selection paired
@@ -30,7 +29,7 @@ declare function idChunks<T>(ids: readonly T[], size: number): Generator<T[], vo
  * never revisits a processed row and never skips an unprocessed one. Never mutates
  * `baseFilter`.
  */
-declare function keysetFilter(baseFilter: Record<string, unknown>, cursor: unknown): Record<string, unknown>;
+export declare function keysetFilter(baseFilter: Record<string, unknown>, cursor: unknown): Record<string, unknown>;
 /**
  * The `_id`-ascending bounded chunk select both action ports share:
  * `find(filter).sort({_id: 1}).limit(limit).lean()`. Lean on purpose — chunk consumers
@@ -38,7 +37,7 @@ declare function keysetFilter(baseFilter: Record<string, unknown>, cursor: unkno
  * are needed (the purge port's common path); omit it for full docs (archive's readChunk,
  * anonymize-functional).
  */
-declare function selectKeysetChunk<T>(model: Model<T>, filter: Record<string, unknown>, limit: number, options?: {
+export declare function selectKeysetChunk<T>(model: Model<T>, filter: Record<string, unknown>, limit: number, options?: {
   session?: ClientSession | undefined;
   projection?: Record<string, 1 | 0> | undefined;
 }): Promise<T[]>;
@@ -49,6 +48,5 @@ declare function selectKeysetChunk<T>(model: Model<T>, filter: Record<string, un
  * write — such a row is silently skipped instead of written outside its cohort. Both
  * action ports use this shape; use it for any select-then-write over a chunk.
  */
-declare function narrowToIds(baseFilter: Record<string, unknown>, ids: readonly unknown[]): Record<string, unknown>;
-//#endregion
-export { type CreateErrorOptions, type CrudSchemasFramework, DEFAULT_ID_CHUNK, type IdType, type LoggerConfig, type ParseDuplicateKeyOptions, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, collectIds, configureLogger, createError, createFieldPreset, createMemoryCache, filterResponseData, getFieldsForUser, getMongooseProjection, getSchemaIdType, idChunks, isObjectIdInstance, isValidIdForType, keysetFilter, narrowToIds, selectKeysetChunk, toObjectId, toPlain };
+export declare function narrowToIds(baseFilter: Record<string, unknown>, ids: readonly unknown[]): Record<string, unknown>;
+export { type CreateErrorOptions, type CrudSchemasFramework, type IdType, type LoggerConfig, type ParseDuplicateKeyOptions, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, configureLogger, createError, createFieldPreset, createMemoryCache, filterResponseData, getFieldsForUser, getMongooseProjection, getSchemaIdType, isObjectIdInstance, isValidIdForType, toObjectId, toPlain };

package/dist/utils/index.mjs

@@ -1,8 +1,8 @@
-import { a as toObjectId, i as isValidIdForType, r as isObjectIdInstance, t as getSchemaIdType } from "../id-resolution-BqDrk0S2.mjs";
-import { a as narrowToIds, i as keysetFilter, n as collectIds, o as selectKeysetChunk, r as idChunks, t as DEFAULT_ID_CHUNK } from "../id-chunks-BmAwsqNk.mjs";
-import { t as configureLogger } from "../logger-K7dPmu2U.mjs";
-import { t as createError } from "../error-BuByZwKU.mjs";
-import { i as getMongooseProjection, n as filterResponseData, r as getFieldsForUser, t as createFieldPreset } from "../field-selection-FSQFLpsU.mjs";
-import { n as createMemoryCache, t as toPlain } from "../to-plain-vksRrLtc.mjs";
-import { n as buildCrudSchemasFromMongooseSchema, t as buildCrudSchemasFromModel } from "../mongooseToJsonSchema-C3k4ide0.mjs";
+import { t as createError } from "../error-DjdmPLWO.mjs";
+import { i as getMongooseProjection, n as filterResponseData, r as getFieldsForUser, t as createFieldPreset } from "../field-selection-DPFaFw9Y.mjs";
+import { a as narrowToIds, i as keysetFilter, n as collectIds, o as selectKeysetChunk, r as idChunks, t as DEFAULT_ID_CHUNK } from "../id-chunks-DH-RAZWG.mjs";
+import { a as toObjectId, i as isValidIdForType, r as isObjectIdInstance, t as getSchemaIdType } from "../id-resolution-Cqh49d9J.mjs";
+import { t as configureLogger } from "../logger-hbWOlj_X.mjs";
+import { n as createMemoryCache, t as toPlain } from "../to-plain-CEKv_ylg.mjs";
+import { n as buildCrudSchemasFromMongooseSchema, t as buildCrudSchemasFromModel } from "../mongooseToJsonSchema-DMDotz4_.mjs";
 export { DEFAULT_ID_CHUNK, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, collectIds, configureLogger, createError, createFieldPreset, createMemoryCache, filterResponseData, getFieldsForUser, getMongooseProjection, getSchemaIdType, idChunks, isObjectIdInstance, isValidIdForType, keysetFilter, narrowToIds, selectKeysetChunk, toObjectId, toPlain };

package/dist/{validation-chain.plugin-BAeC5eVT.d.mts → validation-chain.plugin-COYrUdd8.d.mts}

@@ -1,10 +1,10 @@
-import { A as ObjectId, F as SortSpec, N as SelectSpec, j as PopulateSpec } from "./pagination-D6psses0.mjs";
-import { h as RepositoryInstance, l as Plugin, p as RepositoryContext } from "./repository-MqAP409e.mjs";
-import { c as ValidationChainOptions, i as Logger, l as ValidatorDefinition, o as SoftDeleteOptions, r as FieldPreset, t as CascadeOptions } from "./plugin-options-Cirmb4Kp.mjs";
+import { A as ObjectId, F as SortSpec, N as SelectSpec, j as PopulateSpec } from "./pagination-BAM9cA4N.mjs";
+import { h as RepositoryInstance, l as Plugin, p as RepositoryContext } from "./repository-B0aFVgP2.mjs";
+import { n as RetentionPurgeEvent, r as RetentionPurgeRequest } from "./retention-purge-CCd_VXUf.mjs";
+import { c as ValidationChainOptions, i as Logger, l as ValidatorDefinition, o as SoftDeleteOptions, r as FieldPreset, t as CascadeOptions } from "./plugin-options-DrNGWV5b.mjs";
 import { BulkWriteResult } from "@classytic/repo-core/repository";
 import { OffsetPaginationResult } from "@classytic/repo-core/pagination";
 import { AsyncLocalStorage } from "node:async_hooks";
-//#region src/plugins/aggregate-helpers.plugin.d.ts
 /**
  * Aggregate helpers plugin
  *
@@ -88,8 +88,6 @@ interface AggregateHelpersMethods {
    */
   max(field: string, query?: Record<string, unknown>, options?: Record<string, unknown>): Promise<number>;
 }
-//#endregion
-//#region src/plugins/append-only.plugin.d.ts
 interface AppendOnlyPluginOptions {
   /**
    * Mutating ops to permit besides `create` / `createMany`. Use for a
@@ -106,13 +104,26 @@ interface AppendOnlyPluginOptions {
    * "append-only", never "missing organizationId".
    */
   priority?: number | undefined;
+  /**
+   * Allow the audited retention purge: `delete` / `deleteMany` with
+   * `{ mode: 'hard', retentionPurge: { reason, actor? } }` (and
+   * `purgeByFilter` / `purgeByField` with `retentionPurge`) pass the fence,
+   * emitting `after:append-only-purge`. Default `false`: the option is
+   * refused (403 `RETENTION_PURGE_DISABLED`).
+   */
+  allowPurge?: boolean | undefined;
+  /**
+   * Allow `archiveByFilter(filter, sink, { retentionPurge })` to delete the rows its
+   * sink acknowledged, and nothing else: a retentionPurge delete without the run's
+   * attestation is still refused. Audited via `after:append-only-purge` with
+   * `archived: true`. Implied by `allowPurge`. Default `false`.
+   */
+  allowArchive?: boolean | undefined;
 }
+/** Payload of `after:append-only-purge`: one per successful purge call. */
+type AppendOnlyPurgeEvent = RetentionPurgeEvent;
 declare function appendOnlyPlugin(options?: AppendOnlyPluginOptions): Plugin;
-//#endregion
-//#region src/plugins/audit-log.plugin.d.ts
 declare function auditLogPlugin(logger: Logger): Plugin;
-//#endregion
-//#region src/plugins/batch-operations.plugin.d.ts
 /** Options accepted by `repo.bulkWrite`. Plugin context may ride alongside. */
 interface BulkWriteOptions {
   /** Stop at the first failure. Default `true`, matching the driver. */
@@ -123,6 +134,8 @@ interface BulkWriteOptions {
   comment?: unknown;
   let?: Record<string, unknown>;
   ignoreUndefined?: boolean;
+  /** Server-side time bound for the write. */
+  maxTimeMS?: number;
   /** Plugin context (tenant id, actor, ...) - spread into the op context. */
   [key: string]: unknown;
 }
@@ -144,19 +157,15 @@ interface BatchOperationsMethods {
    * ]);
    * console.log(result.insertedCount, result.modifiedCount, result.deletedCount);
    */
-  bulkWrite(operations: Record<string, unknown>[], options?: {
+  bulkWrite(operations: readonly Record<string, unknown>[], options?: {
     session?: unknown;
     ordered?: boolean;
   }): Promise<BulkWriteResult>;
 }
-//#endregion
-//#region src/plugins/cascade.plugin.d.ts
 /**
  * Cascade delete plugin.
  */
 declare function cascadePlugin(options: CascadeOptions): Plugin;
-//#endregion
-//#region src/plugins/elastic.plugin.d.ts
 interface ElasticSearchOptions {
   /** Elasticsearch or OpenSearch client instance */
   client: any;
@@ -166,8 +175,6 @@ interface ElasticSearchOptions {
   idField?: string;
 }
 declare function elasticSearchPlugin(options: ElasticSearchOptions): Plugin;
-//#endregion
-//#region src/plugins/field-filter.plugin.d.ts
 /**
  * Field filter plugin that restricts fields based on user context
  *
@@ -181,8 +188,6 @@ declare function elasticSearchPlugin(options: ElasticSearchOptions): Plugin;
  * const repo = new Repository(Model, [fieldFilterPlugin(fieldPreset)]);
  */
 declare function fieldFilterPlugin(fieldPreset: FieldPreset): Plugin;
-//#endregion
-//#region src/plugins/idempotency-store.plugin.d.ts
 interface IdempotencyStorePluginOptions {
   /** Field carrying the deterministic operation key. @default `'key'` */
   keyField?: string;
@@ -323,8 +328,6 @@ interface IdempotencyStoreMethods<TProgress = Record<string, unknown>, TResult =
  * failures, lapsed-claim sweeps). Removed in mongokit 4.
  */
 declare function idempotencyStorePlugin(options?: IdempotencyStorePluginOptions): Plugin;
-//#endregion
-//#region src/plugins/immutable-states.plugin.d.ts
 /** The slice of a `before:claim` context `allowClaim` predicates see. */
 interface ImmutableClaimView {
   id: unknown;
@@ -356,6 +359,20 @@ interface ImmutableStatesPluginOptions {
    * state — keep the predicate a strict fingerprint.
    */
   allowClaim?: ((view: ImmutableClaimView) => boolean) | undefined;
+  /**
+   * Allow the audited retention purge: `delete` / `deleteMany` with
+   * `{ mode: 'hard', retentionPurge: { reason, actor? } }` (and
+   * `purgeByFilter` / `purgeByField` with `retentionPurge`) may remove frozen
+   * rows, emitting `after:immutable-states-purge`. Default `false`: the
+   * option is refused (403 `RETENTION_PURGE_DISABLED`).
+   */
+  allowPurge?: boolean | undefined;
+  /**
+   * Allow `archiveByFilter(filter, sink, { retentionPurge })` to delete frozen rows its
+   * sink acknowledged, and nothing else (see `appendOnlyPlugin`'s `allowArchive`).
+   * Implied by `allowPurge`. Default `false`.
+   */
+  allowArchive?: boolean | undefined;
   /** Domain error to throw. Default: 403 `IMMUTABLE_STATE_VIOLATION`. */
   errorFactory?: ((ctx: {
     id: unknown;
@@ -363,9 +380,14 @@ interface ImmutableStatesPluginOptions {
     state?: string | undefined;
   }) => Error) | undefined;
 }
+/** Per-call purge request (`options.retentionPurge`). */
+type ImmutablePurgeRequest = RetentionPurgeRequest;
+/** Payload of `after:immutable-states-purge`: one per successful purge call. */
+interface ImmutablePurgeEvent extends RetentionPurgeEvent {
+  /** The frozen states configured on the plugin. */
+  states: readonly string[];
+}
 declare function immutableStatesPlugin(options: ImmutableStatesPluginOptions): Plugin;
-//#endregion
-//#region src/plugins/lease.plugin.d.ts
 interface LeasePluginOptions {
   /** Field carrying the row's status. @default `'status'` */
   statusField?: string;
@@ -381,7 +403,57 @@ interface LeasePluginOptions {
   doneStatus?: string;
   /** Sort fields used to pick the FIFO winner from the lease pool. @default `{ createdAt: 1 }` */
   sort?: Record<string, 1 | -1>;
+  /**
+   * Clock used by `lease` / `extend` / `release` for both the CAS
+   * comparison and the new expiry. A per-call `now` wins over it.
+   * Inject one to drive lease expiry from a test or a host `Clock`
+   * port. @default `() => new Date()`
+   */
+  nowFn?: () => Date;
+  /**
+   * Statuses whose expired lease `lease()` may recover. Only rows in
+   * one of these statuses AND with `leaseExpiresAt < now` are dead
+   * leases; a row in any other status is never re-leased, whatever its
+   * lease field says (a cancelled row with a stale expiry stays
+   * cancelled). @default `[processingStatus]`
+   */
+  deadLeaseStatuses?: readonly string[];
+  /**
+   * Optional attempts counter. When set, every successful `lease()`
+   * (first claim and dead-lease recovery alike) applies
+   * `$inc: { [attemptsField]: 1 }`. Off by default.
+   */
+  attemptsField?: string;
+  /**
+   * Cap on `attemptsField`. A row whose counter is already
+   * `>= maxAttempts` is not leasable; a row missing the field is.
+   * Exhausted rows stay where they are until `reapExhausted()` moves
+   * them to `exhaustedStatus` (or the host sweeps them itself).
+   * Requires `attemptsField` (throws at construction).
+   */
+  maxAttempts?: number;
+  /**
+   * Terminal status `reapExhausted()` moves an exhausted row to (e.g.
+   * `'failed'`). Requires `maxAttempts`; must differ from
+   * `pendingStatus`, `processingStatus` and every `deadLeaseStatuses`
+   * entry (throws at construction). Without it `reapExhausted()` needs
+   * a per-call `status`.
+   */
+  exhaustedStatus?: string;
+  /** Field `reapExhausted()` stamps with the reap time (e.g. `'failedAt'`). Off by default. */
+  exhaustedAtField?: string;
+  /**
+   * Extra predicate ANDed into the PENDING arm only, so not-yet-due rows
+   * wait while a dead lease is still recovered. The object form is
+   * STATIC (built once); for a time-relative predicate pass the function
+   * form, called per `lease()` with the resolved `now` (per-call `now`,
+   * else `nowFn()`): `pendingFilter: (now) => ({ dueAt: { $lte: now } })`.
+   * A per-call `pendingFilter` replaces this one.
+   */
+  pendingFilter?: LeasePendingFilter;
 }
+/** Static pending-arm predicate, or a builder called with the claim's `now`. */
+type LeasePendingFilter = Record<string, unknown> | ((now: Date) => Record<string, unknown>);
 /**
  * Methods contributed by `leasePlugin()`. Use as a type assertion when
  * constructing the repo so call sites get autocomplete:
@@ -397,9 +469,18 @@ interface LeasePluginOptions {
 interface LeaseMethods<TDoc> {
   /**
    * Atomically claim the next available row. Matches rows that are
-   * either in `pendingStatus` OR have an expired `leaseExpiresAt` (dead
-   * lease recovery). Sets status to `processingStatus`, stamps
-   * `leasedBy`, and pushes `leaseExpiresAt = now + leaseFor`.
+   * either in `pendingStatus` (AND `pendingFilter`, when given) OR in a
+   * `deadLeaseStatuses` status with an expired `leaseExpiresAt` (dead
+   * lease recovery). The caller's `filter` is kept as given (its own
+   * `$or` included) and the claim condition is ANDed beside it. Sets
+   * status to `processingStatus`, stamps `leasedBy`, pushes
+   * `leaseExpiresAt = now + leaseFor`, and bumps `attemptsField` when
+   * configured.
+   *
+   * `leasedBy` is the fencing token for `extend` / `release`: make it
+   * unique per claim (e.g. `${instanceId}:${randomUUID()}`). A worker
+   * that reuses one id could otherwise finalise a stale run after its
+   * own lapsed lease was re-leased under the same id.
    *
    * @returns The leased doc, or `null` when no row matches.
    */
@@ -407,17 +488,24 @@ interface LeaseMethods<TDoc> {
     filter?: Record<string, unknown>;
     leaseFor: number;
     leasedBy: string;
+    /** Clock reading for this call. @default plugin `nowFn()` */
+    now?: Date;
+    /** Replaces the plugin-level `pendingFilter` for this call. */
+    pendingFilter?: LeasePendingFilter;
     options?: Record<string, unknown>;
   }): Promise<TDoc | null>;
   /**
    * Push a held lease's expiry further. Only succeeds when the lease
-   * is still ours (`leasedBy === leasedBy && leaseExpiresAt > now`).
+   * is still ours (`leasedBy === leasedBy && leaseExpiresAt > now`) and
+   * the row is still in `processingStatus` (a row the host moved to a
+   * terminal status, e.g. cancelled, is not kept alive).
    * Returns `null` if the lease was lost — caller should drop the
    * work, since someone else has already started replaying it.
    */
   extend(id: string | ObjectId, opts: {
     leasedBy: string;
     leaseFor: number;
+    now?: Date;
     options?: Record<string, unknown>;
   }): Promise<TDoc | null>;
   /**
@@ -434,17 +522,48 @@ interface LeaseMethods<TDoc> {
    * `lease()` predicate) skip this row.
    *
    * Returns the released doc, or `null` when the CAS lost (lease
-   * expired / held by another worker / row gone).
+   * expired / held by another worker / row gone / row no longer in
+   * `processingStatus`, e.g. the host cancelled it mid-run).
    */
   release(id: string | ObjectId, opts: {
     leasedBy: string;
     finalStatus?: string;
+    now?: Date;
     options?: Record<string, unknown>;
   }): Promise<TDoc | null>;
+  /**
+   * Move every EXHAUSTED row to `exhaustedStatus` and return the moved
+   * rows (after the move), so the host only audits and alerts. A row is
+   * exhausted when `lease()` would claim it but for the attempts cap:
+   * `attemptsField >= maxAttempts` AND either pending (and passing
+   * `pendingFilter`) or in a `deadLeaseStatuses` status whose lease
+   * lapsed (`leaseExpiresAt < now`). A row whose lease is still live is
+   * left alone: its holder may still release it.
+   *
+   * Each move is a compare-and-set on that same condition, so two
+   * reapers never both return a row, and a row is returned once: once
+   * moved it no longer matches. Clears `leasedBy` / `leaseExpiresAt`
+   * and stamps `exhaustedAtField` with `now` when configured. The
+   * caller's `filter` is ANDed in as with `lease()`. Requires
+   * `maxAttempts`; reads at most `limit` rows (default 100) in `sort`
+   * order, so call it again until it returns `[]`. A batch shorter than
+   * `limit` does not mean none are left: a concurrent reaper may have
+   * moved some of the rows read (and keeps draining them).
+   */
+  reapExhausted(opts?: {
+    filter?: Record<string, unknown>;
+    /** Clock reading for this call. @default plugin `nowFn()` */
+    now?: Date;
+    /** Rows read per call. @default 100 */
+    limit?: number;
+    /** Replaces the plugin-level `exhaustedStatus` for this call. */
+    status?: string;
+    /** Replaces the plugin-level `pendingFilter` for this call. */
+    pendingFilter?: LeasePendingFilter;
+    options?: Record<string, unknown>;
+  }): Promise<TDoc[]>;
 }
 declare function leasePlugin(options?: LeasePluginOptions): Plugin;
-//#endregion
-//#region src/plugins/method-registry.plugin.d.ts
 /**
  * Extended repository interface with method registry
  */
@@ -457,8 +576,6 @@ interface MethodRegistryRepository extends RepositoryInstance {
  * Method registry plugin that enables dynamic method registration
  */
 declare function methodRegistryPlugin(): Plugin;
-//#endregion
-//#region src/plugins/mongo-operations.plugin.d.ts
 /**
  * MongoDB operations plugin
  *
@@ -689,8 +806,6 @@ interface MongoOperationsMethods<TDoc> {
    */
   incrementIfBelow(id: string | ObjectId, field: string, ceiling: number, by?: number, options?: Record<string, unknown>): Promise<TDoc | null>;
 }
-//#endregion
-//#region src/plugins/observability.plugin.d.ts
 interface OperationMetric {
   /** Operation name (e.g., 'create', 'getAll', 'update') */
   operation: string;
@@ -718,8 +833,6 @@ interface ObservabilityOptions {
   slowThresholdMs?: number;
 }
 declare function observabilityPlugin(options: ObservabilityOptions): Plugin;
-//#endregion
-//#region src/plugins/search-keys.plugin.d.ts
 interface SearchKeysPluginOptions {
   /** Source fields (dotted paths allowed; string, number, or arrays of them). */
   fields: readonly string[];
@@ -727,8 +840,6 @@ interface SearchKeysPluginOptions {
   keysField?: string;
 }
 declare function searchKeysPlugin(options: SearchKeysPluginOptions): Plugin;
-//#endregion
-//#region src/plugins/soft-delete.plugin.d.ts
 /**
  * Soft delete plugin
  *
@@ -820,8 +931,6 @@ interface SoftDeleteMethods<TDoc> {
     session?: unknown;
   }): Promise<OffsetPaginationResult<TDoc>>;
 }
-//#endregion
-//#region src/plugins/subdocument.plugin.d.ts
 /**
  * Subdocument plugin for managing nested arrays
  *
@@ -902,8 +1011,6 @@ interface SubdocumentMethods<TDoc> {
    */
   deleteSubdocument(parentId: string | ObjectId, arrayPath: string, subId: string | ObjectId, options?: Record<string, unknown>): Promise<TDoc>;
 }
-//#endregion
-//#region src/plugins/tenant-context.d.ts
 interface TenantStore {
   tenantId: string | undefined;
   [key: string]: unknown;
@@ -924,8 +1031,6 @@ interface TenantContext {
   readonly storage: AsyncLocalStorage<TenantStore>;
 }
 declare function createTenantContext(): TenantContext;
-//#endregion
-//#region src/plugins/timestamp.plugin.d.ts
 /**
  * Timestamp plugin that auto-injects timestamps
  *
@@ -933,8 +1038,6 @@ declare function createTenantContext(): TenantContext;
  * const repo = new Repository(Model, [timestampPlugin()]);
  */
 declare function timestampPlugin(): Plugin;
-//#endregion
-//#region src/plugins/validation-chain.plugin.d.ts
 type OperationType = 'create' | 'createMany' | 'update' | 'findOneAndUpdate' | 'delete';
 /**
  * Validation chain plugin
@@ -972,5 +1075,4 @@ declare function immutableField(field: string): ValidatorDefinition;
  * Ensure field value is unique
  */
 declare function uniqueField(field: string, errorMessage?: string): ValidatorDefinition;
-//#endregion
-export { immutableStatesPlugin as A, BulkWriteOptions as B, MethodRegistryRepository as C, leasePlugin as D, LeasePluginOptions as E, fieldFilterPlugin as F, appendOnlyPlugin as G, batchOperationsPlugin as H, ElasticSearchOptions as I, AggregateHelpersMethods as K, elasticSearchPlugin as L, IdempotencyStoreMethods as M, IdempotencyStorePluginOptions as N, ImmutableClaimView as O, idempotencyStorePlugin as P, cascadePlugin as R, mongoOperationsPlugin as S, LeaseMethods as T, auditLogPlugin as U, BulkWriteResult as V, AppendOnlyPluginOptions as W, searchKeysPlugin as _, requireField as a, observabilityPlugin as b, timestampPlugin as c, createTenantContext as d, SubdocumentMethods as f, SearchKeysPluginOptions as g, softDeletePlugin as h, immutableField as i, IdempotencyClaim as j, ImmutableStatesPluginOptions as k, TenantContext as l, SoftDeleteMethods as m, autoInject as n, uniqueField as o, subdocumentPlugin as p, aggregateHelpersPlugin as q, blockIf as r, validationChainPlugin as s, OperationType as t, TenantStore as u, ObservabilityOptions as v, methodRegistryPlugin as w, MongoOperationsMethods as x, OperationMetric as y, BatchOperationsMethods as z };
+export { ImmutablePurgeEvent as A, elasticSearchPlugin as B, MethodRegistryRepository as C, LeasePluginOptions as D, LeasePendingFilter as E, IdempotencyStoreMethods as F, batchOperationsPlugin as G, BatchOperationsMethods as H, IdempotencyStorePluginOptions as I, AppendOnlyPurgeEvent as J, auditLogPlugin as K, idempotencyStorePlugin as L, ImmutableStatesPluginOptions as M, immutableStatesPlugin as N, leasePlugin as O, IdempotencyClaim as P, fieldFilterPlugin as R, mongoOperationsPlugin as S, LeaseMethods as T, BulkWriteOptions as U, cascadePlugin as V, BulkWriteResult as W, AggregateHelpersMethods as X, appendOnlyPlugin as Y, aggregateHelpersPlugin as Z, searchKeysPlugin as _, requireField as a, observabilityPlugin as b, timestampPlugin as c, createTenantContext as d, SubdocumentMethods as f, SearchKeysPluginOptions as g, softDeletePlugin as h, immutableField as i, ImmutablePurgeRequest as j, ImmutableClaimView as k, TenantContext as l, SoftDeleteMethods as m, autoInject as n, uniqueField as o, subdocumentPlugin as p, AppendOnlyPluginOptions as q, blockIf as r, validationChainPlugin as s, OperationType as t, TenantStore as u, ObservabilityOptions as v, methodRegistryPlugin as w, MongoOperationsMethods as x, OperationMetric as y, ElasticSearchOptions as z };