@classytic/mongokit 3.40.0 → 3.40.1

package/dist/plugins/index.d.mts

@@ -1,6 +1,6 @@
-import { S as RepositoryPluginName, b as MONGOKIT_PLUGIN_NAMES, l as Plugin, x as MongoKitPluginName } from "../repository-odl03582.mjs";
-import { A as EnsureAuditTrailReadyOptions, C as AuditQueryOptions, D as AuditTrailOptions, E as AuditTrailMode, M as ensureAuditTrailReady, O as AuditTrailQuery, S as AuditOperation, T as AuditTrailMethods, _ as CacheOptions, a as DateSequentialIdOptions, b as cachePlugin, c as SequentialIdOptions, f as getNextSequence, g as CacheAdapter, h as sequentialId, i as CustomIdOptions, j as auditTrailPlugin, k as AuditTrailQueryOptions, l as customIdPlugin, o as IdGenerator, p as prefixedId, r as multiTenantPlugin, s as PrefixedIdOptions, t as MultiTenantOptions, u as dateSequentialId, v as RepositoryCacheHandle, w as AuditQueryResult, x as AuditEntry, y as RepositoryCachePluginOptions } from "../multi-tenant.plugin-CBgCo9im.mjs";
-import { A as IdempotencyStoreMethods, B as batchOperationsPlugin, C as LeaseMethods, D as ImmutableStatesPluginOptions, E as ImmutableClaimView, F as elasticSearchPlugin, G as aggregateHelpersPlugin, H as AppendOnlyPluginOptions, I as cascadePlugin, L as BatchOperationsMethods, M as idempotencyStorePlugin, N as fieldFilterPlugin, O as immutableStatesPlugin, P as ElasticSearchOptions, S as methodRegistryPlugin, T as leasePlugin, U as appendOnlyPlugin, V as auditLogPlugin, W as AggregateHelpersMethods, _ as OperationMetric, a as requireField, b as mongoOperationsPlugin, c as timestampPlugin, d as createTenantContext, f as SubdocumentMethods, g as ObservabilityOptions, h as softDeletePlugin, i as immutableField, j as IdempotencyStorePluginOptions, k as IdempotencyClaim, l as TenantContext, m as SoftDeleteMethods, n as autoInject, o as uniqueField, p as subdocumentPlugin, r as blockIf, s as validationChainPlugin, t as OperationType, u as TenantStore, v as observabilityPlugin, w as LeasePluginOptions, x as MethodRegistryRepository, y as MongoOperationsMethods } from "../validation-chain.plugin-DYp9E7K2.mjs";
+import { S as RepositoryPluginName, b as MONGOKIT_PLUGIN_NAMES, l as Plugin, x as MongoKitPluginName } from "../repository-DNHfjAZX.mjs";
+import { A as EnsureAuditTrailReadyOptions, C as AuditQueryOptions, D as AuditTrailOptions, E as AuditTrailMode, M as ensureAuditTrailReady, O as AuditTrailQuery, S as AuditOperation, T as AuditTrailMethods, _ as CacheOptions, a as DateSequentialIdOptions, b as cachePlugin, c as SequentialIdOptions, f as getNextSequence, g as CacheAdapter, h as sequentialId, i as CustomIdOptions, j as auditTrailPlugin, k as AuditTrailQueryOptions, l as customIdPlugin, o as IdGenerator, p as prefixedId, r as multiTenantPlugin, s as PrefixedIdOptions, t as MultiTenantOptions, u as dateSequentialId, v as RepositoryCacheHandle, w as AuditQueryResult, x as AuditEntry, y as RepositoryCachePluginOptions } from "../multi-tenant.plugin-a3UhQARj.mjs";
+import { A as IdempotencyStoreMethods, B as batchOperationsPlugin, C as LeaseMethods, D as ImmutableStatesPluginOptions, E as ImmutableClaimView, F as elasticSearchPlugin, G as aggregateHelpersPlugin, H as AppendOnlyPluginOptions, I as cascadePlugin, L as BatchOperationsMethods, M as idempotencyStorePlugin, N as fieldFilterPlugin, O as immutableStatesPlugin, P as ElasticSearchOptions, S as methodRegistryPlugin, T as leasePlugin, U as appendOnlyPlugin, V as auditLogPlugin, W as AggregateHelpersMethods, _ as OperationMetric, a as requireField, b as mongoOperationsPlugin, c as timestampPlugin, d as createTenantContext, f as SubdocumentMethods, g as ObservabilityOptions, h as softDeletePlugin, i as immutableField, j as IdempotencyStorePluginOptions, k as IdempotencyClaim, l as TenantContext, m as SoftDeleteMethods, n as autoInject, o as uniqueField, p as subdocumentPlugin, r as blockIf, s as validationChainPlugin, t as OperationType, u as TenantStore, v as observabilityPlugin, w as LeasePluginOptions, x as MethodRegistryRepository, y as MongoOperationsMethods } from "../validation-chain.plugin-CTcNJCmV.mjs";
 import { ChangeLogStore } from "@classytic/repo-core/sync";
 //#region src/plugins/change-log.plugin.d.ts
 interface ChangeLogPluginOptions {

package/dist/plugins/index.mjs

@@ -1,6 +1,6 @@
-import { _ as AuditTrailQuery, b as auditLogPlugin, f as getNextSequence, g as cachePlugin, h as sequentialId, i as multiTenantPlugin, l as customIdPlugin, n as softDeletePlugin, p as prefixedId, t as timestampPlugin, u as dateSequentialId, v as auditTrailPlugin, y as ensureAuditTrailReady } from "../timestamp.plugin-DF0gJB6p.mjs";
+import { _ as AuditTrailQuery, b as auditLogPlugin, f as getNextSequence, g as cachePlugin, h as sequentialId, i as multiTenantPlugin, l as customIdPlugin, n as softDeletePlugin, p as prefixedId, t as timestampPlugin, u as dateSequentialId, v as auditTrailPlugin, y as ensureAuditTrailReady } from "../timestamp.plugin-zfdLYZiO.mjs";
 import { n as batchOperationsPlugin, t as methodRegistryPlugin } from "../method-registry.plugin-C63pGn1d.mjs";
-import { _ as cascadePlugin, a as uniqueField, c as subdocumentPlugin, d as mongoOperationsPlugin, f as leasePlugin, g as elasticSearchPlugin, h as fieldFilterPlugin, i as requireField, l as observabilityPlugin, m as idempotencyStorePlugin, n as blockIf, o as validationChainPlugin, p as immutableStatesPlugin, r as immutableField, s as createTenantContext, t as autoInject, u as MONGOKIT_PLUGIN_NAMES, v as appendOnlyPlugin, y as aggregateHelpersPlugin } from "../validation-chain.plugin-BLY2gLEk.mjs";
+import { _ as cascadePlugin, a as uniqueField, c as subdocumentPlugin, d as mongoOperationsPlugin, f as leasePlugin, g as elasticSearchPlugin, h as fieldFilterPlugin, i as requireField, l as observabilityPlugin, m as idempotencyStorePlugin, n as blockIf, o as validationChainPlugin, p as immutableStatesPlugin, r as immutableField, s as createTenantContext, t as autoInject, u as MONGOKIT_PLUGIN_NAMES, v as appendOnlyPlugin, y as aggregateHelpersPlugin } from "../validation-chain.plugin-CHUHWMtk.mjs";
 //#region src/plugins/change-log.plugin.ts
 const PLUGIN_NAME = "changeLog";
 /** Marks a repository already captured: the store and scope it writes to. */

package/dist/query-defaults-BxUcSOoF.mjs

@@ -0,0 +1,208 @@
+import { t as createError } from "./error-BuByZwKU.mjs";
+import mongoose from "mongoose";
+//#region src/repository/query-defaults.ts
+/**
+* Query defaults — the time bound and read/write concerns every repository command carries.
+*
+* Resolution, per option: per call → repository (`RepositoryOptions.queryDefaults` /
+* `aggregateDefaults`) → deployment (`configureQueryDefaults` / `configureAggregateDefaults`).
+* An explicit value always wins (FL1). For an aggregation the aggregate chain is consulted before
+* the generic query chain, because it is the more specific instruction.
+*
+* The bound travels as per-op CSOT `timeoutMS` (the driver derives the wire `maxTimeMS` from
+* it, and a client-level `timeoutMS` cannot override it). It and `comment` go to the commands Mongoose itself bounds with its global `maxTimeMS`
+* (find, findOne, countDocuments, distinct, findOneAndUpdate, aggregate:
+* lib/query.js:2465,2812,2905,3074,3610; lib/aggregate.js:1106). Writes get `writeConcern`. The
+* connection's CSOT `timeoutMS` bounds everything else; {@link assertQueryDefaultsConfigured}
+* checks both at boot. Inside a transaction a DEFAULT read/write concern or read preference is
+* dropped (the transaction owns them); a per-call one is passed and the driver judges it.
+*/
+/** On `globalThis`, for the reason `pagination/defaults.ts` gives: a duplicated install must share it. */
+const POLICY_SLOT = Symbol.for("classytic.mongokit.queryDefaults");
+function policy() {
+	const holder = globalThis;
+	holder[POLICY_SLOT] ??= {
+		query: {},
+		aggregate: {}
+	};
+	return holder[POLICY_SLOT];
+}
+function defined(input) {
+	return Object.fromEntries(Object.entries(input).filter(([, v]) => v !== void 0));
+}
+function assertPositive(name, value) {
+	if (value !== void 0 && !(Number.isFinite(value) && value > 0)) throw new TypeError(`[mongokit] ${name} must be a positive number of milliseconds, got ${value}`);
+}
+/** Set the deployment's query defaults. Merges; an explicit `undefined` changes nothing. */
+function configureQueryDefaults(defaults) {
+	assertPositive("queryDefaults.maxTimeMS", defaults.maxTimeMS);
+	Object.assign(policy().query, defined(defaults));
+}
+/** Set the deployment's aggregation defaults. Merges; an explicit `undefined` changes nothing. */
+function configureAggregateDefaults(defaults) {
+	assertPositive("aggregateDefaults.maxTimeMs", defaults.maxTimeMs);
+	Object.assign(policy().aggregate, defined(defaults));
+}
+/** A copy of the deployment defaults. */
+function getQueryDefaults() {
+	const p = policy();
+	return {
+		query: { ...p.query },
+		aggregate: { ...p.aggregate }
+	};
+}
+/** Back to no deployment defaults. For tests. */
+function resetQueryDefaults() {
+	const holder = globalThis;
+	holder[POLICY_SLOT] = {
+		query: {},
+		aggregate: {}
+	};
+}
+/**
+* Boot check (M7): throws unless the deployment sets a query `maxTimeMS`, and — when a connection
+* is passed — unless its client carries a CSOT `timeoutMS`. Returns what it verified.
+*/
+function assertQueryDefaultsConfigured(connection) {
+	const maxTimeMS = policy().query.maxTimeMS;
+	if (maxTimeMS === void 0) throw createError(500, "[mongokit] no deployment query time bound: call configureQueryDefaults({ maxTimeMS }) at boot", {
+		code: QUERY_DEFAULTS_ERROR_CODES.NOT_CONFIGURED,
+		meta: { missing: "maxTimeMS" }
+	});
+	if (!connection) return { maxTimeMS };
+	const timeoutMS = connection.getClient().options.timeoutMS;
+	if (!(typeof timeoutMS === "number" && timeoutMS > 0)) throw createError(500, "[mongokit] the connection has no CSOT timeoutMS: pass { timeoutMS } to mongoose.connect()", {
+		code: QUERY_DEFAULTS_ERROR_CODES.NOT_CONFIGURED,
+		meta: { missing: "timeoutMS" }
+	});
+	return {
+		maxTimeMS,
+		timeoutMS
+	};
+}
+const QUERY_DEFAULTS_ERROR_CODES = {
+	NOT_CONFIGURED: "mongokit.query_defaults.not_configured",
+	/** A per-call bound inside a transaction that carries its own CSOT budget (the driver forbids both). */
+	TIMEOUT_IN_TRANSACTION: "mongokit.query_defaults.timeout_in_transaction"
+};
+const TX_DEADLINE = Symbol.for("@classytic/mongokit/transaction-deadline");
+/**
+* Set (or clear) the transaction budget's deadline (`performance.now()` ms) on a session.
+* `runTransaction` sets it for each attempt; every mongokit op on the session is then bounded
+* by what remains of it, so a transaction budget is ONE budget, as with the driver's own.
+*/
+function setTransactionDeadline(session, deadline) {
+	Object.defineProperty(session, TX_DEADLINE, {
+		value: deadline,
+		writable: true,
+		configurable: true,
+		enumerable: false
+	});
+}
+function transactionRemaining(session) {
+	if (!session || typeof session !== "object") return void 0;
+	const deadline = session[TX_DEADLINE];
+	return deadline === void 0 ? void 0 : Math.floor(deadline - performance.now());
+}
+function inTransaction(session) {
+	const s = session;
+	return typeof s?.inTransaction === "function" && s.inTransaction();
+}
+/**
+* A `withTransaction` running under a CSOT budget: the driver refuses any per-op `timeoutMS`
+* there (mongodb lib/utils.js:451, `session.explicit && session.timeoutContext != null`).
+*/
+function csotTransaction(session) {
+	const s = session;
+	return inTransaction(session) && s?.explicit === true && s.timeoutContext != null;
+}
+/** Resolve the options one command runs with. `repo` is the repository's own defaults. */
+function resolveQueryOptions(kind, perCall, repo = {}) {
+	const deployment = policy();
+	const q = {
+		...deployment.query,
+		...defined(repo.query ?? {})
+	};
+	const agg = {
+		...deployment.aggregate,
+		...defined(repo.aggregate ?? {})
+	};
+	const tx = inTransaction(perCall.session);
+	const out = {};
+	const budget = tx ? transactionRemaining(perCall.session) : void 0;
+	if (budget !== void 0 && budget <= 0) throw new mongoose.mongo.MongoOperationTimeoutError("Transaction budget exhausted before this operation");
+	if (kind !== "write") {
+		if (csotTransaction(perCall.session) && perCall.maxTimeMS !== void 0) throw createError(400, "[mongokit] a per-call maxTimeMS cannot be honoured inside a transaction with its own timeoutMS budget; bound the transaction instead", { code: QUERY_DEFAULTS_ERROR_CODES.TIMEOUT_IN_TRANSACTION });
+		const bound = tx ? perCall.maxTimeMS : perCall.maxTimeMS ?? (kind === "aggregate" ? repo.aggregate?.maxTimeMs ?? deployment.aggregate.maxTimeMs : void 0) ?? q.maxTimeMS;
+		const capped = budget === void 0 ? bound : Math.min(bound ?? Number.POSITIVE_INFINITY, budget);
+		if (capped !== void 0) out.maxTimeMS = capped;
+		const comment = perCall.comment ?? q.comment;
+		if (comment !== void 0) out.comment = comment;
+		if (perCall.hint !== void 0) out.hint = perCall.hint;
+	}
+	if (kind === "read" || kind === "aggregate") {
+		const pref = perCall.readPreference ?? (tx ? void 0 : q.readPreference);
+		if (pref !== void 0) out.readPreference = pref;
+		const concern = perCall.readConcern ?? (tx ? void 0 : q.readConcern);
+		if (concern !== void 0) out.readConcern = concern;
+	}
+	if (kind === "aggregate") {
+		const disk = perCall.allowDiskUse ?? agg.allowDiskUse;
+		if (disk !== void 0) out.allowDiskUse = disk;
+	}
+	if (kind === "write" && budget !== void 0) out.maxTimeMS = budget;
+	if (kind === "write" || kind === "findAndModify") {
+		const wc = perCall.writeConcern ?? (tx ? void 0 : q.writeConcern);
+		if (wc !== void 0) out.writeConcern = wc;
+	}
+	return out;
+}
+const READ_PREFERENCE_MODES = [
+	"primary",
+	"primaryPreferred",
+	"secondary",
+	"secondaryPreferred",
+	"nearest"
+];
+function isReadPreferenceMode(value) {
+	return READ_PREFERENCE_MODES.includes(value);
+}
+/** A read preference outside the driver's modes is refused, never passed through (FL2). */
+function readPreferenceMode(value) {
+	if (isReadPreferenceMode(value)) return value;
+	throw new TypeError(`[mongokit] unknown readPreference '${value}'; expected one of ${READ_PREFERENCE_MODES.join(", ")}`);
+}
+/** Apply resolved options to a mongoose Query. */
+function applyToQuery(query, o) {
+	if (o.maxTimeMS !== void 0) {
+		const csot = { timeoutMS: o.maxTimeMS };
+		query.setOptions(csot);
+	}
+	if (o.comment !== void 0) query.setOptions({ comment: o.comment });
+	if (o.readPreference !== void 0) query.read(readPreferenceMode(o.readPreference));
+	if (o.readConcern !== void 0) query.readConcern(o.readConcern);
+	if (o.writeConcern !== void 0) query.setOptions({ writeConcern: o.writeConcern });
+	if (o.hint !== void 0) query.hint(o.hint);
+}
+/**
+* Make a find cursor's bound apply PER BATCH (CSOT `timeoutMode: 'iteration'`). Only when some
+* `timeoutMS` exists (this op's, or the client's): the driver refuses a timeoutMode without one
+* (mongodb lib/cursor/abstract_cursor.js:114). In iteration mode the driver enforces the budget
+* client-side per batch and sends no wire maxTimeMS.
+*/
+function applyCursorTimeoutMode(query, o, connection) {
+	const clientTimeout = connection.getClient().options.timeoutMS;
+	if (o.maxTimeMS === void 0 && clientTimeout === void 0) return;
+	query.setOptions({ timeoutMode: "iteration" });
+}
+/** Apply resolved options to a mongoose Aggregate. */
+function applyToAggregate(aggregation, o) {
+	if (o.maxTimeMS !== void 0) aggregation.option({ timeoutMS: o.maxTimeMS });
+	if (o.comment !== void 0) aggregation.option({ comment: o.comment });
+	if (o.readPreference !== void 0) aggregation.read(readPreferenceMode(o.readPreference));
+	if (o.readConcern !== void 0) aggregation.readConcern(o.readConcern);
+	if (o.allowDiskUse !== void 0) aggregation.allowDiskUse(o.allowDiskUse);
+	if (o.hint !== void 0) aggregation.hint(o.hint);
+}
+//#endregion
+export { assertQueryDefaultsConfigured as a, getQueryDefaults as c, setTransactionDeadline as d, applyToQuery as i, resetQueryDefaults as l, applyCursorTimeoutMode as n, configureAggregateDefaults as o, applyToAggregate as r, configureQueryDefaults as s, QUERY_DEFAULTS_ERROR_CODES as t, resolveQueryOptions as u };

package/dist/read-model/index.d.mts

@@ -0,0 +1,66 @@
+import { r as Repository } from "../Repository-pnLw1rG5.mjs";
+import { BulkUpsertResult } from "@classytic/repo-core/repository";
+//#region src/read-model/index.d.ts
+declare const READ_MODEL_ERROR_CODES: {
+  readonly MERGE_IN_TRANSACTION: "mongokit.read_model.merge_in_transaction";
+  readonly ON_NOT_UNIQUE: "mongokit.read_model.on_not_unique";
+  readonly ON_MISSING_SCOPE: "mongokit.read_model.on_missing_scope";
+  readonly DEDUPE_NEEDS_TRANSACTION: "mongokit.read_model.dedupe_needs_transaction";
+  readonly DEDUPE_KEY_MISSING: "mongokit.read_model.dedupe_key_missing";
+  readonly INCREMENT_FAILED: "mongokit.read_model.increment_failed";
+  readonly TOO_LARGE: "mongokit.read_model.too_large";
+};
+/** Caller scope forwarded to every repository call (tenant, bypass, attribution). */
+type ReadModelScope = Record<string, unknown>;
+interface IncrementGrain {
+  /** The read-model key (without the policy scope, which the repository adds). */
+  key: Record<string, unknown>;
+  inc: Record<string, number>;
+  setOnInsert?: Record<string, unknown>;
+  /** Identity of the event this grain comes from; required when a ledger is given. */
+  dedupeKey?: string;
+}
+/** Sum grains per key, apply them in one upsert; with a ledger, count each dedupeKey once. */
+declare function applyIncrements<TDoc>(target: Repository<TDoc>, grains: readonly IncrementGrain[], options?: ReadModelScope & {
+  session?: unknown;
+  /** Repository over a collection unique on (scope, `dedupeKey`). */
+  ledger?: Repository<unknown>;
+}): Promise<BulkUpsertResult>;
+interface RebuildOptions {
+  /** Source stages producing one row per read-model grain (with every `on` field except scope fields). */
+  pipeline: readonly unknown[];
+  /** Fields identifying a grain; must equal a unique index of the target and include its tenant field. */
+  on: readonly string[];
+  whenMatched?: 'replace' | 'merge';
+  /** Caller scope (tenant etc.), applied to the source read and stamped on the target rows. */
+  scope?: ReadModelScope;
+  session?: unknown;
+}
+/** Rebuild the scope's slice of `target` from `source` with one `$merge`, then drop stale grains. */
+declare function rebuildInto<TSrc, TDoc>(source: Repository<TSrc>, target: Repository<TDoc>, options: RebuildOptions): Promise<{
+  rebuildId: string;
+  removed: number;
+}>;
+interface ReconcileOptions {
+  pipeline: readonly unknown[];
+  on: readonly string[];
+  /** Fields compared between the recomputed and the stored row. */
+  measures: readonly string[];
+  scope?: ReadModelScope;
+  /** Refuse past this many rows on either side (both are held in memory). Default 100,000. */
+  maxRows?: number;
+}
+interface DriftRow {
+  key: Record<string, unknown>;
+  /** Recomputed measures, `null` when the source produces no such grain. */
+  expected: Record<string, unknown> | null;
+  /** Stored measures, `null` when the read model lacks the grain. */
+  actual: Record<string, unknown> | null;
+}
+/** Recompute the scope's grains from `source` and report every one that differs in `target`. */
+declare function reconcile<TSrc, TDoc>(source: Repository<TSrc>, target: Repository<TDoc>, options: ReconcileOptions): Promise<{
+  drift: DriftRow[];
+  compared: number;
+}>;
+//#endregion
+export { DriftRow, IncrementGrain, READ_MODEL_ERROR_CODES, ReadModelScope, RebuildOptions, ReconcileOptions, applyIncrements, rebuildInto, reconcile };

package/dist/read-model/index.mjs

@@ -0,0 +1,193 @@
+import { t as createError } from "../error-BuByZwKU.mjs";
+import { i as scopeForCollection, o as tenantFieldsOf } from "../join-scope-DSAznE8E.mjs";
+import { randomUUID } from "node:crypto";
+//#region src/read-model/index.ts
+/**
+* `@classytic/mongokit/read-model` — maintain and verify a derived (read) collection.
+*
+* - {@link applyIncrements}: grains summed per key, then ONE `bulkUpsert` (`$inc` + `$setOnInsert`)
+*   inside the caller's unit of work. With a `ledger`, each grain's `dedupeKey` is recorded in the
+*   SAME transaction and a key already recorded is skipped, so a replayed event counts once.
+* - {@link rebuildInto}: the source pipeline (scoped by the source repository) ends in a `$merge`
+*   on a unique `on`; grains of the scope the source no longer produces are then removed.
+*   `$merge` cannot run in a transaction, so a session inside one is refused.
+* - {@link reconcile}: recompute from the source and compare with the read model; returns drift.
+*/
+const READ_MODEL_ERROR_CODES = {
+	MERGE_IN_TRANSACTION: "mongokit.read_model.merge_in_transaction",
+	ON_NOT_UNIQUE: "mongokit.read_model.on_not_unique",
+	ON_MISSING_SCOPE: "mongokit.read_model.on_missing_scope",
+	DEDUPE_NEEDS_TRANSACTION: "mongokit.read_model.dedupe_needs_transaction",
+	DEDUPE_KEY_MISSING: "mongokit.read_model.dedupe_key_missing",
+	INCREMENT_FAILED: "mongokit.read_model.increment_failed",
+	TOO_LARGE: "mongokit.read_model.too_large"
+};
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function inTransaction(session) {
+	const s = session;
+	return typeof s?.inTransaction === "function" && s.inTransaction();
+}
+/** Sum grains per key, apply them in one upsert; with a ledger, count each dedupeKey once. */
+async function applyIncrements(target, grains, options = {}) {
+	const { ledger, ...scope } = options;
+	let live = grains;
+	if (ledger) {
+		if (!inTransaction(scope.session)) throw createError(500, "[mongokit] applyIncrements: a dedupe ledger is only correct inside a transaction", { code: READ_MODEL_ERROR_CODES.DEDUPE_NEEDS_TRANSACTION });
+		if (grains.some((g) => !g.dedupeKey)) throw createError(400, "[mongokit] applyIncrements: every grain needs a dedupeKey when a ledger is given", { code: READ_MODEL_ERROR_CODES.DEDUPE_KEY_MISSING });
+		const keys = [...new Set(grains.flatMap((g) => g.dedupeKey ? [g.dedupeKey] : []))];
+		const seen = new Set((await ledger.findAll({ dedupeKey: { $in: keys } }, {
+			...scope,
+			select: "dedupeKey",
+			lean: true
+		})).map((d) => d).filter(isRecord).map((d) => String(d.dedupeKey)));
+		const fresh = keys.filter((k) => !seen.has(k));
+		if (fresh.length > 0) await ledger.createMany(fresh.map((dedupeKey) => ({ dedupeKey })), scope);
+		const freshSet = new Set(fresh);
+		const taken = /* @__PURE__ */ new Set();
+		live = grains.filter((g) => {
+			const k = g.dedupeKey;
+			if (!k || !freshSet.has(k) || taken.has(k)) return false;
+			taken.add(k);
+			return true;
+		});
+	}
+	if (live.length === 0) return {
+		results: [],
+		inserted: 0,
+		updated: 0,
+		unchanged: 0,
+		failed: 0
+	};
+	const summed = /* @__PURE__ */ new Map();
+	for (const g of live) {
+		const id = JSON.stringify(Object.keys(g.key).sort().map((k) => [k, g.key[k]]));
+		const slot = summed.get(id) ?? {
+			key: g.key,
+			inc: {},
+			setOnInsert: { ...g.setOnInsert }
+		};
+		for (const [field, n] of Object.entries(g.inc)) slot.inc[field] = (slot.inc[field] ?? 0) + n;
+		summed.set(id, slot);
+	}
+	const rows = [...summed.values()].map((s) => ({
+		...s.key,
+		...s.inc,
+		...s.setOnInsert
+	}));
+	const first = [...summed.values()][0];
+	const result = await target.bulkUpsert(rows, {
+		...scope,
+		key: Object.keys(first?.key ?? {}),
+		inc: [...new Set([...summed.values()].flatMap((s) => Object.keys(s.inc)))],
+		setOnInsert: [...new Set([...summed.values()].flatMap((s) => Object.keys(s.setOnInsert)))]
+	});
+	if (result.failed > 0) throw createError(500, `[mongokit] applyIncrements: ${result.failed} grain(s) failed; the unit of work must abort`, {
+		code: READ_MODEL_ERROR_CODES.INCREMENT_FAILED,
+		meta: { failures: result.results.filter((r) => r.outcome === "failed") }
+	});
+	return result;
+}
+function contextOf(scope) {
+	return {
+		operation: "aggregatePipeline",
+		model: "read-model",
+		...scope
+	};
+}
+/** The target's policy predicate for this scope (tenant + live docs), as equality fields. */
+function targetScope(target, scope) {
+	const predicate = scopeForCollection(target.Model.collection.collectionName, {
+		connection: target.Model.db,
+		context: contextOf(scope),
+		operation: "aggregatePipeline"
+	});
+	if (!predicate) return {};
+	const parts = Array.isArray(predicate.$and) ? predicate.$and.filter(isRecord) : [predicate];
+	return Object.assign({}, ...parts);
+}
+/** Rebuild the scope's slice of `target` from `source` with one `$merge`, then drop stale grains. */
+async function rebuildInto(source, target, options) {
+	const scope = options.scope ?? {};
+	if (inTransaction(options.session)) throw createError(500, "[mongokit] rebuildInto: $merge cannot run inside a transaction", { code: READ_MODEL_ERROR_CODES.MERGE_IN_TRANSACTION });
+	const on = [...options.on];
+	const missing = tenantFieldsOf(target.Model).filter((f) => !on.includes(f));
+	if (missing.length > 0) throw createError(400, `[mongokit] rebuildInto: 'on' must include the target's tenant field(s) ${missing.join(", ")}`, { code: READ_MODEL_ERROR_CODES.ON_MISSING_SCOPE });
+	if (!target.Model.schema.indexes().some(([fields, opts]) => opts.unique === true && sameSet(Object.keys(fields), on))) throw createError(400, `[mongokit] rebuildInto: $merge needs a unique index on exactly (${on.join(", ")})`, { code: READ_MODEL_ERROR_CODES.ON_NOT_UNIQUE });
+	const rebuildId = randomUUID();
+	const stamp = {
+		...targetScope(target, scope),
+		_rebuildId: rebuildId
+	};
+	const stages = [
+		...options.pipeline,
+		{ $set: stamp },
+		{ $merge: {
+			into: target.Model.collection.collectionName,
+			on,
+			whenMatched: options.whenMatched ?? "replace",
+			whenNotMatched: "insert"
+		} }
+	];
+	await source.aggregatePipeline(stages, {
+		...scope,
+		...options.session ? { session: options.session } : {}
+	});
+	return {
+		rebuildId,
+		removed: (await target.deleteMany({ _rebuildId: { $ne: rebuildId } }, {
+			...scope,
+			...options.session ? { session: options.session } : {}
+		})).deletedCount
+	};
+}
+function sameSet(a, b) {
+	return a.length === b.length && a.every((x) => b.includes(x));
+}
+function canonical(value) {
+	if (value === null || value === void 0) return "null";
+	if (isRecord(value) && value._bsontype === "Decimal128") return String(Number(String(value)));
+	return JSON.stringify(value);
+}
+/** Recompute the scope's grains from `source` and report every one that differs in `target`. */
+async function reconcile(source, target, options) {
+	const scope = options.scope ?? {};
+	const maxRows = options.maxRows ?? 1e5;
+	const stamp = targetScope(target, scope);
+	const keyFields = options.on.filter((f) => !(f in stamp));
+	const pick = (row, fields) => Object.fromEntries(fields.map((f) => [f, row[f] ?? null]));
+	const id = (row) => keyFields.map((f) => canonical(row[f])).join("|");
+	const expectedRows = await source.aggregatePipeline([...options.pipeline, { $limit: maxRows + 1 }], scope);
+	const actualRows = (await target.findAll({}, {
+		...scope,
+		select: [...keyFields, ...options.measures].join(" "),
+		limit: maxRows + 1,
+		lean: true
+	})).map((d) => d).filter(isRecord);
+	if (expectedRows.length > maxRows || actualRows.length > maxRows) throw createError(500, `[mongokit] reconcile: more than ${maxRows} grains in scope; reconcile a narrower scope`, { code: READ_MODEL_ERROR_CODES.TOO_LARGE });
+	const actual = new Map(actualRows.map((r) => [id(r), r]));
+	const drift = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const e of expectedRows) {
+		const k = id(e);
+		seen.add(k);
+		const a = actual.get(k);
+		if (!a || options.measures.some((m) => canonical(e[m]) !== canonical(a[m]))) drift.push({
+			key: pick(e, keyFields),
+			expected: pick(e, options.measures),
+			actual: a ? pick(a, options.measures) : null
+		});
+	}
+	for (const [k, a] of actual) if (!seen.has(k)) drift.push({
+		key: pick(a, keyFields),
+		expected: null,
+		actual: pick(a, options.measures)
+	});
+	return {
+		drift,
+		compared: expectedRows.length
+	};
+}
+//#endregion
+export { READ_MODEL_ERROR_CODES, applyIncrements, rebuildInto, reconcile };

