@classytic/mongokit 3.43.1 → 3.45.0

package/dist/{Repository-Dj6xqPxJ.mjs → Repository-DheA7oW-.mjs}

@@ -1,15 +1,15 @@
-import { i as isValidIdForType, t as getSchemaIdType } from "./id-resolution-BqDrk0S2.mjs";
-import { a as narrowToIds, i as keysetFilter, o as selectKeysetChunk, r as idChunks, t as DEFAULT_ID_CHUNK } from "./id-chunks-BmAwsqNk.mjs";
-import { _ as SHORTHAND_OPS, a as count, b as create, c as getByQuery, d as deleteById, f as deleteByQuery, g as LookupBuilder, h as distinct, l as getOrCreate, n as update, o as exists, r as updateByQuery, s as getById, t as findOneAndUpdate, v as compileFilterToMongo, x as createMany, y as castFilterToSchema } from "./update-WgeAUJ_I.mjs";
-import { n as warn } from "./logger-K7dPmu2U.mjs";
-import { n as isDuplicateKeyError, r as parseDuplicateKeyError, t as createError } from "./error-BuByZwKU.mjs";
-import { i as applyToQuery, n as applyCursorTimeoutMode, r as applyToAggregate, u as resolveQueryOptions } from "./query-defaults-BxUcSOoF.mjs";
-import { o as withTransaction, p as resolveMongoCapabilities, s as createTxBoundRepo } from "./transaction-DmiB4k2P.mjs";
-import { _ as resolveCursorSecrets, d as withGroupTiebreak, f as withIdTiebreak, g as attachSignature, i as validateKeysetSort, l as assertOffsetWithinCap, n as getPrimaryField, o as encodeCursor, s as resolveCursorFilter, t as PaginationEngine, u as cursorScope, v as verifySignature } from "./PaginationEngine-DZnkbSrr.mjs";
+import { i as isValidIdForType, t as getSchemaIdType } from "./id-resolution-Cqh49d9J.mjs";
+import { n as isDuplicateKeyError, r as parseDuplicateKeyError, t as createError } from "./error-DjdmPLWO.mjs";
+import { a as narrowToIds, i as keysetFilter, o as selectKeysetChunk, r as idChunks, t as DEFAULT_ID_CHUNK } from "./id-chunks-DH-RAZWG.mjs";
+import { _ as SHORTHAND_OPS, a as count, b as create, c as getByQuery, d as deleteById, f as deleteByQuery, g as LookupBuilder, h as distinct, l as getOrCreate, n as update, o as exists, r as updateByQuery, s as getById, t as findOneAndUpdate, v as compileFilterToMongo, x as createMany, y as castFilterToSchema } from "./update-CYaJMu6j.mjs";
+import { n as warn } from "./logger-hbWOlj_X.mjs";
+import { l as resolveQueryOptions, n as applyToAggregate, r as applyToQuery } from "./query-defaults-DwvWUjZU.mjs";
+import { o as withTransaction, p as resolveMongoCapabilities, s as createTxBoundRepo } from "./transaction-C6Oj941P.mjs";
+import { _ as resolveCursorSecrets, d as withGroupTiebreak, f as withIdTiebreak, g as attachSignature, i as validateKeysetSort, l as assertOffsetWithinCap, n as getPrimaryField, o as encodeCursor, s as resolveCursorFilter, t as PaginationEngine, u as cursorScope, v as verifySignature } from "./PaginationEngine-BRlLTQQz.mjs";
 import { calculateTotalPages } from "./pagination/utils/limits.mjs";
-import { a as insertValues, c as writeKeys, d as buildSearchKeys, f as prefixSearchFilter, i as fieldValuesOf, n as SearchKeysWriteError, o as keysFromValues, r as analyzeUpdate, s as unresolvedForUpdate, t as SEARCH_KEYS_ERROR_CODES } from "./derive-DRBiegRH.mjs";
+import { a as insertValues, c as writeKeys, d as buildSearchKeys, f as prefixSearchFilter, i as fieldValuesOf, n as SearchKeysWriteError, o as keysFromValues, r as analyzeUpdate, s as unresolvedForUpdate, t as SEARCH_KEYS_ERROR_CODES } from "./derive-Dxsc31fV.mjs";
 import { hasNearOperator, rewriteNearForCount } from "./query/primitives/geo.mjs";
-import { a as scopeJoins, r as markGoverned } from "./join-scope-DSAznE8E.mjs";
+import { a as scopeJoins, r as markGoverned } from "./join-scope-C1gOtZ59.mjs";
 import { BULK_UPSERT_ERROR_CODES, BULK_UPSERT_FAILURE_CODES, RepositoryBase, bulkUpsertOptionsError, createDistributionGuard, runChunkedArchive, runChunkedPurge, summarizeBulkUpsert, throwIfAborted, validatePluginOrder, withRetry } from "@classytic/repo-core/repository";
 import mongoose from "mongoose";
 import { isFilter } from "@classytic/repo-core/filter";
