@classytic/mongokit 3.38.1 → 3.40.0

package/dist/{Repository-BdSkQ8vc.d.mts → Repository-CR8Y9g2E.d.mts}

@@ -1,8 +1,7 @@
-import { _ as UpdateOptions, a as CreateOptions, b as LookupOptions, c as FindOneAndUpdateOptions, d as LookupPopulateResult, g as UpdateManyResult, h as SessionOptions, m as ReadOptions, o as DeleteManyResult, p as OperationOptions, r as CacheableOptions, s as DeleteResult, t as AggregateOptions, u as LookupPopulateOptions, v as WithTransactionOptions, y as LookupBuilder } from "./operations-DZodvjC-.mjs";
-import { a as PopulateSpec, i as ObjectId, l as SortSpec$1, o as ReadPreferenceType, s as SelectSpec } from "./core-62oo3N1C.mjs";
-import { c as PaginationConfig, r as CollationOptions, t as AggregatePaginationOptions } from "./pagination-jSUdrACK.mjs";
-import { _ as RepositoryOptions, d as PluginType, f as PrioritizedHook, o as Middleware, p as RepositoryContext } from "./repository-H_ffGgpE.mjs";
-import { t as PaginationEngine } from "./PaginationEngine-CBS1XGzp.mjs";
+import { _ as UpdateOptions, a as CreateOptions, b as LookupOptions, c as FindOneAndUpdateOptions, d as LookupPopulateResult, g as UpdateManyResult, h as SessionOptions, m as ReadOptions, o as DeleteManyResult, p as OperationOptions, r as CacheableOptions, s as DeleteResult, t as AggregateOptions, u as LookupPopulateOptions, v as WithTransactionOptions, y as LookupBuilder } from "./operations-CrRIoc8Z.mjs";
+import { _ as PopulateSpec, g as ObjectId, i as CountStrategy, r as CollationOptions, t as AggregatePaginationOptions, u as PaginationConfig, v as ReadPreferenceType, x as SortSpec$1, y as SelectSpec } from "./pagination-BpIv2bdS.mjs";
+import { _ as RepositoryOptions, d as PluginType, f as PrioritizedHook, o as Middleware, p as RepositoryContext } from "./repository-odl03582.mjs";
+import { t as PaginationEngine } from "./PaginationEngine-D-P19Y9m.mjs";
 import { AggPaginationRequest, AggRequest, AggResult, ArchiveOptions, ArchiveResult, ArchiveSink, ChangeEvent, FilterInput, KeysetAggPaginationResult, QueryOptions, RepoCapabilities, RepositoryBase, TenantPurgeOptions, TenantPurgeResult, TenantPurgeStrategy, WatchOptions } from "@classytic/repo-core/repository";
 import { ClientSession, Expression, Model, PipelineStage, PopulateOptions } from "mongoose";
 import { Filter } from "@classytic/repo-core/filter";
@@ -520,6 +519,37 @@ interface TransitionMachine {
   readonly name: string;
   assertTransition(entityId: string, from: string, to: string): void;
 }
