@classytic/mongokit 3.43.1 → 3.45.0

package/README.md

@@ -201,14 +201,17 @@ await orderRepo.withTransaction(async (txRepo) => {
 });
 ```
 
+To serialise writers on a row, the write must change it. An update that sets a field to the value it already has is a no-op: it takes no write lock, so two transactions doing it at the same instant never conflict. Write something that changes (for example `$inc: { writes: 1 }` on a gate or lease row).
+
 ### Time Bounds And Concerns (`queryDefaults`)
 
 ```ts
-// Boot: every command is bounded; the boot check fails without it (and without CSOT timeoutMS).
-await mongoose.connect(uri, { timeoutMS: 30_000 });
+// Boot: every command is bounded by a server-side maxTimeMS; the boot check fails without it.
+// Do not pass `timeoutMS` to mongoose.connect(): the MongoDB driver ignores it since 7.8 (CVE-2026-119179).
+await mongoose.connect(uri);
 configureQueryDefaults({ maxTimeMS: 5_000, writeConcern: { w: 'majority' } });
 configureAggregateDefaults({ maxTimeMs: 15_000 });
-assertQueryDefaultsConfigured(mongoose.connection);
+assertQueryDefaultsConfigured();
 
 // Per repository, and per call (per call always wins):
 const repo = new Repository(Order, plugins, {}, { queryDefaults: { comment: 'orders' } });
@@ -529,6 +532,18 @@ await assertQueryPlan(() => repo.getAll({ filters: { status: 'open' }, sort: { a
 });
 ```
 
+Reads are gated by default; pass `commands: ['findAndModify', 'update', 'delete']` to gate a write's match too.
+`explainCommands(run, { connection, commands?, collections?, verbosity? })` returns the raw explain of every
+command `run` sent (writes are explained, never re-run), for a plugin-built query such as a `leasePlugin` claim:
+
+```ts
+import { explainCommands } from '@classytic/mongokit/testkit';
+const { explains } = await explainCommands(() => jobs.lease({ leaseFor: 30_000, leasedBy }), {
+  connection, commands: ['findAndModify'], collections: ['jobs'],
+});
+explains[0].explain.executionStats; // what the claim examined
+```
+
 ## Kernel Conformance — `@classytic/mongokit/kernel-conformance`
 
 An **executable contract suite** for domain kernels built on `defineModels()`. A kernel that

package/dist/{PaginationEngine-DZnkbSrr.mjs → PaginationEngine-BRlLTQQz.mjs}

@@ -1,13 +1,13 @@
-import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
-import { n as warn } from "./logger-K7dPmu2U.mjs";
-import { t as createError } from "./error-BuByZwKU.mjs";
-import { i as applyToQuery, r as applyToAggregate, u as resolveQueryOptions } from "./query-defaults-BxUcSOoF.mjs";
+import { t as __exportAll } from "./rolldown-runtime-D8jQpDG7.mjs";
+import { l as resolveQueryOptions, n as applyToAggregate, r as applyToQuery } from "./query-defaults-DwvWUjZU.mjs";
+import { t as createError } from "./error-DjdmPLWO.mjs";
+import { n as warn } from "./logger-hbWOlj_X.mjs";
 import { calculateSkip, calculateTotalPages, shouldWarnDeepPagination, validateLimit, validatePage } from "./pagination/utils/limits.mjs";
 import mongoose from "mongoose";
 import { createTtlMemo } from "@classytic/repo-core/cache";
 import { createHash, createHmac, timingSafeEqual } from "node:crypto";
 import { CURSOR_ERROR_CODES } from "@classytic/repo-core/pagination";
-//#region src/pagination/utils/cursor-signing.ts
+// src/pagination/utils/cursor-signing.ts
 /**
 * HMAC signing for pagination cursors.
 *
@@ -122,8 +122,7 @@ function verifySignature(token, secrets) {
 	for (const key of secrets) if (matches(signature, sign(payload, key))) return payload;
 	throw new Error("Invalid cursor token: signature does not verify (tampered, or issued under a retired key)");
 }
-//#endregion
-//#region src/pagination/defaults.ts
+// src/pagination/defaults.ts
 /**
 * The policy lives on `globalThis` under a registered symbol, NOT in a module
 * `let`.
@@ -215,8 +214,7 @@ function define(target, key, explicit, fallback) {
 		get: () => explicit !== void 0 ? explicit : policy()[key] ?? fallback
 	});
 }
-//#endregion
-//#region src/pagination/utils/filter.ts
+// src/pagination/utils/filter.ts
 /**
 * Combine the caller's filters with the keyset position predicate.
 *
@@ -327,8 +325,7 @@ function buildKeysetFilter(baseFilters, sort, cursorValue, cursorId, cursorValue
 	if (orConditions.length === 0) return combine(baseFilters, { _id: { $in: [] } });
 	return combine(baseFilters, { $or: orConditions });
 }
-//#endregion
-//#region src/pagination/utils/guards.ts
+// src/pagination/utils/guards.ts
 /**
 * Pagination guards shared by every paged read: the deep-offset refusal, the unique `_id`
 * tiebreaker that makes a sort a total order, and the cursor SCOPE fingerprint — a hash of
@@ -446,8 +443,7 @@ function warnIfSortNotTotal(model, pipeline, warnFn) {
 	warnedSortSites.add(site);
 	warnFn(`[mongokit] aggregatePipelinePaginate on '${model}': the page sort is not provably total, so rows that tie can repeat or be skipped across pages. End the \$sort on a key unique per output row, then pass \`sortIsTotal: true\` (or sort on _id with no \$unwind/\$group/_id rewrite before the sort).`);
 }
