monsqlize 3.1.14 → 3.3.0

package/dist/esm/index.mjs

@@ -39,6 +39,14 @@ var ErrorCodes = {
   INVALID_EXPRESSION: "INVALID_EXPRESSION",
   INVALID_PAGINATION: "INVALID_PAGINATION",
   INVALID_OPERATION: "INVALID_OPERATION",
+  /** Invalid local Vector Search options before the driver is called. */
+  INVALID_VECTOR_SEARCH: "INVALID_VECTOR_SEARCH",
+  /** 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. */
+  RELATION_IN_USE: "RELATION_IN_USE",
+  /** Relation usage coverage is incomplete, so a protected delete must not continue. */
+  RELATION_USAGE_UNAVAILABLE: "RELATION_USAGE_UNAVAILABLE",
   CACHE_UNAVAILABLE: "CACHE_UNAVAILABLE",
   MANAGEMENT_OPERATION_FAILED: "MANAGEMENT_OPERATION_FAILED",
   NOT_CONNECTED: "NOT_CONNECTED",
@@ -484,12 +492,49 @@ function validateRelationConfig(name, config) {
   if (config.single !== void 0 && typeof config.single !== "boolean") {
     throw createError(ErrorCodes.INVALID_ARGUMENT, `relations.single must be a boolean`);
   }
+  normalizeRelationSelect(config.select, { relation: name });
+}
+function normalizeRelationSelect(value, context = {}) {
+  if (value === void 0) {
+    return void 0;
+  }
+  const invalid2 = (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 tokens = [];
+  for (const rawToken of rawTokens) {
+    if (typeof rawToken !== "string") {
+      invalid2("select array entries must be strings");
+    }
+    const parts = rawToken.trim().split(/\s+/).filter(Boolean);
+    if (parts.length === 0) {
+      invalid2("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");
+    }
+    if (token.includes(".")) {
+      invalid2("dot-path fields are not supported");
+    }
+  }
+  return [...new Set(tokens)];
 }
 function normalizePopulateConfig(path5) {
   return typeof path5 === "string" ? { path: path5 } : path5;
 }
 
 // src/capabilities/model/model-registry.ts
+function defineModel(collectionName, definition) {
+  return { collectionName, definition };
+}
 var Model = class {
   static {
     // collection name → registered model definition
@@ -504,21 +549,19 @@ var Model = class {
     /** Collection names that have been redefined (used by the runtime to trigger hot-reload). */
     this._redefinedNames = /* @__PURE__ */ new Set();
   }
-  /**
-   * Register a new model definition.
-   * Throws MODEL_ALREADY_EXISTS if a model with the same name already exists.
-   * Validates the definition and resolves the timestamps option.
-   */
-  static define(collectionName, definition) {
+  static define(collectionNameOrDescriptor, definition) {
+    const collectionName = typeof collectionNameOrDescriptor === "string" ? collectionNameOrDescriptor : collectionNameOrDescriptor.collectionName;
+    const modelDefinition = typeof collectionNameOrDescriptor === "string" ? definition : collectionNameOrDescriptor.definition;
     const normalizedName = validateCollectionName(collectionName);
     if (this.registry.has(normalizedName)) {
       throw createError(ErrorCodes.MODEL_ALREADY_EXISTS, `Model '${normalizedName}' is already defined.`);
     }
-    validateDefinition(definition);
-    processTimestamps(definition);
+    validateDefinition(modelDefinition);
+    const resolvedDefinition = modelDefinition;
+    processTimestamps(resolvedDefinition);
     this.registry.set(normalizedName, {
       collectionName: normalizedName,
-      definition
+      definition: resolvedDefinition
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
     });
     this.bumpRevision(normalizedName);
@@ -1060,6 +1103,56 @@ function resolveRegisteredCollectionName(registered, fallback) {
   const definition = registered.definition;
   return definition.collection ?? definition.name ?? registered.collectionName;
 }
+function flattenComparableValues(value) {
+  if (Array.isArray(value)) {
+    return value.flatMap((entry) => flattenComparableValues(entry));
+  }
+  return value === void 0 || value === null ? [] : [value];
+}
+function resolveNestedPopulatePaths(value) {
+  if (value === void 0) {
+    return [];
+  }
+  const paths = Array.isArray(value) ? value : [value];
+  for (const path5 of paths) {
+    const valid = typeof path5 === "string" || typeof path5 === "object" && path5 !== null && !Array.isArray(path5) && Boolean(path5.path);
+    if (!valid) {
+      throw createError(ErrorCodes.INVALID_ARGUMENT, "nested populate must be a string, array, or object");
+    }
+  }
+  return paths;
+}
+function collectNestedLocalFields(relatedModel, nestedPaths) {
+  if (!relatedModel) {
+    return [];
+  }
+  const relations = relatedModel.getRelations();
+  return unique(
+    nestedPaths.map((path5) => relations[normalizePopulateConfig(path5).path]?.localField).filter((field) => Boolean(field))
+  );
+}
+function dedupeDocuments(documents) {
+  const seen = /* @__PURE__ */ new Set();
+  return documents.filter((document) => {
+    if (seen.has(document)) {
+      return false;
+    }
+    seen.add(document);
+    return true;
+  });
+}
+function rebuildPopulateMatches(localValue, grouped, sort) {
+  const matches = flattenComparableValues(localValue).flatMap((value) => grouped.get(toKey(value)) ?? []);
+  const deduped = dedupeDocuments(matches);
+  return sort ? applySort(deduped, sort) : deduped;
+}
+function projectPopulatedDocument(document, select, nestedPaths) {
+  if (!select) {
+    return document;
+  }
+  const nestedRelationFields = nestedPaths.map((path5) => normalizePopulateConfig(path5).path);
+  return pickFields(document, [.../* @__PURE__ */ new Set([...select, ...nestedRelationFields])]);
+}
 async function populateModelPath(context, docs, path5, traversalState) {
   const config = normalizePopulateConfig(path5);
   const state = resolvePopulateState(config, traversalState);
@@ -1078,9 +1171,8 @@ async function populateModelPath(context, docs, path5, traversalState) {
     if (!relation) {
       throw createError(ErrorCodes.INVALID_ARGUMENT, `Undefined relation: ${config.path}`);
     }
-    const keys = unique(
-      docs.map((doc) => getByPath(doc, relation.localField)).filter((value) => value !== void 0 && value !== null)
-    );
+    const localValues = docs.map((doc) => getByPath(doc, relation.localField));
+    const keys = unique(localValues.flatMap((value) => flattenComparableValues(value)));
     if (keys.length === 0) {
       for (const doc of docs) {
         doc[config.path] = relation.single ? null : [];
@@ -1095,51 +1187,42 @@ async function populateModelPath(context, docs, path5, traversalState) {
     const relatedCollectionName = resolveRegisteredCollectionName(registered, relation.from);
     const relatedCollection = context.runtime.scopedCollection(relatedCollectionName, scope);
     const relatedModel = Model.has(relation.from) ? context.runtime.scopedModel(relation.from, scope) : null;
+    const nestedPaths = resolveNestedPopulatePaths(config.populate);
+    const effectiveSelect = normalizeRelationSelect(config.select, { path: config.path }) ?? normalizeRelationSelect(relation.select, { relation: config.path });
+    const projectionFields = effectiveSelect ? [.../* @__PURE__ */ new Set([
+      ...effectiveSelect,
+      relation.foreignField,
+      "_id",
+      ...collectNestedLocalFields(relatedModel, nestedPaths)
+    ])] : [];
     const relatedDocs = await relatedCollection.find({
       [relation.foreignField]: { $in: keys },
       ...config.match ?? {}
-    });
+    }, effectiveSelect ? {
+      projection: Object.fromEntries(projectionFields.map((field) => [field, 1]))
+    } : void 0);
     let hydrated = relatedModel ? relatedModel.hydrateDocuments(relatedDocs) : relatedDocs.map((item) => ({ ...item }));
-    if (config.sort) {
-      hydrated = applySort(hydrated, config.sort);
-    }
-    if (config.select) {
-      const select = config.select;
-      hydrated = hydrated.map((item) => pickFields(item, select, [relation.foreignField]));
-    }
-    if (config.populate) {
-      const nestedRaw = config.populate;
-      const isValidNestedConfig = (value) => {
-        if (typeof value === "string" || Array.isArray(value)) return true;
-        if (typeof value === "object" && value !== null && value.path) return true;
-        return false;
-      };
-      if (!isValidNestedConfig(nestedRaw)) {
-        throw createError(ErrorCodes.INVALID_ARGUMENT, "nested populate must be a string, array, or object");
-      }
-      if (relatedModel) {
-        if (state.depth + 1 > state.maxDepth) {
-          throw createError(ErrorCodes.INVALID_ARGUMENT, `populate maxDepth exceeded: ${state.maxDepth}`);
-        }
-        const nestedPaths = Array.isArray(config.populate) ? config.populate : [config.populate];
-        hydrated = await relatedModel.populateDocuments(hydrated, nestedPaths, {
-          depth: state.depth + 1,
-          maxDepth: state.maxDepth,
-          activeConfigs: state.activeConfigs
-        });
+    if (nestedPaths.length > 0 && relatedModel) {
+      if (state.depth + 1 > state.maxDepth) {
+        throw createError(ErrorCodes.INVALID_ARGUMENT, `populate maxDepth exceeded: ${state.maxDepth}`);
       }
+      hydrated = await relatedModel.populateDocuments(hydrated, nestedPaths, {
+        depth: state.depth + 1,
+        maxDepth: state.maxDepth,
+        activeConfigs: state.activeConfigs
+      });
     }
     const grouped = groupBy(hydrated, (item) => getByPath(item, relation.foreignField));
-    for (const doc of docs) {
-      const localValue = getByPath(doc, relation.localField);
-      let matches = grouped.get(toKey(localValue)) ?? [];
+    for (const [index, doc] of docs.entries()) {
+      let matches = rebuildPopulateMatches(localValues[index], grouped, config.sort);
       if (config.skip) {
         matches = matches.slice(config.skip);
       }
       if (config.limit !== void 0) {
         matches = matches.slice(0, config.limit);
       }
-      doc[config.path] = relation.single ? matches[0] ?? null : [...matches];
+      const projectedMatches = matches.map((item) => projectPopulatedDocument(item, effectiveSelect, nestedPaths));
+      doc[config.path] = relation.single ? projectedMatches[0] ?? null : projectedMatches;
     }
     return docs;
   } finally {
@@ -5557,7 +5640,382 @@ async function orchestrateModelDeleteMany(context, filter, options) {
   return result;
 }
 
+// src/capabilities/model/relation-usage.ts
+var DEFAULT_MAX_TARGETS = 100;
+var DEFAULT_MAX_SAMPLES = 20;
+function isNonArrayObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizePositiveInteger(value, field, fallback) {
+  if (value === void 0) {
+    return fallback;
+  }
+  if (!Number.isInteger(value) || value <= 0) {
+    throw createError(ErrorCodes.INVALID_ARGUMENT, `${field} must be a positive integer`, [{ field, value }]);
+  }
+  return value;
+}
+function normalizeRelationNames(value, field) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string" || entry.trim().length === 0)) {
+    throw createError(ErrorCodes.INVALID_ARGUMENT, `${field} must be an array of non-empty strings`, [{ field, value }]);
+  }
+  return [...new Set(value.map((entry) => entry.trim()))];
+}
+function normalizeRelationUsageOptions(options) {
+  if (options !== void 0 && !isNonArrayObject(options)) {
+    throw createError(ErrorCodes.INVALID_ARGUMENT, "relation usage options must be a non-array object", [{ field: "options", value: options }]);
+  }
+  const value = options ?? {};
+  if (value.includeSoftDeletedReferences !== void 0 && typeof value.includeSoftDeletedReferences !== "boolean") {
+    throw createError(
+      ErrorCodes.INVALID_ARGUMENT,
+      "includeSoftDeletedReferences must be a boolean",
+      [{ field: "includeSoftDeletedReferences", value: value.includeSoftDeletedReferences }]
+    );
+  }
+  return {
+    session: value.session,
+    maxTargets: normalizePositiveInteger(value.maxTargets, "maxTargets", DEFAULT_MAX_TARGETS),
+    maxSamples: normalizePositiveInteger(value.maxSamples, "maxSamples", DEFAULT_MAX_SAMPLES),
+    includeRelations: normalizeRelationNames(value.includeRelations, "includeRelations"),
+    excludeRelations: normalizeRelationNames(value.excludeRelations, "excludeRelations"),
+    includeSoftDeletedReferences: value.includeSoftDeletedReferences !== false
+  };
+}
+function resolveRegisteredCollectionName2(registered) {
+  const definition = registered.definition;
+  return definition.collection ?? definition.name ?? registered.collectionName;
+}
+function flattenComparableValues2(value) {
+  if (Array.isArray(value)) {
+    return value.flatMap((entry) => flattenComparableValues2(entry));
+  }
+  return value === void 0 || value === null ? [] : [value];
+}
+function isRelationSelected(options, sourceModel, relation) {
+  const qualified = `${sourceModel}.${relation}`;
+  const matches = (names) => Boolean(names?.includes(qualified) || names?.includes(relation));
+  if (options.includeRelations && !matches(options.includeRelations)) {
+    return false;
+  }
+  return !matches(options.excludeRelations);
+}
+function describeError(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function findDeclaredInboundRelations(targetModelName) {
+  const relations = [];
+  for (const sourceModel of Model.list()) {
+    const registered = Model.get(sourceModel);
+    if (!registered) {
+      continue;
+    }
+    for (const [relation, config] of Object.entries(registered.definition.relations ?? {})) {
+      if (config.from !== targetModelName) {
+        continue;
+      }
+      relations.push({
+        sourceModel,
+        sourceCollection: resolveRegisteredCollectionName2(registered),
+        relation,
+        definition: registered.definition,
+        localField: config.localField,
+        foreignField: config.foreignField
+      });
+    }
+  }
+  return relations;
+}
+function buildRelationUsageTargetProjection(targetModelName) {
+  const fields = /* @__PURE__ */ new Set(["_id"]);
+  for (const relation of findDeclaredInboundRelations(targetModelName)) {
+    fields.add(relation.foreignField);
+  }
+  return Object.fromEntries([...fields].map((field) => [field, 1]));
+}
+function createUnavailableRelationUsageReport(context, reason) {
+  return {
+    used: false,
+    target: {
+      matchedCount: 0,
+      truncated: false,
+      sampleIds: []
+    },
+    checkedRelations: 0,
+    usages: [],
+    coverage: {
+      mode: "registered-declared",
+      complete: false,
+      registryModels: Model.list(),
+      checkedModels: [],
+      skipped: [{ sourceModel: context.modelName, reason }]
+    }
+  };
+}
+async function inspectDeclaredRelationUsage(context, targets, inputOptions, targetTruncated = false) {
+  const options = normalizeRelationUsageOptions(inputOptions);
+  const registryModels = Model.list();
+  const checkedModels = /* @__PURE__ */ new Set();
+  const skipped = [];
+  const usages = [];
+  let checkedRelations = 0;
+  for (const inbound of findDeclaredInboundRelations(context.modelName)) {
+    if (!isRelationSelected(options, inbound.sourceModel, inbound.relation)) {
+      skipped.push({
+        sourceModel: inbound.sourceModel,
+        reason: `relation '${inbound.sourceModel}.${inbound.relation}' was excluded by relation selection`
+      });
+      continue;
+    }
+    checkedRelations += 1;
+    const targetValues = unique(
+      targets.flatMap((target) => flattenComparableValues2(getByPath(target, inbound.foreignField)))
+    );
+    if (targetValues.length === 0) {
+      checkedModels.add(inbound.sourceModel);
+      continue;
+    }
+    const scope = {
+      database: inbound.definition.connection?.database ?? context.dbName,
+      pool: inbound.definition.connection?.pool ?? context.poolName
+    };
+    const baseQuery = {
+      [inbound.localField]: { $in: targetValues }
+    };
+    const sourceSoftDelete = resolveModelSoftDeleteConfig(inbound.definition);
+    const query = !options.includeSoftDeletedReferences && sourceSoftDelete?.enabled ? { $and: [baseQuery, { [sourceSoftDelete.field]: null }] } : baseQuery;
+    try {
+      const collection = context.runtime.scopedCollection(inbound.sourceCollection, scope);
+      if (!collection) {
+        throw new Error("scopedCollection returned no collection");
+      }
+      checkedModels.add(inbound.sourceModel);
+      const count = await collection.count(query, { session: options.session });
+      if (typeof count !== "number" || !Number.isFinite(count) || count < 0) {
+        throw new Error("relation usage count did not return a non-negative number");
+      }
+      if (count === 0) {
+        continue;
+      }
+      const samples = await collection.find(query, {
+        session: options.session,
+        projection: { _id: 1 },
+        limit: options.maxSamples
+      });
+      usages.push({
+        sourceModel: inbound.sourceModel,
+        sourceCollection: inbound.sourceCollection,
+        relation: inbound.relation,
+        localField: inbound.localField,
+        foreignField: inbound.foreignField,
+        count,
+        sampleIds: samples.filter((sample) => isNonArrayObject(sample)).map((sample) => sample._id).filter((id) => id !== void 0).slice(0, options.maxSamples)
+      });
+    } catch (error) {
+      skipped.push({
+        sourceModel: inbound.sourceModel,
+        reason: describeError(error)
+      });
+    }
+  }
+  const targetSampleIds = targets.map((target) => target._id).filter((id) => id !== void 0).slice(0, options.maxSamples);
+  return {
+    used: usages.length > 0,
+    target: {
+      matchedCount: targets.length,
+      truncated: targetTruncated,
+      sampleIds: targetSampleIds
+    },
+    checkedRelations,
+    usages,
+    coverage: {
+      mode: "registered-declared",
+      complete: !targetTruncated && skipped.length === 0,
+      registryModels,
+      checkedModels: [...checkedModels],
+      skipped
+    }
+  };
+}
+function stripRelationUsageOptions(options) {
+  if (!isNonArrayObject(options)) {
+    return options;
+  }
+  const {
+    maxTargets: _maxTargets,
+    maxSamples: _maxSamples,
+    includeRelations: _includeRelations,
+    excludeRelations: _excludeRelations,
+    includeSoftDeletedReferences: _includeSoftDeletedReferences,
+    ...deleteOptions
+  } = options;
+  void _maxTargets;
+  void _maxSamples;
+  void _includeRelations;
+  void _excludeRelations;
+  void _includeSoftDeletedReferences;
+  return deleteOptions;
+}
+
+// src/capabilities/model/model-p0-operations.ts
+function relationUsageContext(host) {
+  return {
+    modelName: host.modelName,
+    runtime: host.runtime,
+    dbName: host.dbName,
+    poolName: host.poolName
+  };
+}
+function isNonEmptyFilter(filter) {
+  return typeof filter === "object" && filter !== null && !Array.isArray(filter) && Object.keys(filter).length > 0;
+}
+function relationTargetReadOptions(options, projection) {
+  const source = options ?? {};
+  const result = { projection };
+  for (const key of ["session", "collation", "hint", "comment", "let", "maxTimeMS", "readConcern", "readPreference"]) {
+    if (source[key] !== void 0) {
+      result[key] = source[key];
+    }
+  }
+  return result;
+}
+function hydrateVectorSearchHits(host, hits) {
+  return hits.map((hit) => {
+    const document = host.hydrateDocument(hit.document);
+    if (!document) {
+      throw createError(ErrorCodes.INVALID_OPERATION, "Vector Search returned a non-document result");
+    }
+    return { document, score: hit.score };
+  });
+}
+async function executeModelVectorSearch(host, options) {
+  if (typeof options !== "object" || options === null || Array.isArray(options)) {
+    const hits2 = await host.collection.vectorSearch(options);
+    return hydrateVectorSearchHits(host, hits2);
+  }
+  const { withDeleted, onlyDeleted, ...collectionOptions } = options;
+  if (withDeleted !== void 0 && typeof withDeleted !== "boolean") {
+    throw createError(
+      ErrorCodes.INVALID_VECTOR_SEARCH,
+      "withDeleted must be a boolean",
+      [{ field: "withDeleted", reason: "boolean required" }]
+    );
+  }
+  if (onlyDeleted !== void 0 && typeof onlyDeleted !== "boolean") {
+    throw createError(
+      ErrorCodes.INVALID_VECTOR_SEARCH,
+      "onlyDeleted must be a boolean",
+      [{ field: "onlyDeleted", reason: "boolean required" }]
+    );
+  }
+  const filter = host.softDeleteConfig?.enabled && !withDeleted ? applyModelSoftDeleteFilter(
+    collectionOptions.filter,
+    { withDeleted, onlyDeleted },
+    host.softDeleteConfig
+  ) : collectionOptions.filter;
+  const hits = await host.collection.vectorSearch({
+    ...collectionOptions,
+    ...filter === void 0 ? {} : { filter }
+  });
+  return hydrateVectorSearchHits(host, hits);
+}
+async function executeRelationUsageCheck(host, filter, options) {
+  const normalizedOptions = normalizeRelationUsageOptions(options);
+  const context = relationUsageContext(host);
+  try {
+    const rawTargets = await host.collection.find(
+      applyModelSoftDeleteFilter(filter, void 0, host.softDeleteConfig),
+      {
+        session: normalizedOptions.session,
+        projection: buildRelationUsageTargetProjection(host.modelName),
+        limit: normalizedOptions.maxTargets + 1
+      }
+    );
+    const targets = rawTargets.filter(
+      (target) => typeof target === "object" && target !== null && !Array.isArray(target)
+    );
+    return inspectDeclaredRelationUsage(
+      context,
+      targets.slice(0, normalizedOptions.maxTargets),
+      normalizedOptions,
+      targets.length > normalizedOptions.maxTargets
+    );
+  } catch (error) {
+    return createUnavailableRelationUsageReport(context, error instanceof Error ? error.message : String(error));
+  }
+}
+async function executeProtectedRelationDelete(host, filter, options, force) {
+  if (!isNonEmptyFilter(filter)) {
+    throw createError(
+      ErrorCodes.INVALID_ARGUMENT,
+      "protected relation deletion requires a non-empty filter",
+      [{ field: "filter", reason: "non-empty object required" }]
+    );
+  }
+  const rawOptions = options ?? {};
+  if (rawOptions.includeRelations !== void 0 || rawOptions.excludeRelations !== void 0) {
+    throw createError(
+      ErrorCodes.INVALID_ARGUMENT,
+      "protected relation deletion cannot narrow the declared relation scan",
+      [{ field: "includeRelations/excludeRelations", reason: "protected deletion always scans all declared relations" }]
+    );
+  }
+  const usageOptions = normalizeRelationUsageOptions(options);
+  const context = relationUsageContext(host);
+  const deleteOptions = stripRelationUsageOptions(options);
+  let target;
+  try {
+    const targetFilter = force || !host.softDeleteConfig?.enabled ? filter : { ...filter, [host.softDeleteConfig.field]: null };
+    const rawTarget = await host.collection.findOne(
+      targetFilter,
+      relationTargetReadOptions(options, buildRelationUsageTargetProjection(host.modelName))
+    );
+    target = typeof rawTarget === "object" && rawTarget !== null && !Array.isArray(rawTarget) ? rawTarget : null;
+  } catch (error) {
+    const usage2 = createUnavailableRelationUsageReport(
+      context,
+      error instanceof Error ? error.message : String(error)
+    );
+    throw createError(
+      ErrorCodes.RELATION_USAGE_UNAVAILABLE,
+      "Unable to resolve a target for protected relation deletion",
+      [{ coverage: usage2.coverage, reason: usage2.coverage.skipped[0]?.reason, skipped: usage2.coverage.skipped }]
+    );
+  }
+  const usage = await inspectDeclaredRelationUsage(context, target ? [target] : [], usageOptions);
+  if (!usage.coverage.complete) {
+    throw createError(
+      ErrorCodes.RELATION_USAGE_UNAVAILABLE,
+      "Declared relation usage coverage is incomplete; protected deletion was not performed",
+      [{ coverage: usage.coverage, reason: "incomplete relation usage coverage", skipped: usage.coverage.skipped }]
+    );
+  }
+  if (usage.used) {
+    throw createError(
+      ErrorCodes.RELATION_IN_USE,
+      "Protected deletion was blocked because declared relations still reference the target",
+      [{ used: usage.used, usages: usage.usages, coverage: usage.coverage }]
+    );
+  }
+  if (target && target._id === void 0) {
+    throw createError(
+      ErrorCodes.RELATION_USAGE_UNAVAILABLE,
+      "Protected deletion target did not include an _id",
+      [{ coverage: usage.coverage, reason: "target _id missing", skipped: usage.coverage.skipped }]
+    );
+  }
+  const deleteFilter = target ? { _id: target._id } : { _id: { $in: [] } };
+  const result = force ? await host.forceDelete(deleteFilter, deleteOptions) : await host.deleteOne(deleteFilter, deleteOptions);
+  return { result, usage };
+}
+
 // src/capabilities/model/index.ts
+function resolveModelRegistryName(definition, fallback) {
+  return Model.list().find((name) => Model.get(name)?.definition === definition) ?? fallback;
+}
 var ModelInstance = class {
   constructor(collection, runtime, options) {
     this.collection = collection;
@@ -5578,6 +6036,7 @@ var ModelInstance = class {
     this.dbName = options.dbName;
     this.poolName = options.poolName;
     this.definition = options.definition;
+    this.modelName = options.modelName ?? resolveModelRegistryName(options.definition, options.collectionName);
     this.relations = new Map(Object.entries(options.definition.relations ?? {}));
     for (const [name, config] of this.relations) {
       validateRelationConfig(name, config);
@@ -5761,6 +6220,9 @@ var ModelInstance = class {
       };
     });
   }
+  async vectorSearch(options) {
+    return executeModelVectorSearch(this.p0OperationsContext(), options);
+  }
   count(query, options) {
     const filteredQuery = applyModelSoftDeleteFilter(query, options, this._softDeleteConfig);
     return this.runV1HookedOperation("find", [filteredQuery, options], (nextQuery, nextOptions) => this.collection.count(nextQuery, nextOptions));
@@ -5810,6 +6272,19 @@ var ModelInstance = class {
   async deleteMany(filter, options) {
     return this.runModelWrite(() => orchestrateModelDeleteMany(this.mutationContext(), filter, options));
   }
+  /**
+   * Inspects only registered and declared inbound relations. It is read-only;
+   * callers must check coverage before treating an empty result as safe.
+   */
+  async checkRelationUsage(filter, options) {
+    return executeRelationUsageCheck(this.p0OperationsContext(), filter, options);
+  }
+  async deleteOneWithRelations(filter, options) {
+    return executeProtectedRelationDelete(this.p0OperationsContext(), filter, options, false);
+  }
+  async forceDeleteWithRelations(filter, options) {
+    return executeProtectedRelationDelete(this.p0OperationsContext(), filter, options, true);
+  }
   // ── soft-delete extended methods (only meaningful when softDelete is enabled) ──
   findWithDeleted(query, options) {
     return findWithDeletedDocuments(this.softDeleteContext(), query, options);
@@ -5978,6 +6453,19 @@ var ModelInstance = class {
       populateDocument: (document, paths) => this.populateSingle(document, paths)
     }, doc);
   }
+  p0OperationsContext() {
+    return {
+      collection: this.collection,
+      softDeleteConfig: this._softDeleteConfig,
+      modelName: this.modelName,
+      runtime: this.runtime,
+      dbName: this.dbName,
+      poolName: this.poolName,
+      hydrateDocument: (doc) => this.hydrateDocument(doc),
+      deleteOne: (filter, options) => this.deleteOne(filter, options),
+      forceDelete: (filter, options) => this.forceDelete(filter, options)
+    };
+  }
   softDeleteContext() {
     return {
       collection: this.collection,
@@ -7173,6 +7661,7 @@ var CountQueue = class {
 };
 
 // src/capabilities/pool/pool-health-checker.ts
+var SILENT_HEALTH_CHECKER_LOGGER = {};
 var HealthChecker = class {
   constructor(options = {}) {
     this._healthStatus = /* @__PURE__ */ new Map();
@@ -7182,7 +7671,7 @@ var HealthChecker = class {
     this._inProgress = /* @__PURE__ */ new Set();
     this._started = false;
     this._poolManager = options.poolManager ?? null;
-    this._logger = options.logger ?? console;
+    this._logger = options.logger ?? SILENT_HEALTH_CHECKER_LOGGER;
   }
   register(poolNameOrConfig, configOrClient) {
     let poolName;
@@ -7306,6 +7795,7 @@ var HealthChecker = class {
 };
 
 // src/capabilities/pool/pool-selector.ts
+var SILENT_POOL_SELECTOR_LOGGER = {};
 var POOL_STRATEGY_ALIASES = {
   "round-robin": "roundRobin",
   "least-connections": "leastConnections",
@@ -7319,7 +7809,7 @@ var PoolSelector = class {
   constructor(options = {}) {
     this._roundRobinIndex = /* @__PURE__ */ new Map();
     this._strategy = normalizePoolStrategy(options.strategy);
-    this._logger = options.logger ?? console;
+    this._logger = options.logger ?? SILENT_POOL_SELECTOR_LOGGER;
   }
   select(pools, context) {
     if (!pools || pools.length === 0) {
@@ -7450,11 +7940,12 @@ var PoolSelector = class {
 };
 
 // src/capabilities/pool/pool-stats-manager.ts
+var SILENT_POOL_STATS_LOGGER = {};
 var PoolStatsManager = class {
   constructor(options = {}) {
     this._stats = /* @__PURE__ */ new Map();
     this._buffer = [];
-    this._logger = options.logger ?? console;
+    this._logger = options.logger ?? SILENT_POOL_STATS_LOGGER;
     this._batchInterval = setInterval(() => {
       this._flush();
     }, 100);
@@ -7702,9 +8193,9 @@ var ConnectionPoolManager = class {
     this._fallbackConfig = this.fallback;
     this._fallback = this.fallback;
     this._pools = this.pools;
-    this._selector = new PoolSelector({ strategy: this.strategy });
-    this._healthChecker = new HealthChecker({ poolManager: this });
-    this._stats = new PoolStatsManager({ logger: options.logger ?? void 0 });
+    this._selector = new PoolSelector({ strategy: this.strategy, logger: this.logger ?? void 0 });
+    this._healthChecker = new HealthChecker({ poolManager: this, logger: this.logger ?? void 0 });
+    this._stats = new PoolStatsManager({ logger: this.logger ?? void 0 });
   }
   /**
    * Add a connection pool.
@@ -9537,7 +10028,7 @@ async function computeTotals(coll, query, limit, totals, defaults = {}, queryCac
 }
 
 // src/adapters/mongodb/queries/find-page.ts
-function normalizePositiveInteger(value, fallback, field) {
+function normalizePositiveInteger2(value, fallback, field) {
   if (value === void 0 || value === null) {
     return fallback;
   }
@@ -9585,8 +10076,8 @@ async function executeFindPage(collection, options = {}, defaults = {}, queryCac
   const metaStartTs = Date.now();
   const metaSteps = [];
   const ext = options;
-  const page = normalizePositiveInteger(options.page, 1, "page");
-  const rawLimit = normalizePositiveInteger(options.limit, DEFAULT_FIND_PAGE_LIMIT, "limit");
+  const page = normalizePositiveInteger2(options.page, 1, "page");
+  const rawLimit = normalizePositiveInteger2(options.limit, DEFAULT_FIND_PAGE_LIMIT, "limit");
   const limit = defaults.findPageMaxLimit !== void 0 && rawLimit > defaults.findPageMaxLimit ? defaults.findPageMaxLimit : rawLimit;
   const sort = normalizeSortShape(options.sort);
   const baseQuery = options.query ?? {};
@@ -10460,6 +10951,138 @@ function explainDocuments(collection, query, options, defaults) {
   return createFindChain(collection, query, options, defaults).explain(options?.explain ?? "queryPlanner");
 }
 
+// src/adapters/mongodb/queries/vector-search.ts
+var VECTOR_SEARCH_SCORE_FIELD = "__monsqlize_vector_search_score__";
+function attachVectorSearchOperationContext(error, namespace) {
+  if (error instanceof Error) {
+    const contextualized = error;
+    const existing = contextualized.monsqlize;
+    try {
+      contextualized.monsqlize = {
+        ...existing && typeof existing === "object" ? existing : {},
+        operation: "vectorSearch",
+        namespace
+      };
+    } catch {
+    }
+    return error;
+  }
+  return createError(
+    ErrorCodes.MONGODB_ERROR,
+    "vectorSearch execution failed",
+    [{ operation: "vectorSearch", namespace, reason: String(error) }]
+  );
+}
+function assertNonEmptyString(value, field) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw createError(ErrorCodes.INVALID_VECTOR_SEARCH, `${field} must be a non-empty string`, [{ field, reason: "non-empty string required" }]);
+  }
+}
+function assertPositiveInteger(value, field) {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw createError(ErrorCodes.INVALID_VECTOR_SEARCH, `${field} must be a positive integer`, [{ field, reason: "positive integer required" }]);
+  }
+}
+function isNonArrayObject2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizeVectorProjection(value) {
+  if (value === void 0) return void 0;
+  if (Array.isArray(value)) {
+    if (value.some((field) => typeof field !== "string" || field.length === 0)) {
+      throw createError(ErrorCodes.INVALID_VECTOR_SEARCH, "projection array entries must be non-empty strings", [{ field: "projection", reason: "array entries must be non-empty strings" }]);
+    }
+    return normalizeProjection(value);
+  }
+  if (!isNonArrayObject2(value)) {
+    throw createError(ErrorCodes.INVALID_VECTOR_SEARCH, "projection must be an object or string array", [{ field: "projection", reason: "object or string array required" }]);
+  }
+  return normalizeProjection(value);
+}
+function normalizeAggregateOptions(value) {
+  if (value === void 0) return void 0;
+  if (!isNonArrayObject2(value)) {
+    throw createError(ErrorCodes.INVALID_VECTOR_SEARCH, "aggregateOptions must be a non-array object", [{ field: "aggregateOptions", reason: "non-array object required" }]);
+  }
+  for (const key of ["meta", "stream", "explain"]) {
+    if (Object.prototype.hasOwnProperty.call(value, key)) {
+      throw createError(ErrorCodes.INVALID_VECTOR_SEARCH, `aggregateOptions.${key} is not supported by vectorSearch()`, [{ field: `aggregateOptions.${key}`, reason: "reserved aggregate option" }]);
+    }
+  }
+  return { ...value };
+}
+function buildVectorSearchPipeline(options) {
+  if (!isNonArrayObject2(options)) {
+    throw createError(ErrorCodes.INVALID_VECTOR_SEARCH, "vectorSearch options must be a non-array object", [{ field: "options", reason: "non-array object required" }]);
+  }
+  assertNonEmptyString(options.index, "index");
+  assertNonEmptyString(options.path, "path");
+  assertPositiveInteger(options.limit, "limit");
+  if (!Array.isArray(options.queryVector) || options.queryVector.length === 0) {
+    throw createError(ErrorCodes.INVALID_VECTOR_SEARCH, "queryVector must be a non-empty number array", [{ field: "queryVector", reason: "non-empty number array required" }]);
+  }
+  if (options.queryVector.some((value) => typeof value !== "number" || !Number.isFinite(value))) {
+    throw createError(ErrorCodes.INVALID_VECTOR_SEARCH, "queryVector values must be finite numbers", [{ field: "queryVector", reason: "finite numbers required" }]);
+  }
+  if (options.exact !== void 0 && typeof options.exact !== "boolean") {
+    throw createError(ErrorCodes.INVALID_VECTOR_SEARCH, "exact must be a boolean", [{ field: "exact", reason: "boolean required" }]);
+  }
+  if (options.filter !== void 0 && !isNonArrayObject2(options.filter)) {
+    throw createError(ErrorCodes.INVALID_VECTOR_SEARCH, "filter must be a non-array object", [{ field: "filter", reason: "non-array object required" }]);
+  }
+  const isExactSearch = options.exact === true;
+  if (isExactSearch) {
+    if (options.numCandidates !== void 0) {
+      throw createError(ErrorCodes.INVALID_VECTOR_SEARCH, "numCandidates is not supported when exact is true", [{ field: "numCandidates", reason: "ANN-only option" }]);
+    }
+  } else {
+    assertPositiveInteger(options.numCandidates, "numCandidates");
+    if (options.numCandidates < options.limit) {
+      throw createError(ErrorCodes.INVALID_VECTOR_SEARCH, "numCandidates must be greater than or equal to limit", [{ field: "numCandidates", reason: "must be greater than or equal to limit" }]);
+    }
+  }
+  const vectorSearchStage = {
+    index: options.index.trim(),
+    path: options.path.trim(),
+    queryVector: [...options.queryVector],
+    limit: options.limit,
+    ...isExactSearch ? { exact: true } : { numCandidates: options.numCandidates },
+    ...options.filter === void 0 ? {} : { filter: options.filter }
+  };
+  const projection = normalizeVectorProjection(options.projection);
+  const scoreStage = projection ? {
+    $project: {
+      ...projection,
+      [VECTOR_SEARCH_SCORE_FIELD]: { $meta: "vectorSearchScore" }
+    }
+  } : {
+    $set: {
+      [VECTOR_SEARCH_SCORE_FIELD]: { $meta: "vectorSearchScore" }
+    }
+  };
+  return {
+    pipeline: [
+      { $vectorSearch: vectorSearchStage },
+      scoreStage
+    ],
+    aggregateOptions: normalizeAggregateOptions(options.aggregateOptions)
+  };
+}
+function mapVectorSearchRows(rows) {
+  return rows.map((row) => {
+    const score = row[VECTOR_SEARCH_SCORE_FIELD];
+    if (typeof score !== "number" || !Number.isFinite(score)) {
+      throw createError(ErrorCodes.INVALID_OPERATION, "Vector Search result did not contain a finite score");
+    }
+    const document = { ...row };
+    delete document[VECTOR_SEARCH_SCORE_FIELD];
+    return {
+      document,
+      score
+    };
+  });
+}
+
 // src/adapters/mongodb/writes/write-utils.ts
 function sleep2(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
@@ -11633,6 +12256,19 @@ var MongoCollectionAccessor = class {
       } : void 0
     );
   }
+  /** Searches a MongoDB Vector Search index through a constrained aggregate pipeline. */
+  async vectorSearch(options) {
+    const { pipeline, aggregateOptions } = buildVectorSearchPipeline(options);
+    try {
+      const rows = await this.aggregate(
+        pipeline,
+        aggregateOptions
+      );
+      return mapVectorSearchRows(rows);
+    } catch (error) {
+      throw attachVectorSearchOperationContext(error, this.getNamespace());
+    }
+  }
   /** Returns an array of distinct values for the given field key. */
   async distinct(key, query, options) {
     const startTs = Date.now();
@@ -12134,10 +12770,10 @@ function assertCompatPoolExists(poolManager, poolName) {
 function createPoolScope(runtime, poolName) {
   return {
     collection: (name) => runtime.scopedCollection(name, { pool: poolName }),
-    model: (name) => runtime.scopedModel(name, { pool: poolName }),
+    model: (model) => runtime.scopedModel(model, { pool: poolName }),
     use: (dbName) => ({
       collection: (name) => runtime.scopedCollection(name, { pool: poolName, database: dbName }),
-      model: (name) => runtime.scopedModel(name, { pool: poolName, database: dbName })
+      model: (model) => runtime.scopedModel(model, { pool: poolName, database: dbName })
     })
   };
 }
@@ -12167,6 +12803,7 @@ function createCompatModelInstance(config) {
     config.runtime,
     {
       collectionName: config.collectionName,
+      modelName: config.modelName,
       dbName: config.dbName,
       poolName: config.poolName,
       definition: config.definition,
@@ -12204,6 +12841,7 @@ function createRuntimeModelInstance(host, name, scope) {
     host.runtime,
     {
       collectionName: actualCollectionName,
+      modelName: registered.collectionName,
       dbName: databaseName,
       poolName,
       definition: registered.definition,
@@ -16294,7 +16932,7 @@ var MonSQLizeRuntime = class {
     requireCompatDbInstance(this);
     return {
       collection: (collectionName) => this.scopedCollection(collectionName, { database: name }),
-      model: (modelName) => this.scopedModel(modelName, { database: name })
+      model: (model) => this.scopedModel(model, { database: name })
     };
   }
   pool(poolName) {
@@ -16326,7 +16964,8 @@ var MonSQLizeRuntime = class {
     });
   }
   // Model accessors ---------------------------------------------------------
-  scopedModel(name, options = {}) {
+  scopedModel(model, options = {}) {
+    const name = typeof model === "string" ? model : model.collectionName;
     const dbInstance = requireCompatDbInstance(this);
     if (this._client) {
       return this.createModelInstance(name, options);
@@ -16343,13 +16982,15 @@ var MonSQLizeRuntime = class {
       collection,
       runtime: this,
       collectionName: actualCollectionName,
+      modelName: registered.collectionName,
       dbName: database ?? getRuntimeDatabaseName(this),
       poolName: pool,
       definition: registered.definition,
       schemaEngine: this._schemaDslEngine
     });
   }
-  model(name) {
+  model(model) {
+    const name = typeof model === "string" ? model : model.collectionName;
     if (this._client) {
       this.ensureConnected();
       return this.createModelInstance(name, {
@@ -16375,6 +17016,7 @@ var MonSQLizeRuntime = class {
       collection,
       runtime: this,
       collectionName: actualCollectionName,
+      modelName: registered.collectionName,
       dbName: getRuntimeDatabaseName(this),
       definition: registered.definition,
       schemaEngine: this._schemaDslEngine
@@ -18149,6 +18791,7 @@ MonSQLize.PoolSelector = PoolSelector;
 MonSQLize.PoolStats = PoolStatsManager;
 MonSQLize.validatePoolConfig = validatePoolConfig;
 MonSQLize.validatePoolConfigSafe = validatePoolConfigSafe;
+MonSQLize.defineModel = defineModel;
 MonSQLize.Model = Model;
 MonSQLize.ModelInstance = ModelInstance;
 MonSQLize.expr = expr;
@@ -18238,6 +18881,7 @@ export {
   dataTasks,
   decodeCursor2 as decodeCursor,
   index_default as default,
+  defineModel,
   encodeCursor2 as encodeCursor,
   expr,
   generateQueryHash,