+/** `Repository.getAll` parameters. */
+type GetAllParams = {
+  filters?: Record<string, unknown>;
+  sort?: SortSpec$1 | string;
+  cursor?: string;
+  after?: string;
+  /** Cursor for the PREVIOUS page. Mutually exclusive with `after`/`cursor`. */
+  before?: string;
+  page?: number;
+  pagination?: {
+    page?: number;
+    limit?: number;
+  };
+  limit?: number;
+  search?: string;
+  mode?: 'offset' | 'keyset';
+  hint?: string | Record<string, 1 | -1>;
+  maxTimeMS?: number;
+  countStrategy?: CountStrategy;
+  /** Ceiling for `countStrategy: 'capped'`. */
+  countLimit?: number;
+  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;
+};
 declare class Repository<TDoc = unknown> extends RepositoryBase {
   /**
    * Cache handle ATTACHED BY the unified cache plugin at wiring time —
@@ -580,6 +610,18 @@ declare class Repository<TDoc = unknown> extends RepositoryBase {
    * the `Middleware<TDoc>` type for the protocol.
    */
   private readonly _middlewares;
+  /**
+   * Shard-key guard built once from `options.distribution`; `undefined`
+   * when not configured so the per-op check is a single falsy test.
+   */
+  private readonly _checkDistribution;
+  /**
+   * Whether id-addressed verbs are guarded too — true unless the
+   * distribution key IS the id field, where an `_id` match is genuinely
+   * routed and guarding would flag every by-id call. See
+   * {@link ID_ADDRESSED_OPERATIONS}.
+   */
+  private readonly _guardIdAddressed;
   constructor(Model: Model<TDoc, any, any, any>, plugins?: PluginType[], paginationConfig?: PaginationConfig, options?: RepositoryOptions);
   /**
    * Live read-through view of the hook engine's listener registry.
@@ -860,8 +902,12 @@ declare class Repository<TDoc = unknown> extends RepositoryBase {
    *     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.
+   *   - Every yielded event carries `resumeToken` (the change document's
+   *     `_id`). Persist the last one you finished processing and pass it
+   *     back as `options.resumeAfter` — or `options.startAfter` to also
+   *     step past an invalidate event — for at-least-once consumption
+   *     across restarts. Setting both is rejected up front (Mongo forbids
+   *     the combination; the driver error is far less legible).
    *
    * Context keys for policy plugins (`organizationId`, `bypassTenant`,
    * `includeDeleted`, ...) ride the options bag at runtime — same as every
@@ -901,32 +947,19 @@ declare class Repository<TDoc = unknown> extends RepositoryBase {
    * // Skip cache for fresh data
    * await repo.getAll({ filters: { status: 'active' } }, { skipCache: true });
    */
-  getAll(params?: {
-    filters?: Record<string, unknown>;
-    sort?: SortSpec$1 | string;
-    cursor?: string;
-    after?: string;
-    page?: number;
-    pagination?: {
-      page?: number;
-      limit?: number;
-    };
-    limit?: number;
-    search?: string;
-    mode?: 'offset' | 'keyset';
-    hint?: string | Record<string, 1 | -1>;
-    maxTimeMS?: number;
-    countStrategy?: 'exact' | 'estimated' | 'none';
-    readPreference?: ReadPreferenceType;
-    /** Advanced populate options (from QueryParser or Arc's BaseController) */
-    populateOptions?: PopulateOptions[];
-    /** Collation for locale-aware string comparison */
-    collation?: CollationOptions;
-    /** Lookup configurations for $lookup joins (from QueryParser or manual) */
-    lookups?: LookupOptions[];
-    /** Skip pagination entirely — returns raw TDoc[] (same as findAll) */
-    noPagination?: boolean;
-  }, options?: CacheableOptions): Promise<OffsetPaginationResult<TDoc> | KeysetPaginationResult<TDoc> | TDoc[]>;
+  /** An explicit `mode` (or `noPagination`) decides the envelope, so the result type follows it. */
+  getAll(params: GetAllParams & {
+    mode: 'offset';
+    noPagination?: false;
+  }, options?: CacheableOptions): Promise<OffsetPaginationResult<TDoc>>;
+  getAll(params: GetAllParams & {
+    mode: 'keyset';
+    noPagination?: false;
+  }, options?: CacheableOptions): Promise<KeysetPaginationResult<TDoc>>;
+  getAll(params: GetAllParams & {
+    noPagination: true;
+  }, options?: CacheableOptions): Promise<TDoc[]>;
+  getAll(params?: GetAllParams, options?: CacheableOptions): Promise<OffsetPaginationResult<TDoc> | KeysetPaginationResult<TDoc> | TDoc[]>;
   /**
    * Atomic "look up by filter, insert `data` if missing, return the doc."
    *
@@ -1249,6 +1282,11 @@ declare class Repository<TDoc = unknown> extends RepositoryBase {
   }, patch?: Record<string, unknown>, options?: SessionOptions & {
     idField?: string;
     upsert?: boolean;
+    /**
+     * The document as the caller just read it in this session. Hooks' `loadTarget()`
+     * returns it instead of reading again. Pass only a read taken in the same session.
+     */
+    target?: Record<string, unknown>;
   }): Promise<TDoc | null>;
   /**
    * State-machine-backed CAS transition with status history — the
@@ -1782,6 +1820,22 @@ declare class Repository<TDoc = unknown> extends RepositoryBase {
    * 4. DEFAULT (500) — user-registered hooks
    */
   _buildContext(operation: string, options: Record<string, unknown> | object): Promise<RepositoryContext>;