-//#endregion
-//#region src/pagination/utils/cursor.ts
+// src/pagination/utils/cursor.ts
 /**
 * Cursor Utilities
 *
@@ -455,12 +451,8 @@ function warnIfSortNotTotal(model, pipeline, warnFn) {
 * Cursors are base64-encoded JSON containing position data and metadata.
 */
 var cursor_exports = /* @__PURE__ */ __exportAll({
-	decodeCursor: () => decodeCursor,
 	encodeCursor: () => encodeCursor,
-	readSortValue: () => readSortValue,
-	resolveCursorFilter: () => resolveCursorFilter,
-	validateCursorSort: () => validateCursorSort,
-	validateCursorVersion: () => validateCursorVersion
+	resolveCursorFilter: () => resolveCursorFilter
 });
 /**
 * Encodes document values and sort metadata into a base64 cursor token
@@ -655,8 +647,7 @@ function resolveCursorFilter(after, sort, cursorVersion, baseFilters, minCursorV
 	validateCursorSort(cursor.sort, sort);
 	return buildKeysetFilter(baseFilters, buildSort, cursor.value, cursor.id, cursor.values);
 }
-//#endregion
-//#region src/pagination/utils/index-hint.ts
+// src/pagination/utils/index-hint.ts
 /**
 * The only operators that give the query planner a *bounded equality* it can
 * lead an index with. Everything else (`$ne`, `$nin`, `$gt(e)`, `$lt(e)`,
@@ -789,12 +780,9 @@ function hasCompatibleKeysetIndex(indexes, filterFields, sort) {
 	}
 	return false;
 }
-//#endregion
-//#region src/pagination/utils/sort.ts
+// src/pagination/utils/sort.ts
 var sort_exports = /* @__PURE__ */ __exportAll({
 	getPrimaryField: () => getPrimaryField,
-	invertSort: () => invertSort,
-	normalizeSort: () => normalizeSort,
 	validateKeysetSort: () => validateKeysetSort
 });
 /**
@@ -882,8 +870,7 @@ function invertSort(sort) {
 function getPrimaryField(sort) {
 	return Object.keys(sort).find((k) => k !== "_id") || "_id";
 }
-//#endregion
-//#region src/pagination/PaginationEngine.ts
+// src/pagination/PaginationEngine.ts
 /**
 * Pagination Engine
 *
@@ -1353,5 +1340,4 @@ var PaginationEngine = class {
 		};
 	}
 };
-//#endregion
 export { resolveCursorSecrets as _, cursor_exports as a, PAGINATION_ERROR_CODES as c, withGroupTiebreak as d, withIdTiebreak as f, attachSignature as g, resetPaginationDefaults as h, validateKeysetSort as i, assertOffsetWithinCap as l, getPaginationDefaults as m, getPrimaryField as n, encodeCursor as o, configurePaginationDefaults as p, sort_exports as r, resolveCursorFilter as s, PaginationEngine as t, cursorScope as u, verifySignature as v };

package/dist/{PaginationEngine-CRHyuUtw.d.mts → PaginationEngine-BWb-c47a.d.mts}

@@ -1,8 +1,7 @@
-import { D as AnyDocument, c as MongokitPageExtras, f as CursorSecret, i as CountStrategy, l as OffsetPaginationOptions, s as KeysetPaginationOptions, t as AggregatePaginationOptions, u as PaginationConfig } from "./pagination-D6psses0.mjs";
+import { D as AnyDocument, c as MongokitPageExtras, f as CursorSecret, i as CountStrategy, l as OffsetPaginationOptions, s as KeysetPaginationOptions, t as AggregatePaginationOptions, u as PaginationConfig } from "./pagination-BAM9cA4N.mjs";
 import { Model } from "mongoose";
 import { TtlMemo } from "@classytic/repo-core/cache";
 import { AggregatePaginationResult, KeysetPaginationResult, OffsetPaginationResult } from "@classytic/repo-core/pagination";
-//#region src/pagination/PaginationEngine.d.ts
 /**
  * Internal pagination config with required values
  */
