@classytic/mongokit 3.36.0 → 3.38.1

package/dist/{PaginationEngine-GdyX29tE.mjs → PaginationEngine-BX9o_-4R.mjs}

@@ -1,6 +1,7 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
 import { n as warn } from "./logger-K7dPmu2U.mjs";
 import { t as createError } from "./error-BuByZwKU.mjs";
+import { calculateSkip, calculateTotalPages, shouldWarnDeepPagination, validateLimit, validatePage } from "./pagination/utils/limits.mjs";
 import mongoose from "mongoose";
 //#region src/pagination/utils/filter.ts
 /**
@@ -374,69 +375,6 @@ function hasCompatibleKeysetIndex(indexes, filterFields, sort) {
 	return false;
 }
 //#endregion
-//#region src/pagination/utils/limits.ts
-/**
-* Validates and sanitizes limit value
-* Parses strings to numbers and prevents NaN bugs
-*
-* @param limit - Requested limit
-* @param config - Pagination configuration
-* @returns Sanitized limit between 1 and maxLimit
-*/
-function validateLimit(limit, config) {
-	const parsed = Number(limit);
-	if (!Number.isFinite(parsed) || parsed < 1) return config.defaultLimit ?? 10;
-	const max = config.maxLimit ?? 100;
-	if (max === 0) return Math.floor(parsed);
-	return Math.min(Math.floor(parsed), max);
-}
-/**
-* Validates and sanitizes page number
-* Parses strings to numbers and prevents NaN bugs
-*
-* @param page - Requested page (1-indexed)
-* @param config - Pagination configuration
-* @returns Sanitized page number >= 1
-* @throws Error if page exceeds maxPage
-*/
-function validatePage(page, config) {
-	const parsed = Number(page);
-	if (!Number.isFinite(parsed) || parsed < 1) return 1;
-	const sanitized = Math.floor(parsed);
-	if (sanitized > (config.maxPage || 1e4)) throw new Error(`Page ${sanitized} exceeds maximum ${config.maxPage || 1e4}`);
-	return sanitized;
-}
-/**
-* Checks if page number should trigger deep pagination warning
-*
-* @param page - Current page number
-* @param threshold - Warning threshold
-* @returns True if warning should be shown
-*/
-function shouldWarnDeepPagination(page, threshold) {
-	return page > threshold;
-}
-/**
-* Calculates number of documents to skip for offset pagination
-*
-* @param page - Page number (1-indexed)
-* @param limit - Documents per page
-* @returns Number of documents to skip
-*/
-function calculateSkip(page, limit) {
-	return (page - 1) * limit;
-}
-/**
-* Calculates total number of pages
-*
-* @param total - Total document count
-* @param limit - Documents per page
-* @returns Total number of pages
-*/
-function calculateTotalPages(total, limit) {
-	return Math.ceil(total / limit);
-}
-//#endregion
 //#region src/pagination/utils/sort.ts
 var sort_exports = /* @__PURE__ */ __exportAll({
 	getPrimaryField: () => getPrimaryField,
@@ -794,4 +732,4 @@ var PaginationEngine = class {
 	}
 };
 //#endregion
-export { cursor_exports as i, sort_exports as n, calculateTotalPages as r, PaginationEngine as t };
+export { sort_exports as n, cursor_exports as r, PaginationEngine as t };

package/dist/{Repository-BArvU32x.mjs → Repository-Ck5x43wF.mjs}

@@ -3,7 +3,8 @@ import { a as narrowToIds, i as keysetFilter, o as selectKeysetChunk } from "./i
 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-jSXp3nu3.mjs";
 import { n as warn } from "./logger-K7dPmu2U.mjs";
 import { n as isDuplicateKeyError, r as parseDuplicateKeyError, t as createError } from "./error-BuByZwKU.mjs";
-import { r as calculateTotalPages, t as PaginationEngine } from "./PaginationEngine-GdyX29tE.mjs";
+import { t as PaginationEngine } from "./PaginationEngine-BX9o_-4R.mjs";
+import { calculateTotalPages } from "./pagination/utils/limits.mjs";
 import { hasNearOperator, rewriteNearForCount } from "./query/primitives/geo.mjs";
 import { RepositoryBase, runChunkedArchive, runChunkedPurge, throwIfAborted, validatePluginOrder, withRetry } from "@classytic/repo-core/repository";
 import mongoose from "mongoose";
@@ -2635,6 +2636,10 @@ var Repository = class extends RepositoryBase {
 				const idType = getSchemaIdType(this.Model.schema);
 				if (!isValidIdForType(id, idType)) {
 					if (wantsThrow) throw createError(404, "Document not found");
+					await this._emitHook("after:getById", {
+						context,
+						result: null
+					});
 					return null;
 				}
 				const result = await this._withResilience(context, () => getById(this.Model, id, context));
@@ -4412,9 +4417,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-GdyX29tE.mjs").then((n) => n.n);
-					const { encodeCursor, resolveCursorFilter } = await import("./PaginationEngine-GdyX29tE.mjs").then((n) => n.i);
-					const { getPrimaryField } = await import("./PaginationEngine-GdyX29tE.mjs").then((n) => n.n);
+					const { validateKeysetSort } = await import("./PaginationEngine-BX9o_-4R.mjs").then((n) => n.n);
+					const { encodeCursor, resolveCursorFilter } = await import("./PaginationEngine-BX9o_-4R.mjs").then((n) => n.r);
+					const { getPrimaryField } = await import("./PaginationEngine-BX9o_-4R.mjs").then((n) => n.n);
 					const normalizedSort = validateKeysetSort(parsedSort, this._pagination.config.strictKeysetSortFields);
 					const cursorVersion = this._pagination.config.cursorVersion ?? 1;
 					const minCursorVersion = this._pagination.config.minCursorVersion ?? 1;

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

@@ -259,6 +259,83 @@ declare function ensureBetterAuthSessionTtl(connection: {
   collection?: string;
   indexName?: string;
 }): Promise<boolean>;
+/**
+ * One declared index on a Better Auth collection.
+ *
+ * `unique` is a REQUEST, not a guarantee: {@link ensureBetterAuthIndexes}
+ * downgrades to a non-unique index when existing rows already violate it,
+ * because failing a boot over historical duplicates is worse than running with
+ * a plain lookup index and reporting the degradation.
+ */
+interface BetterAuthIndexSpec {
+  /** Canonical collection name (`'user'`, `'session'`, ...). */
+  collection: string;
+  keys: Record<string, 1 | -1>;
+  name: string;
+  unique?: boolean;
+  /** Present on self-expiring rows; always paired with `expireAfterSeconds: 0`. */
+  ttl?: boolean;
+}
+/**
+ * The indexes Better Auth's own queries need, which its mongo adapter does NOT
+ * create. Grouped by the plugin that owns the collection so a host only pays
+ * for what it enabled.
+ *
+ * Every entry below backs a query BA runs on a hot path:
+ *   - `session.token`   — read on EVERY authenticated request
+ *   - `user.email`      — read on every sign-in / sign-up, and must be unique
+ *   - `account.(providerId|issuer, accountId)` — the credential lookup at sign-in
+ *   - `member.(organizationId, userId)` — the membership check on org-scoped requests
+ * Without them each of those is a collection scan, and `email` / `slug` /
+ * `token` have no uniqueness guarantee at all.
+ *
+ * TTL entries (`expiresAt`) additionally keep the collection BOUNDED — see
+ * {@link ensureBetterAuthSessionTtl} for the measurements that motivated it.
+ */
+declare const BA_INDEXES_BY_PLUGIN: Record<string, readonly BetterAuthIndexSpec[]>;
+/** Outcome of one declared index. */
+interface BetterAuthIndexResult {
+  collection: string;
+  name: string;
+  status: 'created' | 'degraded' | 'failed';
+  /** Set on `degraded` (unique dropped) and `failed`. */
+  reason?: string;
+}
+interface EnsureBetterAuthIndexesOptions {
+  /** Plugin sets to include beyond `core` (always implied). */
+  plugins?: BetterAuthPluginKey$1[];
+  /** Mirror BA's `usePlural` — appends `s` to every collection name. */
+  usePlural?: boolean;
+  /** Per-collection name override (mirrors BA's `user.modelName`). */
+  modelOverrides?: Partial<Record<string, string>>;
+  /** Canonical collection names to skip entirely. */
+  exclude?: string[];
+}
+interface IndexCreator {
+  collection(name: string): {
+    createIndex(keys: Record<string, 1 | -1>, opts: Record<string, unknown>): Promise<unknown>;
+  };
+}
+/**
+ * Create every index Better Auth's queries need. Idempotent, never throws.
+ *
+ * BA's mongo adapter creates NO indexes — not even on `session.token`, which is
+ * read on every authenticated request, nor a unique one on `user.email`. On a
+ * small database nobody notices; the cost arrives as a full collection scan per
+ * login once the tables grow, and until then nothing stops a duplicate email.
+ *
+ * This lives in the kit rather than a host for the same reason
+ * {@link ensureBetterAuthSessionTtl} does: the kit is what knows BA's collection
+ * names, so fixing it here protects every consumer instead of one host.
+ *
+ * **Uniqueness degrades rather than fails.** A `unique: true` spec is retried
+ * without uniqueness when the collection already holds violating rows, and
+ * reported as `degraded` — a boot must not die because historical data has a
+ * duplicate. Inspect the returned report to find those.
+ *
+ * Call once at boot, after the connection is live. Safe to call again.
+ */
+declare function ensureBetterAuthIndexes(connection: IndexCreator, options?: EnsureBetterAuthIndexesOptions): Promise<BetterAuthIndexResult[]>;
 interface SessionUpdaterLike {
   updateMany(filter: Record<string, unknown>, update: Record<string, unknown>): Promise<{
     modifiedCount?: number;
@@ -293,4 +370,4 @@ declare function clearActiveOrganizationFromSessions(sessions: SessionUpdaterLik
   userId?: unknown;
 }): Promise<number>;
 //#endregion
-export { BetterAuthIdType, BetterAuthInstance, BetterAuthOverlayOptions, type BetterAuthPluginKey, MongooseLike, RegisterBetterAuthStubsOptions, SessionUpdaterLike, clearActiveOrganizationFromSessions, createBetterAuthOverlay, ensureBetterAuthSessionTtl, registerBetterAuthStubs };
+export { BA_INDEXES_BY_PLUGIN, BetterAuthIdType, BetterAuthIndexResult, BetterAuthIndexSpec, BetterAuthInstance, BetterAuthOverlayOptions, type BetterAuthPluginKey, EnsureBetterAuthIndexesOptions, IndexCreator, MongooseLike, RegisterBetterAuthStubsOptions, SessionUpdaterLike, clearActiveOrganizationFromSessions, createBetterAuthOverlay, ensureBetterAuthIndexes, ensureBetterAuthSessionTtl, registerBetterAuthStubs };

package/dist/better-auth/index.mjs

@@ -1,4 +1,4 @@
-import { n as Repository } from "../Repository-BArvU32x.mjs";
+import { n as Repository } from "../Repository-Ck5x43wF.mjs";
 import { n as createMongooseAdapter } from "../adapter-Bfqz8yHE.mjs";
 import { asReadOnlyRepo } from "@classytic/repo-core/repository";
 import { pluralizeBetterAuthCollection, resolveBetterAuthCollections } from "@classytic/repo-core/better-auth";
@@ -203,6 +203,236 @@ async function ensureBetterAuthSessionTtl(connection, options = {}) {
 	}
 }
 /**
+* The indexes Better Auth's own queries need, which its mongo adapter does NOT
+* create. Grouped by the plugin that owns the collection so a host only pays
+* for what it enabled.
+*
+* Every entry below backs a query BA runs on a hot path:
+*   - `session.token`   — read on EVERY authenticated request
+*   - `user.email`      — read on every sign-in / sign-up, and must be unique
+*   - `account.(providerId|issuer, accountId)` — the credential lookup at sign-in
+*   - `member.(organizationId, userId)` — the membership check on org-scoped requests
+* Without them each of those is a collection scan, and `email` / `slug` /
+* `token` have no uniqueness guarantee at all.
+*
+* TTL entries (`expiresAt`) additionally keep the collection BOUNDED — see
+* {@link ensureBetterAuthSessionTtl} for the measurements that motivated it.
+*/
+const BA_INDEXES_BY_PLUGIN = {
+	core: [
+		{
+			collection: "user",
+			keys: { email: 1 },
+			name: "ba_user_email",
+			unique: true
+		},
+		{
+			collection: "session",
+			keys: { token: 1 },
+			name: "ba_session_token",
+			unique: true
+		},
+		{
+			collection: "session",
+			keys: { userId: 1 },
+			name: "ba_session_userId"
+		},
+		{
+			collection: "session",
+			keys: { expiresAt: 1 },
+			name: "ttl_session_expiresAt",
+			ttl: true
+		},
+		{
+			collection: "account",
+			keys: { userId: 1 },
+			name: "ba_account_userId"
+		},
+		{
+			collection: "account",
+			keys: {
+				providerId: 1,
+				accountId: 1
+			},
+			name: "ba_account_provider_accountId"
+		},
+		{
+			collection: "account",
+			keys: {
+				issuer: 1,
+				accountId: 1
+			},
+			name: "ba_account_issuer_accountId"
+		},
+		{
+			collection: "verification",
+			keys: { identifier: 1 },
+			name: "ba_verification_identifier"
+		},
+		{
+			collection: "verification",
+			keys: { expiresAt: 1 },
+			name: "ttl_verification_expiresAt",
+			ttl: true
+		}
+	],
+	organization: [
+		{
+			collection: "organization",
+			keys: { slug: 1 },
+			name: "ba_organization_slug",
+			unique: true
+		},
+		{
+			collection: "member",
+			keys: {
+				organizationId: 1,
+				userId: 1
+			},
+			name: "ba_member_org_user",
+			unique: true
+		},
+		{
+			collection: "member",
+			keys: { userId: 1 },
+			name: "ba_member_userId"
+		},
+		{
+			collection: "invitation",
+			keys: { organizationId: 1 },
+			name: "ba_invitation_org"
+		},
+		{
+			collection: "invitation",
+			keys: { email: 1 },
+			name: "ba_invitation_email"
+		},
+		{
+			collection: "invitation",
+			keys: { expiresAt: 1 },
+			name: "ttl_invitation_expiresAt",
+			ttl: true
+		}
+	],
+	"organization-teams": [{
+		collection: "team",
+		keys: { organizationId: 1 },
+		name: "ba_team_org"
+	}, {
+		collection: "teamMember",
+		keys: {
+			teamId: 1,
+			userId: 1
+		},
+		name: "ba_teamMember_team_user"
+	}],
+	twoFactor: [{
+		collection: "twoFactor",
+		keys: { userId: 1 },
+		name: "ba_twoFactor_userId"
+	}],
+	deviceAuthorization: [
+		{
+			collection: "deviceCode",
+			keys: { deviceCode: 1 },
+			name: "ba_deviceCode_code"
+		},
+		{
+			collection: "deviceCode",
+			keys: { userCode: 1 },
+			name: "ba_deviceCode_userCode"
+		},
+		{
+			collection: "deviceCode",
+			keys: { expiresAt: 1 },
+			name: "ttl_deviceCode_expiresAt",
+			ttl: true
+		}
+	]
+};
+/**
+* Create every index Better Auth's queries need. Idempotent, never throws.
+*
+* BA's mongo adapter creates NO indexes — not even on `session.token`, which is
+* read on every authenticated request, nor a unique one on `user.email`. On a
+* small database nobody notices; the cost arrives as a full collection scan per
+* login once the tables grow, and until then nothing stops a duplicate email.
+*
+* This lives in the kit rather than a host for the same reason
+* {@link ensureBetterAuthSessionTtl} does: the kit is what knows BA's collection
+* names, so fixing it here protects every consumer instead of one host.
+*
+* **Uniqueness degrades rather than fails.** A `unique: true` spec is retried
+* without uniqueness when the collection already holds violating rows, and
+* reported as `degraded` — a boot must not die because historical data has a
+* duplicate. Inspect the returned report to find those.
+*
+* Call once at boot, after the connection is live. Safe to call again.
+*/
+async function ensureBetterAuthIndexes(connection, options = {}) {
+	const plugins = options.plugins ?? [];
+	const excluded = new Set(options.exclude ?? []);
+	const keys = ["core", ...plugins];
+	const resolveName = (canonical) => {
+		const overridden = options.modelOverrides?.[canonical] ?? canonical;
+		return options.usePlural ? pluralizeBetterAuthCollection(overridden) : overridden;
+	};
+	const specs = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const key of keys) for (const spec of BA_INDEXES_BY_PLUGIN[key] ?? []) {
+		if (excluded.has(spec.collection)) continue;
+		const id = `${spec.collection}.${spec.name}`;
+		if (seen.has(id)) continue;
+		seen.add(id);
+		specs.push(spec);
+	}
+	const results = [];
+	for (const spec of specs) {
+		const target = resolveName(spec.collection);
+		const base = { name: spec.name };
+		if (spec.ttl) base.expireAfterSeconds = 0;
+		try {
+			await connection.collection(target).createIndex(spec.keys, {
+				...base,
+				...spec.unique ? { unique: true } : {}
+			});
+			results.push({
+				collection: target,
+				name: spec.name,
+				status: "created"
+			});
+		} catch (err) {
+			const reason = err instanceof Error ? err.message : String(err);
+			if (!spec.unique) {
+				results.push({
+					collection: target,
+					name: spec.name,
+					status: "failed",
+					reason
+				});
+				continue;
+			}
+			try {
+				await connection.collection(target).createIndex(spec.keys, base);
+				results.push({
+					collection: target,
+					name: spec.name,
+					status: "degraded",
+					reason
+				});
+			} catch (err2) {
+				results.push({
+					collection: target,
+					name: spec.name,
+					status: "failed",
+					reason: err2 instanceof Error ? err2.message : String(err2)
+				});
+			}
+		}
+	}
+	return results;
+}
+/**
 * Clear a dangling `activeOrganizationId` from Better Auth `session` rows.
 *
 * WHY THIS EXISTS: Better Auth purges its `member` / `invitation` rows when an
@@ -233,4 +463,4 @@ async function clearActiveOrganizationFromSessions(sessions, organizationId, opt
 	return (await sessions.updateMany(filter, { $set: { activeOrganizationId: null } })).modifiedCount ?? 0;
 }
 //#endregion
-export { clearActiveOrganizationFromSessions, createBetterAuthOverlay, ensureBetterAuthSessionTtl, registerBetterAuthStubs };
+export { BA_INDEXES_BY_PLUGIN, clearActiveOrganizationFromSessions, createBetterAuthOverlay, ensureBetterAuthIndexes, ensureBetterAuthSessionTtl, registerBetterAuthStubs };

package/dist/{create-repository-CPNbktFG.mjs → create-repository-B5EulQ31.mjs}

@@ -1,5 +1,5 @@
-import { n as Repository } from "./Repository-BArvU32x.mjs";
-import { a as customIdPlugin, f as auditTrailPlugin, i as multiTenantPlugin, m as auditLogPlugin, n as softDeletePlugin, t as timestampPlugin, u as cachePlugin } from "./timestamp.plugin-BEc6TANm.mjs";
+import { n as Repository } from "./Repository-Ck5x43wF.mjs";
+import { a as customIdPlugin, f as auditTrailPlugin, i as multiTenantPlugin, m as auditLogPlugin, n as softDeletePlugin, t as timestampPlugin, u as cachePlugin } from "./timestamp.plugin-CBQukQzV.mjs";
 import { n as batchOperationsPlugin, t as methodRegistryPlugin } from "./method-registry.plugin-DblM7V6j.mjs";
 //#region src/create-repository.ts
 function isLoggerAudit(value) {

package/dist/index.mjs

@@ -1,16 +1,16 @@
 import { n as idVariants } from "./id-resolution-BqDrk0S2.mjs";
-import { _ as resetCapabilityProbeCache, a as supportsTransactions, b as transactionResolutionOf, c as ALL_OPERATIONS, d as READ_OPERATIONS, f as operationsByPolicyKey, g as probeMongoCapabilities, h as classifyHelloReply, i as isTransactionUnsupported, l as MUTATING_OPERATIONS, m as capabilitiesForSupport, n as Repository, o as withTransaction, p as MONGOKIT_CAPABILITIES, r as batchTransaction, s as AggregationBuilder, t as HOOK_PRIORITY, u as OP_REGISTRY, v as resolveMongoCapabilities, x as createMongoPurgePort, y as resolveTransactionSupport } from "./Repository-BArvU32x.mjs";
+import { _ as resetCapabilityProbeCache, a as supportsTransactions, b as transactionResolutionOf, c as ALL_OPERATIONS, d as READ_OPERATIONS, f as operationsByPolicyKey, g as probeMongoCapabilities, h as classifyHelloReply, i as isTransactionUnsupported, l as MUTATING_OPERATIONS, m as capabilitiesForSupport, n as Repository, o as withTransaction, p as MONGOKIT_CAPABILITIES, r as batchTransaction, s as AggregationBuilder, t as HOOK_PRIORITY, u as OP_REGISTRY, v as resolveMongoCapabilities, x as createMongoPurgePort, y as resolveTransactionSupport } from "./Repository-Ck5x43wF.mjs";
 import { b as LookupBuilder, x as compileFilterToMongo } from "./update-jSXp3nu3.mjs";
 import { n as warn, t as configureLogger } from "./logger-K7dPmu2U.mjs";
 import { n as isDuplicateKeyError, r as parseDuplicateKeyError, t as createError } from "./error-BuByZwKU.mjs";
 import { t as actions_exports } from "./actions/index.mjs";
-import { a as customIdPlugin, c as prefixedId, d as AuditTrailQuery, f as auditTrailPlugin, i as multiTenantPlugin, l as sequentialId, m as auditLogPlugin, n as softDeletePlugin, o as dateSequentialId, p as ensureAuditTrailReady, r as adminBypass, s as getNextSequence, t as timestampPlugin, u as cachePlugin } from "./timestamp.plugin-BEc6TANm.mjs";
+import { a as customIdPlugin, c as prefixedId, d as AuditTrailQuery, f as auditTrailPlugin, i as multiTenantPlugin, l as sequentialId, m as auditLogPlugin, n as softDeletePlugin, o as dateSequentialId, p as ensureAuditTrailReady, r as adminBypass, s as getNextSequence, t as timestampPlugin, u as cachePlugin } from "./timestamp.plugin-CBQukQzV.mjs";
 import { n as batchOperationsPlugin, t as methodRegistryPlugin } from "./method-registry.plugin-DblM7V6j.mjs";
-import { t as PaginationEngine } from "./PaginationEngine-GdyX29tE.mjs";
+import { t as PaginationEngine } from "./PaginationEngine-BX9o_-4R.mjs";
 import { isGeoOperator, parseGeoFilter } from "./query/primitives/geo.mjs";
-import { t as createRepository } from "./create-repository-CPNbktFG.mjs";
+import { t as createRepository } from "./create-repository-B5EulQ31.mjs";
 import { n as defineModel, r as isModelRegistered, t as ModelCollisionError } from "./model-registry-ClKtWiHa.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-CyK1s9Ze.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-DhNyxNCw.mjs";
 import { i as getMongooseProjection, n as filterResponseData, r as getFieldsForUser, t as createFieldPreset } from "./field-selection-FSQFLpsU.mjs";
 import { buildFieldTypeMap, coerceFieldValue, coerceHeuristic } from "./query/primitives/coercion.mjs";
 import { extractSchemaIndexes } from "./query/primitives/indexes.mjs";
@@ -509,6 +509,11 @@ function parseFilters(rt, filters, depth = 0) {
 			rt.reject(`Blocked filter field not in allowlist: ${baseField}`, { field: baseField });
 			continue;
 		}
+		if (key === "$and") {
+			const branches = parseCompoundBranches(rt, value, depth);
+			if (branches.length > 0) parsedFilters.$and = branches;
+			continue;
+		}
 		if (operatorMatch) {
 			const [, , operator] = operatorMatch;
 			if (rt.dangerousOperators.includes(`$${operator}`)) {
@@ -707,6 +712,24 @@ function handleBracketSyntax(rt, field, operators, parsedFilters, depth = 0) {
 	if (typeof parsedFilters[field] === "object" && Object.keys(parsedFilters[field]).length === 0) delete parsedFilters[field];
 }
 /** Parse `?or=[...]` / `?OR=[...]` / `?$or=[...]` groups into an $or array. */
+/**
+* Parse the branches of a compound operator (`$and`, and the body of `$or`).
+*
+* Every branch goes back through `parseFilters`, so the operator block, the allowlist and the
+* regex budget all apply inside it. Branches that parse to `{}` are DROPPED: a branch holding
+* only a blocked operator would otherwise become match-all, which widens the query instead of
+* failing it — the exact shape `parseOr` documents below.
+*/
+function parseCompoundBranches(rt, raw, depth) {
+	const items = Array.isArray(raw) ? raw : typeof raw === "object" && raw ? Object.values(raw) : [];
+	const branches = [];
+	for (const item of items) {
+		if (typeof item !== "object" || !item) continue;
+		const parsed = parseFilters(rt, item, depth + 1);
+		if (Object.keys(parsed).length > 0) branches.push(parsed);
+	}
+	return branches;
+}
 function parseOr(rt, query) {
 	const orArray = [];
 	const raw = query?.or || query?.OR || query?.$or;

package/dist/indexes/verify-indexes.d.mts

@@ -0,0 +1,69 @@
+//#region src/indexes/verify-indexes.d.ts
+/**
+ * Compare DECLARED indexes against what a database actually has.
+ *
+ * `unique: true` on a schema is a correctness constraint only if the index was
+ * built. A skipped deploy step is otherwise SILENT — one deployment ran with
+ * 401 declared indexes absent, accumulated duplicate rows on a "unique" field,
+ * and nothing anywhere said the constraint did not exist. mongokit owns the
+ * declaration, so it owns the means to check it.
+ *
+ * Read-only. It NEVER builds: index builds belong to a deploy step, not to a
+ * serving process.
+ *
+ * Missing UNIQUE indexes are reported separately from missing regular ones —
+ * the first silently admits duplicate data, the second only costs a scan.
+ *
+ * DELIBERATELY ONE-DIRECTIONAL: an index present in the database but absent
+ * from a schema is NOT drift. Auth libraries and migrations manage indexes
+ * outside the ODM, and treating those as removable is exactly what makes a
+ * `syncIndexes()` unsafe.
+ *
+ * Sibling of `query/primitives/indexes`, which reads DECLARATIONS only and
+ * touches no connection. This module is the live comparison.
+ */
+/** The slice of a Mongoose-like connection this needs. Structural on purpose. */
+interface IndexVerifiableConnection {
+  modelNames(): string[];
+  model(name: string): IndexVerifiableModel;
+}
+interface IndexVerifiableModel {
+  schema: {
+    indexes(): Array<[Record<string, unknown>, Record<string, unknown>?]>;
+  };
+  collection: {
+    name: string;
+    listIndexes(): {
+      toArray(): Promise<Array<Record<string, unknown>>>;
+    };
+  };
+}
+interface MissingIndex {
+  model: string;
+  collection: string;
+  /** The declared key, JSON-stringified — stable to log and to diff. */
+  key: string;
+}
+interface IndexVerifyReport {
+  modelsChecked: number;
+  /** Declared `unique` indexes with nothing behind them. Duplicates can already exist. */
+  missingUnique: MissingIndex[];
+  missingRegular: MissingIndex[];
+  /** Models whose indexes could not be read — collection absent, or no permission. */
+  unreadable: string[];
+}
+interface VerifyIndexesOptions {
+  /**
+   * Include a model in the sweep. Default: every model.
+   *
+   * A kernel that materialises different model sets per mode must skip exactly
+   * the set its deploy step skips — indexing a model CREATES its collection, so
+   * a mismatch here reports permanent phantom drift instead of a real gap.
+   */
+  includeModel?: (modelName: string) => boolean;
+}
+declare function verifyIndexes(connection: IndexVerifiableConnection, options?: VerifyIndexesOptions): Promise<IndexVerifyReport>;
+/** One-line summary for a boot log. */
+declare function formatIndexReport(report: IndexVerifyReport): string;
+//#endregion
+export { IndexVerifiableConnection, IndexVerifiableModel, IndexVerifyReport, MissingIndex, VerifyIndexesOptions, formatIndexReport, verifyIndexes };

package/dist/indexes/verify-indexes.mjs

@@ -0,0 +1,76 @@
+//#region src/indexes/verify-indexes.ts
+/**
+* Order-sensitive: a compound index is not the same index with keys swapped.
+*
+* A SINGLE-field numeric index is direction-agnostic though — mongo traverses
+* an index either way, so `{t:1}` and `{t:-1}` are the same index and a schema
+* declaring one against a database holding the other is not drift. Only numeric
+* directions collapse; `2dsphere` / `hashed` are index TYPES, not directions.
+*/
+function normalizeKey(key) {
+	const entries = Object.entries(key);
+	if (entries.length === 1 && typeof entries[0]?.[1] === "number") return JSON.stringify([[entries[0][0]]]);
+	return JSON.stringify(entries);
+}
+/**
+* A TEXT index is stored under a key mongo invents (`{_fts, _ftsx}`) with the
+* real fields moved to `weights`, so it never matches its own declaration by
+* key. Compare the field SET instead, or every text index reads as permanently
+* missing and the whole check becomes noise nobody reads.
+*/
+function textFields(key) {
+	const fields = Object.entries(key).filter(([, dir]) => dir === "text").map(([field]) => field);
+	return fields.length > 0 ? fields.sort() : null;
+}
+async function verifyIndexes(connection, options = {}) {
+	const include = options.includeModel ?? (() => true);
+	const report = {
+		modelsChecked: 0,
+		missingUnique: [],
+		missingRegular: [],
+		unreadable: []
+	};
+	for (const name of connection.modelNames().sort()) {
+		if (!include(name)) continue;
+		const model = connection.model(name);
+		const declared = model.schema.indexes();
+		if (declared.length === 0) continue;
+		let existing;
+		let existingText;
+		try {
+			const live = await model.collection.listIndexes().toArray();
+			existing = new Set(live.map((i) => normalizeKey(i.key)));
+			existingText = new Set(live.filter((i) => i.weights).map((i) => JSON.stringify(Object.keys(i.weights).sort())));
+		} catch {
+			report.unreadable.push(name);
+			continue;
+		}
+		report.modelsChecked += 1;
+		for (const [key, indexOptions] of declared) {
+			const asText = textFields(key);
+			if (asText) {
+				if (existingText.has(JSON.stringify(asText))) continue;
+			} else if (existing.has(normalizeKey(key))) continue;
+			const entry = {
+				model: name,
+				collection: model.collection.name,
+				key: JSON.stringify(key)
+			};
+			if (indexOptions?.unique) report.missingUnique.push(entry);
+			else report.missingRegular.push(entry);
+		}
+	}
+	return report;
+}
+/** One-line summary for a boot log. */
+function formatIndexReport(report) {
+	const parts = [
+		`${report.modelsChecked} models checked`,
+		`missing unique: ${report.missingUnique.length}`,
+		`missing regular: ${report.missingRegular.length}`
+	];
+	if (report.unreadable.length > 0) parts.push(`unreadable: ${report.unreadable.length}`);
+	return `[index-check] ${parts.join(" — ")}`;
+}
+//#endregion
+export { formatIndexReport, verifyIndexes };

package/dist/outbox/index.mjs

@@ -1,4 +1,4 @@
-import { n as Repository } from "../Repository-BArvU32x.mjs";
+import { n as Repository } from "../Repository-Ck5x43wF.mjs";
 import { n as batchOperationsPlugin, t as methodRegistryPlugin } from "../method-registry.plugin-DblM7V6j.mjs";
 import { Schema } from "mongoose";
 //#region src/outbox/index.ts

package/dist/pagination/PaginationEngine.mjs

@@ -1,2 +1,2 @@
-import { t as PaginationEngine } from "../PaginationEngine-GdyX29tE.mjs";
+import { t as PaginationEngine } from "../PaginationEngine-BX9o_-4R.mjs";
 export { PaginationEngine };

package/dist/pagination/utils/limits.d.mts

@@ -0,0 +1,47 @@
+import { c as PaginationConfig } from "../../pagination-jSUdrACK.mjs";
+//#region src/pagination/utils/limits.d.ts
+/**
+ * Validates and sanitizes limit value
+ * Parses strings to numbers and prevents NaN bugs
+ *
+ * @param limit - Requested limit
+ * @param config - Pagination configuration
+ * @returns Sanitized limit between 1 and maxLimit
+ */
+declare function validateLimit(limit: number | string, config: PaginationConfig): number;
+/**
+ * Validates and sanitizes page number
+ * Parses strings to numbers and prevents NaN bugs
+ *
+ * @param page - Requested page (1-indexed)
+ * @param config - Pagination configuration
+ * @returns Sanitized page number >= 1
+ * @throws Error if page exceeds maxPage
+ */
+declare function validatePage(page: number | string, config: PaginationConfig): number;
+/**
+ * Checks if page number should trigger deep pagination warning
+ *
+ * @param page - Current page number
+ * @param threshold - Warning threshold
+ * @returns True if warning should be shown
+ */
+declare function shouldWarnDeepPagination(page: number, threshold: number): boolean;
+/**
+ * Calculates number of documents to skip for offset pagination
+ *
+ * @param page - Page number (1-indexed)
+ * @param limit - Documents per page
+ * @returns Number of documents to skip
+ */
+declare function calculateSkip(page: number, limit: number): number;
+/**
+ * Calculates total number of pages
+ *
+ * @param total - Total document count
+ * @param limit - Documents per page
+ * @returns Total number of pages
+ */
+declare function calculateTotalPages(total: number, limit: number): number;
+//#endregion
+export { calculateSkip, calculateTotalPages, shouldWarnDeepPagination, validateLimit, validatePage };

package/dist/pagination/utils/limits.mjs

@@ -0,0 +1,64 @@
+//#region src/pagination/utils/limits.ts
+/**
+* Validates and sanitizes limit value
+* Parses strings to numbers and prevents NaN bugs
+*
+* @param limit - Requested limit
+* @param config - Pagination configuration
+* @returns Sanitized limit between 1 and maxLimit
+*/
+function validateLimit(limit, config) {
+	const parsed = Number(limit);
+	if (!Number.isFinite(parsed) || parsed < 1) return config.defaultLimit ?? 10;
+	const max = config.maxLimit ?? 100;
+	if (max === 0) return Math.floor(parsed);
+	return Math.min(Math.floor(parsed), max);
+}
+/**
+* Validates and sanitizes page number
+* Parses strings to numbers and prevents NaN bugs
+*
+* @param page - Requested page (1-indexed)
+* @param config - Pagination configuration
+* @returns Sanitized page number >= 1
+* @throws Error if page exceeds maxPage
+*/
+function validatePage(page, config) {
+	const parsed = Number(page);
+	if (!Number.isFinite(parsed) || parsed < 1) return 1;
+	const sanitized = Math.floor(parsed);
+	if (sanitized > (config.maxPage || 1e4)) throw new Error(`Page ${sanitized} exceeds maximum ${config.maxPage || 1e4}`);
+	return sanitized;
+}
+/**
+* Checks if page number should trigger deep pagination warning
+*
+* @param page - Current page number
+* @param threshold - Warning threshold
+* @returns True if warning should be shown
+*/
+function shouldWarnDeepPagination(page, threshold) {
+	return page > threshold;
+}
+/**
+* Calculates number of documents to skip for offset pagination
+*
+* @param page - Page number (1-indexed)
+* @param limit - Documents per page
+* @returns Number of documents to skip
+*/
+function calculateSkip(page, limit) {
+	return (page - 1) * limit;
+}
+/**
+* Calculates total number of pages
+*
+* @param total - Total document count
+* @param limit - Documents per page
+* @returns Total number of pages
+*/
+function calculateTotalPages(total, limit) {
+	return Math.ceil(total / limit);
+}
+//#endregion
+export { calculateSkip, calculateTotalPages, shouldWarnDeepPagination, validateLimit, validatePage };

package/dist/plugins/index.mjs

@@ -1,6 +1,6 @@
-import { a as customIdPlugin, c as prefixedId, d as AuditTrailQuery, f as auditTrailPlugin, i as multiTenantPlugin, l as sequentialId, m as auditLogPlugin, n as softDeletePlugin, o as dateSequentialId, p as ensureAuditTrailReady, s as getNextSequence, t as timestampPlugin, u as cachePlugin } from "../timestamp.plugin-BEc6TANm.mjs";
+import { a as customIdPlugin, c as prefixedId, d as AuditTrailQuery, f as auditTrailPlugin, i as multiTenantPlugin, l as sequentialId, m as auditLogPlugin, n as softDeletePlugin, o as dateSequentialId, p as ensureAuditTrailReady, s as getNextSequence, t as timestampPlugin, u as cachePlugin } from "../timestamp.plugin-CBQukQzV.mjs";
 import { n as batchOperationsPlugin, t as methodRegistryPlugin } from "../method-registry.plugin-DblM7V6j.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-CyK1s9Ze.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-DhNyxNCw.mjs";
 //#region src/plugins/change-log.plugin.ts
 const PLUGIN_NAME = "changeLog";
 function isSkipped(context) {

package/dist/testkit/index.mjs

@@ -1,4 +1,4 @@
-import { t as createRepository } from "../create-repository-CPNbktFG.mjs";
+import { t as createRepository } from "../create-repository-B5EulQ31.mjs";
 import { createConnection } from "mongoose";
 //#region src/testkit/index.ts
 function idempotentStop(server) {

package/dist/{timestamp.plugin-BEc6TANm.mjs → timestamp.plugin-CBQukQzV.mjs}

@@ -1,4 +1,4 @@
-import { c as ALL_OPERATIONS, t as HOOK_PRIORITY, u as OP_REGISTRY } from "./Repository-BArvU32x.mjs";
+import { c as ALL_OPERATIONS, t as HOOK_PRIORITY, u as OP_REGISTRY } from "./Repository-Ck5x43wF.mjs";
 import { n as warn } from "./logger-K7dPmu2U.mjs";
 import { throwIfAborted, withRetry } from "@classytic/repo-core/repository";
 import mongoose from "mongoose";
@@ -1290,6 +1290,50 @@ function softDeletePlugin(options = {}) {
 					};
 				}
 			}, { priority: HOOK_PRIORITY.POLICY });
+			/**
+			* Hook: before:bulkWrite — every sub-op gets what its standalone form gets.
+			*
+			* This was skipped as "not a single filter we can scope", but a sub-op DOES carry
+			* its own filter — the tenant plugin walks exactly these keys. Skipping it meant a
+			* soft-delete repository's `bulkWrite` updated rows it had already deleted, and
+			* HARD-deleted through `deleteOne`/`deleteMany`, destroying data the model says is
+			* recoverable. The suite's own header claimed this was covered.
+			*
+			* `deleteMode: 'hard'` still bypasses, exactly as the single-doc path does — a purge
+			* is a deliberate physical delete, and it reaches the driver directly anyway.
+			*/
+			repo.on("before:bulkWrite", (context) => {
+				if (options.soft === false || context.deleteMode === "hard") return;
+				const ops = context.operations;
+				if (!Array.isArray(ops)) return;
+				const notDeleted = buildDeletedFilter(deletedField, filterMode, false);
+				for (const subOp of ops) {
+					if (!subOp || typeof subOp !== "object") continue;
+					for (const key of [
+						"updateOne",
+						"updateMany",
+						"replaceOne"
+					]) {
+						const body = subOp[key];
+						if (body?.filter) body.filter = {
+							...body.filter,
+							...notDeleted
+						};
+					}
+					for (const [key, target] of [["deleteOne", "updateOne"], ["deleteMany", "updateMany"]]) {
+						const body = subOp[key];
+						if (!body?.filter) continue;
+						subOp[target] = {
+							filter: {
+								...body.filter,
+								...notDeleted
+							},
+							update: { $set: { [deletedField]: /* @__PURE__ */ new Date() } }
+						};
+						delete subOp[key];
+					}
+				}
+			}, { priority: HOOK_PRIORITY.POLICY });
 			repo.on("before:deleteMany", async (context) => {
 				if (context.deleteMode === "hard") return;
 				if (options.soft !== false) {

package/dist/{validation-chain.plugin-CyK1s9Ze.mjs → validation-chain.plugin-DhNyxNCw.mjs}

@@ -1,5 +1,5 @@
 import { n as collectIds, r as idChunks, t as DEFAULT_ID_CHUNK } from "./id-chunks-BmAwsqNk.mjs";
-import { c as ALL_OPERATIONS, u as OP_REGISTRY } from "./Repository-BArvU32x.mjs";
+import { c as ALL_OPERATIONS, u as OP_REGISTRY } from "./Repository-Ck5x43wF.mjs";
 import { _ as upsert } from "./update-jSXp3nu3.mjs";
 import { n as warn } from "./logger-K7dPmu2U.mjs";
 import { t as createError } from "./error-BuByZwKU.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/mongokit",
-  "version": "3.36.0",
+  "version": "3.38.1",
   "description": "Production-grade MongoDB repositories - smart pagination, events, and plugins. Built on @classytic/repo-core.",
   "type": "module",
   "sideEffects": false,
@@ -16,6 +16,10 @@
       "types": "./dist/pagination/PaginationEngine.d.mts",
       "default": "./dist/pagination/PaginationEngine.mjs"
     },
+    "./pagination/limits": {
+      "types": "./dist/pagination/utils/limits.d.mts",
+      "default": "./dist/pagination/utils/limits.mjs"
+    },
     "./plugins": {
       "types": "./dist/plugins/index.d.mts",
       "default": "./dist/plugins/index.mjs"
@@ -64,6 +68,10 @@
       "types": "./dist/query/primitives/indexes.d.mts",
       "default": "./dist/query/primitives/indexes.mjs"
     },
+    "./indexes": {
+      "types": "./dist/indexes/verify-indexes.d.mts",
+      "default": "./dist/indexes/verify-indexes.mjs"
+    },
     "./testkit": {
       "types": "./dist/testkit/index.d.mts",
       "default": "./dist/testkit/index.mjs"
@@ -122,7 +130,7 @@
   },
   "homepage": "https://github.com/classytic/mongokit#readme",
   "peerDependencies": {
-    "@classytic/repo-core": ">=0.25.0",
+    "@classytic/repo-core": ">=0.27.0",
     "mongodb-memory-server": ">=10.4.3",
     "mongoose": ">=9.4.1"
   },
@@ -174,7 +182,7 @@
     "@better-auth/mongo-adapter": "^1.6.29",
     "@biomejs/biome": "^2.5.8",
     "@classytic/dev-tools": "^0.2.0",
-    "@classytic/repo-core": "^0.25.0",
+    "@classytic/repo-core": "^0.27.0",
     "@types/node": "^26.2.0",
     "@vitest/coverage-v8": "^4.1.10",
     "ajv": "^8.20.0",