+  /**
+   * `memo` and (for an id-addressed op) `loadTarget` — attached before the before-hooks
+   * run so every hook of one operation shares one read. A caller that has just read the
+   * document in the same session passes it as `target`, and nothing is read at all.
+   */
+  private _sharedReadSeams;
+  /**
+   * Feed the resolved filter of a guarded verb to the distribution guard.
+   * The slot follows `OP_REGISTRY[op].policyKey` (`query` vs `filters`);
+   * the portable aggregate verbs ALSO carry the caller's filter on
+   * `aggRequest.filter` (merged into the pipeline later by
+   * `_injectPolicyScopeIntoAgg`), and the kit-native pipeline verbs may
+   * carry it as leading `$match` stages — both are folded in so a key the
+   * caller did supply is never reported missing.
+   */
+  private _guardDistribution;
   /**
    * Walk the well-known filter-carrying keys (`query`, `filters`,
    * `having`) and route any Filter IR through `compileFilterToMongo`.
@@ -1796,6 +1850,9 @@ declare class Repository<TDoc = unknown> extends RepositoryBase {
   private _resolveSort;
   /**
    * Detect whether to use keyset (cursor) or offset (page) pagination.
+   * Precedence: explicit `mode` → `page` (offset) → `after` (keyset) →
+   * `PaginationConfig.defaultMode` → the sort heuristic (a non-default
+   * sort with no page means the caller wants a cursor).
    */
   private _detectPaginationMode;
   /**
@@ -1866,7 +1923,22 @@ declare class Repository<TDoc = unknown> extends RepositoryBase {
    * `errorLabels` exactly as we received it. The caller still sees a
    * thrown error — only the wrapping layer is skipped.
    */
+  /**
+   * Translate a driver error into the repository's error contract, WITHOUT
+   * losing structured diagnostics an action attached to it.
+   *
+   * The translation replaces the object — an E11000 becomes a 409 — so any
+   * property a caller was meant to read went with it. `createMany` attaches a
+   * `partial` report naming which documents landed, and it arrived nowhere:
+   * the report existed, the test for it failed, and the only evidence was the
+   * absence.
+   *
+   * Carried explicitly rather than by copying every own-property, because the
+   * wrap is deliberate: the point is to hide driver internals, and a blanket
+   * copy would put them back.
+   */
   _handleError(error: Error): HttpError;
+  private _translateError;
 }
 //#endregion
-export { AggregationPlan as a, SortOrder as c, AggregationBuilder as i, SortSpec as l, Repository as n, GroupSpec as o, TransitionMachine as r, ProjectionSpec as s, HOOK_PRIORITY as t, VectorSearchOptions as u };
+export { AggregationBuilder as a, ProjectionSpec as c, VectorSearchOptions as d, TransitionMachine as i, SortOrder as l, HOOK_PRIORITY as n, AggregationPlan as o, Repository as r, GroupSpec as s, GetAllParams as t, SortSpec as u };

package/dist/actions/index.d.mts

@@ -1,2 +1,2 @@
-import { a as create_d_exports, i as delete_d_exports, n as update_d_exports, o as aggregate_d_exports, r as read_d_exports } from "../index-DKEql4cL.mjs";
+import { c as create_d_exports, i as delete_d_exports, n as update_d_exports, r as read_d_exports, u as aggregate_d_exports } from "../index-CmjNyulu.mjs";
 export { aggregate_d_exports as aggregate, create_d_exports as create, delete_d_exports as deleteActions, read_d_exports as read, update_d_exports as update };