@@ -138,5 +137,4 @@ declare class PaginationEngine<TDoc = AnyDocument> {
    */
   aggregatePaginate(options?: AggregatePaginationOptions): Promise<AggregatePaginationResult<TDoc, MongokitPageExtras>>;
 }
-//#endregion
 export { PaginationEngine as n, CountMemoKey as t };

package/dist/{Repository-DnL4xk5w.d.mts → Repository-DJuRmBNx.d.mts}

@@ -1,7 +1,8 @@
-import { S as LookupOptions, _ as SessionOptions, b as WithTransactionOptions, c as DeleteResult, f as LookupPopulateOptions, g as ReadOptions, h as OperationOptions, i as CacheableOptions, l as FindOneAndUpdateOptions, n as AggregateOptions, o as CreateOptions, p as LookupPopulateResult, s as DeleteManyResult, t as AggregateCallOptions, u as GetByIdsOptions, v as UpdateManyResult, x as LookupBuilder, y as UpdateOptions } from "./operations-XiFgG5US.mjs";
-import { A as ObjectId, F as SortSpec$1, M as ReadPreferenceType, N as SelectSpec, c as MongokitPageExtras, i as CountStrategy, j as PopulateSpec, r as CollationOptions, t as AggregatePaginationOptions, u as PaginationConfig } from "./pagination-D6psses0.mjs";
-import { _ as RepositoryOptions, d as PluginType, f as PrioritizedHook, o as Middleware, p as RepositoryContext } from "./repository-MqAP409e.mjs";
-import { n as PaginationEngine } from "./PaginationEngine-CRHyuUtw.mjs";
+import { A as ObjectId, F as SortSpec$1, M as ReadPreferenceType, N as SelectSpec, c as MongokitPageExtras, i as CountStrategy, j as PopulateSpec, r as CollationOptions, t as AggregatePaginationOptions, u as PaginationConfig } from "./pagination-BAM9cA4N.mjs";
+import { r as RetentionPurgeRequest } from "./retention-purge-CCd_VXUf.mjs";
+import { n as PaginationEngine } from "./PaginationEngine-BWb-c47a.mjs";
+import { S as LookupOptions, _ as SessionOptions, b as WithTransactionOptions, c as DeleteResult, f as LookupPopulateOptions, g as ReadOptions, h as OperationOptions, i as CacheableOptions, l as FindOneAndUpdateOptions, n as AggregateOptions, o as CreateOptions, p as LookupPopulateResult, s as DeleteManyResult, t as AggregateCallOptions, u as GetByIdsOptions, v as UpdateManyResult, x as LookupBuilder, y as UpdateOptions } from "./operations-D6XsHx4e.mjs";
+import { _ as RepositoryOptions, d as PluginType, f as PrioritizedHook, o as Middleware, p as RepositoryContext } from "./repository-B0aFVgP2.mjs";
 import { AggPaginationRequest, AggRequest, AggResult, ArchiveOptions, ArchiveResult, ArchiveSink, BulkUpsertOptions, BulkUpsertResult, 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";
@@ -9,7 +10,13 @@ import { RepositoryCacheHandle } from "@classytic/repo-core/cache";
 import { HttpError } from "@classytic/repo-core/errors";
 import { UpdateInput } from "@classytic/repo-core/update";
 import { AggregatePaginationResult, KeysetPaginationResult, OffsetPaginationResult, OffsetPaginationResultCore } from "@classytic/repo-core/pagination";
-//#region src/query/AggregationBuilder.d.ts
+/**
+ * `purgeByFilter` / `purgeByField` options: repo-core's `TenantPurgeOptions`
+ * plus the audited `retentionPurge` (see `SessionOptions.retentionPurge`).
+ */
+type RetentionTenantPurgeOptions = TenantPurgeOptions & {
+  retentionPurge?: RetentionPurgeRequest | undefined;
+};
 /** Options for $vectorSearch stage (Atlas only) */
 interface VectorSearchOptions {
   /** Atlas Search index name */
@@ -475,8 +482,6 @@ declare class AggregationBuilder {
  *      .exec(Model)
  *    ```
  */
-//#endregion
-//#region src/Repository.d.ts
 /**
  * Plugin phase priorities (lower = runs first).
  *
@@ -865,7 +870,7 @@ declare class Repository<TDoc = unknown> extends RepositoryBase {
   }): Promise<string>;
   /**
    * Resumable keyset batches over `_id`: each batch is ONE bounded `find` (no long-lived server
-   * cursor, so no cursor timeout and no CSOT lifetime budget), memory is one batch, and every
+   * cursor, so no cursor timeout and a bound on every batch), memory is one batch, and every
    * batch carries a `checkpoint`. Pass a checkpoint back as `after` to resume: rows written
    * behind it are not revisited, rows ahead of it are reached. A checkpoint is bound to the
    * collection, the post-policy filter (tenant included) and is refused elsewhere.
@@ -1397,8 +1402,26 @@ declare class Repository<TDoc = unknown> extends RepositoryBase {
     history?: string | false;
     /** Timestamp for the history entry — default `new Date()`. */
     at?: Date;
+    /**
+     * When the row entered its current state (the caller's read).
+     * Adds `durationInPriorMs: max(0, occurredAt - priorAt)` to the
+     * history entry, the same field primitives' `appendStatus` writes,
+     * without a pre-read here. Pair it with a `where` (e.g.
+     * `{ updatedAt: current.updatedAt }`) or `options.target` so a write
+     * between the read and the claim makes the claim miss rather than
+     * record a stale duration. Requires history (400 with `history: false`).
+     */
+    priorAt?: Date;
+    /**
+     * Extra fields merged into the history entry. May not contain the
+     * reserved keys `status`, `occurredAt`, `by`, `note` or
+     * `durationInPriorMs` (400). Requires history.
+     */
+    historyExtra?: Record<string, unknown>;
   }, options?: SessionOptions & {
     idField?: string;
+    /** Forwarded to `claim()`: the caller's same-session read, pinned by version / `updatedAt`. */
+    target?: Record<string, unknown>;
   }): Promise<TDoc>;
   /**
    * Optimistic-concurrency CAS via a version stamp.
@@ -1566,7 +1589,7 @@ declare class Repository<TDoc = unknown> extends RepositoryBase {
    * + strategy writes). See [actions/purge.ts](./actions/purge.ts) for
    * the port implementation.
    */
-  purgeByField(field: string, value: unknown, strategy: TenantPurgeStrategy, options?: TenantPurgeOptions): Promise<TenantPurgeResult>;
+  purgeByField(field: string, value: unknown, strategy: TenantPurgeStrategy, options?: RetentionTenantPurgeOptions): Promise<TenantPurgeResult>;
   /**
    * Range/filter-scoped purge — see `StandardRepo.purgeByFilter` for the
    * cross-kit contract. The compliance primitive for "purge/anonymize a
@@ -1581,20 +1604,29 @@ declare class Repository<TDoc = unknown> extends RepositoryBase {
    * the same dual-dialect rule as `archiveByFilter` and every other verb.
    * See [actions/purge.ts](./actions/purge.ts) for the port.
    */
-  purgeByFilter(filter: Record<string, unknown> | Filter, strategy: TenantPurgeStrategy, options?: TenantPurgeOptions): Promise<TenantPurgeResult>;
+  purgeByFilter(filter: Record<string, unknown> | Filter, strategy: TenantPurgeStrategy, options?: RetentionTenantPurgeOptions): Promise<TenantPurgeResult>;
   /**
    * Chunked cold-storage extraction — see `StandardRepo.archiveByFilter`
    * for the cross-kit contract (write-before-delete, at-least-once,
    * duplicate-tolerant sinks). Mongokit composes the kit-agnostic
-   * `runChunkedArchive` orchestrator with `createMongoArchivePort`
+   * `runChunkedArchive` orchestrator with `createMongoArchiveRun`
    * (`_id`-ordered lean reads + plugin-routed deleteMany removal). See
    * [actions/archive.ts](./actions/archive.ts) for the port.
    *
+   * `retentionPurge` rides every chunk delete with an attestation of the ids the
+   * sink acknowledged, so a fence built with `allowArchive` (or `allowPurge`)
+   * admits it; validated before any chunk is read. Each row is deleted only if its
+   * `updatedAt` (+ `versionField`) still equals the exported value; an edited row stays
+   * live for the next run.
+   *
    * Accepts Filter IR or a Mongo-shaped filter record — compiled once via
    * `compileFilterToMongo`, same dual-dialect rule as every other verb.
    */
   archiveByFilter(filter: Record<string, unknown> | Filter, sink: ArchiveSink<TDoc>, options?: ArchiveOptions & {
     session?: ClientSession;
+    retentionPurge?: RetentionPurgeRequest | undefined;
+    /** Rows never change: skip the unchanged-since-export pin (refused without it when the schema has no timestamps). */
+    immutable?: boolean | undefined;
   }): Promise<ArchiveResult>;
   /**
    * Many keyed upserts in ONE command with an exact per-row outcome (repo-core `bulkUpsert` IR).
@@ -1989,5 +2021,4 @@ declare class Repository<TDoc = unknown> extends RepositoryBase {
   _handleError(error: Error): HttpError;
   private _translateError;
 }
-//#endregion
-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 };
+export { AggregationBuilder as a, ProjectionSpec as c, VectorSearchOptions as d, RetentionTenantPurgeOptions as f, 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 };