@classytic/mongokit 3.29.0 → 3.30.0

package/dist/{Repository-DThvFCaV.mjs → Repository-X7U2d0kU.mjs}

@@ -1,5 +1,5 @@
 import { i as isValidIdForType, t as getSchemaIdType } from "./id-resolution-BqDrk0S2.mjs";
-import { a as count, b as LookupBuilder, c as getByQuery, d as deleteById, f as deleteByQuery, h as createMany, l as getOrCreate, m as create, n as update, o as exists, r as updateByQuery, s as getById, t as findOneAndUpdate, x as compileFilterToMongo, y as distinct } from "./update-CI2NdAW6.mjs";
+import { a as count, b as LookupBuilder, c as getByQuery, d as deleteById, f as deleteByQuery, h as createMany, l as getOrCreate, m as create, n as update, o as exists, r as updateByQuery, s as getById, t as findOneAndUpdate, x as compileFilterToMongo, y as distinct } from "./update-DHdXdOk_.mjs";
 import { n as warn } from "./logger-K7dPmu2U.mjs";
 import { n as isDuplicateKeyError, r as parseDuplicateKeyError, t as createError } from "./error-BuByZwKU.mjs";
 import { t as PaginationEngine } from "./PaginationEngine-CczbvCAq.mjs";
@@ -80,9 +80,7 @@ function createKeysetPurgePort(repo, baseFilter, session) {
 					[strategy.deletedAtField ?? "deletedAt"]: /* @__PURE__ */ new Date()
 				} }, baseOpts);
 				break;
-			case "anonymize":
-				await repo.updateMany(chunkFilter, { $set: strategy.fields }, baseOpts);
-				break;
+			case "anonymize": await repo.updateMany(chunkFilter, { $set: strategy.fields }, baseOpts);
 		}
 		cursor = ids[ids.length - 1];
 		return idDocs.length;
@@ -127,21 +125,44 @@ async function purgeAnonymizeFunctional(repo, selectFilter, fields, limit, sessi
 }
 //#endregion
 //#region src/capabilities.ts
