@ignex/ninox 0.1.4 → 0.1.6

package/dist/index.js

@@ -1,4 +1,4 @@
-import { ObjectId, MongoClient, Decimal128 } from 'mongodb';
+import { ObjectId, Decimal128, Long, Int32, Double, Timestamp, Binary, MinKey, MaxKey, DBRef, Code, MongoClient } from 'mongodb';
 import { writeFile, mkdir, readdir } from 'fs/promises';
 import { basename, join } from 'path';
 import { pathToFileURL } from 'url';
@@ -56,14 +56,6 @@ var probeMongoCapabilities = async (client) => {
     return { probed: false, transactionsSupported: false };
   }
 };
-var mongoTransactionsEnabled = (store, options = {}) => {
-  const env = options.envOverride ?? readMongoTransactionsEnvOverride();
-  if (env !== void 0) return env;
-  const state = store.get();
-  if (state.probed) return state.transactionsSupported;
-  if (options.urlHint) return /replicaSet=/.test(options.urlHint);
-  return false;
-};
 
 // src/errors/classes.ts
 var ERROR_HTTP_STATUS = {
@@ -138,8 +130,14 @@ var TRANSIENT_MONGO_ERROR_CODES = Object.freeze(
     // ShutdownInProgress
     189,
     // PrimarySteppedDown
+    251,
+    // NoSuchTransaction (stepdown mid-transaction)
+    262,
+    // ExceededTimeLimit (part of the retryable transaction set)
     9001,
     // SocketException
+    10058,
+    // NotWritablePrimary (legacy server code)
     10107,
     // NotWritablePrimary
     11600,
@@ -152,10 +150,13 @@ var TRANSIENT_MONGO_ERROR_CODES = Object.freeze(
     // NotPrimaryOrSecondary
   ])
 );