@@ -17,13 +17,135 @@ import { VersionConflictError, conservativeMongoIsTransientConflict } from "@cla
 import { HOOK_PRIORITY } from "@classytic/repo-core/hooks";
 import { compileUpdateSpecToMongo, isUpdateSpec } from "@classytic/repo-core/update";
 import { decodeAggCursor, encodeAggCursor, isKeysetMode, normalizeGroupBy, validateMeasures } from "@classytic/repo-core/aggregate";
-//#region src/actions/purge.ts
+// src/plugins/retention-purge.ts
+/** Error codes thrown for a malformed or unauthorized retention purge. */
+const RETENTION_PURGE_ERROR_CODES = {
+	DISABLED: "RETENTION_PURGE_DISABLED",
+	REASON_REQUIRED: "RETENTION_PURGE_REASON_REQUIRED",
+	INVALID_ACTOR: "RETENTION_PURGE_INVALID_ACTOR",
+	HARD_ONLY: "RETENTION_PURGE_HARD_ONLY",
+	ARCHIVE_UNATTESTED: "RETENTION_PURGE_ARCHIVE_UNATTESTED"
+};
+/** Attested id sets, keyed by an object only `attestArchivedChunk` can mint. */
+const ATTESTED_CHUNKS = /* @__PURE__ */ new WeakMap();
+/**
+* Mint the attestation for one archive chunk the sink has ACKNOWLEDGED. Internal to
+* mongokit (not exported from the package entry): the archive port is its only caller.
+*/
+function attestArchivedChunk(ids) {
+	const token = Object.freeze({});
+	ATTESTED_CHUNKS.set(token, new Set(ids.map(String)));
+	return token;
+}
+/** Every `_id: { $in: [...] }` list in the query, through nested `$and`. */
+function idListsIn(query) {
+	if (!query || typeof query !== "object") return [];
+	const q = query;
+	const lists = [];
+	const idPredicate = q._id;
+	if (idPredicate && typeof idPredicate === "object" && Array.isArray(idPredicate.$in)) lists.push(idPredicate.$in);
+	if (Array.isArray(q.$and)) for (const arm of q.$and) lists.push(...idListsIn(arm));
+	return lists;
+}
+/**
+* Whether the context carries an attestation, and whether it covers the delete. A delete
+* is covered only when some `_id.$in` it ANDs in is non-empty and wholly attested — an
+* extra predicate can only narrow it further.
+*/
+function archiveAttestationOf(ctx) {
+	const token = ctx.archiveAttestation;
+	if (token === void 0) return "none";
+	const attested = typeof token === "object" && token ? ATTESTED_CHUNKS.get(token) : void 0;
+	if (!attested) return "invalid";
+	const query = ctx.query;
+	return idListsIn(query).some((ids) => ids.length > 0 && ids.every((id) => attested.has(String(id)))) ? "valid" : "invalid";
+}
+/** Validates the request's shape (reason, actor). Throws 400 on a malformed one. */
+function assertRetentionPurgeShape(raw, op) {
+	const req = raw;
+	if (!req || typeof req !== "object" || typeof req.reason !== "string" || !req.reason.trim()) throw createError(400, `'${op}' with retentionPurge needs a non-blank reason.`, {
+		code: RETENTION_PURGE_ERROR_CODES.REASON_REQUIRED,
+		meta: { operation: op }
+	});
+	if (req.actor !== void 0 && (typeof req.actor !== "string" || !req.actor.trim())) throw createError(400, `'${op}' with retentionPurge: actor must be a non-blank string.`, {
+		code: RETENTION_PURGE_ERROR_CODES.INVALID_ACTOR,
+		meta: { operation: op }
+	});
+	return {
+		reason: req.reason,
+		actor: req.actor
+	};
+}
+/**
+* The validated purge request on a delete context, or `undefined` for an
+* ordinary delete. Refuses every malformed or unauthorized form rather than
+* falling back to the fence: a purge that silently became a refused delete
+* would hide the misconfiguration from the job.
+*/
+function readRetentionPurge(ctx, op, guard) {
+	const raw = ctx.retentionPurge;
+	if (raw === void 0 || raw === null || raw === false) return void 0;
+	const attestation = archiveAttestationOf(ctx);
+	if (attestation === "invalid") throw createError(403, `'${op}' carries an archive attestation that does not cover the rows it deletes: an archive delete may remove only the chunk its sink acknowledged.`, {
+		code: RETENTION_PURGE_ERROR_CODES.ARCHIVE_UNATTESTED,
+		meta: {
+			operation: op,
+			plugin: guard.plugin
+		}
+	});
+	if (!guard.allowPurge && !(guard.allowArchive && attestation === "valid")) throw createError(403, `'${op}' with retentionPurge is not enabled on this repository: construct ${guard.plugin} with allowPurge: true for the retention path` + (attestation === "valid" ? ", or allowArchive: true for archiveByFilter." : "."), {
+		code: RETENTION_PURGE_ERROR_CODES.DISABLED,
+		meta: {
+			operation: op,
+			plugin: guard.plugin
+		}
+	});
+	const req = assertRetentionPurgeShape(raw, op);
+	if (ctx.deleteMode !== "hard") throw createError(400, `'${op}' with retentionPurge must be a physical delete: pass mode: 'hard'.`, {
+		code: RETENTION_PURGE_ERROR_CODES.HARD_ONLY,
+		meta: { operation: op }
+	});
+	return req;
+}
+/** Builds the common audit payload from an `after:delete` / `after:deleteMany` emission. */
+function retentionPurgeEvent(operation, context, result) {
+	const req = context.retentionPurge;
+	if (!req || typeof req !== "object") return void 0;
+	const ctx = context;
+	return {
+		operation,
+		reason: req.reason,
+		actor: req.actor,
+		id: operation === "delete" ? ctx.id : void 0,
+		filter: operation === "deleteMany" ? ctx.query : void 0,
+		deletedCount: operation === "delete" ? result ? 1 : 0 : result?.deletedCount ?? 0,
+		archived: archiveAttestationOf(context) === "valid",
+		session: context.session,
+		context
+	};
+}
+// src/actions/purge.ts
+/**
+* Validates the run's `retentionPurge` up front (before any chunk is
+* selected) and returns the port options. A purge request is a physical
+* delete only: with a `soft` / `anonymize` strategy it is refused.
+*/
+function purgePortOptions(op, strategy, options) {
+	const raw = options.retentionPurge;
+	if (raw === void 0 || raw === null || raw === false) return {};
+	const retentionPurge = assertRetentionPurgeShape(raw, op);
+	if (strategy.type !== "hard") throw createError(400, `'${op}' with retentionPurge must use the 'hard' strategy (got '${strategy.type}').`, {
+		code: RETENTION_PURGE_ERROR_CODES.HARD_ONLY,
+		meta: { operation: op }
+	});
+	return { retentionPurge };
+}
 /**
 * Build a `PurgePort` bound to a repository + the `field = value`
 * predicate the purge targets.
 */
