monsqlize 3.3.3 → 3.4.0

package/dist/esm/index.mjs

@@ -66,6 +66,13 @@ var ErrorCodes = {
   INVALID_OPERATION: "INVALID_OPERATION",
   /** Invalid local Vector Search options before the driver is called. */
   INVALID_VECTOR_SEARCH: "INVALID_VECTOR_SEARCH",
+  /** Search index lifecycle errors (v3.4.0). */
+  INVALID_SEARCH_INDEX_DEFINITION: "INVALID_SEARCH_INDEX_DEFINITION",
+  SEARCH_INDEX_EXISTS: "SEARCH_INDEX_EXISTS",
+  SEARCH_INDEX_NOT_FOUND: "SEARCH_INDEX_NOT_FOUND",
+  SEARCH_INDEX_UNSUPPORTED: "SEARCH_INDEX_UNSUPPORTED",
+  SEARCH_INDEX_BUILD_FAILED: "SEARCH_INDEX_BUILD_FAILED",
+  SEARCH_INDEX_WAIT_TIMEOUT: "SEARCH_INDEX_WAIT_TIMEOUT",
   /** Relation select is outside the supported inclusion-only top-level contract. */
   INVALID_RELATION_SELECT: "INVALID_RELATION_SELECT",
   /** A protected delete found declared Model relations that still reference its target. */
@@ -998,31 +1005,31 @@ function normalizeRelationSelect(value, context = {}) {
   if (value === void 0) {
     return void 0;
   }
-  const invalid2 = (reason) => {
+  const invalid3 = (reason) => {
     throw createError(
       ErrorCodes.INVALID_RELATION_SELECT,
       `Relation select must use non-empty top-level inclusion fields: ${reason}`,
       [{ ...context, value, reason }]
     );
   };
-  const rawTokens = typeof value === "string" ? [value] : Array.isArray(value) ? value : invalid2("select must be a string or string array");
+  const rawTokens = typeof value === "string" ? [value] : Array.isArray(value) ? value : invalid3("select must be a string or string array");
   const tokens = [];
   for (const rawToken of rawTokens) {
     if (typeof rawToken !== "string") {
-      invalid2("select array entries must be strings");
+      invalid3("select array entries must be strings");
     }
     const parts = rawToken.trim().split(/\s+/).filter(Boolean);
     if (parts.length === 0) {
-      invalid2("select must not be empty");
+      invalid3("select must not be empty");
     }
     tokens.push(...parts);
   }
   for (const token of tokens) {
     if (token.startsWith("-") || token.startsWith("+")) {
-      invalid2("exclusion and prefix tokens are not supported");
+      invalid3("exclusion and prefix tokens are not supported");
     }
     if (token.includes(".")) {
-      invalid2("dot-path fields are not supported");
+      invalid3("dot-path fields are not supported");
     }
   }
   return [...new Set(tokens)];
@@ -3577,8 +3584,8 @@ function normalizeExtensionValue(value, stack) {
     return `circular:${getExtensionObjectKey(objectValue)}`;
   }
   const prototype = Object.getPrototypeOf(objectValue);
-  const isPlainObject4 = prototype === Object.prototype || prototype === null;
-  if (!Array.isArray(objectValue) && !isPlainObject4) {
+  const isPlainObject5 = prototype === Object.prototype || prototype === null;
+  if (!Array.isArray(objectValue) && !isPlainObject5) {
     return `object:${prototype?.constructor?.name ?? "unknown"}:${getExtensionObjectKey(objectValue)}`;
   }
   stack.add(objectValue);
@@ -6692,6 +6699,28 @@ var ModelInstance = class {
   dropIndexes() {
     return this.runModelWrite(() => this.collection.dropIndexes());
   }
+  /** Search index lifecycle (v3.4.0): writes run as model writes for writePathPolicy. */
+  createSearchIndex(spec, options) {
+    return this.runModelWrite(() => this.collection.createSearchIndex(spec, options));
+  }
+  createSearchIndexes(specs) {
+    return this.runModelWrite(() => this.collection.createSearchIndexes(specs));
+  }
+  listSearchIndexes(options) {
+    return this.collection.listSearchIndexes(options);
+  }
+  getSearchIndex(name) {
+    return this.collection.getSearchIndex(name);
+  }
+  updateSearchIndex(name, definition) {
+    return this.runModelWrite(() => this.collection.updateSearchIndex(name, definition));
+  }
+  dropSearchIndex(name, options) {
+    return this.runModelWrite(() => this.collection.dropSearchIndex(name, options));
+  }
+  waitForSearchIndex(name, options) {
+    return this.collection.waitForSearchIndex(name, options);
+  }
   prewarmBookmarks(keyDims, pages) {
     return this.extendedCollection().prewarmBookmarks(keyDims, pages);
   }
@@ -8248,18 +8277,26 @@ var HealthChecker = class {
     const status = this._healthStatus.get(poolName);
     if (!status) return;
     const client = this._clients.get(poolName) ?? this._poolManager?._getPool(poolName);
-    if (this._inProgress.get(poolName)?.client === client && this._inProgress.has(poolName)) return;
+    const pending = this._inProgress.get(poolName);
+    if (pending && pending.client === client && pending.awaited) return;
     const epoch = this._epochs.get(poolName);
-    const promise = Promise.resolve().then(() => {
-      if (this._epochs.get(poolName) !== epoch || this._healthStatus.get(poolName) !== status) return;
-      return this._pingOverride ? this._pingOverride(poolName) : this._pingPool(poolName);
-    });
-    const operation = { client, promise };
-    this._inProgress.set(poolName, operation);
-    const clearPending = () => {
-      if (this._inProgress.get(poolName) === operation) this._inProgress.delete(poolName);
-    };
-    void promise.then(clearPending, clearPending);
+    let operation;
+    if (pending && pending.client === client) {
+      operation = pending;
+    } else {
+      const promise2 = Promise.resolve().then(() => {
+        if (this._epochs.get(poolName) !== epoch || this._healthStatus.get(poolName) !== status) return;
+        return this._pingOverride ? this._pingOverride(poolName) : this._pingPool(poolName);
+      });
+      operation = { client, promise: promise2, awaited: true };
+      this._inProgress.set(poolName, operation);
+      const clearPending = () => {
+        if (this._inProgress.get(poolName) === operation) this._inProgress.delete(poolName);
+      };
+      void promise2.then(clearPending, clearPending);
+    }
+    operation.awaited = true;
+    const promise = operation.promise;
     let timer;
     let lastError = null;
     try {
@@ -8271,6 +8308,7 @@ var HealthChecker = class {
       lastError = error instanceof Error ? error : new Error(String(error));
     } finally {
       if (timer) clearTimeout(timer);
+      operation.awaited = false;
     }
     if (this._epochs.get(poolName) !== epoch || this._healthStatus.get(poolName) !== status) return;
     status.lastCheck = /* @__PURE__ */ new Date();
@@ -10728,27 +10766,28 @@ function normalizeFindPageLimit(limit, defaults2) {
   }
   return rawLimit;
 }
-function documentReadKey(operation, collection, defaults2, query, options, field) {
-  const captured = snapshotReadInputs(normalizeQueryForCache(query, defaults2), options, collection.bsonOptions);
+function documentReadKey(operation, collection, defaults2, query, options, field, queryPrepared = false) {
+  const keyQuery = queryPrepared ? query ?? {} : normalizeQueryForCache(query, defaults2);
+  const captured = snapshotReadInputs(keyQuery, options, collection.bsonOptions);
   const keyOptions = buildResultCacheKeyOptions(captured.options, collection.bsonOptions);
   if (operation === "count") delete keyOptions.fieldsAsRaw;
   const body = field === void 0 ? stableCacheKeyString(captured.query, "document") : stableCacheKeyString({ key: field, query: captured.query });
   return `${operation}:${buildCollectionCacheNamespace(collection, defaults2)}:${body}:${stableCacheKeyString(keyOptions)}`;
 }
-function buildFindCacheKey(collection, defaults2 = {}, query, options) {
+function buildFindCacheKey(collection, defaults2 = {}, query, options, queryPrepared = false) {
   return documentReadKey("find", collection, defaults2, query, normalizeFindProjectionOptions({
     limit: defaults2.findLimit,
     ...options ?? {}
-  }));
+  }), void 0, queryPrepared);
 }
-function buildFindOneCacheKey(collection, defaults2 = {}, query, options) {
-  return documentReadKey("findOne", collection, defaults2, query, normalizeFindProjectionOptions(options));
+function buildFindOneCacheKey(collection, defaults2 = {}, query, options, queryPrepared = false) {
+  return documentReadKey("findOne", collection, defaults2, query, normalizeFindProjectionOptions(options), void 0, queryPrepared);
 }
-function buildCountCacheKey(collection, defaults2 = {}, query, options) {
-  return documentReadKey("count", collection, defaults2, query, options);
+function buildCountCacheKey(collection, defaults2 = {}, query, options, queryPrepared = false) {
+  return documentReadKey("count", collection, defaults2, query, options, void 0, queryPrepared);
 }
-function buildDistinctCacheKey(collection, defaults2 = {}, field, query, options) {
-  return documentReadKey("distinct", collection, defaults2, query, options, field);
+function buildDistinctCacheKey(collection, defaults2 = {}, field, query, options, queryPrepared = false) {
+  return documentReadKey("distinct", collection, defaults2, query, options, field, queryPrepared);
 }
 function buildPreparedAggregateCacheKey(collection, defaults2 = {}, pipeline = [], options) {
   const namespace = buildCollectionCacheNamespace(collection, defaults2);
@@ -11760,7 +11799,7 @@ var FindChain = class {
     const cacheTTL = typeof this.options.cache === "number" ? this.options.cache : 0;
     const executeOptions = prepared.options;
     if (cacheTTL > 0 && this.queryCache && canCacheBsonResult(executeOptions) && !hasSessionOption(executeOptions) && !await isCollectionCacheBarrierActive(this.queryCache, this.collection, this.defaults)) {
-      const cacheKey = buildFindCacheKey(this.collection, this.defaults, prepared.query, executeOptions);
+      const cacheKey = buildFindCacheKey(this.collection, this.defaults, prepared.query, executeOptions, true);
       const result = await readThroughCache(this.queryCache, cacheKey, cacheTTL, () => this.runToArray(prepared));
       return this.wrapResult("find", startTs, result);
     }
@@ -12101,6 +12140,432 @@ function mapVectorSearchRows(rows) {
   });
 }
 
+// src/adapters/mongodb/search-indexes/errors.ts
+var CODE_INDEX_ALREADY_EXISTS = 68;
+var CODE_INDEX_NOT_FOUND = 27;
+var CODE_NAMESPACE_NOT_FOUND = 26;
+var CODE_COMMAND_NOT_FOUND = 59;
+var CODE_COMMAND_NOT_SUPPORTED = 115;
+var CODE_LIST_SEARCH_ATLAS_ONLY = 6047401;
+var UNSUPPORTED_MESSAGE = /search index commands are only supported|\$listSearchIndexes stage is only allowed/i;
+function readCode(error) {
+  const e = error;
+  return {
+    code: typeof e?.code === "number" ? e.code : void 0,
+    codeName: typeof e?.codeName === "string" ? e.codeName : void 0,
+    message: typeof e?.message === "string" ? e.message : String(error)
+  };
+}
+function classifySearchIndexError(error) {
+  const { code, codeName, message } = readCode(error);
+  if (code === CODE_INDEX_ALREADY_EXISTS || codeName === "IndexAlreadyExists") return "exists";
+  if (code === CODE_NAMESPACE_NOT_FOUND || codeName === "NamespaceNotFound") return "namespaceNotFound";
+  if (code === CODE_INDEX_NOT_FOUND || codeName === "IndexNotFound") return "notFound";
+  if (code === CODE_COMMAND_NOT_FOUND || code === CODE_COMMAND_NOT_SUPPORTED || code === CODE_LIST_SEARCH_ATLAS_ONLY || codeName === "CommandNotFound" || codeName === "CommandNotSupported" || codeName === "SearchNotEnabled") return "unsupported";
+  if (code === void 0 && codeName === void 0 && /already exists/i.test(message)) return "exists";
+  if (UNSUPPORTED_MESSAGE.test(message)) return "unsupported";
+  return "other";
+}
+function attachContext(error, ctx) {
+  const contextualized = error;
+  try {
+    contextualized.monsqlize = {
+      ...contextualized.monsqlize && typeof contextualized.monsqlize === "object" ? contextualized.monsqlize : {},
+      operation: ctx.operation,
+      namespace: ctx.namespace,
+      indexName: ctx.indexName
+    };
+  } catch {
+  }
+  return error;
+}
+function searchIndexError(code, message, ctx, extra = {}, cause) {
+  return createError(code, message, [{ operation: ctx.operation, namespace: ctx.namespace, indexName: ctx.indexName, ...extra }], cause);
+}
+function mapSearchIndexError(error, ctx) {
+  if (!(error instanceof Error)) {
+    return createError(ErrorCodes.MONGODB_ERROR, `${ctx.operation} failed`, [{ ...ctx, reason: String(error) }]);
+  }
+  if (error.code !== void 0 && typeof error.code === "string" && String(error.code).startsWith("SEARCH_INDEX_")) {
+    return error;
+  }
+  const { code, codeName, message } = readCode(error);
+  const server = { serverCode: code, serverCodeName: codeName, serverMessage: message };
+  switch (classifySearchIndexError(error)) {
+    case "exists":
+      return searchIndexError(ErrorCodes.SEARCH_INDEX_EXISTS, `Search index "${ctx.indexName}" already exists`, ctx, server, error);
+    case "notFound":
+      return searchIndexError(ErrorCodes.SEARCH_INDEX_NOT_FOUND, `Search index "${ctx.indexName}" was not found`, ctx, server, error);
+    case "unsupported":
+      return searchIndexError(ErrorCodes.SEARCH_INDEX_UNSUPPORTED, "This deployment does not support Search index commands (requires Atlas, MongoDB 8.2+ with mongot, or mongodb-atlas-local)", ctx, server, error);
+    default:
+      return attachContext(searchIndexError(ErrorCodes.MONGODB_ERROR, `${ctx.operation} failed: ${message}`, ctx, server, error), ctx);
+  }
+}
+
+// src/adapters/mongodb/search-indexes/normalize.ts
+function missingSearchIndexInfo(name) {
+  return { name, status: "DOES_NOT_EXIST", queryable: false, typeSource: "unknown", raw: {} };
+}
+function normalizeSearchIndexInfo(doc) {
+  const info = {
+    name: String(doc.name),
+    // Unknown future statuses are passed through verbatim rather than rewritten.
+    status: typeof doc.status === "string" && doc.status.length > 0 ? doc.status : "PENDING",
+    queryable: doc.queryable === true,
+    typeSource: "unknown",
+    raw: doc
+  };
+  if (typeof doc.id === "string") info.id = doc.id;
+  const resolved = resolveSearchIndexType(doc);
+  info.typeSource = resolved.typeSource;
+  if (resolved.type !== void 0) info.type = resolved.type;
+  if (doc.latestDefinition && typeof doc.latestDefinition === "object") info.latestDefinition = doc.latestDefinition;
+  const version = doc.latestDefinitionVersion;
+  if (version && typeof version === "object") {
+    info.latestDefinitionVersion = { version: Number(version.version), createdAt: version.createdAt };
+  }
+  if (Array.isArray(doc.statusDetail)) info.statusDetail = doc.statusDetail;
+  return info;
+}
+function resolveSearchIndexType(doc) {
+  if (doc.type === "search" || doc.type === "vectorSearch") return { type: doc.type, typeSource: "server" };
+  const definition = doc.latestDefinition;
+  if (definition && typeof definition === "object" && !Array.isArray(definition)) {
+    const fields = definition.fields;
+    if (Array.isArray(fields) && fields.some((field) => field && typeof field === "object" && field.type === "vector")) {
+      return { type: "vectorSearch", typeSource: "inferred" };
+    }
+    if (Object.prototype.hasOwnProperty.call(definition, "mappings")) return { type: "search", typeSource: "inferred" };
+  }
+  return { typeSource: "unknown" };
+}
+function matchesSearchIndexType(info, type) {
+  return info.typeSource !== "unknown" && info.type === type;
+}
+
+// src/adapters/mongodb/search-indexes/validate.ts
+var TYPES = /* @__PURE__ */ new Set(["search", "vectorSearch"]);
+var VECTOR_FIELD_TYPES = /* @__PURE__ */ new Set(["vector", "filter"]);
+var SIMILARITIES = /* @__PURE__ */ new Set(["euclidean", "cosine", "dotProduct"]);
+function invalid(operation, namespace, indexName, field, reason) {
+  throw createError(
+    ErrorCodes.INVALID_SEARCH_INDEX_DEFINITION,
+    `${operation}: invalid ${field} (${reason})`,
+    [{ operation, namespace, indexName: typeof indexName === "string" ? indexName : void 0, field, reason }]
+  );
+}
+function isPlainObject4(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+function assertIndexName(operation, namespace, name) {
+  if (typeof name !== "string" || name.length === 0 || name.trim() !== name) {
+    invalid(operation, namespace, name, "name", "non-empty string without leading or trailing whitespace required");
+  }
+}
+function assertDefinition(operation, namespace, name, definition, type) {
+  if (!isPlainObject4(definition)) invalid(operation, namespace, name, "definition", "plain object required");
+  if (type !== "vectorSearch") return;
+  const fields = definition.fields;
+  if (!Array.isArray(fields) || fields.length === 0) {
+    invalid(operation, namespace, name, "definition.fields", "non-empty array required for vectorSearch");
+  }
+  fields.forEach((field, index) => {
+    const path5 = `definition.fields[${index}]`;
+    if (!isPlainObject4(field)) invalid(operation, namespace, name, path5, "object required");
+    if (typeof field.type !== "string" || !VECTOR_FIELD_TYPES.has(field.type)) {
+      invalid(operation, namespace, name, `${path5}.type`, 'must be "vector" or "filter"');
+    }
+    if (typeof field.path !== "string" || field.path.length === 0) {
+      invalid(operation, namespace, name, `${path5}.path`, "non-empty string required");
+    }
+    if (field.type === "vector") {
+      const dims = field.numDimensions;
+      if (typeof dims !== "number" || !Number.isInteger(dims) || dims <= 0) {
+        invalid(operation, namespace, name, `${path5}.numDimensions`, "positive integer required");
+      }
+      if (typeof field.similarity !== "string" || !SIMILARITIES.has(field.similarity)) {
+        invalid(operation, namespace, name, `${path5}.similarity`, 'must be "euclidean", "cosine", or "dotProduct"');
+      }
+    }
+  });
+}
+function assertSpec(operation, namespace, spec) {
+  if (!isPlainObject4(spec)) invalid(operation, namespace, void 0, "spec", "object required");
+  assertIndexName(operation, namespace, spec.name);
+  if (typeof spec.type !== "string" || !TYPES.has(spec.type)) {
+    invalid(operation, namespace, spec.name, "type", 'must be "search" or "vectorSearch"');
+  }
+  assertDefinition(operation, namespace, spec.name, spec.definition, spec.type);
+}
+function assertOptionsObject(operation, namespace, name, options) {
+  if (options !== void 0 && !isPlainObject4(options)) invalid(operation, namespace, name, "options", "object required");
+}
+function assertEnumOption(operation, namespace, name, field, value, allowed) {
+  if (value !== void 0 && (typeof value !== "string" || !allowed.includes(value))) {
+    invalid(operation, namespace, name, field, `must be one of ${allowed.map((v) => `"${v}"`).join(", ")}`);
+  }
+}
+function assertBooleanOption(operation, namespace, name, field, value) {
+  if (value !== void 0 && typeof value !== "boolean") invalid(operation, namespace, name, field, "boolean required");
+}
+function resolveWaitOptions(namespace, name, options) {
+  const operation = "waitForSearchIndex";
+  assertOptionsObject(operation, namespace, name, options);
+  const opts = options ?? {};
+  assertEnumOption(operation, namespace, name, "options.until", opts.until, ["queryable", "ready", "dropped"]);
+  const timeoutMs = opts.timeoutMs ?? 3e5;
+  const intervalMs = opts.intervalMs ?? 2e3;
+  if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
+    invalid(operation, namespace, name, "options.timeoutMs", "positive integer required");
+  }
+  if (!Number.isInteger(intervalMs) || intervalMs < 100) {
+    invalid(operation, namespace, name, "options.intervalMs", "integer >= 100 required");
+  }
+  const signal = opts.signal;
+  if (signal !== void 0 && (signal === null || typeof signal !== "object" || typeof signal.aborted !== "boolean" || typeof signal.addEventListener !== "function")) {
+    invalid(operation, namespace, name, "options.signal", "AbortSignal required");
+  }
+  return { until: opts.until ?? "queryable", timeoutMs, intervalMs, signal };
+}
+
+// src/adapters/mongodb/search-indexes/operations.ts
+var SEARCH_INDEX_MISSING_GRACE_MS = 3e4;
+async function fetchByName(ctx, operation, name, signal) {
+  try {
+    const docs = await ctx.collection.listSearchIndexes(name, signal ? { signal } : {}).toArray();
+    const match = docs.find((doc) => doc.name === name);
+    return match ? normalizeSearchIndexInfo(match) : missingSearchIndexInfo(name);
+  } catch (error) {
+    if (signal?.aborted) throw signal.reason;
+    if (classifySearchIndexError(error) === "namespaceNotFound") return missingSearchIndexInfo(name);
+    throw mapSearchIndexError(error, { operation, namespace: ctx.namespace, indexName: name });
+  }
+}
+async function getSearchIndexOp(ctx, name) {
+  assertIndexName("getSearchIndex", ctx.namespace, name);
+  return fetchByName(ctx, "getSearchIndex", name);
+}
+async function listSearchIndexesOp(ctx, options) {
+  const operation = "listSearchIndexes";
+  assertOptionsObject(operation, ctx.namespace, void 0, options);
+  assertEnumOption(operation, ctx.namespace, void 0, "options.type", options?.type, ["search", "vectorSearch"]);
+  let docs;
+  try {
+    docs = await ctx.collection.listSearchIndexes().toArray();
+  } catch (error) {
+    if (classifySearchIndexError(error) === "namespaceNotFound") return [];
+    throw mapSearchIndexError(error, { operation, namespace: ctx.namespace });
+  }
+  const infos = docs.map(normalizeSearchIndexInfo);
+  return options?.type ? infos.filter((info) => matchesSearchIndexType(info, options.type)) : infos;
+}
+async function createSearchIndexOp(ctx, spec, options) {
+  const operation = "createSearchIndex";
+  assertSpec(operation, ctx.namespace, spec);
+  assertOptionsObject(operation, ctx.namespace, spec.name, options);
+  assertEnumOption(operation, ctx.namespace, spec.name, "options.ifExists", options?.ifExists, ["error", "skip", "update"]);
+  const ifExists = options?.ifExists ?? "error";
+  const errCtx = { operation, namespace: ctx.namespace, indexName: spec.name };
+  const existing = await fetchByName(ctx, operation, spec.name);
+  if (existing.status !== "DOES_NOT_EXIST") {
+    if (ifExists === "skip") return { name: spec.name, action: "skipped", created: false };
+    if (ifExists === "error") {
+      throw searchIndexError(ErrorCodes.SEARCH_INDEX_EXISTS, `Search index "${spec.name}" already exists`, errCtx);
+    }
+    if (existing.type !== void 0 && existing.type !== spec.type) {
+      throw searchIndexError(
+        ErrorCodes.INVALID_SEARCH_INDEX_DEFINITION,
+        `Search index "${spec.name}" has type "${existing.type}"; drop it before recreating as "${spec.type}"`,
+        errCtx,
+        { field: "type", reason: "type change requires drop and create" }
+      );
+    }
+    try {
+      await ctx.collection.updateSearchIndex(spec.name, spec.definition);
+    } catch (error) {
+      throw mapSearchIndexError(error, errCtx);
+    }
+    return { name: spec.name, action: "updated", created: false };
+  }
+  try {
+    const name = await ctx.collection.createSearchIndex({ name: spec.name, type: spec.type, definition: spec.definition });
+    return { name: typeof name === "string" && name.length > 0 ? name : spec.name, action: "created", created: true };
+  } catch (error) {
+    const mapped = mapSearchIndexError(error, errCtx);
+    if (mapped.code === ErrorCodes.SEARCH_INDEX_EXISTS && ifExists === "skip") {
+      return { name: spec.name, action: "skipped", created: false };
+    }
+    throw mapped;
+  }
+}
+async function createSearchIndexesOp(ctx, specs) {
+  const operation = "createSearchIndexes";
+  if (!Array.isArray(specs) || specs.length === 0) {
+    throw searchIndexError(
+      ErrorCodes.INVALID_SEARCH_INDEX_DEFINITION,
+      `${operation}: specs must be a non-empty array`,
+      { operation, namespace: ctx.namespace },
+      { field: "specs", reason: "non-empty array required" }
+    );
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const spec of specs) {
+    assertSpec(operation, ctx.namespace, spec);
+    if (seen.has(spec.name)) {
+      throw searchIndexError(
+        ErrorCodes.SEARCH_INDEX_EXISTS,
+        `Search index "${spec.name}" is listed more than once`,
+        { operation, namespace: ctx.namespace, indexName: spec.name }
+      );
+    }
+    seen.add(spec.name);
+  }
+  try {
+    return await ctx.collection.createSearchIndexes(specs.map(({ name, type, definition }) => ({ name, type, definition })));
+  } catch (error) {
+    throw mapSearchIndexError(error, { operation, namespace: ctx.namespace });
+  }
+}
+async function updateSearchIndexOp(ctx, name, definition) {
+  const operation = "updateSearchIndex";
+  assertIndexName(operation, ctx.namespace, name);
+  assertDefinition(operation, ctx.namespace, name, definition);
+  const errCtx = { operation, namespace: ctx.namespace, indexName: name };
+  const existing = await fetchByName(ctx, operation, name);
+  if (existing.status === "DOES_NOT_EXIST") {
+    throw searchIndexError(ErrorCodes.SEARCH_INDEX_NOT_FOUND, `Search index "${name}" was not found`, errCtx);
+  }
+  if (existing.type !== void 0) assertDefinition(operation, ctx.namespace, name, definition, existing.type);
+  try {
+    await ctx.collection.updateSearchIndex(name, definition);
+  } catch (error) {
+    throw mapSearchIndexError(error, errCtx);
+  }
+}
+async function dropSearchIndexOp(ctx, name, options) {
+  const operation = "dropSearchIndex";
+  assertIndexName(operation, ctx.namespace, name);
+  assertOptionsObject(operation, ctx.namespace, name, options);
+  assertBooleanOption(operation, ctx.namespace, name, "options.ignoreMissing", options?.ignoreMissing);
+  const errCtx = { operation, namespace: ctx.namespace, indexName: name };
+  const existing = await fetchByName(ctx, operation, name);
+  if (existing.status === "DOES_NOT_EXIST") {
+    if (options?.ignoreMissing) return;
+    throw searchIndexError(ErrorCodes.SEARCH_INDEX_NOT_FOUND, `Search index "${name}" was not found`, errCtx);
+  }
+  try {
+    await ctx.collection.dropSearchIndex(name);
+  } catch (error) {
+    const mapped = mapSearchIndexError(error, errCtx);
+    if (mapped.code === ErrorCodes.SEARCH_INDEX_NOT_FOUND && options?.ignoreMissing) return;
+    throw mapped;
+  }
+}
+function sleep2(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason);
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal?.reason);
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function linkSignal(userSignal, remainingMs) {
+  const controller = new AbortController();
+  let expired = false;
+  const onUserAbort = () => controller.abort(userSignal?.reason);
+  userSignal?.addEventListener("abort", onUserAbort, { once: true });
+  const timer = setTimeout(() => {
+    expired = true;
+    controller.abort(new Error("search index wait deadline reached"));
+  }, Math.max(0, remainingMs));
+  return {
+    signal: controller.signal,
+    timedOut: () => expired,
+    dispose: () => {
+      clearTimeout(timer);
+      userSignal?.removeEventListener("abort", onUserAbort);
+    }
+  };
+}
+async function waitForSearchIndexOp(ctx, name, options, clock = Date.now) {
+  const operation = "waitForSearchIndex";
+  assertIndexName(operation, ctx.namespace, name);
+  const { until, timeoutMs, intervalMs, signal } = resolveWaitOptions(ctx.namespace, name, options);
+  const errCtx = { operation, namespace: ctx.namespace, indexName: name };
+  if (signal?.aborted) throw signal.reason;
+  const start = clock();
+  const grace = Math.min(SEARCH_INDEX_MISSING_GRACE_MS, timeoutMs);
+  let last;
+  const timeoutError = () => searchIndexError(
+    ErrorCodes.SEARCH_INDEX_WAIT_TIMEOUT,
+    `Timed out after ${timeoutMs}ms waiting for Search index "${name}" to become ${until}`,
+    errCtx,
+    { until, timeoutMs, last }
+  );
+  for (; ; ) {
+    const link = linkSignal(signal, timeoutMs - (clock() - start));
+    let info;
+    try {
+      info = await fetchByName(ctx, operation, name, link.signal);
+    } catch (error) {
+      if (signal?.aborted) throw signal.reason;
+      if (link.timedOut()) throw timeoutError();
+      throw error;
+    } finally {
+      link.dispose();
+    }
+    last = info;
+    if (signal?.aborted) throw signal.reason;
+    if (until === "dropped") {
+      if (info.status === "DOES_NOT_EXIST") return info;
+    } else if (info.status === "DOES_NOT_EXIST") {
+      if (clock() - start >= grace) {
+        throw searchIndexError(
+          ErrorCodes.SEARCH_INDEX_NOT_FOUND,
+          `Search index "${name}" was not found within ${grace}ms`,
+          errCtx,
+          { until, graceMs: grace }
+        );
+      }
+    } else if (until === "queryable") {
+      if (info.queryable) return info;
+      if (info.status === "FAILED") {
+        throw searchIndexError(
+          ErrorCodes.SEARCH_INDEX_BUILD_FAILED,
+          `Search index "${name}" build failed`,
+          errCtx,
+          { status: info.status, statusDetail: info.statusDetail }
+        );
+      }
+    } else {
+      if (info.status === "READY") return info;
+      if (info.status === "FAILED") {
+        throw searchIndexError(
+          ErrorCodes.SEARCH_INDEX_BUILD_FAILED,
+          `Search index "${name}" build failed`,
+          errCtx,
+          { status: info.status, statusDetail: info.statusDetail }
+        );
+      }
+    }
+    const remaining = timeoutMs - (clock() - start);
+    if (remaining <= 0) throw timeoutError();
+    await sleep2(Math.min(intervalMs, remaining), signal);
+  }
+}
+
 // src/adapters/mongodb/common/collection-accessor-cache-helpers.ts
 import { types as utilTypes4 } from "node:util";
 function isRecord2(value) {
@@ -12461,7 +12926,7 @@ async function invalidateReadCachesAfterWrite(queryCache, collection, dbName, co
 }
 
 // src/adapters/mongodb/writes/write-utils.ts
-function sleep2(ms) {
+function sleep3(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 function splitIntoBatches(items, batchSize) {
@@ -12881,7 +13346,7 @@ async function insertBatchDocuments(collection, documents, options = {}) {
           result.retries.push(retryInfo);
           onRetry?.(retryInfo);
           if (retryDelay > 0) {
-            await sleep2(retryDelay);
+            await sleep3(retryDelay);
           }
           continue;
         }
@@ -13010,7 +13475,7 @@ async function updateBatchDocuments(collection, filter, update, options = {}) {
           result.retries.push(retryInfo);
           onRetry?.(retryInfo);
           if (retryDelay > 0) {
-            await sleep2(retryDelay);
+            await sleep3(retryDelay);
           }
           continue;
         }
@@ -13105,7 +13570,7 @@ async function deleteBatchDocuments(collection, filter, options = {}) {
           result.retries.push(retryInfo);
           onRetry?.(retryInfo);
           if (retryDelay > 0) {
-            await sleep2(retryDelay);
+            await sleep3(retryDelay);
           }
           continue;
         }
@@ -13602,7 +14067,7 @@ var MongoCollectionAccessor = class {
     const { query: normalizedQuery, options: driverOptions } = snapshotReadInputs(this._cvFilter(query), normalizeFindProjectionOptions(rawOptions), this.collectionRef.bsonOptions);
     const cacheTTL = rawOptions.explain ? 0 : typeof rawOptions.cache === "number" ? rawOptions.cache : 0;
     if (cacheTTL > 0 && this.management.queryCache && canCacheBsonResult(driverOptions) && !hasSessionOption(driverOptions) && !await isCollectionCacheBarrierActive(this.management.queryCache, this.collectionRef, this.management.defaults)) {
-      const cacheKey = buildFindOneCacheKey(this.collectionRef, this.management.defaults, normalizedQuery, driverOptions);
+      const cacheKey = buildFindOneCacheKey(this.collectionRef, this.management.defaults, normalizedQuery, driverOptions, true);
       const result2 = await readThroughCache(this.management.queryCache, cacheKey, cacheTTL, () => findOneDocument(this.collectionRef, normalizedQuery, driverOptions));
       return wrapQueryResultWithMeta(this.collectionRef, this.management.defaults, "findOne", rawOptions, startTs, result2);
     }
@@ -13659,7 +14124,7 @@ var MongoCollectionAccessor = class {
     );
     const countQueue = this.management.defaults?.countQueue;
     if (cacheTTL > 0 && this.management.queryCache && canCacheBsonCount(keyOptions) && !hasSessionOption(keyOptions) && !await isCollectionCacheBarrierActive(this.management.queryCache, this.collectionRef, this.management.defaults)) {
-      const cacheKey = buildCountCacheKey(this.collectionRef, this.management.defaults, normalizedQuery, keyOptions);
+      const cacheKey = buildCountCacheKey(this.collectionRef, this.management.defaults, normalizedQuery, keyOptions, true);
       const result = await readThroughCache(
         this.management.queryCache,
         cacheKey,
@@ -13752,7 +14217,7 @@ var MongoCollectionAccessor = class {
       driverOptions
     );
     if (cacheTTL > 0 && this.management.queryCache && canCacheBsonResult(driverOptions) && !hasSessionOption(driverOptions) && !await isCollectionCacheBarrierActive(this.management.queryCache, this.collectionRef, this.management.defaults)) {
-      const cacheKey = buildDistinctCacheKey(this.collectionRef, this.management.defaults, key, normalizedQuery, driverOptions);
+      const cacheKey = buildDistinctCacheKey(this.collectionRef, this.management.defaults, key, normalizedQuery, driverOptions, true);
       const result2 = await readThroughCache(this.management.queryCache, cacheKey, cacheTTL, executeDistinct);
       return wrapQueryResultWithMeta(this.collectionRef, this.management.defaults, "distinct", rawOptions, startTs, result2);
     }
@@ -13873,6 +14338,35 @@ var MongoCollectionAccessor = class {
     this.assertWritePath("dropIndexes", "management");
     return dropIndexesForAccessor(this.collectionRef);
   }
+  /** Search index lifecycle (v3.4.0); writes are governed by writePathPolicy `management`. */
+  searchIndexContext() {
+    return { collection: this.collectionRef, namespace: this.getNamespace() };
+  }
+  async createSearchIndex(spec, options) {
+    this.assertWritePath("createSearchIndex", "management");
+    return createSearchIndexOp(this.searchIndexContext(), spec, options);
+  }
+  async createSearchIndexes(specs) {
+    this.assertWritePath("createSearchIndexes", "management");
+    return createSearchIndexesOp(this.searchIndexContext(), specs);
+  }
+  async listSearchIndexes(options) {
+    return listSearchIndexesOp(this.searchIndexContext(), options);
+  }
+  async getSearchIndex(name) {
+    return getSearchIndexOp(this.searchIndexContext(), name);
+  }
+  async updateSearchIndex(name, definition) {
+    this.assertWritePath("updateSearchIndex", "management");
+    return updateSearchIndexOp(this.searchIndexContext(), name, definition);
+  }
+  async dropSearchIndex(name, options) {
+    this.assertWritePath("dropSearchIndex", "management");
+    return dropSearchIndexOp(this.searchIndexContext(), name, options);
+  }
+  async waitForSearchIndex(name, options) {
+    return waitForSearchIndexOp(this.searchIndexContext(), name, options);
+  }
   /** Pre-populates bookmark cache entries for the specified key dimensions and page numbers. */
   async prewarmBookmarks(keyDims = {}, pages = []) {
     return prewarmBookmarksForAccessor(this.bookmarkContext(), keyDims, pages);
@@ -14757,7 +15251,7 @@ var LockManager = class {
         break;
       }
       const delay3 = retryDelay * Math.pow(retryBackoff, attempt);
-      await sleep3(delay3);
+      await sleep4(delay3);
     }
     this.stats.errors += 1;
     if (options.fallbackToNoLock) {
@@ -14869,7 +15363,7 @@ var LockManager = class {
     }
   }
 };
-async function sleep3(ms) {
+async function sleep4(ms) {
   await new Promise((resolve) => setTimeout(resolve, ms));
 }
 var DistributedCacheLockManager = class {
@@ -14994,10 +15488,10 @@ var DistributedCacheLockManager = class {
           return new Lock(key, lockId, this, ttl, startedAt);
         }
         if (attempt === retryTimes) break;
-        await sleep3(retryDelay);
+        await sleep4(retryDelay);
       } catch (error) {
         if (attempt === retryTimes) throw error;
-        await sleep3(retryDelay);
+        await sleep4(retryDelay);
       }
     }
     this.stats.errors++;
@@ -18026,7 +18520,7 @@ var DEFAULT_DATA_TASK_MAX_DOCUMENTS = 1e4;
 var DEFAULT_DATA_TASK_BACKUP_MAX_BYTES = 256 * 1024 * 1024;
 var ENVIRONMENTS = /* @__PURE__ */ new Set(["development", "test", "staging", "production", "prod", "live"]);
 var PRODUCTION_ENVIRONMENTS = /* @__PURE__ */ new Set(["production", "prod", "live"]);
-function invalid(message, collection) {
+function invalid2(message, collection) {
   throw new DataTaskJobError("INVALID_JOB", message, "validate", collection);
 }
 function canonicalize(value) {
@@ -18064,15 +18558,15 @@ function connectionDescriptor(value) {
 }
 function validateConnection(value, field) {
   if (isDataTaskJobRuntime(value)) return;
-  if (!isRecord3(value) || value.type !== "mongodb") invalid(`${field} must be a monSQLize runtime or MongoDB MonSQLizeOptions.`);
-  if (typeof value.databaseName !== "string" || value.databaseName.trim() === "") invalid(`${field}.databaseName is required.`);
-  if (!isRecord3(value.config) || typeof value.config.uri !== "string" || value.config.uri.trim() === "") invalid(`${field}.config.uri is required.`);
+  if (!isRecord3(value) || value.type !== "mongodb") invalid2(`${field} must be a monSQLize runtime or MongoDB MonSQLizeOptions.`);
+  if (typeof value.databaseName !== "string" || value.databaseName.trim() === "") invalid2(`${field}.databaseName is required.`);
+  if (!isRecord3(value.config) || typeof value.config.uri !== "string" || value.config.uri.trim() === "") invalid2(`${field}.config.uri is required.`);
 }
 function uniqueFields(value, pathName, collection) {
-  if (!Array.isArray(value) || value.length === 0) invalid(`${pathName} must be a non-empty string array.`, collection);
+  if (!Array.isArray(value) || value.length === 0) invalid2(`${pathName} must be a non-empty string array.`, collection);
   const fields = value.map((item) => typeof item === "string" ? item.trim() : "");
-  if (fields.some((item) => item === "")) invalid(`${pathName} must contain non-empty strings.`, collection);
-  if (new Set(fields).size !== fields.length) invalid(`${pathName} must not contain duplicates.`, collection);
+  if (fields.some((item) => item === "")) invalid2(`${pathName} must contain non-empty strings.`, collection);
+  if (new Set(fields).size !== fields.length) invalid2(`${pathName} must not contain duplicates.`, collection);
   return fields;
 }
 var FORBIDDEN_FIELD_PATH_SEGMENTS = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
@@ -18083,31 +18577,31 @@ function assertBsonLiteral(value, pathName, collection, stack = /* @__PURE__ */
   const valueType = typeof value;
   if (value === null || BSON_PRIMITIVE_TYPES.has(valueType)) return;
   if (BSON_UNSUPPORTED_TYPES.has(valueType)) {
-    invalid(`${pathName} must contain only BSON-compatible literals.`, collection);
+    invalid2(`${pathName} must contain only BSON-compatible literals.`, collection);
   }
   if (value instanceof Date || value instanceof RegExp || Buffer.isBuffer(value)) return;
   if (Array.isArray(value)) {
-    if (stack.has(value)) invalid(`${pathName} must not contain circular values.`, collection);
+    if (stack.has(value)) invalid2(`${pathName} must not contain circular values.`, collection);
     stack.add(value);
     value.forEach((item, position) => assertBsonLiteral(item, `${pathName}[${position}]`, collection, stack));
     stack.delete(value);
     return;
   }
-  if (!isRecord3(value)) invalid(`${pathName} must contain only BSON-compatible literals.`, collection);
+  if (!isRecord3(value)) invalid2(`${pathName} must contain only BSON-compatible literals.`, collection);
   if (typeof value._bsontype === "string") return;
   const prototype = Object.getPrototypeOf(value);
-  if (!PLAIN_OBJECT_PROTOTYPES.has(prototype)) invalid(`${pathName} must contain only BSON-compatible literals.`, collection);
-  if (stack.has(value)) invalid(`${pathName} must not contain circular values.`, collection);
+  if (!PLAIN_OBJECT_PROTOTYPES.has(prototype)) invalid2(`${pathName} must contain only BSON-compatible literals.`, collection);
+  if (stack.has(value)) invalid2(`${pathName} must not contain circular values.`, collection);
   stack.add(value);
   for (const [key, item] of Object.entries(value)) assertBsonLiteral(item, `${pathName}.${key}`, collection, stack);
   stack.delete(value);
 }
 function normalizeFieldPath(value, pathName, collection) {
-  if (typeof value !== "string" || value.trim() === "") invalid(`${pathName} must be a non-empty field path.`, collection);
+  if (typeof value !== "string" || value.trim() === "") invalid2(`${pathName} must be a non-empty field path.`, collection);
   const field = value.trim();
   const segments = field.split(".");
   if (segments.some((segment) => segment === "" || segment.startsWith("$") || FORBIDDEN_FIELD_PATH_SEGMENTS.has(segment))) {
-    invalid(`${pathName} contains an unsafe field path.`, collection);
+    invalid2(`${pathName} contains an unsafe field path.`, collection);
   }
   return field;
 }
@@ -18123,13 +18617,13 @@ function projectionIncludes(projection, field) {
   return included.some((key) => key === field || field.startsWith(`${key}.`));
 }
 function normalizeFieldPatch(data, identityFields, collection) {
-  if (data.rename !== void 0 && !isRecord3(data.rename)) invalid("data.rename must be an object.", collection);
-  if (data.set !== void 0 && !isRecord3(data.set)) invalid("data.set must be an object.", collection);
-  if (data.unset !== void 0 && !Array.isArray(data.unset)) invalid("data.unset must be an array.", collection);
+  if (data.rename !== void 0 && !isRecord3(data.rename)) invalid2("data.rename must be an object.", collection);
+  if (data.set !== void 0 && !isRecord3(data.set)) invalid2("data.set must be an object.", collection);
+  if (data.unset !== void 0 && !Array.isArray(data.unset)) invalid2("data.unset must be an array.", collection);
   const renameEntries = Object.entries(data.rename ?? {}).map(([source, destination], position) => {
     const normalizedSource = normalizeFieldPath(source, `data.rename source ${position}`, collection);
     const normalizedDestination = normalizeFieldPath(destination, `data.rename.${source}`, collection);
-    if (pathsOverlap(normalizedSource, normalizedDestination)) invalid("data.rename source and destination must not overlap.", collection);
+    if (pathsOverlap(normalizedSource, normalizedDestination)) invalid2("data.rename source and destination must not overlap.", collection);
     return [normalizedSource, normalizedDestination];
   });
   const setEntries = Object.entries(data.set ?? {}).map(([field, value], position) => {
@@ -18138,14 +18632,14 @@ function normalizeFieldPatch(data, identityFields, collection) {
     try {
       canonicalStringify(value);
     } catch {
-      invalid(`data.set.${field} must be a BSON-compatible literal.`, collection);
+      invalid2(`data.set.${field} must be a BSON-compatible literal.`, collection);
     }
     return [normalizedField, value];
   });
   const unset = (data.unset ?? []).map((field, position) => normalizeFieldPath(field, `data.unset[${position}]`, collection));
-  if (new Set(unset).size !== unset.length) invalid("data.unset must not contain duplicates.", collection);
+  if (new Set(unset).size !== unset.length) invalid2("data.unset must not contain duplicates.", collection);
   const destinations = renameEntries.map(([, destination]) => destination);
-  if (new Set(destinations).size !== destinations.length) invalid("data.rename destinations must be unique.", collection);
+  if (new Set(destinations).size !== destinations.length) invalid2("data.rename destinations must be unique.", collection);
   const configuredPaths = [
     ...renameEntries.flatMap(([source, destination]) => [
       { path: source, label: `rename source "${source}"` },
@@ -18157,18 +18651,18 @@ function normalizeFieldPatch(data, identityFields, collection) {
   for (let left = 0; left < configuredPaths.length; left += 1) {
     for (let right = left + 1; right < configuredPaths.length; right += 1) {
       if (pathsOverlap(configuredPaths[left].path, configuredPaths[right].path)) {
-        invalid(`${configuredPaths[left].label} conflicts with ${configuredPaths[right].label}.`, collection);
+        invalid2(`${configuredPaths[left].label} conflicts with ${configuredPaths[right].label}.`, collection);
       }
     }
   }
   for (const configured of configuredPaths) {
     if (configured.path === "_id" || configured.path.startsWith("_id.") || identityFields.some((identity) => pathsOverlap(configured.path, identity))) {
-      invalid(`${configured.label} must not overlap _id or an identity field.`, collection);
+      invalid2(`${configured.label} must not overlap _id or an identity field.`, collection);
     }
   }
   if (data.projection) {
     for (const required of [...identityFields, ...renameEntries.map(([source]) => source)]) {
-      if (!projectionIncludes(data.projection, required)) invalid(`data.projection must include required field "${required}".`, collection);
+      if (!projectionIncludes(data.projection, required)) invalid2(`data.projection must include required field "${required}".`, collection);
     }
   }
   return {
@@ -18179,105 +18673,105 @@ function normalizeFieldPatch(data, identityFields, collection) {
 }
 function normalizeData(data, collection) {
   if (data === void 0) return void 0;
-  if (!isRecord3(data)) invalid("data must be an object.", collection);
+  if (!isRecord3(data)) invalid2("data must be an object.", collection);
   const hasFilter = isRecord3(data.filter) && Object.keys(data.filter).length > 0;
-  if (hasFilter === (data.all === true)) invalid("data requires exactly one of a non-empty filter or all: true.", collection);
+  if (hasFilter === (data.all === true)) invalid2("data requires exactly one of a non-empty filter or all: true.", collection);
   if (!isRecord3(data.identity) || data.identity.mode !== "fields" && data.identity.mode !== "source-id") {
-    invalid("data.identity.mode must be fields or source-id.", collection);
+    invalid2("data.identity.mode must be fields or source-id.", collection);
   }
   const identity = data.identity.mode === "fields" ? { mode: "fields", fields: uniqueFields(data.identity.fields, "identity.fields", collection) } : {
     mode: "source-id",
     ...data.identity.conflictBy === void 0 ? {} : { conflictBy: uniqueFields(data.identity.conflictBy, "identity.conflictBy", collection) }
   };
-  if (data.projection !== void 0 && !isRecord3(data.projection)) invalid("data.projection must be an object.", collection);
+  if (data.projection !== void 0 && !isRecord3(data.projection)) invalid2("data.projection must be an object.", collection);
   if (data.projection) assertBsonLiteral(data.projection, "data.projection", collection);
   if (hasFilter) assertBsonLiteral(data.filter, "data.filter", collection);
   const identityFields = identity.mode === "fields" ? identity.fields : ["_id", ...identity.conflictBy ?? []];
   const patch = normalizeFieldPatch(data, identityFields, collection);
   const batchSize = data.batchSize ?? 500;
-  if (!Number.isInteger(batchSize) || batchSize < 1 || batchSize > 1e4) invalid("data.batchSize must be an integer from 1 to 10000.", collection);
+  if (!Number.isInteger(batchSize) || batchSize < 1 || batchSize > 1e4) invalid2("data.batchSize must be an integer from 1 to 10000.", collection);
   const maxDocuments = data.maxDocuments ?? DEFAULT_DATA_TASK_MAX_DOCUMENTS;
   if (!Number.isInteger(maxDocuments) || maxDocuments < 1 || maxDocuments > 1e6) {
-    invalid("data.maxDocuments must be an integer from 1 to 1000000.", collection);
+    invalid2("data.maxDocuments must be an integer from 1 to 1000000.", collection);
   }
   const strategy = data.strategy ?? "upsert";
-  if (strategy !== "upsert" && strategy !== "insert") invalid("data.strategy must be upsert or insert.", collection);
+  if (strategy !== "upsert" && strategy !== "insert") invalid2("data.strategy must be upsert or insert.", collection);
   return { ...data, ...patch, filter: hasFilter ? data.filter : {}, all: data.all === true, identity, strategy, batchSize, maxDocuments };
 }
 function normalizeIndexes(indexes, collection) {
   if (indexes === void 0) return [];
-  if (!Array.isArray(indexes)) invalid("indexes must be an array.", collection);
+  if (!Array.isArray(indexes)) invalid2("indexes must be an array.", collection);
   const names = /* @__PURE__ */ new Set();
   return indexes.map((index, position) => {
-    if (!isRecord3(index) || !isRecord3(index.key) || Object.keys(index.key).length === 0) invalid(`indexes[${position}].key must be non-empty.`, collection);
+    if (!isRecord3(index) || !isRecord3(index.key) || Object.keys(index.key).length === 0) invalid2(`indexes[${position}].key must be non-empty.`, collection);
     assertBsonLiteral(index.key, `indexes[${position}].key`, collection);
-    if (index.name !== void 0 && (typeof index.name !== "string" || index.name.trim() === "")) invalid(`indexes[${position}].name must be non-empty.`, collection);
-    if (index.name && names.has(index.name)) invalid(`duplicate index name "${index.name}".`, collection);
+    if (index.name !== void 0 && (typeof index.name !== "string" || index.name.trim() === "")) invalid2(`indexes[${position}].name must be non-empty.`, collection);
+    if (index.name && names.has(index.name)) invalid2(`duplicate index name "${index.name}".`, collection);
     if (index.name) names.add(index.name);
-    if (index.options !== void 0 && !isRecord3(index.options)) invalid(`indexes[${position}].options must be an object.`, collection);
+    if (index.options !== void 0 && !isRecord3(index.options)) invalid2(`indexes[${position}].options must be an object.`, collection);
     if (index.options) assertBsonLiteral(index.options, `indexes[${position}].options`, collection);
-    if (index.options && "name" in index.options) invalid(`indexes[${position}].options.name is not allowed; use indexes[${position}].name.`, collection);
-    if (Object.keys(index.key).length === 1 && index.key._id === 1 || index.name === "_id_") invalid("indexes must not declare the built-in _id index.", collection);
+    if (index.options && "name" in index.options) invalid2(`indexes[${position}].options.name is not allowed; use indexes[${position}].name.`, collection);
+    if (Object.keys(index.key).length === 1 && index.key._id === 1 || index.name === "_id_") invalid2("indexes must not declare the built-in _id index.", collection);
     return { key: { ...index.key }, ...index.name ? { name: index.name } : {}, options: { ...index.options ?? {} } };
   });
 }
 function normalizeVerify(verify, collection) {
-  if (verify !== void 0 && !isRecord3(verify)) invalid("verify must be an object.", collection);
+  if (verify !== void 0 && !isRecord3(verify)) invalid2("verify must be an object.", collection);
   const input = verify;
   const mode = input?.mode ?? "sample";
-  if (mode !== "sample" && mode !== "full") invalid("verify.mode must be sample or full.", collection);
+  if (mode !== "sample" && mode !== "full") invalid2("verify.mode must be sample or full.", collection);
   const sampleSize = input?.sampleSize ?? 20;
-  if (!Number.isInteger(sampleSize) || sampleSize < 1 || sampleSize > 1e3) invalid("verify.sampleSize must be an integer from 1 to 1000.", collection);
+  if (!Number.isInteger(sampleSize) || sampleSize < 1 || sampleSize > 1e3) invalid2("verify.sampleSize must be an integer from 1 to 1000.", collection);
   const fields = input?.fields === void 0 ? void 0 : uniqueFields(input.fields, "verify.fields", collection);
   return { mode, sampleSize, ...fields ? { fields } : {} };
 }
 function normalizeBackup(backup, production) {
-  if (backup !== void 0 && !isRecord3(backup)) invalid("backup must be an object.");
+  if (backup !== void 0 && !isRecord3(backup)) invalid2("backup must be an object.");
   const input = backup;
-  if (production && (typeof input?.dir !== "string" || input.dir.trim() === "")) invalid("production jobs require an explicit durable backup.dir.");
+  if (production && (typeof input?.dir !== "string" || input.dir.trim() === "")) invalid2("production jobs require an explicit durable backup.dir.");
   const dir = typeof input?.dir === "string" && input.dir.trim() ? input.dir : path3.join(os2.tmpdir(), "monsqlize-data-tasks");
   const compression = input?.compression ?? "gzip";
-  if (compression !== "gzip" && compression !== "none") invalid("backup.compression must be gzip or none.");
-  if (input?.format !== void 0 && input.format !== "extended-jsonl") invalid("backup.format must be extended-jsonl.");
+  if (compression !== "gzip" && compression !== "none") invalid2("backup.compression must be gzip or none.");
+  if (input?.format !== void 0 && input.format !== "extended-jsonl") invalid2("backup.format must be extended-jsonl.");
   const retentionDays = input?.retentionDays ?? 7;
-  if (!Number.isInteger(retentionDays) || retentionDays < 1) invalid("backup.retentionDays must be a positive integer.");
+  if (!Number.isInteger(retentionDays) || retentionDays < 1) invalid2("backup.retentionDays must be a positive integer.");
   const maxBytes = input?.maxBytes ?? DEFAULT_DATA_TASK_BACKUP_MAX_BYTES;
-  if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) invalid("backup.maxBytes must be a positive safe integer.");
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) invalid2("backup.maxBytes must be a positive safe integer.");
   return { dir, format: "extended-jsonl", compression, retentionDays, maxBytes };
 }
 function normalizeLock(lock) {
   if (!lock) return false;
-  if (lock !== true && !isRecord3(lock)) invalid("lock must be a boolean or lease options object.");
+  if (lock !== true && !isRecord3(lock)) invalid2("lock must be a boolean or lease options object.");
   const options = lock === true ? {} : lock;
   const ttlMs = options.ttlMs ?? 12e4;
   const waitTimeoutMs = options.waitTimeoutMs ?? 0;
-  if (!Number.isInteger(ttlMs) || ttlMs < 1e3) invalid("lock.ttlMs must be an integer of at least 1000.");
-  if (!Number.isInteger(waitTimeoutMs) || waitTimeoutMs < 0) invalid("lock.waitTimeoutMs must be a non-negative integer.");
+  if (!Number.isInteger(ttlMs) || ttlMs < 1e3) invalid2("lock.ttlMs must be an integer of at least 1000.");
+  if (!Number.isInteger(waitTimeoutMs) || waitTimeoutMs < 0) invalid2("lock.waitTimeoutMs must be a non-negative integer.");
   return { ttlMs, waitTimeoutMs };
 }
 function normalizeDataTaskJob(job) {
-  if (!isRecord3(job)) invalid("job must be an object.");
-  if (typeof job.name !== "string" || job.name.trim() === "") invalid("job.name is required.");
+  if (!isRecord3(job)) invalid2("job must be an object.");
+  if (typeof job.name !== "string" || job.name.trim() === "") invalid2("job.name is required.");
   validateConnection(job.source, "source");
   validateConnection(job.target, "target");
-  if (job.source === job.target) invalid("source and target must be independent runtimes or connection options.");
+  if (job.source === job.target) invalid2("source and target must be independent runtimes or connection options.");
   const sourceOptions = connectionOptions(job.source);
   const targetOptions = connectionOptions(job.target);
-  if (sourceOptions && targetOptions && sourceOptions.databaseName === targetOptions.databaseName && sourceOptions.config?.uri === targetOptions.config?.uri) invalid("source and target resolve to the same MongoDB database.");
+  if (sourceOptions && targetOptions && sourceOptions.databaseName === targetOptions.databaseName && sourceOptions.config?.uri === targetOptions.config?.uri) invalid2("source and target resolve to the same MongoDB database.");
   if (typeof job.targetEnvironment !== "string" || !ENVIRONMENTS.has(job.targetEnvironment.toLowerCase())) {
-    invalid("targetEnvironment must be development, test, staging, production, prod, or live.");
+    invalid2("targetEnvironment must be development, test, staging, production, prod, or live.");
   }
-  if (!Array.isArray(job.collections) || job.collections.length === 0) invalid("collections must be a non-empty array.");
+  if (!Array.isArray(job.collections) || job.collections.length === 0) invalid2("collections must be a non-empty array.");
   const targetNames = /* @__PURE__ */ new Set();
   const collections = job.collections.map((collection, position) => {
-    if (!isRecord3(collection) || typeof collection.name !== "string" || collection.name.trim() === "") invalid(`collections[${position}].name is required.`);
+    if (!isRecord3(collection) || typeof collection.name !== "string" || collection.name.trim() === "") invalid2(`collections[${position}].name is required.`);
     const name = collection.name.trim();
     const targetName = typeof collection.targetName === "string" && collection.targetName.trim() ? collection.targetName.trim() : name;
-    if (targetNames.has(targetName)) invalid(`target collection "${targetName}" is configured more than once.`, name);
+    if (targetNames.has(targetName)) invalid2(`target collection "${targetName}" is configured more than once.`, name);
     targetNames.add(targetName);
     const indexes = normalizeIndexes(collection.indexes, name);
     const data = normalizeData(collection.data, name);
-    if (indexes.length === 0 && !data) invalid("each collection requires indexes or data.", name);
+    if (indexes.length === 0 && !data) invalid2("each collection requires indexes or data.", name);
     return { name, targetName, indexes, ...data ? { data } : {}, verify: normalizeVerify(collection.verify, name) };
   });
   const production = PRODUCTION_ENVIRONMENTS.has(job.targetEnvironment.toLowerCase());