@classytic/mongokit 3.43.1 → 3.44.0

package/dist/{Repository-Dj6xqPxJ.mjs → Repository-eMRYZ_2Y.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-DcfmNbJe.mjs";
+import { n as warn } from "./logger-hbWOlj_X.mjs";
+import { i as applyToQuery, n as applyCursorTimeoutMode, r as applyToAggregate, u as resolveQueryOptions } from "./query-defaults-aUoKlEbh.mjs";
+import { o as withTransaction, p as resolveMongoCapabilities, s as createTxBoundRepo } from "./transaction-C2PFxfIv.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-C9iS0U5l.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,91 @@ 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"
+};
+/** 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;
+	if (!guard.allowPurge) throw createError(403, `'${op}' with retentionPurge is not enabled on this repository: construct ${guard.plugin} with allowPurge: true for the retention path.`, {
+		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,
+		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
@@ -42,24 +120,29 @@ function createMongoPurgePort(repo, field, value, session) {
 * Mirrors `createMongoArchivePort`, 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 +156,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 +172,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 +396,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 +428,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 +557,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 +871,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 +940,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 +953,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 +1346,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 +1365,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 +1395,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,8 +1458,7 @@ function buildKeysetPredicate(sort, cursor) {
 	}
 	return { $match: branches.length === 1 ? branches[0] : { $or: branches } };
 }
-//#endregion
-//#region src/actions/archive.ts
+// src/actions/archive.ts
 /**
 * Build an `ArchivePort` bound to a repository + a pre-compiled Mongo
 * filter (the repository compiles Filter IR before calling this).
@@ -1387,8 +1478,7 @@ function createMongoArchivePort(repo, filter, session) {
 		}
 	};
 }
-//#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,
@@ -1569,8 +1659,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 +1769,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 +2300,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 +2352,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.
@@ -3885,7 +3980,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 +4103,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 +4270,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 +4484,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,8 +4502,7 @@ 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);
 	}
 	/**
@@ -4827,9 +4940,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-C9iS0U5l.mjs").then((n) => n.r);
+					const { encodeCursor, resolveCursorFilter } = await import("./PaginationEngine-C9iS0U5l.mjs").then((n) => n.a);
+					const { getPrimaryField } = await import("./PaginationEngine-C9iS0U5l.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 +5505,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 };

package/dist/actions/index.d.mts

@@ -1,2 +1,2 @@
-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-SYF8N28D.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-8QUEsOFI.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,2 +1,2 @@
-export { m as aggregate, S as create, p as deleteActions, u as read, i as update } from "../update-WgeAUJ_I.mjs";
-import "../actions-ChYfkPYP.mjs";
+export { m as aggregate, S as create, p as deleteActions, u as read, i as update } from "../update-DcfmNbJe.mjs";
+import "../actions-DExyXMTy.mjs";

package/dist/{actions-ChYfkPYP.mjs → actions-DExyXMTy.mjs}

@@ -1,6 +1,6 @@
-import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
-import { S as create_exports, i as update_exports, m as aggregate_exports, p as delete_exports, u as read_exports } from "./update-WgeAUJ_I.mjs";
-//#region src/actions/index.ts
+import { t as __exportAll } from "./rolldown-runtime-D8jQpDG7.mjs";
+import { S as create_exports, i as update_exports, m as aggregate_exports, p as delete_exports, u as read_exports } from "./update-DcfmNbJe.mjs";
+// src/actions/index.ts
 var actions_exports = /* @__PURE__ */ __exportAll({
 	aggregate: () => aggregate_exports,
 	create: () => create_exports,
@@ -8,5 +8,4 @@ var actions_exports = /* @__PURE__ */ __exportAll({
 	read: () => read_exports,
 	update: () => update_exports
 });
-//#endregion
 export { actions_exports as t };

package/dist/adapter/index.d.mts

@@ -2,7 +2,6 @@ import { StandardRepo } from "@classytic/repo-core/repository";
 import { Document, Model } from "mongoose";
 import { SchemaBuilderOptions, SchemaGenerator } from "@classytic/repo-core/schema";
 import { AdapterRepositoryInput, AdapterSchemaContext, AdapterValidationResult, DataAdapter, OpenApiSchemas, RepositoryLike, SchemaMetadata } from "@classytic/repo-core/adapter";
-//#region src/adapter/mongoose-adapter.d.ts
 interface MongooseAdapterOptions<TDoc = unknown, TModelDoc = unknown> {
   /**
    * The Mongoose model. Still a real `Model`, so a Schema or a hand-built
@@ -68,8 +67,8 @@ interface MongooseAdapterOptions<TDoc = unknown, TModelDoc = unknown> {
  * Mongoose data adapter — implements the `DataAdapter<TDoc>` contract from
  * `@classytic/repo-core/adapter`.
  */
-declare class MongooseAdapter<TDoc = unknown, TModelDoc = unknown> implements DataAdapter<TDoc> {
-  readonly type: "mongoose";
+export declare class MongooseAdapter<TDoc = unknown, TModelDoc = unknown> implements DataAdapter<TDoc> {
+  readonly type: 'mongoose';
   readonly name: string;
   /**
    * The model as given. Its document type is NOT `TDoc` — a lean repository
@@ -196,10 +195,8 @@ declare class MongooseAdapter<TDoc = unknown, TModelDoc = unknown> implements Da
  * const adapter = createMongooseAdapter(ProductModel, productRepository);
  * ```
  */
-declare function createMongooseAdapter<TDoc = unknown, TModelDoc = unknown>(model: Model<TModelDoc>, repository: AdapterRepositoryInput<TDoc>): DataAdapter<TDoc>;
-declare function createMongooseAdapter<TDoc = unknown, TModelDoc = unknown>(options: MongooseAdapterOptions<TDoc, TModelDoc>): DataAdapter<TDoc>;
-//#endregion
-//#region src/adapter/types.d.ts
+export declare function createMongooseAdapter<TDoc = unknown, TModelDoc = unknown>(model: Model<TModelDoc>, repository: AdapterRepositoryInput<TDoc>): DataAdapter<TDoc>;
+export declare function createMongooseAdapter<TDoc = unknown, TModelDoc = unknown>(options: MongooseAdapterOptions<TDoc, TModelDoc>): DataAdapter<TDoc>;
 /**
  * Infer document type from a Mongoose model.
  *
@@ -233,7 +230,7 @@ type MatchingModel<TDoc> = Model<TDoc & Document>;
 /**
  * Runtime guard: is `value` a Mongoose model?
  */
-declare function isMongooseModel(value: unknown): value is Model<Document>;
+export declare function isMongooseModel(value: unknown): value is Model<Document>;
 /**
  * Mongoose SchemaType internal shape (not fully exposed by `@types/mongoose`).
  * Used to extract field metadata from schema paths.
@@ -252,5 +249,4 @@ interface MongooseSchemaType {
   };
   [key: string]: unknown;
 }
-//#endregion
-export { type CleanDoc, type InferAdapterDoc, type InferMongooseDoc, type InferRepoDoc, type MatchingModel, MongooseAdapter, type MongooseAdapterOptions, type MongooseDocument, type MongooseSchemaType, createMongooseAdapter, isMongooseModel };
+export type { CleanDoc, InferAdapterDoc, InferMongooseDoc, InferRepoDoc, MatchingModel, MongooseAdapterOptions, MongooseDocument, MongooseSchemaType };

package/dist/adapter/index.mjs

@@ -1 +1 @@
-export { t as MongooseAdapter, n as createMongooseAdapter, r as isMongooseModel } from "../adapter-CkMoMF83.mjs";
+export { t as MongooseAdapter, n as createMongooseAdapter, r as isMongooseModel } from "../adapter-Qzgc3ZD_.mjs";

package/dist/{adapter-CkMoMF83.mjs → adapter-Qzgc3ZD_.mjs}

@@ -1,17 +1,16 @@
-import { n as warn } from "./logger-K7dPmu2U.mjs";
-import { t as buildCrudSchemasFromModel } from "./mongooseToJsonSchema-C3k4ide0.mjs";
+import { n as warn } from "./logger-hbWOlj_X.mjs";
+import { t as buildCrudSchemasFromModel } from "./mongooseToJsonSchema-DMDotz4_.mjs";
 import { matchesRecordFilter } from "@classytic/repo-core/filter";
 import { mergeFieldRuleConstraints } from "@classytic/repo-core/schema";
 import { asRepositoryLike, isRepository } from "@classytic/repo-core/adapter";
-//#region src/adapter/types.ts
+// src/adapter/types.ts
 /**
 * Runtime guard: is `value` a Mongoose model?
 */
 function isMongooseModel(value) {
 	return typeof value === "function" && value.prototype && "modelName" in value && "schema" in value;
 }
-//#endregion
-//#region src/adapter/mongoose-adapter.ts
+// src/adapter/mongoose-adapter.ts
 const REQUIRED_REPO_METHODS = [
 	"getAll",
 	"getById",
@@ -325,5 +324,4 @@ function createMongooseAdapter(modelOrOptions, repository) {
 	}
 	return new MongooseAdapter(modelOrOptions);
 }
-//#endregion
 export { createMongooseAdapter as n, isMongooseModel as r, MongooseAdapter as t };