package/dist/{repository-odl03582.d.mts → repository-DNHfjAZX.d.mts}

@@ -1,4 +1,4 @@
-import { _ as PopulateSpec, g as ObjectId, h as FilterQuery, i as CountStrategy, p as AnyDocument, v as ReadPreferenceType, x as SortSpec, y as SelectSpec } from "./pagination-BpIv2bdS.mjs";
+import { A as ObjectId, D as AnyDocument, F as SortSpec, M as ReadPreferenceType, N as SelectSpec, _ as QueryDefaults, b as WriteConcernSpec, i as CountStrategy, j as PopulateSpec, k as FilterQuery, p as AggregateDefaults, v as ReadConcernLevel } from "./pagination-D6psses0.mjs";
 import { r as DocField } from "./type-utils-CLzRFtIA.mjs";
 import { DistributionConfig, DistributionMissHandler, RepoCapabilities, RepositoryBase } from "@classytic/repo-core/repository";
 import { Model, PipelineStage } from "mongoose";
@@ -199,6 +199,13 @@ interface RepositoryOptions {
    * ```
    */
   requirePlugins?: readonly RepositoryPluginName[];
+  /**
+   * Time bound and concerns for every command this repository issues. A per-call value
+   * wins; unset fields fall back to `configureQueryDefaults` (see `repository/query-defaults.ts`).
+   */
+  queryDefaults?: QueryDefaults;
+  /** Aggregation-only defaults, consulted before `queryDefaults`. */
+  aggregateDefaults?: AggregateDefaults;
   /**
    * Declare the collection's shard key so every filter-taking verb
    * (`getAll`, `findAll`, `getOne`, `count`, `updateMany`, `aggregate`, …)
@@ -327,6 +334,13 @@ interface RepositoryContext {
   hint?: string | Record<string, 1 | -1>;
   /** Maximum execution time in milliseconds */
   maxTimeMS?: number;
+  /** Per-call read concern / comment / write concern / disk use (see `queryDefaults`). */
+  readConcern?: ReadConcernLevel;
+  comment?: string;
+  writeConcern?: WriteConcernSpec;
+  allowDiskUse?: boolean;
+  /** Collections the caller asserts are company-wide (joins only). */
+  unscopedJoins?: readonly string[];
   /** Count strategy for offset pagination. See {@link CountStrategy}. */
   countStrategy?: CountStrategy;
   /** Ceiling for `countStrategy: 'capped'` (default 10000). */
@@ -447,7 +461,7 @@ interface RepositoryInstance extends RepositoryBase {
   [key: string]: unknown;
 }
 /** Repository operation names */
-type RepositoryOperation = 'create' | 'createMany' | 'update' | 'updateMany' | 'findOneAndUpdate' | 'delete' | 'deleteMany' | 'restore' | 'getById' | 'getByQuery' | 'getOne' | 'getAll' | 'findAll' | 'getOrCreate' | 'count' | 'exists' | 'distinct' | 'aggregate' | 'aggregatePaginate' | 'aggregatePipeline' | 'aggregatePipelinePaginate' | 'lookupPopulate' | 'bulkWrite' | 'claim' | 'claimVersion' | 'cursor' | 'watch';
+type RepositoryOperation = 'create' | 'createMany' | 'update' | 'updateMany' | 'findOneAndUpdate' | 'delete' | 'deleteMany' | 'restore' | 'getById' | 'getByQuery' | 'getOne' | 'getAll' | 'findAll' | 'getOrCreate' | 'count' | 'exists' | 'distinct' | 'aggregate' | 'aggregatePaginate' | 'aggregatePipeline' | 'aggregatePipelinePaginate' | 'lookupPopulate' | 'bulkWrite' | 'bulkUpsert' | 'claim' | 'claimVersion' | 'cursor' | 'iterate' | 'watch';
 /** Event lifecycle phases */
 type EventPhase = 'before' | 'after' | 'error';
 /** Repository event names (generated from template literals) */

package/dist/sync/index.d.mts

@@ -14,7 +14,20 @@ interface ChangeLogModels {
   feed: string;
 }
 declare function createChangeLogModels(connection: Connection, options?: ChangeLogModelOptions): ChangeLogModels;
-declare function createChangeLogStore(models: ChangeLogModels): ChangeLogStore;
+/** The mongo change feed: the `ChangeLogStore` contract plus superseded-entry compaction. */
+interface MongoChangeLogStore extends ChangeLogStore {
+  /**
+   * Delete every entry a later COMMITTED entry of the same `(scope, docId)` replaced. Safe for any client
+   * cursor: entries carry whole documents, so a reader only ever needs the latest one; tombstones and
+   * each document's latest entry stay. Idempotent; run it on a schedule.
+   */
+  compactSuperseded(options?: {
+    batchSize?: number;
+  }): Promise<{
+    removed: number;
+  }>;
+}
+declare function createChangeLogStore(models: ChangeLogModels): MongoChangeLogStore;
 interface CommandStreamModelOptions {
   /** Collection prefix: `<prefix>_streams`, `<prefix>_verdicts`, `<prefix>_aliases`. Default `sync`. */
   prefix?: string;
@@ -37,4 +50,4 @@ interface MongoCommandStreamTx extends CommandStreamTx {
  */
 declare function createCommandStreamStore(connection: Pick<Connection, 'startSession'>, models: CommandStreamModels, changes: ChangeLogStore): CommandStreamStore<MongoCommandStreamTx>;
 //#endregion
-export { ChangeLogModelOptions, ChangeLogModels, CommandStreamModelOptions, CommandStreamModels, MongoCommandStreamTx, createChangeLogModels, createChangeLogStore, createCommandStreamModels, createCommandStreamStore };
+export { ChangeLogModelOptions, ChangeLogModels, CommandStreamModelOptions, CommandStreamModels, MongoChangeLogStore, MongoCommandStreamTx, createChangeLogModels, createChangeLogStore, createCommandStreamModels, createCommandStreamStore };

package/dist/sync/index.mjs

@@ -1,4 +1,4 @@
-import { i as withTransaction } from "../transaction-B5L9glO0.mjs";
+import { i as withTransaction } from "../transaction-BrRYtH_b.mjs";
 import { Schema } from "mongoose";
 //#region src/sync/index.ts
 function createChangeLogModels(connection, options = {}) {
@@ -49,6 +49,11 @@ function createChangeLogModels(connection, options = {}) {
 				scope: 1,
 				seq: 1
 			}, { name: "tenant_scope_feed" });
+			schema.index({
+				scope: 1,
+				docId: 1,
+				seq: 1
+			}, { name: "doc_versions" });
 			return schema;
 		})()),
 		counter: connection.models[counterName] ?? connection.model(counterName, new Schema({
@@ -138,6 +143,38 @@ function createChangeLogStore(models) {
 		async latestCursor(options = {}) {
 			const row = await entries.findOne(filterOf(0, options)).sort({ seq: -1 }).select({ seq: 1 }).lean().exec();
 			return row?.seq ? toCursor(row.seq) : "";
+		},
+		async compactSuperseded(options = {}) {
+			const batchSize = options.batchSize ?? 1e3;
+			const groups = entries.aggregate([
+				{ $group: {
+					_id: {
+						scope: "$scope",
+						docId: "$docId"
+					},
+					latest: { $max: "$seq" },
+					n: { $sum: 1 }
+				} },
+				{ $match: { n: { $gt: 1 } } },
+				{ $project: { latest: 1 } }
+			]).allowDiskUse(true).cursor({ batchSize });
+			let removed = 0;
+			let ops = [];
+			const flush = async () => {
+				if (ops.length === 0) return;
+				removed += (await entries.bulkWrite(ops, { ordered: false })).deletedCount;
+				ops = [];
+			};
+			for await (const g of groups) {
+				ops.push({ deleteMany: { filter: {
+					scope: g._id.scope,
+					docId: g._id.docId,
+					seq: { $lt: g.latest }
+				} } });
+				if (ops.length >= batchSize) await flush();
+			}
+			await flush();
+			return { removed };
 		}
 	};
 }