-var TRANSIENT_NAME = /MongoNetworkError|PoolClearedError|MongoWriteConcernError|MongoNotPrimaryError|MongoNodeIsRecoveringError|MongoNetworkTimeoutError/;
+var TRANSIENT_NAME = /MongoNetworkError|PoolClearedError|MongoWriteConcernError|MongoNotPrimaryError|MongoNodeIsRecoveringError|MongoNetworkTimeoutError|MongoServerSelectionError/;
 var isMongoTransientError = (error) => {
   if (!error || typeof error !== "object") return false;
   const e = error;
+  if (typeof e.hasErrorLabel === "function" && e.hasErrorLabel("TransientTransactionError")) {
+    return true;
+  }
   if (typeof e.name === "string" && TRANSIENT_NAME.test(e.name)) return true;
   if (typeof e.code === "number" && TRANSIENT_MONGO_ERROR_CODES.has(e.code)) return true;
   return false;
@@ -167,6 +168,42 @@ var isMongoDuplicateKeyError = (error) => {
   if (typeof e.message === "string" && /E11000|duplicate key/i.test(e.message)) return true;
   return false;
 };
+var isTransactionUnsupportedError = (error) => {
+  const code = error?.code;
+  if (code === 20) return true;
+  const message = error instanceof Error ? error.message : "";
+  return /Transaction numbers are only allowed/i.test(message) || /transactions are not supported/i.test(message) || /does not support retryable writes/i.test(message);
+};
+var MONGO_ERROR_NAME = /MongoError|MongoServerError|MongoBulkWriteError|MongoNetworkError|MongoNetworkTimeoutError|MongoWriteConcernError|MongoNotPrimaryError|MongoNodeIsRecoveringError|MongoCursorExhaustedError|PoolClearedError|MongoTopologyClosedError|MongoServerSelectionError/;
+var DRIVER_ERROR_CODES = Object.freeze(
+  /* @__PURE__ */ new Set([
+    20,
+    // IllegalOperation (transactions unsupported)
+    26,
+    // NamespaceNotFound
+    48,
+    // NamespaceExists
+    50,
+    // MaxTimeMSExpired
+    112,
+    // WriteConflict
+    121,
+    // DocumentValidationFailure
+    11e3,
+    // DuplicateKey
+    11001,
+    // DuplicateKey (legacy)
+    ...TRANSIENT_MONGO_ERROR_CODES
+  ])
+);
+var isMongoDriverError = (error) => {
+  if (!error || typeof error !== "object") return false;
+  const e = error;
+  if (typeof e.name === "string" && MONGO_ERROR_NAME.test(e.name)) return true;
+  if (typeof e.code === "number" && DRIVER_ERROR_CODES.has(e.code)) return true;
+  if (typeof e.message === "string" && /E11000 duplicate key/i.test(e.message)) return true;
+  return false;
+};
 
 // src/errors/driver-map.ts
 var extractValidationPaths = (errInfo) => {
@@ -195,6 +232,7 @@ var addValidationContext = (context, errInfo) => {
 var isBulkWriteError = (error) => typeof error === "object" && error !== null && "writeErrors" in error && Array.isArray(error.writeErrors);
 var mapMongoDriverError = (error, ctx = {}) => {
   if (error instanceof AppError) return error;
+  if (!isMongoDriverError(error)) return error;
   const context = { ...ctx };
   if (isMongoDuplicateKeyError(error)) {
     const e = error;
@@ -207,7 +245,7 @@ var mapMongoDriverError = (error, ctx = {}) => {
     if (first?.code === 11e3) {
       if (first.keyPattern) context.keyPattern = first.keyPattern;
       if (first.keyValue) context.keyValue = first.keyValue;
-      return new DomainError("DUPLICATE_KEY", first.errmsg ?? "Duplicate key error", context);
+      return new DomainError("DUPLICATE_KEY", "Duplicate key error", context);
     }
     if (first?.code === 121) {
       addValidationContext(context, first.errInfo);
@@ -252,7 +290,47 @@ var serializeError = (err, ctx = {}) => {
 var cloneDeep = (value) => {
   if (value instanceof Date) return new Date(value.getTime());
   if (value instanceof ObjectId) return new ObjectId(value.toHexString());
+  if (value instanceof Decimal128) return Decimal128.fromString(value.toString());
+  if (value instanceof Long) return Long.fromString(value.toString());
+  if (value instanceof Int32) return new Int32(value.valueOf());
+  if (value instanceof Double) return new Double(value.valueOf());
+  if (value instanceof Timestamp)
+    return Timestamp.fromBits(value.getLowBits(), value.getHighBits());
+  if (value instanceof Binary) {
+    const bytes = Buffer.from(value.buffer);
+    return new Binary(bytes, value.sub_type);
+  }
+  if (value instanceof MinKey) return new MinKey();
+  if (value instanceof MaxKey) return new MaxKey();
+  if (value instanceof DBRef) {
+    return new DBRef(value.collection, cloneDeep(value.oid), value.db);
+  }
+  if (value instanceof Code) {
+    return new Code(
+      value.code,
+      value.scope !== void 0 ? cloneDeep(value.scope) : void 0
+    );
+  }
   if (value instanceof RegExp) return new RegExp(value.source, value.flags);
+  if (value instanceof Map) {
+    const out = /* @__PURE__ */ new Map();
+    for (const [k, v] of value) out.set(cloneDeep(k), cloneDeep(v));
+    return out;
+  }
+  if (value instanceof Set) {
+    const out = /* @__PURE__ */ new Set();
+    for (const v of value) out.add(cloneDeep(v));
+    return out;
+  }
+  if (Buffer.isBuffer(value)) return Buffer.from(value);
+  if (ArrayBuffer.isView(value)) {
+    const view = value;
+    if (view instanceof DataView) {
+      const bytes = view.buffer.slice(view.byteOffset, view.byteOffset + view.byteLength);
+      return new DataView(bytes);
+    }
+    return typeof view.slice === "function" ? view.slice() : value;
+  }
   if (Array.isArray(value)) return value.map((item) => cloneDeep(item));
   if (value !== null && typeof value === "object") {
     const out = {};
@@ -265,7 +343,10 @@ var cloneDeep = (value) => {
 };
 
 // src/utils/hash.ts
-var isPlainObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var isPlainObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v) && !(v instanceof Date) && !(v instanceof RegExp) && // Mongo driver ObjectId (and other BSON values with a toHexString marker)
+// must fall through to `toPrimitive` — treating them as plain objects
+// would serialize every ObjectId as `{}` and collapse distinct values.
+typeof v.toHexString !== "function";
 var toPrimitive = (v) => {
   if (v === void 0 || v === null) return null;
   if (typeof v === "bigint") return v.toString();
@@ -290,11 +371,15 @@ var stableStringify = (value) => {
   return JSON.stringify(visit(value));
 };
 var hashString = (input) => {
-  let hash = 5381;
+  let h1 = 5381;
+  let h2 = 2166136261;
   for (let i = 0; i < input.length; i++) {
-    hash = (hash << 5) + hash + input.charCodeAt(i) | 0;
+    const c = input.charCodeAt(i);
+    h1 = (h1 << 5) + h1 + c | 0;
+    h2 = (h2 ^ c) * 16777619 | 0;
+    h2 = h2 << 3 | h2 >>> 29;
   }
-  return (hash >>> 0).toString(36);
+  return `${(h1 >>> 0).toString(36)}${(h2 >>> 0).toString(36)}`;
 };
 var stableHash = (value) => hashString(stableStringify(value));
 
@@ -302,11 +387,13 @@ var stableHash = (value) => hashString(stableStringify(value));
 var LRU = class {
   max;
   map = /* @__PURE__ */ new Map();
+  onEvict;
   /** Number of entries evicted to make room for new ones (capacity evictions only). */
   evictions = 0;
   constructor(options) {
     if (options.max <= 0) throw new Error("LRU max must be > 0");
     this.max = options.max;
+    this.onEvict = options.onEvict;
   }
   get size() {
     return this.map.size;
@@ -328,10 +415,16 @@ var LRU = class {
     if (this.map.has(key)) this.map.delete(key);
     this.map.set(key, value);
     if (this.map.size > this.max) {
-      const oldest = this.map.keys().next().value;
-      if (oldest !== void 0) {
-        this.map.delete(oldest);
+      const next = this.map.keys().next();
+      if (next.done !== true) {
+        const evictedKey = next.value;
+        const evictedValue = this.map.get(evictedKey);
+        this.map.delete(evictedKey);
         this.evictions++;
+        try {
+          this.onEvict?.(evictedKey, evictedValue);
+        } catch {
+        }
       }
     }
     return this;
@@ -362,9 +455,20 @@ var InFlight = class {
   run(key, fn) {
     const existing = this.pending.get(key);
     if (existing) return existing;
-    const promise = fn().finally(() => {
-      this.pending.delete(key);
-    });
+    let promise;
+    try {
+      promise = Promise.resolve(fn());
+    } catch (err) {
+      promise = Promise.reject(err);
+    }
+    promise.then(
+      () => {
+        this.pending.delete(key);
+      },
+      () => {
+        this.pending.delete(key);
+      }
+    );
     this.pending.set(key, promise);
     return promise;
   }
@@ -372,24 +476,50 @@ var InFlight = class {
     this.pending.clear();
   }
 };
-var estimateSize = (value) => {
+var OVERHEAD_PER_KEY = 8;
+var estimateSize = (value, seen) => {
   if (value === null || value === void 0) return 0;
   if (typeof value === "string") return value.length * 2;
   if (typeof value === "number" || typeof value === "boolean") return 8;
+  if (typeof value === "bigint") return 16;
+  if (typeof value !== "object") return 0;
   if (value instanceof ObjectId) return 16;
   if (value instanceof Date) return 8;
-  if (Array.isArray(value)) return value.reduce((sum, v) => sum + estimateSize(v), 0);
-  if (typeof value === "object") {
-    let sum = 0;
-    for (const [k, v] of Object.entries(value)) {
-      sum += k.length * 2 + estimateSize(v);
+  const visit = (v) => {
+    if (v !== null && typeof v === "object") {
+      if (!seen) seen = /* @__PURE__ */ new WeakSet();
+      else if (seen.has(v)) return OVERHEAD_PER_KEY;
+      seen.add(v);
     }
-    return sum;
+    return estimateSize(v, seen);
+  };
+  if (Array.isArray(value)) {
+    let sum2 = OVERHEAD_PER_KEY * Math.max(value.length, 1);
+    for (const v of value) sum2 += visit(v);
+    return sum2;
+  }
+  if (value instanceof Map) {
+    let sum2 = OVERHEAD_PER_KEY * value.size;
+    for (const [k, v] of value) sum2 += estimateSize(k, seen) + visit(v);
+    return sum2;
+  }
+  if (value instanceof Set) {
+    let sum2 = OVERHEAD_PER_KEY * value.size;
+    for (const v of value) sum2 += visit(v);
+    return sum2;
+  }
+  if (ArrayBuffer.isView(value)) {
+    return value.byteLength + OVERHEAD_PER_KEY;
+  }
+  let sum = 0;
+  for (const [k, v] of Object.entries(value)) {
+    sum += k.length * 2 + OVERHEAD_PER_KEY + visit(v);
   }
-  return 0;
+  return sum;
 };
 
 // src/cache/hot-cache/ticker.ts
+var MAX_TICK_INFLIGHT = 64;
 var RefreshTicker = class {
   constructor(host, tickIntervalMs) {
     this.host = host;
@@ -424,17 +554,26 @@ var RefreshTicker = class {
       this.timer = void 0;
     }
   }
-  /** Background refresh pass: re-run loaders for due entries, swap fresh values. */
+  /**
+   * Background refresh pass: re-run loaders for due entries, swap fresh values.
+   * A per-tick in-flight budget bounds the stampede after downtime/throttling —
+   * one sweep can't launch unbounded simultaneous loaders across all queries;
+   * skipped entries stay due and are picked up by the next tick.
+   */
   tick() {
     const now = Date.now();
+    let budget = MAX_TICK_INFLIGHT;
     for (const q of this.host.queries().values()) {
       if (q.refreshIntervalMs <= 0) continue;
       for (const [key, entry] of [...q.lru.entries()]) {
         if (entry.nextRefreshAt <= now) {
+          if (budget <= 0) return;
+          budget--;
+          entry.nextRefreshAt = now + q.refreshIntervalMs;
           q.refreshes++;
           void this.host.fetch(q, key, entry.args, q.gen).catch((err) => {
             const current = q.lru.peek(key);
-            if (current) current.nextRefreshAt = now + q.refreshIntervalMs;
+            if (current) current.nextRefreshAt = Date.now();
             this.host.logger.warn?.(
               {
                 error: err instanceof Error ? err.message : String(err),
@@ -468,6 +607,15 @@ var RefreshTicker = class {
 
 // src/cache/hot-cache/types.ts
 var WATCH_SEP = "\0";
+var resolveWatchDb = (ref) => typeof ref.db === "function" ? ref.db() : ref.db;
+var normalizeWatchId = (id) => {
+  if (typeof id === "string") return id;
+  if (typeof id === "number" || typeof id === "bigint") return String(id);
+  if (id instanceof Date) return `d${id.getTime()}`;
+  const hex = typeof id === "object" && id !== null ? id.toHexString : void 0;
+  if (typeof hex === "function") return hex.call(id);
+  return stableStringify(id);
+};
 
 // src/utils/watch-errors.ts
 var isPermanentWatchError = (message) => (
@@ -482,6 +630,21 @@ var isPermanentWatchError = (message) => (
 );
 
 // src/cache/hot-cache/watcher.ts
+var resolveDbSafe = (ref, logger) => {
+  try {
+    return resolveWatchDb(ref);
+  } catch (err) {
+    logger.debug?.(
+      { error: err instanceof Error ? err.message : String(err), collection: ref.collection },
+      "hot cache: watch db accessor not ready yet"
+    );
+    return null;
+  }
+};
+var documentKeyOf = (change) => {
+  const key = change?.documentKey;
+  return key ? key._id : void 0;
+};
 var WatchCoordinator = class {
   constructor(host) {
     this.host = host;
@@ -489,6 +652,8 @@ var WatchCoordinator = class {
   streams = /* @__PURE__ */ new Map();
   failedStreams = /* @__PURE__ */ new Set();
   stopped = true;
+  /** Guards against stacking reconnect timers when several accessors lag. */
+  reopenTimer;
   /** Number of currently open change streams. */
   get size() {
     return this.streams.size;
@@ -501,6 +666,7 @@ var WatchCoordinator = class {
   /** Close every watcher and clear failure bookkeeping (idempotent). */
   async stop() {
     this.stopped = true;
+    if (this.reopenTimer) clearTimeout(this.reopenTimer);
     const closes = [...this.streams.values()].map((stream) => {
       try {
         return Promise.resolve(stream.close()).catch(() => {
@@ -515,14 +681,32 @@ var WatchCoordinator = class {
   }
   openWatchStreams() {
     const seen = /* @__PURE__ */ new Set();
+    let deferred = false;
     for (const q of this.host.queries().values()) {
       for (const ref of q.config.watch ?? []) {
-        const key = `${ref.db.databaseName}${WATCH_SEP}${ref.collection}`;
+        const db = resolveDbSafe(ref, this.host.logger);
+        if (!db) {
+          deferred = true;
+          continue;
+        }
+        const key = `${db.databaseName}${WATCH_SEP}${ref.collection}`;
         if (seen.has(key) || this.streams.has(key)) continue;
         seen.add(key);
-        void this.watchLoop(key, ref);
+        void this.watchLoop(key, ref).catch((err) => {
+          this.host.logger.error?.(
+            { error: err instanceof Error ? err.message : String(err), collection: ref.collection },
+            "hot cache: watcher crashed"
+          );
+        });
       }
     }
+    if (deferred && !this.stopped && !this.reopenTimer) {
+      this.reopenTimer = setTimeout(() => {
+        this.reopenTimer = void 0;
+        if (!this.stopped) this.openWatchStreams();
+      }, 5e3);
+      this.reopenTimer.unref?.();
+    }
   }
   /**
    * Long-lived change-stream consumer for one collection. Each data change
@@ -536,11 +720,19 @@ var WatchCoordinator = class {
   async watchLoop(key, ref) {
     let backoff = 0;
     while (!this.stopped) {
+      let connectedAt = Date.now();
       try {
-        const stream = ref.db.collection(ref.collection).watch([]);
-        stream.on("error", () => {
+        const db = resolveDbSafe(ref, this.host.logger);
+        if (!db) throw new Error("watch db accessor not available");
+        const stream = db.collection(ref.collection).watch([]);
+        stream.on("error", (err) => {
+          this.host.logger.debug?.(
+            { error: err instanceof Error ? err.message : String(err) },
+            "hot cache change stream error event"
+          );
         });
         this.streams.set(key, stream);
+        connectedAt = Date.now();
         if (backoff > 0) {
           this.host.logger.warn?.(
             { collection: ref.collection },
@@ -549,10 +741,13 @@ var WatchCoordinator = class {
           this.host.invalidateCollection(ref.collection);
         }
         const iterator = stream[Symbol.asyncIterator]();
-        for await (const _change of iterator) {
-          this.host.invalidateCollection(ref.collection);
+        for await (const change of iterator) {
+          const docId = documentKeyOf(change);
+          if (docId === void 0) this.host.invalidateCollection(ref.collection);
+          else this.host.invalidateDocument(ref.collection, docId);
         }
       } catch (err) {
+        if (Date.now() - connectedAt > 6e4) backoff = 0;
         const message = err instanceof Error ? err.message : String(err);
         this.host.logger.warn?.(
           { error: message, collection: ref.collection },
@@ -589,7 +784,9 @@ var WatchCoordinator = class {
     const set = /* @__PURE__ */ new Set();
     for (const q of this.host.queries().values()) {
       for (const ref of q.config.watch ?? []) {
-        set.add(`${ref.db.databaseName}${WATCH_SEP}${ref.collection}`);
+        const db = resolveDbSafe(ref, this.host.logger);
+        if (!db) continue;
+        set.add(`${db.databaseName}${WATCH_SEP}${ref.collection}`);
       }
     }
     return set;
@@ -630,10 +827,14 @@ var HotCache = class {
     this.watcher = new WatchCoordinator({
       queries: () => this.queries,
       invalidateCollection: (collection) => this.invalidateCollection(collection),
+      invalidateDocument: (collection, id) => this.invalidateIds(collection, [id]),
       isReplica: () => this._mode === "replica",
       fallbackToStandalone: () => {
         this._mode = "standalone";
-        if (this.refreshEnabled) this.ticker.start();
+        if (this.refreshEnabled && !this.ticker.running) {
+          this.ticker.start();
+          this.ticker.warnUnboundedStaleness();
+        }
       },
       logger: this.logger
     });
@@ -676,25 +877,26 @@ var HotCache = class {
       refreshIntervalMs: config.refreshIntervalMs ?? 0,
       clone: config.clone ?? false,
       ...config.maxValueBytes !== void 0 ? { maxValueBytes: config.maxValueBytes } : {},
+      hasIdWatch: (config.watch ?? []).some((ref) => typeof ref.idsOf === "function"),
       gen: 0,
       hits: 0,
       misses: 0,
       refreshes: 0,
       loadErrors: 0,
       sizeSkips: 0,
+      idDrops: 0,
       warnedSize: false
     };
     this.queries.set(name, query);
     if (this._mode === "replica" && !this.stopped) {
       this.watcher.start();
     }
-    return {
-      get: (...args) => this.get(name, ...args),
-      invalidate: (...args) => {
-        if (args.length === 0) this.invalidate(name);
-        else this.invalidateParams(name, ...args);
-      }
+    const get = (...args) => this.get(name, ...args);
+    const invalidate = (...args) => {
+      if (args.length === 0) this.invalidate(name);
+      else this.invalidateParams(name, ...args);
     };
+    return { get, invalidate };
   }
   /**
    * Read-through read by dynamic name lookup. Call parameters are hashed into
@@ -716,7 +918,7 @@ var HotCache = class {
       q.lru.delete(key);
     }
     q.misses++;
-    return this.fetch(q, key, args, q.gen);
+    return await this.fetch(q, key, args, q.gen);
   }
   /** Drop every cached entry for a registered query. */
   invalidate(name) {
@@ -749,6 +951,48 @@ var HotCache = class {
       }
     }
   }
+  /**
+   * Fine-tuned purge: drop only the entries that depend on specific document
+   * ids of a watched collection. Two complementary mechanisms feed it:
+   *
+   *   - **Replica mode** — the change stream extracts `documentKey._id` from
+   *     each event and calls this with just that id, so a write to one document
+   *     no longer purges every query bound to the whole collection.
+   *   - **Manual (any mode)** — call it from ORM after-write hooks or anywhere
+   *     else you know exactly which ids changed.
+   *
+   * Per query bound to `collection`, semantics are:
+   *   - watch ref declares `idsOf` → only LRU entries whose extracted ids
+   *     include one of `ids` are dropped (`depsAll` entries — where extraction
+   *     failed — are dropped too; conservative). Sibling entries stay warm and
+   *     `stats().perQuery[name].idDrops` counts what was dropped.
+   *   - no `idsOf` on any bound ref → full purge of that query (the
+   *     `invalidateCollection` behavior — the safe default).
+   */
+  invalidateIds(collection, ids) {
+    if (ids.length === 0) return;
+    const changed = /* @__PURE__ */ new Set();
+    for (const id of ids) changed.add(`${collection}${WATCH_SEP}${normalizeWatchId(id)}`);
+    for (const q of this.queries.values()) {
+      const bound = q.config.watch?.filter((ref) => ref.collection === collection);
+      if (!bound || bound.length === 0) continue;
+      if (!bound.some((ref) => typeof ref.idsOf === "function")) {
+        q.lru.clear();
+        q.gen++;
+        continue;
+      }
+      let dropped = 0;
+      for (const [key, entry] of [...q.lru.entries()]) {
+        const matches = entry.depsAll === true || entry.deps?.some((dep) => changed.has(dep)) === true;
+        if (matches) {
+          q.lru.delete(key);
+          dropped++;
+        }
+      }
+      q.idDrops += dropped;
+      q.gen++;
+    }
+  }
   /** Drop every cached entry for every query. */
   clear() {
     for (const q of this.queries.values()) {
@@ -758,9 +1002,10 @@ var HotCache = class {
   }
   /**
    * Runtime observability snapshot: total queries/entries plus per-query
-   * counters (`hits`, `misses`, background `refreshes`, `loadErrors`, and
-   * `sizeSkips` for entries dropped by `maxValueBytes`). Useful for dashboards
-   * and cache-effectiveness checks.
+   * counters (`hits`, `misses`, background `refreshes`, `loadErrors`,
+   * `sizeSkips` for entries dropped by `maxValueBytes`, and `idDrops` for
+   * entries dropped by id-targeted invalidation). Useful for dashboards and
+   * cache-effectiveness checks.
    */
   stats() {
     const perQuery = {};
@@ -772,6 +1017,7 @@ var HotCache = class {
         refreshes: q.refreshes,
         loadErrors: q.loadErrors,
         sizeSkips: q.sizeSkips,
+        idDrops: q.idDrops,
         evictions: q.lru.evictions
       };
     }
@@ -780,12 +1026,15 @@ var HotCache = class {
   /**
    * Probe replica support once, then start change-stream watchers (replica) or
    * the global refresh ticker (standalone). Idempotent — resolves the mode.
+   * A FAILED start does not stick: the memoized promise is cleared so the next
+   * `get()`/`start()` retries probing (one transient blip during startup must
+   * not disable background freshness for the life of the instance).
    */
   async start() {
     if (this.disposed) return this._mode;
     if (this.started) return this._mode;
     if (!this.startPromise) {
-      this.startPromise = this.runStart();
+      this.startPromise = this.runStart().catch(this.forgetFailedStart);
     }
     return this.startPromise;
   }
@@ -807,6 +1056,17 @@ var HotCache = class {
     this._mode = "unknown";
   }
   /* ----------------------------- internals ----------------------------- */
+  /**
+   * A FAILED start does not stick: clear the memoized state so the next
+   * `get()`/`start()` retries probing (one transient blip during startup must
+   * not disable background freshness for the life of the instance).
+   */
+  forgetFailedStart = (err) => {
+    this.startPromise = void 0;
+    this.startAttempted = false;
+    this.started = false;
+    throw err;
+  };
   async runStart() {
     this.stopped = false;
     const supported = this.options.mode === "replica" ? true : this.options.mode === "standalone" ? false : await (this.options.probe ?? this.defaultProbe)();
@@ -830,20 +1090,34 @@ var HotCache = class {
   ensureStarted() {
     if (this.disposed || this.started || this.startAttempted) return;
     this.startAttempted = true;
-    void this.start().catch((err) => {
+    const origin = new Error("hot cache: background start() was triggered by this call");
+    const reportStartFailure = (err) => {
+      const wrapped = err instanceof Error ? err : new Error(String(err));
+      if (wrapped.cause === void 0) wrapped.cause = origin;
       this.logger.warn?.(
-        { error: err instanceof Error ? err.message : String(err) },
+        { error: wrapped.message, stack: wrapped.stack, trigger: origin.stack },
         "hot cache start failed; reads continue without auto-refresh"
       );
-    });
+    };
+    this.start().catch(reportStartFailure);
   }
   defaultProbe = async () => {
     for (const q of this.queries.values()) {
       for (const ref of q.config.watch ?? []) {
-        const caps = await probeMongoCapabilities(ref.db);
+        let db;
+        try {
+          db = resolveWatchDb(ref);
+        } catch {
+          this.logger.warn?.(
+            {},
+            "hot cache: replica probe could not resolve the watch db (accessor threw) \u2014 falling back to the standalone ticker; pass `mode` or a custom `probe` to pin the behavior"
+          );
+          return false;
+        }
+        const caps = await probeMongoCapabilities(db);
         if (!caps.probed) {
           this.logger.warn?.(
-            { db: ref.db.databaseName },
+            { db: db.databaseName },
             "hot cache: replica probe returned no result (timeout?) \u2014 falling back to the standalone ticker; pass `mode` or a custom `probe` to pin the behavior"
           );
           return false;
@@ -854,17 +1128,18 @@ var HotCache = class {
     return false;
   };
   fetch(q, key, args, gen) {
-    const dedupeKey = `${q.name}${WATCH_SEP}${key}`;
-    return this.inflight.run(dedupeKey, async () => {
+    const dedupeKey = `${q.name}${WATCH_SEP}g${gen}${WATCH_SEP}${key}`;
+    const loadOnce = async () => {
       try {
         const value = await q.config.loader(...args);
         if (q.gen === gen) {
-          if (q.maxValueBytes !== void 0 && estimateSize(value) > q.maxValueBytes) {
+          const bytes = q.maxValueBytes !== void 0 ? estimateSize(value) : void 0;
+          if (bytes !== void 0 && bytes > q.maxValueBytes) {
             q.sizeSkips++;
             if (!q.warnedSize) {
               q.warnedSize = true;
               this.logger.warn?.(
-                { query: q.name, bytes: estimateSize(value), max: q.maxValueBytes },
+                { query: q.name, bytes, max: q.maxValueBytes },
                 "hot cache: value exceeds maxValueBytes \u2014 returned but not cached"
               );
             }
@@ -877,17 +1152,42 @@ var HotCache = class {
         q.loadErrors++;
         throw err;
       }
-    });
+    };
+    return this.inflight.run(dedupeKey, loadOnce);
   }
   setEntry(q, key, args, value) {
     const now = Date.now();
+    const deps2 = q.hasIdWatch ? this.computeDeps(q, args) : {};
     q.lru.set(key, {
       value,
       args,
       expiresAt: q.ttlMs > 0 ? now + q.ttlMs : Infinity,
-      nextRefreshAt: q.refreshIntervalMs > 0 ? now + q.refreshIntervalMs : Infinity
+      nextRefreshAt: q.refreshIntervalMs > 0 ? now + q.refreshIntervalMs : Infinity,
+      ...deps2
     });
   }
+  /**
+   * Extract the watched-document dependencies of one loader call. Namespaced by
+   * collection so multi-collection watchers never cross-invalidate. An extractor
+   * that throws or returns a non-array yields `{ depsAll: true }` — the entry is
+   * then dropped by ANY targeted change on its watched collections instead of
+   * being incorrectly kept.
+   */
+  computeDeps(q, args) {
+    const deps2 = [];
+    for (const ref of q.config.watch ?? []) {
+      if (!ref.idsOf) continue;
+      const extract = ref.idsOf;
+      try {
+        const ids = extract(...args);
+        if (!Array.isArray(ids)) return { depsAll: true };
+        for (const id of ids) deps2.push(`${ref.collection}${WATCH_SEP}${normalizeWatchId(id)}`);
+      } catch {
+        return { depsAll: true };
+      }
+    }
+    return { deps: deps2 };
+  }
 };
 var createHotCache = (options) => new HotCache(options);
 
@@ -898,6 +1198,12 @@ var cacheCollectionKey = (dbName, physical) => `${dbName}${NS_SEP}${physical}`;
 var QueryCache = class {
   lru;
   index = /* @__PURE__ */ new Map();
+  /**
+   * Reverse index: key → every collection it is registered under. Without it,
+   * keys dropped by TTL expiry / capacity eviction / version-guard would stay
+   * listed in `index` forever (unbounded growth + O(dead) invalidation scans).
+   */
+  keyCollections = /* @__PURE__ */ new Map();
   /** Per-collection version — bumped on every invalidation/clear of that collection. */
   colVersions = /* @__PURE__ */ new Map();
   ttlMs;
@@ -909,7 +1215,10 @@ var QueryCache = class {
   invalidateEvents = 0;
   clearEvents = 0;
   constructor(options = {}) {
-    this.lru = new LRU({ max: options.maxSize ?? 500 });
+    this.lru = new LRU({
+      max: options.maxSize ?? 500,
+      onEvict: (key) => this.unregisterKey(key)
+    });
     this.ttlMs = options.ttlMs ?? 0;
     this.clone = options.clone ?? false;
   }
@@ -949,14 +1258,14 @@ var QueryCache = class {
       return void 0;
     }
     if (this.ttlMs > 0 && Date.now() > entry.expiresAt) {
-      this.lru.delete(key);
+      this.dropKey(key);
       this.misses++;
       return void 0;
     }
     if (entry.versions) {
       for (const [col, ver] of Object.entries(entry.versions)) {
         if (this.versionOf(col) !== ver) {
-          this.lru.delete(key);
+          this.dropKey(key);
           this.misses++;
           return void 0;
         }
@@ -965,6 +1274,23 @@ var QueryCache = class {
     this.hits++;
     return this.clone ? cloneDeep(entry.value) : entry.value;
   }
+  /** Remove a key from the LRU and every collection index that references it. */
+  dropKey(key) {
+    this.lru.delete(key);
+    this.unregisterKey(key);
+  }
+  /** Remove `key` from `index` (called for evictions AND explicit drops). */
+  unregisterKey(key) {
+    const collections = this.keyCollections.get(key);
+    if (!collections) return;
+    this.keyCollections.delete(key);
+    for (const collection of collections) {
+      const keys = this.index.get(collection);
+      if (!keys) continue;
+      keys.delete(key);
+      if (keys.size === 0) this.index.delete(collection);
+    }
+  }
   set(key, value, ttlMs, collections, versions) {
     this.sets++;
     const ttl = ttlMs ?? this.ttlMs;
@@ -977,6 +1303,7 @@ var QueryCache = class {
     const sep = key.indexOf(SEP);
     const primary = sep === -1 ? key : key.slice(0, sep);
     const collectionKeys = /* @__PURE__ */ new Set([primary, ...collections ?? []]);
+    this.keyCollections.set(key, collectionKeys);
     for (const collection of collectionKeys) {
       let keys = this.index.get(collection);
       if (!keys) {
@@ -988,7 +1315,7 @@ var QueryCache = class {
   }
   delete(key) {
     this.deletes++;
-    this.lru.delete(key);
+    this.dropKey(key);
   }
   /** Drop every cached entry belonging to a physical collection. */
   invalidateByCollection(collection) {
@@ -996,7 +1323,7 @@ var QueryCache = class {
     const keys = this.index.get(collection);
     if (!keys) return;
     this.invalidateEvents++;
-    for (const key of keys) this.lru.delete(key);
+    for (const key of [...keys]) this.dropKey(key);
     this.index.delete(collection);
   }
   clear() {
@@ -1006,21 +1333,35 @@ var QueryCache = class {
     }
     this.lru.clear();
     this.index.clear();
+    this.keyCollections.clear();
   }
 };
 
 // src/graceful-transaction.ts
 var withGracefulMongoTransaction = async (runner, fn, options = {}) => {
-  const enabled = options.capabilities === void 0 || mongoTransactionsEnabled(options.capabilities, {
-    ...options.urlHint !== void 0 ? { urlHint: options.urlHint } : {}
-  });
+  let enabled = true;
+  if (options.capabilities !== void 0) {
+    const env = readMongoTransactionsEnvOverride();
+    if (env !== void 0) {
+      enabled = env;
+    } else {
+      const state = options.capabilities.get();
+      if (state.probed) {
+        enabled = state.transactionsSupported;
+      } else if (options.urlHint) {
+        enabled = /replicaSet=|mongodb\+srv:/i.test(options.urlHint);
+      }
+    }
+  }
   if (!enabled) return fn(null);
   try {
     return await runner.transaction(fn);
   } catch (err) {
-    const message = err instanceof Error ? err.message : "";
-    if (/Transaction numbers are only allowed|transactions are not supported/i.test(message)) {
-      options.logger?.warn?.({ error: message }, "transactions unsupported, falling back");
+    if (isTransactionUnsupportedError(err)) {
+      options.logger?.warn?.(
+        { error: err instanceof Error ? err.message : String(err) },
+        "transactions unsupported, falling back"
+      );
       return fn(null);
     }
     if (options.wrapMongoErrors !== false) {
@@ -1119,13 +1460,17 @@ var DataLoader = class {
     }
   }
   async flush() {
-    if (this.flushing) return;
+    if (this.flushing) {
+      this.scheduled = false;
+      return;
+    }
     if (this.queue.length === 0) {
       this.scheduled = false;
       return;
     }
     const items = this.queue.splice(0, this.maxBatchSize);
     this.flushing = true;
+    this.scheduled = false;
     try {
       const resultMap = await this.batchFn(items.map((item) => item.key));
       for (const item of items) {
@@ -1140,12 +1485,8 @@ var DataLoader = class {
       }
     } finally {
       this.flushing = false;
-      this.scheduled = false;
-      if (this.queue.length > 0) {
-        this.scheduled = true;
-        queueMicrotask(() => {
-          void this.flush();
-        });
+      if (!this.scheduled && this.queue.length > 0) {
+        this.scheduleFlush();
       }
     }
   }
@@ -1156,6 +1497,7 @@ var canonicalKey = (value) => {
     const anyValue = value;
     if (typeof anyValue.toHexString === "function") return `oid:${anyValue.toHexString()}`;
     if (value instanceof Date) return `date:${value.getTime()}`;
+    return `obj:${stableStringify(value)}`;
   }
   return `${typeof value}:${String(value)}`;
 };
@@ -1166,13 +1508,14 @@ var JOURNAL_COLLECTION = "_migrations";
 
 // src/migrations/files.ts
 var migrationNameOf = (file) => basename(file).replace(/\.(ts|js|mjs)$/, "");
+var numericPrefixOf = (file) => Number(MIGRATION_FILE.exec(basename(file))?.[1] ?? Number.MAX_SAFE_INTEGER);
 var listMigrationFiles = async (dir) => {
   const files = await readdir(dir);
-  return files.filter((file) => MIGRATION_FILE.test(file)).sort();
+  return files.filter((file) => MIGRATION_FILE.test(file)).sort((a, b) => numericPrefixOf(a) - numericPrefixOf(b) || a.localeCompare(b));
 };
 var loadMigration = async (dir, file) => {
   const mod = await import(pathToFileURL(join(dir, file)).href);
-  return { name: migrationNameOf(file), ...mod };
+  return { ...mod, name: migrationNameOf(file) };
 };
 var ensureMigrationDir = async (dir) => {
   await mkdir(dir, { recursive: true });
@@ -1186,45 +1529,78 @@ var nextMigrationNumber = async (dir) => {
 };
 
 // src/migrations/journal.ts
+var isDuplicateKeyError = (err) => {
+  const code = err?.code;
+  if (code === 11e3 || code === 11001) return true;
+  return /E11000 duplicate key/.test(String(err?.message ?? ""));
+};
 var createMigrationJournal = (manager) => {
+  let indexReady = false;
+  const ensureIndex = async () => {
+    if (indexReady) return;
+    try {
+      await manager.createIndex?.(JOURNAL_COLLECTION, { name: 1 }, { unique: true });
+    } catch {
+    }
+    indexReady = true;
+  };
   const appliedNames = async () => {
     const rows = await manager.findMany(JOURNAL_COLLECTION);
     return new Set(
       rows.filter((row) => row.status === void 0 || row.status === "applied").map((row) => row.name)
     );
   };
-  const cleanupStale = async () => {
-    await manager.deleteMany(JOURNAL_COLLECTION, {
-      status: "running",
-      appliedAt: { $lt: new Date(Date.now() - 6e4) }
-    }).catch(() => {
-    });
+  const stealableFilter = (name, now, staleCutoff) => ({
+    name,
+    status: { $ne: "applied" },
+    $or: [
+      { expiresAt: { $lt: now } },
+      { expiresAt: { $exists: false }, appliedAt: { $lt: staleCutoff } },
+      { status: { $nin: ["running", "applied"] } }
+    ]
+  });
+  const claim = async (name, file, leaseMs) => {
+    await ensureIndex();
+    const now = /* @__PURE__ */ new Date();
+    const expiresAt = new Date(Date.now() + leaseMs);
+    const stole = await manager.findOneAndUpdate(
+      JOURNAL_COLLECTION,
+      stealableFilter(name, now, new Date(Date.now() - leaseMs)),
+      { $set: { status: "running", appliedAt: now, file, expiresAt } },
+      { returnDocument: "before" }
+    );
+    if (stole !== null) return true;
+    try {
+      await manager.insertOne(JOURNAL_COLLECTION, {
+        name,
+        appliedAt: now,
+        status: "running",
+        file,
+        expiresAt
+      });
+      return true;
+    } catch (err) {
+      if (isDuplicateKeyError(err)) return false;
+      throw err;
+    }
   };
-  const claim = async (name, file) => {
-    const claimed = await manager.findOneAndUpdate(
+  const renew = async (name, leaseMs) => {
+    await manager.updateOne(
       JOURNAL_COLLECTION,
-      { name },
-      {
-        $setOnInsert: {
-          name,
-          appliedAt: /* @__PURE__ */ new Date(),
-          status: "running",
-          file
-        }
-      },
-      { upsert: true, returnDocument: "before" }
+      { name, status: "running" },
+      { $set: { expiresAt: new Date(Date.now() + leaseMs) } }
     );
-    return claimed === null;
   };
   const markApplied = async (name) => {
-    await manager.updateOne(JOURNAL_COLLECTION, { name, status: "running" }, { $set: { status: "applied" } }).catch(async () => {
-      await manager.insertOne(JOURNAL_COLLECTION, {
-        name,
-        appliedAt: /* @__PURE__ */ new Date(),
-        status: "applied"
-      }).catch(() => {
+    const res = await manager.updateOne(
+      JOURNAL_COLLECTION,
+      { name, status: "running" },
+      { $set: { status: "applied" } }
+    );
+    if (res?.matchedCount === 0) {
+      await manager.insertOne(JOURNAL_COLLECTION, { name, appliedAt: /* @__PURE__ */ new Date(), status: "applied" }).catch(() => {
       });
-    });
+    }
   };
   const removeRunning = async (name) => {
     await manager.deleteOne(JOURNAL_COLLECTION, { name, status: "running" }).catch(() => {
@@ -1233,45 +1609,76 @@ var createMigrationJournal = (manager) => {
   const unrecord = async (name) => {
     await manager.deleteOne(JOURNAL_COLLECTION, { name });
   };
-  return { appliedNames, cleanupStale, claim, markApplied, removeRunning, unrecord };
+  return { appliedNames, claim, renew, markApplied, removeRunning, unrecord };
 };
 
 // src/migrations/index.ts
+var DEFAULT_LEASE_MS = 12e4;
 var createMongoMigrationRunner = (service, options = {}) => {
   const migrationDir = options.migrationDir ?? service.config?.migrationDir ?? "./migrations";
   const logger = options.logger ?? service.logger;
+  const leaseMs = options.leaseMs ?? DEFAULT_LEASE_MS;
   const manager = () => {
-    const key = Object.keys(service.db)[0];
+    const keys = Object.keys(service.db);
+    const key = options.db !== void 0 ? options.db : keys[0];
     const db = key ? service.db[key] : void 0;
-    if (!db) throw new Error("No database client connected \u2014 call service.makeConnections() first");
+    if (!db) {
+      throw new Error(
+        options.db !== void 0 && !keys.includes(options.db) ? `Unknown database "${options.db}" \u2014 connected: ${keys.join(", ")}` : "No database client connected \u2014 call service.makeConnections() first"
+      );
+    }
     return db;
   };
+  const startHeartbeat = (journal, name) => {
+    const timer = setInterval(
+      () => {
+        void journal.renew(name, leaseMs).catch(() => {
+        });
+      },
+      Math.max(leaseMs / 2, 1e3)
+    );
+    timer.unref?.();
+    return () => clearInterval(timer);
+  };
   const up = async () => {
     await ensureMigrationDir(migrationDir);
     const journal = createMigrationJournal(manager());
-    await journal.cleanupStale();
     const files = await listMigrationFiles(migrationDir);
     const applied = await journal.appliedNames();
     const pending = files.filter((file) => !applied.has(migrationNameOf(file)));
     for (const file of pending) {
       const migration = await loadMigration(migrationDir, file);
       logger.info({ name: migration.name }, "running migration up");
-      if (!await journal.claim(migration.name, basename(file))) {
-        logger.info({ name: migration.name }, "migration already applied, skipping");
+      if (!await journal.claim(migration.name, basename(file), leaseMs)) {
+        logger.info(
+          { name: migration.name },
+          "migration claimed by another runner or already applied, skipping"
+        );
         continue;
       }
+      const stopHeartbeat = startHeartbeat(journal, migration.name);
       try {
         await migration.up({ service, logger, name: migration.name });
         await journal.markApplied(migration.name);
       } catch (err) {
         await journal.removeRunning(migration.name);
         throw err;
+      } finally {
+        stopHeartbeat();
       }
       logger.info({ name: migration.name }, "migration applied");
     }
   };
   const down = async (targetName) => {
     const files = await listMigrationFiles(migrationDir);
+    if (targetName !== void 0) {
+      const known = files.some((file) => migrationNameOf(file) === targetName);
+      if (!known) {
+        throw new Error(
+          `down(): unknown migration "${targetName}" \u2014 known: ${files.map(migrationNameOf).join(", ") || "(none)"}`
+        );
+      }
+    }
     const journal = createMigrationJournal(manager());
     const applied = await journal.appliedNames();
     const appliedFiles = files.filter((file) => applied.has(migrationNameOf(file))).reverse();
@@ -1281,7 +1688,7 @@ var createMongoMigrationRunner = (service, options = {}) => {
       await migration.down({ service, logger, name: migration.name });
       await journal.unrecord(migration.name);
       logger.info({ name: migration.name }, "migration rolled back");
-      if (targetName && migration.name === targetName) break;
+      if (targetName !== void 0 && migration.name === targetName) break;
     }
   };
   const status = async () => {
@@ -1295,10 +1702,6 @@ var createMongoMigrationRunner = (service, options = {}) => {
   };
   const create = async (name) => {
     await ensureMigrationDir(migrationDir);
-    const next = await nextMigrationNumber(migrationDir);
-    const padded = String(next).padStart(3, "0");
-    const fileName = `${padded}_${name}.ts`;
-    const filePath = join(migrationDir, fileName);
     const template = `import type { MigrationContext } from '@ignex/ninox';
 
 export const up = async (ctx: MigrationContext): Promise<void> => {
@@ -1311,15 +1714,26 @@ export const down = async (ctx: MigrationContext): Promise<void> => {
   // await users.client.dropCollection('users');
 };
 `;
-    await writeFile(filePath, template, "utf8");
-    logger.info({ name, file: fileName }, "migration scaffolded");
-    return filePath;
+    for (; ; ) {
+      const next = await nextMigrationNumber(migrationDir);
+      const padded = String(next).padStart(3, "0");
+      const fileName = `${padded}_${name}.ts`;
+      const filePath = join(migrationDir, fileName);
+      try {
+        await writeFile(filePath, template, { encoding: "utf8", flag: "wx" });
+        logger.info({ name, file: fileName }, "migration scaffolded");
+        return filePath;
+      } catch (err) {
+        if (err?.code === "EEXIST") continue;
+        throw err;
+      }
+    }
   };
   return { up, down, status, create };
 };
 
 // src/mongo-helpers.ts
-var withRetry = async (fn, options = {}, _ctx) => {
+var withRetry = async (fn, options = {}) => {
   const maxAttempts = Math.max(1, options.maxAttempts ?? 3);
   const delayMs = options.delayMs ?? 150;
   const logger = options.logger;
@@ -1332,7 +1746,8 @@ var withRetry = async (fn, options = {}, _ctx) => {
       lastError = err;
       attempt += 1;
       if (attempt >= maxAttempts || !isMongoTransientError(err)) throw err;
-      const backoff = delayMs * 2 ** (attempt - 1);
+      const base = delayMs * 2 ** (attempt - 1);
+      const backoff = Math.round(base * (0.8 + Math.random() * 0.4));
       logger?.debug?.({ attempt, backoffMs: backoff, error: err?.message }, "retrying");
       await sleep(backoff);
     }
@@ -1362,7 +1777,13 @@ var DEFAULT_FIND_LIMIT = 100;
 var MAX_BATCH_OPS = 1e5;
 
 // src/query-builder/query-builder.ts
-var QueryBuilder = class {
+var mergeFilterKey = (prev, next) => {
+  if (prev !== null && typeof prev === "object" && !Array.isArray(prev) && next !== null && typeof next === "object" && !Array.isArray(next)) {
+    return { ...prev, ...next };
+  }
+  return next;
+};
+var QueryBuilder = class _QueryBuilder {
   constructor(ctx) {
     this.ctx = ctx;
   }
@@ -1375,77 +1796,112 @@ var QueryBuilder = class {
   get filter() {
     return this._filter;
   }
-  /** Shallow-merge a filter into the current one (later keys win). */
+  /** Copy-on-write fork used by every chain method. */
+  fork() {
+    const next = new _QueryBuilder(this.ctx);
+    next._filter = this._filter;
+    if (this._sort !== void 0) next._sort = this._sort;
+    if (this._skip !== void 0) next._skip = this._skip;
+    if (this._limit !== void 0) next._limit = this._limit;
+    if (this._projection !== void 0) next._projection = this._projection;
+    next._options = { ...this._options };
+    return next;
+  }
+  /** Merge a filter into the current one (operator docs deep-merge per key). */
   where(filter) {
-    this._filter = { ...this._filter, ...filter };
-    return this;
+    const next = this.fork();
+    const merged = { ...next._filter };
+    for (const [key, value] of Object.entries(filter)) {
+      merged[key] = key in merged ? mergeFilterKey(merged[key], value) : value;
+    }
+    next._filter = merged;
+    return next;
   }
-  /** AND-combine the current filter with a new one. */
+  /** AND-combine the current filter with a new one (stays flat across repeats). */
   and(filter) {
-    this._filter = { $and: [this._filter, filter] };
-    return this;
+    const next = this.fork();
+    const current = next._filter;
+    const existing = Array.isArray(current.$and) ? current.$and : Object.keys(current).length > 0 ? [current] : [];
+    next._filter = { $and: [...existing, filter] };
+    return next;
   }
-  /** OR-combine: current filter AND (filter1 OR filter2 ...). */
+  /**
+   * OR-combine: current filter AND (filter1 OR filter2 ...). Requires at least
+   * one filter — an empty `$or` is rejected by the server.
+   */
   or(...filters) {
-    this._filter = { $and: [this._filter, { $or: filters }] };
-    return this;
+    if (filters.length === 0) {
+      throw new BadRequest("QueryBuilder.or() requires at least one filter");
+    }
+    return this.and(filters.length === 1 ? filters[0] : { $or: filters });
   }
   /** Set the sort order (`{ field: 1 | -1 }`). */
   sort(sort) {
-    this._sort = sort;
-    return this;
+    const next = this.fork();
+    next._sort = sort;
+    return next;
   }
   /** Skip the first `n` matching documents. */
   skip(n) {
-    this._skip = n;
-    return this;
+    const next = this.fork();
+    next._skip = n;
+    return next;
   }
   /** Limit the result set to `n` documents. */
   limit(n) {
-    this._limit = n;
-    return this;
+    const next = this.fork();
+    next._limit = n;
+    return next;
   }
   /** Project only the given fields — the projection is pushed to the driver. */
   select(fields) {
+    const next = this.fork();
     const projection = {};
     for (const field of fields) projection[field] = 1;
-    this._projection = projection;
-    return this;
+    next._projection = projection;
+    return next;
   }
   /** Raw projection document (`{ field: 1 }` / `{ field: 0 }`). */
   project(projection) {
-    this._projection = projection;
-    return this;
+    const next = this.fork();
+    next._projection = projection;
+    return next;
   }
   /** Set the index hint. */
   hint(hint) {
-    this._options.hint = hint;
-    return this;
+    const next = this.fork();
+    next._options.hint = hint;
+    return next;
   }
   /** Set the driver cursor batch size. */
   batchSize(n) {
-    this._options.batchSize = n;
-    return this;
+    const next = this.fork();
+    next._options.batchSize = n;
+    return next;
   }
   /** Run the query inside a transaction session. */
   session(session) {
-    this._options.session = session;
-    return this;
+    const next = this.fork();
+    next._options.session = session;
+    return next;
   }
   /** Cap server-side execution time. */
   maxTimeMS(ms) {
-    this._options.maxTimeMS = ms;
-    return this;
+    const next = this.fork();
+    next._options.maxTimeMS = ms;
+    return next;
   }
   /** Bypass the read cache for this query when `false`. */
   cache(on) {
-    this._options.cache = on;
-    return this;
+    const next = this.fork();
+    next._options.cache = on;
+    return next;
   }
   /** Override in-flight dedup for this query when set. */
   dedupe(on) {
-    this._options.dedupe = on;
-    return this;
+    const next = this.fork();
+    next._options.dedupe = on;
+    return next;
   }
   /** Compile the builder into driver options (does not execute). */
   compile() {
@@ -1487,7 +1943,7 @@ var QueryBuilder = class {
       options
     );
   }
-  /** Streaming cursor (raw driver cursor; no retry, applies batchSize). */
+  /** Streaming cursor (raw driver cursor; no retry/cache/drift — caller-owned). */
   cursor() {
     return this.ctx.collection.find(
       this._filter,
@@ -1503,9 +1959,21 @@ var QueryBuilder = class {
       this.countOptions()
     );
   }
-  /** True when at least one document matches. */
+  /** True when at least one document matches (`_id`-only projection — no doc transfer). */
   async exists() {
-    return await this.one() !== null;
+    const options = this.compile();
+    if (options.limit === void 0) options.limit = 1;
+    options.projection = { _id: 1 };
+    const doc = await this.ctx.run(
+      "mongo.exists",
+      this._filter,
+      (opts) => this.ctx.collection.findOne(
+        this._filter,
+        opts
+      ),
+      options
+    );
+    return doc !== null;
   }
 };
 
@@ -1536,8 +2004,9 @@ var createRepository = (manager, collection, options = {}) => {
     findOne: (filter, o) => manager.getOne(collection, filter, o),
     findOneOrFail: (filter, o) => manager.getOneOrFail(collection, filter, o),
     findMany: (filter, o) => manager.findMany(collection, filter, {
-      ...o ?? {},
-      ...options.limit !== void 0 ? { limit: options.limit } : {}
+      // Repository `limit` is a DEFAULT — a per-call option must win.
+      ...options.limit !== void 0 ? { limit: options.limit } : {},
+      ...o ?? {}
     }),
     findActive: (filter, o) => manager.findActive(collection, filter, o),
     count: (filter, o) => manager.countDocuments(collection, filter, o),
@@ -1565,9 +2034,25 @@ var createRepository = (manager, collection, options = {}) => {
 
 // src/schema/collections.ts
 var resolveItemName = (item) => "schema" in item ? item.schema.name : item.name;
+var assertTimestampsDeclared = (name, schema, timestamps) => {
+  const ts = typeof timestamps === "boolean" ? {} : timestamps;
+  const createdAt = ts.createdAt ?? "createdAt";
+  const updatedAt = ts.updatedAt ?? "updatedAt";
+  const properties = schema.properties ?? {};
+  for (const field of [createdAt, updatedAt]) {
+    if (!(field in properties)) {
+      throw new Error(
+        `defineCollections: "${name}" enables timestamps but its schema does not declare the field "${field}". Add \`${field}: s.date().optional()\` to the schema (or adjust \`timestamps\`) \u2014 otherwise strict validation rejects every stamped write.`
+      );
+    }
+  }
+};
 var resolveItemValue = (item) => {
   if ("schema" in item) {
     const def = item;
+    if (def.timestamps !== void 0) {
+      assertTimestampsDeclared(def.name, def.schema, def.timestamps);
+    }
     return {
       schema: def.schema,
       ...def.indexes ? { indexes: def.indexes } : {},
@@ -1579,6 +2064,9 @@ var resolveItemValue = (item) => {
 };
 var defineCollection = (name, schema, extras = {}) => {
   const namedSchema = { ...schema, name };
+  if (extras.timestamps !== void 0) {
+    assertTimestampsDeclared(name, schema, extras.timestamps);
+  }
   return {
     name,
     schema: namedSchema,
@@ -1608,6 +2096,11 @@ var addNumericBounds = (out, field) => {
   if (field.exclusiveMaximum) out.exclusiveMaximum = true;
   return out;
 };
+var NUMERIC_WIRE_UNION = {
+  double: ["double", "int", "long"],
+  long: ["long", "int", "double"]
+};
+var INTEGER_WIRE_UNION = ["int", "long", "double"];
 var convertField = (field) => {
   if (field.kind === "raw") {
     const out2 = { ...field.fragment };
@@ -1624,13 +2117,15 @@ var convertField = (field) => {
       if (field.pattern) out.pattern = field.pattern;
       return out;
     case "number":
-      out.bsonType = field.integer ? "int" : "number";
+      out.bsonType = field.integer ? [...INTEGER_WIRE_UNION] : "number";
+      if (field.integer && field.multipleOf === void 0) out.multipleOf = 1;
       return addNumericBounds(out, field);
     case "double":
-      out.bsonType = "double";
+      out.bsonType = [...NUMERIC_WIRE_UNION.double];
       return addNumericBounds(out, field);
     case "long":
-      out.bsonType = "long";
+      out.bsonType = [...NUMERIC_WIRE_UNION.long];
+      if (field.multipleOf === void 0) out.multipleOf = 1;
       return addNumericBounds(out, field);
     case "decimal":
       out.bsonType = "decimal";
@@ -1646,6 +2141,7 @@ var convertField = (field) => {
       return out;
     case "geoPoint":
       return {
+        ...field.description ? { description: field.description } : {},
         bsonType: "object",
         required: ["type", "coordinates"],
         properties: {
@@ -1671,7 +2167,10 @@ var convertField = (field) => {
         else if (typeof v === "string") types.add("string");
         else if (typeof v === "number") {
           const allInt = field.values.every((x) => typeof x !== "number" || Number.isInteger(x));
-          types.add(allInt ? "int" : "number");
+          const fitsInt32 = allInt && field.values.every(
+            (x) => typeof x !== "number" || x >= -2147483648 && x <= 2147483647
+          );
+          types.add(allInt && fitsInt32 ? "int" : "number");
           break;
         }
       }
@@ -1825,6 +2324,10 @@ var numericValue = (value) => {
     const n = Number(value.toString());
     return Number.isNaN(n) ? void 0 : n;
   }
+  if (value instanceof Long) {
+    const n = value.toNumber();
+    return Number.isNaN(n) ? void 0 : n;
+  }
   if (typeof value === "number" && !Number.isNaN(value)) return value;
   return void 0;
 };
@@ -1882,7 +2385,7 @@ var bsonTypeMatches = (bsonType, value) => {
     case "double":
       return typeof value === "number" && !Number.isNaN(value);
     case "long":
-      return typeof value === "number" && Number.isInteger(value);
+      return typeof value === "number" && Number.isInteger(value) || value instanceof Long;
     case "decimal":
       return value instanceof Decimal128;
     default:
@@ -1904,6 +2407,19 @@ var checkReservedValue = (key, value, path, issues) => {
 };
 
 // src/schema/validate-doc/field-validators.ts
+var patternCache = /* @__PURE__ */ new WeakMap();
+var compiledPattern = (field) => {
+  if (!field.pattern) return void 0;
+  const cached = patternCache.get(field);
+  if (cached) return cached;
+  try {
+    const re = new RegExp(field.pattern);
+    patternCache.set(field, re);
+    return re;
+  } catch {
+    return void 0;
+  }
+};
 var stringValidator = (_deps, field, value, path, issues) => {
   const f = field;
   if (typeof value !== "string") {
@@ -1928,19 +2444,15 @@ var stringValidator = (_deps, field, value, path, issues) => {
       `Length ${value.length} > ${f.maxLength}`
     );
   }
-  if (f.pattern) {
-    try {
-      if (!new RegExp(f.pattern).test(value)) {
-        push(
-          issues,
-          path,
-          "constraint",
-          `string(pattern ${f.pattern})`,
-          `"${value}" does not match pattern`
-        );
-      }
-    } catch {
-    }
+  const pattern = compiledPattern(f);
+  if (pattern && !pattern.test(value)) {
+    push(
+      issues,
+      path,
+      "constraint",
+      `string(pattern ${f.pattern})`,
+      `"${value}" does not match pattern`
+    );
   }
 };
 var numberValidator = (_deps, field, value, path, issues) => {
@@ -1957,7 +2469,7 @@ var numberValidator = (_deps, field, value, path, issues) => {
 };
 var floatingValidator = (_deps, field, value, path, issues) => {
   const f = field;
-  const ok = f.kind === "decimal" ? value instanceof Decimal128 : f.kind === "long" ? typeof value === "number" && Number.isInteger(value) : typeof value === "number" && !Number.isNaN(value);
+  const ok = f.kind === "decimal" ? value instanceof Decimal128 : f.kind === "long" ? typeof value === "number" && Number.isInteger(value) || value instanceof Long : typeof value === "number" && !Number.isNaN(value);
   if (!ok) {
     push(issues, path, "type", f.kind, `Expected ${f.kind}, got ${describeValue(value)}`);
     return;
@@ -2114,7 +2626,7 @@ function validateObjectProps(field, value, path, issues, topLevel) {
     validateValue(prop, value[key], propPath(key), issues);
   }
   if (field.additionalProperties !== true) {
-    const allowedReserved = topLevel ? /* @__PURE__ */ new Set(["_id", ...Object.keys(ORM_RESERVED_FIELDS)]) : /* @__PURE__ */ new Set();
+    const allowedReserved = topLevel ? ALLOWED_RESERVED_TOP : NO_RESERVED;
     for (const key of Object.keys(value)) {
       if (key in field.properties) continue;
       if (allowedReserved.has(key)) continue;
@@ -2161,6 +2673,11 @@ function validateObjectProps(field, value, path, issues, topLevel) {
   }
 }
 var deps = { validateValue, validateObjectProps };
+var ALLOWED_RESERVED_TOP = /* @__PURE__ */ new Set([
+  "_id",
+  ...Object.keys(ORM_RESERVED_FIELDS)
+]);
+var NO_RESERVED = /* @__PURE__ */ new Set();
 var validateDoc = (schema, doc) => {
   const issues = [];
   if (doc === null || typeof doc !== "object" || Array.isArray(doc)) {
@@ -2187,15 +2704,23 @@ var createResolveCollectionName = (config) => {
 // src/service/connection-uri.ts
 var normalizeMongoUrl = (rawUrl) => {
   try {
-    const url = new URL(rawUrl);
-    if (!url.searchParams.has("retryWrites")) url.searchParams.set("retryWrites", "false");
-    const hasWriteConcern = url.searchParams.has("w") || url.searchParams.has("wtimeoutMS") || url.searchParams.has("writeConcern");
-    if (!hasWriteConcern) url.searchParams.set("w", "1");
-    const hostCount = url.hostname.split(",").length;
-    if (hostCount === 1 && !url.searchParams.has("replicaSet") && !url.searchParams.has("directConnection")) {
-      url.searchParams.set("directConnection", "true");
+    const qIndex = rawUrl.indexOf("?");
+    const base = qIndex === -1 ? rawUrl : rawUrl.slice(0, qIndex);
+    const query = qIndex === -1 ? "" : rawUrl.slice(qIndex + 1);
+    const params = new URLSearchParams(query);
+    if (!params.has("retryWrites")) params.set("retryWrites", "false");
+    const hasWriteConcern = params.has("w") || params.has("wtimeoutMS") || params.has("writeConcern");
+    if (!hasWriteConcern) params.set("w", "1");
+    const schemeSep = base.indexOf("://");
+    const authority = schemeSep === -1 ? base : base.slice(schemeSep + 3).split("/")[0] ?? "";
+    const hostPart = authority.includes("@") ? authority.split("@").pop() ?? "" : authority;
+    const hostCount = hostPart === "" ? 0 : hostPart.split(",").length;
+    const isSrv = base.startsWith("mongodb+srv://");
+    if (!isSrv && hostCount === 1 && !params.has("replicaSet") && !params.has("directConnection")) {
+      params.set("directConnection", "true");
     }
-    return url.toString();
+    const queryString = params.toString();
+    return queryString ? `${base}?${queryString}` : base;
   } catch {
     return rawUrl;
   }
@@ -2231,7 +2756,12 @@ var CacheInvalidator = class {
       const key = `${ref.db.databaseName}${SEP2}${ref.collection}`;
       if (seen.has(key) || this.streams.has(key)) continue;
       seen.add(key);
-      void this.watchLoop(key, ref);
+      void this.watchLoop(key, ref).catch((err) => {
+        this.logger.error?.(
+          { error: err instanceof Error ? err.message : String(err), collection: ref.collection },
+          "cacheWatch: watcher crashed"
+        );
+      });
     }
   }
   /** Close every watcher. Safe to call repeatedly, and before any `start`. */
@@ -2251,11 +2781,17 @@ var CacheInvalidator = class {
   async watchLoop(key, ref) {
     let backoff = 0;
     while (!this.stopped) {
+      let connectedAt = Date.now();
       try {
         const stream = ref.db.collection(ref.collection).watch([]);
-        stream.on("error", () => {
+        stream.on("error", (err) => {
+          this.logger.debug?.(
+            { error: err instanceof Error ? err.message : String(err) },
+            "cacheWatch: stream error event"
+          );
         });
         this.streams.set(key, stream);
+        connectedAt = Date.now();
         if (backoff > 0) {
           this.cache.invalidateByCollection(
             cacheCollectionKey(ref.db.databaseName, ref.collection)
@@ -2268,6 +2804,7 @@ var CacheInvalidator = class {
           );
         }
       } catch (err) {
+        if (Date.now() - connectedAt > 6e4) backoff = 0;
         const message = err instanceof Error ? err.message : String(err);
         const abandoned = this.streams.get(key);
         this.streams.delete(key);
@@ -2373,6 +2910,7 @@ var makeGetDbUrl = (dbClients, config) => (name) => {
   return normalizeMongoUrl(config.defaultDb);
 };
 var makeConnectionFactory = (dbClients, db, getDbUrl, buildManager2, openedClients = /* @__PURE__ */ new Map()) => {
+  const connecting = /* @__PURE__ */ new Map();
   return async (names) => {
     const keys = names && names.length > 0 ? names : Object.keys(dbClients);
     const openedThisCall = [];
@@ -2383,18 +2921,32 @@ var makeConnectionFactory = (dbClients, db, getDbUrl, buildManager2, openedClien
         const dbUrl = getDbUrl(key);
         let client = openedClients.get(dbUrl);
         if (!client) {
-          client = new MongoClient(dbUrl, {
-            connectTimeoutMS: definition.connectTimeoutMs ?? 1e4,
-            serverSelectionTimeoutMS: definition.connectTimeoutMs ?? 1e4,
-            ...definition.readPreference && { readPreference: definition.readPreference },
-            ...definition.readConcern && { readConcern: definition.readConcern },
-            ...definition.writeConcern && { writeConcern: definition.writeConcern }
-          });
-          client.on("error", () => {
-          });
-          openedClients.set(dbUrl, client);
-          openedThisCall.push({ url: dbUrl, client });
-          await client.connect();
+          const inflight = connecting.get(dbUrl);
+          if (inflight) {
+            client = await inflight;
+          } else {
+            const attempt = (async () => {
+              const c = new MongoClient(dbUrl, {
+                connectTimeoutMS: definition.connectTimeoutMs ?? 1e4,
+                serverSelectionTimeoutMS: definition.connectTimeoutMs ?? 1e4,
+                ...definition.readPreference && { readPreference: definition.readPreference },
+                ...definition.readConcern && { readConcern: definition.readConcern },
+                ...definition.writeConcern && { writeConcern: definition.writeConcern }
+              });
+              c.on("error", () => {
+              });
+              await c.connect();
+              return c;
+            })();
+            connecting.set(dbUrl, attempt);
+            try {
+              client = await attempt;
+              openedClients.set(dbUrl, client);
+              openedThisCall.push({ url: dbUrl, client });
+            } finally {
+              connecting.delete(dbUrl);
+            }
+          }
         }
         const dbKey = `${key}Client`;
         db[dbKey] = buildManager2(key, definition.name, client);
@@ -2422,23 +2974,32 @@ var closeConnections = async (openedClients) => {
 };
 
 // src/service/health.ts
-var createHealth = (db) => async () => {
+var createHealth = (db, options = {}) => async () => {
   const started = performance.now();
+  const timeoutMs = options.timeoutMs ?? 2e3;
   const dbs = await Promise.all(
     Object.entries(db).map(async ([key, manager]) => {
       const name = key.replace(/Client$/, "");
       const handle = manager?.client;
-      if (!handle) return { name, ok: false };
+      if (!handle) return { name, ok: false, error: "no client handle on manager" };
       try {
         const t0 = performance.now();
-        await withTimeout(handle.admin().command({ ping: 1 }), 2e3, `health:${name}`);
+        await withTimeout(handle.admin().command({ ping: 1 }), timeoutMs, `health:${name}`);
         return { name, ok: true, latencyMs: performance.now() - t0 };
-      } catch {
-        return { name, ok: false };
+      } catch (err) {
+        return {
+          name,
+          ok: false,
+          error: err instanceof Error ? err.message : String(err)
+        };
       }
     })
   );
-  return { ok: dbs.every((r) => r.ok), latencyMs: performance.now() - started, dbs };
+  return {
+    ok: dbs.length > 0 && dbs.every((r) => r.ok),
+    latencyMs: performance.now() - started,
+    dbs
+  };
 };
 
 // src/relation/populate.ts
@@ -2484,57 +3045,72 @@ var distinctKeys = (values) => {
 };
 var makePopulator = (deps2) => {
   const populate = async (docs, relations, options = {}) => {
-    for (const relation of relations) {
-      const target = relation.foreignField ?? "_id";
-      const sourceKeys = distinctKeys(docs.map((doc) => doc[relation.localField]));
-      if (relation.type === "belongsTo") {
-        const loader = createForeignKeyLoader(deps2, relation.collection, target, options);
-        const values = await loader.loadMany(sourceKeys);
-        const byKey = new Map(sourceKeys.map((key, i) => [canonicalKey(key), values[i]]));
-        for (const doc of docs) {
-          const key = doc[relation.localField];
-          const match = key === void 0 || key === null ? void 0 : byKey.get(canonicalKey(key))?.[0];
-          doc[relation.as] = match ?? (relation.optional ? void 0 : null);
-        }
-      } else if (relation.type === "hasMany") {
-        const loader = createForeignKeyLoader(deps2, relation.collection, target, options);
-        const values = await loader.loadMany(sourceKeys);
-        const byKey = new Map(sourceKeys.map((key, i) => [canonicalKey(key), values[i] ?? []]));
-        for (const doc of docs) {
-          const key = doc[relation.localField];
-          doc[relation.as] = key === void 0 || key === null ? [] : byKey.get(canonicalKey(key)) ?? [];
-        }
-      } else {
-        const throughLoader = createForeignKeyLoader(
-          deps2,
-          relation.through.collection,
-          relation.through.localField,
-          options
-        );
-        const throughValues = await throughLoader.loadMany(sourceKeys);
-        const throughByKey = new Map(
-          sourceKeys.map((key, i) => [canonicalKey(key), throughValues[i] ?? []])
-        );
-        const joinDocs = throughValues.flat();
-        const targetKeys = distinctKeys(
-          joinDocs.map((join3) => join3[relation.through.foreignField])
-        );
-        const targetLoader = createForeignKeyLoader(deps2, relation.collection, target, options);
-        const targetValues = await targetLoader.loadMany(targetKeys);
-        const targetByKey = new Map(
-          targetKeys.map((key, i) => [canonicalKey(key), targetValues[i] ?? []])
-        );
-        for (const doc of docs) {
-          const key = doc[relation.localField];
-          const joins = key === void 0 || key === null ? [] : throughByKey.get(canonicalKey(key)) ?? [];
-          const targets = joins.flatMap(
-            (join3) => targetByKey.get(canonicalKey(join3[relation.through.foreignField])) ?? []
+    const out = docs.map((doc) => ({ ...doc }));
+    if (out.length === 0 || relations.length === 0) return out;
+    const loaderCache = /* @__PURE__ */ new Map();
+    const loaderFor = (collection, foreignField) => {
+      const cacheKey = `${collection}\0${foreignField}`;
+      let loader = loaderCache.get(cacheKey);
+      if (!loader) {
+        loader = createForeignKeyLoader(deps2, collection, foreignField, options);
+        loaderCache.set(cacheKey, loader);
+      }
+      return loader;
+    };
+    const loadIndex = async (collection, foreignField, keys) => {
+      const values = await loaderFor(collection, foreignField).loadMany(keys);
+      const byKey = /* @__PURE__ */ new Map();
+      keys.forEach((key, i) => {
+        byKey.set(canonicalKey(key), values[i] ?? []);
+      });
+      return byKey;
+    };
+    await Promise.all(
+      relations.map(async (relation) => {
+        const target = relation.foreignField ?? "_id";
+        const sourceKeys = distinctKeys(out.map((doc) => doc[relation.localField]));
+        if (relation.type === "belongsTo") {
+          const byKey = await loadIndex(relation.collection, target, sourceKeys);
+          for (const doc of out) {
+            const key = doc[relation.localField];
+            const matches = key === void 0 || key === null ? void 0 : byKey.get(canonicalKey(key));
+            doc[relation.as] = matches?.[0] ?? (relation.optional ? void 0 : null);
+          }
+        } else if (relation.type === "hasMany") {
+          const byKey = await loadIndex(relation.collection, target, sourceKeys);
+          for (const doc of out) {
+            const key = doc[relation.localField];
+            doc[relation.as] = key === void 0 || key === null ? [] : byKey.get(canonicalKey(key)) ?? [];
+          }
+        } else {
+          const throughByKey = await loadIndex(
+            relation.through.collection,
+            relation.through.localField,
+            sourceKeys
           );
-          doc[relation.as] = targets;
+          const joinDocs = [...throughByKey.values()].flat();
+          const targetKeys = distinctKeys(
+            joinDocs.map((join3) => join3[relation.through.foreignField])
+          );
+          const targetByKey = await loadIndex(relation.collection, target, targetKeys);
+          for (const doc of out) {
+            const key = doc[relation.localField];
+            const joins = key === void 0 || key === null ? [] : throughByKey.get(canonicalKey(key)) ?? [];
+            const seenTargets = /* @__PURE__ */ new Set();
+            const targets = [];
+            for (const join3 of joins) {
+              const tk = canonicalKey(join3[relation.through.foreignField]);
+              if (seenTargets.has(tk)) continue;
+              seenTargets.add(tk);
+              const bucket = targetByKey.get(tk);
+              if (bucket) targets.push(...bucket);
+            }
+            doc[relation.as] = targets;
+          }
         }
-      }
-    }
-    return docs;
+      })
+    );
+    return out;
   };
   return { populate };
 };
@@ -2566,13 +3142,28 @@ var probeDebugQuery = async () => {
     debugQueryCache = null;
   }
 };
+var sanitizeDebugParams = (value) => {
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch {
+    try {
+      return String(value);
+    } catch {
+      return "[unserializable]";
+    }
+  }
+};
 var traceDbOp = async (logger, meta, fn, options = {}) => {
   const start = performance.now();
   logger.debug({ ...meta, operation: "start" }, "start");
   try {
-    if (debugQueryCache === void 0) await probeDebugQuery();
-    const debugQuery = debugQueryCache;
-    const result = debugQuery ? await debugQuery(`${meta.collection}.${meta.op}`, void 0, () => fn()) : await fn();
+    let debugQuery = options.debugQuery;
+    if (debugQuery === void 0) {
+      if (debugQueryCache === void 0) await probeDebugQuery();
+      debugQuery = debugQueryCache;
+    }
+    const params = meta.params === void 0 ? void 0 : sanitizeDebugParams(meta.params);
+    const result = debugQuery ? await debugQuery(`${meta.collection}.${meta.op}`, params, () => fn()) : await fn();
     const durationMs = performance.now() - start;
     logger.info({ ...meta, durationMs }, "ok");
     return result;
@@ -2588,11 +3179,12 @@ var traceDbOp = async (logger, meta, fn, options = {}) => {
 // src/service/op-deps.ts
 var makeOpDeps = (logger, dbLabel, resolve, wrapMongoErrors) => {
   const trace = (meta2, fn) => traceDbOp(logger, meta2, fn, { wrapMongoErrors });
-  const meta = (collection, op) => ({
+  const meta = (collection, op, params) => ({
     collection: String(collection),
     physicalCollection: resolve(String(collection)),
     db: dbLabel,
-    op
+    op,
+    ...params !== void 0 ? { params } : {}
   });
   return { trace, meta };
 };
@@ -2638,11 +3230,11 @@ var resolveDriftMode = (perOp, serviceDefault) => {
 };
 
 // src/service/crud-op.ts
-var defineCrudOp = async (deps2, collection, opName, execute, options, write = false) => {
+var defineCrudOp = async (deps2, collection, opName, execute, options, write = false, params) => {
   const resolved = resolveQueryOptions(options);
   const maxAttempts = write && resolved.retryWrites !== true ? 1 : resolved.maxAttempts;
   return deps2.trace(
-    deps2.meta(collection, opName),
+    deps2.meta(collection, opName, params),
     async () => withRetry(async () => execute(resolved), {
       maxAttempts,
       delayMs: resolved.retryDelayMs
@@ -2747,7 +3339,9 @@ var PipelineBuilder = class _PipelineBuilder {
       this.deps.logical,
       "mongo.pipeline",
       run,
-      this.deps.options
+      this.deps.options,
+      false,
+      { pipeline: this.stages }
     );
   }
   /** Run the pipeline and return the first output document (or null). */
@@ -2774,7 +3368,9 @@ var PipelineBuilder = class _PipelineBuilder {
       this.deps.logical,
       "mongo.pipeline.first",
       run,
-      this.deps.options
+      this.deps.options,
+      false,
+      { pipeline: this.stages }
     );
   }
   /** Streaming cursor (raw driver cursor; no retry / trace). */
@@ -2894,7 +3490,9 @@ var makeAggregateOps = (ctx) => {
       collection,
       "mongo.aggregate",
       (r) => coll(collection).aggregate(pipeline2, mergeAggOptions2(r.driverOpts, r.sdk)),
-      options
+      options,
+      false,
+      { pipeline: pipeline2 }
     );
   };
   const pipeline = (collection, options) => new PipelineBuilder({
@@ -2980,7 +3578,7 @@ var createCachedAggregate = (ctx) => {
     const noSession = !resolved.sdk.session;
     const useCache = cache !== void 0 && noSession && resolved.cache !== false && isCacheablePipeline(pipeline);
     const shouldDedupe = resolved.dedupe !== false && (resolved.dedupe === true || opts.dedupeReads === true && noSession) && opts.inFlight !== void 0;
-    const runDriver = () => defineCrudOp(deps2, collection, opName, execute, options);
+    const runDriver = () => defineCrudOp(deps2, collection, opName, execute, options, false, { pipeline });
     const key = useCache ? cache.key(
       cacheCollectionKey(client.databaseName, physical),
       stableHash([opName, pipeline, options])
@@ -3010,10 +3608,12 @@ var createCachedAggregate = (ctx) => {
       return runDriver();
     };
     if (shouldDedupe) {
-      const dedupeKey = `${cacheCollectionKey(client.databaseName, physical)}|${opName}|${stableHash([pipeline, options])}`;
-      return opts.inFlight.run(dedupeKey, runOnce);
+      const primaryKey = cacheCollectionKey(client.databaseName, physical);
+      const gen = cache !== void 0 ? cache.versionOf(primaryKey) : "";
+      const dedupeKey = `${primaryKey}|${gen}|${opName}|${stableHash([pipeline, options])}`;
+      return await opts.inFlight.run(dedupeKey, runOnce);
     }
-    return runOnce();
+    return await runOnce();
   };
 };
 
@@ -3235,6 +3835,54 @@ var makeAggregationOps = (client, dbLabel, logger, opts) => {
   };
 };
 
+// src/schema/apply-defaults.ts
+var cloneDefault = (value) => {
+  if (value === null || typeof value !== "object") return value;
+  if (typeof structuredClone === "function") return structuredClone(value);
+  return Array.isArray(value) ? [...value] : { ...value };
+};
+var applySchemaDefaults = (schema, doc) => {
+  if (!schema || doc === null || typeof doc !== "object" || Array.isArray(doc)) return;
+  for (const [key, prop] of Object.entries(schema.properties)) {
+    if (key in doc && doc[key] !== void 0) {
+      if (prop.kind === "object" && doc[key] !== null && typeof doc[key] === "object" && !Array.isArray(doc[key])) {
+        applySchemaDefaults(prop, doc[key]);
+      }
+      continue;
+    }
+    if (prop.flags.hasDefault) {
+      doc[key] = cloneDefault(prop.flags.defaultValue);
+    }
+  }
+};
+
+// src/utils/omit-undefined.ts
+var stripUndefinedKeys = (doc) => {
+  for (const key of Object.keys(doc)) {
+    if (doc[key] === void 0) {
+      delete doc[key];
+    }
+  }
+  return doc;
+};
+var stripUndefinedFromUpdate = (update) => {
+  if (update === null || typeof update !== "object") return update;
+  const doc = update;
+  for (const operator of ["$set", "$setOnInsert"]) {
+    const op = doc[operator];
+    if (op !== null && typeof op === "object" && !Array.isArray(op)) {
+      const opDoc = op;
+      for (const key of Object.keys(opDoc)) {
+        if (opDoc[key] === void 0) delete opDoc[key];
+      }
+    }
+  }
+  for (const key of Object.keys(doc)) {
+    if (doc[key] === void 0) delete doc[key];
+  }
+  return update;
+};
+
 // src/service/drift.ts
 var checkDocsDrift = (options, collection, op, docs) => {
   if (options.drift === "off") return;
@@ -3279,8 +3927,8 @@ var createCrudContext = (client, dbLabel, logger, opts) => {
   );
   const coll = (name) => client.collection(resolve(String(name)));
   const toDriverFilter = (filter) => filter;
-  const run = (collection, opName, execute, options) => defineCrudOp(deps2, collection, opName, execute, options);
-  const writeRun = (collection, opName, execute, options) => defineCrudOp(deps2, collection, opName, execute, options, true);
+  const run = (collection, opName, execute, options, params) => defineCrudOp(deps2, collection, opName, execute, options, false, params);
+  const writeRun = (collection, opName, execute, options, params) => defineCrudOp(deps2, collection, opName, execute, options, true, params);
   const invalidate = (collection) => {
     opts.cache?.invalidateByCollection(
       cacheCollectionKey(client.databaseName, resolve(String(collection)))
@@ -3288,6 +3936,8 @@ var createCrudContext = (client, dbLabel, logger, opts) => {
   };
   const timestampsFor = (collection) => opts.timestamps?.[String(collection)];
   const stampCreate = (collection, doc) => {
+    applySchemaDefaults(opts.getSchema?.(String(collection)), doc);
+    stripUndefinedKeys(doc);
     const ts = timestampsFor(collection);
     if (!ts) return;
     const now = /* @__PURE__ */ new Date();
@@ -3295,6 +3945,7 @@ var createCrudContext = (client, dbLabel, logger, opts) => {
     if (ts.updatedAt && doc[ts.updatedAt] === void 0) doc[ts.updatedAt] = now;
   };
   const stampUpdate = (collection, update) => {
+    stripUndefinedFromUpdate(update);
     const formatted = formatUpdateFilter(update);
     const ts = timestampsFor(collection);
     if (ts?.updatedAt) {
@@ -3304,13 +3955,18 @@ var createCrudContext = (client, dbLabel, logger, opts) => {
     return formatted;
   };
   const stampReplace = (collection, doc) => {
+    applySchemaDefaults(opts.getSchema?.(String(collection)), doc);
+    stripUndefinedKeys(doc);
     const ts = timestampsFor(collection);
     if (!ts?.updatedAt) return doc;
     return { ...doc, [ts.updatedAt]: /* @__PURE__ */ new Date() };
   };
-  const read = async (collection, opName, filter, options, execute, shape = "none") => {
+  const read = async (collection, opName, filter, options, execute, shape = "none", keyExtra) => {
     const physical = resolve(String(collection));
     const resolved = resolveQueryOptions(options);
+    const sentParams = { filter };
+    if (Object.keys(resolved.driverOpts).length > 0) sentParams.options = resolved.driverOpts;
+    if (keyExtra !== void 0) sentParams.field = keyExtra;
     const noSession = !resolved.sdk.session;
     const useCache = opts.cache !== void 0 && noSession && resolved.cache !== false;
     const shouldDedupe = resolved.dedupe !== false && (resolved.dedupe === true || opts.dedupeReads === true && noSession) && opts.inFlight !== void 0;
@@ -3332,16 +3988,28 @@ var createCrudContext = (client, dbLabel, logger, opts) => {
       );
     };
     const executeWrapped = () => deps2.trace(
-      deps2.meta(collection, opName),
+      deps2.meta(collection, opName, sentParams),
       () => withRetry(() => execute(resolved), {
         maxAttempts: resolved.maxAttempts,
         delayMs: resolved.retryDelayMs
       })
     );
-    const key = useCache ? opts.cache.key(
-      cacheCollectionKey(client.databaseName, physical),
-      stableHash([filter, options])
-    ) : void 0;
+    const {
+      maxAttempts: _ma,
+      retryDelayMs: _rd,
+      dedupe: _dd,
+      cache: _ca,
+      retryWrites: _rw,
+      ...resultOptions
+    } = options ?? {};
+    let payloadHash;
+    const getPayloadHash = () => {
+      if (payloadHash === void 0) {
+        payloadHash = stableHash([opName, keyExtra ?? "", filter, resultOptions]);
+      }
+      return payloadHash;
+    };
+    const key = useCache ? opts.cache.key(cacheCollectionKey(client.databaseName, physical), getPayloadHash()) : void 0;
     const fetchAndCheck = () => executeWrapped().then((value) => {
       checkDrift(value);
       return value;
@@ -3360,10 +4028,11 @@ var createCrudContext = (client, dbLabel, logger, opts) => {
       return fetchAndCheck();
     };
     if (shouldDedupe) {
-      const dedupeKey = `${cacheCollectionKey(client.databaseName, physical)}|${opName}|${stableHash([filter, options])}`;
-      return opts.inFlight.run(dedupeKey, runOnce);
+      const colKey = cacheCollectionKey(client.databaseName, physical);
+      const gen = opts.cache !== void 0 ? opts.cache.versionOf(colKey) : "";
+      return await opts.inFlight.run(`${colKey}|${gen}|${getPayloadHash()}`, runOnce);
     }
-    return runOnce();
+    return await runOnce();
   };
   const normalizeFindOptions = (options) => {
     if (!options) return {};
@@ -3422,7 +4091,10 @@ var makeReadOps = (ctx) => {
           ...r.sdk.maxTimeMS !== void 0 ? { maxTimeMS: r.sdk.maxTimeMS } : {},
           ...r.sdk.hint !== void 0 ? { hint: r.sdk.hint } : {}
         };
-        return coll(collection).findOne(toDriverFilter(f), opts2);
+        return await coll(collection).findOne(
+          toDriverFilter(f),
+          opts2
+        );
       },
       "one"
     );
@@ -3516,7 +4188,7 @@ var makeReadOps = (ctx) => {
         ...r.sdk.maxTimeMS !== void 0 ? { maxTimeMS: r.sdk.maxTimeMS } : {},
         ...r.sdk.hint !== void 0 ? { hint: r.sdk.hint } : {}
       };
-      return coll(collection).countDocuments(toDriverFilter(filter ?? {}), opts2);
+      return await coll(collection).countDocuments(toDriverFilter(filter ?? {}), opts2);
     },
     "none"
   );
@@ -3541,21 +4213,24 @@ var makeReadOps = (ctx) => {
           opts2
         );
       },
-      "none"
+      "none",
+      String(field)
     );
   };
-  const estimatedDocumentCount = async (collection, options) => ctx.run(
+  const estimatedDocumentCount = async (collection, options) => read(
     collection,
     "mongo.estimatedDocumentCount",
+    {},
+    options,
     async (r) => {
       const opts2 = {
         ...r.driverOpts,
         ...r.sdk.session !== void 0 ? { session: r.sdk.session } : {},
         ...r.sdk.maxTimeMS !== void 0 ? { maxTimeMS: r.sdk.maxTimeMS } : {}
       };
-      return coll(collection).estimatedDocumentCount(opts2);
+      return await coll(collection).estimatedDocumentCount(opts2);
     },
-    options
+    "none"
   );
   return {
     getOne,
@@ -3592,7 +4267,7 @@ var makeWatchOps = (ctx) => {
             ...r.sdk.maxTimeMS !== void 0 ? { maxTimeMS: r.sdk.maxTimeMS } : {},
             ...r.sdk.hint !== void 0 ? { hint: r.sdk.hint } : {}
           };
-          return execute(opts);
+          return await execute(opts);
         },
         opName === "mongo.getOne" ? "one" : opName === "mongo.findMany" ? "many" : "none"
       )
@@ -3609,6 +4284,20 @@ var makeWriteOps = (ctx, readOps) => {
   const { opts } = ctx;
   const { coll, toDriverFilter, writeRun, invalidate, stampCreate, stampUpdate, stampReplace } = ctx;
   const { getOne } = readOps;
+  const safeAfterHooks = async (collection, name, hookCtx) => {
+    try {
+      await runHooks(opts.hooks, collection, name, hookCtx);
+    } catch (err) {
+      ctx.logger.error?.(
+        {
+          collection,
+          hook: name,
+          error: err instanceof Error ? err.message : String(err)
+        },
+        `post-commit ${name} hook failed; DB write is already committed`
+      );
+    }
+  };
   const insertOne = async (collection, doc, options) => {
     await runHooks(opts.hooks, String(collection), "beforeCreate", {
       collection: String(collection),
@@ -3623,28 +4312,32 @@ var makeWriteOps = (ctx, readOps) => {
           ...r.driverOpts,
           ...r.sdk.session !== void 0 ? { session: r.sdk.session } : {}
         };
-        return coll(collection).insertOne(doc, insertOpts);
+        return await coll(collection).insertOne(
+          doc,
+          insertOpts
+        );
       },
-      options
+      options,
+      { doc }
     );
     invalidate(collection);
-    await runHooks(opts.hooks, String(collection), "afterCreate", {
+    await safeAfterHooks(String(collection), "afterCreate", {
       collection: String(collection),
       doc
     });
     return result;
   };
   const insertMany = async (collection, docs, options) => {
-    await runHooks(opts.hooks, String(collection), "beforeCreate", {
-      collection: String(collection),
-      docs
-    });
-    for (const d of docs) stampCreate(collection, d);
     if (docs.length > MAX_BATCH_OPS) {
       throw new BadRequest(
         `insertMany: too many docs (${docs.length} > ${MAX_BATCH_OPS}); split the batch`
       );
     }
+    await runHooks(opts.hooks, String(collection), "beforeCreate", {
+      collection: String(collection),
+      docs
+    });
+    for (const d of docs) stampCreate(collection, d);
     const result = await writeRun(
       collection,
       "mongo.insertMany",
@@ -3658,10 +4351,11 @@ var makeWriteOps = (ctx, readOps) => {
           bulkOpts
         );
       },
-      options
+      options,
+      { docs }
     );
     invalidate(collection);
-    await runHooks(opts.hooks, String(collection), "afterCreate", {
+    await safeAfterHooks(String(collection), "afterCreate", {
       collection: String(collection),
       docs
     });
@@ -3687,16 +4381,21 @@ var makeWriteOps = (ctx, readOps) => {
           updateOpts
         );
       },
-      options
+      options,
+      { filter, update: effective }
     );
     invalidate(collection);
-    await runHooks(opts.hooks, String(collection), "afterUpdate", {
+    await safeAfterHooks(String(collection), "afterUpdate", {
       collection: String(collection),
       filter
     });
     return result;
   };
   const updateMany = async (collection, filter, update, options) => {
+    await runHooks(opts.hooks, String(collection), "beforeUpdate", {
+      collection: String(collection),
+      filter
+    });
     const effective = stampUpdate(collection, update);
     const result = await writeRun(
       collection,
@@ -3712,12 +4411,21 @@ var makeWriteOps = (ctx, readOps) => {
           updateOpts
         );
       },
-      options
+      options,
+      { filter, update: effective }
     );
     invalidate(collection);
+    await safeAfterHooks(String(collection), "afterUpdate", {
+      collection: String(collection),
+      filter
+    });
     return result;
   };
   const findOneAndUpdate = async (collection, filter, update, options) => {
+    await runHooks(opts.hooks, String(collection), "beforeUpdate", {
+      collection: String(collection),
+      filter
+    });
     const effective = stampUpdate(collection, update);
     const result = await writeRun(
       collection,
@@ -3737,12 +4445,21 @@ var makeWriteOps = (ctx, readOps) => {
           fOpts
         );
       },
-      options
+      options,
+      { filter, update: effective }
     );
     invalidate(collection);
+    await safeAfterHooks(String(collection), "afterUpdate", {
+      collection: String(collection),
+      filter
+    });
     return result;
   };
   const findOneAndReplace = async (collection, filter, replacement, options) => {
+    await runHooks(opts.hooks, String(collection), "beforeUpdate", {
+      collection: String(collection),
+      filter
+    });
     const effective = stampReplace(collection, replacement);
     const result = await writeRun(
       collection,
@@ -3762,12 +4479,21 @@ var makeWriteOps = (ctx, readOps) => {
           fOpts
         );
       },
-      options
+      options,
+      { filter, replacement: effective }
     );
     invalidate(collection);
+    await safeAfterHooks(String(collection), "afterUpdate", {
+      collection: String(collection),
+      filter
+    });
     return result;
   };
   const replaceOne = async (collection, filter, replacement, options) => {
+    await runHooks(opts.hooks, String(collection), "beforeUpdate", {
+      collection: String(collection),
+      filter
+    });
     const result = await writeRun(
       collection,
       "mongo.replaceOne",
@@ -3782,9 +4508,14 @@ var makeWriteOps = (ctx, readOps) => {
           repOpts
         );
       },
-      options
+      options,
+      { filter, replacement }
     );
     invalidate(collection);
+    await safeAfterHooks(String(collection), "afterUpdate", {
+      collection: String(collection),
+      filter
+    });
     return result;
   };
   const deleteOne = async (collection, filter, options) => {
@@ -3800,18 +4531,23 @@ var makeWriteOps = (ctx, readOps) => {
           ...r.driverOpts,
           ...r.sdk.session !== void 0 ? { session: r.sdk.session } : {}
         };
-        return coll(collection).deleteOne(toDriverFilter(filter), delOpts);
+        return await coll(collection).deleteOne(toDriverFilter(filter), delOpts);
       },
-      options
+      options,
+      { filter }
     );
     invalidate(collection);
-    await runHooks(opts.hooks, String(collection), "afterDelete", {
+    await safeAfterHooks(String(collection), "afterDelete", {
       collection: String(collection),
       filter
     });
     return result;
   };
   const deleteMany = async (collection, filter, options) => {
+    await runHooks(opts.hooks, String(collection), "beforeDelete", {
+      collection: String(collection),
+      filter
+    });
     const result = await writeRun(
       collection,
       "mongo.deleteMany",
@@ -3820,14 +4556,23 @@ var makeWriteOps = (ctx, readOps) => {
           ...r.driverOpts,
           ...r.sdk.session !== void 0 ? { session: r.sdk.session } : {}
         };
-        return coll(collection).deleteMany(toDriverFilter(filter), delOpts);
+        return await coll(collection).deleteMany(toDriverFilter(filter), delOpts);
       },
-      options
+      options,
+      { filter }
     );
     invalidate(collection);
+    await safeAfterHooks(String(collection), "afterDelete", {
+      collection: String(collection),
+      filter
+    });
     return result;
   };
   const findOneAndDelete = async (collection, filter, options) => {
+    await runHooks(opts.hooks, String(collection), "beforeDelete", {
+      collection: String(collection),
+      filter
+    });
     const result = await writeRun(
       collection,
       "mongo.findOneAndDelete",
@@ -3843,13 +4588,25 @@ var makeWriteOps = (ctx, readOps) => {
           fOpts
         );
       },
-      options
+      options,
+      { filter }
     );
     invalidate(collection);
+    await safeAfterHooks(String(collection), "afterDelete", {
+      collection: String(collection),
+      filter
+    });
     return result;
   };
   const softDeleteOne = async (collection, filter, options) => {
+    await runHooks(opts.hooks, String(collection), "beforeDelete", {
+      collection: String(collection),
+      filter
+    });
     const active = mergeMongoActiveFilter(true, filter);
+    const effective = stampUpdate(collection, {
+      $set: { deletedAt: /* @__PURE__ */ new Date() }
+    });
     const result = await writeRun(
       collection,
       "mongo.softDeleteOne",
@@ -3860,16 +4617,25 @@ var makeWriteOps = (ctx, readOps) => {
         };
         return coll(collection).updateOne(
           active,
-          { $set: { deletedAt: /* @__PURE__ */ new Date() } },
+          effective,
           updateOpts
         );
       },
-      options
+      options,
+      { filter, update: effective }
     );
     invalidate(collection);
+    await safeAfterHooks(String(collection), "afterDelete", {
+      collection: String(collection),
+      filter
+    });
     return result;
   };
   const upsert = async (collection, filter, update, options) => {
+    await runHooks(opts.hooks, String(collection), "beforeUpdate", {
+      collection: String(collection),
+      filter
+    });
     const formatted = stampUpdate(collection, update);
     const result = await writeRun(
       collection,
@@ -3880,14 +4646,24 @@ var makeWriteOps = (ctx, readOps) => {
           ...r.sdk.session !== void 0 ? { session: r.sdk.session } : {},
           upsert: true
         };
-        return coll(collection).updateOne(toDriverFilter(filter), formatted, updateOpts);
+        return await coll(collection).updateOne(toDriverFilter(filter), formatted, updateOpts);
       },
-      options
+      options,
+      { filter, update: formatted }
     );
     invalidate(collection);
+    await safeAfterHooks(String(collection), "afterUpdate", {
+      collection: String(collection),
+      filter
+    });
     return result;
   };
   const bulkUpsert = async (collection, operations, options) => {
+    if (operations.length > MAX_BATCH_OPS) {
+      throw new BadRequest(
+        `bulkUpsert: too many operations (${operations.length} > ${MAX_BATCH_OPS}); split the batch`
+      );
+    }
     const writes = operations.map((op) => ({
       updateOne: {
         filter: op.filter,
@@ -3895,11 +4671,6 @@ var makeWriteOps = (ctx, readOps) => {
         upsert: op.upsert ?? true
       }
     }));
-    if (operations.length > MAX_BATCH_OPS) {
-      throw new BadRequest(
-        `bulkUpsert: too many operations (${operations.length} > ${MAX_BATCH_OPS}); split the batch`
-      );
-    }
     const result = await writeRun(
       collection,
       "mongo.bulkUpsert",
@@ -3908,9 +4679,10 @@ var makeWriteOps = (ctx, readOps) => {
           ...r.driverOpts,
           ...r.sdk.session !== void 0 ? { session: r.sdk.session } : {}
         };
-        return coll(collection).bulkWrite(writes, bulkOpts);
+        return await coll(collection).bulkWrite(writes, bulkOpts);
       },
-      options
+      options,
+      { operations }
     );
     invalidate(collection);
     return result;
@@ -3929,9 +4701,10 @@ var makeWriteOps = (ctx, readOps) => {
           ...r.driverOpts,
           ...r.sdk.session !== void 0 ? { session: r.sdk.session } : {}
         };
-        return coll(collection).bulkWrite(operations, bulkOpts);
+        return await coll(collection).bulkWrite(operations, bulkOpts);
       },
-      options
+      options,
+      { operations }
     );
     invalidate(collection);
     return result;
@@ -4001,14 +4774,29 @@ var tag = (value) => {
 var untag = (tagged) => {
   switch (tagged.t) {
     case "oid":
+      if (typeof tagged.v !== "string") {
+        throw new BadRequest("paginateCursor: invalid cursor \u2014 oid value must be a string");
+      }
       return new ObjectId(tagged.v);
     case "date":
+      if (typeof tagged.v !== "string") {
+        throw new BadRequest("paginateCursor: invalid cursor \u2014 date value must be a string");
+      }
       return new Date(tagged.v);
     case "string":
+      if (typeof tagged.v !== "string") {
+        throw new BadRequest("paginateCursor: invalid cursor \u2014 string value expected");
+      }
       return tagged.v;
     case "number":
+      if (typeof tagged.v !== "number") {
+        throw new BadRequest("paginateCursor: invalid cursor \u2014 number value expected");
+      }
       return tagged.v;
     case "boolean":
+      if (typeof tagged.v !== "boolean") {
+        throw new BadRequest("paginateCursor: invalid cursor \u2014 boolean value expected");
+      }
       return tagged.v;
     case "null":
       return null;
@@ -4094,11 +4882,14 @@ var makePaginateCursor = (ctx) => {
           ...r.driverOpts,
           ...r.sdk.session !== void 0 ? { session: r.sdk.session } : {},
           ...r.sdk.maxTimeMS !== void 0 ? { maxTimeMS: r.sdk.maxTimeMS } : {},
-          ...r.sdk.hint !== void 0 ? { hint: r.sdk.hint } : {}
+          ...r.sdk.hint !== void 0 ? { hint: r.sdk.hint } : {},
+          ...r.sdk.batchSize !== void 0 ? { batchSize: r.sdk.batchSize } : {}
         };
         return client.collection(resolve(String(collection))).find(filter, findOpts).sort(effectiveSort).limit(limit + 1).toArray();
       },
-      config.queryOptions
+      config.queryOptions,
+      false,
+      { filter, sort: effectiveSort, limit }
     );
     const hasMore = rows.length > limit;
     const page = backwards ? rows.slice(0, limit).reverse() : rows.slice(0, limit);
@@ -4114,10 +4905,16 @@ var makePaginateCursor = (ctx) => {
       page
     );
     const boundary = backwards ? rows[limit] : page[page.length - 1];
-    const nextCursor = hasMore && boundary !== void 0 ? encodeCursor({
-      sort: config.sort,
-      values: sortKeys.map(([f]) => boundary[f])
-    }) : null;
+    let nextCursor = null;
+    if (hasMore && boundary !== void 0) {
+      const values = sortKeys.map(([f]) => boundary[f]);
+      if (values.some((v) => v === void 0)) {
+        throw new BadRequest(
+          "paginateCursor: boundary document is missing a sort field \u2014 every sort key must exist on every document for keyset pagination"
+        );
+      }
+      nextCursor = encodeCursor({ sort: config.sort, values });
+    }
     return { data: page, nextCursor, hasMore };
   };
   return { paginateCursor };
@@ -4132,13 +4929,17 @@ var makePaginateFlexible = (ctx) => {
         ...config.page !== void 0 ? { page: config.page } : {},
         ...config.limit !== void 0 ? { limit: config.limit } : {}
       },
-      config.maxLimit ?? DEFAULT_MAX_LIMIT
+      config.maxLimit ?? DEFAULT_MAX_LIMIT,
+      // Same default as `findMany`/`paginateCursor` — the two pagination
+      // APIs used to disagree silently (10 vs 100).
+      { limit: DEFAULT_FIND_LIMIT }
     );
     const dataStages = [
       ...config.prePipeline ?? [],
       ...config.sort && Object.keys(config.sort).length > 0 ? [{ $sort: config.sort }] : [],
       { $skip: normalized.offset },
       { $limit: normalized.limit },
+      ...config.projection !== void 0 ? [{ $project: config.projection }] : [],
       ...config.postPipeline ?? []
     ];
     const pipeline = [
@@ -4167,17 +4968,19 @@ var makePaginateFlexible = (ctx) => {
         const row = rows[0];
         const data = row?.data ?? [];
         const totalCount = row?.totalCount?.[0]?.count ?? 0;
-        checkDocsDrift(
-          {
-            logger,
-            db: dbLabel,
-            drift: resolveDriftMode(config.queryOptions?.drift, opts.drift),
-            ...opts.getSchema !== void 0 ? { getSchema: opts.getSchema } : {}
-          },
-          String(collection),
-          "mongo.paginateFlexible",
-          data
-        );
+        if (config.projection === void 0) {
+          checkDocsDrift(
+            {
+              logger,
+              db: dbLabel,
+              drift: resolveDriftMode(config.queryOptions?.drift, opts.drift),
+              ...opts.getSchema !== void 0 ? { getSchema: opts.getSchema } : {}
+            },
+            String(collection),
+            "mongo.paginateFlexible",
+            data
+          );
+        }
         return buildPaginationResult(data, totalCount, normalized.page, normalized.limit);
       }
     });
@@ -4205,42 +5008,70 @@ var makePaginationOps = (client, dbLabel, logger, opts) => {
 };
 
 // src/service/schema-ops.ts
-var indexKeyOf = (key) => JSON.stringify(
-  Object.keys(key).sort().map((k) => [k, key[k]])
-);
+var optionSignature = (o) => JSON.stringify([
+  Boolean(o?.unique),
+  Boolean(o?.sparse),
+  typeof o?.expireAfterSeconds === "number" ? o.expireAfterSeconds : null
+]);
+var indexKeyOf = (key, options) => `${JSON.stringify(Object.keys(key).map((k) => [k, key[k]]))}|${optionSignature(options)}`;
 var makeSchemaOps = (client, _logger, opts) => {
+  const readCollectionValidator = async (physical) => {
+    const info = await client.listCollections({ name: physical }).next();
+    return info?.options?.validator;
+  };
+  const ensureDeclaredIndexes = async (collection, physical, def) => {
+    const declared = def?.indexes ?? [];
+    if (declared.length === 0) return;
+    const handle = client.collection(physical);
+    const existing = new Set(
+      (await handle.listIndexes().toArray()).filter((i) => i.name !== "_id_").map((i) => indexKeyOf(i.key, i))
+    );
+    for (const index of declared) {
+      if (existing.has(indexKeyOf(index.key, index.options))) continue;
+      try {
+        await handle.createIndex(index.key, index.options);
+      } catch (err) {
+        if (err?.code === 85) {
+          throw new Error(
+            `Cannot apply declared index on "${collection}": an index with the same name/key already exists with different options. Run db.syncIndexes("${collection}") to reconcile index drift.`,
+            { cause: err }
+          );
+        }
+        throw err;
+      }
+    }
+  };
   const createSchema = async (collection, createCollectionOptions) => {
     const physical = opts.resolveCollectionName(collection);
     const def = opts.getDefinition(collection);
-    const validator = def?.schema ? toMongoValidator(def.schema) : void 0;
+    const createOptions = {
+      ...createCollectionOptions ?? {},
+      ...def?.schema ? { validator: toMongoValidator(def.schema) } : {}
+    };
+    let created = true;
     try {
-      await client.createCollection(physical, {
-        ...validator ? { validator } : {},
-        ...createCollectionOptions ?? {}
-      });
+      await client.createCollection(physical, createOptions);
     } catch (err) {
-      if (err?.code === 48) {
-        throw new DomainError("COLLECTION_EXISTS", `Collection "${collection}" already exists`, {
-          physicalCollection: physical
-        });
-      }
-      throw err;
+      if (err?.code !== 48) throw err;
+      created = false;
     }
-    const indexes = def?.indexes ?? [];
-    if (indexes.length > 0) {
+    if (created) {
       try {
-        await client.collection(physical).createIndexes(
-          indexes.map((index) => ({
-            key: index.key,
-            ...index.options ?? {}
-          }))
-        );
+        await ensureDeclaredIndexes(collection, physical, def);
       } catch (err) {
         await client.dropCollection(physical).catch(() => {
         });
         throw err;
       }
+      return;
     }
+    if (createOptions.validator) {
+      const current = await readCollectionValidator(physical);
+      if (JSON.stringify(current) !== JSON.stringify(createOptions.validator)) {
+        await client.command({ collMod: physical, validator: createOptions.validator });
+      }
+    }
+    await ensureDeclaredIndexes(collection, physical, def);
   };
   const updateSchema = async (collection, schema) => {
     const physical = opts.resolveCollectionName(collection);
@@ -4261,9 +5092,11 @@ var makeSchemaOps = (client, _logger, opts) => {
     const handle = client.collection(physical);
     const existing = (await handle.listIndexes().toArray()).filter((i) => i.name !== "_id_");
     const existingByKey = new Map(
-      existing.map((i) => [indexKeyOf(i.key), i.name])
+      existing.map((i) => [indexKeyOf(i.key, i), i.name])
+    );
+    const declaredByKey = new Map(
+      declared.map((d) => [indexKeyOf(d.key, d.options), d])
     );
-    const declaredByKey = new Map(declared.map((d) => [indexKeyOf(d.key), d]));
     const created = [];
     const dropped = [];
     for (const [key] of declaredByKey) {
@@ -4275,7 +5108,9 @@ var makeSchemaOps = (client, _logger, opts) => {
       }
     }
     const after = (await handle.listIndexes().toArray()).filter((i) => i.name !== "_id_");
-    const afterByKey = new Map(after.map((i) => [indexKeyOf(i.key), i.name]));
+    const afterByKey = new Map(
+      after.map((i) => [indexKeyOf(i.key, i), i.name])
+    );
     for (const [key, spec] of declaredByKey) {
       if (!existingByKey.has(key)) {
         created.push(spec.options?.name ?? afterByKey.get(key) ?? JSON.stringify(spec.key));
@@ -4294,16 +5129,22 @@ var makeSchemaOps = (client, _logger, opts) => {
 
 // src/service/transaction.ts
 var makeTransactionOps = (client, handle, logger, _config, opts) => {
+  let warnedUnsupported = false;
+  let journalIndexReady = false;
+  const MIGRATE_LEASE_MS = 12e4;
   const transaction = async (fn, options) => {
     const session = client.startSession();
     try {
       return await session.withTransaction(async () => fn(session), options);
     } catch (err) {
-      const message = err instanceof Error ? err.message : "";
-      const code = err?.code;
-      const unsupported = code === 20 || /Transaction numbers are only allowed/i.test(message) || /does not support retryable writes/i.test(message);
-      if (unsupported) {
-        logger.warn?.({ code }, "transactions unsupported, falling back to non-transactional");
+      if (isTransactionUnsupportedError(err)) {
+        if (!warnedUnsupported) {
+          warnedUnsupported = true;
+          logger.warn?.(
+            { error: err instanceof Error ? err.message : String(err) },
+            "transactions unsupported on this deployment, falling back to non-transactional"
+          );
+        }
         return fn(null);
       }
       if (opts.wrapMongoErrors) {
@@ -4315,34 +5156,105 @@ var makeTransactionOps = (client, handle, logger, _config, opts) => {
     }
   };
   const migrate = async (name, fn, filePath) => {
-    const journal = handle.collection(
-      opts.migrationCollectionPhysical
-    );
+    const journal = handle.collection(opts.migrationCollectionPhysical);
+    if (!journalIndexReady) {
+      try {
+        await journal.createIndex({ name: 1 }, { unique: true });
+      } catch {
+      }
+      journalIndexReady = true;
+    }
+    const isDupKeyError = (err) => {
+      const code = err?.code;
+      if (code === 11e3 || code === 11001) return true;
+      return /E11000 duplicate key/.test(String(err?.message ?? ""));
+    };
     await transaction(async (session) => {
       const sessionOpts = session ? { session } : {};
-      const claim = await journal.findOneAndUpdate(
-        { name },
+      const now = /* @__PURE__ */ new Date();
+      const expiresAt = new Date(Date.now() + MIGRATE_LEASE_MS);
+      const stole = await journal.findOneAndUpdate(
         {
-          $setOnInsert: {
-            name,
-            appliedAt: /* @__PURE__ */ new Date(),
+          name,
+          status: { $exists: true, $nin: ["applied"] },
+          $or: [
+            { expiresAt: { $lt: now } },
+            {
+              expiresAt: { $exists: false },
+              appliedAt: { $lt: new Date(now.getTime() - MIGRATE_LEASE_MS) }
+            }
+          ]
+        },
+        {
+          $set: {
+            status: "running",
+            appliedAt: now,
+            expiresAt,
             ...filePath ? { file: filePath } : {}
           }
         },
-        { upsert: true, returnDocument: "before", ...sessionOpts }
+        { returnDocument: "before", ...sessionOpts }
       );
-      if (claim) {
-        logger.info({ name }, "migration already applied, skipping");
+      if (stole !== null) {
+        await runClaimed(session);
         return;
       }
+      try {
+        await journal.insertOne(
+          {
+            name,
+            appliedAt: now,
+            status: "running",
+            expiresAt,
+            ...filePath ? { file: filePath } : {}
+          },
+          sessionOpts
+        );
+      } catch (err) {
+        if (!isDupKeyError(err)) throw err;
+        const existing = await journal.findOne(
+          { name },
+          { projection: { status: 1 }, ...sessionOpts }
+        );
+        const status = existing?.status;
+        if (status === void 0 || status === "applied") {
+          logger.info({ name }, "migration already applied, skipping");
+        } else {
+          logger.warn({ name }, "migration claim held by another runner, skipping");
+        }
+        return;
+      }
+      await runClaimed(session);
+    });
+    async function runClaimed(session) {
+      const sessionOpts = session ? { session } : {};
+      const heartbeat = session === null ? setInterval(() => {
+        void journal.updateOne(
+          { name, status: "running" },
+          { $set: { expiresAt: new Date(Date.now() + MIGRATE_LEASE_MS) } }
+        ).catch(() => {
+        });
+      }, MIGRATE_LEASE_MS / 2) : void 0;
+      heartbeat?.unref?.();
       try {
         await fn(session);
+        const res = await journal.updateOne(
+          { name, status: "running" },
+          { $set: { status: "applied" } },
+          sessionOpts
+        );
+        if (res?.matchedCount === 0) {
+          await journal.insertOne({ name, appliedAt: /* @__PURE__ */ new Date(), status: "applied" }, sessionOpts).catch(() => {
+          });
+        }
       } catch (err) {
         await journal.deleteOne({ name }, sessionOpts).catch(() => {
         });
         throw err;
+      } finally {
+        if (heartbeat !== void 0) clearInterval(heartbeat);
       }
-    });
+    }
   };
   return { transaction, migrate };
 };
@@ -4487,11 +5399,27 @@ var createMongoService = (dbClients, configOverrides = {}) => {
 };
 
 // src/shared/merge-filters.ts
+var isOperatorDoc = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
 var mergeMongoFilters = (...parts) => {
   const out = {};
   for (const part of parts) {
     if (!part) continue;
-    Object.assign(out, part);
+    for (const [key, value] of Object.entries(part)) {
+      if (!(key in out)) {
+        out[key] = value;
+        continue;
+      }
+      if (key === "$and" || key === "$or") {
+        const prev2 = out[key];
+        out[key] = [
+          ...Array.isArray(prev2) ? prev2 : [prev2],
+          ...Array.isArray(value) ? value : [value]
+        ];
+        continue;
+      }
+      const prev = out[key];
+      out[key] = isOperatorDoc(prev) && isOperatorDoc(value) ? { ...prev, ...value } : value;
+    }
   }
   return out;
 };
@@ -4570,6 +5498,6 @@ var createCachedAsyncFactory = (factory, options = {}) => {
   };
 };
 
-export { AppError, BadRequest, CacheInvalidator, DEFAULT_FIND_LIMIT, DEFAULT_MAX_LIMIT, DataLoader, DomainError, ERROR_HTTP_STATUS, HOOK_NAMES, HotCache, InFlight, InfraError, LRU, MAX_BATCH_OPS, QueryBuilder, QueryCache, TRANSIENT_MONGO_ERROR_CODES, belongsTo, buildKeysetFilter, buildMongoActiveFilter, buildPaginationResult, cacheCollectionKey, canonicalKey, createCachedAsyncFactory, createCachedFactory, createConsoleLogger, createHotCache, createMongoCapabilitiesStore, createMongoMigrationRunner, createMongoService, createMongoToolkit, createNoopLogger, createRepository, createResolveCollectionName, decodeCursor, defineCollection, defineCollections, encodeCursor, hasMany, hashString, httpStatusForError, isAppError, isDomainError, isInfraError, isMappedMongoError, isMongoDuplicateKeyError, isMongoTransientError, manyToMany, mapMongoDriverError, mergeMongoActiveFilter, mergeMongoFilters, normalizeMongoUrl, normalizePageLimit, optional, probeMongoCapabilities, runHooks, s, serializeError, sleep, sleepJittered, stableHash, stableStringify, stripDocumentId, stripPrimaryKey, toMongoSchema, toMongoValidator, validateDoc, withDefault, withGracefulMongoTransaction, withRetry, withTimeout, withTransaction };
+export { AppError, BadRequest, CacheInvalidator, DEFAULT_FIND_LIMIT, DEFAULT_MAX_LIMIT, DataLoader, DomainError, ERROR_HTTP_STATUS, HOOK_NAMES, HotCache, InFlight, InfraError, LRU, MAX_BATCH_OPS, QueryBuilder, QueryCache, TRANSIENT_MONGO_ERROR_CODES, belongsTo, buildKeysetFilter, buildMongoActiveFilter, buildPaginationResult, cacheCollectionKey, canonicalKey, createCachedAsyncFactory, createCachedFactory, createConsoleLogger, createHotCache, createMongoCapabilitiesStore, createMongoMigrationRunner, createMongoService, createMongoToolkit, createNoopLogger, createRepository, createResolveCollectionName, decodeCursor, defineCollection, defineCollections, encodeCursor, hasMany, hashString, httpStatusForError, isAppError, isDomainError, isInfraError, isMappedMongoError, isMongoDuplicateKeyError, isMongoTransientError, isTransactionUnsupportedError, manyToMany, mapMongoDriverError, mergeMongoActiveFilter, mergeMongoFilters, normalizeMongoUrl, normalizePageLimit, optional, probeMongoCapabilities, runHooks, s, serializeError, sleep, sleepJittered, stableHash, stableStringify, stripDocumentId, stripPrimaryKey, toMongoSchema, toMongoValidator, validateDoc, withDefault, withGracefulMongoTransaction, withRetry, withTimeout, withTransaction };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map