@ignex/ninox 0.1.7 → 0.2.0

package/dist/index.js

@@ -1,7 +1,9 @@
-import { ObjectId, Decimal128, Long, Int32, Double, Timestamp, Binary, MinKey, MaxKey, DBRef, Code, MongoClient } from 'mongodb';
+import { BSON, ObjectId, Decimal128, Long, Int32, Double, Timestamp, Binary, MinKey, MaxKey, DBRef, Code, MongoClient } from 'mongodb';
+import { createHash, randomUUID } from 'crypto';
 import { writeFile, mkdir, readdir } from 'fs/promises';
 import { basename, join } from 'path';
 import { pathToFileURL } from 'url';
+import { isIP } from 'net';
 
 // src/utils/timeout.ts
 var withTimeout = (promise, timeoutMs, label) => {
@@ -228,7 +230,7 @@ var isMongoDuplicateKeyError = (error) => {
 };
 var isTransactionUnsupportedError = (error) => {
   const code = error?.code;
-  if (code === 20) return true;
+  if (code === 20 || code === "TRANSACTIONS_UNSUPPORTED") 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);
 };
@@ -313,6 +315,12 @@ var mapMongoDriverError = (error, ctx = {}) => {
   }
   const code = error.code;
   switch (code) {
+    case 20:
+      return new InfraError(
+        "TRANSACTIONS_UNSUPPORTED",
+        "MongoDB deployment does not support transactions; enable allowNonTransactionalFallback to run non-atomically",
+        context
+      );
     case 112:
       return new DomainError("VERSION_CONFLICT", "Document version conflict", context);
     case 50:
@@ -406,46 +414,81 @@ var cloneDeep = (value) => {
   }
   return value;
 };