package/dist/actions/index.mjs

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "../rolldown-runtime-D7D4PA-g.mjs";
-import { g as create_exports, i as update_exports, p as delete_exports, u as read_exports, v as aggregate_exports } from "../update-jSXp3nu3.mjs";
+import { S as create_exports, i as update_exports, m as aggregate_exports, p as delete_exports, u as read_exports } from "../update-DG0fCwRJ.mjs";
 //#region src/actions/index.ts
 var actions_exports = /* @__PURE__ */ __exportAll({
 	aggregate: () => aggregate_exports,

package/dist/adapter/index.d.mts

@@ -129,6 +129,27 @@ declare class MongooseAdapter<TDoc = unknown, TModelDoc = unknown> implements Da
    * `matchesRecordFilter` — one shared contract/IR across every kit; its
    * evaluator is id-coercion aware so a Mongo `ObjectId` `_id` matches its
    * string form. Arrow field: keeps its binding when passed by reference.
+   *
+   * The document is flattened to a plain record FIRST, and that step is the
+   * whole reason this is not a one-liner. The evaluator resolves field paths
+   * with `Object.hasOwn`, own-properties-only and deliberately so: it must not
+   * walk a prototype chain, or a crafted `{ 'constructor.x': … }` policy filter
+   * could match an inherited member. A HYDRATED Mongoose document keeps its
+   * values in `_doc` and exposes them through prototype getters, so it has no
+   * own `status`, no own `organizationId` — every path resolves to absent and
+   * the filter matches NOTHING. Fail-closed, so it does not leak; it denies.
+   *
+   * That turned any policy at all into a blanket 404 on every non-compound
+   * fetch (`getBySlug`, cache revalidation, the realtime feed) while the same
+   * policy worked perfectly on list/get, which filter at the DB. The asymmetry
+   * is what made it so hard to see: a resource reads fine until the day someone
+   * gives it a row-level policy, and then one route starts lying.
+   *
+   * Knowing that a Mongoose document is not a plain record is the MONGO kit's
+   * job, not the dialect-agnostic evaluator's, so the normalisation lives here.
+   * `toObject` rather than `toJSON`: it preserves `ObjectId` and `Date` values,
+   * which the evaluator compares by type. A `.lean()` result is already plain
+   * and passes through untouched.
    */
   readonly matchesFilter: (item: unknown, filters: Record<string, unknown>) => boolean;
   /**

package/dist/adapter/index.mjs

@@ -1,2 +1,2 @@
-import { n as createMongooseAdapter, r as isMongooseModel, t as MongooseAdapter } from "../adapter-Bfqz8yHE.mjs";
+import { n as createMongooseAdapter, r as isMongooseModel, t as MongooseAdapter } from "../adapter-BrVfPFSW.mjs";
 export { MongooseAdapter, createMongooseAdapter, isMongooseModel };

package/dist/{adapter-Bfqz8yHE.mjs → adapter-BrVfPFSW.mjs}

@@ -19,6 +19,29 @@ const REQUIRED_REPO_METHODS = [
 	"update",
 	"delete"
 ];
+/**
+* A Mongoose document as a plain record, for anything that reads fields directly.
+*
+* Hydrated documents hold their values in `_doc` and surface them through prototype getters, so
+* `Object.hasOwn(doc, 'status')` is FALSE even though `doc.status` reads fine. Any consumer that
+* refuses to walk the prototype chain — as a prototype-pollution-safe field resolver must — sees
+* an empty document. See `matchesFilter` for what that cost us.
+*
+* `toObject` over `toJSON`: it keeps `ObjectId` and `Date` as values rather than stringifying
+* them, and callers here compare by type. Anything already plain (a `.lean()` result, a POJO) is
+* returned untouched, and a `toObject` that throws degrades to the original rather than taking
+* the caller down.
+*/
+function toPlainRecord(item) {
+	if (item === null || typeof item !== "object") return item;
+	const maybe = item;
+	if (typeof maybe.toObject !== "function") return item;
+	try {
+		return maybe.toObject();
+	} catch {
+		return item;
+	}
+}
 function describeValue(value) {
 	if (value === null) return "null";
 	if (value === void 0) return "undefined";
@@ -215,8 +238,29 @@ var MongooseAdapter = class {
 	* `matchesRecordFilter` — one shared contract/IR across every kit; its
 	* evaluator is id-coercion aware so a Mongo `ObjectId` `_id` matches its
 	* string form. Arrow field: keeps its binding when passed by reference.
+	*
+	* The document is flattened to a plain record FIRST, and that step is the
+	* whole reason this is not a one-liner. The evaluator resolves field paths
+	* with `Object.hasOwn`, own-properties-only and deliberately so: it must not
+	* walk a prototype chain, or a crafted `{ 'constructor.x': … }` policy filter
+	* could match an inherited member. A HYDRATED Mongoose document keeps its
+	* values in `_doc` and exposes them through prototype getters, so it has no
+	* own `status`, no own `organizationId` — every path resolves to absent and
+	* the filter matches NOTHING. Fail-closed, so it does not leak; it denies.
+	*
+	* That turned any policy at all into a blanket 404 on every non-compound
+	* fetch (`getBySlug`, cache revalidation, the realtime feed) while the same
+	* policy worked perfectly on list/get, which filter at the DB. The asymmetry
+	* is what made it so hard to see: a resource reads fine until the day someone
+	* gives it a row-level policy, and then one route starts lying.
+	*
+	* Knowing that a Mongoose document is not a plain record is the MONGO kit's
+	* job, not the dialect-agnostic evaluator's, so the normalisation lives here.
+	* `toObject` rather than `toJSON`: it preserves `ObjectId` and `Date` values,
+	* which the evaluator compares by type. A `.lean()` result is already plain
+	* and passes through untouched.
 	*/
-	matchesFilter = (item, filters) => matchesRecordFilter(item, filters);
+	matchesFilter = (item, filters) => matchesRecordFilter(toPlainRecord(item), filters);
 	/**
 	* No-op — mongokit's per-call resources (`watch()` change streams,
 	* `cursor()` iterators) are released by their own `AbortSignal` /

package/dist/ai/index.d.mts

@@ -1,4 +1,4 @@
-import { l as Plugin } from "../repository-H_ffGgpE.mjs";
+import { l as Plugin } from "../repository-odl03582.mjs";
 import { PipelineStage } from "mongoose";
 //#region src/ai/types.d.ts
 /** Supported similarity metrics for vector search */

package/dist/better-auth/index.mjs

@@ -1,5 +1,5 @@
-import { n as Repository } from "../Repository-Ck5x43wF.mjs";
-import { n as createMongooseAdapter } from "../adapter-Bfqz8yHE.mjs";
+import { n as Repository } from "../Repository-BMgPSkqZ.mjs";
+import { n as createMongooseAdapter } from "../adapter-BrVfPFSW.mjs";
 import { asReadOnlyRepo } from "@classytic/repo-core/repository";
 import { pluralizeBetterAuthCollection, resolveBetterAuthCollections } from "@classytic/repo-core/better-auth";
 //#region src/better-auth/index.ts

package/dist/{create-repository-B5EulQ31.mjs → create-repository-BzBUMvd1.mjs}

@@ -1,6 +1,6 @@
-import { n as Repository } from "./Repository-Ck5x43wF.mjs";
-import { a as customIdPlugin, f as auditTrailPlugin, i as multiTenantPlugin, m as auditLogPlugin, n as softDeletePlugin, t as timestampPlugin, u as cachePlugin } from "./timestamp.plugin-CBQukQzV.mjs";
-import { n as batchOperationsPlugin, t as methodRegistryPlugin } from "./method-registry.plugin-DblM7V6j.mjs";
+import { n as Repository } from "./Repository-BMgPSkqZ.mjs";
+import { b as auditLogPlugin, g as cachePlugin, i as multiTenantPlugin, l as customIdPlugin, n as softDeletePlugin, t as timestampPlugin, v as auditTrailPlugin } from "./timestamp.plugin-DF0gJB6p.mjs";
+import { n as batchOperationsPlugin, t as methodRegistryPlugin } from "./method-registry.plugin-C63pGn1d.mjs";
 //#region src/create-repository.ts
 function isLoggerAudit(value) {
 	const v = value;

package/dist/{create-repository-BU4x9Kb0.d.mts → create-repository-CAle1MSU.d.mts}

@@ -1,8 +1,8 @@
-import { c as PaginationConfig } from "./pagination-jSUdrACK.mjs";
-import { _ as RepositoryOptions, d as PluginType } from "./repository-H_ffGgpE.mjs";
-import { T as AuditTrailOptions, _ as RepositoryCachePluginOptions, i as CustomIdOptions, t as MultiTenantOptions } from "./multi-tenant.plugin-BwSvTirB.mjs";
-import { n as Repository } from "./Repository-BdSkQ8vc.mjs";
-import { i as Logger, o as SoftDeleteOptions } from "./plugin-options-DXnlKM3B.mjs";
+import { u as PaginationConfig } from "./pagination-BpIv2bdS.mjs";
+import { _ as RepositoryOptions, d as PluginType } from "./repository-odl03582.mjs";
+import { D as AuditTrailOptions, i as CustomIdOptions, t as MultiTenantOptions, y as RepositoryCachePluginOptions } from "./multi-tenant.plugin-CBgCo9im.mjs";
+import { r as Repository } from "./Repository-CR8Y9g2E.mjs";
+import { i as Logger, o as SoftDeleteOptions } from "./plugin-options-Zk46lD6F.mjs";
 import { Model } from "mongoose";
 //#region src/create-repository.d.ts
 /**

package/dist/idempotency/index.d.mts

@@ -0,0 +1,23 @@
+import { Connection, Model } from "mongoose";
+import { IdempotencyClaimStore } from "@classytic/repo-core/idempotency";
+//#region src/idempotency/index.d.ts
+interface IdempotencyModelOptions {
+  /** Collection name. Default `idempotency_claims`. */
+  collection?: string;
+  /** Mongoose model name. Default `IdempotencyClaim`. Must be unique per connection. */
+  modelName?: string;
+}
+interface IdempotencyStoreOptions {
+  /**
+   * How long a claim is kept after its last write before the TTL monitor removes it.
+   * Default 7 days. Size it to the longest a caller may retry — a retry after the claim
+   * is gone executes again. An offline till that syncs days later needs more.
+   */
+  retentionSeconds?: number;
+}
+/** Build (or return) the claims model on `connection`. Idempotent per connection. */
+declare function createIdempotencyModel(connection: Connection, options?: IdempotencyModelOptions): Model<Record<string, unknown>>;
+/** The store over a model from {@link createIdempotencyModel}. */
+declare function createIdempotencyStore(model: Model<Record<string, unknown>>, options?: IdempotencyStoreOptions): IdempotencyClaimStore;
+//#endregion
+export { IdempotencyModelOptions, IdempotencyStoreOptions, createIdempotencyModel, createIdempotencyStore };

package/dist/idempotency/index.mjs

@@ -0,0 +1,134 @@
+import { Schema } from "mongoose";
+import { identityKey } from "@classytic/repo-core/idempotency";
+//#region src/idempotency/index.ts
+/**
+* The mongo {@link IdempotencyClaimStore} — use this with `runIdempotent` from
+* `@classytic/repo-core/idempotency`; never keep a per-module claims table.
+*
+* ```ts
+* const store = createIdempotencyStore(createIdempotencyModel(connection));
+* const run = await runIdempotent({ store, identity, requestFingerprint, execute });
+* ```
+*
+* One document per identity, `_id` = `identityKey(identity)`, so "insert iff absent" is
+* the `_id` index and every compare-and-set is a single-document filter. Proven by
+* `runIdempotencyStoreConformance` (`@classytic/repo-core/testing`) in this package's tests.
+*/
+const DEFAULT_RETENTION_SECONDS = 604800;
+/** Build (or return) the claims model on `connection`. Idempotent per connection. */
+function createIdempotencyModel(connection, options = {}) {
+	const { collection = "idempotency_claims", modelName = "IdempotencyClaim" } = options;
+	const existing = connection.models[modelName];
+	if (existing) return existing;
+	const schema = new Schema({
+		_id: {
+			type: String,
+			required: true
+		},
+		identity: {
+			type: Schema.Types.Mixed,
+			required: true
+		},
+		requestFingerprint: {
+			type: String,
+			required: true
+		},
+		state: {
+			type: String,
+			enum: [
+				"in_flight",
+				"succeeded",
+				"failed"
+			],
+			required: true
+		},
+		leaseToken: {
+			type: String,
+			required: true
+		},
+		leaseExpiresAt: {
+			type: Date,
+			required: true
+		},
+		createdAt: {
+			type: Date,
+			required: true
+		},
+		completedAt: { type: Date },
+		result: { type: Schema.Types.Mixed },
+		attempts: {
+			type: Number,
+			required: true
+		},
+		progress: { type: Schema.Types.Mixed },
+		context: { type: Schema.Types.Mixed },
+		lastError: { type: String },
+		purgeAt: {
+			type: Date,
+			required: true
+		}
+	}, {
+		collection,
+		versionKey: false,
+		minimize: false
+	});
+	schema.index({ purgeAt: 1 }, {
+		expireAfterSeconds: 0,
+		name: "retention"
+	});
+	schema.index({
+		"identity.operation": 1,
+		state: 1,
+		leaseExpiresAt: 1
+	}, { name: "lapsed_sweep" });
+	return connection.model(modelName, schema);
+}
+/** The store over a model from {@link createIdempotencyModel}. */
+function createIdempotencyStore(model, options = {}) {
+	const retentionMs = (options.retentionSeconds ?? DEFAULT_RETENTION_SECONDS) * 1e3;
+	const claims = () => model.collection;
+	const toDoc = (claim) => ({
+		...claim,
+		_id: identityKey(claim.identity),
+		purgeAt: new Date(Date.now() + retentionMs)
+	});
+	/** The caller's transaction, so a claim commits or rolls back with the writes it describes. */
+	const withSession = (options) => options?.session ? { session: options.session } : {};
+	const ownedInFlight = (identity, leaseToken) => ({
+		_id: identityKey(identity),
+		state: "in_flight",
+		leaseToken
+	});
+	return {
+		async get(identity, options) {
+			const doc = await claims().findOne({ _id: identityKey(identity) }, withSession(options));
+			if (!doc) return null;
+			const { _id, purgeAt, ...claim } = doc;
+			return claim;
+		},
+		async insert(claim, options) {
+			try {
+				await claims().insertOne(toDoc(claim), withSession(options));
+				return true;
+			} catch (error) {
+				if (error.code === 11e3) return false;
+				throw error;
+			}
+		},
+		async swap(identity, expectedLeaseToken, next, options) {
+			return (await claims().replaceOne(ownedInFlight(identity, expectedLeaseToken), toDoc(next), withSession(options))).matchedCount === 1;
+		},
+		async release(identity, expectedLeaseToken, options) {
+			return (await claims().deleteOne(ownedInFlight(identity, expectedLeaseToken), withSession(options))).deletedCount === 1;
+		},
+		async listLapsed(operation, now, limit) {
+			return (await claims().find({
+				"identity.operation": operation,
+				state: "in_flight",
+				leaseExpiresAt: { $lte: now }
+			}).sort({ leaseExpiresAt: 1 }).limit(limit).toArray()).map(({ _id, purgeAt, ...claim }) => claim);
+		}
+	};
+}
+//#endregion
+export { createIdempotencyModel, createIdempotencyStore };

package/dist/{index-DKEql4cL.d.mts → index-CmjNyulu.d.mts}

@@ -1,5 +1,5 @@
-import { _ as UpdateOptions, a as CreateOptions, b as LookupOptions, c as FindOneAndUpdateOptions, f as MinMaxResult, g as UpdateManyResult, l as GroupResult, p as OperationOptions, s as DeleteResult } from "./operations-DZodvjC-.mjs";
-import { a as PopulateSpec, i as ObjectId, l as SortSpec, o as ReadPreferenceType, s as SelectSpec, t as AnyDocument } from "./core-62oo3N1C.mjs";
+import { _ as UpdateOptions, a as CreateOptions, b as LookupOptions, c as FindOneAndUpdateOptions, f as MinMaxResult, g as UpdateManyResult, l as GroupResult, p as OperationOptions, s as DeleteResult } from "./operations-CrRIoc8Z.mjs";
+import { _ as PopulateSpec, g as ObjectId, p as AnyDocument, v as ReadPreferenceType, x as SortSpec, y as SelectSpec } from "./pagination-BpIv2bdS.mjs";
 import { p as UpdateWithValidationResult } from "./type-utils-CLzRFtIA.mjs";
 import { Model, PipelineStage } from "mongoose";
 declare namespace aggregate_d_exports {
@@ -12,9 +12,18 @@ declare function aggregate<TResult = unknown>(Model: Model<any>, pipeline: Pipel
   session?: unknown;
 }): Promise<TResult[]>;
 /**
- * Aggregate with pagination using native MongoDB $facet
- * WARNING: $facet results must be <16MB. For larger results (limit >1000),
- * consider using Repository.aggregatePaginate() or splitting into separate queries.
+ * Aggregate with pagination.
+ *
+ * Page and count run as TWO concurrent pipelines rather than one `$facet`.
+ * `$facet` bundles every returned document plus the count into a SINGLE output
+ * document, and no stage may exceed 16MB — so a page of large documents failed
+ * with `BSONObjectTooLarge` instead of paginating, and the only defence was a
+ * warning above an arbitrary limit of 1000 that told the caller to go
+ * elsewhere. `$facet` also cannot use an index for the stages inside it.
+ *
+ * The trade: two reads, so a concurrent write between them can leave `total`
+ * a document out of step with `data` — the same trade `PaginationEngine`
+ * already makes on both its offset and aggregate paths.
  */
 declare function aggregatePaginate<TDoc = AnyDocument>(Model: Model<TDoc>, pipeline: PipelineStage[], options?: {
   page?: number;
@@ -91,14 +100,64 @@ declare function minMax(Model: Model<any>, field: string, query?: Record<string,
   session?: unknown;
 }): Promise<MinMaxResult>;
 declare namespace create_d_exports {
-  export { create, createDefault, createMany, upsert };
+  export { CreateManyFailure, CreateManyPartial, CreateManyPartialError, create, createDefault, createMany, isCreateManyPartialError, upsert };
 }
 /**
  * Create single document
  */
 declare function create<TDoc = AnyDocument>(Model: Model<TDoc>, data: Record<string, unknown>, options?: CreateOptions): Promise<TDoc>;
 /**
- * Create multiple documents
+ * One rejected input, keyed by its position in the array that was passed in.
+ *
+ * The index is the load-bearing part: it is the only way to tie a failure back
+ * to the caller's own record — the driver reports failures positionally, and a
+ * rejected document never comes back with an `_id` to match on.
+ */
+interface CreateManyFailure {
+  /** Position in the ORIGINAL `dataArray`. */
+  index: number;
+  /** The input that was rejected, as supplied. */
+  doc: Record<string, unknown>;
+  /** MongoDB error code, e.g. 11000 for a duplicate key. */
+  code?: number;
+  message: string;
+}
+/**
+ * What a partially-successful `createMany` actually did.
+ *
+ * Attached to the thrown error as `partial`. `createMany` still REJECTS — that
+ * is unchanged and deliberate — but the rejection now says which documents
+ * landed and which did not, instead of leaving the caller to dig through a
+ * driver error to find out.
+ */
+interface CreateManyPartial<TDoc = AnyDocument> {
+  /** Documents the server accepted. */
+  inserted: TDoc[];
+  /** Every rejected input, in input order. */
+  failed: CreateManyFailure[];
+}
+/** The error `createMany` throws when some documents landed and some did not. */
+type CreateManyPartialError<TDoc = AnyDocument> = Error & {
+  partial?: CreateManyPartial<TDoc>;
+};
+/** Narrow a caught error to one carrying a partial-write report. */
+declare function isCreateManyPartialError<TDoc = AnyDocument>(err: unknown): err is CreateManyPartialError<TDoc> & {
+  partial: CreateManyPartial<TDoc>;
+};
+/**
+ * Create multiple documents.
+ *
+ * **A rejection does NOT mean nothing was written.** Neither ordering does:
+ * `ordered: true` stops at the first failure and keeps everything before it,
+ * `ordered: false` keeps everything valid. Measured on a six-document batch
+ * with a conflict in the middle — ordered wrote 3, unordered wrote 5. Only a
+ * transaction gives all-or-nothing.
+ *
+ * So the rejection carries a `partial` report naming what landed and what did
+ * not, because the alternative is a caller retrying the whole batch and
+ * double-writing everything that had already succeeded. Use it to retry only
+ * `failed`, or to reconcile — and prefer a unique index or an idempotency key
+ * for anything that will be retried automatically.
  */
 declare function createMany<TDoc = AnyDocument>(Model: Model<TDoc>, dataArray: Record<string, unknown>[], options?: CreateOptions): Promise<TDoc[]>;
 /**
@@ -301,4 +360,4 @@ declare namespace index_d_exports {
   export { aggregate_d_exports as aggregate, create_d_exports as create, delete_d_exports as deleteActions, read_d_exports as read, update_d_exports as update };
 }
 //#endregion
-export { create_d_exports as a, delete_d_exports as i, update_d_exports as n, aggregate_d_exports as o, read_d_exports as r, index_d_exports as t };
+export { CreateManyFailure as a, create_d_exports as c, delete_d_exports as i, isCreateManyPartialError as l, update_d_exports as n, CreateManyPartial as o, read_d_exports as r, CreateManyPartialError as s, index_d_exports as t, aggregate_d_exports as u };