-const MONGOKIT_CAPABILITIES = {
+/**
+* Read the provenance of a capability descriptor's `transactions` flag.
+* A descriptor without the field is a static declaration (`'declared'`) —
+* which is exactly right for sqlitekit / prismakit / any kit whose answer
+* genuinely does not depend on a live deployment.
+*/
+function transactionResolutionOf(caps) {
+	const value = caps.transactionsResolution;
+	return value === "observed" || value === "unknown" ? value : "declared";
+}
+/**
+* What MongoDB supports through mongokit's surface, DECLARED (not observed).
+*
+* Deployment-dependent flags (`transactions`, `nestedTransactions`,
+* `changeStreams` — all three need a replica set or mongos) are `true` here
+* because they describe the product, not the server you happen to be pointed
+* at. **Do not read this constant to decide whether a live connection can run
+* a transaction** — that is {@link resolveMongoCapabilities}, which is what
+* `Repository#capabilities` returns. This one is for the cross-kit conformance
+* harness (which overrides environment-specific limits where it is
+* constructed) and as the base every observed descriptor is derived from.
+*/
+const MONGOKIT_CAPABILITIES = Object.freeze({
+	transactionsResolution: "declared",
 	transactions: true,
 	nestedTransactions: true,
 	upsert: true,
 	duplicateKeyError: true,
 	distinct: true,
 	aggregate: true,
-	aggregateOps: {
+	aggregateOps: Object.freeze({
 		percentile: true,
 		stddev: true,
 		topN: true,
 		customDateBuckets: true,
 		dateBucketSubMinute: true,
 		cache: true
-	},
+	}),
 	getOrCreate: true,
 	countAndExists: true,
 	purgeByField: true,
@@ -153,7 +174,195 @@ const MONGOKIT_CAPABILITIES = {
 	lean: true,
 	lookupPopulate: true,
 	streaming: true
-};
+});
+/**
+* Driver `ServerType`s that positively imply a session-capable, transaction-
+* capable deployment. Verified against mongodb driver 7.x: a single-node
+* replica set reports `RSPrimary` (topology `ReplicaSetWithPrimary`, or
+* `Single` when reached with `directConnection`), a standalone `mongod`
+* reports `Standalone`, and a mongos reports `Mongos`.
+*
+* **This is why the check reads SERVER type, not just topology type.** The
+* pre-existing heuristic (`topology.description.type !== 'Single'`) has a
+* false NEGATIVE: a directly-connected single-node replica set is `Single`
+* yet runs transactions fine.
+*/
+const TRANSACTION_CAPABLE_SERVER_TYPES = /* @__PURE__ */ new Set([
+	"RSPrimary",
+	"RSSecondary",
+	"RSArbiter",
+	"RSOther",
+	"RSGhost",
+	"Mongos",
+	"LoadBalancer"
+]);
+/** Topology types that positively imply transactions regardless of server detail. */
+const TRANSACTION_CAPABLE_TOPOLOGY_TYPES = /* @__PURE__ */ new Set([
+	"ReplicaSetWithPrimary",
+	"ReplicaSetNoPrimary",
+	"Sharded",
+	"LoadBalanced"
+]);
+function clientOf(connection) {
+	const probe = connection;
+	if (!probe || typeof probe !== "object") return void 0;
+	try {
+		return probe.getClient?.() ?? probe.client ?? (probe.topology !== void 0 ? probe : void 0);
+	} catch {
+		return;
+	}
+}
+function serverTypes(description) {
+	const servers = description.servers;
+	if (!servers) return [];
+	return (typeof servers.values === "function" ? [...servers.values()] : Object.values(servers)).map((s) => s?.type).filter((t) => typeof t === "string");
+}
+/**
+* Read whether a connection's LIVE deployment supports multi-document
+* transactions, synchronously, from the driver's SDAM topology description.
+*
+* Free (a few property reads against an object the driver keeps current), so
+* it is deliberately NOT memoized — a connection that opens after the repo was
+* constructed upgrades its own answer with no invalidation step. What IS
+* memoized is the async {@link probeMongoCapabilities} result, which this
+* function consults first so an exotic deployment that answered `hello` but
+* exposes no topology still reports definitively.
+*
+* @returns `'yes'` / `'no'` when the topology is conclusive, `'unknown'`
+*   otherwise — never optimistic. See the module docblock on rule 3.
+*/
+function resolveTransactionSupport(connection) {
+	const cached = readProbeCache(connection);
+	if (cached) return cached;
+	const description = clientOf(connection)?.topology?.description;
+	if (!description) return "unknown";
+	const types = serverTypes(description);
+	if (types.some((t) => TRANSACTION_CAPABLE_SERVER_TYPES.has(t))) return "yes";
+	if (types.length > 0 && types.every((t) => t === "Standalone")) return "no";
+	const topologyType = description.type;
+	if (topologyType && TRANSACTION_CAPABLE_TOPOLOGY_TYPES.has(topologyType)) return "yes";
+	return "unknown";
+}
+function deriveCapabilities(support) {
+	const available = support === "yes";
+	return Object.freeze({
+		...MONGOKIT_CAPABILITIES,
+		transactionsResolution: support === "unknown" ? "unknown" : "observed",
+		transactions: available,
+		nestedTransactions: available,
+		changeStreams: available
+	});
+}
+/** Three possible answers ⇒ three frozen singletons; the getter allocates nothing. */
+const DERIVED = Object.freeze({
+	yes: deriveCapabilities("yes"),
+	no: deriveCapabilities("no"),
+	unknown: deriveCapabilities("unknown")
+});
+/**
+* The capability descriptor for a LIVE connection — what
+* `Repository#capabilities` returns.
+*
+* Every deployment-dependent flag reflects the observed topology; everything
+* else comes from {@link MONGOKIT_CAPABILITIES}. Cheap enough to call per
+* access (topology read + one frozen-object lookup).
+*/
+function resolveMongoCapabilities(connection) {
+	return DERIVED[resolveTransactionSupport(connection)];
+}
+/** The three derived descriptors, for tests and for gates that want to compare identity. */
+function capabilitiesForSupport(support) {
+	return DERIVED[support];
+}
+/** Definitive results only. Keyed on the connection object; never holds `'unknown'`. */
+const PROBE_RESULTS = /* @__PURE__ */ new WeakMap();
+/** In-flight de-duplication so N repos on one connection issue ONE `hello`. */
+const PROBE_INFLIGHT = /* @__PURE__ */ new WeakMap();
+function readProbeCache(connection) {
+	if (!connection || typeof connection !== "object") return void 0;
+	return PROBE_RESULTS.get(connection);
+}
+/** Test seam — drop memoized probe answers (a reused connection object across suites). */
+function resetCapabilityProbeCache(connection) {
+	if (connection && typeof connection === "object") {
+		PROBE_RESULTS.delete(connection);
+		PROBE_INFLIGHT.delete(connection);
+	}
+}
+function withTimeout(promise, ms, onTimeout) {
+	return new Promise((resolve) => {
+		const timer = setTimeout(() => resolve(onTimeout), ms);
+		timer.unref?.();
+		promise.then((value) => {
+			clearTimeout(timer);
+			resolve(value);
+		}, () => {
+			clearTimeout(timer);
+			resolve(onTimeout);
+		});
+	});
+}
+/**
+* Classify a `hello` (or legacy `isMaster`) reply.
+*
+* - `msg: 'isdbgrid'` ⇒ mongos ⇒ transactions (Mongo 4.2+ sharded).
+* - `setName` ⇒ a replica-set member ⇒ transactions.
+* - a reply that IS a hello (`isWritablePrimary` / `ismaster` present) with
+*   neither marker ⇒ standalone ⇒ **no**. Verified: a memory-server standalone
+*   returns `{ isWritablePrimary: true }` and nothing else.
+* - anything unrecognised ⇒ `'unknown'`. A reply we cannot parse is not a yes.
+*/
+function classifyHelloReply(reply) {
+	if (!reply || typeof reply !== "object") return "unknown";
+	const { msg, setName } = reply;
+	if (msg === "isdbgrid") return "yes";
+	if (typeof setName === "string" && setName.length > 0) return "yes";
+	return "isWritablePrimary" in reply || "ismaster" in reply ? "no" : "unknown";
+}
+async function runProbe(connection, timeoutMs) {
+	if (connection.readyState === 2 && typeof connection.asPromise === "function") await withTimeout(connection.asPromise().then(() => void 0, () => void 0), timeoutMs, void 0);
+	const fromTopology = resolveTransactionSupport(connection);
+	if (fromTopology !== "unknown") return fromTopology;
+	const admin = connection.db?.admin?.();
+	if (!admin) return "unknown";
+	return classifyHelloReply(await withTimeout(admin.command({ hello: 1 }).catch(async () => admin.command({ isMaster: 1 }).catch(() => void 0)), timeoutMs, void 0));
+}
+/**
+* Resolve a connection's real capabilities, waiting for (and if necessary
+* asking) the deployment. Memoized per connection: N repositories and N
+* kernels on one connection issue at most ONE `hello`.
+*
+* Hosts do not have to call this — `Repository#capabilities` reads the live
+* topology synchronously, which is already conclusive once
+* `await mongoose.connect()` has returned (the Kernel Construction Standard's
+* Describe → **Bind** ordering guarantees that). It exists for the cases the
+* sync read cannot cover: binding while a connection is still opening, or a
+* deployment whose driver surfaces no topology description. Calling it makes
+* the SUBSEQUENT synchronous reads definitive, so nothing else needs rewiring:
+*
+* ```ts
+* await probeMongoCapabilities(connection);   // once, before bind
+* const engine = defineWallet().bind(connection);  // gate now sees the truth
+* ```
+*
+* Only definitive answers are cached — an `'unknown'` may be re-probed later
+* (the deployment may simply not have been up yet).
+*/
+async function probeMongoCapabilities(connection, options = {}) {
+	if (!connection || typeof connection !== "object") return DERIVED.unknown;
+	const key = connection;
+	const cached = PROBE_RESULTS.get(key);
+	if (cached) return DERIVED[cached];
+	const inflight = PROBE_INFLIGHT.get(key);
+	if (inflight) return DERIVED[await inflight];
+	const run = runProbe(connection, options.timeoutMs ?? 2e3).catch(() => "unknown").then((support) => {
+		if (support !== "unknown") PROBE_RESULTS.set(key, support);
+		PROBE_INFLIGHT.delete(key);
+		return support;
+	});
+	PROBE_INFLIGHT.set(key, run);
+	return DERIVED[await run];
+}
 //#endregion
 //#region src/operations.ts
 /**
@@ -705,7 +914,16 @@ function buildAggPipeline(req, schema) {
 	const aliasSet = new Set((req.lookups ?? []).map((l) => l.as ?? l.from));
 	const { base: baseFilter, joined: joinedFilter } = splitFilterByAlias(schema !== void 0 && req.filter !== void 0 ? castFilterToSchema(req.filter, schema) : req.filter, aliasSet);
 	if (baseFilter !== void 0) {
-		const match = compileFilterToMongo(baseFilter);
+		/**
+		* The SCHEMA is passed so the date coercion can consult it.
+		*
+		* `castFilterToSchema` above already casts operands to their declared types; without
+		* the schema here, `compileFilterToMongo`'s coercion then guessed from value shape
+		* alone and OVERRODE that cast — turning a `'2026-08-02'` bound on a String column
+		* into a Date, which BSON refuses to compare against the stored string. The aggregate
+		* returned zero rows and nothing indicated why.
+		*/
+		const match = compileFilterToMongo(baseFilter, schema);
 		if (Object.keys(match).length > 0) stages.push({ $match: match });
 	}
 	if (req.lookups && req.lookups.length > 0) appendLookupStages$1(stages, req.lookups);
