monsqlize 2.0.2 → 2.0.4

package/dist/esm/index.mjs

@@ -128,8 +128,8 @@ function createQueryTimeoutError(timeoutMs) {
 }
 
 // src/capabilities/cache/redis-cache-adapter.ts
-var LEGACY_INVALID_REDIS_ARG_ERROR = "redisUrlOrInstance \u5FC5\u987B\u662F Redis URL \u5B57\u7B26\u4E32\u6216 ioredis \u5B9E\u4F8B";
-var LEGACY_IOREDIS_MISSING_ERROR = "ioredis \u672A\u5B89\u88C5\u3002\u8BF7\u8FD0\u884C: npm install ioredis\n\u6216\u4F20\u5165\u5DF2\u521B\u5EFA\u7684 ioredis \u5B9E\u4F8B";
+var LEGACY_INVALID_REDIS_ARG_ERROR = "redisUrlOrInstance must be a Redis URL string or an ioredis instance";
+var LEGACY_IOREDIS_MISSING_ERROR = "Unable to load ioredis. monsqlize installs ioredis by default; check package installation completeness or pass an existing ioredis instance";
 function isMissingIoredisError(error) {
   if (!(error instanceof Error)) {
     return false;
@@ -139,14 +139,14 @@ function isMissingIoredisError(error) {
 function createLegacyRedisError(message, code = ErrorCodes.INVALID_ARGUMENT) {
   return createError(code, message);
 }
-function createRedisCacheAdapter(redisUrlOrInstance) {
+function createRedisCacheAdapter(redisUrlOrInstance, options) {
   if (typeof redisUrlOrInstance === "string") {
     const redisUrl = redisUrlOrInstance.trim();
     if (!redisUrl) {
       throw createLegacyRedisError(LEGACY_INVALID_REDIS_ARG_ERROR);
     }
     try {
-      return createHubRedisCacheAdapter(redisUrl);
+      return createHubRedisCacheAdapter(redisUrl, options);
     } catch (error) {
       if (isMissingIoredisError(error)) {
         throw createLegacyRedisError(LEGACY_IOREDIS_MISSING_ERROR, ErrorCodes.CACHE_UNAVAILABLE);
@@ -155,7 +155,7 @@ function createRedisCacheAdapter(redisUrlOrInstance) {
     }
   }
   if (redisUrlOrInstance && typeof redisUrlOrInstance === "object") {
-    return createHubRedisCacheAdapter(redisUrlOrInstance);
+    return createHubRedisCacheAdapter(redisUrlOrInstance, options);
   }
   throw createLegacyRedisError(LEGACY_INVALID_REDIS_ARG_ERROR);
 }
@@ -165,7 +165,7 @@ import { randomBytes } from "crypto";
 var DistributedCacheInvalidator = class {
   constructor(options) {
     if (!options.cache) {
-      throw new Error("DistributedCacheInvalidator requires a cache instance");
+      throw createError(ErrorCodes.CACHE_UNAVAILABLE, "DistributedCacheInvalidator requires a cache instance");
     }
     this._cache = options.cache;
     this._logger = options.logger ?? null;
@@ -183,7 +183,7 @@ var DistributedCacheInvalidator = class {
       this.pub = new Redis(options.redisUrl);
       this.sub = new Redis(options.redisUrl);
     } else {
-      throw new Error("DistributedCacheInvalidator requires either redis or redisUrl");
+      throw createError(ErrorCodes.INVALID_CONFIG, "DistributedCacheInvalidator requires either redis or redisUrl");
     }
     this._setupSubscription();
   }
@@ -363,17 +363,17 @@ var _PopulatePromise = class _PopulatePromise {
   /**
    * Append a populate path and return a new PopulatePromise (chainable).
    */
-  populate(path2, options) {
+  populate(path3, options) {
     const toConfig = (item) => {
       if (typeof item !== "string" && (typeof item !== "object" || item === null || Array.isArray(item))) {
         throw createError(ErrorCodes.INVALID_ARGUMENT, "populate param must be a string, array, or object");
       }
       return typeof item === "string" ? { path: item, ...options } : { ...item, ...options };
     };
-    if (Array.isArray(path2)) {
-      return new _PopulatePromise(this.executor, [...this.paths, ...path2.map(toConfig)]);
+    if (Array.isArray(path3)) {
+      return new _PopulatePromise(this.executor, [...this.paths, ...path3.map(toConfig)]);
     }
-    const config = toConfig(path2);
+    const config = toConfig(path3);
     return new _PopulatePromise(this.executor, [...this.paths, config]);
   }
   /**
@@ -487,8 +487,8 @@ function validateRelationConfig(name, config) {
     throw createError(ErrorCodes.INVALID_ARGUMENT, `relations.single must be a boolean`);
   }
 }
-function normalizePopulateConfig(path2) {
-  return typeof path2 === "string" ? { path: path2 } : path2;
+function normalizePopulateConfig(path3) {
+  return typeof path3 === "string" ? { path: path3 } : path3;
 }
 
 // src/capabilities/model/model-registry.ts
@@ -639,8 +639,8 @@ function groupBy(values, keySelector) {
   }
   return map;
 }
-function getByPath(source, path2) {
-  return path2.split(".").reduce((current, key) => {
+function getByPath(source, path3) {
+  return path3.split(".").reduce((current, key) => {
     if (!current || typeof current !== "object") {
       return void 0;
     }
@@ -695,8 +695,8 @@ function resolveRegisteredCollectionName(registered, fallback) {
   const definition = registered.definition;
   return definition.collection ?? definition.name ?? registered.collectionName;
 }
-async function populateModelPath(context, docs, path2) {
-  const config = normalizePopulateConfig(path2);
+async function populateModelPath(context, docs, path3) {
+  const config = normalizePopulateConfig(path3);
   if (docs.length === 0) {
     return docs;
   }
@@ -813,8 +813,8 @@ function hydrateModelDocument(context, doc) {
     populate: {
       configurable: true,
       enumerable: false,
-      value: (path2) => {
-        const paths = Array.isArray(path2) ? path2 : [path2];
+      value: (path3) => {
+        const paths = Array.isArray(path3) ? path3 : [path3];
         return new PopulatePromise(
           (resolvedPaths) => context.populateDocument(hydrated, resolvedPaths),
           paths
@@ -980,6 +980,75 @@ function stableIndexStringify(value) {
   }
   return JSON.stringify(value) ?? "undefined";
 }
+function getIndexOptionName(options) {
+  return typeof options.name === "string" && options.name.length > 0 ? options.name : void 0;
+}
+function summarizeIndexError(error) {
+  if (error instanceof Error) {
+    const record = error;
+    return {
+      name: error.name,
+      message: error.message,
+      code: record.code ?? record.codeName
+    };
+  }
+  return {
+    message: String(error)
+  };
+}
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function getExistingIndexKey(index) {
+  return index.key;
+}
+function declaredOptionEntries(options) {
+  return Object.entries(options).filter(([name, value]) => {
+    if (value === void 0) return false;
+    if (name === "background") return false;
+    return true;
+  });
+}
+function indexOptionsMatch(existing, declared) {
+  if (stableIndexStringify(getExistingIndexKey(existing)) !== stableIndexStringify(declared.key)) {
+    return false;
+  }
+  for (const [name, value] of declaredOptionEntries(declared.options)) {
+    const existingValue = existing[name];
+    if (value === false && existingValue === void 0) {
+      continue;
+    }
+    if (stableIndexStringify(existingValue) !== stableIndexStringify(value)) {
+      return false;
+    }
+  }
+  return true;
+}
+function findExistingIndexByName(existingIndexes, name) {
+  if (!name) return void 0;
+  return existingIndexes.find((index) => index.name === name);
+}
+function findExistingIndexByKey(existingIndexes, key) {
+  const fingerprint = stableIndexStringify(key);
+  return existingIndexes.find((index) => stableIndexStringify(getExistingIndexKey(index)) === fingerprint);
+}
+function createIndexEnsureError(message, result, cause) {
+  return createError(ErrorCodes.MONGODB_ERROR, message, [result], cause);
+}
+function resolveModelAutoIndexOptions(definition, runtimeAutoIndex) {
+  const modelAutoIndex = toCompatDefinition(definition).options?.autoIndex;
+  const value = modelAutoIndex ?? runtimeAutoIndex;
+  if (value === false) {
+    return { enabled: false, emitEvents: true };
+  }
+  if (value && typeof value === "object") {
+    return {
+      enabled: value.enabled !== false,
+      emitEvents: value.emitEvents !== false
+    };
+  }
+  return { enabled: true, emitEvents: true };
+}
 function getIndexTaskRegistry(runtime) {
   if (!runtime) {
     return fallbackModelIndexTasks;
@@ -1007,6 +1076,20 @@ function resolveIndexTaskScope(collection, options) {
     };
   }
 }
+function toIndexNamespace(scope) {
+  return {
+    db: scope.dbName,
+    collection: scope.collectionName,
+    poolName: scope.poolName
+  };
+}
+function emitIndexFailure(runtime, payload, emitEvents) {
+  if (!emitEvents) {
+    return;
+  }
+  const emitter = runtime;
+  emitter?.emit?.("model-index-error", payload);
+}
 function warnIndexFailure(runtime, taskKey, error) {
   const logger = runtime;
   logger?.logger?.warn?.("[MonSQLize] model index creation failed", {
@@ -1014,9 +1097,10 @@ function warnIndexFailure(runtime, taskKey, error) {
     error: error instanceof Error ? error.message : String(error)
   });
 }
-function scheduleIndexTask(collection, key, indexOptions, options) {
+function scheduleIndexTask(collection, declaredIndex, emitEvents, options) {
   const scope = resolveIndexTaskScope(collection, options);
-  const indexFingerprint = stableIndexStringify({ key, options: indexOptions });
+  const { key, options: indexOptions } = declaredIndex;
+  const indexFingerprint = declaredIndex.fingerprint;
   const taskKey = `${scope.poolName}:${scope.dbName}:${scope.collectionName}:${indexFingerprint}`;
   const registry = getIndexTaskRegistry(options?.runtime);
   const existing = registry.get(taskKey);
@@ -1034,6 +1118,14 @@ function scheduleIndexTask(collection, key, indexOptions, options) {
           task.status = "failed";
           task.error = error;
           warnIndexFailure(options?.runtime, taskKey, error);
+          emitIndexFailure(options?.runtime, {
+            namespace: scope,
+            taskKey,
+            source: declaredIndex.source,
+            key,
+            options: indexOptions,
+            error: summarizeIndexError(error)
+          }, emitEvents);
           resolve();
         });
       });
@@ -1150,6 +1242,134 @@ function resolveModelHooksFactory(definition) {
   const hooks = toCompatDefinition(definition).hooks;
   return typeof hooks === "function" ? hooks : null;
 }
+function collectModelIndexDefinitions(definition, softDeleteConfig) {
+  const declared = [];
+  if (softDeleteConfig?.enabled && softDeleteConfig.type === "timestamp" && softDeleteConfig.ttl) {
+    const key = { [softDeleteConfig.field]: 1 };
+    const options = { expireAfterSeconds: softDeleteConfig.ttl };
+    declared.push({
+      source: "softDelete",
+      key,
+      options,
+      name: getIndexOptionName(options),
+      fingerprint: stableIndexStringify({ key, options })
+    });
+  }
+  const indexes = toCompatDefinition(definition).indexes;
+  if (!Array.isArray(indexes) || indexes.length === 0) {
+    return declared;
+  }
+  for (const indexSpec of indexes) {
+    if (!isRecord(indexSpec) || !indexSpec.key) {
+      continue;
+    }
+    const { key, ...indexOptions } = indexSpec;
+    declared.push({
+      source: "definition",
+      key,
+      options: indexOptions,
+      name: getIndexOptionName(indexOptions),
+      fingerprint: stableIndexStringify({ key, options: indexOptions })
+    });
+  }
+  return declared;
+}
+async function ensureModelIndexesForCollection(collection, definition, softDeleteConfig, options = {}) {
+  const namespace = toIndexNamespace(resolveIndexTaskScope(collection, options));
+  const declared = collectModelIndexDefinitions(definition, softDeleteConfig);
+  const existingIndexes = await collection.listIndexes();
+  const existing = [];
+  const missing = [];
+  const conflicts = [];
+  for (const declaredIndex of declared) {
+    const existingByName = findExistingIndexByName(existingIndexes, declaredIndex.name);
+    if (existingByName) {
+      if (indexOptionsMatch(existingByName, declaredIndex)) {
+        existing.push({ declared: declaredIndex, existing: existingByName });
+      } else {
+        conflicts.push({
+          declared: declaredIndex,
+          existing: existingByName,
+          reason: "name-conflict"
+        });
+      }
+      continue;
+    }
+    const existingByKey = findExistingIndexByKey(existingIndexes, declaredIndex.key);
+    if (existingByKey) {
+      if (indexOptionsMatch(existingByKey, declaredIndex)) {
+        existing.push({ declared: declaredIndex, existing: existingByKey });
+      } else {
+        conflicts.push({
+          declared: declaredIndex,
+          existing: existingByKey,
+          reason: "options-conflict"
+        });
+      }
+      continue;
+    }
+    missing.push(declaredIndex);
+  }
+  const result = {
+    dryRun: options.dryRun === true,
+    namespace,
+    declared,
+    existing,
+    missing,
+    created: [],
+    conflicts,
+    failed: [],
+    skipped: options.dryRun === true ? missing.map((declaredIndex) => ({ declared: declaredIndex, reason: "dry-run" })) : conflicts.map((conflict) => ({ declared: conflict.declared, reason: conflict.reason }))
+  };
+  if (conflicts.length > 0 && options.throwOnError) {
+    throw createIndexEnsureError("Model index conflicts detected.", result);
+  }
+  if (options.dryRun === true) {
+    return result;
+  }
+  for (const declaredIndex of missing) {
+    try {
+      const createdName = await collection.createIndex(declaredIndex.key, declaredIndex.options);
+      result.created.push({
+        declared: declaredIndex,
+        name: typeof createdName === "string" ? createdName : void 0,
+        result: createdName
+      });
+    } catch (error) {
+      result.failed.push({
+        declared: declaredIndex,
+        error: summarizeIndexError(error)
+      });
+      if (options.throwOnError) {
+        throw createIndexEnsureError(
+          "Model index creation failed.",
+          result,
+          error instanceof Error ? error : void 0
+        );
+      }
+    }
+  }
+  return result;
+}
+function summarizeModelIndexEnsureResults(results) {
+  return results.reduce((totals, result) => ({
+    declared: totals.declared + result.declared.length,
+    existing: totals.existing + result.existing.length,
+    missing: totals.missing + result.missing.length,
+    created: totals.created + result.created.length,
+    conflicts: totals.conflicts + result.conflicts.length,
+    failed: totals.failed + result.failed.length,
+    skipped: totals.skipped + result.skipped.length
+  }), {
+    declared: 0,
+    existing: 0,
+    missing: 0,
+    created: 0,
+    conflicts: 0,
+    failed: 0,
+    skipped: 0
+  });
+}
 function initializeModelV1Methods(target, definition) {
   const methods = toCompatDefinition(definition).methods;
   if (typeof methods !== "function") {
@@ -1174,25 +1394,12 @@ function initializeModelV1Methods(target, definition) {
   }
 }
 function scheduleModelIndexes(collection, definition, softDeleteConfig, options) {
-  if (softDeleteConfig?.enabled && softDeleteConfig.type === "timestamp" && softDeleteConfig.ttl) {
-    const softDeleteIndex = softDeleteConfig;
-    scheduleIndexTask(
-      collection,
-      { [softDeleteIndex.field]: 1 },
-      { expireAfterSeconds: softDeleteIndex.ttl },
-      options
-    );
-  }
-  const indexes = toCompatDefinition(definition).indexes;
-  if (!Array.isArray(indexes) || indexes.length === 0) {
+  const autoIndex = resolveModelAutoIndexOptions(definition, options?.autoIndex);
+  if (!autoIndex.enabled) {
     return;
   }
-  for (const indexSpec of indexes) {
-    if (!indexSpec?.key) {
-      continue;
-    }
-    const { key, ...indexOptions } = indexSpec;
-    scheduleIndexTask(collection, key, indexOptions, options);
+  for (const declaredIndex of collectModelIndexDefinitions(definition, softDeleteConfig)) {
+    scheduleIndexTask(collection, declaredIndex, autoIndex.emitEvents, options);
   }
 }
 
@@ -1760,7 +1967,8 @@ var ModelInstance = class {
       runtime: this.runtime,
       dbName: options.dbName,
       poolName: options.poolName,
-      collectionName: options.collectionName
+      collectionName: options.collectionName,
+      autoIndex: this.runtime.options?.autoIndex
     });
     this._v1InstanceMethods = initializeModelV1Methods(this, options.definition);
   }
@@ -1964,6 +2172,15 @@ var ModelInstance = class {
   listIndexes() {
     return this.collection.listIndexes();
   }
+  ensureIndexes(options = {}) {
+    return ensureModelIndexesForCollection(this.collection, this.definition, this._softDeleteConfig, {
+      ...options,
+      runtime: this.runtime,
+      dbName: this.dbName,
+      poolName: this.poolName,
+      collectionName: this.collectionName
+    });
+  }
   dropIndex(name) {
     return this.collection.dropIndex(name);
   }
@@ -2049,18 +2266,18 @@ var ModelInstance = class {
   }
   async populateDocuments(docs, paths) {
     let current = docs;
-    for (const path2 of paths) {
-      current = await this.populatePath(current, path2);
+    for (const path3 of paths) {
+      current = await this.populatePath(current, path3);
     }
     return current;
   }
-  async populatePath(docs, path2) {
+  async populatePath(docs, path3) {
     return populateModelPath({
       relations: this.relations,
       runtime: this.runtime,
       dbName: this.dbName,
       poolName: this.poolName
-    }, docs, path2);
+    }, docs, path3);
   }
   hydrateDocuments(docs) {
     return docs.filter(Boolean).map((doc) => this.hydrateDocument(doc));
@@ -2233,9 +2450,9 @@ var Transaction = class {
    */
   async start() {
     if (this.state !== "pending") {
-      throw new Error(`Cannot start transaction in state: ${this.state}`);
+      throw createError(ErrorCodes.INVALID_OPERATION, `Cannot start transaction in state: ${this.state}`);
     }
-    this.session.startTransaction();
+    this.session.startTransaction(this.options.transactionOptions);
     this.state = "active";
     this.startedAt = Date.now();
     const timeout = this.options.timeout ?? 3e4;
@@ -2255,7 +2472,7 @@ var Transaction = class {
    */
   async commit() {
     if (this.state !== "active") {
-      throw new Error(`Cannot commit transaction in state: ${this.state}`);
+      throw createError(ErrorCodes.INVALID_OPERATION, `Cannot commit transaction in state: ${this.state}`);
     }
     if (typeof this.session.commitTransaction === "function") {
       await this.session.commitTransaction();
@@ -2353,7 +2570,9 @@ var TransactionManager = class {
     this.stats = {
       totalTransactions: 0,
       successfulTransactions: 0,
-      failedTransactions: 0
+      failedTransactions: 0,
+      readOnlyTransactions: 0,
+      writeTransactions: 0
     };
     const options = "client" in input ? input : {
       client: input,
@@ -2364,6 +2583,10 @@ var TransactionManager = class {
     this.cache = options.cache ?? null;
     this.logger = options.logger ?? null;
     this.lockManager = options.lockManager ?? null;
+    this.defaultReadConcern = options.defaultReadConcern;
+    this.defaultWriteConcern = options.defaultWriteConcern;
+    this.defaultReadPreference = options.defaultReadPreference;
+    this.maxStatsSamples = options.maxStatsSamples ?? 1e3;
     this.defaultOptions = {
       maxDuration: options.maxDuration ?? 3e4,
       enableRetry: options.enableRetry ?? true,
@@ -2380,11 +2603,17 @@ var TransactionManager = class {
     const session = this.client.startSession({
       causalConsistency: options.causalConsistency !== false
     });
+    const transactionOptions = {
+      readConcern: options.readConcern ?? this.defaultReadConcern,
+      writeConcern: options.writeConcern ?? this.defaultWriteConcern,
+      readPreference: options.readPreference ?? this.defaultReadPreference
+    };
     const transaction = new Transaction(session, {
       cache: this.cache,
       logger: this.logger,
       lockManager: options.enableCacheLock === false ? null : this.lockManager,
-      timeout: options.timeout ?? options.maxDuration ?? this.defaultOptions.maxDuration
+      timeout: options.timeout ?? options.maxDuration ?? this.defaultOptions.maxDuration,
+      transactionOptions: compactUndefined(transactionOptions)
     });
     const originalEnd = transaction.end.bind(transaction);
     transaction.end = async () => {
@@ -2411,12 +2640,12 @@ var TransactionManager = class {
         await transaction.start();
         const result = await callback(transaction);
         await transaction.commit();
-        this.recordStats(Date.now() - startedAt, true);
+        this.recordStats(transaction, Date.now() - startedAt, true);
         return result;
       } catch (error) {
         lastError = error;
         await transaction.abort();
-        this.recordStats(Date.now() - startedAt, false);
+        this.recordStats(transaction, Date.now() - startedAt, false);
         if (!enableRetry || attempt === maxRetries || !isTransientTransactionError(error)) {
           throw error;
         }
@@ -2452,27 +2681,54 @@ var TransactionManager = class {
    */
   getStats() {
     const averageDuration = this.durations.length === 0 ? 0 : this.durations.reduce((sum, item) => sum + item, 0) / this.durations.length;
+    const sortedDurations = [...this.durations].sort((a, b) => a - b);
+    const p95Duration = percentile(sortedDurations, 0.95);
+    const p99Duration = percentile(sortedDurations, 0.99);
+    const totalTransactions = this.stats.totalTransactions;
     return {
-      totalTransactions: this.stats.totalTransactions,
+      totalTransactions,
       successfulTransactions: this.stats.successfulTransactions,
       failedTransactions: this.stats.failedTransactions,
+      readOnlyTransactions: this.stats.readOnlyTransactions,
+      writeTransactions: this.stats.writeTransactions,
       activeTransactions: this.activeTransactions.size,
-      averageDuration
+      averageDuration,
+      p95Duration,
+      p99Duration,
+      successRate: totalTransactions > 0 ? `${(this.stats.successfulTransactions / totalTransactions * 100).toFixed(2)}%` : "0%",
+      readOnlyRatio: totalTransactions > 0 ? `${(this.stats.readOnlyTransactions / totalTransactions * 100).toFixed(2)}%` : "0%",
+      sampleCount: this.durations.length
     };
   }
-  recordStats(duration, success) {
+  recordStats(transaction, duration, success) {
     this.stats.totalTransactions += 1;
     if (success) {
       this.stats.successfulTransactions += 1;
     } else {
       this.stats.failedTransactions += 1;
     }
+    if (transaction.pendingInvalidations.size > 0) {
+      this.stats.writeTransactions += 1;
+    } else {
+      this.stats.readOnlyTransactions += 1;
+    }
     this.durations.push(duration);
-    if (this.durations.length > 100) {
+    if (this.durations.length > this.maxStatsSamples) {
       this.durations.shift();
     }
   }
 };
+function percentile(sortedValues, ratio) {
+  if (sortedValues.length === 0) {
+    return 0;
+  }
+  const index = Math.floor(sortedValues.length * ratio);
+  return sortedValues[Math.min(index, sortedValues.length - 1)] ?? 0;
+}
+function compactUndefined(value) {
+  const entries = Object.entries(value).filter(([, item]) => item !== void 0);
+  return entries.length === 0 ? void 0 : Object.fromEntries(entries);
+}
 function stringifySessionId(id) {
   if (typeof id === "string") {
     return id;
@@ -2509,18 +2765,166 @@ async function sleep(ms) {
 }
 
 // src/adapters/mongodb/common/connect.ts
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync } from "node:fs";
+import path from "node:path";
 import { MongoClient } from "mongodb";
+var DEFAULT_MEMORY_SERVER_VERSION = "7.0.14";
+var MANAGED_DB_PATH_PREFIXES = ["single-", "replset-", "examples-single-", "examples-replset-", "probe-single-", "probe-replset-"];
 var _memoryServerInstance = null;
+var _memoryServerCleanupOptions = { doCleanup: true, force: true };
+var _memoryServerDbPath = null;
+var _memoryServerClients = /* @__PURE__ */ new Set();
+function setDefaultEnv(name, value) {
+  if (!process.env[name]) {
+    process.env[name] = value;
+  }
+}
+function sanitizePathSegment(input) {
+  return input.replace(/[^a-zA-Z0-9_.-]+/g, "-").replace(/^-+|-+$/g, "") || "default";
+}
+function parseManagedPathPid(name) {
+  if (!MANAGED_DB_PATH_PREFIXES.some((prefix) => name.startsWith(prefix))) {
+    return null;
+  }
+  const match = /-(\d+)-[^-]+$/.exec(name);
+  if (!match) {
+    return null;
+  }
+  const pid = Number.parseInt(match[1], 10);
+  return Number.isFinite(pid) && pid > 0 ? pid : null;
+}
+function isProcessAlive(pid) {
+  if (pid === process.pid) {
+    return true;
+  }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+}
+function pruneManagedDbRoot(dbRoot) {
+  let entries;
+  try {
+    entries = readdirSync(dbRoot, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    const pid = parseManagedPathPid(entry.name);
+    if (!pid || isProcessAlive(pid)) {
+      continue;
+    }
+    try {
+      rmSync(path.join(dbRoot, entry.name), { recursive: true, force: true });
+    } catch {
+    }
+  }
+}
+function resolveMemoryServerBinaryVersion(memoryServerOptions = {}) {
+  return memoryServerOptions?.binary?.version || process.env.MONSQLIZE_REPLSET_BINARY_VERSION || process.env.MONSQLIZE_MEMORY_MONGO_BINARY_VERSION || process.env.MONGOMS_VERSION || DEFAULT_MEMORY_SERVER_VERSION;
+}
+function resolveMemoryServerPolicy(binaryVersion) {
+  const cacheRoot = path.resolve(process.env.MONSQLIZE_MEMORY_SERVER_CACHE_DIR || path.join(process.cwd(), ".cache", "mongodb-memory-server"));
+  const downloadDir = path.resolve(process.env.MONGOMS_DOWNLOAD_DIR || path.join(cacheRoot, "binaries"));
+  const dbRoot = path.resolve(process.env.MONSQLIZE_MEMORY_SERVER_DB_DIR || path.join(cacheRoot, "db"));
+  mkdirSync(downloadDir, { recursive: true });
+  mkdirSync(dbRoot, { recursive: true });
+  pruneManagedDbRoot(dbRoot);
+  setDefaultEnv("MONGOMS_DOWNLOAD_DIR", downloadDir);
+  setDefaultEnv("MONGOMS_PREFER_GLOBAL_PATH", "false");
+  setDefaultEnv("MONGOMS_RUNTIME_DOWNLOAD", "true");
+  setDefaultEnv("MONGOMS_VERSION", binaryVersion);
+  return { downloadDir, dbRoot };
+}
+function createManagedDbPath(dbRoot, dbName) {
+  return mkdtempSync(path.join(dbRoot, `replset-${sanitizePathSegment(dbName)}-${process.pid}-`));
+}
+function isManagedCleanupError(error, dbPath) {
+  if (!error || typeof error !== "object") {
+    return false;
+  }
+  const candidate = error;
+  if (!candidate.code || !["ENOTEMPTY", "EBUSY", "EPERM", "ENOENT"].includes(candidate.code)) {
+    return false;
+  }
+  return !candidate.path || path.resolve(candidate.path).startsWith(path.resolve(dbPath));
+}
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function cleanupManagedDbPath(dbPath) {
+  if (!dbPath) {
+    return true;
+  }
+  for (const waitMs of [0, 50, 100, 200, 400, 800]) {
+    if (waitMs > 0) {
+      await delay(waitMs);
+    }
+    try {
+      rmSync(dbPath, { recursive: true, force: true });
+      if (!existsSync(dbPath)) {
+        return true;
+      }
+    } catch {
+    }
+  }
+  return !existsSync(dbPath);
+}
+function resolveLaunchTimeout() {
+  const raw = process.env.MONSQLIZE_MEMORY_MONGO_LAUNCH_TIMEOUT_MS;
+  if (!raw) {
+    return void 0;
+  }
+  const value = Number.parseInt(raw, 10);
+  return Number.isFinite(value) && value > 0 ? value : void 0;
+}
+async function seedMemoryServerBinaryCache(binaryVersion, downloadDir) {
+  try {
+    const { DryMongoBinary } = __require("mongodb-memory-server-core/lib/util/DryMongoBinary");
+    const options = await DryMongoBinary.generateOptions({ version: binaryVersion, downloadDir });
+    options.downloadDir = downloadDir;
+    const paths = await DryMongoBinary.generatePaths(options);
+    if (paths.resolveConfig && paths.homeCache && path.resolve(paths.resolveConfig) !== path.resolve(paths.homeCache) && existsSync(paths.homeCache) && !existsSync(paths.resolveConfig)) {
+      mkdirSync(path.dirname(paths.resolveConfig), { recursive: true });
+      copyFileSync(paths.homeCache, paths.resolveConfig);
+    }
+  } catch {
+  }
+}
 async function startMemoryServer(logger, memoryServerOptions = {}) {
   if (_memoryServerInstance) {
     return _memoryServerInstance.getUri();
   }
+  const binaryVersion = resolveMemoryServerBinaryVersion(memoryServerOptions);
+  const { dbRoot, downloadDir } = resolveMemoryServerPolicy(binaryVersion);
+  await seedMemoryServerBinaryCache(binaryVersion, downloadDir);
   const { MongoMemoryReplSet } = __require("mongodb-memory-server");
-  logger?.info?.("\u{1F680} Starting MongoDB Memory ReplSet (transactions supported)...");
+  logger?.info?.("Starting MongoDB Memory ReplSet", { binaryVersion });
+  const dbName = memoryServerOptions?.instance?.dbName || "monsqlize_memory";
+  const instanceConfig = { ...memoryServerOptions?.instance ?? {} };
+  const hasUserDbPath = typeof instanceConfig.dbPath === "string" && instanceConfig.dbPath.length > 0;
+  if (!hasUserDbPath) {
+    _memoryServerDbPath = createManagedDbPath(dbRoot, dbName);
+    instanceConfig.dbPath = _memoryServerDbPath;
+  } else {
+    _memoryServerDbPath = null;
+  }
+  if (instanceConfig.launchTimeout === void 0) {
+    const launchTimeout = resolveLaunchTimeout();
+    if (launchTimeout) {
+      instanceConfig.launchTimeout = launchTimeout;
+    }
+  }
+  _memoryServerCleanupOptions = { doCleanup: true, force: !hasUserDbPath };
   const defaultConfig = {
     replSet: { count: 1, storageEngine: "wiredTiger" },
-    binary: { version: "6.0.12" },
-    instanceOpts: [{ ...memoryServerOptions?.instance ?? {} }]
+    binary: { version: binaryVersion },
+    instanceOpts: [instanceConfig]
   };
   const resolvedConfig = {
     ...defaultConfig,
@@ -2529,11 +2933,43 @@ async function startMemoryServer(logger, memoryServerOptions = {}) {
   try {
     _memoryServerInstance = await MongoMemoryReplSet.create(resolvedConfig);
     const uri = _memoryServerInstance.getUri();
-    logger?.info?.("\u2705 MongoDB Memory ReplSet started", { uri });
+    logger?.info?.("MongoDB Memory ReplSet started", { uri });
     return uri;
   } catch (err) {
-    logger?.error?.("\u274C Failed to start MongoDB Memory ReplSet", err);
-    throw new Error(`Failed to start MongoDB Memory ReplSet: ${err.message}`);
+    if (!hasUserDbPath) {
+      await cleanupManagedDbPath(_memoryServerDbPath);
+      _memoryServerDbPath = null;
+    }
+    logger?.error?.("Failed to start MongoDB Memory ReplSet", err);
+    throw createConnectionError(
+      `Failed to start MongoDB Memory ReplSet: ${err.message}`,
+      err instanceof Error ? err : void 0
+    );
+  }
+}
+async function stopMemoryServer(logger) {
+  if (!_memoryServerInstance) {
+    return;
+  }
+  const instance = _memoryServerInstance;
+  const dbPath = _memoryServerDbPath;
+  _memoryServerInstance = null;
+  _memoryServerDbPath = null;
+  let stopError = null;
+  try {
+    await instance.stop(_memoryServerCleanupOptions);
+    logger?.info?.("MongoDB Memory ReplSet stopped");
+  } catch (cause) {
+    stopError = cause;
+    logger?.warn?.("Failed to stop MongoDB Memory ReplSet cleanly.", cause);
+  } finally {
+    if (_memoryServerCleanupOptions.force) {
+      const cleaned = await cleanupManagedDbPath(dbPath);
+      if (!cleaned && (!stopError || isManagedCleanupError(stopError, dbPath ?? ""))) {
+        logger?.warn?.("Failed to remove MongoDB Memory ReplSet dbPath.", { dbPath });
+      }
+    }
+    _memoryServerCleanupOptions = { doCleanup: true, force: true };
   }
 }
 async function connectMongo(params) {
@@ -2542,13 +2978,15 @@ async function connectMongo(params) {
     throw createError(ErrorCodes.INVALID_DATABASE_NAME, "Database name must be a non-empty string.");
   }
   let effectiveUri = params.config?.uri?.trim();
+  let usesManagedMemoryServer = false;
   if (!effectiveUri && params.config?.useMemoryServer === true) {
     if (process.env["MONSQLIZE_USE_SYSTEM_MONGO"] === "true") {
       const systemUri = process.env["MONSQLIZE_SYSTEM_MONGO_URI"] ?? "mongodb://127.0.0.1:27017";
-      params.logger?.info?.("\u{1F527} Using system MongoDB instead of memory server", { uri: systemUri });
+      params.logger?.info?.("Using system MongoDB instead of memory server", { uri: systemUri });
       effectiveUri = systemUri;
     } else {
       effectiveUri = await startMemoryServer(params.logger, params.config.memoryServerOptions);
+      usesManagedMemoryServer = true;
     }
   }
   if (!effectiveUri) {
@@ -2562,6 +3000,9 @@ async function connectMongo(params) {
   try {
     await client.connect();
     const db = client.db(databaseName);
+    if (usesManagedMemoryServer) {
+      _memoryServerClients.add(client);
+    }
     params.logger?.info?.("MongoDB connected", { databaseName });
     return { client, db };
   } catch (cause) {
@@ -2569,6 +3010,9 @@ async function connectMongo(params) {
       await client.close();
     } catch {
     }
+    if (usesManagedMemoryServer && _memoryServerClients.size === 0) {
+      await stopMemoryServer(params.logger);
+    }
     throw createConnectionError(
       `Failed to connect to MongoDB database: ${databaseName}`,
       cause instanceof Error ? cause : void 0
@@ -2579,17 +3023,26 @@ async function closeMongo(client, logger) {
   if (!client) {
     return;
   }
+  const shouldReleaseMemoryServer = _memoryServerClients.delete(client);
+  let closeError = null;
   try {
     await client.close();
     logger?.info?.("MongoDB connection closed");
   } catch (cause) {
-    const error = createError(
+    closeError = createError(
       ErrorCodes.CONNECTION_CLOSED,
       "Failed to close MongoDB connection cleanly.",
       void 0,
       cause instanceof Error ? cause : void 0
     );
-    logger?.warn?.(error.message, error.cause);
+    logger?.warn?.(closeError.message, closeError.cause);
+  } finally {
+    if (shouldReleaseMemoryServer && _memoryServerClients.size === 0) {
+      await stopMemoryServer(logger);
+    }
+  }
+  if (closeError) {
+    return;
   }
 }
 
@@ -2601,8 +3054,9 @@ function loadSsh2Client() {
   try {
     return __require("ssh2").Client;
   } catch {
-    throw new Error(
-      'ssh2 is not installed. SSH tunnel support requires the optional "ssh2" package.\nRun: npm install ssh2'
+    throw createError(
+      ErrorCodes.INVALID_CONFIG,
+      "Unable to load ssh2. monsqlize installs ssh2 by default; check that the package installation is complete and that your runtime can resolve bundled dependencies."
     );
   }
 }
@@ -2630,10 +3084,10 @@ var SSHTunnelSSH2 = class {
       keepaliveInterval = 3e4
     } = this._sshConfig;
     if (!host || !username) {
-      throw new Error("SSH config requires: host, username");
+      throw createError(ErrorCodes.INVALID_CONFIG, "SSH config requires: host, username");
     }
     if (!password && !privateKey && !privateKeyPath) {
-      throw new Error("SSH authentication required: provide password, privateKey, or privateKeyPath");
+      throw createError(ErrorCodes.INVALID_CONFIG, "SSH authentication required: provide password, privateKey, or privateKeyPath");
     }
     const config = { host, port, username, readyTimeout, keepaliveInterval };
     if (password) {
@@ -2708,7 +3162,7 @@ var SSHTunnelSSH2 = class {
   }
   getTunnelUri(_protocol, originalUri) {
     if (!this.isConnected || this.localPort === null) {
-      throw new Error(`SSH tunnel [${this.remoteHost}:${this.remotePort}] not connected`);
+      throw createError(ErrorCodes.NOT_CONNECTED, `SSH tunnel [${this.remoteHost}:${this.remotePort}] not connected`);
     }
     return originalUri.replace(
       `${this.remoteHost}:${this.remotePort}`,
@@ -2717,7 +3171,7 @@ var SSHTunnelSSH2 = class {
   }
   getLocalAddress() {
     if (!this.isConnected || this.localPort === null) {
-      throw new Error(`SSH tunnel [${this.remoteHost}:${this.remotePort}] not connected`);
+      throw createError(ErrorCodes.NOT_CONNECTED, `SSH tunnel [${this.remoteHost}:${this.remotePort}] not connected`);
     }
     return `localhost:${this.localPort}`;
   }
@@ -3166,7 +3620,7 @@ var HealthChecker = class {
   async _pingPool(poolName, timeout) {
     const stored = this._clients.get(poolName);
     const client = stored ?? this._poolManager?._getPool(poolName);
-    if (!client) throw new Error(`No client for pool: ${poolName}`);
+    if (!client) throw createError(ErrorCodes.POOL_NOT_FOUND, `No client for pool: ${poolName}`);
     const db = client.db("admin");
     const pingFn = db.command ? () => db.command({ ping: 1 }) : () => db.admin().ping();
     const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error("Ping timeout")), timeout));
@@ -3198,7 +3652,7 @@ var PoolSelector = class {
   }
   select(pools, context) {
     if (!pools || pools.length === 0) {
-      throw new Error("No available pools");
+      throw createError(ErrorCodes.INVALID_OPERATION, "No available pools");
     }
     switch (this._strategy) {
       case "auto":
@@ -3219,7 +3673,10 @@ var PoolSelector = class {
   selectByAuto(pools, context) {
     const { operation, poolPreference } = context;
     let candidates = pools;
-    if (operation === "read") {
+    const preferred = this.filterByPreference(pools, poolPreference);
+    if (preferred.length > 0) {
+      candidates = preferred;
+    } else if (operation === "read") {
       const secondaries = pools.filter((pool) => pool.role === "secondary");
       if (secondaries.length > 0) {
         candidates = secondaries;
@@ -3230,10 +3687,19 @@ var PoolSelector = class {
         candidates = primaries;
       }
     }
+    if (candidates.length === 1) {
+      return candidates[0].name;
+    }
+    return this.selectByWeighted(candidates);
+  }
+  filterByPreference(pools, poolPreference) {
+    let candidates = pools;
+    let applied = false;
     if (poolPreference?.role) {
       const filteredByRole = candidates.filter((pool) => pool.role === poolPreference.role);
       if (filteredByRole.length > 0) {
         candidates = filteredByRole;
+        applied = true;
       }
     }
     if (poolPreference?.tags?.length) {
@@ -3246,12 +3712,10 @@ var PoolSelector = class {
       });
       if (filteredByTags.length > 0) {
         candidates = filteredByTags;
+        applied = true;
       }
     }
-    if (candidates.length === 1) {
-      return candidates[0].name;
-    }
-    return this.selectByWeighted(candidates);
+    return applied ? candidates : [];
   }
   selectByRoundRobin(pools, context) {
     let candidates = pools;
@@ -3411,43 +3875,43 @@ var DEFAULT_POOL_CONNECT_OPTIONS = {
   serverSelectionTimeoutMS: 5e3
 };
 function validatePoolConfig(config) {
-  if (!config || typeof config !== "object") throw new Error("Pool config must be an object");
-  if (!config.name || typeof config.name !== "string") throw new Error("Pool config.name is required and must be a string");
-  if (!config.uri || typeof config.uri !== "string") throw new Error("Pool config.uri is required and must be a string");
+  if (!config || typeof config !== "object") throw createError(ErrorCodes.INVALID_CONFIG, "Pool config must be an object");
+  if (!config.name || typeof config.name !== "string") throw createError(ErrorCodes.INVALID_CONFIG, "Pool config.name is required and must be a string");
+  if (!config.uri || typeof config.uri !== "string") throw createError(ErrorCodes.INVALID_CONFIG, "Pool config.uri is required and must be a string");
   if (!config.uri.startsWith("mongodb://") && !config.uri.startsWith("mongodb+srv://")) {
-    throw new Error("Pool config.uri must start with mongodb:// or mongodb+srv://");
+    throw createError(ErrorCodes.INVALID_CONFIG, "Pool config.uri must start with mongodb:// or mongodb+srv://");
   }
   if (config.role) {
     const validRoles = ["primary", "secondary", "analytics", "custom"];
-    if (!validRoles.includes(config.role)) throw new Error(`Pool config.role must be one of: ${validRoles.join(", ")}`);
+    if (!validRoles.includes(config.role)) throw createError(ErrorCodes.INVALID_CONFIG, `Pool config.role must be one of: ${validRoles.join(", ")}`);
   }
   if (config.weight !== void 0) {
-    if (typeof config.weight !== "number") throw new Error("Pool config.weight must be a number");
-    if (config.weight < 0) throw new Error("Pool config.weight must be a non-negative number");
+    if (typeof config.weight !== "number") throw createError(ErrorCodes.INVALID_CONFIG, "Pool config.weight must be a number");
+    if (config.weight < 0) throw createError(ErrorCodes.INVALID_CONFIG, "Pool config.weight must be a non-negative number");
   }
   if (config.options !== void 0) {
-    if (typeof config.options !== "object" || Array.isArray(config.options)) throw new Error("Pool config.options must be an object");
+    if (typeof config.options !== "object" || Array.isArray(config.options)) throw createError(ErrorCodes.INVALID_CONFIG, "Pool config.options must be an object");
     const opts = config.options;
     for (const key of ["maxPoolSize", "minPoolSize", "maxIdleTimeMS", "waitQueueTimeoutMS", "connectTimeoutMS", "serverSelectionTimeoutMS"]) {
       if (opts[key] !== void 0 && (typeof opts[key] !== "number" || opts[key] < 0)) {
-        throw new Error(`Pool config.options.${key} must be a non-negative number`);
+        throw createError(ErrorCodes.INVALID_CONFIG, `Pool config.options.${key} must be a non-negative number`);
       }
     }
   }
   if (config.healthCheck !== void 0) {
-    if (typeof config.healthCheck !== "object" || Array.isArray(config.healthCheck)) throw new Error("Pool config.healthCheck must be an object");
+    if (typeof config.healthCheck !== "object" || Array.isArray(config.healthCheck)) throw createError(ErrorCodes.INVALID_CONFIG, "Pool config.healthCheck must be an object");
     const hc = config.healthCheck;
-    if (hc.enabled !== void 0 && typeof hc.enabled !== "boolean") throw new Error("Pool config.healthCheck.enabled must be a boolean");
+    if (hc.enabled !== void 0 && typeof hc.enabled !== "boolean") throw createError(ErrorCodes.INVALID_CONFIG, "Pool config.healthCheck.enabled must be a boolean");
     for (const key of ["interval", "timeout", "retries"]) {
       if (hc[key] !== void 0 && (typeof hc[key] !== "number" || hc[key] < 0)) {
-        throw new Error(`Pool config.healthCheck.${key} must be a non-negative number`);
+        throw createError(ErrorCodes.INVALID_CONFIG, `Pool config.healthCheck.${key} must be a non-negative number`);
       }
     }
   }
   if (config.tags !== void 0) {
-    if (!Array.isArray(config.tags)) throw new Error("Pool config.tags must be an array");
+    if (!Array.isArray(config.tags)) throw createError(ErrorCodes.INVALID_CONFIG, "Pool config.tags must be an array");
     for (const tag of config.tags) {
-      if (typeof tag !== "string") throw new Error("Pool config.tags must be an array of strings");
+      if (typeof tag !== "string") throw createError(ErrorCodes.INVALID_CONFIG, "Pool config.tags must be an array of strings");
     }
   }
 }
@@ -3506,10 +3970,10 @@ function validatePoolConfigSafe(config) {
 }
 function validatePoolConfigInternal(config) {
   if (!config.name?.trim()) {
-    throw new Error("Pool config requires a non-empty name");
+    throw createError(ErrorCodes.INVALID_CONFIG, "Pool config requires a non-empty name");
   }
   if (!config.uri?.trim()) {
-    throw new Error("Pool config requires a non-empty uri");
+    throw createError(ErrorCodes.INVALID_CONFIG, "Pool config requires a non-empty uri");
   }
 }
 function createEmptyPoolStats(name) {
@@ -3586,10 +4050,10 @@ var ConnectionPoolManager = class {
   async addPool(config) {
     validatePoolConfigInternal(config);
     if (this.pools.has(config.name) || this._pendingAdds.has(config.name)) {
-      throw new Error(`Pool '${config.name}' already exists`);
+      throw createError(ErrorCodes.INVALID_CONFIG, `Pool '${config.name}' already exists`);
     }
     if (this.maxPoolsCount > 0 && this.pools.size >= this.maxPoolsCount) {
-      throw new Error(`Maximum pool count (${this.maxPoolsCount}) reached`);
+      throw createError(ErrorCodes.INVALID_CONFIG, `Maximum pool count (${this.maxPoolsCount}) reached`);
     }
     this._pendingAdds.add(config.name);
     try {
@@ -3597,7 +4061,7 @@ var ConnectionPoolManager = class {
       if (this.pools.has(config.name)) {
         await client.close().catch(() => {
         });
-        throw new Error(`Pool '${config.name}' already exists`);
+        throw createError(ErrorCodes.INVALID_CONFIG, `Pool '${config.name}' already exists`);
       }
       this.pools.set(config.name, {
         client,
@@ -3636,7 +4100,7 @@ var ConnectionPoolManager = class {
   async removePool(name) {
     const pool = this.pools.get(name);
     if (!pool) {
-      throw new Error(`Pool '${name}' not found`);
+      throw createError(ErrorCodes.POOL_NOT_FOUND, `Pool '${name}' not found`);
     }
     this.stopHealthCheck(name);
     await pool.client.close();
@@ -3660,27 +4124,28 @@ var ConnectionPoolManager = class {
   selectPool(operation, options = {}) {
     if (options.pool) {
       const poolData2 = this.pools.get(options.pool);
-      if (!poolData2) throw new Error(`Pool '${options.pool}' not found`);
+      if (!poolData2) throw createError(ErrorCodes.POOL_NOT_FOUND, `Pool '${options.pool}' not found`);
       return this._createPoolResult(options.pool, poolData2.client);
     }
     let candidates = this._getHealthyPools();
     if (candidates.length === 0) {
       if (!this.fallback.enabled) {
-        throw new Error("No available connection pool");
+        throw createError(ErrorCodes.INVALID_OPERATION, "No available connection pool");
       }
       candidates = this._handleAllPoolsDown(operation);
       if (candidates.length === 0) {
-        throw new Error("No available connection pool");
+        throw createError(ErrorCodes.INVALID_OPERATION, "No available connection pool");
       }
     }
+    const poolPreference = options.poolPreference ?? (options.tags?.length ? { tags: options.tags } : void 0);
     const poolName = this._selector.select(candidates, {
       operation,
       stats: this._stats.getAllStats(),
-      poolPreference: options.poolPreference
+      poolPreference
     });
     const poolData = this.pools.get(poolName);
     if (!poolData) {
-      throw new Error(`Selected pool '${poolName}' not available`);
+      throw createError(ErrorCodes.INVALID_OPERATION, `Selected pool '${poolName}' not available`);
     }
     this._stats.recordSelection(poolName, operation);
     this.recordSelection(poolName, true);
@@ -3803,10 +4268,12 @@ var ConnectionPoolManager = class {
   _getHealthyPools() {
     const result = [];
     for (const [name, config] of this._configs.entries()) {
-      const status = this._healthChecker.getStatus(name);
-      if (!status || status.status !== "down") {
-        result.push(config);
+      const compatStatus = this._healthChecker.getStatus(name);
+      const publicStatus = this.healthStatus.get(name);
+      if (compatStatus?.status === "down" || publicStatus?.status === "down") {
+        continue;
       }
+      result.push(config);
     }
     return result;
   }
@@ -3959,7 +4426,7 @@ async function initializeDistributedCacheInvalidator(options, cache, logger) {
       logger
     });
   } catch (err) {
-    logger.warn?.("[Cache] Failed to initialize distributed cache invalidator \u2014 is ioredis installed?", err);
+    logger.warn?.("[Cache] Failed to initialize distributed cache invalidator \u2014 check Redis config or package installation completeness.", err);
     return null;
   }
 }
@@ -3967,7 +4434,7 @@ async function loadModelFiles(options, logger, opts = {}) {
   const modelsConfig = options.models;
   if (!modelsConfig) return;
   if (typeof modelsConfig !== "string" && typeof modelsConfig !== "object") return;
-  const { readdirSync } = await import("node:fs");
+  const { readdirSync: readdirSync2 } = await import("node:fs");
   const { resolve, join, isAbsolute } = await import("node:path");
   const { createRequire } = await import("node:module");
   let targetPath;
@@ -3991,7 +4458,7 @@ async function loadModelFiles(options, logger, opts = {}) {
   const collectFiles = (dir) => {
     let entries;
     try {
-      entries = readdirSync(dir, { withFileTypes: true });
+      entries = readdirSync2(dir, { withFileTypes: true });
     } catch {
       logger.warn?.(`[Models] cannot read directory: ${dir}`);
       return [];
@@ -4470,7 +4937,7 @@ async function indexStatsForAccessor(collectionRef) {
 }
 async function setValidatorForAccessor(collectionRef, collectionName, dbRef, validator, options = {}) {
   if (validator === null || typeof validator !== "object") {
-    throw new Error("Validator must be a non-null object");
+    throw createError(ErrorCodes.INVALID_ARGUMENT, "Validator must be a non-null object");
   }
   const isEmptyValidator = Object.keys(validator).length === 0;
   const command = {
@@ -4491,14 +4958,14 @@ async function setValidatorForAccessor(collectionRef, collectionName, dbRef, val
 }
 async function setValidationLevelForAccessor(collectionRef, collectionName, dbRef, level) {
   if (typeof level !== "string" || !["off", "strict", "moderate"].includes(level)) {
-    throw new Error('Invalid validation level: must be "off", "strict", or "moderate"');
+    throw createError(ErrorCodes.INVALID_ARGUMENT, 'Invalid validation level: must be "off", "strict", or "moderate"');
   }
   const result = await resolveDb(collectionRef, dbRef).command({ collMod: collectionName, validationLevel: level });
   return { ok: result["ok"], validationLevel: level };
 }
 async function setValidationActionForAccessor(collectionRef, collectionName, dbRef, action) {
   if (typeof action !== "string" || !["error", "warn"].includes(action)) {
-    throw new Error('Invalid validation action: must be "error" or "warn"');
+    throw createError(ErrorCodes.INVALID_ARGUMENT, 'Invalid validation action: must be "error" or "warn"');
   }
   const result = await resolveDb(collectionRef, dbRef).command({ collMod: collectionName, validationAction: action });
   return { ok: result["ok"], validationAction: action };
@@ -4530,14 +4997,14 @@ async function statsForAccessor(collectionRef, dbName, collectionName, options =
 }
 async function renameCollectionForAccessor(collectionRef, collectionName, newName, options = {}) {
   if (!newName || typeof newName !== "string") {
-    throw new Error("New collection name is required and must be a non-empty string");
+    throw createError(ErrorCodes.INVALID_ARGUMENT, "New collection name is required and must be a non-empty string");
   }
   await collectionRef.rename(newName, { dropTarget: options.dropTarget ?? false });
   return { renamed: true, from: collectionName, to: newName };
 }
 async function collModForAccessor(collectionRef, collectionName, dbRef, modifications) {
   if (modifications === null || typeof modifications !== "object") {
-    throw new Error("Modifications must be a non-null object");
+    throw createError(ErrorCodes.INVALID_ARGUMENT, "Modifications must be a non-null object");
   }
   return resolveDb(collectionRef, dbRef).command({
     collMod: collectionName,
@@ -4546,10 +5013,10 @@ async function collModForAccessor(collectionRef, collectionName, dbRef, modifica
 }
 async function convertToCappedForAccessor(collectionRef, collectionName, dbRef, size, options = {}) {
   if (typeof size !== "number") {
-    throw new Error("Size must be a number");
+    throw createError(ErrorCodes.INVALID_ARGUMENT, "Size must be a number");
   }
   if (size <= 0) {
-    throw new Error("Size must be a positive number");
+    throw createError(ErrorCodes.INVALID_ARGUMENT, "Size must be a positive number");
   }
   const command = { convertToCapped: collectionName, size };
   if (options.max !== void 0) {
@@ -4730,7 +5197,7 @@ function dispatchFunction(name, argsStr) {
     }
     case "REDUCE": {
       const lambdaMatch = /\((\w+),\s*(\w+)\)\s*=>\s*(.+)/.exec(args[2]);
-      if (!lambdaMatch) throw new Error("REDUCE requires a lambda: (acc, item) => expr");
+      if (!lambdaMatch) throw createError(ErrorCodes.INVALID_EXPRESSION, "REDUCE requires a lambda: (acc, item) => expr");
       const [, accVar, itemVar, lambdaExpr] = lambdaMatch;
       const compiledExpr = lambdaExpr.replace(new RegExp(`\\b${accVar}\\b`, "g"), "$$value").replace(new RegExp(`\\b${itemVar}\\b`, "g"), "$$this");
       return { $reduce: { input: parseValue(args[0]), initialValue: parseValue(args[1]), in: compileInnerExpression(compiledExpr) } };
@@ -4875,7 +5342,7 @@ function dispatchFunction(name, argsStr) {
       return { $setUnion: unionArgs };
     }
     case "SWITCH": {
-      if (args.length < 2) throw new Error("SWITCH requires at least 2 arguments");
+      if (args.length < 2) throw createError(ErrorCodes.INVALID_EXPRESSION, "SWITCH requires at least 2 arguments");
       const branches = [];
       let defaultValue = null;
       for (let index = 0; index < args.length - 1; index += 2) {
@@ -4893,15 +5360,15 @@ function dispatchFunction(name, argsStr) {
     case "ANY_ELEMENT_TRUE":
       return { $anyElementTrue: [parseValue(args[0])] };
     case "COND": {
-      if (args.length !== 3) throw new Error("COND requires 3 arguments");
+      if (args.length !== 3) throw createError(ErrorCodes.INVALID_EXPRESSION, "COND requires 3 arguments");
       return { $cond: { if: compileInnerExpression(args[0]), then: parseValue(args[1]), else: parseValue(args[2]) } };
     }
     case "IF_NULL": {
-      if (args.length !== 2) throw new Error("IF_NULL requires 2 arguments");
+      if (args.length !== 2) throw createError(ErrorCodes.INVALID_EXPRESSION, "IF_NULL requires 2 arguments");
       return { $ifNull: [parseValue(args[0]), parseValue(args[1])] };
     }
     case "SET_FIELD": {
-      if (args.length !== 3) throw new Error("SET_FIELD requires 3 arguments: (field, value, input)");
+      if (args.length !== 3) throw createError(ErrorCodes.INVALID_EXPRESSION, "SET_FIELD requires 3 arguments: (field, value, input)");
       return { $setField: { field: parseValue(args[0]), input: parseValue(args[2]), value: parseValue(args[1]) } };
     }
     case "UNSET_FIELD":
@@ -4918,7 +5385,7 @@ function dispatchFunction(name, argsStr) {
       return { $setIsSubset: [parseValue(args[0]), parseValue(args[1])] };
     case "LET": {
       const varsMatch = /\{(.+)\}/.exec(args[0]);
-      if (!varsMatch) throw new Error("LET requires an object literal for variables");
+      if (!varsMatch) throw createError(ErrorCodes.INVALID_EXPRESSION, "LET requires an object literal for variables");
       const varPairs = varsMatch[1].split(",").map((pair) => {
         const [key, ...rest] = pair.split(":");
         return [key.trim(), rest.join(":").trim()];
@@ -4936,7 +5403,7 @@ function dispatchFunction(name, argsStr) {
     case "SAMPLE_RATE":
       return { $sampleRate: parseValue(args[0]) };
     default:
-      throw new Error(`Unsupported function: ${name}`);
+      throw createError(ErrorCodes.INVALID_EXPRESSION, `Unsupported function: ${name}`);
   }
 }
 function compileFilterCondition(condition, varName) {
@@ -5263,7 +5730,7 @@ function decodeCursor(cursor, secret) {
     }
     const payload = JSON.parse(Buffer.from(raw, "base64url").toString("utf8"));
     if (payload?.v !== 1 || !Array.isArray(payload.values)) {
-      throw new Error("Invalid cursor payload.");
+      throw createError(ErrorCodes.INVALID_ARGUMENT, "Invalid cursor payload.");
     }
     return payload.values;
   } catch (cause) {
@@ -5362,6 +5829,7 @@ function buildEffectiveProjection(projection, sort) {
 }
 
 // src/adapters/mongodb/queries/find-page.ts
+import { createHash as createHash2 } from "node:crypto";
 function normalizePositiveInteger(value, fallback, field) {
   if (value === void 0 || value === null) {
     return fallback;
@@ -5380,54 +5848,192 @@ function mergeFilters(base, extra) {
   }
   return { $and: [base, extra] };
 }
+function stableStringify2(value) {
+  if (value === void 0) {
+    return '"__undefined__"';
+  }
+  if (value === null) {
+    return "null";
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify2(item)).join(",")}]`;
+  }
+  if (value instanceof Date) {
+    return JSON.stringify(value.toISOString());
+  }
+  if (typeof value === "object") {
+    const customJson = value.toJSON;
+    if (typeof customJson === "function" && value.constructor?.name !== "Object") {
+      return stableStringify2(customJson.call(value));
+    }
+    const entries = Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => `${JSON.stringify(key)}:${stableStringify2(item)}`);
+    return `{${entries.join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+function hashPayload(payload) {
+  return createHash2("sha256").update(stableStringify2(payload)).digest("hex");
+}
+function buildFindPageCacheKey(collection, options, normalized) {
+  const payload = {
+    query: normalized.query,
+    sort: normalized.sort,
+    limit: normalized.limit,
+    page: normalized.page,
+    after: options.after,
+    before: options.before,
+    projection: options.projection,
+    pipeline: options.pipeline ?? [],
+    totals: options.totals,
+    jump: options.jump,
+    offsetJump: options.offsetJump,
+    maxTimeMS: normalized.maxTimeMS,
+    hint: options.hint,
+    collation: options.collation,
+    batchSize: options.batchSize,
+    options: options.options
+  };
+  const keyHash = hashPayload(payload);
+  return { key: `findPage:${collection.namespace}:${keyHash}`, keyHash };
+}
+function buildTotalsCacheKey(collection, query, limit, totals) {
+  const payload = {
+    query,
+    limit,
+    mode: totals.mode ?? "sync",
+    hint: totals.hint,
+    collation: totals.collation,
+    maxTimeMS: totals.maxTimeMS
+  };
+  const token = hashPayload(payload);
+  return { key: `findPageTotals:${collection.namespace}:${token}`, token };
+}
+function cloneFindPageResult(result) {
+  return {
+    ...result,
+    items: Array.isArray(result.items) ? [...result.items] : result.items,
+    pageInfo: result.pageInfo && typeof result.pageInfo === "object" ? { ...result.pageInfo } : result.pageInfo,
+    totals: result.totals && typeof result.totals === "object" ? { ...result.totals } : result.totals,
+    meta: result.meta && typeof result.meta === "object" ? {
+      ...result.meta,
+      ns: { ...result.meta.ns },
+      steps: result.meta.steps ? [...result.meta.steps] : void 0
+    } : result.meta
+  };
+}
+function getPositiveTtl(value, fallback) {
+  return typeof value === "number" && value > 0 ? value : fallback;
+}
 var _asyncTotalsCache = new MemoryCache({
   maxEntries: 1e4,
   enableStats: false
 });
-async function computeTotals(coll, query, limit, totals) {
+var _totalsInflight = /* @__PURE__ */ new Map();
+function runTotalsOnce(key, task) {
+  if (_totalsInflight.has(key)) {
+    return;
+  }
+  const promise = task().catch(() => {
+  }).finally(() => {
+    _totalsInflight.delete(key);
+  });
+  _totalsInflight.set(key, promise);
+}
+async function computeTotals(coll, query, limit, totals, defaults = {}, queryCache) {
   const mode = totals.mode ?? "sync";
-  if (mode === "sync") {
+  const cache = queryCache ?? _asyncTotalsCache;
+  const ttlMs = getPositiveTtl(totals.ttlMs, 10 * 6e4);
+  const { key: cacheKey, token } = buildTotalsCacheKey(coll, query, limit, totals);
+  const buildCountOptions = (fallbackMaxTimeMS) => {
     const countOpts = {};
-    if (totals.maxTimeMS !== void 0) {
-      countOpts.maxTimeMS = totals.maxTimeMS;
+    const maxTimeMS = totals.maxTimeMS ?? fallbackMaxTimeMS;
+    if (maxTimeMS !== void 0) {
+      countOpts.maxTimeMS = maxTimeMS;
+    }
+    if (totals.hint !== void 0) {
+      countOpts.hint = totals.hint;
+    }
+    if (totals.collation !== void 0) {
+      countOpts.collation = totals.collation;
     }
-    const total = await coll.countDocuments(
-      query,
+    return countOpts;
+  };
+  const countWithOptions = async () => {
+    const countOpts = buildCountOptions(2e3);
+    const countQuery = query;
+    const runner = () => coll.countDocuments(
+      countQuery,
       countOpts
     );
-    const totalPages = total > 0 ? Math.ceil(total / limit) : 0;
-    return { mode: "sync", total, totalPages, ts: Date.now() };
+    return defaults.countQueue ? defaults.countQueue.execute(runner) : runner();
+  };
+  const buildPayload = (total, approx = false) => ({
+    mode,
+    total,
+    totalPages: total > 0 ? Math.ceil(total / limit) : 0,
+    ts: Date.now(),
+    ...approx ? { approx: true } : {}
+  });
+  const buildFailurePayload = (error) => ({
+    mode,
+    total: null,
+    totalPages: null,
+    ts: Date.now(),
+    error
+  });
+  if (mode === "sync") {
+    const cached = cache.get(cacheKey);
+    if (cached !== void 0) {
+      return { ...cached, mode: "sync" };
+    }
+    try {
+      const payload = buildPayload(await countWithOptions());
+      await Promise.resolve(cache.set(cacheKey, payload, ttlMs));
+      return { ...payload, mode: "sync" };
+    } catch {
+      const payload = buildFailurePayload("count_failed");
+      await Promise.resolve(cache.set(cacheKey, payload, ttlMs));
+      return { ...payload, mode: "sync" };
+    }
   }
   if (mode === "async") {
-    const cacheKey = JSON.stringify({ ns: coll.namespace, q: query });
-    const token = Buffer.from(cacheKey).toString("base64url");
-    const cachedTotal = _asyncTotalsCache.get(cacheKey);
-    if (cachedTotal !== void 0) {
-      return { mode: "async", total: cachedTotal, token };
+    const cached = cache.get(cacheKey);
+    if (cached !== void 0) {
+      return { ...cached, mode: "async", token };
     }
-    setImmediate(async () => {
-      try {
-        const n = await coll.countDocuments(
-          query
-        );
-        _asyncTotalsCache.set(cacheKey, n);
-      } catch {
-      }
+    setImmediate(() => {
+      runTotalsOnce(cacheKey, async () => {
+        try {
+          const payload = buildPayload(await countWithOptions());
+          await Promise.resolve(cache.set(cacheKey, payload, ttlMs));
+        } catch {
+          await Promise.resolve(cache.set(cacheKey, buildFailurePayload("count_failed"), ttlMs));
+        }
+      });
     });
     return { mode: "async", total: null, token };
   }
   if (mode === "approx") {
-    const countOpts = {};
-    if (totals.maxTimeMS !== void 0) {
-      countOpts.maxTimeMS = totals.maxTimeMS;
+    const cached = cache.get(cacheKey);
+    if (cached !== void 0) {
+      return { ...cached, mode: "approx" };
+    }
+    try {
+      const total = Object.keys(query ?? {}).length > 0 ? await countWithOptions() : await coll.estimatedDocumentCount({
+        maxTimeMS: totals.maxTimeMS ?? 1e3
+      });
+      const payload = buildPayload(total, true);
+      await Promise.resolve(cache.set(cacheKey, payload, ttlMs));
+      return { ...payload, mode: "approx" };
+    } catch {
+      const payload = buildFailurePayload("approx_failed");
+      await Promise.resolve(cache.set(cacheKey, payload, ttlMs));
+      return { ...payload, mode: "approx" };
     }
-    const total = await coll.estimatedDocumentCount(countOpts);
-    const totalPages = total > 0 ? Math.ceil(total / limit) : 0;
-    return { mode: "approx", total, totalPages, ts: Date.now() };
   }
   return { mode: mode ?? "sync" };
 }
-async function executeFindPage(collection, options = {}, defaults = {}) {
+async function executeFindPage(collection, options = {}, defaults = {}, queryCache) {
   const metaEnabled = options.meta === true || typeof options.meta === "object" && options.meta !== null;
   const metaOptions = options.meta && typeof options.meta === "object" ? options.meta : {};
   const metaLevel = options.meta === true ? "op" : metaOptions.level ?? "op";
@@ -5458,6 +6064,10 @@ async function executeFindPage(collection, options = {}, defaults = {}) {
     driverOpts.projection = buildEffectiveProjection(options.projection, sort);
   }
   const jumpOpts = ext.jump;
+  const cacheTTL = typeof ext.cache === "number" && ext.cache > 0 ? ext.cache : 0;
+  const pageResultCache = cacheTTL > 0 && queryCache && options.stream !== true && (options.explain === void 0 || options.explain === false) ? buildFindPageCacheKey(collection, options, { query: baseQuery, sort, limit, page, maxTimeMS: effectiveMaxTimeMS }) : null;
+  const shouldRefreshAsyncTotals = options.totals?.mode === "async";
+  let findPageCacheHit = false;
   const finishResult = (result2) => {
     if (!metaEnabled) {
       return result2;
@@ -5488,6 +6098,9 @@ async function executeFindPage(collection, options = {}, defaults = {}) {
       endTs: metaEndTs,
       durationMs: metaEndTs - metaStartTs,
       ...typeof effectiveMaxTimeMS === "number" ? { maxTimeMS: effectiveMaxTimeMS } : {},
+      cacheHit: findPageCacheHit,
+      ...findPageCacheHit ? { fromCache: true } : {},
+      ...pageResultCache ? { cacheTtl: cacheTTL, keyHash: pageResultCache.keyHash } : {},
       page,
       after: Boolean(options.after),
       before: Boolean(options.before),
@@ -5556,7 +6169,7 @@ async function executeFindPage(collection, options = {}, defaults = {}) {
   };
   const timedComputeTotals = async () => {
     const stepStartTs = Date.now();
-    const result2 = await computeTotals(collection, baseQuery, limit, options.totals);
+    const result2 = await computeTotals(collection, baseQuery, limit, options.totals, defaults, queryCache);
     pushMetaStep("computeTotals", Date.now() - stepStartTs, "totals");
     return result2;
   };
@@ -5575,6 +6188,32 @@ async function executeFindPage(collection, options = {}, defaults = {}) {
       ...extra.currentPage !== void 0 ? { currentPage: extra.currentPage } : {}
     };
   };
+  const writePageResultCache = (result2) => {
+    if (!pageResultCache || !queryCache) {
+      return;
+    }
+    const cacheValue = cloneFindPageResult(result2);
+    delete cacheValue.meta;
+    if (shouldRefreshAsyncTotals) {
+      delete cacheValue.totals;
+    }
+    void queryCache.set(pageResultCache.key, cacheValue, cacheTTL);
+  };
+  const finishAndCache = (result2) => {
+    writePageResultCache(result2);
+    return finishResult(result2);
+  };
+  if (pageResultCache && queryCache) {
+    const cached = queryCache.get(pageResultCache.key);
+    if (cached !== void 0) {
+      findPageCacheHit = true;
+      const result2 = cloneFindPageResult(cached);
+      if (options.totals && options.totals.mode !== "none" && (shouldRefreshAsyncTotals || result2.totals === void 0)) {
+        result2.totals = await timedComputeTotals();
+      }
+      return finishResult(result2);
+    }
+  }
   if (options.stream === true) {
     const direction = options.before ? "before" : "after";
     const { queryFilter, effectiveSort } = buildPageQuery(options.after ?? options.before, direction);
@@ -5617,7 +6256,7 @@ async function executeFindPage(collection, options = {}, defaults = {}) {
     if (options.totals && options.totals.mode !== "none") {
       result2.totals = await timedComputeTotals();
     }
-    return finishResult(result2);
+    return finishAndCache(result2);
   }
   if (options.after || options.before) {
     const direction = options.after ? "after" : "before";
@@ -5627,7 +6266,7 @@ async function executeFindPage(collection, options = {}, defaults = {}) {
     const first = items2[0] ?? null;
     const last = items2[items2.length - 1] ?? null;
     const enc = (item) => item ? encodeCursor(Object.keys(sort).map((f) => item[f]), cursorSecret) : null;
-    return finishResult({
+    const result2 = {
       items: items2,
       pageInfo: {
         hasNext: direction === "before" ? Boolean(options.before) : hasMore2,
@@ -5635,7 +6274,11 @@ async function executeFindPage(collection, options = {}, defaults = {}) {
         startCursor: enc(first),
         endCursor: enc(last)
       }
-    });
+    };
+    if (options.totals && options.totals.mode !== "none") {
+      result2.totals = await timedComputeTotals();
+    }
+    return finishAndCache(result2);
   }
   const { queryFilter: q0, effectiveSort: es0 } = buildPageQuery();
   let { items, hasMore } = await timedFetchItems("initialFetch", page > 1 ? "hop" : "fetch", q0, es0, {}, 1);
@@ -5647,15 +6290,19 @@ async function executeFindPage(collection, options = {}, defaults = {}) {
     if (options.totals && options.totals.mode !== "none") {
       result2.totals = await timedComputeTotals();
     }
-    return finishResult(result2);
+    return finishAndCache(result2);
   }
   for (let cp = 2; cp <= page; cp++) {
     const lastItem = items[items.length - 1];
     if (!lastItem) {
-      return finishResult({
+      const result2 = {
         items,
         pageInfo: buildPageInfo(items, false, { hasPrev: cp > 2, currentPage: cp - 1 })
-      });
+      };
+      if (options.totals && options.totals.mode !== "none") {
+        result2.totals = await timedComputeTotals();
+      }
+      return finishAndCache(result2);
     }
     const endCursor = encodeCursor(
       Object.keys(sort).map((f) => lastItem[f]),
@@ -5673,10 +6320,10 @@ async function executeFindPage(collection, options = {}, defaults = {}) {
   if (options.totals && options.totals.mode !== "none") {
     result.totals = await timedComputeTotals();
   }
-  return finishResult(result);
+  return finishAndCache(result);
 }
-async function findPageDocuments(collection, options = {}, defaults) {
-  return executeFindPage(collection, options, defaults ?? {});
+async function findPageDocuments(collection, options = {}, defaults, queryCache) {
+  return executeFindPage(collection, options, defaults ?? {}, queryCache);
 }
 
 // src/adapters/mongodb/queries/find-by-id.ts
@@ -5898,21 +6545,21 @@ var FindChain = class {
   }
   limit(value) {
     if (typeof value !== "number" || value < 0) {
-      throw new Error(`limit() requires a non-negative number, got: ${typeof value} (${value})`);
+      throw createError(ErrorCodes.INVALID_ARGUMENT, `limit() requires a non-negative number, got: ${typeof value} (${value})`);
     }
     this.options.limit = value;
     return this;
   }
   skip(value) {
     if (typeof value !== "number" || value < 0) {
-      throw new Error(`skip() requires a non-negative number, got: ${typeof value} (${value})`);
+      throw createError(ErrorCodes.INVALID_ARGUMENT, `skip() requires a non-negative number, got: ${typeof value} (${value})`);
     }
     this.options.skip = value;
     return this;
   }
   sort(value) {
     if (!value || typeof value !== "object") {
-      throw new Error(`sort() requires an object or array, got: ${typeof value}`);
+      throw createError(ErrorCodes.INVALID_ARGUMENT, `sort() requires an object or array, got: ${typeof value}`);
     }
     this.options.sort = value;
     return this;
@@ -5956,7 +6603,7 @@ var FindChain = class {
   }
   toArray() {
     if (this.executed) {
-      throw new Error("Query already executed.");
+      throw createError(ErrorCodes.INVALID_OPERATION, "Query already executed.");
     }
     this.executed = true;
     return this.collection.find(this.normalizedQuery, buildFindDriverOptions(this.buildExecuteOptions())).toArray();
@@ -6044,7 +6691,7 @@ var AggregateChain = class {
   }
   toArray() {
     if (this.executed) {
-      throw new Error("Query already executed.");
+      throw createError(ErrorCodes.INVALID_OPERATION, "Query already executed.");
     }
     this.executed = true;
     return this.collection.aggregate(this.pipeline, buildAggregateDriverOptions(this.buildExecuteOptions())).toArray();
@@ -6839,7 +7486,7 @@ async function insertOneForAccessor(context, doc, options) {
   const threshold = context.defaults?.slowQueryMs ?? 500;
   if (elapsed > threshold && context.logger) {
     try {
-      context.logger.warn("[insertOne] \u6162\u64CD\u4F5C\u8B66\u544A", {
+      context.logger.warn("[insertOne] slow operation warning", {
         ns: `${context.dbName}.${context.collectionName}`,
         threshold,
         duration: elapsed,
@@ -6884,7 +7531,7 @@ async function insertManyForAccessor(context, documents, options) {
   const elapsed = Date.now() - startedAt;
   const threshold = context.defaults?.slowQueryMs ?? 500;
   if (elapsed >= threshold && context.logger) {
-    context.logger.warn("[insertMany] \u6162\u64CD\u4F5C\u8B66\u544A", {
+    context.logger.warn("[insertMany] slow operation warning", {
       ns: `${context.dbName}.${context.collectionName}`,
       threshold,
       duration: elapsed,
@@ -7015,11 +7662,17 @@ var MongoCollectionAccessor = class {
     const legacyNamespacePatterns = [
       `${String(this.management.defaults?.namespace?.instanceId)}:mongodb:${this.dbName}:${this.collectionName}:*`
     ];
-    const patterns = operation === "find" ? [`find:${namespace}:*`] : operation === "findOne" ? [`findOne:${namespace}:*`] : operation === "count" ? [`count:${namespace}:*`] : operation === "findPage" ? [`bookmark:${bookmarkNamespace}:*`] : [
+    const findPagePatterns = [
+      `findPage:${namespace}:*`,
+      `findPageTotals:${namespace}:*`,
+      `bookmark:${bookmarkNamespace}:*`,
+      `${bookmarkNamespace}:bm:*`
+    ];
+    const patterns = operation === "find" ? [`find:${namespace}:*`] : operation === "findOne" ? [`findOne:${namespace}:*`] : operation === "count" ? [`count:${namespace}:*`] : operation === "findPage" ? findPagePatterns : [
       `find:${namespace}:*`,
       `findOne:${namespace}:*`,
       `count:${namespace}:*`,
-      `bookmark:${bookmarkNamespace}:*`
+      ...findPagePatterns
     ];
     patterns.push(...legacyNamespacePatterns);
     let deleted = 0;
@@ -7149,7 +7802,7 @@ var MongoCollectionAccessor = class {
   }
   async findPage(options = {}) {
     const resolvedOptions = options.query ? { ...options, query: this._cvFilter(options.query) } : options;
-    return findPageDocuments(this.collectionRef, resolvedOptions, this.management.defaults);
+    return findPageDocuments(this.collectionRef, resolvedOptions, this.management.defaults, this.management.queryCache);
   }
   /** Opens a change stream on the collection with an optional aggregation pipeline. */
   watch(pipeline = [], options) {
@@ -7626,6 +8279,26 @@ function createRuntimeModelInstance(host, name, scope) {
   });
   return instance;
 }
+async function ensureRuntimeModelIndexes(host, options = {}) {
+  const modelNames = options.models ?? Model.list();
+  const models = [];
+  for (const name of modelNames) {
+    const model = host.scopedModel(name, {
+      database: options.database,
+      pool: options.pool
+    });
+    const result = await model.ensureIndexes({
+      dryRun: options.dryRun,
+      throwOnError: options.throwOnError
+    });
+    models.push({ name, result });
+  }
+  return {
+    dryRun: options.dryRun === true,
+    models,
+    totals: summarizeModelIndexEnsureResults(models.map((item) => item.result))
+  };
+}
 
 // src/entry/runtime-core-hosts.ts
 function resolveAdapterCache(state) {
@@ -7841,7 +8514,7 @@ function createRuntimeAdapterBridge(host) {
     dropDatabase: async (name, adminOptions) => {
       host.ensureConnected();
       if (!name || typeof name !== "string") {
-        throw new Error("Database name is required and must be a non-empty string");
+        throw createError(ErrorCodes.INVALID_DATABASE_NAME, "Database name is required and must be a non-empty string");
       }
       if (!adminOptions?.confirm) {
         const error = new Error(
@@ -7877,7 +8550,7 @@ function createRuntimeAdapterBridge(host) {
     runCommand: async (command, adminOptions) => {
       host.ensureConnected();
       if (command === null || typeof command !== "object") {
-        throw new Error("Command must be a non-null object");
+        throw createError(ErrorCodes.INVALID_ARGUMENT, "Command must be a non-null object");
       }
       return host.db().runCommand(command, adminOptions ?? {});
     },
@@ -8003,8 +8676,8 @@ var LockManager = class {
       if (attempt === retryTimes) {
         break;
       }
-      const delay = retryDelay * Math.pow(retryBackoff, attempt);
-      await sleep3(delay);
+      const delay2 = retryDelay * Math.pow(retryBackoff, attempt);
+      await sleep3(delay2);
     }
     this.stats.errors += 1;
     if (options.fallbackToNoLock) {
@@ -8128,7 +8801,7 @@ var DistributedCacheLockManager = class {
       errors: 0
     };
     if (!options.redis) {
-      throw new Error("DistributedCacheLockManager requires a Redis instance");
+      throw createError(ErrorCodes.INVALID_CONFIG, "DistributedCacheLockManager requires a Redis instance");
     }
     this.redis = options.redis;
     this.lockKeyPrefix = options.lockKeyPrefix ?? "monsqlize:cache:lock:";
@@ -8786,17 +9459,17 @@ var BatchQueue = class {
 import { MongoClient as MongoDriverClient2 } from "mongodb";
 
 // src/capabilities/slow-query-log/slow-query-log-records.ts
-import { createHash as createHash2 } from "node:crypto";
-function stableStringify2(value) {
+import { createHash as createHash3 } from "node:crypto";
+function stableStringify3(value) {
   if (Array.isArray(value)) {
-    return `[${value.map((item) => stableStringify2(item)).join(",")}]`;
+    return `[${value.map((item) => stableStringify3(item)).join(",")}]`;
   }
   if (value instanceof Date) {
     return JSON.stringify(value.toISOString());
   }
   if (value && typeof value === "object") {
     const entries = Object.entries(value).sort(([left], [right]) => left.localeCompare(right));
-    return `{${entries.map(([key, current]) => `${JSON.stringify(key)}:${stableStringify2(current)}`).join(",")}}`;
+    return `{${entries.map(([key, current]) => `${JSON.stringify(key)}:${stableStringify3(current)}`).join(",")}}`;
   }
   return JSON.stringify(value);
 }
@@ -8813,7 +9486,7 @@ function normalizeHashInput(input) {
   };
 }
 function generateQueryHash(input) {
-  return createHash2("sha256").update(stableStringify2(normalizeHashInput(input))).digest("hex").slice(0, 16);
+  return createHash3("sha256").update(stableStringify3(normalizeHashInput(input))).digest("hex").slice(0, 16);
 }
 function handleSlowQueryLogError(logger, policy, error) {
   if (policy === "throw") {
@@ -9263,7 +9936,7 @@ var SlowQueryLogManager = class {
 
 // src/capabilities/sync/index.ts
 import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
-import path from "node:path";
+import path2 from "node:path";
 import { MongoClient as MongoDriverClient3 } from "mongodb";
 function validateTargetConfig(target, index) {
   if (!target || typeof target !== "object") {
@@ -9370,7 +10043,7 @@ var ResumeTokenStore = class {
         await Promise.resolve(this.redis.set(this.redisKey, payload));
         return;
       }
-      await mkdir(path.dirname(this.path), { recursive: true });
+      await mkdir(path2.dirname(this.path), { recursive: true });
       await writeFile(this.path, payload, "utf8");
     } catch (error) {
       this.logger?.error?.("[Sync] failed to save resume token", error);
@@ -9642,7 +10315,16 @@ function getOrCreateTransactionManager(config) {
     client: config.client,
     cache: config.cache,
     logger: config.logger,
-    lockManager: config.lockManager
+    lockManager: config.lockManager,
+    maxDuration: config.transaction?.maxDuration ?? config.transaction?.defaultTimeout,
+    enableRetry: config.transaction?.enableRetry,
+    maxRetries: config.transaction?.maxRetries,
+    retryDelay: config.transaction?.retryDelay,
+    retryBackoff: config.transaction?.retryBackoff,
+    defaultReadConcern: config.transaction?.defaultReadConcern,
+    defaultWriteConcern: config.transaction?.defaultWriteConcern,
+    defaultReadPreference: config.transaction?.defaultReadPreference,
+    maxStatsSamples: config.transaction?.maxStatsSamples
   });
 }
 function getOrCreateLockManager(current, logger) {
@@ -9932,7 +10614,7 @@ function resolveCacheSource(cacheOrDb) {
       return cache;
     }
   }
-  throw new Error("Invalid cache instance from MonSQLize");
+  throw createError(ErrorCodes.CACHE_UNAVAILABLE, "Invalid cache instance from MonSQLize");
 }
 function toWithCacheStats(stats, totalTime = 0) {
   const calls = stats.hits + stats.misses;
@@ -9961,46 +10643,46 @@ function normalizeFunctionCacheStats(stats, timings, name) {
 }
 function validateFunctionCacheOptions(options) {
   if (options !== void 0 && (typeof options !== "object" || options === null || Array.isArray(options))) {
-    throw new Error("options must be an object");
+    throw createError(ErrorCodes.INVALID_ARGUMENT, "options must be an object");
   }
   const opts = options ?? {};
   if (opts.namespace !== void 0 && typeof opts.namespace !== "string") {
-    throw new Error("namespace must be a string");
+    throw createError(ErrorCodes.INVALID_ARGUMENT, "namespace must be a string");
   }
   const ttl = opts.ttl !== void 0 ? opts.ttl : opts.defaultTTL;
   if (ttl !== void 0 && (typeof ttl !== "number" || Number.isNaN(ttl) || ttl < 0)) {
-    throw new Error("defaultTTL must be a non-negative number");
+    throw createError(ErrorCodes.INVALID_ARGUMENT, "defaultTTL must be a non-negative number");
   }
   return opts;
 }
 function validateFunctionCachePerFnOptions(options) {
   if (options !== void 0 && (typeof options !== "object" || options === null || Array.isArray(options))) {
-    throw new Error("options must be an object");
+    throw createError(ErrorCodes.INVALID_ARGUMENT, "options must be an object");
   }
   const opts = options ?? {};
   if (opts.keyBuilder !== void 0 && typeof opts.keyBuilder !== "function") {
-    throw new Error("keyBuilder must be a function");
+    throw createError(ErrorCodes.INVALID_ARGUMENT, "keyBuilder must be a function");
   }
   if (opts.condition !== void 0 && typeof opts.condition !== "function") {
-    throw new Error("condition must be a function");
+    throw createError(ErrorCodes.INVALID_ARGUMENT, "condition must be a function");
   }
   const ttl = opts.ttl !== void 0 ? opts.ttl : opts.defaultTTL;
   if (ttl !== void 0 && (typeof ttl !== "number" || Number.isNaN(ttl) || ttl < 0)) {
-    throw new Error("defaultTTL must be a non-negative number");
+    throw createError(ErrorCodes.INVALID_ARGUMENT, "defaultTTL must be a non-negative number");
   }
   return opts;
 }
 function withCache(fn, options = {}) {
-  if (typeof fn !== "function") throw new Error("fn must be a function");
+  if (typeof fn !== "function") throw createError(ErrorCodes.INVALID_ARGUMENT, "fn must be a function");
   const { ttl = 6e4, namespace, keyBuilder, condition, cache: externalCache, enableStats = true } = options;
   if (typeof ttl !== "number" || Number.isNaN(ttl) || ttl < 0)
-    throw new Error("ttl must be a non-negative number");
+    throw createError(ErrorCodes.INVALID_ARGUMENT, "ttl must be a non-negative number");
   if (keyBuilder !== void 0 && typeof keyBuilder !== "function")
-    throw new Error("keyBuilder must be a function");
+    throw createError(ErrorCodes.INVALID_ARGUMENT, "keyBuilder must be a function");
   if (condition !== void 0 && typeof condition !== "function")
-    throw new Error("condition must be a function");
+    throw createError(ErrorCodes.INVALID_ARGUMENT, "condition must be a function");
   if (externalCache !== void 0 && !isValidCache(externalCache))
-    throw new Error("Invalid cache instance");
+    throw createError(ErrorCodes.CACHE_UNAVAILABLE, "Invalid cache instance");
   const wrapped = hubWithCache(fn, {
     ttl,
     namespace: namespace ?? "fn",
@@ -10042,9 +10724,9 @@ var FunctionCache = class {
   }
   register(name, fn, options) {
     if (!name || typeof name !== "string")
-      throw new Error("Function name must be a non-empty string");
+      throw createError(ErrorCodes.INVALID_ARGUMENT, "Function name must be a non-empty string");
     if (typeof fn !== "function")
-      throw new Error("fn must be a function");
+      throw createError(ErrorCodes.INVALID_ARGUMENT, "fn must be a function");
     const opts = validateFunctionCachePerFnOptions(options);
     const ttl = opts.ttl !== void 0 ? opts.ttl : opts.defaultTTL;
     this._inner.register(name, fn, {
@@ -10070,13 +10752,13 @@ var FunctionCache = class {
   }
   async invalidate(name, ...args) {
     if (!name || typeof name !== "string") {
-      throw new Error("Function name must be a non-empty string");
+      throw createError(ErrorCodes.INVALID_ARGUMENT, "Function name must be a non-empty string");
     }
     await this._inner.invalidate(name, ...args);
   }
   async invalidatePattern(pattern) {
     if (!pattern || typeof pattern !== "string")
-      throw new Error("Pattern must be a non-empty string");
+      throw createError(ErrorCodes.INVALID_ARGUMENT, "Pattern must be a non-empty string");
     return this._inner.invalidatePattern(pattern);
   }
   list() {
@@ -10111,15 +10793,15 @@ function b64urlDecodeStr(s) {
   const b64 = pad(String(s || "")).replace(/-/g, "+").replace(/_/g, "/");
   return Buffer.from(b64, "base64").toString();
 }
-function makeInvalidCursorError(cause) {
-  const err = new Error("Invalid cursor");
+function makeInvalidCursorError(message = "Invalid cursor", cause) {
+  const err = new Error(message);
   err.code = "INVALID_CURSOR";
   if (cause !== void 0) err.cause = cause;
   return err;
 }
 function encodeCursor2(payload) {
   if (!payload.s || !payload.a) {
-    throw new Error("encodeCursor requires sort (s) and anchor (a)");
+    throw makeInvalidCursorError("encodeCursor requires sort (s) and anchor (a)");
   }
   const json = JSON.stringify({ v: payload.v ?? 1, s: payload.s, a: payload.a, d: payload.d });
   return b64urlEncodeStr(json);
@@ -10128,11 +10810,11 @@ function decodeCursor2(str) {
   try {
     const obj = JSON.parse(b64urlDecodeStr(str));
     if (!obj || obj["v"] !== 1 || !obj["s"] || !obj["a"]) {
-      throw new Error("bad-structure");
+      throw makeInvalidCursorError("bad-structure");
     }
     return obj;
   } catch (e) {
-    throw makeInvalidCursorError(e);
+    throw makeInvalidCursorError("Invalid cursor", e);
   }
 }
 
@@ -10204,7 +10886,11 @@ var MonSQLizeRuntime = class {
     } : rawCacheInput;
     this._cache = normalizeRuntimeCache(cacheInput);
     this._logger = Logger.create(options.logger ?? null);
-    this._cacheLockManager = new CacheLockManager({ logger: options.logger ?? null });
+    this._cacheLockManager = new CacheLockManager({
+      logger: options.logger ?? null,
+      maxDuration: options.transaction?.lockMaxDuration,
+      cleanupInterval: options.transaction?.lockCleanupInterval
+    });
     this._cache.setLockManager?.(this._cacheLockManager);
     this._runtimeDefaults = buildRuntimeDefaults(options);
     this._adapterCacheOverride = void 0;
@@ -10324,7 +11010,8 @@ var MonSQLizeRuntime = class {
       namespace: d.namespace,
       log: d.log,
       countQueue: this.options.countQueue,
-      models: this.options.models
+      models: this.options.models,
+      autoIndex: this.options.autoIndex
     };
   }
   async close() {
@@ -10521,6 +11208,10 @@ var MonSQLizeRuntime = class {
     cache.set(name, instance);
     return instance;
   }
+  async ensureModelIndexes(options = {}) {
+    this.ensureConnected();
+    return ensureRuntimeModelIndexes(this, options);
+  }
   // Capability delegation ----------------------------------------------------
   async startSession(options = {}) {
     this.ensureConnected();
@@ -10575,9 +11266,15 @@ var MonSQLizeRuntime = class {
   listSagas() {
     return this.initializeSagaOrchestrator().listSagas();
   }
+  getTransactionStats() {
+    return this._transactionManager?.getStats() ?? null;
+  }
   getSagaStats() {
     return this.initializeSagaOrchestrator().getStats();
   }
+  getDistributedCacheInvalidatorStats() {
+    return this._distributedInvalidator?.getStats() ?? null;
+  }
   async startSync() {
     this.ensureConnected();
     const manager = await this.initializeSyncManager();
@@ -10656,7 +11353,8 @@ var MonSQLizeRuntime = class {
       client: this._client,
       cache: this._cache,
       logger: this.options.logger ?? null,
-      lockManager: this._cacheLockManager
+      lockManager: this._cacheLockManager,
+      transaction: this.options.transaction
     });
     return this._transactionManager;
   }