monsqlize 3.2.0 → 3.3.1

package/dist/esm/index.mjs

@@ -170,12 +170,17 @@ function createRedisCacheAdapter(redisUrlOrInstance, options) {
 
 // src/capabilities/cache/distributed-cache-invalidator.ts
 import { randomBytes } from "crypto";
+import { MemoryCache as BaseMemoryCache2 } from "cache-hub";
 var DistributedCacheInvalidator = class {
   constructor(options) {
     if (!options.cache) {
       throw createError(ErrorCodes.CACHE_UNAVAILABLE, "DistributedCacheInvalidator requires a cache instance");
     }
     this._cache = options.cache;
+    const safeMemoryCache = this._cache instanceof BaseMemoryCache2 || this._cache.local instanceof BaseMemoryCache2 && this._cache.remote === void 0;
+    if (!safeMemoryCache && typeof this._cache.invalidateFromRemote !== "function") {
+      throw createError(ErrorCodes.INVALID_CONFIG, "DistributedCacheInvalidator requires receive-only cache invalidation");
+    }
     this._logger = options.logger ?? null;
     this.channel = options.channel ?? "monsqlize:cache:invalidate";
     this.instanceId = options.instanceId ?? `instance-${Date.now()}-${randomBytes(4).toString("hex")}`;
@@ -223,18 +228,10 @@ var DistributedCacheInvalidator = class {
       this._stats.messagesReceived++;
       try {
         if (isPatternInvalidation) {
-          for (const targetCache of this._getPatternTargetCaches()) {
-            await targetCache.delPattern?.(String(message.pattern));
-          }
+          await this._invalidateFromRemote("pattern", String(message.pattern));
           this._logger?.debug?.(`[DistributedCacheInvalidator] Invalidated cache targets: ${String(message.pattern)}`);
         } else {
-          for (const targetCache of this._getKeyTargetCaches()) {
-            if (typeof targetCache.del === "function") {
-              await targetCache.del(String(message.key));
-            } else {
-              await targetCache.delete?.(String(message.key));
-            }
-          }
+          await this._invalidateFromRemote("key", String(message.key));
           this._logger?.debug?.(`[DistributedCacheInvalidator] Invalidated cache key targets: ${String(message.key)}`);
         }
         this._stats.invalidationsTriggered++;
@@ -244,32 +241,18 @@ var DistributedCacheInvalidator = class {
       }
     });
   }
-  _getPatternTargetCaches() {
-    const targets = /* @__PURE__ */ new Set();
-    if (typeof this._cache?.delPattern === "function") {
-      targets.add(this._cache);
-    }
-    if (this._cache?.local && typeof this._cache.local.delPattern === "function") {
-      targets.add(this._cache.local);
-    }
-    if (this._cache?.remote && typeof this._cache.remote.delPattern === "function") {
-      targets.add(this._cache.remote);
-    }
-    return [...targets];
-  }
-  _getKeyTargetCaches() {
-    const targets = /* @__PURE__ */ new Set();
-    const supportsKeyDelete = (cache) => typeof cache?.del === "function" || typeof cache?.delete === "function";
-    if (supportsKeyDelete(this._cache)) {
-      targets.add(this._cache);
-    }
-    if (supportsKeyDelete(this._cache?.local)) {
-      targets.add(this._cache.local);
+  async _invalidateFromRemote(kind, value) {
+    if (this._cache instanceof BaseMemoryCache2) {
+      if (kind === "pattern") await this._cache.delPattern(value);
+      else await this._cache.del(value);
+      return;
     }
-    if (supportsKeyDelete(this._cache?.remote)) {
-      targets.add(this._cache.remote);
+    if (this._cache.local instanceof BaseMemoryCache2 && this._cache.remote === void 0) {
+      if (kind === "pattern") await this._cache.local.delPattern(value);
+      else await this._cache.local.del(value);
+      return;
     }
-    return [...targets];
+    await this._cache.invalidateFromRemote?.(kind, value);
   }
   async invalidate(pattern) {
     if (!pattern) return;
@@ -341,6 +324,15 @@ var MultiLevelCache = class extends BaseMultiLevelCache {
     this._localCompat.setLockManager?.(lockManager);
     this._remoteCompat?.setLockManager?.(lockManager);
   }
+  async invalidateFromRemote(kind, value) {
+    if (kind === "pattern") {
+      await this._localCompat.delPattern(value);
+      await this._remoteCompat?.delPattern(value);
+    } else {
+      await this._localCompat.del(value);
+      await this._remoteCompat?.del(value);
+    }
+  }
 };
 function adaptLegacyCacheLike(v1Cache) {
   if ("has" in v1Cache && typeof v1Cache.has === "function") {
@@ -532,6 +524,9 @@ function normalizePopulateConfig(path5) {
 }
 
 // src/capabilities/model/model-registry.ts
+function defineModel(collectionName, definition) {
+  return { collectionName, definition };
+}
 var Model = class {
   static {
     // collection name → registered model definition
@@ -546,21 +541,19 @@ var Model = class {
     /** Collection names that have been redefined (used by the runtime to trigger hot-reload). */
     this._redefinedNames = /* @__PURE__ */ new Set();
   }
-  /**
-   * Register a new model definition.
-   * Throws MODEL_ALREADY_EXISTS if a model with the same name already exists.
-   * Validates the definition and resolves the timestamps option.
-   */
-  static define(collectionName, definition) {
+  static define(collectionNameOrDescriptor, definition) {
+    const collectionName = typeof collectionNameOrDescriptor === "string" ? collectionNameOrDescriptor : collectionNameOrDescriptor.collectionName;
+    const modelDefinition = typeof collectionNameOrDescriptor === "string" ? definition : collectionNameOrDescriptor.definition;
     const normalizedName = validateCollectionName(collectionName);
     if (this.registry.has(normalizedName)) {
       throw createError(ErrorCodes.MODEL_ALREADY_EXISTS, `Model '${normalizedName}' is already defined.`);
     }
-    validateDefinition(definition);
-    processTimestamps(definition);
+    validateDefinition(modelDefinition);
+    const resolvedDefinition = modelDefinition;
+    processTimestamps(resolvedDefinition);
     this.registry.set(normalizedName, {
       collectionName: normalizedName,
-      definition
+      definition: resolvedDefinition
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
     });
     this.bumpRevision(normalizedName);
@@ -717,6 +710,40 @@ function serializeDocument(document) {
 }
 
 // src/capabilities/model/model-write-helpers.ts
+async function* iterateModelCandidateBatches(context, filter, options, batchSize) {
+  const lookupOptions = buildModelVersionLookupOptions(options, {
+    _id: 1,
+    [context.versionConfig?.field ?? "__v"]: 1
+  });
+  const stream = context.collection.stream(filter, {
+    ...lookupOptions,
+    sort: { _id: 1 },
+    batchSize
+  });
+  let batch = [];
+  try {
+    for await (const document of stream) {
+      batch.push(document);
+      if (batch.length === batchSize) {
+        yield batch;
+        batch = [];
+      }
+    }
+    if (batch.length > 0) yield batch;
+  } finally {
+    stream.destroy();
+  }
+}
+function buildStrictCandidateFilter(filter, id, versionField, expectedVersion) {
+  return { $and: [filter ?? {}, { _id: id }, { [versionField]: expectedVersion }] };
+}
+async function isModelVersionConflict(context, filter, id, versionField, expectedVersion, options) {
+  const current = await context.collection.findOne(
+    { $and: [filter ?? {}, { _id: id }] },
+    buildModelVersionLookupOptions(options, { [versionField]: 1 })
+  );
+  return current !== null && current !== void 0 && current[versionField] !== expectedVersion;
+}
 var VERSION_LOOKUP_OPTION_KEYS = [
   "session",
   "readConcern",
@@ -802,11 +829,14 @@ function mapModelSchemaValidationErrors(errors = []) {
 }
 function validateModelSchemaPayload(context, document, options, metadata = {}) {
   const shouldValidate = context.validateEnabled || options?.validate === true;
-  if (!shouldValidate) {
+  if (!shouldValidate || options?.skipValidation) {
     return document;
   }
-  if (options?.skipValidation) {
-    return document;
+  if (context.schemaError) {
+    throw withModelErrorMetadata(
+      createError(ErrorCodes.VALIDATION_ERROR, `Schema initialization failed: ${context.schemaError.message}`),
+      { errors: [{ field: "_schema", message: context.schemaError.message }], ...metadata }
+    );
   }
   if (!context.schemaCache || !context.schemaValidateFn) {
     return document;
@@ -840,22 +870,31 @@ function validateModelSchemaPayload(context, document, options, metadata = {}) {
   }
   return normalized;
 }
+function buildModelVisibleSoftDeleteCondition(config) {
+  return { [config.field]: config.type === "boolean" ? { $ne: true } : null };
+}
 function applyModelSoftDeleteFilter(query, options, softDeleteConfig) {
   if (!softDeleteConfig?.enabled) {
     return query ?? {};
   }
   const resolvedOptions = options ?? {};
   const resolvedQuery = query ?? {};
-  if (resolvedQuery[softDeleteConfig.field] !== void 0) {
+  if (resolvedOptions.withDeleted !== void 0 && typeof resolvedOptions.withDeleted !== "boolean") {
+    throw createError(ErrorCodes.INVALID_ARGUMENT, "withDeleted must be a boolean.");
+  }
+  if (resolvedOptions.onlyDeleted !== void 0 && typeof resolvedOptions.onlyDeleted !== "boolean") {
+    throw createError(ErrorCodes.INVALID_ARGUMENT, "onlyDeleted must be a boolean.");
+  }
+  if (Object.prototype.hasOwnProperty.call(resolvedQuery, softDeleteConfig.field)) {
     return resolvedQuery;
   }
   if (resolvedOptions.withDeleted) {
     return resolvedQuery;
   }
   if (resolvedOptions.onlyDeleted) {
-    return { ...resolvedQuery, [softDeleteConfig.field]: { $ne: null } };
+    return { ...resolvedQuery, [softDeleteConfig.field]: softDeleteConfig.type === "boolean" ? true : { $ne: null } };
   }
-  return { ...resolvedQuery, [softDeleteConfig.field]: null };
+  return { ...resolvedQuery, ...buildModelVisibleSoftDeleteCondition(softDeleteConfig) };
 }
 function applyModelInsertTimestamps(document, timestampsConfig, nowFactory) {
   if (!timestampsConfig) {
@@ -1150,7 +1189,9 @@ function projectPopulatedDocument(document, select, nestedPaths) {
     return document;
   }
   const nestedRelationFields = nestedPaths.map((path5) => normalizePopulateConfig(path5).path);
-  return pickFields(document, [.../* @__PURE__ */ new Set([...select, ...nestedRelationFields])]);
+  const projected = pickFields(document, [.../* @__PURE__ */ new Set([...select, ...nestedRelationFields])]);
+  if (!select.includes("_id")) delete projected._id;
+  return projected;
 }
 async function populateModelPath(context, docs, path5, traversalState) {
   const config = normalizePopulateConfig(path5);
@@ -1172,7 +1213,13 @@ async function populateModelPath(context, docs, path5, traversalState) {
     }
     const localValues = docs.map((doc) => getByPath(doc, relation.localField));
     const keys = unique(localValues.flatMap((value) => flattenComparableValues(value)));
-    if (keys.length === 0) {
+    if (config.limit !== void 0 && (!Number.isSafeInteger(config.limit) || config.limit < 0)) {
+      throw createError(ErrorCodes.INVALID_ARGUMENT, "populate limit must be a non-negative integer");
+    }
+    if (config.skip !== void 0 && (!Number.isSafeInteger(config.skip) || config.skip < 0)) {
+      throw createError(ErrorCodes.INVALID_ARGUMENT, "populate skip must be a non-negative integer");
+    }
+    if (keys.length === 0 || config.limit === 0) {
       for (const doc of docs) {
         doc[config.path] = relation.single ? null : [];
       }
@@ -1192,36 +1239,63 @@ async function populateModelPath(context, docs, path5, traversalState) {
       ...effectiveSelect,
       relation.foreignField,
       "_id",
-      ...collectNestedLocalFields(relatedModel, nestedPaths)
+      ...Object.keys(config.sort ?? {}),
+      ...collectNestedLocalFields(relatedModel, nestedPaths),
+      ...relatedModel?.softDeleteConfig?.enabled ? [relatedModel.softDeleteConfig.field] : []
     ])] : [];
-    const relatedDocs = await relatedCollection.find({
-      [relation.foreignField]: { $in: keys },
-      ...config.match ?? {}
-    }, effectiveSelect ? {
-      projection: Object.fromEntries(projectionFields.map((field) => [field, 1]))
-    } : void 0);
-    let hydrated = relatedModel ? relatedModel.hydrateDocuments(relatedDocs) : relatedDocs.map((item) => ({ ...item }));
-    if (nestedPaths.length > 0 && relatedModel) {
-      if (state.depth + 1 > state.maxDepth) {
-        throw createError(ErrorCodes.INVALID_ARGUMENT, `populate maxDepth exceeded: ${state.maxDepth}`);
+    const readOptions = {
+      ...effectiveSelect ? { projection: Object.fromEntries(projectionFields.map((field) => [field, 1])) } : {},
+      ...config.sort ? { sort: config.sort } : {}
+    };
+    const visibilityMatch = applyModelSoftDeleteFilter(config.match ?? {}, {}, relatedModel?.softDeleteConfig ?? null);
+    const readForKeys = (values, options = readOptions) => {
+      const keyFilter = { [relation.foreignField]: { $in: values } };
+      return readPopulateRows(
+        relatedCollection,
+        Object.keys(visibilityMatch).length === 0 ? keyFilter : { $and: [keyFilter, visibilityMatch] },
+        options
+      );
+    };
+    const hydrateRelated = async (rows) => {
+      let hydrated = relatedModel ? relatedModel.hydrateDocuments(rows) : rows.map((item) => ({ ...item }));
+      if (nestedPaths.length > 0 && relatedModel) {
+        if (state.depth + 1 > state.maxDepth) {
+          throw createError(ErrorCodes.INVALID_ARGUMENT, `populate maxDepth exceeded: ${state.maxDepth}`);
+        }
+        hydrated = await relatedModel.populateDocuments(hydrated, nestedPaths, {
+          depth: state.depth + 1,
+          maxDepth: state.maxDepth,
+          activeConfigs: state.activeConfigs
+        });
       }
-      hydrated = await relatedModel.populateDocuments(hydrated, nestedPaths, {
-        depth: state.depth + 1,
-        maxDepth: state.maxDepth,
-        activeConfigs: state.activeConfigs
-      });
-    }
-    const grouped = groupBy(hydrated, (item) => getByPath(item, relation.foreignField));
-    for (const [index, doc] of docs.entries()) {
-      let matches = rebuildPopulateMatches(localValues[index], grouped, config.sort);
-      if (config.skip) {
-        matches = matches.slice(config.skip);
+      return hydrated;
+    };
+    if (config.limit !== void 0 || config.skip !== void 0) {
+      const scopedOptions = {
+        ...readOptions,
+        ...config.skip !== void 0 ? { skip: config.skip } : {},
+        ...config.limit !== void 0 ? { limit: config.limit } : {}
+      };
+      for (const [index, doc] of docs.entries()) {
+        const parentKeys = unique(flattenComparableValues(localValues[index]));
+        const rows = parentKeys.length > 0 ? await readForKeys(parentKeys, scopedOptions) : [];
+        const hydrated = await hydrateRelated(rows);
+        const matches = dedupeDocuments(hydrated);
+        const projectedMatches = matches.map((item) => projectPopulatedDocument(item, effectiveSelect, nestedPaths));
+        doc[config.path] = relation.single ? projectedMatches[0] ?? null : projectedMatches;
+      }
+    } else {
+      const rows = [];
+      for (let offset = 0; offset < keys.length; offset += 200) {
+        rows.push(...await readForKeys(keys.slice(offset, offset + 200)));
       }
-      if (config.limit !== void 0) {
-        matches = matches.slice(0, config.limit);
+      const hydrated = await hydrateRelated(rows);
+      const grouped = groupBy(hydrated, (item) => getByPath(item, relation.foreignField));
+      for (const [index, doc] of docs.entries()) {
+        const matches = rebuildPopulateMatches(localValues[index], grouped, config.sort);
+        const projectedMatches = matches.map((item) => projectPopulatedDocument(item, effectiveSelect, nestedPaths));
+        doc[config.path] = relation.single ? projectedMatches[0] ?? null : projectedMatches;
       }
-      const projectedMatches = matches.map((item) => projectPopulatedDocument(item, effectiveSelect, nestedPaths));
-      doc[config.path] = relation.single ? projectedMatches[0] ?? null : projectedMatches;
     }
     return docs;
   } finally {
@@ -1422,12 +1496,28 @@ async function saveModelDocument(collection, document, options = {}) {
   document._id = result.insertedId;
   return document;
 }
-async function removeModelDocument(collection, document) {
+async function removeModelDocument(collection, document, deleteOne = (filter) => collection.deleteOne(filter)) {
   if (document._id === void 0) {
     return false;
   }
-  const result = await collection.deleteOne({ _id: document._id });
-  return Boolean(result.deletedCount ?? result.acknowledged);
+  const result = await deleteOne({ _id: document._id });
+  if (result.matchedCount === void 0 && result.modifiedCount === void 0 && result.deletedCount === void 0) {
+    return result.acknowledged === true;
+  }
+  return Boolean(result.matchedCount || result.modifiedCount || result.deletedCount);
+}
+async function readPopulateRows(collection, query, options) {
+  if (typeof collection.stream !== "function") {
+    return await collection.find(query, options);
+  }
+  const stream = collection.stream(query, options);
+  const rows = [];
+  try {
+    for await (const row of stream) rows.push(row);
+  } finally {
+    stream.destroy();
+  }
+  return rows;
 }
 
 // src/capabilities/model/model-soft-delete-helpers.ts
@@ -1435,7 +1525,53 @@ function deletedFilter(filter, softDeleteConfig) {
   if (!softDeleteConfig) {
     return filter ?? {};
   }
-  return { ...filter ?? {}, [softDeleteConfig.field]: { $ne: null } };
+  return applyModelSoftDeleteFilter(filter, { onlyDeleted: true }, softDeleteConfig);
+}
+function filterVisibleBySoftDelete(docs, options, config) {
+  if (!config?.enabled) return docs.filter((doc) => Boolean(doc));
+  const rawOptions = options ?? {};
+  applyModelSoftDeleteFilter({}, rawOptions, config);
+  if (rawOptions.withDeleted) return docs.filter((doc) => Boolean(doc));
+  return docs.filter((doc) => {
+    if (!doc) return false;
+    const value = doc[config.field];
+    const deleted = config.type === "boolean" ? value === true : value !== void 0 && value !== null;
+    return rawOptions.onlyDeleted ? deleted : !deleted;
+  });
+}
+function withSoftDeleteProjection(options, config) {
+  if (!config?.enabled) return { options, stripField: false };
+  const rawOptions = options ?? {};
+  const field = config.field;
+  const projection = rawOptions.projection ?? rawOptions.project;
+  if (Array.isArray(projection)) {
+    if (projection.includes(field)) return { options, stripField: false };
+    return { options: { ...rawOptions, projection: [...projection, field] }, stripField: true };
+  }
+  if (!projection || typeof projection !== "object") return { options, stripField: false };
+  const projectionRecord = projection;
+  if (projectionRecord[field] === 1 || projectionRecord[field] === true) return { options, stripField: false };
+  const inclusion = Object.entries(projectionRecord).some(([key, value]) => key !== "_id" && (value === 1 || value === true));
+  const nextProjection = { ...projectionRecord };
+  if (inclusion) nextProjection[field] = 1;
+  else delete nextProjection[field];
+  return { options: { ...rawOptions, projection: nextProjection }, stripField: true };
+}
+function applySoftDeleteFindPageOptions(options, config) {
+  const rawOptions = options ?? {};
+  return { ...rawOptions, query: applyModelSoftDeleteFilter(rawOptions.query, rawOptions, config) };
+}
+function applySoftDeleteAggregatePipeline(pipeline, options, config) {
+  if (!config?.enabled) return pipeline ?? [];
+  const rawOptions = options ?? {};
+  if (rawOptions.withDeleted) return pipeline ?? [];
+  const softDeleteMatch = applyModelSoftDeleteFilter({}, rawOptions, config);
+  const matchStage = { $match: softDeleteMatch };
+  const stages = [...pipeline ?? []];
+  if (stages.length > 0 && stages[0] && typeof stages[0] === "object" && "$geoNear" in stages[0]) {
+    return [stages[0], matchStage, ...stages.slice(1)];
+  }
+  return [matchStage, ...stages];
 }
 function findWithDeletedDocuments(context, query, options) {
   return new PopulatePromise(async (paths) => {
@@ -1478,7 +1614,7 @@ function restoreSoftDeletedDocuments(context, filter, options) {
     return Promise.resolve({ modifiedCount: 0 });
   }
   return context.collection.updateOne(
-    { ...filter ?? {}, [softDeleteConfig.field]: { $ne: null } },
+    deletedFilter(filter, softDeleteConfig),
     { $unset: { [softDeleteConfig.field]: 1 } },
     options
   );
@@ -1489,7 +1625,7 @@ function restoreManySoftDeletedDocuments(context, filter, options) {
     return Promise.resolve({ modifiedCount: 0 });
   }
   return context.collection.updateMany(
-    { ...filter ?? {}, [softDeleteConfig.field]: { $ne: null } },
+    deletedFilter(filter, softDeleteConfig),
     { $unset: { [softDeleteConfig.field]: 1 } },
     options
   );
@@ -3105,6 +3241,9 @@ var modelWriteSourceStorage = new AsyncLocalStorage();
 function isPlainObject2(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
+function ownValue(record, key) {
+  return Object.prototype.hasOwnProperty.call(record, key) ? record[key] : void 0;
+}
 function invalidConfig(path5, reason) {
   throw createError(
     ErrorCodes.INVALID_OPERATION,
@@ -3125,19 +3264,19 @@ function normalizeRule(input, path5) {
   if (!isPlainObject2(input)) {
     invalidConfig(path5, "rule must be a string mode or an object");
   }
-  const mode = input.mode ?? DEFAULT_RULE.mode;
+  const mode = ownValue(input, "mode") ?? DEFAULT_RULE.mode;
   if (!ALLOWED_MODES.has(mode)) {
     invalidConfig(`${path5}.mode`, 'must be "allow-both" or "model-only"');
   }
-  const raw = input.raw ?? DEFAULT_RULE.raw;
+  const raw = ownValue(input, "raw") ?? DEFAULT_RULE.raw;
   if (!ALLOWED_RAW.has(raw)) {
     invalidConfig(`${path5}.raw`, 'must be "inherit", "allow", or "block"');
   }
-  const management = input.management ?? DEFAULT_RULE.management;
+  const management = ownValue(input, "management") ?? DEFAULT_RULE.management;
   if (!ALLOWED_MANAGEMENT.has(management)) {
     invalidConfig(`${path5}.management`, 'must be "inherit", "allow", or "block"');
   }
-  const onViolation = input.onViolation ?? DEFAULT_RULE.onViolation;
+  const onViolation = ownValue(input, "onViolation") ?? DEFAULT_RULE.onViolation;
   if (!ALLOWED_VIOLATION_ACTIONS.has(onViolation)) {
     invalidConfig(`${path5}.onViolation`, 'must be "throw" or "warn"');
   }
@@ -3153,15 +3292,15 @@ function validateWritePathPolicyConfig(options) {
 }
 function normalizeWritePathPolicy(options) {
   if (options === void 0) {
-    return { default: { ...DEFAULT_RULE }, namespaces: {}, enabled: false };
+    return { default: { ...DEFAULT_RULE }, namespaces: /* @__PURE__ */ Object.create(null), enabled: false };
   }
   if (!isPlainObject2(options)) {
     invalidConfig("writePathPolicy", "must be an object");
   }
   const typedOptions = options;
-  const defaultRule = normalizeRule(typedOptions.default, "writePathPolicy.default");
-  const namespacesInput = options.namespaces;
-  const namespaces = {};
+  const defaultRule = normalizeRule(ownValue(typedOptions, "default"), "writePathPolicy.default");
+  const namespacesInput = ownValue(options, "namespaces");
+  const namespaces = /* @__PURE__ */ Object.create(null);
   if (namespacesInput !== void 0) {
     if (!isPlainObject2(namespacesInput)) {
       invalidConfig("writePathPolicy.namespaces", "must be an object");
@@ -3209,8 +3348,8 @@ function resolveWritePathRule(policy, namespace) {
     if (candidate === "default") {
       return { key: "default", rule: effectivePolicy.default };
     }
-    const rule = effectivePolicy.namespaces[candidate];
-    if (rule) {
+    if (Object.prototype.hasOwnProperty.call(effectivePolicy.namespaces, candidate)) {
+      const rule = effectivePolicy.namespaces[candidate];
       return { key: candidate, rule };
     }
   }
@@ -3353,16 +3492,17 @@ var fallbackModelIndexTasks = /* @__PURE__ */ new Map();
 function toCompatDefinition(definition) {
   return definition;
 }
-function stableIndexStringify(value) {
+function stableIndexStringify(value, mode = "options") {
   if (value instanceof Date) {
     return JSON.stringify(value.toISOString());
   }
   if (Array.isArray(value)) {
-    return `[${value.map((item) => stableIndexStringify(item)).join(",")}]`;
+    return `[${value.map((item) => stableIndexStringify(item, mode)).join(",")}]`;
   }
   if (value && typeof value === "object") {
-    const entries = Object.entries(value).filter(([, current]) => current !== void 0).sort(([left], [right]) => left.localeCompare(right));
-    return `{${entries.map(([key, current]) => `${JSON.stringify(key)}:${stableIndexStringify(current)}`).join(",")}}`;
+    const entries = Object.entries(value).filter(([, current]) => current !== void 0);
+    if (mode === "options") entries.sort(([left], [right]) => left.localeCompare(right));
+    return `{${entries.map(([key, current]) => `${JSON.stringify(key)}:${stableIndexStringify(current, key === "key" ? "key" : mode)}`).join(",")}}`;
   }
   return JSON.stringify(value) ?? "undefined";
 }
@@ -3396,7 +3536,7 @@ function declaredOptionEntries(options) {
   });
 }
 function indexOptionsMatch(existing, declared) {
-  if (stableIndexStringify(getExistingIndexKey(existing)) !== stableIndexStringify(declared.key)) {
+  if (stableIndexStringify(getExistingIndexKey(existing), "key") !== stableIndexStringify(declared.key, "key")) {
     return false;
   }
   for (const [name, value] of declaredOptionEntries(declared.options)) {
@@ -3415,8 +3555,8 @@ function findExistingIndexByName(existingIndexes, name) {
   return existingIndexes.find((index) => index.name === name);
 }
 function findExistingIndexByKey(existingIndexes, key) {
-  const fingerprint = stableIndexStringify(key);
-  return existingIndexes.find((index) => stableIndexStringify(getExistingIndexKey(index)) === fingerprint);
+  const fingerprint = stableIndexStringify(key, "key");
+  return existingIndexes.find((index) => stableIndexStringify(getExistingIndexKey(index), "key") === fingerprint);
 }
 function createIndexEnsureError(message, result, cause) {
   return createError(ErrorCodes.MONGODB_ERROR, message, [result], cause);
@@ -4156,7 +4296,7 @@ async function readNearestBookmark(cache, namespace, keyDims, targetPage) {
 
 // src/adapters/mongodb/queries/query-helpers.ts
 import { createHmac, timingSafeEqual } from "node:crypto";
-import { ObjectId as ObjectId2 } from "mongodb";
+import { BSON, ObjectId as ObjectId2 } from "mongodb";
 
 // src/utils/normalize.ts
 function normalizeProjection(p) {
@@ -4254,12 +4394,17 @@ function shouldConvertQueryField(autoConvert, path5, depth) {
   if (!config.enabled || depth > config.maxDepth) return false;
   return shouldConvertObjectIdPath(path5, config);
 }
+function isPlainQueryRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
 function normalizeQueryArray(value, autoConvert, path5, depth) {
   return value.map((item, index) => {
     if (typeof item === "string" && item.length === 24 && ObjectId2.isValid(item) && shouldConvertQueryField(autoConvert, path5, depth)) {
       return new ObjectId2(item);
     }
-    if (item && typeof item === "object" && !Array.isArray(item) && !(item instanceof ObjectId2)) {
+    if (isPlainQueryRecord(item)) {
       return normalizeQueryFilter(item, autoConvert, `${path5}[${index}]`, depth + 1);
     }
     return item;
@@ -4275,7 +4420,7 @@ function normalizeQueryFilter(filter, autoConvert, fieldPath = "", depth = 0) {
   }
   for (const [key, value] of Object.entries(filter)) {
     if (key === "$and" || key === "$or" || key === "$nor") {
-      result[key] = Array.isArray(value) ? value.map((item) => item && typeof item === "object" ? normalizeQueryFilter(item, autoConvert, fieldPath, depth + 1) : item) : value;
+      result[key] = Array.isArray(value) ? value.map((item) => isPlainQueryRecord(item) ? normalizeQueryFilter(item, autoConvert, fieldPath, depth + 1) : item) : value;
       continue;
     }
     const currentPath = fieldPath ? `${fieldPath}.${key}` : key;
@@ -4284,7 +4429,7 @@ function normalizeQueryFilter(filter, autoConvert, fieldPath = "", depth = 0) {
       result[key] = shouldConvert ? new ObjectId2(value) : value;
     } else if (Array.isArray(value)) {
       result[key] = shouldConvert ? normalizeQueryArray(value, autoConvert, currentPath, depth + 1) : value;
-    } else if (value && typeof value === "object" && !Array.isArray(value) && !(value instanceof ObjectId2)) {
+    } else if (isPlainQueryRecord(value)) {
       const nested = value;
       const hasOperators = Object.keys(nested).some((k) => k.startsWith("$"));
       if (hasOperators) {
@@ -4296,7 +4441,7 @@ function normalizeQueryFilter(filter, autoConvert, fieldPath = "", depth = 0) {
             );
           } else if (shouldConvert && QUERY_OBJECTID_SCALAR_OPERATORS.has(op) && typeof opVal === "string" && opVal.length === 24 && ObjectId2.isValid(opVal)) {
             nestedResult[op] = new ObjectId2(opVal);
-          } else if (op === "$elemMatch" && opVal && typeof opVal === "object" && !Array.isArray(opVal)) {
+          } else if (op === "$elemMatch" && isPlainQueryRecord(opVal)) {
             nestedResult[op] = normalizeQueryFilter(opVal, autoConvert, currentPath, depth + 1);
           } else {
             nestedResult[op] = opVal;
@@ -4470,36 +4615,29 @@ async function isCollectionCacheBarrierActive(queryCache, collection, defaults =
     buildCollectionCacheBarrierNamespaces(collection, defaults)
   );
 }
-function normalizeCacheKeyValue(value) {
-  if (value === void 0 || typeof value === "function" || typeof value === "symbol") {
-    return void 0;
-  }
-  if (value instanceof Date) {
-    return { $date: value.toISOString() };
-  }
-  if (value instanceof ObjectId2) {
-    return { $oid: value.toHexString() };
-  }
-  if (value instanceof RegExp) {
-    return { $regex: value.source, $flags: value.flags };
-  }
-  if (Array.isArray(value)) {
-    return value.map((item) => normalizeCacheKeyValue(item));
-  }
-  if (value && typeof value === "object") {
-    const sorted = {};
-    for (const key of Object.keys(value).sort()) {
-      const normalized = normalizeCacheKeyValue(value[key]);
-      if (normalized !== void 0) {
-        sorted[key] = normalized;
-      }
-    }
-    return sorted;
-  }
-  return value;
-}
-function stableCacheKeyString(value) {
-  return JSON.stringify(normalizeCacheKeyValue(value));
+var ORDERED_OPTION_FIELDS = /* @__PURE__ */ new Set(["query", "filter", "pipeline", "sort", "hint", "projection", "min", "max"]);
+function normalizeCacheKeyValue(value, mode) {
+  if (value === null) return ["null"];
+  if (value === void 0) return ["undefined"];
+  if (typeof value === "number") return ["number", String(value)];
+  if (typeof value === "bigint") return ["bigint", value.toString()];
+  if (typeof value !== "object") return [typeof value, value];
+  if (value instanceof Date) return ["date", String(value.getTime())];
+  if (value instanceof RegExp) return ["regexp", value.source, value.flags];
+  if (Array.isArray(value)) return ["array", value.map((item) => normalizeCacheKeyValue(item, mode))];
+  const bsonType = value._bsontype;
+  if (typeof bsonType === "string") {
+    return ["bson", bsonType, BSON.EJSON.serialize(value, { relaxed: false })];
+  }
+  const entries = Object.entries(value).filter(([, item]) => item !== void 0 && typeof item !== "function" && typeof item !== "symbol");
+  if (mode === "options") entries.sort(([left], [right]) => left.localeCompare(right));
+  return ["object", entries.map(([key, item]) => [
+    key,
+    normalizeCacheKeyValue(item, mode === "options" && ORDERED_OPTION_FIELDS.has(key) ? "document" : mode)
+  ])];
+}
+function stableCacheKeyString(value, mode = "options") {
+  return `v2:${JSON.stringify(normalizeCacheKeyValue(value, mode))}`;
 }
 function buildResultCacheKeyOptions(options = {}) {
   const keyOptions = {};
@@ -4620,7 +4758,7 @@ function buildFindCacheKey(collection, defaults = {}, query, options) {
     ...options ?? {}
   });
   const namespace = buildCollectionCacheNamespace(collection, defaults);
-  return `find:${namespace}:${stableCacheKeyString(normalizeQueryForCache(query, defaults))}:${stableCacheKeyString(buildResultCacheKeyOptions(executeOptions))}`;
+  return `find:${namespace}:${stableCacheKeyString(normalizeQueryForCache(query, defaults), "document")}:${stableCacheKeyString(buildResultCacheKeyOptions(executeOptions))}`;
 }
 function buildFindOneCacheKey(collection, defaults = {}, query, options) {
   const executeOptions = normalizeFindProjectionOptions({
@@ -4628,7 +4766,7 @@ function buildFindOneCacheKey(collection, defaults = {}, query, options) {
     ...options ?? {}
   });
   const namespace = buildCollectionCacheNamespace(collection, defaults);
-  return `findOne:${namespace}:${stableCacheKeyString(normalizeQueryForCache(query, defaults))}:${stableCacheKeyString(buildResultCacheKeyOptions(executeOptions))}`;
+  return `findOne:${namespace}:${stableCacheKeyString(normalizeQueryForCache(query, defaults), "document")}:${stableCacheKeyString(buildResultCacheKeyOptions(executeOptions))}`;
 }
 function buildCountCacheKey(collection, defaults = {}, query, options) {
   const merged = {
@@ -4638,7 +4776,7 @@ function buildCountCacheKey(collection, defaults = {}, query, options) {
   const { cache: _cache, ...keyOptions } = merged;
   void _cache;
   const namespace = buildCollectionCacheNamespace(collection, defaults);
-  return `count:${namespace}:${stableCacheKeyString(normalizeQueryForCache(query, defaults))}:${stableCacheKeyString(buildResultCacheKeyOptions(keyOptions))}`;
+  return `count:${namespace}:${stableCacheKeyString(normalizeQueryForCache(query, defaults), "document")}:${stableCacheKeyString(buildResultCacheKeyOptions(keyOptions))}`;
 }
 function buildDistinctCacheKey(collection, defaults = {}, field, query, options) {
   const rawOptions = options ?? {};
@@ -4668,7 +4806,7 @@ function buildAggregateCacheKey(collection, defaults = {}, pipeline, options) {
     ...options ?? {}
   };
   const namespace = buildCollectionCacheNamespace(collection, defaults);
-  return `aggregate:${namespace}:${stableCacheKeyString(normalizePipelineForCache(pipeline, defaults))}:${stableCacheKeyString(buildResultCacheKeyOptions(executeOptions))}`;
+  return `aggregate:${namespace}:${stableCacheKeyString(normalizePipelineForCache(pipeline, defaults), "document")}:${stableCacheKeyString(buildResultCacheKeyOptions(executeOptions))}`;
 }
 function buildFindOneByIdCacheKey(collection, defaults = {}, id, options) {
   const objectId = parseRequiredObjectId(id);
@@ -4683,6 +4821,8 @@ function buildFindByIdsCacheKey(collection, defaults = {}, ids, options) {
 function buildFindPageCacheKey(collection, defaults = {}, options = {}) {
   const ext = options;
   const cursorTypes = ext.cursorTypes && typeof ext.cursorTypes === "object" && !Array.isArray(ext.cursorTypes) ? ext.cursorTypes : void 0;
+  const { let: nestedLet, ...nestedOptions } = options.options ?? {};
+  const effectiveLet = ext.let !== void 0 ? ext.let : nestedLet;
   const payload = {
     query: normalizeQueryForCache(options.query, defaults),
     sort: normalizeSortShape(options.sort),
@@ -4704,9 +4844,10 @@ function buildFindPageCacheKey(collection, defaults = {}, options = {}) {
     hint: ext.hint,
     collation: ext.collation,
     batchSize: ext.batchSize,
-    options: options.options
+    let: effectiveLet,
+    options: nestedOptions
   };
-  const keyHash = hashPayload(payload);
+  const keyHash = hashPayload(stableCacheKeyString(payload));
   const namespace = buildCollectionCacheNamespace(collection, defaults);
   return { key: `findPage:${namespace}:${keyHash}`, keyHash };
 }
@@ -5053,29 +5194,30 @@ async function runStrictUpdateMany(context, filter, update, options) {
   if (rawOptions.upsert === true) {
     throw createError(ErrorCodes.INVALID_ARGUMENT, 'versionMode "strict" does not support upsert.');
   }
-  const docs = await context.collection.find(filter, {
-    ...buildModelVersionLookupOptions(rawOptions, {
-      _id: 1,
-      [context.versionConfig.field]: 1
-    })
-  });
   let matchedCount = 0;
   let modifiedCount = 0;
   const conflictedIds = [];
-  for (const doc of docs) {
-    const id = doc._id;
-    const expectedVersion = assertNumericExpectedVersion(doc[context.versionConfig.field], "updateMany");
-    const result = await context.collection.updateOne(
-      { _id: id, [context.versionConfig.field]: expectedVersion },
-      update,
-      options
-    );
-    if ((result?.matchedCount ?? 0) === 0) {
-      conflictedIds.push(id);
-      continue;
+  const skippedIds = [];
+  for await (const batch of iterateModelCandidateBatches(context, filter, rawOptions, 200)) {
+    for (const doc of batch) {
+      const id = doc._id;
+      const expectedVersion = assertNumericExpectedVersion(doc[context.versionConfig.field], "updateMany");
+      const result = await context.collection.updateOne(
+        buildStrictCandidateFilter(filter, id, context.versionConfig.field, expectedVersion),
+        update,
+        options
+      );
+      if ((result?.matchedCount ?? 0) === 0) {
+        if (await isModelVersionConflict(context, filter, id, context.versionConfig.field, expectedVersion, options)) {
+          conflictedIds.push(id);
+        } else {
+          skippedIds.push(id);
+        }
+        continue;
+      }
+      matchedCount += result.matchedCount ?? 0;
+      modifiedCount += result.modifiedCount ?? 0;
     }
-    matchedCount += result.matchedCount ?? 0;
-    modifiedCount += result.modifiedCount ?? 0;
   }
   return {
     acknowledged: true,
@@ -5084,7 +5226,9 @@ async function runStrictUpdateMany(context, filter, update, options) {
     upsertedCount: 0,
     upsertedId: null,
     conflictCount: conflictedIds.length,
-    conflictedIds
+    conflictedIds,
+    skippedCount: skippedIds.length,
+    skippedIds
   };
 }
 async function runStrictUpdateBatch(context, filter, update, options) {
@@ -5107,7 +5251,7 @@ async function runStrictUpdateBatch(context, filter, update, options) {
     retryAttempts: _retryAttempts,
     retryDelay: _retryDelay,
     onRetry: _onRetry,
-    sort = { _id: 1 },
+    sort: _sort,
     ...driverOptions
   } = rawOptions;
   void _batchSize;
@@ -5116,38 +5260,42 @@ async function runStrictUpdateBatch(context, filter, update, options) {
   void _retryAttempts;
   void _retryDelay;
   void _onRetry;
-  const docs = await context.collection.find(filter, {
-    ...buildModelVersionLookupOptions(driverOptions, {
-      _id: 1,
-      [context.versionConfig.field]: 1
-    }),
-    sort
-  });
+  void _sort;
+  const countOptions = buildModelVersionLookupOptions(driverOptions, {});
+  delete countOptions.projection;
+  const totalCount = await context.collection.count(filter, countOptions);
   const result = {
     acknowledged: true,
-    totalCount: docs.length,
+    totalCount,
     matchedCount: 0,
     modifiedCount: 0,
     upsertedCount: 0,
-    batchCount: Math.ceil(docs.length / batchSize),
+    batchCount: 0,
     errors: [],
     retries: [],
     conflictCount: 0,
-    conflictedIds: []
+    conflictedIds: [],
+    skippedCount: 0,
+    skippedIds: []
   };
-  for (let offset = 0; offset < docs.length; offset += batchSize) {
-    const batch = docs.slice(offset, offset + batchSize);
+  for await (const batch of iterateModelCandidateBatches(context, filter, driverOptions, batchSize)) {
+    result.batchCount++;
     for (const doc of batch) {
       const id = doc._id;
       const expectedVersion = assertNumericExpectedVersion(doc[context.versionConfig.field], "updateBatch");
       const updateResult = await context.collection.updateOne(
-        { _id: id, [context.versionConfig.field]: expectedVersion },
+        buildStrictCandidateFilter(filter, id, context.versionConfig.field, expectedVersion),
         update,
         driverOptions
       );
       if ((updateResult?.matchedCount ?? 0) === 0) {
-        result.conflictCount = (result.conflictCount ?? 0) + 1;
-        result.conflictedIds?.push(id);
+        if (await isModelVersionConflict(context, filter, id, context.versionConfig.field, expectedVersion, driverOptions)) {
+          result.conflictCount = (result.conflictCount ?? 0) + 1;
+          result.conflictedIds?.push(id);
+        } else {
+          result.skippedCount = (result.skippedCount ?? 0) + 1;
+          result.skippedIds?.push(id);
+        }
         continue;
       }
       result.matchedCount += updateResult.matchedCount ?? 0;
@@ -5155,15 +5303,16 @@ async function runStrictUpdateBatch(context, filter, update, options) {
     }
     if (typeof onProgress === "function") {
       onProgress({
-        currentBatch: Math.floor(offset / batchSize) + 1,
-        totalBatches: result.batchCount,
+        currentBatch: result.batchCount,
+        totalBatches: Math.ceil(totalCount / batchSize),
         modified: result.modifiedCount,
         matched: result.matchedCount,
-        total: docs.length,
-        percentage: docs.length > 0 ? Math.round(result.modifiedCount / docs.length * 100) : null,
+        total: totalCount,
+        percentage: totalCount > 0 ? Math.round(result.modifiedCount / totalCount * 100) : null,
         errors: result.errors.length,
         retries: result.retries.length,
-        conflicts: result.conflictCount ?? 0
+        conflicts: result.conflictCount ?? 0,
+        skipped: result.skippedCount ?? 0
       });
     }
   }
@@ -5176,10 +5325,7 @@ function buildSoftDeletePatch(config, now) {
   return { [config.field]: config.type === "boolean" ? true : now };
 }
 function buildSoftDeleteFilter(filter, config) {
-  return {
-    ...filter ?? {},
-    ...config?.enabled ? { [config.field]: null } : {}
-  };
+  return applyModelSoftDeleteFilter(filter, {}, config);
 }
 function applyModelIncrementVersion(field, increment, versionConfig) {
   if (!versionConfig?.enabled || field === void 0) {
@@ -5219,7 +5365,8 @@ async function orchestrateModelInsertOne(context, document, options) {
   payload = validateModelSchemaPayload({
     validateEnabled: context.validateEnabled,
     schemaCache: context.schemaCache,
-    schemaValidateFn: context.schemaValidateFn
+    schemaValidateFn: context.schemaValidateFn,
+    schemaError: context.schemaError
   }, payload, options);
   payload = applyModelInsertTimestamps(payload, context.timestampsConfig, () => context.nowDate());
   payload = applyModelInsertVersion(payload, context.versionConfig);
@@ -5253,7 +5400,8 @@ async function orchestrateModelInsertMany(context, documents, options) {
     doc = validateModelSchemaPayload({
       validateEnabled: context.validateEnabled,
       schemaCache: context.schemaCache,
-      schemaValidateFn: context.schemaValidateFn
+      schemaValidateFn: context.schemaValidateFn,
+      schemaError: context.schemaError
     }, doc, resolvedOptions, { index });
     doc = applyModelInsertTimestamps(doc, context.timestampsConfig, () => context.nowDate());
     doc = applyModelInsertVersion(doc, context.versionConfig);
@@ -5338,7 +5486,8 @@ async function orchestrateModelReplaceOne(context, filter, replacement, options)
   let nextReplacement = validateModelSchemaPayload({
     validateEnabled: context.validateEnabled,
     schemaCache: context.schemaCache,
-    schemaValidateFn: context.schemaValidateFn
+    schemaValidateFn: context.schemaValidateFn,
+    schemaError: context.schemaError
   }, replacement, options);
   nextReplacement = preserveModelReplaceCreatedAt(
     replacement,
@@ -5397,7 +5546,8 @@ async function orchestrateModelFindOneAndReplace(context, filter, replacement, o
   let nextReplacement = validateModelSchemaPayload({
     validateEnabled: context.validateEnabled,
     schemaCache: context.schemaCache,
-    schemaValidateFn: context.schemaValidateFn
+    schemaValidateFn: context.schemaValidateFn,
+    schemaError: context.schemaError
   }, replacement, options);
   nextReplacement = preserveModelReplaceCreatedAt(
     replacement,
@@ -5509,7 +5659,8 @@ async function orchestrateModelInsertBatch(context, docs, options) {
     record = validateModelSchemaPayload({
       validateEnabled: context.validateEnabled,
       schemaCache: context.schemaCache,
-      schemaValidateFn: context.schemaValidateFn
+      schemaValidateFn: context.schemaValidateFn,
+      schemaError: context.schemaError
     }, record, resolvedOptions, { index });
     record = applyModelInsertTimestamps(record, context.timestampsConfig, () => context.nowDate());
     record = applyModelInsertVersion(record, context.versionConfig);
@@ -5587,7 +5738,7 @@ async function orchestrateModelDeleteOne(context, filter, options) {
   let result;
   if (softDeleteConfig?.enabled && !resolvedOptions._forceDelete) {
     result = await context.collection.updateOne(
-      { ...filter ?? {}, [softDeleteConfig.field]: null },
+      buildSoftDeleteFilter(filter, softDeleteConfig),
       { $set: { [softDeleteConfig.field]: softDeleteConfig.type === "boolean" ? true : context.nowDate() } },
       options
     );
@@ -5621,7 +5772,7 @@ async function orchestrateModelDeleteMany(context, filter, options) {
   let result;
   if (softDeleteConfig?.enabled && !resolvedOptions._forceDelete) {
     result = await context.collection.updateMany(
-      { ...filter ?? {}, [softDeleteConfig.field]: null },
+      { $and: [filter ?? {}, buildModelVisibleSoftDeleteCondition(softDeleteConfig)] },
       { $set: { [softDeleteConfig.field]: softDeleteConfig.type === "boolean" ? true : context.nowDate() } },
       options
     );
@@ -5785,7 +5936,7 @@ async function inspectDeclaredRelationUsage(context, targets, inputOptions, targ
       [inbound.localField]: { $in: targetValues }
     };
     const sourceSoftDelete = resolveModelSoftDeleteConfig(inbound.definition);
-    const query = !options.includeSoftDeletedReferences && sourceSoftDelete?.enabled ? { $and: [baseQuery, { [sourceSoftDelete.field]: null }] } : baseQuery;
+    const query = !options.includeSoftDeletedReferences && sourceSoftDelete?.enabled ? { $and: [baseQuery, buildModelVisibleSoftDeleteCondition(sourceSoftDelete)] } : baseQuery;
     try {
       const collection = context.runtime.scopedCollection(inbound.sourceCollection, scope);
       if (!collection) {
@@ -5967,7 +6118,7 @@ async function executeProtectedRelationDelete(host, filter, options, force) {
   const deleteOptions = stripRelationUsageOptions(options);
   let target;
   try {
-    const targetFilter = force || !host.softDeleteConfig?.enabled ? filter : { ...filter, [host.softDeleteConfig.field]: null };
+    const targetFilter = force || !host.softDeleteConfig?.enabled ? filter : applyModelSoftDeleteFilter(filter, void 0, host.softDeleteConfig);
     const rawTarget = await host.collection.findOne(
       targetFilter,
       relationTargetReadOptions(options, buildRelationUsageTargetProjection(host.modelName))
@@ -6051,7 +6202,7 @@ var ModelInstance = class {
     this.softDeleteConfig = this._softDeleteConfig;
     this._versionConfig = resolveModelVersionConfig(options.definition);
     this._v1HooksFactory = resolveModelHooksFactory(options.definition);
-    scheduleModelIndexes(this.collection, options.definition, this._softDeleteConfig, {
+    if (!this._schemaError) scheduleModelIndexes(this.collection, options.definition, this._softDeleteConfig, {
       runtime: this.runtime,
       dbName: options.dbName,
       poolName: options.poolName,
@@ -6111,46 +6262,6 @@ var ModelInstance = class {
     }
     return result;
   }
-  isVisibleBySoftDelete(doc, options) {
-    if (!doc || !this._softDeleteConfig?.enabled) {
-      return Boolean(doc);
-    }
-    const rawOptions = options ?? {};
-    if (rawOptions.withDeleted) {
-      return true;
-    }
-    const value = doc[this._softDeleteConfig.field];
-    if (rawOptions.onlyDeleted) {
-      return value !== void 0 && value !== null;
-    }
-    return value === void 0 || value === null;
-  }
-  filterVisibleBySoftDelete(docs, options) {
-    return docs.filter((doc) => this.isVisibleBySoftDelete(doc, options));
-  }
-  applySoftDeleteFindPageOptions(options) {
-    const rawOptions = options ?? {};
-    return {
-      ...rawOptions,
-      query: applyModelSoftDeleteFilter(rawOptions.query, rawOptions, this._softDeleteConfig)
-    };
-  }
-  applySoftDeleteAggregatePipeline(pipeline, options) {
-    if (!this._softDeleteConfig?.enabled) {
-      return pipeline ?? [];
-    }
-    const rawOptions = options ?? {};
-    if (rawOptions.withDeleted) {
-      return pipeline ?? [];
-    }
-    const softDeleteMatch = applyModelSoftDeleteFilter({}, rawOptions, this._softDeleteConfig);
-    const matchStage = { $match: softDeleteMatch };
-    const stages = [...pipeline ?? []];
-    if (stages.length > 0 && stages[0] && typeof stages[0] === "object" && "$geoNear" in stages[0]) {
-      return [stages[0], matchStage, ...stages.slice(1)];
-    }
-    return [matchStage, ...stages];
-  }
   // ── public API ────────────────────────────────────────────────────────────────
   find(query, options) {
     return new PopulatePromise(async (paths) => {
@@ -6186,8 +6297,12 @@ var ModelInstance = class {
   }
   findOneById(id, options) {
     return new PopulatePromise(async (paths) => {
-      const doc = this._v1HooksFactory ? await this.runV1HookedOperation("find", [id, options], (nextId, nextOptions) => this.collection.findOneById(nextId, nextOptions)) : await this.collection.findOneById(id, options);
-      return this.populateSingle(this.hydrateDocument(this.isVisibleBySoftDelete(doc, options) ? doc : null), paths);
+      const lookupById = (nextId, nextOptions) => this._softDeleteConfig?.enabled ? this.collection.findOne(
+        applyModelSoftDeleteFilter({ _id: parseRequiredObjectId(nextId) }, nextOptions, this._softDeleteConfig),
+        nextOptions
+      ) : this.collection.findOneById(nextId, nextOptions);
+      const doc = this._v1HooksFactory ? await this.runV1HookedOperation("find", [id, options], lookupById) : await lookupById(id, options);
+      return this.populateSingle(this.hydrateDocument(doc), paths);
     });
   }
   findById(id, options) {
@@ -6195,13 +6310,25 @@ var ModelInstance = class {
   }
   findByIds(ids, options) {
     return new PopulatePromise(async (paths) => {
-      const docs = this._v1HooksFactory ? await this.runV1HookedOperation("find", [ids, options], (nextIds, nextOptions) => this.collection.findByIds(nextIds, nextOptions)) : await this.collection.findByIds(ids, options);
-      return this.populateDocuments(this.hydrateDocuments(this.filterVisibleBySoftDelete(docs, options)), paths);
+      let stripField = false;
+      const lookupByIds = (nextIds, nextOptions) => {
+        const projection = withSoftDeleteProjection(nextOptions, this._softDeleteConfig);
+        stripField = projection.stripField;
+        return this.collection.findByIds(nextIds, projection.options);
+      };
+      const docs = this._v1HooksFactory ? await this.runV1HookedOperation("find", [ids, options], lookupByIds) : await lookupByIds(ids, options);
+      const visible = filterVisibleBySoftDelete(docs, options, this._softDeleteConfig);
+      const projected = stripField && this._softDeleteConfig ? visible.map((doc) => {
+        const copy = { ...doc };
+        delete copy[this._softDeleteConfig.field];
+        return copy;
+      }) : visible;
+      return this.populateDocuments(this.hydrateDocuments(projected), paths);
     });
   }
   findPage(options) {
     return new PopulatePromise(async (paths) => {
-      const filteredOptions = this.applySoftDeleteFindPageOptions(options);
+      const filteredOptions = applySoftDeleteFindPageOptions(options, this._softDeleteConfig);
       const result = this._v1HooksFactory ? await this.runV1HookedOperation("find", [filteredOptions], (nextOptions) => this.collection.findPage(nextOptions)) : await this.collection.findPage(filteredOptions);
       return {
         ...result,
@@ -6353,7 +6480,7 @@ var ModelInstance = class {
     return this.runV1HookedOperation("find", [key, filteredQuery, options], (nextKey, nextQuery, nextOptions) => this.collection.distinct(nextKey, nextQuery, nextOptions));
   }
   aggregate(pipeline, options) {
-    const filteredPipeline = this.applySoftDeleteAggregatePipeline(pipeline, options);
+    const filteredPipeline = applySoftDeleteAggregatePipeline(pipeline, options, this._softDeleteConfig);
     return this.runV1HookedOperation("find", [filteredPipeline, options], (nextPipeline, nextOptions) => {
       const execute = () => this.collection.aggregate(nextPipeline, nextOptions);
       if (resolveAggregateWriteTarget(Array.isArray(nextPipeline) ? nextPipeline : [])) {
@@ -6482,13 +6609,14 @@ var ModelInstance = class {
       schemaValidationContext: {
         validateEnabled: this._validateEnabled,
         schemaCache: this._schemaCache,
-        schemaValidateFn: this._schemaValidateFn
+        schemaValidateFn: this._schemaValidateFn,
+        schemaError: this._schemaError
       },
       nowFactory: () => this.nowDate()
     }));
   }
   async removeDocument(document) {
-    return this.runModelWrite(() => removeModelDocument(this.collection, document));
+    return this.runModelWrite(() => removeModelDocument(this.collection, document, (filter) => this.deleteOne(filter)));
   }
   applyDefaults(document) {
     return applyModelDefaults(this.definition, document);
@@ -6506,6 +6634,7 @@ var ModelInstance = class {
       validateEnabled: this._validateEnabled,
       schemaCache: this._schemaCache,
       schemaValidateFn: this._schemaValidateFn,
+      schemaError: this._schemaError,
       hooksFactory: this._v1HooksFactory,
       runHook: (hookName, context) => this.runHook(hookName, context)
     };
@@ -6521,6 +6650,11 @@ var ModelInstance = class {
 
 // src/capabilities/transaction/index.ts
 import { randomBytes as randomBytes2 } from "node:crypto";
+function assertManagedTransactionWriteAllowed(options) {
+  const session = options?.session;
+  const managed = session?.__monSQLizeTransaction;
+  if (typeof managed?.assertAcceptingWrites === "function") managed.assertAcceptingWrites();
+}
 function toPublicTransactionStatus(state) {
   return state === "active" ? "started" : state;
 }
@@ -6621,6 +6755,7 @@ var Transaction = class {
     this.options = options;
     this.id = `tx_${randomBytes2(8).toString("hex")}`;
     this.state = "pending";
+    this.acceptingWrites = false;
     this.startedAt = null;
     this.timeoutTimer = null;
     this.pendingInvalidations = /* @__PURE__ */ new Set();
@@ -6639,6 +6774,7 @@ var Transaction = class {
     }
     this.session.startTransaction(this.options.transactionOptions);
     this.state = "active";
+    this.acceptingWrites = true;
     this.startedAt = Date.now();
     const timeout = this.options.timeout ?? 3e4;
     if (timeout > 0) {
@@ -6661,6 +6797,7 @@ var Transaction = class {
     if (this.state !== "active") {
       throw createError(ErrorCodes.INVALID_OPERATION, `Cannot commit transaction in state: ${this.state}`);
     }
+    this.acceptingWrites = false;
     if (typeof this.session.commitTransaction === "function") {
       await commitTransactionWithRetry(this.session, this.options.logger);
     }
@@ -6686,6 +6823,7 @@ var Transaction = class {
    * @since v1.4.0
    */
   async abort() {
+    this.acceptingWrites = false;
     if (this.state !== "pending" && this.state !== "active") {
       return;
     }
@@ -6710,10 +6848,16 @@ var Transaction = class {
    * @since v1.4.0
    */
   async end() {
+    this.acceptingWrites = false;
     this.clearTimeout();
     this.options.lockManager?.releaseLocks(this.id);
     await this.session.endSession();
   }
+  assertAcceptingWrites() {
+    if (this.state !== "active" || !this.acceptingWrites) {
+      throw createError(ErrorCodes.INVALID_OPERATION, `Managed transaction ${this.id} is no longer accepting writes.`);
+    }
+  }
   /**
    * Record a cache invalidation intent.
    * @since v1.4.0
@@ -6887,12 +7031,12 @@ var TransactionManager = class {
         return result;
       } catch (error) {
         lastError = error;
-        await transaction.abort();
-        this.recordStats(transaction, Date.now() - startedAt, false);
         if (transaction.state === "committed") {
           throw error;
         }
-        if (!enableRetry || attempt === maxRetries || !isTransientTransactionError(error)) {
+        await transaction.abort();
+        this.recordStats(transaction, Date.now() - startedAt, false);
+        if (!enableRetry || attempt === maxRetries || isUnknownTransactionCommitResult(error) || !isTransientTransactionError(error)) {
           throw error;
         }
         await sleep(retryDelay * Math.pow(retryBackoff, attempt));
@@ -6993,22 +7137,34 @@ function stringifySessionId(id) {
   }
   return String(id);
 }
-function isTransientTransactionError(error) {
-  if (!error || typeof error !== "object") {
-    return false;
-  }
-  const candidate = error;
-  if (typeof candidate.hasErrorLabel === "function" && candidate.hasErrorLabel("TransientTransactionError")) {
-    return true;
+function transactionErrorChain(error) {
+  const chain = [];
+  const seen = /* @__PURE__ */ new Set();
+  let current = error;
+  while (current && typeof current === "object" && chain.length < 8 && !seen.has(current)) {
+    seen.add(current);
+    const candidate = current;
+    chain.push(candidate);
+    current = candidate.cause;
+  }
+  return chain;
+}
+function hasTransactionErrorLabel(candidate, label) {
+  if (Array.isArray(candidate.errorLabels) && candidate.errorLabels.includes(label)) return true;
+  if (typeof candidate.hasErrorLabel === "function") {
+    try {
+      return Boolean(candidate.hasErrorLabel.call(candidate, label));
+    } catch {
+    }
   }
-  return candidate.code === 112 || candidate.code === 117;
+  return false;
 }
 function isUnknownTransactionCommitResult(error) {
-  if (!error || typeof error !== "object") {
-    return false;
-  }
-  const candidate = error;
-  return typeof candidate.hasErrorLabel === "function" && candidate.hasErrorLabel("UnknownTransactionCommitResult");
+  return transactionErrorChain(error).some((candidate) => hasTransactionErrorLabel(candidate, "UnknownTransactionCommitResult"));
+}
+function isTransientTransactionError(error) {
+  if (isUnknownTransactionCommitResult(error)) return false;
+  return transactionErrorChain(error).some((candidate) => hasTransactionErrorLabel(candidate, "TransientTransactionError") || candidate.code === 112 || candidate.code === 117 || candidate.codeName === "WriteConflict" || candidate.codeName === "LockTimeout");
 }
 async function commitTransactionWithRetry(session, logger) {
   const maxAttempts = 3;
@@ -7524,26 +7680,27 @@ var CountQueue = class {
    * @returns The result of fn
    * @throws A controlled error when the queue is full or the wait times out
    */
-  async execute(fn) {
+  async execute(fn, options = {}) {
     const startTime = Date.now();
+    const signal = options.signal;
+    if (signal?.aborted) throw createError(ErrorCodes.INVALID_OPERATION, "Count operation aborted");
     if (this.running >= this.concurrency) {
       if (this.queue.length >= this.maxQueueSize) {
         this.stats.rejected += 1;
         throw createError(ErrorCodes.INVALID_OPERATION, `Count queue is full (${this.maxQueueSize})`);
       }
       this.stats.queued += 1;
-      await this._waitInQueue(startTime);
+      await this._waitInQueue(startTime, signal);
     }
+    if (signal?.aborted) throw createError(ErrorCodes.INVALID_OPERATION, "Count operation aborted");
     this.running += 1;
     this.stats.executed += 1;
-    try {
-      const elapsed = Date.now() - startTime;
-      const remainingMs = Math.max(1, this.timeout - elapsed);
-      return await this._executeWithTimeout(fn, remainingMs);
-    } finally {
+    const elapsed = Date.now() - startTime;
+    const remainingMs = Math.max(1, this.timeout - elapsed);
+    return this._executeWithTimeout(fn, remainingMs, signal, () => {
       this.running -= 1;
       this._wakeNext();
-    }
+    });
   }
   /**
    * Get queue statistics (including live state).
@@ -7578,17 +7735,28 @@ var CountQueue = class {
       const entry = this.queue.shift();
       if (entry) {
         clearTimeout(entry.timer);
+        entry.cleanup();
         entry.reject(createError(ErrorCodes.INVALID_OPERATION, "Count queue was cleared before execution"));
       }
     }
   }
-  _waitInQueue(startTime) {
+  _waitInQueue(startTime, signal) {
     return new Promise((resolve, reject) => {
       let entry;
+      const onAbort = () => {
+        const index = this.queue.indexOf(entry);
+        if (index !== -1) {
+          this.queue.splice(index, 1);
+          clearTimeout(entry.timer);
+          entry.cleanup();
+          reject(createError(ErrorCodes.INVALID_OPERATION, "Count operation aborted"));
+        }
+      };
       const timer = setTimeout(() => {
         const index = this.queue.indexOf(entry);
         if (index !== -1) {
           this.queue.splice(index, 1);
+          entry.cleanup();
           this.stats.timeout += 1;
           reject(createError(ErrorCodes.OPERATION_TIMEOUT, `Count queue wait timeout (${this.timeout}ms)`));
         }
@@ -7601,9 +7769,12 @@ var CountQueue = class {
         },
         reject,
         timer,
-        startTime
+        startTime,
+        cleanup: () => signal?.removeEventListener("abort", onAbort)
       };
       this.queue.push(entry);
+      signal?.addEventListener("abort", onAbort, { once: true });
+      if (signal?.aborted) onAbort();
     });
   }
   _wakeNext() {
@@ -7611,6 +7782,7 @@ var CountQueue = class {
       const entry = this.queue.shift();
       if (entry) {
         clearTimeout(entry.timer);
+        entry.cleanup();
         entry.resolve();
       }
     }
@@ -7627,10 +7799,12 @@ var CountQueue = class {
     }
     return value;
   }
-  _executeWithTimeout(fn, timeoutMs = this.timeout) {
+  _executeWithTimeout(fn, timeoutMs, signal, release) {
     let timer = null;
     const controller = new AbortController();
-    const timeoutPromise = new Promise((_, reject) => {
+    let rejectCancellation;
+    const cancellation = new Promise((_, reject) => {
+      rejectCancellation = reject;
       timer = setTimeout(
         () => {
           controller.abort();
@@ -7640,14 +7814,22 @@ var CountQueue = class {
         timeoutMs
       );
     });
+    const onAbort = () => {
+      controller.abort();
+      rejectCancellation(createError(ErrorCodes.INVALID_OPERATION, "Count operation aborted"));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
     let taskPromise;
     try {
       taskPromise = Promise.resolve(fn(controller.signal));
     } catch (error) {
       taskPromise = Promise.reject(error);
     }
-    return Promise.race([taskPromise, timeoutPromise]).finally(() => {
+    void taskPromise.then(release, release);
+    if (signal?.aborted) onAbort();
+    return Promise.race([taskPromise, cancellation]).finally(() => {
       if (timer !== null) clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
     });
   }
   _updateWaitTimeStats(waitTime) {
@@ -7660,6 +7842,7 @@ var CountQueue = class {
 };
 
 // src/capabilities/pool/pool-health-checker.ts
+var SILENT_HEALTH_CHECKER_LOGGER = {};
 var HealthChecker = class {
   constructor(options = {}) {
     this._healthStatus = /* @__PURE__ */ new Map();
@@ -7669,7 +7852,7 @@ var HealthChecker = class {
     this._inProgress = /* @__PURE__ */ new Set();
     this._started = false;
     this._poolManager = options.poolManager ?? null;
-    this._logger = options.logger ?? console;
+    this._logger = options.logger ?? SILENT_HEALTH_CHECKER_LOGGER;
   }
   register(poolNameOrConfig, configOrClient) {
     let poolName;
@@ -7793,6 +7976,7 @@ var HealthChecker = class {
 };
 
 // src/capabilities/pool/pool-selector.ts
+var SILENT_POOL_SELECTOR_LOGGER = {};
 var POOL_STRATEGY_ALIASES = {
   "round-robin": "roundRobin",
   "least-connections": "leastConnections",
@@ -7806,7 +7990,7 @@ var PoolSelector = class {
   constructor(options = {}) {
     this._roundRobinIndex = /* @__PURE__ */ new Map();
     this._strategy = normalizePoolStrategy(options.strategy);
-    this._logger = options.logger ?? console;
+    this._logger = options.logger ?? SILENT_POOL_SELECTOR_LOGGER;
   }
   select(pools, context) {
     if (!pools || pools.length === 0) {
@@ -7937,11 +8121,12 @@ var PoolSelector = class {
 };
 
 // src/capabilities/pool/pool-stats-manager.ts
+var SILENT_POOL_STATS_LOGGER = {};
 var PoolStatsManager = class {
   constructor(options = {}) {
     this._stats = /* @__PURE__ */ new Map();
     this._buffer = [];
-    this._logger = options.logger ?? console;
+    this._logger = options.logger ?? SILENT_POOL_STATS_LOGGER;
     this._batchInterval = setInterval(() => {
       this._flush();
     }, 100);
@@ -8173,6 +8358,9 @@ var ConnectionPoolManager = class {
     this._closed = false;
     this._configs = /* @__PURE__ */ new Map();
     this._pendingAdds = /* @__PURE__ */ new Set();
+    this._pendingAddTasks = /* @__PURE__ */ new Set();
+    this._generation = 0;
+    this._closePromise = null;
     this.logger = options.logger ?? null;
     this.maxPoolsCount = options.maxPoolsCount ?? 10;
     this.strategy = options.poolStrategy ?? "auto";
@@ -8189,9 +8377,9 @@ var ConnectionPoolManager = class {
     this._fallbackConfig = this.fallback;
     this._fallback = this.fallback;
     this._pools = this.pools;
-    this._selector = new PoolSelector({ strategy: this.strategy });
-    this._healthChecker = new HealthChecker({ poolManager: this });
-    this._stats = new PoolStatsManager({ logger: options.logger ?? void 0 });
+    this._selector = new PoolSelector({ strategy: this.strategy, logger: this.logger ?? void 0 });
+    this._healthChecker = new HealthChecker({ poolManager: this, logger: this.logger ?? void 0 });
+    this._stats = new PoolStatsManager({ logger: this.logger ?? void 0 });
   }
   /**
    * Add a connection pool.
@@ -8199,35 +8387,21 @@ var ConnectionPoolManager = class {
    */
   async addPool(config) {
     validatePoolConfig(config);
+    if (this._closed) {
+      throw createError(ErrorCodes.INVALID_OPERATION, "Connection pool manager is closed");
+    }
     if (this.pools.has(config.name) || this._pendingAdds.has(config.name)) {
       throw createError(ErrorCodes.INVALID_CONFIG, `Pool '${config.name}' already exists`);
     }
-    if (this.maxPoolsCount > 0 && this.pools.size >= this.maxPoolsCount) {
+    if (this.maxPoolsCount > 0 && this.pools.size + this._pendingAdds.size >= this.maxPoolsCount) {
       throw createError(ErrorCodes.INVALID_CONFIG, `Maximum pool count (${this.maxPoolsCount}) reached`);
     }
     this._pendingAdds.add(config.name);
+    const generation = this._generation;
+    const task = this._finishAddPool(config, generation);
+    this._pendingAddTasks.add(task);
     try {
-      const client = await this.clientFactory(config);
-      if (this.pools.has(config.name)) {
-        await client.close().catch(() => {
-        });
-        throw createError(ErrorCodes.INVALID_CONFIG, `Pool '${config.name}' already exists`);
-      }
-      this.pools.set(config.name, {
-        client,
-        config,
-        createdAt: Date.now()
-      });
-      this.healthStatus.set(config.name, {
-        status: "up",
-        consecutiveFailures: 0,
-        lastCheckTime: null,
-        lastError: null,
-        uptime: 0
-      });
-      this.stats.set(config.name, createEmptyPoolStats(config.name));
-      this._configs.set(config.name, config);
-      this._healthChecker.register(config.name, config.healthCheck ?? {});
+      await task;
     } catch (err) {
       const error = err;
       const msg = error.message ?? "";
@@ -8241,8 +8415,31 @@ var ConnectionPoolManager = class {
       throw err;
     } finally {
       this._pendingAdds.delete(config.name);
+      this._pendingAddTasks.delete(task);
     }
   }
+  async _finishAddPool(config, generation) {
+    const client = await this.clientFactory(config);
+    if (this._closed || generation !== this._generation || this.pools.has(config.name)) {
+      await client.close().catch(() => {
+      });
+      throw createError(
+        this._closed || generation !== this._generation ? ErrorCodes.INVALID_OPERATION : ErrorCodes.INVALID_CONFIG,
+        this._closed || generation !== this._generation ? "Connection pool manager closed while adding a pool" : `Pool '${config.name}' already exists`
+      );
+    }
+    this.pools.set(config.name, { client, config, createdAt: Date.now() });
+    this.healthStatus.set(config.name, {
+      status: "up",
+      consecutiveFailures: 0,
+      lastCheckTime: null,
+      lastError: null,
+      uptime: 0
+    });
+    this.stats.set(config.name, createEmptyPoolStats(config.name));
+    this._configs.set(config.name, config);
+    this._healthChecker.register(config.name, config.healthCheck ?? {});
+  }
   /**
    * Remove a connection pool.
    * @since v1.0.8
@@ -8398,16 +8595,24 @@ var ConnectionPoolManager = class {
    * @since v1.0.8
    */
   async close() {
+    if (this._closePromise) return this._closePromise;
+    this._closed = true;
+    this._generation += 1;
+    this._closePromise = this._closeAllPools();
+    return this._closePromise;
+  }
+  async _closeAllPools() {
     this.stopHealthCheck();
     this._healthChecker.stop();
     this._stats.close();
+    await Promise.allSettled([...this._pendingAddTasks]);
     for (const pool of this.pools.values()) {
       await pool.client.close();
     }
     this.pools.clear();
     this.healthStatus.clear();
     this.stats.clear();
-    this._closed = true;
+    this._configs.clear();
   }
   // ─── v1 compat methods ───────────────────────────────────────────────────────────
   /** v1 compat: get pool health Map */
@@ -8595,6 +8800,7 @@ async function initializeDistributedCacheInvalidator(options, cache, logger) {
       logger
     });
   } catch (err) {
+    if (err?.code === ErrorCodes.INVALID_CONFIG) throw err;
     logger.warn?.("[Cache] Failed to initialize distributed cache invalidator \u2014 check Redis config or package installation completeness.", err);
     return null;
   }
@@ -8673,6 +8879,33 @@ async function loadModelFiles(options, logger, opts = {}) {
   }
 }
 
+// src/entry/runtime-health.ts
+function summarizeRuntimeHealth(cacheOption, cache, poolManager, invalidator) {
+  const cacheStats = cache.getStats?.();
+  const poolHealth = poolManager?.getHealthStatus();
+  const distributedStats = invalidator?.getStats() ?? null;
+  const cacheInput = cacheOption;
+  const cacheEnabled = cacheInput?.enabled !== false;
+  const distributedEnabled = cacheInput?.distributed !== void 0 && cacheInput.distributed.enabled !== false;
+  const cacheProbe = cacheEnabled ? cache.getHealthStatus?.() : void 0;
+  const cacheProbeStatus = cacheProbe === true || cacheProbe === "up" ? "up" : cacheProbe === false || cacheProbe === "down" ? "down" : "unknown";
+  const redisState = invalidator;
+  const redisStatuses = [redisState?.pub?.status, redisState?.sub?.status];
+  const distributedStatus = !distributedEnabled || !invalidator ? "unknown" : redisStatuses.every((status) => status === "ready") ? "up" : redisStatuses.some((status) => status === "end" || status === "close") ? "down" : "unknown";
+  const poolStates = Object.values(poolHealth ?? {}).map((health) => health.status);
+  const poolsStatus = poolStates.length === 0 ? "unknown" : poolStates.some((status) => status === "down") ? "down" : poolStates.every((status) => status === "up") ? "up" : "unknown";
+  return {
+    cacheStats,
+    poolHealth,
+    distributedStats,
+    cacheEnabled,
+    distributedEnabled,
+    cacheProbeStatus,
+    distributedStatus,
+    poolsStatus
+  };
+}
+
 // src/entry/runtime-defaults.ts
 function isPlainObject3(value) {
   if (value === null || typeof value !== "object") return false;
@@ -9323,36 +9556,36 @@ var FUNC_REGEX = /^(CONCAT|UPPER|LOWER|TRIM|SUBSTR|LENGTH|ABS|CEIL|FLOOR|ROUND|S
 var IS_FUNC_CALL_RE = /^(CONCAT|UPPER|LOWER|TRIM|SUBSTR|LENGTH|ABS|CEIL|FLOOR|ROUND|SQRT|POW|SIZE|IN|SLICE|FIRST|LAST|ARRAY_ELEM_AT|FILTER|MAP|INDEX_OF|CONCAT_ARRAYS|TYPE|NOT|EXISTS|IS_NUMBER|IS_ARRAY|SUM|AVG|MAX|MIN|COUNT|PUSH|ADD_TO_SET|YEAR|MONTH|DAY_OF_MONTH|HOUR|MINUTE|SECOND|SPLIT|REPLACE|INDEX_OF_STR|LTRIM|RTRIM|SUBSTR_CP|REGEX|MERGE_OBJECTS|TO_INT|TO_STRING|OBJECT_TO_ARRAY|ARRAY_TO_OBJECT|SET_UNION|SWITCH)\s*\(/i;
 function compileInnerExpression(expression) {
   const expr2 = expression.trim();
-  const funcMatch = expr2.match(FUNC_REGEX);
-  if (funcMatch) {
-    return dispatchFunction(funcMatch[1].toUpperCase(), funcMatch[2] ?? "");
-  }
-  const andParts = splitTopLevel2(expr2, "&&");
-  if (andParts.length > 1) {
-    return { $and: andParts.map((part) => compileInnerExpression(part.trim())) };
+  if (!expr2) throw createError(ErrorCodes.INVALID_EXPRESSION, "Expression cannot be empty");
+  const positions = topLevelPositions(expr2);
+  const unwrapped = stripOuterParentheses(expr2);
+  if (unwrapped !== expr2) return compileInnerExpression(unwrapped);
+  if (/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/i.test(expr2)) return Number(expr2);
+  const conditional = findConditional(expr2, positions);
+  if (conditional) {
+    return { $cond: {
+      if: compileInnerExpression(expr2.slice(0, conditional.question)),
+      then: compileInnerExpression(expr2.slice(conditional.question + 1, conditional.colon)),
+      else: compileInnerExpression(expr2.slice(conditional.colon + 1))
+    } };
+  }
+  const nullCoalParts = splitTopLevel2(expr2, "??", positions);
+  if (nullCoalParts.length > 1) {
+    return nullCoalParts.slice(1).reduce(
+      (left, right) => ({ $ifNull: [left, compileInnerExpression(right)] }),
+      compileInnerExpression(nullCoalParts[0])
+    );
   }
-  const orParts = splitTopLevel2(expr2, "||");
+  const orParts = splitTopLevel2(expr2, "||", positions);
   if (orParts.length > 1) {
-    return { $or: orParts.map((part) => compileInnerExpression(part.trim())) };
-  }
-  const ternary = /^([^?]+)\s*\?\s*([^:]+)\s*:\s*(.+)$/.exec(expr2);
-  if (ternary) {
-    const [, condition, thenPart, elsePart] = ternary;
-    return {
-      $cond: {
-        if: compileInnerExpression(condition.trim()),
-        then: parseThenElse(thenPart.trim()),
-        else: parseThenElse(elsePart.trim())
-      }
-    };
+    return { $or: orParts.map((part) => compileInnerExpression(part)) };
   }
-  const nullCoalParts = splitTopLevel2(expr2, "??");
-  if (nullCoalParts.length > 1) {
-    return { $ifNull: [parseValue(nullCoalParts[0].trim()), parseValue(nullCoalParts[1].trim())] };
+  const andParts = splitTopLevel2(expr2, "&&", positions);
+  if (andParts.length > 1) {
+    return { $and: andParts.map((part) => compileInnerExpression(part)) };
   }
-  const cmpMatch = /^(.+?)\s*(===|!==|>=|<=|>|<)\s*(.+)$/.exec(expr2);
-  if (cmpMatch) {
-    const [, left, operator, right] = cmpMatch;
+  const comparison = findBinaryOperator(expr2, positions, ["===", "!==", ">=", "<=", ">", "<"]);
+  if (comparison) {
     const operatorMap = {
       "===": "$eq",
       "!==": "$ne",
@@ -9361,24 +9594,39 @@ function compileInnerExpression(expression) {
       ">": "$gt",
       "<": "$lt"
     };
-    return {
-      [operatorMap[operator]]: [
-        compileInnerExpression(left.trim()),
-        compileInnerExpression(right.trim())
-      ]
-    };
+    return { [operatorMap[comparison.operator]]: [
+      compileInnerExpression(expr2.slice(0, comparison.index)),
+      compileInnerExpression(expr2.slice(comparison.index + comparison.operator.length))
+    ] };
+  }
+  const additive = findBinaryOperator(expr2, positions, ["+", "-"], true);
+  if (additive) {
+    return { [additive.operator === "+" ? "$add" : "$subtract"]: [
+      compileInnerExpression(expr2.slice(0, additive.index)),
+      compileInnerExpression(expr2.slice(additive.index + 1))
+    ] };
+  }
+  const multiplicative = findBinaryOperator(expr2, positions, ["*", "/", "%"], true);
+  if (multiplicative) {
+    const operatorMap = { "*": "$multiply", "/": "$divide", "%": "$mod" };
+    return { [operatorMap[multiplicative.operator]]: [
+      compileInnerExpression(expr2.slice(0, multiplicative.index)),
+      compileInnerExpression(expr2.slice(multiplicative.index + 1))
+    ] };
   }
-  const addSubMatch = /^(.+?)\s*([+\-])\s*(.+)$/.exec(expr2);
-  if (addSubMatch) {
-    const [, left, operator, right] = addSubMatch;
-    const operatorMap = { "+": "$add", "-": "$subtract" };
-    return { [operatorMap[operator]]: [parseOperand(left.trim()), parseOperand(right.trim())] };
+  if (expr2.startsWith("-")) {
+    return { $multiply: [-1, compileInnerExpression(expr2.slice(1))] };
   }
-  const mulDivMatch = /^(.+?)\s*([*\/%])\s*(.+)$/.exec(expr2);
-  if (mulDivMatch) {
-    const [, left, operator, right] = mulDivMatch;
-    const operatorMap = { "*": "$multiply", "/": "$divide", "%": "$mod" };
-    return { [operatorMap[operator]]: [parseOperand(left.trim()), parseOperand(right.trim())] };
+  const funcMatch = expr2.match(FUNC_REGEX);
+  if (funcMatch) {
+    try {
+      return dispatchFunction(funcMatch[1].toUpperCase(), funcMatch[2] ?? "");
+    } catch (error) {
+      if (error && typeof error === "object" && "code" in error && error.code === ErrorCodes.INVALID_EXPRESSION) {
+        throw error;
+      }
+      throw createError(ErrorCodes.INVALID_EXPRESSION, `Invalid arguments for ${funcMatch[1].toUpperCase()}`);
+    }
   }
   const genericFuncCallRe = /^[A-Za-z_][A-Za-z0-9_]*\s*\(.+\)$/;
   if (genericFuncCallRe.test(expr2)) {
@@ -9387,9 +9635,6 @@ function compileInnerExpression(expression) {
   }
   return parseValue(expr2);
 }
-function parseThenElse(source) {
-  return source.includes("?") && source.includes(":") ? compileInnerExpression(source) : parseValue(source);
-}
 function parseValue(value) {
   const normalized = stripOuterParentheses(value.trim());
   if (normalized.startsWith("'") && normalized.endsWith("'") || normalized.startsWith('"') && normalized.endsWith('"')) {
@@ -9399,18 +9644,22 @@ function parseValue(value) {
   if (normalized === "true") return true;
   if (normalized === "false") return false;
   if (!isNaN(Number(normalized)) && normalized !== "") return Number(normalized);
-  if (IS_FUNC_CALL_RE.test(normalized)) {
+  if (normalized !== value.trim() || IS_FUNC_CALL_RE.test(normalized) || FUNC_REGEX.test(normalized)) {
     return compileInnerExpression(normalized);
   }
-  if (normalized.startsWith("$")) return normalized;
-  return `$${normalized}`;
-}
-function parseOperand(value) {
-  const normalized = stripOuterParentheses(value);
-  if (/[+\-*/%]/.test(normalized)) {
+  if (normalized.startsWith("[") || normalized.startsWith("{")) {
+    try {
+      return JSON.parse(normalized);
+    } catch {
+      throw createError(ErrorCodes.INVALID_EXPRESSION, "Invalid array or object literal");
+    }
+  }
+  const positions = topLevelPositions(normalized);
+  if (positions.some((index) => /[?+\-*/%><&|]/.test(normalized[index]))) {
     return compileInnerExpression(normalized);
   }
-  return parseValue(normalized);
+  if (normalized.startsWith("$")) return normalized;
+  return `$${normalized}`;
 }
 function dispatchFunction(name, argsStr) {
   const args = splitArgsStr(argsStr);
@@ -9712,72 +9961,82 @@ function compileMapExpression(exprStr, varName) {
   return compileInnerExpression(replaced);
 }
 function splitArgsStr(argsStr) {
-  const args = [];
-  let current = "";
-  let inString = false;
-  let stringChar = "";
-  let parenDepth = 0;
-  for (let index = 0; index < argsStr.length; index++) {
-    const ch = argsStr[index];
-    if ((ch === '"' || ch === "'") && (index === 0 || argsStr[index - 1] !== "\\")) {
-      if (!inString) {
-        inString = true;
-        stringChar = ch;
-      } else if (ch === stringChar) {
-        inString = false;
-        stringChar = "";
-      }
-      current += ch;
-    } else if (ch === "(" && !inString) {
-      parenDepth++;
-      current += ch;
-    } else if (ch === ")" && !inString) {
-      parenDepth--;
-      current += ch;
-    } else if (ch === "," && !inString && parenDepth === 0) {
-      args.push(current.trim());
-      current = "";
-    } else {
-      current += ch;
-    }
-  }
-  if (current.trim()) args.push(current.trim());
-  return args;
+  if (!argsStr.trim()) return [];
+  return splitTopLevel2(argsStr, ",");
 }
-function splitTopLevel2(source, separator) {
-  const parts = [];
-  let current = "";
-  let parenDepth = 0;
-  let inString = false;
-  let stringChar = "";
+function topLevelPositions(source) {
+  const positions = [];
+  const stack = [];
+  let quote = null;
   for (let index = 0; index < source.length; index++) {
     const ch = source[index];
-    if ((ch === '"' || ch === "'") && (index === 0 || source[index - 1] !== "\\")) {
-      if (!inString) {
-        inString = true;
-        stringChar = ch;
-      } else if (ch === stringChar) {
-        inString = false;
-        stringChar = "";
+    if (quote) {
+      if (ch === quote && source[index - 1] !== "\\") quote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      continue;
+    }
+    if (ch === "(" || ch === "[" || ch === "{") {
+      stack.push(ch);
+      continue;
+    }
+    if (ch === ")" || ch === "]" || ch === "}") {
+      const opening = stack.pop();
+      if (ch === ")" && opening !== "(" || ch === "]" && opening !== "[" || ch === "}" && opening !== "{") {
+        throw createError(ErrorCodes.INVALID_EXPRESSION, "Unbalanced expression delimiters");
       }
-      current += ch;
-    } else if (!inString && ch === "(") {
-      parenDepth++;
-      current += ch;
-    } else if (!inString && ch === ")") {
-      parenDepth--;
-      current += ch;
-    } else if (!inString && parenDepth === 0 && source.startsWith(separator, index)) {
-      parts.push(current);
-      current = "";
-      index += separator.length - 1;
-    } else {
-      current += ch;
+      continue;
     }
+    if (stack.length === 0) positions.push(index);
+  }
+  if (quote || stack.length > 0) {
+    throw createError(ErrorCodes.INVALID_EXPRESSION, "Unbalanced expression delimiters");
+  }
+  return positions;
+}
+function splitTopLevel2(source, separator, positions = topLevelPositions(source)) {
+  const parts = [];
+  let start = 0;
+  for (const index of positions) {
+    if (index < start || !source.startsWith(separator, index)) continue;
+    parts.push(source.slice(start, index).trim());
+    start = index + separator.length;
+  }
+  if (parts.length === 0) return [source];
+  parts.push(source.slice(start).trim());
+  if (parts.some((part) => !part)) {
+    throw createError(ErrorCodes.INVALID_EXPRESSION, `Missing operand around ${separator}`);
   }
-  parts.push(current);
   return parts;
 }
+function findConditional(source, positions) {
+  const question = positions.find((index) => source[index] === "?" && source[index - 1] !== "?" && source[index + 1] !== "?");
+  if (question === void 0) return null;
+  let nested = 0;
+  for (const index of positions) {
+    if (index <= question) continue;
+    if (source[index] === "?" && source[index - 1] !== "?" && source[index + 1] !== "?") nested++;
+    if (source[index] === ":") {
+      if (nested === 0) return { question, colon: index };
+      nested--;
+    }
+  }
+  throw createError(ErrorCodes.INVALID_EXPRESSION, "Conditional expression is missing a branch");
+}
+function findBinaryOperator(source, positions, operators, rightmost = false) {
+  let match = null;
+  for (const index of positions) {
+    const operator = operators.find((candidate) => source.startsWith(candidate, index));
+    if (!operator) continue;
+    if ((operator === "+" || operator === "-") && !source.slice(0, index).trim()) continue;
+    if ((operator === "+" || operator === "-") && /[+\-*/%<>=!?&|:,]$/.test(source.slice(0, index).trimEnd())) continue;
+    match = { index, operator };
+    if (!rightmost) break;
+  }
+  return match;
+}
 function stripOuterParentheses(source) {
   let normalized = source.trim();
   while (normalized.startsWith("(") && normalized.endsWith(")") && isWrappedByOuterParentheses(normalized)) {
@@ -9823,10 +10082,15 @@ function isExpressionObject(value) {
     value && typeof value === "object" && "__expr__" in value && typeof value.__expr__ === "string" && "__compiled__" in value && typeof value.__compiled__ === "boolean"
   );
 }
+function isPlainExpressionRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
 function hasExpressionInObject(value) {
   if (isExpressionObject(value)) return true;
-  if (!value || typeof value !== "object") return false;
   if (Array.isArray(value)) return value.some((item) => hasExpressionInObject(item));
+  if (!isPlainExpressionRecord(value)) return false;
   return Object.values(value).some((item) => hasExpressionInObject(item));
 }
 function hasExpressionInPipeline(pipeline) {
@@ -9843,7 +10107,7 @@ function transformExpressions(value, context) {
   if (Array.isArray(value)) {
     return value.map((item) => transformStageEntry(item));
   }
-  if (!value || typeof value !== "object") return value;
+  if (!isPlainExpressionRecord(value)) return value;
   const entries = Object.entries(value);
   const result = {};
   for (const [key, current] of entries) {
@@ -9852,7 +10116,7 @@ function transformExpressions(value, context) {
   return result;
 }
 function transformStageEntry(stage) {
-  if (!stage || typeof stage !== "object" || Array.isArray(stage)) {
+  if (!isPlainExpressionRecord(stage)) {
     return transformExpressions(stage, "project");
   }
   const entries = Object.entries(stage);
@@ -9876,7 +10140,7 @@ function transformStageValue(value, context) {
   if (Array.isArray(value)) {
     return value.map((item) => transformStageValue(item, context));
   }
-  if (!value || typeof value !== "object") return value;
+  if (!isPlainExpressionRecord(value)) return value;
   const entries = Object.entries(value);
   const result = {};
   for (const [key, current] of entries) {
@@ -10807,6 +11071,7 @@ var AggregateChain = class {
     return this.collection.aggregate(this.pipeline, buildAggregateDriverOptions(this.buildExecuteOptions())).explain(verbosity === true ? "queryPlanner" : verbosity);
   }
   stream() {
+    if (this.writePipelineHooks) assertManagedTransactionWriteAllowed(this.buildExecuteOptions());
     const stream = this.collection.aggregate(this.pipeline, buildAggregateDriverOptions(this.buildExecuteOptions())).stream();
     const onWriteComplete = this.writePipelineHooks?.onWriteComplete;
     if (onWriteComplete) {
@@ -10824,6 +11089,7 @@ var AggregateChain = class {
       throw createError(ErrorCodes.INVALID_OPERATION, "Query already executed.");
     }
     this.executed = true;
+    if (this.writePipelineHooks) assertManagedTransactionWriteAllowed(this.buildExecuteOptions());
     return this.collection.aggregate(this.pipeline, buildAggregateDriverOptions(this.buildExecuteOptions())).toArray().then(async (result) => {
       await this.writePipelineHooks?.onWriteComplete?.();
       return result;
@@ -11140,48 +11406,59 @@ function stripWriteCacheControlOptions(options) {
 
 // src/adapters/mongodb/writes/write-basic.ts
 async function insertOneDocument(collection, ...args) {
+  assertManagedTransactionWriteAllowed(args[1]);
   return collection.insertOne(...args);
 }
 async function insertManyDocuments(collection, ...args) {
+  assertManagedTransactionWriteAllowed(args[1]);
   return collection.insertMany(...args);
 }
 async function updateOneDocument(collection, ...args) {
+  assertManagedTransactionWriteAllowed(args[2]);
   return collection.updateOne(...args);
 }
 async function updateManyDocuments(collection, ...args) {
+  assertManagedTransactionWriteAllowed(args[2]);
   return collection.updateMany(...args);
 }
 async function replaceOneDocument(collection, ...args) {
+  assertManagedTransactionWriteAllowed(args[2]);
   return collection.replaceOne(...args);
 }
 async function findOneAndUpdateDocument(collection, filter, update, options) {
+  assertManagedTransactionWriteAllowed(options);
   if (options !== void 0) {
     return collection.findOneAndUpdate(filter, update, options);
   }
   return collection.findOneAndUpdate(filter, update);
 }
 async function findOneAndReplaceDocument(collection, filter, replacement, options) {
+  assertManagedTransactionWriteAllowed(options);
   if (options !== void 0) {
     return collection.findOneAndReplace(filter, replacement, options);
   }
   return collection.findOneAndReplace(filter, replacement);
 }
 async function findOneAndDeleteDocument(collection, filter, options) {
+  assertManagedTransactionWriteAllowed(options);
   if (options !== void 0) {
     return collection.findOneAndDelete(filter, options);
   }
   return collection.findOneAndDelete(filter);
 }
 async function upsertOneDocument(collection, filter, update, options = {}) {
+  assertManagedTransactionWriteAllowed(options);
   return collection.updateOne(filter, update, {
     ...options,
     upsert: true
   });
 }
 async function deleteOneDocument(collection, ...args) {
+  assertManagedTransactionWriteAllowed(args[1]);
   return collection.deleteOne(...args);
 }
 async function deleteManyDocuments(collection, ...args) {
+  assertManagedTransactionWriteAllowed(args[1]);
   return collection.deleteMany(...args);
 }
 async function incrementOneDocument(collection, filter, field, incrementOrOptions, maybeOptions) {
@@ -11208,6 +11485,7 @@ async function incrementOneDocument(collection, filter, field, incrementOrOption
     includeResultMetadata: true
   };
   if (normalizedProjection) findOptions.projection = normalizedProjection;
+  assertManagedTransactionWriteAllowed(findOptions);
   const rawResult = await collection.findOneAndUpdate(
     filter,
     updateDocument,
@@ -11340,14 +11618,25 @@ async function runWithConcurrency(items, concurrency, worker) {
     return;
   }
   let nextIndex = 0;
+  let stopAcquiring = false;
+  let firstFatal;
   const workerCount = Math.min(concurrency, items.length);
   await Promise.all(Array.from({ length: workerCount }, async () => {
-    while (nextIndex < items.length) {
+    while (!stopAcquiring && nextIndex < items.length) {
       const item = items[nextIndex];
       nextIndex += 1;
-      await worker(item);
+      try {
+        await worker(item);
+      } catch (error) {
+        if (!stopAcquiring) {
+          firstFatal = error;
+          stopAcquiring = true;
+        }
+        break;
+      }
     }
   }));
+  if (stopAcquiring) throw firstFatal;
 }
 async function insertBatchDocuments(collection, documents, options = {}) {
   if (!Array.isArray(documents)) {
@@ -11394,12 +11683,14 @@ async function insertBatchDocuments(collection, documents, options = {}) {
     insertedIds: {},
     retries: []
   };
+  assertManagedTransactionWriteAllowed(driverOptions);
   await runWithConcurrency(batchPlans, effectiveConcurrency, async ({ batchIndex, batch, batchOffset: batchOffset2 }) => {
     let pendingBatch = batch;
     let pendingIndexes = batch.map((_, index) => index);
     let attempts = 0;
     while (true) {
       try {
+        assertManagedTransactionWriteAllowed(driverOptions);
         const batchResult = await collection.insertMany(pendingBatch, {
           ...driverOptions,
           ordered
@@ -11419,6 +11710,7 @@ async function insertBatchDocuments(collection, documents, options = {}) {
         });
         break;
       } catch (cause) {
+        assertManagedTransactionWriteAllowed(driverOptions);
         const errorRecord = {
           batchIndex,
           message: cause instanceof Error ? cause.message : String(cause),
@@ -11490,6 +11782,10 @@ async function insertBatchDocuments(collection, documents, options = {}) {
   });
   return result;
 }
+function batchWriteFilter(filter, batch) {
+  const ids = { _id: { $in: batch } };
+  return Object.prototype.hasOwnProperty.call(filter, "_id") ? { $and: [filter, ids] } : { ...filter, ...ids };
+}
 async function updateBatchDocuments(collection, filter, update, options = {}) {
   if (!filter || typeof filter !== "object" || Array.isArray(filter)) {
     throw createError(ErrorCodes.INVALID_ARGUMENT, "filter must be a non-array object");
@@ -11533,6 +11829,7 @@ async function updateBatchDocuments(collection, filter, update, options = {}) {
       "updateBatch retry requires an idempotent update; non-idempotent operators such as $inc/$push cannot be safely replayed"
     );
   }
+  assertManagedTransactionWriteAllowed(driverOptions);
   const estimatedTotal = await estimateBatchTotal(collection, filter, driverOptions, estimateProgress);
   const totalBatches = estimatedTotal === null ? null : Math.ceil(estimatedTotal / batchSize);
   const result = {
@@ -11549,8 +11846,9 @@ async function updateBatchDocuments(collection, filter, update, options = {}) {
     let attempts = 0;
     while (true) {
       try {
+        assertManagedTransactionWriteAllowed(driverOptions);
         const batchResult = await collection.updateMany(
-          { _id: { $in: batch } },
+          batchWriteFilter(filter, batch),
           update,
           driverOptions
         );
@@ -11568,6 +11866,7 @@ async function updateBatchDocuments(collection, filter, update, options = {}) {
         });
         break;
       } catch (cause) {
+        assertManagedTransactionWriteAllowed(driverOptions);
         const errorRecord = {
           batchIndex,
           message: cause instanceof Error ? cause.message : String(cause),
@@ -11630,6 +11929,7 @@ async function deleteBatchDocuments(collection, filter, options = {}) {
   if (!Number.isInteger(retryAttempts) || retryAttempts < 0) {
     throw createError(ErrorCodes.INVALID_ARGUMENT, "retryAttempts must be a non-negative integer");
   }
+  assertManagedTransactionWriteAllowed(driverOptions);
   const estimatedTotal = await estimateBatchTotal(collection, filter, driverOptions, estimateProgress);
   const totalBatches = estimatedTotal === null ? null : Math.ceil(estimatedTotal / batchSize);
   const result = {
@@ -11644,8 +11944,9 @@ async function deleteBatchDocuments(collection, filter, options = {}) {
     let attempts = 0;
     while (true) {
       try {
+        assertManagedTransactionWriteAllowed(driverOptions);
         const batchResult = await collection.deleteMany(
-          { _id: { $in: batch } },
+          batchWriteFilter(filter, batch),
           driverOptions
         );
         result.deletedCount += batchResult.deletedCount;
@@ -11660,6 +11961,7 @@ async function deleteBatchDocuments(collection, filter, options = {}) {
         });
         break;
       } catch (cause) {
+        assertManagedTransactionWriteAllowed(driverOptions);
         const errorRecord = {
           batchIndex,
           message: cause instanceof Error ? cause.message : String(cause),
@@ -12188,9 +12490,11 @@ var MongoCollectionAccessor = class {
     const normalizedQuery = this._cvFilter(query);
     const maxTimeMS = this.management.defaults?.maxTimeMS;
     const merged = { ...maxTimeMS !== void 0 ? { maxTimeMS } : {}, ...options ?? {} };
-    const cacheTTL = typeof merged.cache === "number" ? merged.cache : 0;
+    const cacheTTL = merged.explain === void 0 || merged.explain === false ? typeof merged.cache === "number" ? merged.cache : 0 : 0;
     const { cache: _cache, ...keyOptions } = merged;
     void _cache;
+    const callerSignal = keyOptions.signal;
+    if (callerSignal?.aborted) throw createError(ErrorCodes.INVALID_OPERATION, "Count operation aborted");
     const executeCount = (signal) => countDocuments(
       this.collectionRef,
       normalizedQuery ?? {},
@@ -12201,15 +12505,16 @@ var MongoCollectionAccessor = class {
       const cacheKey = buildCountCacheKey(this.collectionRef, this.management.defaults, normalizedQuery, keyOptions);
       const cached = await Promise.resolve(this.management.queryCache.get(cacheKey));
       if (cached !== void 0) {
+        if (callerSignal?.aborted) throw createError(ErrorCodes.INVALID_OPERATION, "Count operation aborted");
         return Promise.resolve(wrapQueryResultWithMeta(this.collectionRef, this.management.defaults, "count", merged, startTs, cached));
       }
-      const runner2 = countQueue ? countQueue.execute(executeCount) : executeCount();
+      const runner2 = countQueue ? countQueue.execute(executeCount, { signal: callerSignal }) : executeCount();
       return runner2.then(async (result) => {
         await Promise.resolve(this.management.queryCache?.set(cacheKey, result, cacheTTL));
         return wrapQueryResultWithMeta(this.collectionRef, this.management.defaults, "count", merged, startTs, result);
       });
     }
-    const runner = countQueue ? countQueue.execute(executeCount) : executeCount();
+    const runner = countQueue ? countQueue.execute(executeCount, { signal: callerSignal }) : executeCount();
     return runner.then((result) => wrapQueryResultWithMeta(this.collectionRef, this.management.defaults, "count", merged, startTs, result));
   }
   /** Runs an aggregation pipeline and returns a chainable aggregate cursor. */
@@ -12766,10 +13071,10 @@ function assertCompatPoolExists(poolManager, poolName) {
 function createPoolScope(runtime, poolName) {
   return {
     collection: (name) => runtime.scopedCollection(name, { pool: poolName }),
-    model: (name) => runtime.scopedModel(name, { pool: poolName }),
+    model: (model) => runtime.scopedModel(model, { pool: poolName }),
     use: (dbName) => ({
       collection: (name) => runtime.scopedCollection(name, { pool: poolName, database: dbName }),
-      model: (name) => runtime.scopedModel(name, { pool: poolName, database: dbName })
+      model: (model) => runtime.scopedModel(model, { pool: poolName, database: dbName })
     })
   };
 }
@@ -13498,20 +13803,21 @@ var DistributedCacheLockManager = class {
     }
   }
   async withLock(key, callback, options = {}) {
+    let lock;
     try {
-      const lock = await this.acquireLock(key, options);
-      try {
-        return await callback();
-      } finally {
-        await lock.release().catch(() => {
-        });
-      }
+      lock = await this.acquireLock(key, options);
     } catch (error) {
       if (this._isRedisConnectionError(error) && options.fallbackToNoLock) {
         return callback();
       }
       throw error;
     }
+    try {
+      return await callback();
+    } finally {
+      await lock.release().catch(() => {
+      });
+    }
   }
   async acquireLock(key, options = {}) {
     const ttl = options.ttl ?? 1e4;
@@ -14614,8 +14920,6 @@ var SlowQueryLogManager = class {
 };
 
 // src/capabilities/sync/index.ts
-import { copyFile, mkdir, open, readFile, rename, unlink } from "node:fs/promises";
-import path2 from "node:path";
 import { MongoClient as MongoDriverClient3 } from "mongodb";
 
 // src/capabilities/sync/idempotency.ts
@@ -14718,25 +15022,19 @@ function validateSyncIdempotencyConfig(config) {
   }
 }
 
-// src/capabilities/sync/index.ts
+// src/capabilities/sync/resume-token-store.ts
+import { copyFile, mkdir, open, readFile, rename, unlink } from "node:fs/promises";
+import path2 from "node:path";
 function normalizeError(error) {
   return error instanceof Error ? error : new Error(String(error));
 }
 function delay2(ms) {
-  if (ms <= 0) {
-    return Promise.resolve();
-  }
+  if (ms <= 0) return Promise.resolve();
   return new Promise((resolve) => {
     const timer = setTimeout(resolve, ms);
     timer.unref?.();
   });
 }
-function normalizeCollectionFilter(collections) {
-  if (!collections?.length || collections.includes("*")) {
-    return null;
-  }
-  return new Set(collections);
-}
 async function syncDirectory(directory) {
   try {
     const handle = await open(directory, "r");
@@ -14748,35 +15046,6 @@ async function syncDirectory(directory) {
   } catch {
   }
 }
-function validateTargetConfig(target, index) {
-  if (!target || typeof target !== "object") {
-    throw createError(ErrorCodes.INVALID_CONFIG, `[Sync] targets[${index}] must be an object.`);
-  }
-  if (typeof target.name !== "string" || target.name.trim() === "") {
-    throw createError(ErrorCodes.INVALID_CONFIG, `[Sync] targets[${index}].name must be a non-empty string.`);
-  }
-  if (!target.apply && !target.uri && !target.pool) {
-    throw createError(ErrorCodes.INVALID_CONFIG, `[Sync] targets[${index}] requires one of apply / uri / pool.`);
-  }
-  if (target.uri !== void 0 && (typeof target.uri !== "string" || target.uri.trim() === "")) {
-    throw createError(ErrorCodes.INVALID_CONFIG, `[Sync] targets[${index}].uri must be a non-empty string when provided.`);
-  }
-  if (target.pool !== void 0 && (typeof target.pool !== "string" || target.pool.trim() === "")) {
-    throw createError(ErrorCodes.INVALID_CONFIG, `[Sync] targets[${index}].pool must be a non-empty string when provided.`);
-  }
-  if (target.databaseName !== void 0 && (typeof target.databaseName !== "string" || target.databaseName.trim() === "")) {
-    throw createError(ErrorCodes.INVALID_CONFIG, `[Sync] targets[${index}].databaseName must be a non-empty string when provided.`);
-  }
-  if (target.collections !== void 0 && (!Array.isArray(target.collections) || target.collections.length === 0)) {
-    throw createError(ErrorCodes.INVALID_CONFIG, `[Sync] targets[${index}].collections must be a non-empty array when provided.`);
-  }
-  if (target.collections?.some((item) => typeof item !== "string" || item.trim() === "")) {
-    throw createError(ErrorCodes.INVALID_CONFIG, `[Sync] targets[${index}].collections must contain non-empty strings.`);
-  }
-  if (target.apply !== void 0 && typeof target.apply !== "function") {
-    throw createError(ErrorCodes.INVALID_CONFIG, `[Sync] targets[${index}].apply must be a function when provided.`);
-  }
-}
 function validateResumeTokenConfig(config) {
   if (!config || typeof config !== "object") {
     throw createError(ErrorCodes.INVALID_CONFIG, "[Sync] resumeToken must be an object.");
@@ -14807,39 +15076,6 @@ function validateResumeTokenConfig(config) {
     throw createError(ErrorCodes.INVALID_CONFIG, "[Sync] resumeToken.saveRetryDelayMs must be a non-negative integer.");
   }
 }
-function validateSyncConfig(config) {
-  if (!config || typeof config !== "object") {
-    throw createError(ErrorCodes.INVALID_CONFIG, "[Sync] config must be an object.");
-  }
-  if (typeof config.enabled !== "boolean") {
-    throw createError(ErrorCodes.INVALID_CONFIG, "[Sync] enabled must be a boolean.");
-  }
-  if (!config.enabled) {
-    return;
-  }
-  if (!Array.isArray(config.targets) || config.targets.length === 0) {
-    throw createError(ErrorCodes.INVALID_CONFIG, "[Sync] targets must be a non-empty array.");
-  }
-  if (config.collections !== void 0 && (!Array.isArray(config.collections) || config.collections.length === 0)) {
-    throw createError(ErrorCodes.INVALID_CONFIG, "[Sync] collections must be a non-empty array when provided.");
-  }
-  if (config.collections?.some((item) => typeof item !== "string" || item.trim() === "")) {
-    throw createError(ErrorCodes.INVALID_CONFIG, "[Sync] collections must contain non-empty strings.");
-  }
-  if (config.filter !== void 0 && typeof config.filter !== "function") {
-    throw createError(ErrorCodes.INVALID_CONFIG, "[Sync] filter must be a function.");
-  }
-  if (config.transform !== void 0 && typeof config.transform !== "function") {
-    throw createError(ErrorCodes.INVALID_CONFIG, "[Sync] transform must be a function.");
-  }
-  validateSyncIdempotencyConfig(config.idempotency);
-  config.targets.forEach((target, index) => {
-    validateTargetConfig(target, index);
-  });
-  if (config.resumeToken) {
-    validateResumeTokenConfig(config.resumeToken);
-  }
-}
 var ResumeTokenStore = class {
   constructor(options = {}) {
     this.storage = options.storage ?? "file";
@@ -14863,16 +15099,9 @@ var ResumeTokenStore = class {
       return JSON.parse(payload);
     } catch (error) {
       const code = error?.code;
-      if (code !== "ENOENT") {
-        this.logger?.warn?.("[Sync] failed to load resume token", error);
-      }
+      if (code !== "ENOENT") this.logger?.warn?.("[Sync] failed to load resume token", error);
       if (code !== "ENOENT" && this.strictLoad) {
-        throw createError(
-          ErrorCodes.DATABASE_ERROR,
-          "[Sync] failed to load resume token",
-          void 0,
-          normalizeError(error)
-        );
+        throw createError(ErrorCodes.DATABASE_ERROR, "[Sync] failed to load resume token", void 0, normalizeError(error));
       }
       return null;
     }
@@ -14898,12 +15127,7 @@ var ResumeTokenStore = class {
     }
     this.logger?.error?.("[Sync] failed to save resume token", lastError);
     if (this.strictSave) {
-      throw createError(
-        ErrorCodes.DATABASE_ERROR,
-        "[Sync] failed to save resume token",
-        void 0,
-        lastError ?? void 0
-      );
+      throw createError(ErrorCodes.DATABASE_ERROR, "[Sync] failed to save resume token", void 0, lastError ?? void 0);
     }
   }
   async writePayload(payload) {
@@ -14936,9 +15160,7 @@ var ResumeTokenStore = class {
       await copyFile(this.path, `${this.path}.bak`);
     } catch (error) {
       const code = error?.code;
-      if (code !== "ENOENT") {
-        throw error;
-      }
+      if (code !== "ENOENT") throw error;
     }
   }
   async clear() {
@@ -14950,12 +15172,80 @@ var ResumeTokenStore = class {
       await unlink(this.path);
     } catch (error) {
       const code = error?.code;
-      if (code !== "ENOENT") {
-        this.logger?.warn?.("[Sync] failed to clear resume token", error);
-      }
+      if (code !== "ENOENT") this.logger?.warn?.("[Sync] failed to clear resume token", error);
     }
   }
 };
+
+// src/capabilities/sync/index.ts
+function normalizeCollectionFilter(collections) {
+  if (!collections?.length || collections.includes("*")) {
+    return null;
+  }
+  return new Set(collections);
+}
+function validateTargetConfig(target, index) {
+  if (!target || typeof target !== "object") {
+    throw createError(ErrorCodes.INVALID_CONFIG, `[Sync] targets[${index}] must be an object.`);
+  }
+  if (typeof target.name !== "string" || target.name.trim() === "") {
+    throw createError(ErrorCodes.INVALID_CONFIG, `[Sync] targets[${index}].name must be a non-empty string.`);
+  }
+  if (!target.apply && !target.uri && !target.pool) {
+    throw createError(ErrorCodes.INVALID_CONFIG, `[Sync] targets[${index}] requires one of apply / uri / pool.`);
+  }
+  if (target.uri !== void 0 && (typeof target.uri !== "string" || target.uri.trim() === "")) {
+    throw createError(ErrorCodes.INVALID_CONFIG, `[Sync] targets[${index}].uri must be a non-empty string when provided.`);
+  }
+  if (target.pool !== void 0 && (typeof target.pool !== "string" || target.pool.trim() === "")) {
+    throw createError(ErrorCodes.INVALID_CONFIG, `[Sync] targets[${index}].pool must be a non-empty string when provided.`);
+  }
+  if (target.databaseName !== void 0 && (typeof target.databaseName !== "string" || target.databaseName.trim() === "")) {
+    throw createError(ErrorCodes.INVALID_CONFIG, `[Sync] targets[${index}].databaseName must be a non-empty string when provided.`);
+  }
+  if (target.collections !== void 0 && (!Array.isArray(target.collections) || target.collections.length === 0)) {
+    throw createError(ErrorCodes.INVALID_CONFIG, `[Sync] targets[${index}].collections must be a non-empty array when provided.`);
+  }
+  if (target.collections?.some((item) => typeof item !== "string" || item.trim() === "")) {
+    throw createError(ErrorCodes.INVALID_CONFIG, `[Sync] targets[${index}].collections must contain non-empty strings.`);
+  }
+  if (target.apply !== void 0 && typeof target.apply !== "function") {
+    throw createError(ErrorCodes.INVALID_CONFIG, `[Sync] targets[${index}].apply must be a function when provided.`);
+  }
+}
+function validateSyncConfig(config) {
+  if (!config || typeof config !== "object") {
+    throw createError(ErrorCodes.INVALID_CONFIG, "[Sync] config must be an object.");
+  }
+  if (typeof config.enabled !== "boolean") {
+    throw createError(ErrorCodes.INVALID_CONFIG, "[Sync] enabled must be a boolean.");
+  }
+  if (!config.enabled) {
+    return;
+  }
+  if (!Array.isArray(config.targets) || config.targets.length === 0) {
+    throw createError(ErrorCodes.INVALID_CONFIG, "[Sync] targets must be a non-empty array.");
+  }
+  if (config.collections !== void 0 && (!Array.isArray(config.collections) || config.collections.length === 0)) {
+    throw createError(ErrorCodes.INVALID_CONFIG, "[Sync] collections must be a non-empty array when provided.");
+  }
+  if (config.collections?.some((item) => typeof item !== "string" || item.trim() === "")) {
+    throw createError(ErrorCodes.INVALID_CONFIG, "[Sync] collections must contain non-empty strings.");
+  }
+  if (config.filter !== void 0 && typeof config.filter !== "function") {
+    throw createError(ErrorCodes.INVALID_CONFIG, "[Sync] filter must be a function.");
+  }
+  if (config.transform !== void 0 && typeof config.transform !== "function") {
+    throw createError(ErrorCodes.INVALID_CONFIG, "[Sync] transform must be a function.");
+  }
+  validateSyncIdempotencyConfig(config.idempotency);
+  config.targets.forEach((target, index) => {
+    validateTargetConfig(target, index);
+  });
+  if (config.resumeToken) {
+    validateResumeTokenConfig(config.resumeToken);
+  }
+}
 var ChangeStreamSyncManager = class {
   constructor(options) {
     this.targets = [];
@@ -14964,7 +15254,10 @@ var ChangeStreamSyncManager = class {
     this.closingStreamPromise = null;
     this.changeQueue = Promise.resolve();
     this.running = false;
+    this.stopping = false;
+    this.stopPromise = null;
     this.fatalSyncError = null;
+    this.generation = 0;
     this.stats = {
       eventCount: 0,
       syncedCount: 0,
@@ -14997,40 +15290,62 @@ var ChangeStreamSyncManager = class {
    * @since v1.0.9
    */
   async start() {
+    if (this.stopPromise) await this.stopPromise;
     if (this.running || !this.config.enabled) return;
     if (this.startPromise) return this.startPromise;
+    const generation = ++this.generation;
     const startup = (async () => {
       await this.closingStreamPromise;
+      await this.changeQueue.catch(() => void 0);
+      this.assertCurrentGeneration(generation, true);
       if (this.running) return;
       this.fatalSyncError = null;
-      await this.validateEnvironment();
-      await this.initializeTargets();
-      const resumeAfter = await this.tokenStore.load();
-      const options = { fullDocument: "updateLookup" };
-      if (resumeAfter) options.resumeAfter = resumeAfter;
-      const stream = this.db.watch(this.buildPipeline(), options);
-      stream.on("change", (event) => this.enqueueChange(event));
-      stream.on("error", (error) => {
-        const normalized = normalizeError(error);
-        this.stats.errorCount += 1;
-        this.stats.lastError = normalized;
-        this.logger?.error?.("[Sync] change stream error", normalized);
-      });
-      stream.on("close", () => {
-        if (!this.running || this.changeStream !== stream) {
-          this.logger?.debug?.("[Sync] change stream closed");
-          return;
-        }
-        const error = createError(ErrorCodes.CONNECTION_CLOSED, "[Sync] change stream closed unexpectedly");
-        this.running = false;
-        this.changeStream = null;
-        this.stats.errorCount += 1;
-        this.stats.lastError = error;
-        this.logger?.warn?.("[Sync] change stream closed unexpectedly", error);
-      });
-      this.changeStream = stream;
-      this.running = true;
-      this.stats.startTime = /* @__PURE__ */ new Date();
+      await this.closeTargets();
+      let stagedTargets = [];
+      let stream = null;
+      try {
+        await this.validateEnvironment();
+        this.assertCurrentGeneration(generation);
+        stagedTargets = await this.initializeTargets();
+        this.assertCurrentGeneration(generation);
+        const resumeAfter = await this.tokenStore.load();
+        this.assertCurrentGeneration(generation);
+        const options = { fullDocument: "updateLookup" };
+        if (resumeAfter) options.resumeAfter = resumeAfter;
+        stream = this.db.watch(this.buildPipeline(), options);
+        const activeStream = stream;
+        activeStream.on("change", (event) => this.enqueueChange(event, generation));
+        activeStream.on("error", (error) => {
+          if (generation !== this.generation) return;
+          const normalized = normalizeError(error);
+          this.stats.errorCount += 1;
+          this.stats.lastError = normalized;
+          this.logger?.error?.("[Sync] change stream error", normalized);
+          this.stopAfterFatalSyncError(normalized, generation);
+        });
+        activeStream.on("close", () => {
+          if (generation !== this.generation || !this.running || this.changeStream !== activeStream) {
+            this.logger?.debug?.("[Sync] change stream closed");
+            return;
+          }
+          const error = createError(ErrorCodes.CONNECTION_CLOSED, "[Sync] change stream closed unexpectedly");
+          this.stats.errorCount += 1;
+          this.stats.lastError = error;
+          this.logger?.warn?.("[Sync] change stream closed unexpectedly", error);
+          this.stopAfterFatalSyncError(error, generation);
+        });
+        this.assertCurrentGeneration(generation);
+        this.targets.push(...stagedTargets);
+        stagedTargets = [];
+        this.changeStream = activeStream;
+        stream = null;
+        this.running = true;
+        this.stats.startTime = /* @__PURE__ */ new Date();
+      } catch (error) {
+        if (stream) await this.closeChangeStream(stream).catch(() => void 0);
+        for (const target of stagedTargets.reverse()) await target.close().catch(() => void 0);
+        throw error;
+      }
     })();
     this.startPromise = startup;
     try {
@@ -15044,16 +15359,37 @@ var ChangeStreamSyncManager = class {
    * @since v1.0.9
    */
   async stop() {
-    this.running = false;
-    await this.startPromise;
-    const stream = this.changeStream;
-    this.changeStream = null;
-    if (stream) await this.closeChangeStream(stream);
-    else await this.closingStreamPromise;
-    await this.changeQueue.catch(() => void 0);
+    if (this.stopPromise) return this.stopPromise;
+    this.stopping = true;
+    const cleanup = (async () => {
+      if (this.startPromise && !this.running) this.generation += 1;
+      await this.startPromise?.catch(() => void 0);
+      await this.changeQueue.catch(() => void 0);
+      this.generation += 1;
+      this.running = false;
+      const stream = this.changeStream;
+      this.changeStream = null;
+      if (stream) await this.closeChangeStream(stream);
+      else await this.closingStreamPromise;
+      await this.closeTargets();
+    })();
+    this.stopPromise = cleanup;
+    try {
+      await cleanup;
+    } finally {
+      if (this.stopPromise === cleanup) this.stopPromise = null;
+      this.stopping = false;
+    }
+  }
+  assertCurrentGeneration(generation, allowPreviousFatal = false) {
+    if (generation !== this.generation) {
+      throw createError(ErrorCodes.CONNECTION_CLOSED, "[Sync] startup was superseded by stop or restart");
+    }
+    if (!allowPreviousFatal && this.fatalSyncError) throw this.fatalSyncError;
+  }
+  async closeTargets() {
     while (this.targets.length > 0) {
-      const target = this.targets.pop();
-      await target?.close();
+      await this.targets.pop()?.close();
     }
   }
   /**
@@ -15118,11 +15454,13 @@ var ChangeStreamSyncManager = class {
     return pipeline;
   }
   async initializeTargets() {
-    if (this.targets.length > 0) {
-      return;
-    }
-    for (const target of this.config.targets) {
-      this.targets.push(await this.resolveTarget(target));
+    const staged = [];
+    try {
+      for (const target of this.config.targets) staged.push(await this.resolveTarget(target));
+      return staged;
+    } catch (error) {
+      for (const target of staged.reverse()) await target.close().catch(() => void 0);
+      throw error;
     }
   }
   async resolveTarget(target) {
@@ -15159,14 +15497,15 @@ var ChangeStreamSyncManager = class {
     const client = await this.clientFactory(target.uri, target.options);
     return createMongoTarget(target.name, collections, client, target.databaseName ?? this.db.databaseName, true);
   }
-  async handleChange(event) {
-    if (this.fatalSyncError) {
+  async handleChange(event, generation = this.generation) {
+    if (generation !== this.generation || !this.running || this.fatalSyncError) {
       this.logger?.warn?.("[Sync] skipping queued change after fatal sync error", this.fatalSyncError);
       return;
     }
     this.stats.eventCount += 1;
     this.stats.lastEventTime = /* @__PURE__ */ new Date();
     if (this.config.filter && !this.config.filter(event)) {
+      await this.saveProcessedToken(event, generation);
       return;
     }
     let document = event.fullDocument;
@@ -15178,6 +15517,7 @@ var ChangeStreamSyncManager = class {
     let duplicateTargets = 0;
     const targetErrors = [];
     for (const target of this.targets) {
+      if (generation !== this.generation || this.fatalSyncError || !this.running) return;
       if (target.collections && !target.collections.has(event.ns.coll)) {
         continue;
       }
@@ -15194,11 +15534,13 @@ var ChangeStreamSyncManager = class {
         if (idempotencyKey && this.idempotency.markMode === "start") {
           await this.markTargetEventApplied(idempotencyKey, event, target.name, "start");
         }
+        if (generation !== this.generation || this.fatalSyncError || !this.running) return;
         await target.apply(event, document, {
           targetName: target.name,
           ...idempotencyKey ? { idempotencyKey } : {}
         });
         if (idempotencyKey && this.idempotency.markMode === "success") {
+          if (generation !== this.generation || this.fatalSyncError || !this.running) return;
           await this.markTargetEventApplied(idempotencyKey, event, target.name, "success");
         }
         target.stats.syncCount += 1;
@@ -15219,26 +15561,30 @@ var ChangeStreamSyncManager = class {
       }
     }
     if (targetErrors.length > 0) {
-      this.stopAfterFatalSyncError(targetErrors[0]);
+      this.stopAfterFatalSyncError(targetErrors[0], generation);
       return;
     }
-    if (eligibleTargets > 0 && succeeded === eligibleTargets) {
-      try {
-        await this.tokenStore.save(event._id);
-      } catch (error) {
-        const normalized = normalizeError(error);
-        this.stats.tokenSaveErrorCount += 1;
-        this.stats.lastTokenSaveError = normalized;
-        this.stats.lastError = normalized;
-        this.stopAfterFatalSyncError(normalized);
-        throw normalized;
-      }
-      this.stats.syncedCount += 1;
+    if (succeeded === eligibleTargets) {
+      await this.saveProcessedToken(event, generation);
       if (duplicateTargets > 0 && duplicateTargets === eligibleTargets) {
         this.stats.duplicateEventCount += 1;
       }
     }
   }
+  async saveProcessedToken(event, generation) {
+    if (generation !== this.generation || this.fatalSyncError || !this.running) return;
+    try {
+      await this.tokenStore.save(event._id);
+    } catch (error) {
+      const normalized = normalizeError(error);
+      this.stats.tokenSaveErrorCount += 1;
+      this.stats.lastTokenSaveError = normalized;
+      this.stats.lastError = normalized;
+      this.stopAfterFatalSyncError(normalized, generation);
+      throw normalized;
+    }
+    if (generation === this.generation && !this.fatalSyncError && this.running) this.stats.syncedCount += 1;
+  }
   buildTargetIdempotencyKey(targetName, event) {
     if (!this.idempotency.enabled) {
       return null;
@@ -15261,7 +15607,8 @@ var ChangeStreamSyncManager = class {
       ts: Date.now()
     }, this.idempotency.ttl));
   }
-  stopAfterFatalSyncError(error) {
+  stopAfterFatalSyncError(error, generation) {
+    if (generation !== this.generation) return;
     this.fatalSyncError = error;
     this.running = false;
     const stream = this.changeStream;
@@ -15279,12 +15626,14 @@ var ChangeStreamSyncManager = class {
       if (this.closingStreamPromise === closing) this.closingStreamPromise = null;
     });
   }
-  enqueueChange(event) {
-    this.changeQueue = this.changeQueue.then(() => this.handleChange(event)).catch((error) => {
+  enqueueChange(event, generation) {
+    if (generation !== this.generation || !this.running || this.stopping || this.fatalSyncError) return;
+    this.changeQueue = this.changeQueue.then(() => this.handleChange(event, generation)).catch((error) => {
       const normalized = normalizeError(error);
       this.stats.errorCount += 1;
       this.stats.lastError = normalized;
       this.logger?.error?.("[Sync] change handling failed", normalized);
+      this.stopAfterFatalSyncError(normalized, generation);
     });
   }
 };
@@ -15713,7 +16062,9 @@ var SSHTunnelSSH2 = class {
       passphrase,
       port = 22,
       readyTimeout = 2e4,
-      keepaliveInterval = 3e4
+      keepaliveInterval = 3e4,
+      hostHash,
+      hostVerifier
     } = this._sshConfig;
     if (!host || !username) {
       throw createError(ErrorCodes.INVALID_CONFIG, "SSH config requires: host, username");
@@ -15722,6 +16073,8 @@ var SSHTunnelSSH2 = class {
       throw createError(ErrorCodes.INVALID_CONFIG, "SSH authentication required: provide password, privateKey, or privateKeyPath");
     }
     const config = { host, port, username, readyTimeout, keepaliveInterval };
+    if (hostHash !== void 0) config.hostHash = hostHash;
+    if (hostVerifier !== void 0) config.hostVerifier = hostVerifier;
     if (password) {
       config.password = password;
     } else if (privateKey) {
@@ -15740,6 +16093,25 @@ var SSHTunnelSSH2 = class {
     return new Promise((resolve, reject) => {
       const ssh = new SshClient();
       let settled = false;
+      const fail = (err) => {
+        if (settled) {
+          this.markDisconnected();
+          return;
+        }
+        settled = true;
+        this.isConnected = false;
+        this.localPort = null;
+        this.server = null;
+        this.sshClient = null;
+        for (const socket of this._activeSockets) socket.destroy();
+        this._activeSockets.clear();
+        void closeServer(server);
+        try {
+          ssh.end();
+        } catch {
+        }
+        reject(err);
+      };
       const server = net.createServer((socket) => {
         this._activeSockets.add(socket);
         socket.on("close", () => this._activeSockets.delete(socket));
@@ -15765,12 +16137,7 @@ var SSHTunnelSSH2 = class {
           }
         );
       });
-      server.on("error", (err) => {
-        if (!settled) {
-          settled = true;
-          reject(err);
-        }
-      });
+      server.on("error", fail);
       server.listen(this._sshConfig.localPort ?? 0, "127.0.0.1", () => {
         this.server = server;
         const addr = server.address();
@@ -15785,25 +16152,25 @@ var SSHTunnelSSH2 = class {
         });
         ssh.on("error", (err) => {
           if (!settled) {
-            settled = true;
-            server.close();
-            reject(err);
+            fail(err);
             return;
           }
           this.markDisconnected();
         });
         const handleDisconnect = () => {
           if (!settled) {
-            settled = true;
-            server.close();
-            reject(createError(ErrorCodes.CONNECTION_FAILED, "SSH connection closed before the tunnel became ready"));
+            fail(createError(ErrorCodes.CONNECTION_FAILED, "SSH connection closed before the tunnel became ready"));
             return;
           }
           this.markDisconnected();
         };
         ssh.on("close", handleDisconnect);
         ssh.on("end", handleDisconnect);
-        ssh.connect(authConfig);
+        try {
+          ssh.connect(authConfig);
+        } catch (err) {
+          fail(err);
+        }
       });
     });
   }
@@ -15834,6 +16201,7 @@ var SSHTunnelSSH2 = class {
     ssh?.end();
   }
   markDisconnected() {
+    const ssh = this.sshClient;
     this.isConnected = false;
     this.localPort = null;
     this.sshClient = null;
@@ -15844,6 +16212,10 @@ var SSHTunnelSSH2 = class {
     }
     this._activeSockets.clear();
     void closeServer(server);
+    try {
+      ssh?.end();
+    } catch {
+    }
   }
 };
 function parseHostFromUri(uri) {
@@ -15930,12 +16302,17 @@ async function prepareSshTunnelConnectConfig(connectConfig, databaseName, logger
   const remotePort = Number(cfg["dstPort"] ?? rawCfg["remotePort"] ?? rawCfg["mongoPort"] ?? parsePortFromUri(uri));
   const tunnel = new SSHTunnelSSH2(sshCfg, remoteHost, remotePort, { name: databaseName });
   logger.info?.(`[SSH] Establishing tunnel to ${remoteHost}:${remotePort} via ${String(cfg["host"])}`);
-  await tunnel.connect();
-  logger.info?.(`[SSH] Tunnel ready \u2014 local address: ${tunnel.getLocalAddress()}`);
-  return {
-    tunnel,
-    connectConfig: connectConfig?.uri ? { ...connectConfig, uri: tunnel.getTunnelUri("mongodb", connectConfig.uri) } : connectConfig
-  };
+  try {
+    await tunnel.connect();
+    logger.info?.(`[SSH] Tunnel ready \u2014 local address: ${tunnel.getLocalAddress()}`);
+    return {
+      tunnel,
+      connectConfig: connectConfig?.uri ? { ...connectConfig, uri: tunnel.getTunnelUri("mongodb", connectConfig.uri) } : connectConfig
+    };
+  } catch (error) {
+    await tunnel.close();
+    throw error;
+  }
 }
 
 // src/entry/runtime-schema-dsl.ts
@@ -16230,7 +16607,7 @@ function makePageResult(rows, ctx) {
 import { createHash as createHash4 } from "node:crypto";
 import os2 from "node:os";
 import path3 from "node:path";
-import { BSON } from "mongodb";
+import { BSON as BSON2 } from "mongodb";
 
 // src/capabilities/data-tasks/support.ts
 var INDEX_OPTION_KEYS = [
@@ -16338,7 +16715,7 @@ function canonicalize(value) {
   return value;
 }
 function canonicalStringify(value) {
-  return JSON.stringify(canonicalize(BSON.EJSON.serialize(value, { relaxed: false })));
+  return JSON.stringify(canonicalize(BSON2.EJSON.serialize(value, { relaxed: false })));
 }
 function hashDataTaskValue(value) {
   return createHash4("sha256").update(canonicalStringify(value)).digest("hex");
@@ -16827,9 +17204,8 @@ var MonSQLizeRuntime = class {
         driverError = error instanceof Error ? error.message : String(error);
       }
     }
-    const cacheStats = this._cache.getStats?.();
-    const poolHealth = this._poolManager?.getHealthStatus();
-    const distributedStats = this._distributedInvalidator?.getStats() ?? null;
+    const health = summarizeRuntimeHealth(this.options.cache, this._cache, this._poolManager, this._distributedInvalidator);
+    const { cacheStats, poolHealth, distributedStats, cacheEnabled, distributedEnabled, cacheProbeStatus, distributedStatus, poolsStatus } = health;
     const connected = this._connected && driverConnected;
     return {
       status: connected ? "up" : "down",
@@ -16837,7 +17213,7 @@ var MonSQLizeRuntime = class {
       driver: { connected: driverConnected, ...driverError ? { error: driverError } : {} },
       defaults: this.getDefaults(),
       cache: {
-        enabled: true,
+        enabled: cacheEnabled,
         stats: cacheStats,
         pools: poolHealth,
         distributed: distributedStats
@@ -16849,18 +17225,18 @@ var MonSQLizeRuntime = class {
           ...driverError ? { error: driverError } : {}
         },
         cache: {
-          status: "up",
-          enabled: true,
+          status: cacheProbeStatus,
+          enabled: cacheEnabled,
           hasStats: cacheStats !== void 0
         },
         distributedCacheInvalidator: {
-          status: distributedStats ? "up" : "unknown",
-          enabled: distributedStats !== null,
+          status: distributedStatus,
+          enabled: distributedEnabled,
           stats: distributedStats
         },
         pools: {
-          status: poolHealth ? "up" : "unknown",
-          enabled: poolHealth !== void 0,
+          status: poolsStatus,
+          enabled: this._poolManager !== null,
           health: poolHealth
         }
       },
@@ -16928,7 +17304,7 @@ var MonSQLizeRuntime = class {
     requireCompatDbInstance(this);
     return {
       collection: (collectionName) => this.scopedCollection(collectionName, { database: name }),
-      model: (modelName) => this.scopedModel(modelName, { database: name })
+      model: (model) => this.scopedModel(model, { database: name })
     };
   }
   pool(poolName) {
@@ -16960,7 +17336,8 @@ var MonSQLizeRuntime = class {
     });
   }
   // Model accessors ---------------------------------------------------------
-  scopedModel(name, options = {}) {
+  scopedModel(model, options = {}) {
+    const name = typeof model === "string" ? model : model.collectionName;
     const dbInstance = requireCompatDbInstance(this);
     if (this._client) {
       return this.createModelInstance(name, options);
@@ -16984,7 +17361,8 @@ var MonSQLizeRuntime = class {
       schemaEngine: this._schemaDslEngine
     });
   }
-  model(name) {
+  model(model) {
+    const name = typeof model === "string" ? model : model.collectionName;
     if (this._client) {
       this.ensureConnected();
       return this.createModelInstance(name, {
@@ -17220,7 +17598,7 @@ var MonSQLizeRuntime = class {
 };
 
 // src/capabilities/data-tasks/job-planner.ts
-import { BSON as BSON2 } from "mongodb";
+import { BSON as BSON3 } from "mongodb";
 
 // src/capabilities/data-tasks/document-utils.ts
 function isPlainRecord(value) {
@@ -17702,7 +18080,7 @@ async function planCollection(sourceHost, targetHost, config, sampleSize) {
     before: change.before,
     after: change.after
   }));
-  const backupBytes = changes.reduce((total, change) => total + Buffer.byteLength(`${BSON2.EJSON.stringify({
+  const backupBytes = changes.reduce((total, change) => total + Buffer.byteLength(`${BSON3.EJSON.stringify({
     ...change,
     beforeHash: hashDataTaskValue(change.before),
     plannedAfterHash: hashDataTaskValue(change.after)
@@ -17787,7 +18165,7 @@ import { mkdir as mkdir2, open as open2, readFile as readFile2, rename as rename
 import path4 from "node:path";
 import { gzip, gunzip } from "node:zlib";
 import { promisify } from "node:util";
-import { BSON as BSON3 } from "mongodb";
+import { BSON as BSON4, Int32, Long } from "mongodb";
 var gzipAsync = promisify(gzip);
 var gunzipAsync = promisify(gunzip);
 var BACKUP_TARGET = /* @__PURE__ */ Symbol("dataTaskBackupTarget");
@@ -17804,10 +18182,31 @@ function checksum(buffer) {
   return createHash5("sha256").update(buffer).digest("hex");
 }
 function ejsonLine(value) {
-  return BSON3.EJSON.stringify(value, { relaxed: false });
+  return BSON4.EJSON.stringify(value, { relaxed: false });
 }
 function ejsonManifest(value) {
-  return BSON3.EJSON.stringify(value, void 0, 2, { relaxed: false });
+  return BSON4.EJSON.stringify(value, void 0, 2, { relaxed: false });
+}
+function manifestInteger(value, field, minimum) {
+  const numeric = value instanceof Int32 ? value.valueOf() : Long.isLong(value) ? value.toBigInt() : value;
+  if (typeof numeric === "bigint") {
+    if (numeric < BigInt(minimum) || numeric > BigInt(Number.MAX_SAFE_INTEGER)) {
+      throw new Error(`invalid backup ${field}`);
+    }
+    return Number(numeric);
+  }
+  if (typeof numeric !== "number" || !Number.isSafeInteger(numeric) || numeric < minimum) {
+    throw new Error(`invalid backup ${field}`);
+  }
+  return numeric;
+}
+function decodeManifestControls(raw) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) throw new Error("invalid backup manifest");
+  const manifest = raw;
+  manifest.version = manifestInteger(manifest.version, "manifest", 1);
+  manifest.entryCount = manifestInteger(manifest.entryCount, "entry count", 0);
+  if (manifest.maxBytes !== void 0) manifest.maxBytes = manifestInteger(manifest.maxBytes, "max bytes", 1);
+  return manifest;
 }
 function sanitizeName(value) {
   return value.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "data-task";
@@ -17985,10 +18384,9 @@ async function createRestoreSafetyBackup(source, entries, beforeIndexes, targetH
 }
 async function readDataTaskBackup(ref) {
   try {
-    const manifest = BSON3.EJSON.parse(await readFile2(ref.manifestPath, "utf8"), { relaxed: true });
+    const manifest = decodeManifestControls(BSON4.EJSON.parse(await readFile2(ref.manifestPath, "utf8"), { relaxed: false }));
     if (manifest.kind !== "monsqlize-data-task-backup" || manifest.version !== 1 || manifest.runId !== ref.runId) throw new Error("invalid backup manifest");
     if (manifest.compression !== "gzip" && manifest.compression !== "none") throw new Error("invalid backup compression");
-    if (!Number.isSafeInteger(manifest.entryCount) || manifest.entryCount < 0) throw new Error("invalid backup entry count");
     if (typeof manifest.checksum !== "string" || !/^[a-f0-9]{64}$/i.test(manifest.checksum)) throw new Error("invalid backup checksum");
     if (typeof manifest.dataFile !== "string" || manifest.dataFile.length === 0 || path4.isAbsolute(manifest.dataFile) || path4.basename(manifest.dataFile) !== manifest.dataFile) {
       throw new Error("backup data file must stay beside its manifest");
@@ -18001,7 +18399,7 @@ async function readDataTaskBackup(ref) {
     if (digest !== manifest.checksum || digest !== ref.checksum) throw new Error("backup checksum mismatch");
     const plain = manifest.compression === "gzip" ? await gunzipAsync(contents) : contents;
     const lines = plain.toString("utf8").split(/\r?\n/).filter(Boolean);
-    const entries = lines.map((line) => BSON3.EJSON.parse(line, { relaxed: false }));
+    const entries = lines.map((line) => BSON4.EJSON.parse(line, { relaxed: false }));
     if (entries.length !== manifest.entryCount) throw new Error("backup entry count mismatch");
     return { ref: attachTarget({ ...ref }, backupTargetHint(ref)), manifest, entries };
   } catch (error) {
@@ -18319,6 +18717,7 @@ async function acquireDataTaskLease(host, options) {
 }
 
 // src/capabilities/data-tasks/job-restore.ts
+import { Int32 as Int322, Long as Long2 } from "mongodb";
 async function findCurrent(collection, identity) {
   let chain = collection.find(identity);
   if (typeof chain.limit === "function") chain = chain.limit(2);
@@ -18339,13 +18738,20 @@ function restoreApproval(hashes) {
   };
   return { ...payload, token: hashDataTaskValue(payload) };
 }
+function comparableIndexKey(key) {
+  return Object.fromEntries(Object.entries(key).map(([field, value]) => {
+    if (value instanceof Int322) return [field, value.valueOf()];
+    if (Long2.isLong(value) && value.toBigInt() <= BigInt(Number.MAX_SAFE_INTEGER) && value.toBigInt() >= BigInt(Number.MIN_SAFE_INTEGER)) return [field, Number(value.toBigInt())];
+    return [field, value];
+  }));
+}
 function exactIndex(index, current) {
-  return classifyDataTaskIndexes([{ key: index.key, name: index.name, options: index.options }], current)[0]?.status === "existing";
+  return classifyDataTaskIndexes([{ key: comparableIndexKey(index.key), name: index.name, options: index.options }], current)[0]?.status === "existing";
 }
 function pendingIndexMatches(index, current) {
   return current.filter((candidate) => {
     if (index.name && candidate.name !== index.name) return false;
-    return classifyDataTaskIndexes([{ key: index.key, options: index.options }], [candidate])[0]?.status === "existing";
+    return classifyDataTaskIndexes([{ key: comparableIndexKey(index.key), options: index.options }], [candidate])[0]?.status === "existing";
   });
 }
 function plannedDocumentMatches(current, entry) {
@@ -18613,7 +19019,7 @@ async function restoreDataTaskPlan(plan, target, targetHint, lease) {
       await updateDataTaskBackup(safety, (manifest) => {
         manifest.pendingIndexes = [...manifest.pendingIndexes ?? [], pending];
       });
-      await collection.createIndex(index.key, { ...index.options, name: index.name });
+      await collection.createIndex(comparableIndexKey(index.key), { ...index.options, name: index.name });
       if (!exactIndex(index, await collection.listIndexes())) {
         throw new DataTaskJobError("RESTORE_FAILED", `index "${index.name}" failed immediate readback.`, "restore");
       }
@@ -18785,6 +19191,7 @@ MonSQLize.PoolSelector = PoolSelector;
 MonSQLize.PoolStats = PoolStatsManager;
 MonSQLize.validatePoolConfig = validatePoolConfig;
 MonSQLize.validatePoolConfigSafe = validatePoolConfigSafe;
+MonSQLize.defineModel = defineModel;
 MonSQLize.Model = Model;
 MonSQLize.ModelInstance = ModelInstance;
 MonSQLize.expr = expr;
@@ -18874,6 +19281,7 @@ export {
   dataTasks,
   decodeCursor2 as decodeCursor,
   index_default as default,
+  defineModel,
   encodeCursor2 as encodeCursor,
   expr,
   generateQueryHash,