-function createMongoPurgePort(repo, field, value, session) {
-	return createKeysetPurgePort(repo, { [field]: value }, session);
+function createMongoPurgePort(repo, field, value, session, portOptions = {}) {
+	return createKeysetPurgePort(repo, { [field]: value }, session, portOptions);
 }
 /**
 * Build a `PurgePort` bound to a repository + a pre-compiled Mongo filter
@@ -39,27 +161,32 @@ function createMongoPurgePort(repo, field, value, session) {
 * uses, so a row that leaves the matching set between the id select and the
 * write is never touched.
 *
-* Mirrors `createMongoArchivePort`, which likewise binds a pre-compiled
+* Mirrors `createMongoArchiveRun`, which likewise binds a pre-compiled
 * filter rather than a `field/value` pair.
 */
-function createMongoPurgePortFromFilter(repo, filter, session) {
-	return createKeysetPurgePort(repo, filter, session);
+function createMongoPurgePortFromFilter(repo, filter, session, portOptions = {}) {
+	return createKeysetPurgePort(repo, filter, session, portOptions);
 }
 /**
 * Shared keyset-progressed port both public factories delegate to. The
 * closure's `cursor` is the port's single-run progression state.
 */
-function createKeysetPurgePort(repo, baseFilter, session) {
+function createKeysetPurgePort(repo, baseFilter, session, portOptions) {
 	const baseOpts = {
 		session,
 		bypassTenant: true
 	};
+	const hardOpts = {
+		...baseOpts,
+		mode: "hard",
+		...portOptions.retentionPurge ? { retentionPurge: portOptions.retentionPurge } : {}
+	};
 	let cursor = null;
 	const selectFilter = () => keysetFilter(baseFilter, cursor);
 	return { async purgeChunk(strategy, limit) {
 		if (strategy.type === "anonymize") {
 			if (Object.values(strategy.fields).some((v) => typeof v === "function")) {
-				const { processed, lastId } = await purgeAnonymizeFunctional(repo, selectFilter(), strategy.fields, limit, session);
+				const { processed, lastId } = await purgeAnonymizeFunctional(repo, selectFilter(), baseFilter, strategy.fields, limit, session, baseOpts);
 				if (lastId != null) cursor = lastId;
 				return processed;
 			}
@@ -73,10 +200,7 @@ function createKeysetPurgePort(repo, baseFilter, session) {
 		const chunkFilter = narrowToIds(baseFilter, ids);
 		switch (strategy.type) {
 			case "hard":
-				await repo.deleteMany(chunkFilter, {
-					...baseOpts,
-					mode: "hard"
-				});
+				await repo.deleteMany(chunkFilter, hardOpts);
 				break;
 			case "soft":
 				await repo.updateMany(chunkFilter, { $set: {
@@ -92,47 +216,68 @@ function createKeysetPurgePort(repo, baseFilter, session) {
 }
 /**
 * Anonymize with at least one function-form field replacer. Fetches the
-* full docs (function needs the row) and issues ONE `bulkWrite` with N
-* heterogeneous `updateOne` ops. Two round-trips per chunk regardless
-* of N — vs the N+1 of per-doc `update()` fan-out.
+* full docs (function needs the row), computes each row's values, and
+* writes the chunk with ONE `repo.updateMany` whose pipeline picks each
+* row's value by its `_id`. Two round-trips per chunk regardless of N.
+*
+* Through the repository, never a raw `Model.bulkWrite`: the write meets
+* the same `before:updateMany` fences as the static form —
+* `immutableStatesPlugin` refuses a chunk holding a frozen row,
+* `appendOnlyPlugin` refuses the edit, tenant / soft-delete scope apply —
+* and `after:updateMany` reaches the change log, cache and audit plugins.
 *
 * Selection is `_id`-ascending against the caller's keyset-narrowed
 * filter; returns the chunk's last `_id` so the port can advance its
-* cursor after the write commits.
-*
-* Mongo's `bulkWrite` is ordered: false → independent failures don't
-* abort the batch. For idempotent anonymize (same row anonymized twice
-* is the same write), this matches the at-least-once contract.
+* cursor after the write commits. Values are cast by the field's schema
+* type where it is a scalar (a pipeline update is not cast by mongoose);
+* `undefined` is written as `null`. Idempotent per row, so the
+* at-least-once contract holds.
 */
-async function purgeAnonymizeFunctional(repo, selectFilter, fields, limit, session) {
+async function purgeAnonymizeFunctional(repo, selectFilter, baseFilter, fields, limit, session, writeOpts) {
 	const docs = await selectKeysetChunk(repo.Model, selectFilter, limit, { session });
 	if (docs.length === 0) return {
 		processed: 0,
 		lastId: null
 	};
-	const operations = docs.map((doc) => {
-		const set = {};
-		for (const [k, v] of Object.entries(fields)) set[k] = typeof v === "function" ? v(doc) : v;
-		return { updateOne: {
-			filter: { _id: doc._id },
-			update: { $set: set }
+	const ids = docs.map((doc) => doc._id);
+	const set = {};
+	for (const [k, v] of Object.entries(fields)) {
+		const values = docs.map((doc) => castScalar(repo.Model, k, typeof v === "function" ? v(doc) : v));
+		set[k] = { $let: {
+			vars: { i: { $indexOfArray: [{ $literal: ids }, "$_id"] } },
+			in: { $arrayElemAt: [{ $literal: values }, "$$i"] }
 		} };
-	});
-	await repo.Model.bulkWrite(operations, {
-		ordered: false,
-		session: session ?? void 0
-	});
-	await repo.emitAsync("after:anonymize", {
-		context: { ...session ? { session } : {} },
-		result: { ids: docs.map((doc) => doc._id) }
+	}
+	await repo.updateMany(narrowToIds(baseFilter, ids), [{ $set: set }], {
+		...writeOpts,
+		updatePipeline: true
 	});
 	return {
 		processed: docs.length,
 		lastId: docs[docs.length - 1]?._id ?? null
 	};
 }
-//#endregion
-//#region src/operations.ts
+/** Scalar schema types a pipeline write must be cast to by hand (mongoose casts `$set`, not pipelines). */
+const SCALAR_INSTANCES = /* @__PURE__ */ new Set([
+	"String",
+	"Number",
+	"Date",
+	"Boolean",
+	"ObjectId",
+	"ObjectID",
+	"Decimal128",
+	"UUID",
+	"BigInt",
+	"Double",
+	"Int32"
+]);
+function castScalar(model, path, value) {
+	if (value === void 0 || value === null) return null;
+	const type = model.schema.path(path);
+	if (!type?.instance || !SCALAR_INSTANCES.has(type.instance) || !type.cast) return value;
+	return type.cast(value);
+}
+// src/operations.ts
 /**
 * The registry. Order intentionally groups by category for readability.
 * Adding a new RepositoryOperation requires exactly one entry here, after
@@ -295,8 +440,7 @@ const READ_OPERATIONS = ALL_OPERATIONS.filter((op) => !OP_REGISTRY[op].mutates);
 function operationsByPolicyKey(key) {
 	return ALL_OPERATIONS.filter((op) => OP_REGISTRY[op].policyKey === key);
 }
-//#endregion
-//#region src/actions/aggregate-ir/hints.ts
+// src/actions/aggregate-ir/hints.ts
 function applyExecutionHints(aggregation, hints) {
 	if (!hints) return;
 	if (hints.allowDiskUse) aggregation.allowDiskUse(true);
@@ -328,8 +472,7 @@ function assertExpectedIndex(model, leadingKeys) {
 	if (!keys.some((key) => startsWith(key, 0) || startsWith(key, 1))) throw new Error(`[mongokit] ${model.modelName}: an aggregation expects an index leading with (${id}), but none is declared — declared: ${keys.map((k) => `(${k.join(",")})`).join(" ") || "none"}. Declare one, or drop the hint.`);
 	checked.set(model, (done ?? /* @__PURE__ */ new Set()).add(id));
 }
-//#endregion
-//#region src/actions/aggregate-ir/dateBucket.ts
+// src/actions/aggregate-ir/dateBucket.ts
 /**
 * Compile a `AggDateBucket` to the mongo expression that produces the
 * bucket label string for a single document. Used in two places:
@@ -458,8 +601,7 @@ function formatForUnit(unit) {
 		case "year": return "%Y";
 	}
 }
-//#endregion
-//#region src/filter/compile-expr.ts
+// src/filter/compile-expr.ts
 /**
 * Compile a Filter IR node (or already-built expression) to a MongoDB
 * aggregation expression. Returns the literal `true` for empty `and`
@@ -773,8 +915,7 @@ function likeToRegexPattern(pattern) {
 function escapeRegexChar(ch) {
 	return /[.*+?^${}()|[\]\\]/.test(ch) ? `\\${ch}` : ch;
 }
-//#endregion
-//#region src/actions/aggregate-ir/measure.ts
+// src/actions/aggregate-ir/measure.ts
 function compileMeasure(measure) {
 	const whereExpr = measure.where !== void 0 ? compileFilterToMongoExpr(measure.where) : void 0;
 	switch (measure.op) {
@@ -843,8 +984,7 @@ function compileMeasure(measure) {
 			};
 	}
 }
-//#endregion
-//#region src/actions/aggregate-ir/normalize.ts
+// src/actions/aggregate-ir/normalize.ts
 /**
 * AggRequest → input normalization (mongokit binding).
 *
@@ -857,8 +997,7 @@ function compileMeasure(measure) {
 function validateMeasures$1(measures) {
 	validateMeasures(measures, "mongokit");
 }
-//#endregion
-//#region src/actions/aggregate-ir/pipeline.ts
+// src/actions/aggregate-ir/pipeline.ts
 function buildAggPipeline(req, schema) {
 	validateMeasures$1(req.measures);
 	const groupCols = normalizeGroupBy(req.groupBy);
@@ -1251,8 +1390,7 @@ function irReferencesAlias(filter, aliasSet) {
 	if (node.child) return irReferencesAlias(node.child, aliasSet);
 	return false;
 }
-//#endregion
-//#region src/actions/aggregate-ir/execute.ts
+// src/actions/aggregate-ir/execute.ts
 /** Build the aggregate for `stages` with every execution option applied, unexecuted. */
 function prepareAgg(Model, stages, req, options = {}) {
 	const aggregation = Model.aggregate(options.finalize ? options.finalize(stages) : stages);
@@ -1271,8 +1409,7 @@ async function executeAgg(Model, req, options = {}) {
 	const { pipeline } = buildAggPipeline(req, Model.schema);
 	return runAgg(Model, pipeline, req, options);
 }
-//#endregion
-//#region src/actions/aggregate-ir/count.ts
+// src/actions/aggregate-ir/count.ts
 async function countAggGroups(Model, req, options = {}) {
 	const groupCols = normalizeGroupBy(req.groupBy);
 	const hasDottedGroupBy = groupCols.some((f) => f.includes("."));
@@ -1302,8 +1439,7 @@ async function countAggGroups(Model, req, options = {}) {
 	const [row] = await runAgg(Model, pipeline, req, options);
 	return row?.n ?? 0;
 }
-//#endregion
-//#region src/actions/aggregate-ir/keyset.ts
+// src/actions/aggregate-ir/keyset.ts
 /**
 * Keyset (cursor) pagination helpers — mongokit binding.
 *
@@ -1366,29 +1502,83 @@ function buildKeysetPredicate(sort, cursor) {
 	}
 	return { $match: branches.length === 1 ? branches[0] : { $or: branches } };
 }
-//#endregion
-//#region src/actions/archive.ts
+// src/actions/archive.ts
+const idOf = (doc) => doc._id;
+const valueAt = (doc, path) => path.split(".").reduce((acc, key) => acc?.[key], doc);
 /**
-* Build an `ArchivePort` bound to a repository + a pre-compiled Mongo
-* filter (the repository compiles Filter IR before calling this).
+* The fields that prove a row is unchanged since export: the `updatedAt` mongoose
+* timestamps maintain on every write path, plus the repository's `versionField` when
+* the schema has it. Empty only for a collection declared `immutable`. A collection with
+* no maintained `updatedAt` is refused before the run reads anything.
 */
-function createMongoArchivePort(repo, filter, session) {
+function archiveChangeTokens(model, versionField, immutable) {
+	if (immutable) return [];
+	const ts = model.timestamps;
+	const updatedAt = ts === true ? "updatedAt" : ts && typeof ts === "object" && ts.updatedAt !== false ? typeof ts.updatedAt === "string" ? ts.updatedAt : "updatedAt" : void 0;
+	if (!updatedAt) throw createError(400, `archiveByFilter on '${model.modelName}': the schema maintains no updatedAt (timestamps), so a row edited between export and delete could not be told apart and would be deleted with its edit. Enable timestamps, or pass immutable: true for a collection whose rows never change.`, {
+		code: "ARCHIVE_NO_CHANGE_TOKEN",
+		meta: { model: model.modelName }
+	});
+	return model.hasVersionPath ? [updatedAt, versionField] : [updatedAt];
+}
+/** Each exported row pinned to its change tokens: an edited row no longer matches. */
+function unchangedSince(docs, tokens) {
+	return { $or: docs.map((doc) => {
+		const pin = { _id: idOf(doc) };
+		for (const token of tokens) {
+			const value = valueAt(doc, token);
+			pin[token] = value === void 0 ? { $exists: false } : value;
+		}
+		return pin;
+	}) };
+}
+/**
+* Build the sink + port pair for ONE `archiveByFilter` call. The returned sink
+* forwards to the caller's and records what it acknowledged; the port's delete
+* removes only acknowledged rows still unchanged since export, and throws on any other.
+* Progression is a keyset over `_id`, so a row left live is not revisited by this run.
+*/
+function createMongoArchiveRun(repo, filter, sink, session, retentionPurge, immutable) {
+	const tokens = archiveChangeTokens({
+		modelName: repo.Model.modelName,
+		timestamps: repo.Model.schema.get("timestamps"),
+		hasVersionPath: Boolean(repo.Model.schema.path(repo.versionField))
+	}, repo.versionField, immutable);
+	let acknowledged = /* @__PURE__ */ new Set();
+	let cursor = null;
 	return {
-		async readChunk(limit) {
-			return selectKeysetChunk(repo.Model, filter, limit, { session });
+		sink: {
+			async write(docs) {
+				await sink.write(docs);
+				acknowledged = new Set(docs.map((doc) => String(idOf(doc))));
+			},
+			...sink.flush ? { flush: () => sink.flush?.() ?? Promise.resolve() } : {}
 		},
-		async deleteChunk(docs) {
-			const ids = docs.map((doc) => doc._id);
-			return (await repo.deleteMany(narrowToIds(filter, ids), {
-				session,
-				bypassTenant: true,
-				mode: "hard"
-			})).deletedCount;
+		port: {
+			async readChunk(limit) {
+				return selectKeysetChunk(repo.Model, keysetFilter(filter, cursor), limit, { session });
+			},
+			async deleteChunk(docs) {
+				const ids = docs.map(idOf);
+				const unacknowledged = ids.filter((id) => !acknowledged.has(String(id)));
+				if (unacknowledged.length > 0) throw new Error(`archiveByFilter: refusing to delete ${unacknowledged.length} row(s) the sink did not acknowledge`);
+				const narrowed = narrowToIds(filter, ids);
+				const result = await repo.deleteMany(tokens.length > 0 ? { $and: [narrowed, unchangedSince(docs, tokens)] } : narrowed, {
+					session,
+					bypassTenant: true,
+					mode: "hard",
+					...retentionPurge ? {
+						retentionPurge,
+						archiveAttestation: attestArchivedChunk(ids)
+					} : {}
+				});
+				if (ids.length > 0) cursor = ids[ids.length - 1];
+				return result.deletedCount;
+			}
 		}
 	};
 }
-//#endregion
-//#region src/actions/bulk-upsert.ts
+// src/actions/bulk-upsert.ts
 /**
 * `bulkUpsert` execution: keyed `updateOne` + `upsert` sub-ops in ONE `client.bulkWrite` with
 * `verboseResults`, the only form that reports matched / modified / upserted PER OP (server 8.0,
@@ -1529,7 +1719,7 @@ async function executeUpserts(model, ops, options) {
 			verboseResults: true,
 			...options.session ? { session: options.session } : {},
 			...options.writeConcern ? { writeConcern: options.writeConcern } : {},
-			...options.timeoutMS !== void 0 ? { timeoutMS: options.timeoutMS } : {}
+			...options.maxTimeMS !== void 0 ? { maxTimeMS: options.maxTimeMS } : {}
 		});
 	} catch (err) {
 		throwIfUnsupported(err);
@@ -1569,8 +1759,7 @@ async function executeUpserts(model, ops, options) {
 	});
 	return results;
 }
-//#endregion
-//#region src/plugins/search-keys.plugin.ts
+// src/plugins/search-keys.plugin.ts
 /**
 * Search-keys plugin: keeps the `searchMode: 'prefix'` keys field in step with
 * its source fields on EVERY write path, inside the same write.
@@ -1680,8 +1869,7 @@ function searchKeysPlugin(options) {
 		}
 	};
 }
-//#endregion
-//#region src/query/AggregationBuilder.ts
+// src/query/AggregationBuilder.ts
 /**
 * Normalize SortSpec to MongoDB's strict format (1 | -1)
 * Converts 'asc' -> 1, 'desc' -> -1
@@ -2212,8 +2400,7 @@ var AggregationBuilder = class AggregationBuilder {
 *      .exec(Model)
 *    ```
 */
-//#endregion
-//#region src/repository/lookup-populate.ts
+// src/repository/lookup-populate.ts
 /**
 * Inclusion projections must carry the keyset sort fields (plus `_id`) or
 * cursor encoding has no values to serialize. No-op for exclusion
@@ -2265,8 +2452,16 @@ function appendLookupStages(pipeline, lookups, projection, keysetSort) {
 	const finalProjection = ensureLookupProjectionIncludesCursorFields(projection, keysetSort);
 	if (finalProjection) pipeline.push({ $project: finalProjection });
 }
-//#endregion
-//#region src/Repository.ts
+// src/Repository.ts
+/**
+* A CAS guard (`claim` / `claimVersion` `where`) as Mongo: Filter IR compiled, a plain
+* record (Mongo operators) as is. Spreading an IR node raw made the match require
+* `doc.op === 'eq'` — no document matched, and the miss read as a lost race.
+*/
+function casGuard(where) {
+	if (where === void 0) return {};
+	return isFilter(where) ? compileFilterToMongo(where) : where;
+}
 /**
 * Validates that an update patch is homogeneous — either all top-level
 * keys are `$`-prefixed Mongo operators OR none are. Mixed shapes (e.g.
@@ -2990,7 +3185,7 @@ var Repository = class extends RepositoryBase {
 	}
 	/**
 	* 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.
@@ -3069,7 +3264,6 @@ var Repository = class extends RepositoryBase {
 		if (options.session) query.session(options.session);
 		const cursorOpts = this._opts("read", context);
 		applyToQuery(query, cursorOpts);
-		applyCursorTimeoutMode(query, cursorOpts, this.Model.db);
 		const stream = query.cursor();
 		let yieldedCount = 0;
 		try {
@@ -3885,7 +4079,7 @@ var Repository = class extends RepositoryBase {
 		const effectiveIdField = options.idField ?? this.idField;
 		const fromSpec = Array.isArray(transition.from) ? { $in: transition.from } : transition.from;
 		const filter = {
-			...transition.where ?? {},
+			...casGuard(transition.where),
 			[effectiveIdField]: id,
 			[stateField]: fromSpec
 		};
@@ -4008,13 +4202,32 @@ var Repository = class extends RepositoryBase {
 			machine.assertTransition(entityId, from, args.to);
 		}
 		const historyField = args.history === false ? null : args.history ?? "statusHistory";
+		if (historyField === null && (args.priorAt !== void 0 || args.historyExtra !== void 0)) throw createError(400, "applyTransition: priorAt / historyExtra need history (got history: false)", { code: "TRANSITION_HISTORY_DISABLED" });
+		if (args.priorAt !== void 0 && (!(args.priorAt instanceof Date) || Number.isNaN(args.priorAt.getTime()))) throw createError(400, "applyTransition: priorAt must be a valid Date", { code: "TRANSITION_INVALID_PRIOR_AT" });
+		if (args.priorAt !== void 0 && args.at !== void 0 && (!(args.at instanceof Date) || Number.isNaN(args.at.getTime()))) throw createError(400, "applyTransition: at must be a valid Date when priorAt is given", { code: "TRANSITION_INVALID_AT" });
+		if (args.historyExtra !== void 0 && (args.historyExtra === null || typeof args.historyExtra !== "object" || Array.isArray(args.historyExtra))) throw createError(400, "applyTransition: historyExtra must be a plain object", { code: "TRANSITION_INVALID_HISTORY_EXTRA" });
+		if (args.historyExtra !== void 0) {
+			const reserved = [
+				"status",
+				"occurredAt",
+				"by",
+				"note",
+				"durationInPriorMs"
+			].filter((k) => k in args.historyExtra);
+			if (reserved.length > 0) throw createError(400, `applyTransition: historyExtra may not set reserved key(s) ${reserved.join(", ")}`, { code: "TRANSITION_HISTORY_RESERVED_KEY" });
+		}
 		const pushSpec = { ...args.push ?? {} };
-		if (historyField !== null) pushSpec[historyField] = {
-			status: args.to,
-			occurredAt: args.at ?? /* @__PURE__ */ new Date(),
-			...args.by !== void 0 ? { by: args.by } : {},
-			...args.note !== void 0 ? { note: args.note } : {}
-		};
+		if (historyField !== null) {
+			const occurredAt = args.at ?? /* @__PURE__ */ new Date();
+			pushSpec[historyField] = {
+				...args.historyExtra ?? {},
+				status: args.to,
+				occurredAt,
+				...args.by !== void 0 ? { by: args.by } : {},
+				...args.note !== void 0 ? { note: args.note } : {},
+				...args.priorAt !== void 0 ? { durationInPriorMs: Math.max(0, occurredAt.getTime() - args.priorAt.getTime()) } : {}
+			};
+		}
 		const patch = {
 			...args.set !== void 0 && Object.keys(args.set).length > 0 ? { $set: args.set } : {},
 			...Object.keys(pushSpec).length > 0 ? { $push: pushSpec } : {},
@@ -4156,7 +4369,7 @@ var Repository = class extends RepositoryBase {
 		};
 		const versionMatch = transition.from === void 0 ? null : transition.from;
 		const filter = {
-			...transition.where ?? {},
+			...casGuard(transition.where),
 			[effectiveIdField]: id,
 			[versionField]: versionMatch
 		};
@@ -4370,7 +4583,7 @@ var Repository = class extends RepositoryBase {
 	* the port implementation.
 	*/
 	async purgeByField(field, value, strategy, options = {}) {
-		const port = createMongoPurgePort(this, field, value, options.session);
+		const port = createMongoPurgePort(this, field, value, options.session, purgePortOptions("purgeByField", strategy, options));
 		return runChunkedPurge(strategy, options, port);
 	}
 	/**
@@ -4388,25 +4601,31 @@ var Repository = class extends RepositoryBase {
 	* See [actions/purge.ts](./actions/purge.ts) for the port.
 	*/
 	async purgeByFilter(filter, strategy, options = {}) {
-		const compiled = compileFilterToMongo(filter);
-		const port = createMongoPurgePortFromFilter(this, compiled, options.session);
+		const port = createMongoPurgePortFromFilter(this, compileFilterToMongo(filter), options.session, purgePortOptions("purgeByFilter", strategy, options));
 		return runChunkedPurge(strategy, options, port);
 	}
 	/**
 	* 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.
 	*/
 	async archiveByFilter(filter, sink, options = {}) {
 		const compiled = compileFilterToMongo(filter);
-		const port = createMongoArchivePort(this, compiled, options.session);
-		return runChunkedArchive(options, sink, port);
+		const retentionPurge = options.retentionPurge === void 0 ? void 0 : assertRetentionPurgeShape(options.retentionPurge, "archiveByFilter");
+		const run = createMongoArchiveRun(this, compiled, sink, options.session, retentionPurge, options.immutable === true);
+		return runChunkedArchive(options, run.sink, run.port);
 	}
 	/**
 	* Many keyed upserts in ONE command with an exact per-row outcome (repo-core `bulkUpsert` IR).
@@ -4467,7 +4686,7 @@ var Repository = class extends RepositoryBase {
 				ordered,
 				session: context.session,
 				writeConcern: writeOpts.writeConcern,
-				timeoutMS: writeOpts.maxTimeMS
+				maxTimeMS: writeOpts.maxTimeMS
 			});
 			return summarizeBulkUpsert([...refused, ...sent].sort((a, b) => a.index - b.index));
 		});
@@ -4827,9 +5046,9 @@ var Repository = class extends RepositoryBase {
 				const appendLookupStages$2 = (pipeline) => appendLookupStages(pipeline, lookups, projection, isKeyset && sort ? this._parseSort(sort) : void 0);
 				if (isKeyset && sort) {
 					const parsedSort = this._parseSort(sort);
-					const { validateKeysetSort } = await import("./PaginationEngine-DZnkbSrr.mjs").then((n) => n.r);
-					const { encodeCursor, resolveCursorFilter } = await import("./PaginationEngine-DZnkbSrr.mjs").then((n) => n.a);
-					const { getPrimaryField } = await import("./PaginationEngine-DZnkbSrr.mjs").then((n) => n.r);
+					const { validateKeysetSort } = await import("./PaginationEngine-BRlLTQQz.mjs").then((n) => n.r);
+					const { encodeCursor, resolveCursorFilter } = await import("./PaginationEngine-BRlLTQQz.mjs").then((n) => n.a);
+					const { getPrimaryField } = await import("./PaginationEngine-BRlLTQQz.mjs").then((n) => n.r);
 					const normalizedSort = validateKeysetSort(parsedSort, this._pagination.config.strictKeysetSortFields);
 					const cursorVersion = this._pagination.config.cursorVersion ?? 1;
 					const minCursorVersion = this._pagination.config.minCursorVersion ?? 1;
@@ -5392,5 +5611,4 @@ var Repository = class extends RepositoryBase {
 		return createError(500, error.message || "Internal Server Error");
 	}
 };
-//#endregion
-export { ALL_OPERATIONS as a, READ_OPERATIONS as c, searchKeysPlugin as i, operationsByPolicyKey as l, Repository as n, MUTATING_OPERATIONS as o, AggregationBuilder as r, OP_REGISTRY as s, HOOK_PRIORITY$1 as t, createMongoPurgePort as u };
+export { ALL_OPERATIONS as a, READ_OPERATIONS as c, RETENTION_PURGE_ERROR_CODES as d, readRetentionPurge as f, searchKeysPlugin as i, operationsByPolicyKey as l, Repository as n, MUTATING_OPERATIONS as o, retentionPurgeEvent as p, AggregationBuilder as r, OP_REGISTRY as s, HOOK_PRIORITY$1 as t, createMongoPurgePort as u };