@@ -993,7 +1211,7 @@ async function countAggGroups(Model, req, options = {}) {
 		const [row] = await aggregation.exec();
 		return row?.n ?? 0;
 	}
-	const match = req.filter ? compileFilterToMongo(castFilterToSchema(req.filter, Model.schema)) : {};
+	const match = req.filter ? compileFilterToMongo(castFilterToSchema(req.filter, Model.schema), Model.schema) : {};
 	if (groupCols.length === 0) {
 		const pipeline = [];
 		if (Object.keys(match).length > 0) pipeline.push({ $match: match });
@@ -1899,29 +2117,29 @@ function isTransactionUnsupported(error) {
 /**
 * PROACTIVELY report whether a connection's deployment supports multi-document
 * transactions — the read-side companion to {@link isTransactionUnsupported}
-* (which classifies a FAILED attempt). Single source of truth for the topology
-* check so callers don't hand-roll `client.topology.description.type` probing.
+* (which classifies a FAILED attempt). Lets a caller skip a doomed transaction
+* attempt on standalone dev Mongo rather than starting one just to catch the
+* error.
+*
+* Delegates to {@link resolveTransactionSupport} so mongokit has exactly ONE
+* topology reader. That also fixes a false NEGATIVE this function used to
+* have: it tested `description.type !== 'Single'`, but a single-node replica
+* set reached with `directConnection` is `Single` with a server type of
+* `RSPrimary` and runs transactions fine. The shared reader looks at the
+* SERVER descriptions first.
 *
-* Returns `false` ONLY when the topology is positively a standalone (`'Single'`)
-* server; an unknown/undefined topology (not yet connected, non-standard
-* connection object) returns `true` — optimistic, because a genuine failure is
-* still caught reactively by `isTransactionUnsupported`. Lets a caller skip a
-* doomed transaction attempt on standalone dev Mongo rather than starting one
-* just to catch the error.
+* **`unknown` is optimistic HERE and pessimistic in `capabilities.ts` — the
+* difference is deliberate.** This answers "should I bother ATTEMPTING a
+* transaction?", where guessing yes costs one caught error (`allowFallback`
+* still recovers). The capability descriptor answers "may this deployment be
+* trusted with money?", where guessing yes is the bug class this repo keeps
+* hitting (AGENTS.md FAIL LOUD rule 3). Do not "unify" them.
 *
 * Accepts a Mongoose `Connection` (or anything exposing `getClient()`/`client`
 * with a driver `topology`), so it stays decoupled from mongoose types.
 */
 function supportsTransactions(connection) {
-	const probe = connection;
-	if (!probe) return true;
-	let client;
-	try {
-		client = probe.getClient?.() ?? probe.client ?? void 0;
-	} catch {
-		return true;
-	}
-	return client?.topology?.description?.type !== "Single";
+	return resolveTransactionSupport(connection) !== "no";
 }
 //#endregion
 //#region src/Repository.ts
@@ -1986,8 +2204,31 @@ var Repository = class extends RepositoryBase {
 	* Runtime capability descriptor required by `StandardRepo<TDoc>`
 	* (repo-core 0.6.0). Hosts feature-detect once at boot instead of
 	* try/catching `UnsupportedOperationError` per call.
+	*
+	* **OBSERVED, not declared** (changed 2026-08-05). Until then this was a
+	* class field pointing at the static `MONGOKIT_CAPABILITIES`, so
+	* `transactions` read `true` for every mongoose-backed repository —
+	* including one pointed at a standalone `mongod`, which cannot run a
+	* transaction at all. Every kernel boot gate that reads it (wallet, party,
+	* invoice, purchase, flow, …) was therefore unfalsifiable decoration
+	* (AGENTS.md FAIL LOUD rule 4).
+	*
+	* Now it derives the deployment-dependent flags (`transactions`,
+	* `nestedTransactions`, `changeStreams`) from THIS model's connection and
+	* its live SDAM topology. A getter rather than a constructor snapshot on
+	* purpose: a repository built before `mongoose.connect()` resolves upgrades
+	* its own answer the moment the connection is up, with no invalidation step.
+	* When the topology cannot be read the answer is `transactions: false` +
+	* `transactionsResolution: 'unknown'` — fail closed, never an optimistic
+	* yes (rule 3). See `capabilities.ts` and `probeMongoCapabilities`.
+	*
+	* `options.capabilities` overrides the whole descriptor for hosts/tests that
+	* genuinely know better (a proxied connection, a non-mongoose driver seam).
 	*/
-	capabilities = MONGOKIT_CAPABILITIES;
+	get capabilities() {
+		return this._capabilitiesOverride ?? resolveMongoCapabilities(this.Model?.db);
+	}
+	_capabilitiesOverride;
 	Model;
 	/**
 	* Mongoose model name. Duplicated on the instance for BC — arc / catalog /
@@ -2020,6 +2261,7 @@ var Repository = class extends RepositoryBase {
 			warn(m);
 		});
 		this.Model = Model;
+		this._capabilitiesOverride = options.capabilities;
 		this.model = Model.modelName;
 		this._pagination = new PaginationEngine(Model, paginationConfig);
 		this.idField = options.idField ?? "_id";
@@ -2318,7 +2560,8 @@ var Repository = class extends RepositoryBase {
 					return result;
 				}
 				const wantsThrow = context.throwOnNotFound === true || options.throwOnNotFound === true;
-				if (!isValidIdForType(id, getSchemaIdType(this.Model.schema))) {
+				const idType = getSchemaIdType(this.Model.schema);
+				if (!isValidIdForType(id, idType)) {
 					if (wantsThrow) throw createError(404, "Document not found");
 					return null;
 				}
@@ -2822,8 +3065,9 @@ var Repository = class extends RepositoryBase {
 	/**
 	* Update a document by id and return the post-update doc.
 	*
-	* Compiles to `Model.findOneAndUpdate(filter, { $set: data }, { new:
-	* true, runValidators: true })` under the hood and routes through the
+	* Compiles to `Model.findOneAndUpdate(filter, { $set: data },
+	* { returnDocument: 'after', runValidators: true })` under the hood and
+	* routes through the
 	* full plugin pipeline — `multiTenantPlugin` injects the tenant scope,
 	* `auditTrailPlugin` records the change, `cachePlugin` invalidates,
 	* `softDeletePlugin` etc. all compose. Returns `null` on miss (the
@@ -2838,7 +3082,7 @@ var Repository = class extends RepositoryBase {
 	* const doc = await CampaignModel.findOneAndUpdate(
 	*   { _id: id, organizationId: ctx.orgId },     // hand-rolled tenant filter
 	*   { $set: patch, $currentDate: { updatedAt: 1 } },
-	*   { new: true, runValidators: true }
+	*   { returnDocument: 'after', runValidators: true }
 	* );
 	* return doc ? toEntity(doc) : null;
 	*
@@ -2867,7 +3111,7 @@ var Repository = class extends RepositoryBase {
 	* const doc = await CampaignModel.findOneAndUpdate(
 	*   { _id: id, organizationId: ctx.orgId, status: 'pending' },
 	*   { $set: { status: 'sent', sentAt: new Date() } },
-	*   { new: true }
+	*   { returnDocument: 'after' }
 	* );
 	* if (!doc) throw new ConcurrentTransitionError(id);
 	*
@@ -2921,7 +3165,8 @@ var Repository = class extends RepositoryBase {
 				const wantsThrow = context.throwOnNotFound === true || options.throwOnNotFound === true;
 				const effectiveIdField = options.idField ?? this.idField;
 				if (effectiveIdField === "_id") {
-					if (!isValidIdForType(id, getSchemaIdType(this.Model.schema))) {
+					const idType = getSchemaIdType(this.Model.schema);
+					if (!isValidIdForType(id, idType)) {
 						if (wantsThrow) throw createError(404, "Document not found");
 						await this._emitHook("after:update", {
 							context,
@@ -3211,7 +3456,8 @@ var Repository = class extends RepositoryBase {
 			const finalQuery = context.query || filter;
 			const finalUpdate = context.data || update;
 			if (effectiveIdField === "_id" && !options.upsert) {
-				if (!isValidIdForType(id, getSchemaIdType(this.Model.schema))) return null;
+				const idType = getSchemaIdType(this.Model.schema);
+				if (!isValidIdForType(id, idType)) return null;
 			}
 			if (Object.keys(finalUpdate).length === 0) return await this.Model.findOne(finalQuery, null, { session: options.session });
 			return await findOneAndUpdate(this.Model, finalQuery, finalUpdate, {
@@ -3444,7 +3690,8 @@ var Repository = class extends RepositoryBase {
 			const finalQuery = context.query || filter;
 			const finalUpdate = context.data || operatorUpdate;
 			if (effectiveIdField === "_id") {
-				if (!isValidIdForType(id, getSchemaIdType(this.Model.schema))) return null;
+				const idType = getSchemaIdType(this.Model.schema);
+				if (!isValidIdForType(id, idType)) return null;
 			}
 			return await findOneAndUpdate(this.Model, finalQuery, finalUpdate, {
 				returnDocument: "after",
@@ -3497,7 +3744,8 @@ var Repository = class extends RepositoryBase {
 				const effectiveIdField = options.idField ?? this.idField;
 				const wantsThrow = context.throwOnNotFound === true || options.throwOnNotFound === true;
 				if (effectiveIdField === "_id") {
-					if (!isValidIdForType(id, getSchemaIdType(this.Model.schema))) {
+					const idType = getSchemaIdType(this.Model.schema);
+					if (!isValidIdForType(id, idType)) {
 						if (wantsThrow) throw createError(404, "Document not found");
 						await this._emitHook("after:delete", {
 							context,
@@ -3630,7 +3878,8 @@ var Repository = class extends RepositoryBase {
 	* the port implementation.
 	*/
 	async purgeByField(field, value, strategy, options = {}) {
-		return runChunkedPurge(strategy, options, createMongoPurgePort(this, field, value, options.session));
+		const port = createMongoPurgePort(this, field, value, options.session);
+		return runChunkedPurge(strategy, options, port);
 	}
 	/**
 	* Range/filter-scoped purge — see `StandardRepo.purgeByFilter` for the
@@ -3648,7 +3897,8 @@ var Repository = class extends RepositoryBase {
 	*/
 	async purgeByFilter(filter, strategy, options = {}) {
 		const compiled = compileFilterToMongo(filter);
-		return runChunkedPurge(strategy, options, createMongoPurgePortFromFilter(this, compiled, options.session));
+		const port = createMongoPurgePortFromFilter(this, compiled, options.session);
+		return runChunkedPurge(strategy, options, port);
 	}
 	/**
 	* Chunked cold-storage extraction — see `StandardRepo.archiveByFilter`
@@ -3663,7 +3913,8 @@ var Repository = class extends RepositoryBase {
 	*/
 	async archiveByFilter(filter, sink, options = {}) {
 		const compiled = compileFilterToMongo(filter);
-		return runChunkedArchive(options, sink, createMongoArchivePort(this, compiled, options.session));
+		const port = createMongoArchivePort(this, compiled, options.session);
+		return runChunkedArchive(options, sink, port);
 	}
 	/**
 	* Kit-native aggregation pipeline — takes a MongoDB stage array and
@@ -4410,7 +4661,10 @@ var Repository = class extends RepositoryBase {
 		const labels = error.errorLabels;
 		const hasLabel = error.hasErrorLabel;
 		if (Array.isArray(labels) && (labels.includes("TransientTransactionError") || labels.includes("UnknownTransactionCommitResult")) || typeof hasLabel === "function" && (hasLabel.call(error, "TransientTransactionError") || hasLabel.call(error, "UnknownTransactionCommitResult"))) return error;
-		if (error instanceof mongoose.Error.ValidationError) return createError(400, `Validation Error: ${Object.values(error.errors).map((err) => err.message).join(", ")}`);
+		if (error instanceof mongoose.Error.ValidationError) {
+			const messages = Object.values(error.errors).map((err) => err.message);
+			return createError(400, `Validation Error: ${messages.join(", ")}`);
+		}
 		if (error instanceof mongoose.Error.CastError) return createError(400, `Invalid ${error.path}: ${error.value}`);
 		const duplicateErr = parseDuplicateKeyError(error);
 		if (duplicateErr) return duplicateErr;
@@ -4419,4 +4673,4 @@ var Repository = class extends RepositoryBase {
 	}
 };
 //#endregion
-export { supportsTransactions as a, ALL_OPERATIONS as c, READ_OPERATIONS as d, operationsByPolicyKey as f, isTransactionUnsupported as i, MUTATING_OPERATIONS as l, createMongoPurgePort as m, Repository as n, withTransaction as o, MONGOKIT_CAPABILITIES as p, batchTransaction as r, AggregationBuilder as s, HOOK_PRIORITY$1 as t, OP_REGISTRY as u };
+export { resetCapabilityProbeCache as _, supportsTransactions as a, transactionResolutionOf as b, ALL_OPERATIONS as c, READ_OPERATIONS as d, operationsByPolicyKey as f, probeMongoCapabilities as g, classifyHelloReply as h, isTransactionUnsupported as i, MUTATING_OPERATIONS as l, capabilitiesForSupport as m, Repository as n, withTransaction as o, MONGOKIT_CAPABILITIES as p, batchTransaction as r, AggregationBuilder as s, HOOK_PRIORITY$1 as t, OP_REGISTRY as u, resolveMongoCapabilities as v, createMongoPurgePort as x, resolveTransactionSupport as y };

package/dist/actions/index.mjs

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "../rolldown-runtime-D7D4PA-g.mjs";
-import { g as create_exports, i as update_exports, p as delete_exports, u as read_exports, v as aggregate_exports } from "../update-CI2NdAW6.mjs";
+import { g as create_exports, i as update_exports, p as delete_exports, u as read_exports, v as aggregate_exports } from "../update-DHdXdOk_.mjs";
 //#region src/actions/index.ts
 var actions_exports = /* @__PURE__ */ __exportAll({
 	aggregate: () => aggregate_exports,

package/dist/adapter/index.mjs

@@ -1,2 +1,2 @@
-import { n as createMongooseAdapter, r as isMongooseModel, t as MongooseAdapter } from "../adapter-CLvUHiTW.mjs";
+import { n as createMongooseAdapter, r as isMongooseModel, t as MongooseAdapter } from "../adapter-BitHg-CN.mjs";
 export { MongooseAdapter, createMongooseAdapter, isMongooseModel };

package/dist/{adapter-CLvUHiTW.mjs → adapter-BitHg-CN.mjs}

@@ -1,5 +1,5 @@
 import { n as warn } from "./logger-K7dPmu2U.mjs";
-import { t as buildCrudSchemasFromModel } from "./mongooseToJsonSchema-CByt1VhQ.mjs";
+import { t as buildCrudSchemasFromModel } from "./mongooseToJsonSchema-DKbnKduN.mjs";
 import { matchesRecordFilter } from "@classytic/repo-core/filter";
 import { mergeFieldRuleConstraints } from "@classytic/repo-core/schema";
 import { asRepositoryLike, isRepository } from "@classytic/repo-core/adapter";

package/dist/ai/index.d.mts

@@ -1,4 +1,4 @@
-import { l as Plugin } from "../repository-DCHRWRXw.mjs";
+import { l as Plugin } from "../repository-Q16ErTu8.mjs";
 import { PipelineStage } from "mongoose";
 //#region src/ai/types.d.ts
 /** Supported similarity metrics for vector search */

package/dist/better-auth/index.d.mts

@@ -58,6 +58,19 @@ interface RegisterBetterAuthStubsOptions {
   usePlural?: boolean;
   /** Per-collection model name override (mirrors BA's `user.modelName`). */
   modelOverrides?: Partial<Record<string, string>>;
+  /**
+   * Canonical collection names to SKIP — because something else owns their model.
+   *
+   * The normal reason is `createBetterAuthOverlay`: a host wants stubs for the collections it merely
+   * REFERENCES (`organization`, `member`) and a full overlay for the one it exposes CRUD on (`user`).
+   * Without this the two helpers collide — the stub registers `user` first, and the overlay then
+   * THROWS, correctly, because mongoose locks a schema on first `model()` and its `additionalFields`
+   * would be silently dropped.
+   *
+   * Names are CANONICAL (`'user'`, not a pluralised or overridden model name); exclusion is applied
+   * before `usePlural` / `modelOverrides`, so a caller does not have to predict the final name.
+   */
+  exclude?: string[];
 }
 /**
  * Register stub Mongoose models for Better Auth's collections so that

package/dist/better-auth/index.mjs

@@ -1,8 +1,45 @@
-import { n as Repository } from "../Repository-DThvFCaV.mjs";
-import { n as createMongooseAdapter } from "../adapter-CLvUHiTW.mjs";
+import { n as Repository } from "../Repository-X7U2d0kU.mjs";
+import { n as createMongooseAdapter } from "../adapter-BitHg-CN.mjs";
 import { pluralizeBetterAuthCollection, resolveBetterAuthCollections } from "@classytic/repo-core/better-auth";
 //#region src/better-auth/index.ts
 /**
+* Field key with ORDER PRESERVED — a compound index is identified by its key sequence.
+* `{ organizationId: 1, createdAt: -1 }` is a DIFFERENT index from `{ createdAt: -1, organizationId: 1 }`
+* (they serve different queries), so sorting the keys here would wrongly equate them.
+*/
+function indexFieldsKey(fields) {
+	return Object.entries(fields).map(([k, v]) => `${k}:${String(v)}`).join(",");
+}
+/** Deterministic canonical form (sorted object keys, recursive) for value equality. */
+function canonical(value) {
+	if (Array.isArray(value)) return value.map(canonical);
+	if (value && typeof value === "object") {
+		const obj = value;
+		return Object.keys(obj).sort().reduce((acc, k) => {
+			acc[k] = canonical(obj[k]);
+			return acc;
+		}, {});
+	}
+	return value;
+}
+/**
+* Is every DECLARED option satisfied by the existing index's options? A subset check, not
+* equality: Mongoose augments stored index options with defaults (e.g. `background`), so the
+* existing side legitimately carries extra keys. We require each declared key to deep-equal the
+* existing value — covering ALL declared options (unique, sparse, expireAfterSeconds, collation,
+* name, weights, default_language, partialFilterExpression, …) with no hand-maintained subset.
+*/
+function declaredOptionsSatisfied(declared = {}, existing = {}) {
+	for (const [key, value] of Object.entries(declared)) if (JSON.stringify(canonical(value)) !== JSON.stringify(canonical(existing[key]))) return false;
+	return true;
+}
+/** Which declared indexes are NOT already present on the existing model's schema. */
+function missingIndexesOn(existing, declared) {
+	if (declared.length === 0) return [];
+	const existingIndexes = (existing?.schema)?.indexes?.() ?? [];
+	return declared.filter((d) => !existingIndexes.some(([fields, options]) => indexFieldsKey(fields) === indexFieldsKey(d.fields) && declaredOptionsSatisfied(d.options ?? {}, options ?? {})));
+}
+/**
 * Register stub Mongoose models for Better Auth's collections so that
 * Mongoose-based resources can `.populate()` references to BA-owned
 * documents. Idempotent — safe to call multiple times.
@@ -22,10 +59,14 @@ import { pluralizeBetterAuthCollection, resolveBetterAuthCollections } from "@cl
 *          already existed on `mongoose.models`).
 */
 function registerBetterAuthStubs(mongoose, options = {}) {
-	const names = resolveBetterAuthCollections(options);
+	const excluded = new Set(options.exclude ?? []);
+	const names = resolveBetterAuthCollections({
+		...options,
+		...excluded.size ? { exclude: [...excluded] } : {}
+	});
 	const registered = [];
 	for (const finalName of names) {
-		if (mongoose.models[finalName]) continue;
+		if (finalName in mongoose.models) continue;
 		const schema = new mongoose.Schema({}, {
 			strict: false,
 			collection: finalName,
@@ -59,8 +100,37 @@ async function createBetterAuthOverlay(options) {
 	const tableConfig = ctx.tables[collection];
 	if (!tableConfig) throw new Error(`[mongokit:better-auth] Better Auth has no table named '${collection}'. Available: ${Object.keys(ctx.tables).join(", ")}. Did you enable the right plugin in your betterAuth() config?`);
 	const finalName = usePlural ? pluralizeBetterAuthCollection(tableConfig.modelName) : tableConfig.modelName;
-	if (mongoose.models[finalName]) {
-		if (Object.keys(additionalFields).length > 0 || indexes.length > 0) throw new Error(`[mongokit:better-auth] '${finalName}' already registered on mongoose.models. Cannot apply additionalFields / indexes from this createBetterAuthOverlay() call — mongoose locks schema on first model() call. Either: (a) drop the prior registerBetterAuthStubs() call for '${finalName}', or (b) move additionalFields / indexes into the existing schema definition.`);
+	if (finalName in mongoose.models) {
+		const declared = Object.keys(additionalFields);
+		if (declared.length > 0 || indexes.length > 0) {
+			/**
+			* Distinguish "a STUB got here first" from "this same overlay already ran in this process".
+			*
+			* The guard exists because mongoose locks a schema on first `model()`, so declared
+			* `additionalFields` would be silently dropped. That danger is real when a
+			* `registerBetterAuthStubs()` call registered an EMPTY `strict: false` schema first.
+			*
+			* It is NOT real on a re-boot: a process that composes the app twice (every integration suite,
+			* and any host that recomposes) hits an existing model whose schema ALREADY carries these exact
+			* paths, because an identical overlay call put them there. Throwing then just makes the second
+			* boot impossible — which is precisely why hosts hand-rolled `models.X || model(X, schema)` and
+			* inherited the silent-drop bug this guard was written to stop.
+			*
+			* So the test is the SCHEMA, not the mere presence of a model: if every declared field is
+			* already a path, the fields are applied and reuse is safe. If any is missing, something else
+			* owns this model and the throw stands.
+			*/
+			const existing = mongoose.models[finalName];
+			const paths = existing?.schema?.paths ?? {};
+			const missing = declared.filter((f) => !(f in paths));
+			const missingIdx = missingIndexesOn(existing, indexes);
+			if (missing.length > 0 || missingIdx.length > 0) {
+				const parts = [];
+				if (missing.length > 0) parts.push(`${missing.length === 1 ? "field" : "fields"} ${missing.map((f) => `'${f}'`).join(", ")}`);
+				if (missingIdx.length > 0) parts.push(`${missingIdx.length === 1 ? "index" : "indexes"} on ${missingIdx.map((i) => `{${Object.keys(i.fields).join(",")}}`).join(", ")}`);
+				throw new Error(`[mongokit:better-auth] '${finalName}' already registered on mongoose.models WITHOUT ${parts.join(" and ")}. Cannot apply additionalFields / indexes from this createBetterAuthOverlay() call — mongoose locks schema on first model() call, so they would be SILENTLY DROPPED. Either: (a) exclude '${finalName}' from the prior registerBetterAuthStubs() call (\`exclude: ['${collection}']\`), or (b) move additionalFields / indexes there.`);
+			}
+		}
 	}
 	let Model = mongoose.models[finalName];
 	if (!Model) {