@classytic/mongokit 3.44.0 → 3.45.0

package/dist/{transaction-C2PFxfIv.mjs → transaction-C6Oj941P.mjs}

@@ -1,4 +1,4 @@
-import { d as setTransactionDeadline } from "./query-defaults-aUoKlEbh.mjs";
+import { u as setTransactionDeadline } from "./query-defaults-DwvWUjZU.mjs";
 import { t as createError } from "./error-DjdmPLWO.mjs";
 import mongoose from "mongoose";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
@@ -494,18 +494,17 @@ function timeoutError(cause, csot) {
 }
 /**
 * The driver's convenient-transaction algorithm (start → callback → commit, label-based retry,
-* jittered backoff, a deadline), run here so the driver never attaches a session `timeoutContext`:
-* with one, every legacy bulk write (`insertMany`, `bulkWrite`) in the transaction is refused once
-* the client carries `timeoutMS` (driver <= 7.7: the bulk path re-resolves the inherited client
-* `timeoutMS` as a per-op one). Each operation keeps its own per-op CSOT budget instead.
-* Deadline: `transactionOptions.timeoutMS`, else the client's `timeoutMS`, else 120 s (as the driver).
-* Pinned by `tests/integration/csot-transaction-matrix.test.ts`.
+* jittered backoff, a deadline), run here and nowhere else: the driver's own `timeoutMS` / CSOT is a
+* no-op since 7.8, so the budget is mongokit's. `transactionOptions.timeoutMS` is that budget, enforced
+* by mongokit alone: every mongokit operation in the transaction is sent with `maxTimeMS` = what
+* remains of it, the commit is bounded by `maxCommitTimeMS`, and the retry loop stops at the deadline
+* (a spent budget before the commit aborts, so the outcome is known). Without it the deadline is 120 s
+* (as the driver) and operations carry only their own bound. The client's `timeoutMS` is not read.
+* Pinned by `tests/integration/transaction-budget-matrix.test.ts`.
 */
 async function runTransaction(session, callback, transactionOptions = {}) {
 	assertSessionSurface(session, DRIVEN);
-	const { timeoutMS: explicitTimeout, ...startOptions } = transactionOptions;
-	const clientTimeout = session.timeoutMS;
-	const timeoutMS = explicitTimeout ?? clientTimeout;
+	const { timeoutMS, ...startOptions } = transactionOptions;
 	const csot = timeoutMS != null;
 	const deadline = performance.now() + (timeoutMS ?? MAX_TRANSACTION_TIMEOUT_MS);
 	let lastError;
@@ -517,7 +516,10 @@ async function runTransaction(session, callback, transactionOptions = {}) {
 				if (performance.now() + backoff >= deadline) throw timeoutError(lastError, csot);
 				await setTimeout$1(backoff);
 			}
-			session.startTransaction(startOptions);
+			session.startTransaction(csot && startOptions.maxCommitTimeMS === void 0 ? {
+				...startOptions,
+				maxCommitTimeMS: Math.max(1, Math.floor(deadline - performance.now()))
+			} : startOptions);
 			let result;
 			try {
 				result = await callback(session);
@@ -539,7 +541,7 @@ async function runTransaction(session, callback, transactionOptions = {}) {
 					throw late;
 				}
 				try {
-					await session.commitTransaction(csot ? { timeoutMS: Math.max(1, Math.floor(left)) } : void 0);
+					await session.commitTransaction();
 					return result;
 				} catch (err) {
 					lastError = err;

package/dist/{update-DcfmNbJe.mjs → update-CYaJMu6j.mjs}

@@ -1,7 +1,7 @@
 import { t as __exportAll } from "./rolldown-runtime-D8jQpDG7.mjs";
 import { t as createError } from "./error-DjdmPLWO.mjs";
 import { n as warn } from "./logger-hbWOlj_X.mjs";
-import { i as applyToQuery } from "./query-defaults-aUoKlEbh.mjs";
+import { r as applyToQuery } from "./query-defaults-DwvWUjZU.mjs";
 import { coerceFilterDates, isFilter } from "@classytic/repo-core/filter";
 // src/actions/create.ts
 var create_exports = /* @__PURE__ */ __exportAll({
@@ -17,8 +17,6 @@ var create_exports = /* @__PURE__ */ __exportAll({
 async function create(Model, data, options = {}) {
 	const document = new Model(data);
 	const saveOptions = { session: options.session };
-	const bound = options.queryOptions?.maxTimeMS;
-	if (bound !== void 0) Object.assign(saveOptions, { timeoutMS: bound });
 	const wc = options.queryOptions?.writeConcern;
 	if (wc) Object.assign(saveOptions, { writeConcern: {
 		...wc.w !== void 0 ? { w: wc.w } : {},
@@ -71,7 +69,7 @@ async function createMany(Model, dataArray, options = {}) {
 		const wc = options.queryOptions?.writeConcern;
 		if (wc) Object.assign(insertOptions, { writeConcern: wc });
 		const bound = options.queryOptions?.maxTimeMS;
-		if (bound !== void 0) Object.assign(insertOptions, { timeoutMS: bound });
+		if (bound !== void 0) Object.assign(insertOptions, { maxTimeMS: bound });
 		return await Model.insertMany(dataArray, insertOptions);
 	} catch (err) {
 		const inserted = err.insertedDocs;

package/dist/utils/index.d.mts

@@ -1,4 +1,4 @@
-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-PO5r1Qoy.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";
 /**
  * Default slice for `$in` fan-out. Larger than `runChunkedPurge`'s 1000 on purpose:

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

@@ -1,7 +1,7 @@
-import { A as ObjectId, F as SortSpec, N as SelectSpec, j as PopulateSpec } from "./pagination-DAUg5zOY.mjs";
-import { h as RepositoryInstance, l as Plugin, p as RepositoryContext } from "./repository-DzVIwhU2.mjs";
-import { n as RetentionPurgeEvent, r as RetentionPurgeRequest } from "./retention-purge-DqcYvRnG.mjs";
-import { c as ValidationChainOptions, i as Logger, l as ValidatorDefinition, o as SoftDeleteOptions, r as FieldPreset, t as CascadeOptions } from "./plugin-options-Bpcuz9kS.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";
@@ -112,6 +112,13 @@ interface AppendOnlyPluginOptions {
    * 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;
@@ -127,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;
 }
@@ -358,6 +367,12 @@ interface ImmutableStatesPluginOptions {
    * 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;

package/dist/{validation-chain.plugin-DNY6MIF6.mjs → validation-chain.plugin-DJplVJ12.mjs}

@@ -1,9 +1,9 @@
 import { t as createError } from "./error-DjdmPLWO.mjs";
-import { a as ALL_OPERATIONS, f as readRetentionPurge, p as retentionPurgeEvent, s as OP_REGISTRY } from "./Repository-eMRYZ_2Y.mjs";
+import { a as ALL_OPERATIONS, f as readRetentionPurge, p as retentionPurgeEvent, s as OP_REGISTRY } from "./Repository-DheA7oW-.mjs";
 import { n as collectIds, r as idChunks, t as DEFAULT_ID_CHUNK } from "./id-chunks-DH-RAZWG.mjs";
-import { w as upsert } from "./update-DcfmNbJe.mjs";
+import { w as upsert } from "./update-CYaJMu6j.mjs";
 import { n as warn } from "./logger-hbWOlj_X.mjs";
-import { c as tenantContextKeysOf, o as forwardScope } from "./timestamp.plugin-Bz_zL9PX.mjs";
+import { c as tenantContextKeysOf, o as forwardScope } from "./timestamp.plugin-B-IJrlYb.mjs";
 import { r as getFieldsForUser } from "./field-selection-DPFaFw9Y.mjs";
 import mongoose from "mongoose";
 import { HOOK_PRIORITY } from "@classytic/repo-core/hooks";
@@ -125,6 +125,7 @@ function aggregateHelpersPlugin() {
 * applies). The same option is honoured by `immutableStatesPlugin`, so a
 * repository with both plugins purges through one call. Prefer it over
 * `bypassAppendOnly` for retention: it is delete-only and carries a reason.
+* `allowArchive: true` admits only `archiveByFilter`'s attested chunk deletes.
 *
 * `skipPlugins` is deliberately IGNORED — same policy as tenant scope
 * and soft delete: integrity fences don't have a convenience bypass.
@@ -154,7 +155,8 @@ function appendOnlyPlugin(options = {}) {
 			const modelName = repo.Model?.modelName ?? "model";
 			const purgeGuard = {
 				plugin: "appendOnlyPlugin",
-				allowPurge: options.allowPurge === true
+				allowPurge: options.allowPurge === true,
+				allowArchive: options.allowArchive === true
 			};
 			const priority = options.priority ?? HOOK_PRIORITY.POLICY;
 			for (const [op, meta] of Object.entries(OP_REGISTRY)) {
@@ -183,7 +185,7 @@ function appendOnlyPlugin(options = {}) {
 					});
 				}, { priority });
 			}
-			if (options.allowPurge) for (const op of ["delete", "deleteMany"]) repo.on(`after:${op}`, async (payload) => {
+			if (options.allowPurge || options.allowArchive) for (const op of ["delete", "deleteMany"]) repo.on(`after:${op}`, async (payload) => {
 				const event = retentionPurgeEvent(op, payload.context, payload.result);
 				if (event) await repo.emitAsync("after:append-only-purge", event);
 			});
@@ -827,7 +829,8 @@ function immutableStatesPlugin(options) {
 			};
 			const purgeGuard = {
 				plugin: "immutableStatesPlugin",
-				allowPurge: options.allowPurge === true
+				allowPurge: options.allowPurge === true,
+				allowArchive: options.allowArchive === true
 			};
 			const purgeRequest = (op, ctx) => readRetentionPurge(ctx, op, purgeGuard);
 			for (const op of [
@@ -842,7 +845,7 @@ function immutableStatesPlugin(options) {
 				await guardDelete(ctx);
 			});
 			const emitPurge = async (operation, context, result) => {
-				if (!options.allowPurge || context[internalFlag]) return;
+				if (!(options.allowPurge || options.allowArchive) || context[internalFlag]) return;
 				const base = retentionPurgeEvent(operation, context, result);
 				if (!base) return;
 				const event = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/mongokit",
-  "version": "3.44.0",
+  "version": "3.45.0",
   "description": "Production-grade MongoDB repositories - smart pagination, events, and plugins. Built on @classytic/repo-core.",
   "type": "module",
   "sideEffects": false,
@@ -152,9 +152,9 @@
   },
   "homepage": "https://github.com/classytic/mongokit#readme",
   "peerDependencies": {
-    "@classytic/repo-core": ">=0.37.0",
+    "@classytic/repo-core": ">=0.38.0",
     "mongodb-memory-server": ">=11.3.0",
-    "mongoose": ">=9.11.4"
+    "mongoose": ">=9.12.0"
   },
   "peerDependenciesMeta": {
     "mongodb-memory-server": {
@@ -202,25 +202,25 @@
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",
-    "@better-auth/api-key": "^1.7.15",
-    "@better-auth/mongo-adapter": "^1.7.15",
-    "@biomejs/biome": "^2.6.4",
+    "@better-auth/api-key": "^1.7.18",
+    "@better-auth/mongo-adapter": "^1.7.18",
+    "@biomejs/biome": "^2.6.5",
     "@classytic/dev-tools": "^0.2.1",
-    "@classytic/repo-core": "^0.37.0",
+    "@classytic/repo-core": "^0.38.0",
     "@types/node": "^26.6.6",
     "@vitest/coverage-v8": "^5.1.0",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
-    "better-auth": "^1.7.15",
+    "better-auth": "^1.7.18",
     "dotenv": "^18.0.9",
     "fast-check": "^4.10.2",
     "knip": "^6.44.1",
-    "mongodb": "~7.7.0",
+    "mongodb": "~7.8.0",
     "mongodb-memory-server": "^11.3.0",
-    "mongoose": "^9.11.4",
+    "mongoose": "^9.12.0",
     "publint": "^0.3.25",
     "ts-api": "npm:typescript@~5.9.3",
-    "tsdown": "^0.23.4",
+    "tsdown": "^0.23.5",
     "typescript": "~7.0.2",
     "vitest": "^5.1.0"
   }

package/skills/mongokit/references/plugins-tenancy.md

@@ -37,6 +37,7 @@ Retention purge (append-only or frozen rows): build `appendOnlyPlugin` and/or `i
 `purgeByFilter(filter, { type: 'hard' }, { retentionPurge: { reason, actor } })` (or `deleteMany(filter, { mode: 'hard', retentionPurge })`).
 Each delete call emits `after:append-only-purge` / `after:immutable-states-purge` with `deletedCount` and `session`. Listeners are awaited and a
 throwing one fails the purge; write the audit row with `{ session: event.session }` so it commits or aborts with the delete. Ordinary deletes stay refused.
+Archive (move to cold storage) on those repos: `allowArchive: true`, then `archiveByFilter(filter, sink, { retentionPurge })`; only chunks the sink acknowledged are deleted (event `archived: true`).
 Function-form anonymize writes through the guarded `updateMany` (frozen / append-only rows refused); `immutableStatesPlugin` reads state in the call's session.
 
 `leasePlugin` (after `methodRegistryPlugin`): `lease({ filter, leaseFor, leasedBy, now })` claims a pending row or a dead lease (a row

package/skills/mongokit/references/transactions-outbox.md

@@ -77,12 +77,14 @@ Resolution order: per call, then repository (`queryDefaults` option), then deplo
 import { assertQueryDefaultsConfigured, configureAggregateDefaults, configureQueryDefaults } from '@classytic/mongokit';
 configureQueryDefaults({ maxTimeMS: 15000, readConcern: 'majority', comment: 'api' });
 configureAggregateDefaults({ maxTimeMs: 30000, allowDiskUse: true });
-assertQueryDefaultsConfigured(mongoose.connection);   // boot gate: throws without maxTimeMS or a client timeoutMS
+assertQueryDefaultsConfigured();   // boot gate: throws without a deployment maxTimeMS
 await repo.getAll({ mode: 'offset', page: 1 }, { comment: 'orders.list', maxTimeMS: 5000, hint: { organizationId: 1, createdAt: -1 } });
 ```
 
 Inside a transaction a default read or write concern is dropped (the transaction owns it); a per-call one is passed through.
 
+The bound is the server-side `maxTimeMS`. The driver's `timeoutMS` (CSOT) is a no-op since 7.8, so never rely on it. A single `create()` (Mongoose `save()`) forwards no `maxTimeMS` and is not server-bounded; `createMany`, updates, deletes, `bulkWrite`, reads and aggregates are. `withTransaction({ transactionOptions: { timeoutMS } })` is mongokit's own budget for the whole transaction: each operation gets `maxTimeMS` = what remains, the commit gets `maxCommitTimeMS`.
+
 ## Verify indexes
 
 ```ts