-
-// src/utils/hash.ts
-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();
-  if (v instanceof Date) return `date:${v.getTime()}`;
-  if (typeof v === "object") {
-    const anyV = v;
-    if (typeof anyV.toHexString === "function") return `oid:${anyV.toHexString()}`;
-    if (anyV instanceof RegExp) return `re:${anyV.source}/${anyV.flags}`;
-  }
-  return v;
+var { EJSON } = BSON;
+var bsonTypeOf = (value) => {
+  const type = value._bsontype;
+  return typeof type === "string" ? type : void 0;
+};
+var isPlainObject = (value) => {
+  if (value === null || typeof value !== "object") return false;
+  const prototype = Object.getPrototypeOf(value);
+  return (prototype === Object.prototype || prototype === null) && bsonTypeOf(value) === void 0;
 };
 var stableStringify = (value) => {
-  const visit = (v) => {
-    if (Array.isArray(v)) return v.map(visit);
-    if (isPlainObject(v)) {
-      const out = {};
-      for (const key of Object.keys(v).sort()) out[key] = visit(v[key]);
-      return out;
+  const ancestors = /* @__PURE__ */ new WeakSet();
+  const visit = (input) => {
+    if (input === null) return { t: "null" };
+    if (input === void 0) return { t: "undefined" };
+    switch (typeof input) {
+      case "string":
+      case "boolean":
+        return { t: typeof input, v: input };
+      case "number":
+        if (Number.isNaN(input)) return { t: "number", v: "NaN" };
+        if (input === Infinity) return { t: "number", v: "Infinity" };
+        if (input === -Infinity) return { t: "number", v: "-Infinity" };
+        if (Object.is(input, -0)) return { t: "number", v: "-0" };
+        return { t: "number", v: input };
+      case "bigint":
+        return { t: "bigint", v: input.toString() };
+      case "symbol":
+      case "function":
+        throw new TypeError(`stableStringify: unsupported ${typeof input} value`);
+    }
+    const object = input;
+    if (ancestors.has(object)) throw new TypeError("stableStringify: cyclic value");
+    ancestors.add(object);
+    try {
+      if (input instanceof Date) {
+        return { t: "date", v: Number.isNaN(input.getTime()) ? "Invalid" : input.toISOString() };
+      }
+      if (input instanceof RegExp) return { t: "regexp", v: `re:${input.source}/${input.flags}` };
+      const bsonType = bsonTypeOf(object);
+      if (bsonType !== void 0) {
+        return { t: "bson", kind: bsonType, v: EJSON.stringify(input, { relaxed: false }) };
+      }
+      if (Array.isArray(input)) return { t: "array", v: input.map(visit) };
+      if (input instanceof Map) {
+        return {
+          t: "map",
+          v: [...input.entries()].map(([key, entry]) => [visit(key), visit(entry)])
+        };
+      }
+      if (input instanceof Set) return { t: "set", v: [...input].map(visit) };
+      if (Buffer.isBuffer(input)) return { t: "buffer", v: input.toString("base64") };
+      if (ArrayBuffer.isView(input)) {
+        return {
+          t: "bytes",
+          kind: input.constructor.name,
+          v: Buffer.from(input.buffer, input.byteOffset, input.byteLength).toString("base64")
+        };
+      }
+      if (input instanceof ArrayBuffer) {
+        return { t: "arraybuffer", v: Buffer.from(input).toString("base64") };
+      }
+      if (isPlainObject(input)) {
+        const out = {};
+        for (const key of Object.keys(input).sort()) out[key] = visit(input[key]);
+        return { t: "object", v: out };
+      }
+      throw new TypeError(`stableStringify: unsupported object ${input.constructor.name}`);
+    } finally {
+      ancestors.delete(object);
     }
-    return toPrimitive(v);
   };
   return JSON.stringify(visit(value));
 };
-var hashString = (input) => {
-  let h1 = 5381;
-  let h2 = 2166136261;
-  for (let i = 0; i < input.length; i++) {
-    const c = input.charCodeAt(i);
-    h1 = (h1 << 5) + h1 + c | 0;
-    h2 = (h2 ^ c) * 16777619 | 0;
-    h2 = h2 << 3 | h2 >>> 29;
-  }
-  return `${(h1 >>> 0).toString(36)}${(h2 >>> 0).toString(36)}`;
-};
+var hashString = (input) => createHash("sha256").update(input, "utf8").digest("base64url");
 var stableHash = (value) => hashString(stableStringify(value));
 
 // src/utils/lru.ts
@@ -590,7 +633,6 @@ var RefreshTicker = class {
     this.host = host;
     this.intervalMs = tickIntervalMs;
   }
-  host;
   timer;
   intervalMs;
   /** Whether the timer is currently running. */
@@ -725,7 +767,6 @@ var WatchCoordinator = class {
   constructor(host) {
     this.host = host;
   }
-  host;
   streams = /* @__PURE__ */ new Map();
   failedStreams = /* @__PURE__ */ new Set();
   stopped = true;
@@ -1274,7 +1315,7 @@ var createHotCache = (options) => new HotCache(options);
 // src/cache/query-cache.ts
 var SEP = "\0";
 var NS_SEP = "
";
-var cacheCollectionKey = (dbName, physical) => `${dbName}${NS_SEP}${physical}`;
+var cacheCollectionKey = (dbName, physical, clusterNamespace = "") => `${clusterNamespace}${NS_SEP}${dbName}${NS_SEP}${physical}`;
 var QueryCache = class {
   lru;
   index = /* @__PURE__ */ new Map();
@@ -1299,8 +1340,8 @@ var QueryCache = class {
       max: options.maxSize ?? 500,
       onEvict: (key) => this.unregisterKey(key)
     });
-    this.ttlMs = options.ttlMs ?? 0;
-    this.clone = options.clone ?? false;
+    this.ttlMs = options.ttlMs ?? 3e4;
+    this.clone = options.clone ?? true;
   }
   get size() {
     return this.lru.size;
@@ -1375,6 +1416,7 @@ var QueryCache = class {
     this.sets++;
     const ttl = ttlMs ?? this.ttlMs;
     const expiresAt = ttl > 0 ? Date.now() + ttl : Infinity;
+    this.unregisterKey(key);
     this.lru.set(key, {
       value,
       expiresAt,
@@ -1433,14 +1475,24 @@ var withGracefulMongoTransaction = async (runner, fn, options = {}) => {
       }
     }
   }
-  if (!enabled) return fn(null);
+  const unsupported = () => new InfraError(
+    "TRANSACTIONS_UNSUPPORTED",
+    "MongoDB deployment does not support transactions; set allowNonTransactionalFallback to run non-atomically"
+  );
+  if (!enabled) {
+    if (options.allowNonTransactionalFallback === true) return fn(null);
+    throw unsupported();
+  }
   try {
-    return await runner.transaction(fn);
+    return await runner.transaction(fn, {
+      ...options.allowNonTransactionalFallback !== void 0 ? { allowNonTransactionalFallback: options.allowNonTransactionalFallback } : {}
+    });
   } catch (err) {
     if (isTransactionUnsupportedError(err)) {
+      if (options.allowNonTransactionalFallback !== true) throw err;
       options.logger?.warn?.(
         { error: err instanceof Error ? err.message : String(err) },
-        "transactions unsupported, falling back"
+        "transactions unsupported; running explicitly requested non-transactional fallback"
       );
       return fn(null);
     }
@@ -1607,89 +1659,134 @@ var nextMigrationNumber = async (dir) => {
     return match ? Math.max(max, Number(match[1])) : max;
   }, 0) + 1;
 };
-
-// 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 expiredLeaseFilter = (now, staleCutoff) => ({
+  $or: [
+    { expiresAt: { $lt: now } },
+    { expiresAt: { $exists: false }, appliedAt: { $lt: staleCutoff } }
+  ]
+});
 var createMigrationJournal = (manager) => {
   let indexReady = false;
   const ensureIndex = async () => {
     if (indexReady) return;
-    try {
-      await manager.createIndex?.(JOURNAL_COLLECTION, { name: 1 }, { unique: true });
-    } catch {
+    if (manager.createIndex) {
+      await manager.createIndex(JOURNAL_COLLECTION, { name: 1 }, { unique: true });
     }
     indexReady = true;
   };
   const appliedNames = async () => {
-    const rows = await manager.findMany(JOURNAL_COLLECTION);
+    const rows = await manager.findMany(JOURNAL_COLLECTION, {}, { cache: false });
     return new Set(
-      rows.filter((row) => row.status === void 0 || row.status === "applied").map((row) => row.name)
+      rows.filter(
+        (row) => row.status === void 0 || row.status === "applied" || row.status === "rolling_back"
+      ).map((row) => row.name)
     );
   };
-  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 staleCutoff = new Date(Date.now() - leaseMs);
+    const claimId = randomUUID();
     const stole = await manager.findOneAndUpdate(
       JOURNAL_COLLECTION,
-      stealableFilter(name, now, new Date(Date.now() - leaseMs)),
-      { $set: { status: "running", appliedAt: now, file, expiresAt } },
-      { returnDocument: "before" }
+      {
+        name,
+        status: { $nin: ["applied", "rolling_back"] },
+        ...expiredLeaseFilter(now, staleCutoff)
+      },
+      {
+        $set: {
+          status: "running",
+          appliedAt: now,
+          file,
+          expiresAt: new Date(Date.now() + leaseMs),
+          claimId
+        }
+      },
+      { returnDocument: "before", cache: false }
     );
-    if (stole !== null) return true;
+    if (stole !== null) return claimId;
     try {
       await manager.insertOne(JOURNAL_COLLECTION, {
         name,
         appliedAt: now,
         status: "running",
         file,
-        expiresAt
+        expiresAt: new Date(Date.now() + leaseMs),
+        claimId
       });
-      return true;
+      return claimId;
     } catch (err) {
-      if (isDuplicateKeyError(err)) return false;
+      if (isDuplicateKeyError(err)) return null;
       throw err;
     }
   };
-  const renew = async (name, leaseMs) => {
+  const claimRollback = async (name, file, leaseMs) => {
+    await ensureIndex();
+    const now = /* @__PURE__ */ new Date();
+    const claimId = randomUUID();
+    const claimed = await manager.findOneAndUpdate(
+      JOURNAL_COLLECTION,
+      {
+        name,
+        $or: [
+          { status: "applied" },
+          { status: "rolling_back", ...expiredLeaseFilter(now, new Date(Date.now() - leaseMs)) }
+        ]
+      },
+      {
+        $set: {
+          status: "rolling_back",
+          file,
+          claimId,
+          expiresAt: new Date(Date.now() + leaseMs)
+        }
+      },
+      { returnDocument: "before", cache: false }
+    );
+    return claimed === null ? null : claimId;
+  };
+  const renew = async (name, claimId, leaseMs) => {
     await manager.updateOne(
       JOURNAL_COLLECTION,
-      { name, status: "running" },
-      { $set: { expiresAt: new Date(Date.now() + leaseMs) } }
+      { name, claimId, status: { $in: ["running", "rolling_back"] } },
+      { $set: { expiresAt: new Date(Date.now() + leaseMs) } },
+      { cache: false }
     );
   };
-  const markApplied = async (name) => {
+  const markApplied = async (name, claimId) => {
     const res = await manager.updateOne(
       JOURNAL_COLLECTION,
-      { name, status: "running" },
-      { $set: { status: "applied" } }
+      { name, claimId, status: "running" },
+      { $set: { status: "applied" }, $unset: { expiresAt: "", claimId: "" } },
+      { cache: false }
     );
     if (res?.matchedCount === 0) {
       await manager.insertOne(JOURNAL_COLLECTION, { name, appliedAt: /* @__PURE__ */ new Date(), status: "applied" }).catch(() => {
       });
+      throw new Error(`Migration "${name}" lost its claim before it could be marked applied`);
     }
   };
-  const removeRunning = async (name) => {
-    await manager.deleteOne(JOURNAL_COLLECTION, { name, status: "running" }).catch(() => {
+  const removeRunning = async (name, claimId) => {
+    await manager.deleteOne(JOURNAL_COLLECTION, { name, claimId, status: "running" }, { cache: false }).catch(() => {
     });
   };
-  const unrecord = async (name) => {
-    await manager.deleteOne(JOURNAL_COLLECTION, { name });
+  const unrecord = async (name, claimId) => {
+    const result = await manager.deleteOne(
+      JOURNAL_COLLECTION,
+      { name, claimId, status: "rolling_back" },
+      { cache: false }
+    );
+    if (result?.deletedCount === 0) {
+      throw new Error(`Migration "${name}" lost its rollback claim`);
+    }
   };
-  return { appliedNames, claim, renew, markApplied, removeRunning, unrecord };
+  return { appliedNames, claim, claimRollback, renew, markApplied, removeRunning, unrecord };
 };
 
 // src/migrations/index.ts
@@ -1709,10 +1806,10 @@ var createMongoMigrationRunner = (service, options = {}) => {
     }
     return db;
   };
-  const startHeartbeat = (journal, name) => {
+  const startHeartbeat = (journal, name, claimId) => {
     const timer = setInterval(
       () => {
-        void journal.renew(name, leaseMs).catch(() => {
+        void journal.renew(name, claimId, leaseMs).catch(() => {
         });
       },
       Math.max(leaseMs / 2, 1e3)
@@ -1729,19 +1826,20 @@ var createMongoMigrationRunner = (service, options = {}) => {
     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), leaseMs)) {
+      const claimId = await journal.claim(migration.name, basename(file), leaseMs);
+      if (claimId === null) {
         logger.info(
           { name: migration.name },
           "migration claimed by another runner or already applied, skipping"
         );
         continue;
       }
-      const stopHeartbeat = startHeartbeat(journal, migration.name);
+      const stopHeartbeat = startHeartbeat(journal, migration.name, claimId);
       try {
         await migration.up({ service, logger, name: migration.name });
-        await journal.markApplied(migration.name);
+        await journal.markApplied(migration.name, claimId);
       } catch (err) {
-        await journal.removeRunning(migration.name);
+        await journal.removeRunning(migration.name, claimId);
         throw err;
       } finally {
         stopHeartbeat();
@@ -1764,9 +1862,19 @@ var createMongoMigrationRunner = (service, options = {}) => {
     const appliedFiles = files.filter((file) => applied.has(migrationNameOf(file))).reverse();
     for (const file of appliedFiles) {
       const migration = await loadMigration(migrationDir, file);
+      const claimId = await journal.claimRollback(migration.name, basename(file), leaseMs);
+      if (claimId === null) {
+        logger.info({ name: migration.name }, "migration rollback already claimed, skipping");
+        continue;
+      }
+      const stopHeartbeat = startHeartbeat(journal, migration.name, claimId);
       logger.info({ name: migration.name }, "running migration down");
-      await migration.down({ service, logger, name: migration.name });
-      await journal.unrecord(migration.name);
+      try {
+        await migration.down({ service, logger, name: migration.name });
+        await journal.unrecord(migration.name, claimId);
+      } finally {
+        stopHeartbeat();
+      }
       logger.info({ name: migration.name }, "migration rolled back");
       if (targetName !== void 0 && migration.name === targetName) break;
     }
@@ -1867,7 +1975,6 @@ var QueryBuilder = class _QueryBuilder {
   constructor(ctx) {
     this.ctx = ctx;
   }
-  ctx;
   _filter = {};
   _sort;
   _skip;
@@ -2308,6 +2415,16 @@ var toMongoValidator = (schema) => ({
 });
 
 // src/schema/types.ts
+var SUPPORTED_STRING_FORMATS = /* @__PURE__ */ new Set([
+  "email",
+  "uri",
+  "date-time",
+  "date",
+  "uuid",
+  "hostname",
+  "ipv4",
+  "ipv6"
+]);
 var chain = (field) => {
   const obj = field;
   obj.optional = () => chain({ ...field, flags: { ...field.flags, optional: true } });
@@ -2321,6 +2438,11 @@ function objectField(properties, opts = {}) {
 var s = {
   /** UTF-8 string field (optional `format` / length / regex constraints). */
   string(opts = {}) {
+    if (opts.format !== void 0 && !SUPPORTED_STRING_FORMATS.has(opts.format)) {
+      throw new Error(
+        `Unsupported string format "${opts.format}"; supported: ${[...SUPPORTED_STRING_FORMATS].join(", ")}`
+      );
+    }
     return chain({ kind: "string", ...BASE, ...opts });
   },
   /** 32-bit integer field with optional bounds (min/max, exclusive, multipleOf). */
@@ -2486,6 +2608,200 @@ var checkReservedValue = (key, value, path, issues) => {
     `Reserved field "${key}" must be ${types.join(" | ")}`
   );
 };
+var typeMatches = (value, type) => {
+  if (type === "number") return typeof value === "number" || value instanceof BSON.Long;
+  if (type === "int") {
+    return value instanceof BSON.Int32 || typeof value === "number" && Number.isInteger(value);
+  }
+  if (type === "long") {
+    return value instanceof BSON.Long || typeof value === "number" && Number.isInteger(value);
+  }
+  if (type === "double") return typeof value === "number" || value instanceof BSON.Double;
+  if (type === "decimal") return value instanceof BSON.Decimal128;
+  if (type === "object")
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+  if (type === "array") return Array.isArray(value);
+  if (type === "string") return typeof value === "string";
+  if (type === "bool" || type === "boolean") return typeof value === "boolean";
+  if (type === "date") return value instanceof Date;
+  if (type === "objectId") return value instanceof BSON.ObjectId;
+  if (type === "null") return value === null;
+  if (type === "binData") return value instanceof BSON.Binary;
+  if (type === "regex") return value instanceof RegExp;
+  return true;
+};
+var comparable = (value) => {
+  if (typeof value === "number") return value;
+  if (value instanceof BSON.Long || value instanceof BSON.Int32 || value instanceof BSON.Double) {
+    return Number(value.toString());
+  }
+  if (value instanceof BSON.Decimal128) return Number(value.toString());
+  return void 0;
+};
+var validateRawSchema = (schema, value, path, issues) => {
+  const types = schema.bsonType === void 0 ? [] : [schema.bsonType].flat();
+  if (types.length > 0 && !types.some((type) => typeMatches(value, type))) {
+    push(issues, path, "type", types.join(" | "), "BSON type does not match raw schema");
+    return;
+  }
+  if (schema.enum && !schema.enum.some(
+    (candidate) => BSON.EJSON.stringify(candidate) === BSON.EJSON.stringify(value)
+  )) {
+    push(issues, path, "enum", "raw enum", "Value is not in the allowed set");
+  }
+  if (typeof value === "string") {
+    if (schema.minLength !== void 0 && value.length < schema.minLength) {
+      push(issues, path, "constraint", `minLength ${schema.minLength}`, "String is too short");
+    }
+    if (schema.maxLength !== void 0 && value.length > schema.maxLength) {
+      push(issues, path, "constraint", `maxLength ${schema.maxLength}`, "String is too long");
+    }
+    if (schema.pattern && !new RegExp(schema.pattern).test(value)) {
+      push(
+        issues,
+        path,
+        "constraint",
+        `pattern ${schema.pattern}`,
+        "String does not match pattern"
+      );
+    }
+  }
+  const numeric = comparable(value);
+  if (numeric !== void 0) {
+    const minimum = typeof schema.exclusiveMinimum === "number" ? schema.exclusiveMinimum : schema.minimum;
+    const maximum = typeof schema.exclusiveMaximum === "number" ? schema.exclusiveMaximum : schema.maximum;
+    if (minimum !== void 0 && (numeric < minimum || schema.exclusiveMinimum === true && numeric === minimum)) {
+      push(issues, path, "constraint", `minimum ${minimum}`, "Number is below minimum");
+    }
+    if (maximum !== void 0 && (numeric > maximum || schema.exclusiveMaximum === true && numeric === maximum)) {
+      push(issues, path, "constraint", `maximum ${maximum}`, "Number is above maximum");
+    }
+    if (schema.multipleOf !== void 0 && Math.abs(numeric / schema.multipleOf - Math.round(numeric / schema.multipleOf)) > 1e-9) {
+      push(
+        issues,
+        path,
+        "constraint",
+        `multipleOf ${schema.multipleOf}`,
+        "Number is not a multiple"
+      );
+    }
+  }
+  if (Array.isArray(value)) {
+    if (schema.minItems !== void 0 && value.length < schema.minItems) {
+      push(issues, path, "constraint", `minItems ${schema.minItems}`, "Array is too short");
+    }
+    if (schema.maxItems !== void 0 && value.length > schema.maxItems) {
+      push(issues, path, "constraint", `maxItems ${schema.maxItems}`, "Array is too long");
+    }
+    if (schema.uniqueItems) {
+      const unique = new Set(value.map((item) => BSON.EJSON.stringify(item, { relaxed: false })));
+      if (unique.size !== value.length) {
+        push(issues, path, "constraint", "uniqueItems", "Array contains duplicate items");
+      }
+    }
+    if (Array.isArray(schema.items)) {
+      schema.items.forEach((item, index) => {
+        if (index < value.length)
+          validateRawSchema(item, value[index], `${path}[${index}]`, issues);
+      });
+    } else if (schema.items) {
+      value.forEach((item, index) => {
+        validateRawSchema(schema.items, item, `${path}[${index}]`, issues);
+      });
+    }
+  }
+  if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+    const object = value;
+    for (const required of schema.required ?? []) {
+      if (object[required] === void 0)
+        push(issues, `${path}.${required}`, "missing", "required", "Required field is missing");
+    }
+    for (const [key, child] of Object.entries(schema.properties ?? {})) {
+      if (key in object)
+        validateRawSchema(child, object[key], path ? `${path}.${key}` : key, issues);
+    }
+    for (const [pattern, child] of Object.entries(schema.patternProperties ?? {})) {
+      for (const key of Object.keys(object)) {
+        if (new RegExp(pattern).test(key))
+          validateRawSchema(child, object[key], `${path}.${key}`, issues);
+      }
+    }
+    if (schema.additionalProperties === false) {
+      const known = /* @__PURE__ */ new Set([
+        ...Object.keys(schema.properties ?? {}),
+        ...Object.keys(object).filter(
+          (key) => Object.keys(schema.patternProperties ?? {}).some(
+            (pattern) => new RegExp(pattern).test(key)
+          )
+        )
+      ]);
+      for (const key of Object.keys(object)) {
+        if (!known.has(key))
+          push(
+            issues,
+            `${path}.${key}`,
+            "unknown_key",
+            "no additional properties",
+            "Unexpected field"
+          );
+      }
+    } else if (typeof schema.additionalProperties === "object") {
+      for (const key of Object.keys(object)) {
+        if (!(key in (schema.properties ?? {})))
+          validateRawSchema(schema.additionalProperties, object[key], `${path}.${key}`, issues);
+      }
+    }
+    const count = Object.keys(object).length;
+    if (schema.minProperties !== void 0 && count < schema.minProperties)
+      push(
+        issues,
+        path,
+        "constraint",
+        `minProperties ${schema.minProperties}`,
+        "Too few properties"
+      );
+    if (schema.maxProperties !== void 0 && count > schema.maxProperties)
+      push(
+        issues,
+        path,
+        "constraint",
+        `maxProperties ${schema.maxProperties}`,
+        "Too many properties"
+      );
+    for (const [key, dependency] of Object.entries(schema.dependencies ?? {})) {
+      if (!(key in object)) continue;
+      if (Array.isArray(dependency)) {
+        for (const required of dependency)
+          if (!(required in object))
+            push(issues, path, "constraint", "dependencies", `${key} requires ${required}`);
+      } else validateRawSchema(dependency, object, path, issues);
+    }
+  }
+  for (const child of schema.allOf ?? []) validateRawSchema(child, value, path, issues);
+  if (schema.anyOf) {
+    const matches = schema.anyOf.some((child) => {
+      const candidate = [];
+      validateRawSchema(child, value, path, candidate);
+      return candidate.length === 0;
+    });
+    if (!matches) push(issues, path, "constraint", "anyOf", "No anyOf schema matched");
+  }
+  if (schema.oneOf) {
+    const matches = schema.oneOf.filter((child) => {
+      const candidate = [];
+      validateRawSchema(child, value, path, candidate);
+      return candidate.length === 0;
+    }).length;
+    if (matches !== 1)
+      push(issues, path, "constraint", "oneOf", "Exactly one oneOf schema must match");
+  }
+  if (schema.not) {
+    const candidate = [];
+    validateRawSchema(schema.not, value, path, candidate);
+    if (candidate.length === 0)
+      push(issues, path, "constraint", "not", "Value matched a forbidden schema");
+  }
+};
 
 // src/schema/validate-doc/field-validators.ts
 var patternCache = /* @__PURE__ */ new WeakMap();
@@ -2501,6 +2817,22 @@ var compiledPattern = (field) => {
     return void 0;
   }
 };
+var STRING_FORMAT_VALIDATORS = {
+  email: (value) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value),
+  uri: (value) => {
+    try {
+      return new URL(value).protocol.length > 0;
+    } catch {
+      return false;
+    }
+  },
+  "date-time": (value) => /^\d{4}-\d{2}-\d{2}T/.test(value) && !Number.isNaN(Date.parse(value)),
+  date: (value) => /^\d{4}-\d{2}-\d{2}$/.test(value) && !Number.isNaN(Date.parse(`${value}T00:00:00Z`)),
+  uuid: (value) => /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value),
+  hostname: (value) => /^(?=.{1,253}$)[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/i.test(value),
+  ipv4: (value) => isIP(value) === 4,
+  ipv6: (value) => isIP(value) === 6
+};
 var stringValidator = (_deps, field, value, path, issues) => {
   const f = field;
   if (typeof value !== "string") {
@@ -2535,6 +2867,16 @@ var stringValidator = (_deps, field, value, path, issues) => {
       `"${value}" does not match pattern`
     );
   }
+  const format = f.format ? STRING_FORMAT_VALIDATORS[f.format] : void 0;
+  if (format && !format(value)) {
+    push(
+      issues,
+      path,
+      "constraint",
+      `string(format ${f.format})`,
+      `"${value}" is not a valid ${f.format}`
+    );
+  }
 };
 var numberValidator = (_deps, field, value, path, issues) => {
   const f = field;
@@ -2605,7 +2947,8 @@ var nullValidator = (_deps, _field, value, path, issues) => {
 };
 var anyValidator = () => {
 };
-var rawValidator = () => {
+var rawValidator = (_deps, field, value, path, issues) => {
+  validateRawSchema(field.fragment, value, path, issues);
 };
 var enumValidator = (_deps, field, value, path, issues) => {
   const f = field;
@@ -2875,13 +3218,13 @@ var CacheInvalidator = class {
         connectedAt = Date.now();
         if (backoff > 0) {
           this.cache.invalidateByCollection(
-            cacheCollectionKey(ref.db.databaseName, ref.collection)
+            cacheCollectionKey(ref.db.databaseName, ref.collection, ref.namespace)
           );
         }
         const iterator = stream[Symbol.asyncIterator]();
         for await (const _change of iterator) {
           this.cache.invalidateByCollection(
-            cacheCollectionKey(ref.db.databaseName, ref.collection)
+            cacheCollectionKey(ref.db.databaseName, ref.collection, ref.namespace)
           );
         }
       } catch (err) {
@@ -2998,7 +3341,8 @@ var makeGetDbUrl = (dbClients, config) => (name) => {
 };
 var makeConnectionFactory = (dbClients, db, getDbUrl, buildManager2, openedClients = /* @__PURE__ */ new Map()) => {
   const connecting = /* @__PURE__ */ new Map();
-  return async (names) => {
+  let transition = Promise.resolve();
+  const connect = async (names) => {
     const keys = names && names.length > 0 ? names : Object.keys(dbClients);
     const openedThisCall = [];
     const assignedThisCall = [];
@@ -3016,6 +3360,7 @@ var makeConnectionFactory = (dbClients, db, getDbUrl, buildManager2, openedClien
               const c = new MongoClient(dbUrl, {
                 connectTimeoutMS: definition.connectTimeoutMs ?? 1e4,
                 serverSelectionTimeoutMS: definition.connectTimeoutMs ?? 1e4,
+                monitorCommands: definition.monitorCommands ?? false,
                 ...definition.readPreference && { readPreference: definition.readPreference },
                 ...definition.readConcern && { readConcern: definition.readConcern },
                 ...definition.writeConcern && { writeConcern: definition.writeConcern }
@@ -3046,18 +3391,20 @@ var makeConnectionFactory = (dbClients, db, getDbUrl, buildManager2, openedClien
       throw err;
     }
   };
+  return (names) => {
+    const result = transition.then(() => connect(names));
+    transition = result.catch(() => {
+    });
+    return result;
+  };
 };
 var closeConnections = async (openedClients) => {
-  const closes = [...openedClients.values()].map((client) => {
-    try {
-      return Promise.resolve(client.close()).catch(() => {
-      });
-    } catch {
-      return Promise.resolve();
-    }
-  });
-  await Promise.allSettled(closes);
+  const results = await Promise.allSettled(
+    [...openedClients.values()].map((client) => client.close())
+  );
   openedClients.clear();
+  const errors = results.filter((result) => result.status === "rejected").map((result) => result.reason);
+  if (errors.length > 0) throw new AggregateError(errors, "Failed to close MongoDB connections");
 };
 
 // src/service/health.ts
@@ -3099,9 +3446,19 @@ var createForeignKeyLoader = (deps2, collection, foreignField, options = {}) =>
       collection,
       { [foreignField]: { $in: keys } },
       {
-        ...options.maxDocs !== void 0 ? { limit: options.maxDocs } : {}
+        limit: options.maxDocs !== void 0 ? options.maxDocs + 1 : 0,
+        ...options.session !== void 0 ? { session: options.session } : {},
+        ...options.maxTimeMS !== void 0 ? { maxTimeMS: options.maxTimeMS } : {},
+        ...options.readPreference !== void 0 ? { readPreference: options.readPreference } : {},
+        ...options.readConcern !== void 0 ? { readConcern: options.readConcern } : {},
+        ...options.queryCache !== void 0 ? { queryCache: options.queryCache } : {}
       }
     );
+    if (options.maxDocs !== void 0 && docs.length > options.maxDocs) {
+      throw new BadRequest(
+        `populate: ${collection}.${foreignField} exceeded maxDocs ${options.maxDocs}; raise the cap or narrow the relation`
+      );
+    }
     const index = /* @__PURE__ */ new Map();
     for (const doc of docs) {
       const value = doc[foreignField];
@@ -3264,8 +3621,11 @@ 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 });
+var makeOpDeps = (logger, dbLabel, resolve, wrapMongoErrors, debugQuery) => {
+  const trace = (meta2, fn) => traceDbOp(logger, meta2, fn, {
+    wrapMongoErrors,
+    ...debugQuery !== void 0 ? { debugQuery } : {}
+  });
   const meta = (collection, op, params) => ({
     collection: String(collection),
     physicalCollection: resolve(String(collection)),
@@ -3335,8 +3695,6 @@ var PipelineBuilder = class _PipelineBuilder {
     this.deps = deps2;
     this.stages = stages;
   }
-  deps;
-  stages;
   /** Raw accumulated stages — embeddable into `$lookup` / `$facet` branches. */
   raw() {
     return this.stages;
@@ -3669,20 +4027,20 @@ var createCachedAggregate = (ctx) => {
     const shouldDedupe = resolved.dedupe !== false && (resolved.dedupe === true || opts.dedupeReads === true && noSession) && opts.inFlight !== void 0;
     const runDriver = () => defineCrudOp(deps2, collection, opName, execute, options, false, { pipeline });
     const key = useCache ? cache.key(
-      cacheCollectionKey(client.databaseName, physical),
+      cacheCollectionKey(client.databaseName, physical, opts.cacheNamespace),
       stableHash([opName, pipeline, options])
     ) : void 0;
     const toSourceKeys = () => collectAggSources(String(collection), pipeline, sources).map((name) => {
       try {
-        return cacheCollectionKey(client.databaseName, resolve(name));
+        return cacheCollectionKey(client.databaseName, resolve(name), opts.cacheNamespace);
       } catch {
-        return cacheCollectionKey(client.databaseName, name);
+        return cacheCollectionKey(client.databaseName, name, opts.cacheNamespace);
       }
     });
     const runOnce = () => {
       if (useCache && key) {
         const sourceKeys = toSourceKeys();
-        const primaryKey = cacheCollectionKey(client.databaseName, physical);
+        const primaryKey = cacheCollectionKey(client.databaseName, physical, opts.cacheNamespace);
         const versions = { [primaryKey]: cache.versionOf(primaryKey) };
         for (const col of sourceKeys) {
           if (!(col in versions)) versions[col] = cache.versionOf(col);
@@ -3697,8 +4055,8 @@ var createCachedAggregate = (ctx) => {
       return runDriver();
     };
     if (shouldDedupe) {
-      const primaryKey = cacheCollectionKey(client.databaseName, physical);
-      const gen = cache !== void 0 ? cache.versionOf(primaryKey) : "";
+      const primaryKey = cacheCollectionKey(client.databaseName, physical, opts.cacheNamespace);
+      const gen = cache !== void 0 ? toSourceKeys().map((source) => `${source}:${cache.versionOf(source)}`).join("|") : "";
       const dedupeKey = `${primaryKey}|${gen}|${opName}|${stableHash([pipeline, options])}`;
       return await opts.inFlight.run(dedupeKey, runOnce);
     }
@@ -3907,7 +4265,13 @@ var makeTextSearchOp = (ctx) => {
 // src/service/aggregation/index.ts
 var makeAggregationOps = (client, dbLabel, logger, opts) => {
   const resolve = opts.resolveCollectionName;
-  const deps2 = makeOpDeps(logger, dbLabel, resolve, opts.wrapMongoErrors === true);
+  const deps2 = makeOpDeps(
+    logger,
+    dbLabel,
+    resolve,
+    opts.wrapMongoErrors === true,
+    opts.debugQuery
+  );
   const coll = (collection) => client.collection(resolve(String(collection)));
   const ctx = {
     resolve,
@@ -3925,11 +4289,7 @@ 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 cloneDefault = (value) => cloneDeep(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)) {
@@ -3978,7 +4338,9 @@ var checkDocsDrift = (options, collection, op, docs) => {
   const schema = options.getSchema?.(collection);
   if (!schema) return;
   for (const doc of docs) {
-    const issues = validateDoc(schema, doc);
+    const issues = validateDoc(schema, doc).filter(
+      (issue) => options.partial !== true || issue.code !== "missing"
+    );
     if (issues.length === 0) continue;
     const detail = issues.map((i) => `${i.path}: ${i.message}`).join("; ");
     const extra = { collection, db: options.db, op, issues };
@@ -4012,7 +4374,8 @@ var createCrudContext = (client, dbLabel, logger, opts) => {
     logger,
     dbLabel,
     resolve,
-    opts.wrapMongoErrors === true
+    opts.wrapMongoErrors === true,
+    opts.debugQuery
   );
   const coll = (name) => client.collection(resolve(String(name)));
   const toDriverFilter = (filter) => filter;
@@ -4020,7 +4383,7 @@ var createCrudContext = (client, dbLabel, logger, opts) => {
   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)))
+      cacheCollectionKey(client.databaseName, resolve(String(collection)), opts.cacheNamespace)
     );
   };
   const timestampsFor = (collection) => opts.timestamps?.[String(collection)];
@@ -4050,6 +4413,26 @@ var createCrudContext = (client, dbLabel, logger, opts) => {
     if (!ts?.updatedAt) return doc;
     return { ...doc, [ts.updatedAt]: /* @__PURE__ */ new Date() };
   };
+  const validateWrite = (collection, doc, generateId = true) => {
+    if (opts.validateWrites === false) return;
+    const schema = opts.getSchema?.(String(collection));
+    if (!schema) return;
+    if (generateId && doc._id === void 0 && schema.properties._id?.kind === "objectId") {
+      doc._id = new ObjectId();
+    }
+    const issues = validateDoc(schema, doc).filter(
+      (issue) => generateId || issue.path !== "_id" || issue.code !== "missing"
+    );
+    if (issues.length > 0) {
+      throw new DomainError("VALIDATION_FAILED", "Document failed schema validation", {
+        db: client.databaseName,
+        collection: String(collection),
+        ...doc._id !== void 0 ? { documentId: doc._id } : {},
+        fields: [...new Set(issues.map((issue) => issue.path))],
+        issues
+      });
+    }
+  };
   const read = async (collection, opName, filter, options, execute, shape = "none", keyExtra) => {
     const physical = resolve(String(collection));
     const resolved = resolveQueryOptions(options);
@@ -4062,14 +4445,15 @@ var createCrudContext = (client, dbLabel, logger, opts) => {
     const checkDrift = (value) => {
       const mode = resolveDriftMode(resolved.sdk.drift, opts.drift);
       if (mode === "off") return;
-      if (resolved.driverOpts.projection !== void 0) return;
+      const partial = resolved.driverOpts.projection !== void 0;
       const docs = shape === "many" ? value : shape === "one" && value !== null ? [value] : [];
       checkDocsDrift(
         {
           logger,
           db: dbLabel,
           drift: mode,
-          ...opts.getSchema !== void 0 ? { getSchema: opts.getSchema } : {}
+          ...opts.getSchema !== void 0 ? { getSchema: opts.getSchema } : {},
+          partial
         },
         String(collection),
         opName,
@@ -4098,14 +4482,17 @@ var createCrudContext = (client, dbLabel, logger, opts) => {
       }
       return payloadHash;
     };
-    const key = useCache ? opts.cache.key(cacheCollectionKey(client.databaseName, physical), getPayloadHash()) : void 0;
+    const key = useCache ? opts.cache.key(
+      cacheCollectionKey(client.databaseName, physical, opts.cacheNamespace),
+      getPayloadHash()
+    ) : void 0;
     const fetchAndCheck = () => executeWrapped().then((value) => {
       checkDrift(value);
       return value;
     });
     const runOnce = () => {
       if (useCache && key) {
-        const colKey = cacheCollectionKey(client.databaseName, physical);
+        const colKey = cacheCollectionKey(client.databaseName, physical, opts.cacheNamespace);
         const versions = { [colKey]: opts.cache.versionOf(colKey) };
         const hit = opts.cache.get(key);
         if (hit !== void 0) return Promise.resolve(hit);
@@ -4117,7 +4504,7 @@ var createCrudContext = (client, dbLabel, logger, opts) => {
       return fetchAndCheck();
     };
     if (shouldDedupe) {
-      const colKey = cacheCollectionKey(client.databaseName, physical);
+      const colKey = cacheCollectionKey(client.databaseName, physical, opts.cacheNamespace);
       const gen = opts.cache !== void 0 ? opts.cache.versionOf(colKey) : "";
       return await opts.inFlight.run(`${colKey}|${gen}|${getPayloadHash()}`, runOnce);
     }
@@ -4147,6 +4534,7 @@ var createCrudContext = (client, dbLabel, logger, opts) => {
     stampCreate,
     stampUpdate,
     stampReplace,
+    validateWrite,
     read,
     normalizeFindOptions
   };
@@ -4371,7 +4759,16 @@ var makeWatchOps = (ctx) => {
 // src/service/crud/write-ops.ts
 var makeWriteOps = (ctx, readOps) => {
   const { opts } = ctx;
-  const { coll, toDriverFilter, writeRun, invalidate, stampCreate, stampUpdate, stampReplace } = ctx;
+  const {
+    coll,
+    toDriverFilter,
+    writeRun,
+    invalidate,
+    stampCreate,
+    stampUpdate,
+    stampReplace,
+    validateWrite
+  } = ctx;
   const { getOne } = readOps;
   const safeAfterHooks = async (collection, name, hookCtx) => {
     try {
@@ -4393,6 +4790,7 @@ var makeWriteOps = (ctx, readOps) => {
       doc
     });
     stampCreate(collection, doc);
+    validateWrite(collection, doc);
     const result = await writeRun(
       collection,
       "mongo.insertOne",
@@ -4426,7 +4824,10 @@ var makeWriteOps = (ctx, readOps) => {
       collection: String(collection),
       docs
     });
-    for (const d of docs) stampCreate(collection, d);
+    for (const d of docs) {
+      stampCreate(collection, d);
+      validateWrite(collection, d);
+    }
     const result = await writeRun(
       collection,
       "mongo.insertMany",
@@ -4550,6 +4951,7 @@ var makeWriteOps = (ctx, readOps) => {
       filter
     });
     const effective = stampReplace(collection, replacement);
+    validateWrite(collection, effective, false);
     const result = await writeRun(
       collection,
       "mongo.findOneAndReplace",
@@ -4583,6 +4985,8 @@ var makeWriteOps = (ctx, readOps) => {
       collection: String(collection),
       filter
     });
+    const effective = stampReplace(collection, replacement);
+    validateWrite(collection, effective, false);
     const result = await writeRun(
       collection,
       "mongo.replaceOne",
@@ -4593,7 +4997,7 @@ var makeWriteOps = (ctx, readOps) => {
         };
         return coll(collection).replaceOne(
           toDriverFilter(filter),
-          stampReplace(collection, replacement),
+          effective,
           repOpts
         );
       },
@@ -4849,6 +5253,7 @@ var makeCrudOps = (client, dbLabel, logger, opts) => {
     ...makeWatchOps(ctx)
   };
 };
+var { EJSON: EJSON2 } = BSON;
 var tag = (value) => {
   if (value instanceof ObjectId) return { t: "oid", v: value.toHexString() };
   if (value instanceof Date) return { t: "date", v: value.toISOString() };
@@ -4856,6 +5261,9 @@ var tag = (value) => {
   if (typeof value === "number") return { t: "number", v: value };
   if (typeof value === "boolean") return { t: "boolean", v: value };
   if (value === null || value === void 0) return { t: "null" };
+  if (typeof value === "object" && "_bsontype" in value) {
+    return { t: "bson", v: EJSON2.stringify(value, { relaxed: false }) };
+  }
   throw new BadRequest(
     `paginateCursor: unsupported sort value type "${typeof value}" \u2014 key values must be ObjectId, Date, string, number, boolean, or null`
   );
@@ -4889,6 +5297,11 @@ var untag = (tagged) => {
       return tagged.v;
     case "null":
       return null;
+    case "bson":
+      if (typeof tagged.v !== "string") {
+        throw new BadRequest("paginateCursor: invalid cursor \u2014 BSON value must be a string");
+      }
+      return EJSON2.parse(tagged.v, { relaxed: false });
   }
 };
 var encodeCursor = (cursor) => Buffer.from(
@@ -4933,11 +5346,17 @@ var makePaginateCursor = (ctx) => {
   const { client, dbLabel, logger, opts, resolve, deps: deps2 } = ctx;
   const paginateCursor = async (collection, baseFilter, config) => {
     const sortKeys = Object.entries(config.sort);
+    const uniqueTiebreaker = config.uniqueTiebreaker ?? "_id";
     if (sortKeys.length === 0) {
       throw new BadRequest(
         "paginateCursor: `sort` is required (include a unique tiebreaker like `_id`)"
       );
     }
+    if (sortKeys.at(-1)?.[0] !== uniqueTiebreaker) {
+      throw new BadRequest(
+        `paginateCursor: the final sort key must be the unique tiebreaker "${uniqueTiebreaker}"`
+      );
+    }
     if (config.before !== void 0 && config.after !== void 0) {
       throw new BadRequest("paginateCursor: provide either `after` or `before`, not both");
     }
@@ -4993,10 +5412,15 @@ var makePaginateCursor = (ctx) => {
       "mongo.paginateCursor",
       page
     );
-    const boundary = backwards ? rows[limit] : page[page.length - 1];
+    const boundary = backwards ? page[0] : page[page.length - 1];
     let nextCursor = null;
     if (hasMore && boundary !== void 0) {
-      const values = sortKeys.map(([f]) => boundary[f]);
+      const values = sortKeys.map(
+        ([f]) => f.split(".").reduce(
+          (value, part) => value !== null && typeof value === "object" ? value[part] : void 0,
+          boundary
+        )
+      );
       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"
@@ -5023,6 +5447,12 @@ var makePaginateFlexible = (ctx) => {
       // APIs used to disagree silently (10 vs 100).
       { limit: DEFAULT_FIND_LIMIT }
     );
+    const maxOffset = config.maxOffset ?? 1e4;
+    if (normalized.offset > maxOffset) {
+      throw new BadRequest(
+        `paginateFlexible: offset ${normalized.offset} exceeds maxOffset ${maxOffset}; use paginateCursor for deep pages`
+      );
+    }
     const dataStages = [
       ...config.prePipeline ?? [],
       ...config.sort && Object.keys(config.sort).length > 0 ? [{ $sort: config.sort }] : [],
@@ -5057,19 +5487,18 @@ var makePaginateFlexible = (ctx) => {
         const row = rows[0];
         const data = row?.data ?? [];
         const totalCount = row?.totalCount?.[0]?.count ?? 0;
-        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
-          );
-        }
+        checkDocsDrift(
+          {
+            logger,
+            db: dbLabel,
+            drift: resolveDriftMode(config.queryOptions?.drift, opts.drift),
+            ...opts.getSchema !== void 0 ? { getSchema: opts.getSchema } : {},
+            partial: config.projection !== void 0
+          },
+          String(collection),
+          "mongo.paginateFlexible",
+          data
+        );
         return buildPaginationResult(data, totalCount, normalized.page, normalized.limit);
       }
     });
@@ -5080,7 +5509,13 @@ var makePaginateFlexible = (ctx) => {
 // src/service/pagination/index.ts
 var makePaginationOps = (client, dbLabel, logger, opts) => {
   const resolve = opts.resolveCollectionName;
-  const deps2 = makeOpDeps(logger, dbLabel, resolve, opts.wrapMongoErrors === true);
+  const deps2 = makeOpDeps(
+    logger,
+    dbLabel,
+    resolve,
+    opts.wrapMongoErrors === true,
+    opts.debugQuery
+  );
   const ctx = {
     client,
     dbLabel,
@@ -5097,16 +5532,37 @@ var makePaginationOps = (client, dbLabel, logger, opts) => {
 };
 
 // src/service/schema-ops.ts
-var optionSignature = (o) => JSON.stringify([
-  Boolean(o?.unique),
-  Boolean(o?.sparse),
-  typeof o?.expireAfterSeconds === "number" ? o.expireAfterSeconds : null
-]);
+var optionSignature = (options) => {
+  const normalized = {
+    unique: Boolean(options?.unique),
+    sparse: Boolean(options?.sparse),
+    hidden: Boolean(options?.hidden),
+    expireAfterSeconds: typeof options?.expireAfterSeconds === "number" ? options.expireAfterSeconds : null
+  };
+  for (const key of [
+    "partialFilterExpression",
+    "collation",
+    "wildcardProjection",
+    "weights",
+    "default_language",
+    "language_override",
+    "textIndexVersion",
+    "2dsphereIndexVersion",
+    "bits",
+    "min",
+    "max",
+    "bucketSize",
+    "storageEngine"
+  ]) {
+    if (options?.[key] !== void 0) normalized[key] = options[key];
+  }
+  return stableStringify(normalized);
+};
 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 readCollectionValidation = async (physical) => {
     const info = await client.listCollections({ name: physical }).next();
-    return info?.options?.validator;
+    return info?.options ?? {};
   };
   const ensureDeclaredIndexes = async (collection, physical, def) => {
     const declared = def?.indexes ?? [];
@@ -5120,7 +5576,7 @@ var makeSchemaOps = (client, _logger, opts) => {
       try {
         await handle.createIndex(index.key, index.options);
       } catch (err) {
-        if (err?.code === 85) {
+        if ([85, 86].includes(err?.code ?? -1)) {
           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 }
@@ -5145,19 +5601,21 @@ var makeSchemaOps = (client, _logger, opts) => {
       created = false;
     }
     if (created) {
-      try {
-        await ensureDeclaredIndexes(collection, physical, def);
-      } catch (err) {
-        await client.dropCollection(physical).catch(() => {
-        });
-        throw err;
-      }
+      await ensureDeclaredIndexes(collection, physical, def);
       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 });
+      const current = await readCollectionValidation(physical);
+      const collMod = {};
+      if (stableStringify(current.validator) !== stableStringify(createOptions.validator)) {
+        collMod.validator = createOptions.validator;
+      }
+      for (const key of ["validationLevel", "validationAction"]) {
+        const requested = createOptions[key];
+        if (requested !== void 0 && current[key] !== requested) collMod[key] = requested;
+      }
+      if (Object.keys(collMod).length > 0) {
+        await client.command({ collMod: physical, ...collMod });
       }
     }
     await ensureDeclaredIndexes(collection, physical, def);
@@ -5173,6 +5631,7 @@ var makeSchemaOps = (client, _logger, opts) => {
       collMod: physical,
       validator: toMongoValidator(resolved)
     });
+    if (def) def.schema = resolved;
   };
   const syncIndexes = async (collection) => {
     const physical = opts.resolveCollectionName(collection);
@@ -5186,52 +5645,68 @@ var makeSchemaOps = (client, _logger, opts) => {
     const declaredByKey = new Map(
       declared.map((d) => [indexKeyOf(d.key, d.options), d])
     );
-    const created = [];
+    const keyPattern = (key) => JSON.stringify(Object.entries(key));
     const dropped = [];
-    for (const [key] of declaredByKey) {
-      if (!existingByKey.has(key)) {
-        await handle.createIndex(
-          declaredByKey.get(key).key,
-          declaredByKey.get(key).options
-        );
-      }
-    }
-    const after = (await handle.listIndexes().toArray()).filter((i) => i.name !== "_id_");
-    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));
+    const droppedNames = /* @__PURE__ */ new Set();
+    for (const spec of declaredByKey.values()) {
+      const signature = indexKeyOf(spec.key, spec.options);
+      if (existingByKey.has(signature)) continue;
+      for (const index of existing) {
+        const name = index.name;
+        if (droppedNames.has(name)) continue;
+        const sameName = spec.options?.name !== void 0 && index.name === spec.options.name;
+        if (sameName || keyPattern(index.key) === keyPattern(spec.key)) {
+          await handle.dropIndex(name);
+          droppedNames.add(name);
+          dropped.push(name);
+        }
       }
+      await handle.createIndex(spec.key, spec.options);
     }
-    for (const [key, name] of existingByKey) {
-      if (!declaredByKey.has(key)) {
+    for (const [signature, name] of existingByKey) {
+      if (!declaredByKey.has(signature) && !droppedNames.has(name)) {
         await handle.dropIndex(name);
         dropped.push(name);
       }
     }
+    const after = (await handle.listIndexes().toArray()).filter((i) => i.name !== "_id_");
+    const afterByKey = new Map(
+      after.map((i) => [indexKeyOf(i.key, i), i.name])
+    );
+    const created = [...declaredByKey].filter(([signature]) => !existingByKey.has(signature)).map(
+      ([signature, spec]) => spec.options?.name ?? afterByKey.get(signature) ?? JSON.stringify(spec.key)
+    );
     return { created, dropped };
   };
   return { createSchema, updateSchema, syncIndexes };
 };
-
-// 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 transaction = async (fn, options = {}) => {
+    const { allowNonTransactionalFallback, ...driverOptions } = options;
+    const allowFallback = allowNonTransactionalFallback ?? opts.allowNonTransactionalFallback ?? false;
     const session = client.startSession();
     try {
-      return await session.withTransaction(async () => fn(session), options);
+      return await session.withTransaction(async () => fn(session), driverOptions);
     } catch (err) {
       if (isTransactionUnsupportedError(err)) {
+        if (!allowFallback) {
+          if (opts.wrapMongoErrors) {
+            throw new InfraError(
+              "TRANSACTIONS_UNSUPPORTED",
+              "MongoDB deployment does not support transactions; enable allowNonTransactionalFallback to run non-atomically",
+              { db: handle.databaseName, op: "transaction" }
+            );
+          }
+          throw 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"
+            "transactions unsupported; running explicitly requested non-transactional fallback"
           );
         }
         return fn(null);
@@ -5241,16 +5716,14 @@ var makeTransactionOps = (client, handle, logger, _config, opts) => {
       }
       throw err;
     } finally {
-      await session.endSession();
+      await session.endSession().catch(() => {
+      });
     }
   };
-  const migrate = async (name, fn, filePath) => {
+  const migrate = async (name, fn, filePath, options = {}) => {
     const journal = handle.collection(opts.migrationCollectionPhysical);
     if (!journalIndexReady) {
-      try {
-        await journal.createIndex({ name: 1 }, { unique: true });
-      } catch {
-      }
+      await journal.createIndex({ name: 1 }, { unique: true });
       journalIndexReady = true;
     }
     const isDupKeyError = (err) => {
@@ -5262,10 +5735,11 @@ var makeTransactionOps = (client, handle, logger, _config, opts) => {
       const sessionOpts = session ? { session } : {};
       const now = /* @__PURE__ */ new Date();
       const expiresAt = new Date(Date.now() + MIGRATE_LEASE_MS);
+      const claimId = randomUUID();
       const stole = await journal.findOneAndUpdate(
         {
           name,
-          status: { $exists: true, $nin: ["applied"] },
+          status: { $exists: true, $nin: ["applied", "rolling_back"] },
           $or: [
             { expiresAt: { $lt: now } },
             {
@@ -5279,13 +5753,14 @@ var makeTransactionOps = (client, handle, logger, _config, opts) => {
             status: "running",
             appliedAt: now,
             expiresAt,
+            claimId,
             ...filePath ? { file: filePath } : {}
           }
         },
         { returnDocument: "before", ...sessionOpts }
       );
       if (stole !== null) {
-        await runClaimed(session);
+        await runClaimed(session, claimId);
         return;
       }
       try {
@@ -5295,6 +5770,7 @@ var makeTransactionOps = (client, handle, logger, _config, opts) => {
             appliedAt: now,
             status: "running",
             expiresAt,
+            claimId,
             ...filePath ? { file: filePath } : {}
           },
           sessionOpts
@@ -5313,13 +5789,13 @@ var makeTransactionOps = (client, handle, logger, _config, opts) => {
         }
         return;
       }
-      await runClaimed(session);
-    });
-    async function runClaimed(session) {
+      await runClaimed(session, claimId);
+    }, options);
+    async function runClaimed(session, claimId) {
       const sessionOpts = session ? { session } : {};
       const heartbeat = session === null ? setInterval(() => {
         void journal.updateOne(
-          { name, status: "running" },
+          { name, claimId, status: "running" },
           { $set: { expiresAt: new Date(Date.now() + MIGRATE_LEASE_MS) } }
         ).catch(() => {
         });
@@ -5328,16 +5804,15 @@ var makeTransactionOps = (client, handle, logger, _config, opts) => {
       try {
         await fn(session);
         const res = await journal.updateOne(
-          { name, status: "running" },
-          { $set: { status: "applied" } },
+          { name, claimId, status: "running" },
+          { $set: { status: "applied" }, $unset: { expiresAt: "", claimId: "" } },
           sessionOpts
         );
-        if (res?.matchedCount === 0) {
-          await journal.insertOne({ name, appliedAt: /* @__PURE__ */ new Date(), status: "applied" }, sessionOpts).catch(() => {
-          });
+        if (res.matchedCount === 0) {
+          throw new Error(`Migration "${name}" lost its claim before it could be marked applied`);
         }
       } catch (err) {
-        await journal.deleteOne({ name }, sessionOpts).catch(() => {
+        await journal.deleteOne({ name, claimId, status: "running" }, sessionOpts).catch(() => {
         });
         throw err;
       } finally {
@@ -5349,7 +5824,7 @@ var makeTransactionOps = (client, handle, logger, _config, opts) => {
 };
 
 // src/service/manager.ts
-var buildManager = (deps2, dbKey, dbName, client) => {
+var buildManager = (deps2, dbKey, dbName, client, cacheNamespace = "") => {
   const { dbClients, config, logger, sharedCache, dedupeReads, inFlight, collectionRefs } = deps2;
   const definition = dbClients[dbKey];
   const handle = client.db(dbName);
@@ -5362,7 +5837,11 @@ var buildManager = (deps2, dbKey, dbName, client) => {
     registry.set(logical, def);
     hooks[logical] = def.hooks;
     if (def.timestamps) timestamps[logical] = def.timestamps;
-    collectionRefs.push({ db: handle, collection: baseResolveCollectionName(logical) });
+    collectionRefs.push({
+      db: handle,
+      collection: baseResolveCollectionName(logical),
+      namespace: cacheNamespace
+    });
   }
   const getDefinition = (logical) => registry.get(logical);
   const resolveCollectionName = (logical) => {
@@ -5373,18 +5852,23 @@ var buildManager = (deps2, dbKey, dbName, client) => {
   };
   const crud = makeCrudOps(handle, dbName, logger, {
     resolveCollectionName,
+    cacheNamespace,
     wrapMongoErrors: deps2.wrapMongoErrors,
+    ...deps2.debugQuery !== void 0 ? { debugQuery: deps2.debugQuery } : {},
     ...sharedCache !== void 0 ? { cache: sharedCache } : {},
     dedupeReads,
     inFlight,
     hooks,
     timestamps,
+    ...deps2.validateWrites !== void 0 ? { validateWrites: deps2.validateWrites } : {},
     ...deps2.drift !== void 0 ? { drift: deps2.drift } : {},
     ...getDefinition !== void 0 ? { getSchema: (logical) => getDefinition(logical)?.schema } : {}
   });
   const pagination = makePaginationOps(handle, dbName, logger, {
     resolveCollectionName,
+    cacheNamespace,
     wrapMongoErrors: deps2.wrapMongoErrors,
+    ...deps2.debugQuery !== void 0 ? { debugQuery: deps2.debugQuery } : {},
     ...deps2.drift !== void 0 ? { drift: deps2.drift } : {},
     ...getDefinition !== void 0 ? { getSchema: (logical) => getDefinition(logical)?.schema } : {},
     ...sharedCache !== void 0 ? { cache: sharedCache } : {},
@@ -5393,7 +5877,9 @@ var buildManager = (deps2, dbKey, dbName, client) => {
   });
   const aggregation = makeAggregationOps(handle, dbName, logger, {
     resolveCollectionName,
+    cacheNamespace,
     wrapMongoErrors: deps2.wrapMongoErrors,
+    ...deps2.debugQuery !== void 0 ? { debugQuery: deps2.debugQuery } : {},
     ...sharedCache !== void 0 ? { cache: sharedCache } : {},
     dedupeReads,
     inFlight
@@ -5401,16 +5887,14 @@ var buildManager = (deps2, dbKey, dbName, client) => {
   const schema = makeSchemaOps(handle, logger, { resolveCollectionName, getDefinition });
   const transactionOps = makeTransactionOps(client, handle, logger, config, {
     migrationCollectionPhysical: resolveCollectionName("_migrations"),
-    wrapMongoErrors: deps2.wrapMongoErrors
+    wrapMongoErrors: deps2.wrapMongoErrors,
+    ...deps2.allowNonTransactionalFallback !== void 0 ? { allowNonTransactionalFallback: deps2.allowNonTransactionalFallback } : {}
   });
   const populator = makePopulator({
-    findMany: async (logical, filter, options) => {
-      const physical = resolveCollectionName(logical);
-      return handle.collection(physical).find(filter, {
-        ...options?.projection !== void 0 ? { projection: options.projection } : {},
-        limit: options?.limit ?? 1e4
-      }).toArray();
-    }
+    findMany: async (logical, filter, options) => crud.findMany(logical, filter, {
+      ...options,
+      cache: options?.queryCache ?? false
+    })
   });
   const populate = (async (docs, relations, options = {}) => {
     const result = await populator.populate(docs, relations, options);
@@ -5424,6 +5908,7 @@ var buildManager = (deps2, dbKey, dbName, client) => {
     ...transactionOps,
     populate,
     client: handle,
+    mongoClient: client,
     db: deps2.db
   };
 };
@@ -5451,25 +5936,44 @@ var createMongoService = (dbClients, configOverrides = {}) => {
         dedupeReads,
         inFlight,
         wrapMongoErrors: runtime.wrapMongoErrors,
+        ...configOverrides.debugQuery !== void 0 ? { debugQuery: configOverrides.debugQuery } : {},
+        ...configOverrides.allowNonTransactionalFallback !== void 0 ? { allowNonTransactionalFallback: configOverrides.allowNonTransactionalFallback } : {},
+        ...configOverrides.validateWrites !== void 0 ? { validateWrites: configOverrides.validateWrites } : {},
         ...configOverrides.drift !== void 0 ? { drift: configOverrides.drift } : {},
         collectionRefs,
         db
       },
       key,
       dbName,
-      client
+      client,
+      stableHash(getDbUrl(key))
     )),
     openedClients
   );
-  const makeConnections = async (names) => {
+  let lifecycle = Promise.resolve();
+  const serializeLifecycle = (operation) => {
+    const result = lifecycle.then(operation, operation);
+    lifecycle = result.then(
+      () => {
+      },
+      () => {
+      }
+    );
+    return result;
+  };
+  const makeConnections = (names) => serializeLifecycle(async () => {
     await baseMakeConnections(names);
     await cacheInvalidator?.start(collectionRefs);
-  };
-  const closeConnections2 = async () => {
+  });
+  const closeConnections2 = () => serializeLifecycle(async () => {
     await cacheInvalidator?.stop();
     collectionRefs.length = 0;
-    await closeConnections(openedClients);
-  };
+    try {
+      await closeConnections(openedClients);
+    } finally {
+      for (const key of Object.keys(db)) delete db[key];
+    }
+  });
   const eachDb = async (fn) => {
     return Promise.all(Object.keys(db).map((key) => fn(db[key], key.replace(/Client$/, ""))));
   };