monsqlize 2.0.3 → 2.0.4

package/CHANGELOG.md

@@ -1,7 +1,7 @@
 # CHANGELOG
 
-> Summary index — current release details are packaged in [changelogs/v2.0.3.md](./changelogs/v2.0.3.md); historical details live in the repository changelog archive.
-> **Last updated**: 2026-06-11
+> Summary index — current release details are packaged in [changelogs/v2.0.4.md](./changelogs/v2.0.4.md); historical details live in the repository changelog archive.
+> **Last updated**: 2026-06-12
 
 ---
 
@@ -9,6 +9,7 @@
 
 | Version | Date | Summary | Details |
 |---------|------|---------|---------|
+| [v2.0.4](./changelogs/v2.0.4.md) | 2026-06-12 | Patch: production-safe Model index rollout controls, `schema-dsl@2.0.9`, capability-index wording cleanup, and documentation home refinements | [View](./changelogs/v2.0.4.md) |
 | [v2.0.3](./changelogs/v2.0.3.md) | 2026-06-11 | Patch: v1 compatibility fixes, public stats APIs, standalone docs-site link safety, bilingual docs consistency, and release preflight alignment | [View](./changelogs/v2.0.3.md) |
 | [v2.0.2](./changelogs/v2.0.2.md) | 2026-06-09 | Patch: direct runtime, optional and development dependencies pinned to exact versions for deterministic consumer installs | [View](./changelogs/v2.0.2.md) |
 | [v2.0.1](./changelogs/v2.0.1.md) | 2026-06-03 | Patch: model collection/pool compatibility, automatic-index task dedupe, runtime cache/pool v1 smooth-upgrade fixes, and current docs/types alignment | [View](./changelogs/v2.0.1.md) |
@@ -446,7 +447,8 @@ const result = await msq.collection('orders').insertOne(dataFromMongoose);
 changelogs/
 ├── README.md          # 变更文档说明
 ├── TEMPLATE.md        # 变更文档模板
-├── v2.0.3.md         # 当前发布详细变更
+├── v2.0.4.md         # 当前发布详细变更
+├── v2.0.3.md         # v2.0.3 详细变更
 ├── v2.0.2.md         # v2.0.2 详细变更
 ├── v2.0.1.md         # v2.0.1 详细变更
 ├── v2.0.0.md         # v2 TypeScript 重写发布详细变更
@@ -500,7 +502,8 @@ changelogs/
 
 ## 相关文档
 
-- [changelogs/v2.0.3.md](./changelogs/v2.0.3.md) - 当前发布详细变更文档
+- [changelogs/v2.0.4.md](./changelogs/v2.0.4.md) - 当前发布详细变更文档
+- [changelogs/v2.0.3.md](./changelogs/v2.0.3.md) - v2.0.3 详细变更文档
 - [changelogs/v2.0.2.md](./changelogs/v2.0.2.md) - v2.0.2 详细变更文档
 - [changelogs/v2.0.1.md](./changelogs/v2.0.1.md) - v2.0.1 详细变更文档
 - [README.md](./README.md) - 项目说明
@@ -508,5 +511,5 @@ changelogs/
 
 ---
 
-**最后更新**: 2026-06-11
+**最后更新**: 2026-06-12
 

package/README.md

@@ -7,6 +7,8 @@ TypeScript-native MongoDB ODM and enhancement layer with v1-compatible APIs, mul
 [![MongoDB](https://img.shields.io/badge/MongoDB-6.x%20%2F%207.x-green.svg)](https://www.mongodb.com/)
 [![Node.js](https://img.shields.io/badge/Node.js-18%2B-brightgreen)](https://nodejs.org/)
 
+Documentation: [English](https://vextjs.github.io/monSQLize/) · [简体中文](https://vextjs.github.io/monSQLize/zh/)
+
 ```bash
 npm install monsqlize
 ```
@@ -37,7 +39,7 @@ monSQLize keeps the MongoDB driver mental model while adding the production feat
 
 - Drop-in collection helpers that preserve MongoDB-style CRUD, aggregation, indexes, transactions, and Change Streams.
 - Smart caching through `cache-hub`, including local memory caching, optional Redis-backed L2 caching, automatic invalidation, and function-level caching.
-- A lightweight Model layer with `schema-dsl` validation, hooks, relations, populate, custom methods, timestamps, soft delete, and optimistic locking.
+- A lightweight Model layer with `schema-dsl` validation, hooks, relations, populate, custom methods, timestamps, soft delete, optimistic locking, and production-safe index preflight.
 - Multi-connection-pool support, pool health checks, pool-scoped collections/models, and fallback strategies.
 - Business locks and distributed locks for multi-instance deployments.
 - Saga orchestration for multi-step business workflows.
@@ -251,6 +253,27 @@ module.exports = {
 
 Relative model paths are resolved from `process.cwd()`. In production services, prefer absolute paths such as `path.join(__dirname, 'models')`.
 
+### Production Model Index Rollout
+
+Model-declared indexes are still created automatically by default for backward compatibility. Production services can turn off automatic indexing and run an explicit preflight before creating missing indexes:
+
+```js
+const db = new MonSQLize({
+  type: 'mongodb',
+  databaseName: 'mydb',
+  config: { uri: 'mongodb://localhost:27017' },
+  autoIndex: false
+});
+
+const plan = await db.ensureModelIndexes({ models: ['users'], dryRun: true });
+
+if (plan.totals.conflicts === 0) {
+  await db.ensureModelIndexes({ models: ['users'], throwOnError: true });
+}
+```
+
+`ensureModelIndexes()` creates only missing indexes. It does not drop, rename, or rebuild conflicting indexes.
+
 ### Populate
 
 ```js
@@ -443,6 +466,7 @@ See the current support and verification documents:
 
 Current TypeScript documentation and examples are the source of truth for the v2 package:
 
+- Complete docs: [English](https://vextjs.github.io/monSQLize/) · [简体中文](https://vextjs.github.io/monSQLize/zh/)
 - `docs/en/**` - default English documentation.
 - `docs/zh/**` - Simplified Chinese documentation.
 - `docs/en/recipes.md` / `docs/zh/recipes.md` - shortest copy-ready paths for common setup scenarios.
@@ -494,7 +518,7 @@ npm run test:real-env:private
 
 ## Release Status
 
-The current published release is `v2.0.3`.
+The current published release is `v2.0.4`.
 
 Key release-readiness points:
 
@@ -502,11 +526,17 @@ Key release-readiness points:
 - Package exports are consolidated under `dist/cjs`, `dist/esm`, and `dist/types`.
 - npm packages include the runtime bundles and declaration files only; source maps are disabled by default and can be generated locally with `MONSQLIZE_BUILD_SOURCEMAPS=1 npm run build`.
 - v1 smooth-upgrade compatibility has been validated against the target workspace consumers.
-- `schema-dsl` follows the npm `latest` TypeScript line `schema-dsl@2.0.8`; deprecated `2.3.x` mistake releases are intentionally excluded.
+- `schema-dsl` follows the npm `latest` TypeScript line `schema-dsl@2.0.9`; deprecated `2.3.x` mistake releases are intentionally excluded.
 - GitHub Actions publishes to npm from `v*` tags after running `npm run release:preflight`; the publish step skips duplicate lifecycle scripts because the gate already ran in the same job.
 
 ## Roadmap
 
+### v2.0.4
+
+- Production-safe Model index rollout controls with `autoIndex`, dry-run preflight, conflict reporting, and explicit `ensureIndexes()` / `ensureModelIndexes()` APIs.
+- `schema-dsl` updated to `2.0.9`, with transitive `cache-hub` aligned to `2.2.4`.
+- User-facing capability and verification documentation wording cleaned up, plus documentation home experience refinements.
+
 ### v2.0.3
 
 - v1 compatibility patch for documented `findPage({ cache })` behavior.

package/changelogs/v2.0.4.md

@@ -0,0 +1,61 @@
+# v2.0.4 — 2026-06-12
+
+## Overview
+
+v2.0.4 is a production-safety and documentation-quality patch. It keeps the public API backward compatible while adding explicit Model index rollout controls, updating the schema validation dependency, and refining user-facing documentation language.
+
+---
+
+## Runtime Fixes
+
+- Added production-safe Model index controls:
+  - runtime-level and model-level `autoIndex` options.
+  - explicit `ModelInstance.ensureIndexes()` and `MonSQLize.ensureModelIndexes()` APIs.
+  - dry-run index preflight with `existing`, `missing`, `conflicts`, and `failed` classification.
+  - missing-index creation without dropping, renaming, or rebuilding conflicting indexes.
+  - `model-index-error` events for observable automatic-index creation failures.
+- Kept automatic Model indexing enabled by default for backward compatibility.
+- Moved runtime Model index aggregation into the Model runtime helper layer so the strict source-size gate remains clean.
+
+## Dependencies
+
+- Updated `schema-dsl` from `2.0.8` to npm `latest` `2.0.9`.
+- Confirmed `schema-dsl@2.0.9` keeps the required `dsl()` and `validate()` runtime paths compatible with monSQLize.
+- Confirmed the `schema-dsl` transitive `cache-hub` dependency now resolves to `2.2.4`, matching the root direct dependency.
+
+## Documentation
+
+- Documented the recommended production index rollout flow:
+  - set `autoIndex: false` in production services.
+  - run `ensureIndexes({ dryRun: true })` / `ensureModelIndexes({ dryRun: true })`.
+  - create only missing indexes during a low-traffic maintenance window.
+  - monitor TTL and index-build behavior.
+- Corrected create-index documentation to distinguish local `INVALID_ARGUMENT` validation from raw MongoDB driver/server index conflicts.
+- Reworded capability-index and verification-entry documentation to use user-facing availability and verification language instead of internal migration status terms.
+- Refined the documentation home experience with the VextJS-style footer, aligned hero/feature layout, and updated hero data-flow visual.
+
+---
+
+## Compatibility
+
+- SemVer: patch release.
+- Breaking changes: none.
+- Existing v2 imports remain under `dist/cjs`, `dist/esm`, and `dist/types`.
+- Existing default automatic Model indexing behavior remains enabled unless users opt into the new production-safe controls.
+
+---
+
+## Validation
+
+- `npm run lint`
+- `npm run check:docs-examples`
+- `npm run type-check`
+- targeted Model/index unit and integration tests
+- `npm run test:examples`
+- `npm --prefix website run build`
+- `npm run verify:fast`
+- `npm run test:server-matrix`
+- `npm run test:audit`
+- `git diff --check`
+
+Full release validation is handled by `npm run release:preflight`, `npm pack --dry-run`, `npm publish --dry-run`, and pack install smoke before publishing.

package/dist/cjs/index.cjs

@@ -997,6 +997,75 @@ function stableIndexStringify(value) {
   }
   return JSON.stringify(value) ?? "undefined";
 }
+function getIndexOptionName(options) {
+  return typeof options.name === "string" && options.name.length > 0 ? options.name : void 0;
+}
+function summarizeIndexError(error) {
+  if (error instanceof Error) {
+    const record = error;
+    return {
+      name: error.name,
+      message: error.message,
+      code: record.code ?? record.codeName
+    };
+  }
+  return {
+    message: String(error)
+  };
+}
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function getExistingIndexKey(index) {
+  return index.key;
+}
+function declaredOptionEntries(options) {
+  return Object.entries(options).filter(([name, value]) => {
+    if (value === void 0) return false;
+    if (name === "background") return false;
+    return true;
+  });
+}
+function indexOptionsMatch(existing, declared) {
+  if (stableIndexStringify(getExistingIndexKey(existing)) !== stableIndexStringify(declared.key)) {
+    return false;
+  }
+  for (const [name, value] of declaredOptionEntries(declared.options)) {
+    const existingValue = existing[name];
+    if (value === false && existingValue === void 0) {
+      continue;
+    }
+    if (stableIndexStringify(existingValue) !== stableIndexStringify(value)) {
+      return false;
+    }
+  }
+  return true;
+}
+function findExistingIndexByName(existingIndexes, name) {
+  if (!name) return void 0;
+  return existingIndexes.find((index) => index.name === name);
+}
+function findExistingIndexByKey(existingIndexes, key) {
+  const fingerprint = stableIndexStringify(key);
+  return existingIndexes.find((index) => stableIndexStringify(getExistingIndexKey(index)) === fingerprint);
+}
+function createIndexEnsureError(message, result, cause) {
+  return createError(ErrorCodes.MONGODB_ERROR, message, [result], cause);
+}
+function resolveModelAutoIndexOptions(definition, runtimeAutoIndex) {
+  const modelAutoIndex = toCompatDefinition(definition).options?.autoIndex;
+  const value = modelAutoIndex ?? runtimeAutoIndex;
+  if (value === false) {
+    return { enabled: false, emitEvents: true };
+  }
+  if (value && typeof value === "object") {
+    return {
+      enabled: value.enabled !== false,
+      emitEvents: value.emitEvents !== false
+    };
+  }
+  return { enabled: true, emitEvents: true };
+}
 function getIndexTaskRegistry(runtime) {
   if (!runtime) {
     return fallbackModelIndexTasks;
@@ -1024,6 +1093,20 @@ function resolveIndexTaskScope(collection, options) {
     };
   }
 }
+function toIndexNamespace(scope) {
+  return {
+    db: scope.dbName,
+    collection: scope.collectionName,
+    poolName: scope.poolName
+  };
+}
+function emitIndexFailure(runtime, payload, emitEvents) {
+  if (!emitEvents) {
+    return;
+  }
+  const emitter = runtime;
+  emitter?.emit?.("model-index-error", payload);
+}
 function warnIndexFailure(runtime, taskKey, error) {
   const logger = runtime;
   logger?.logger?.warn?.("[MonSQLize] model index creation failed", {
@@ -1031,9 +1114,10 @@ function warnIndexFailure(runtime, taskKey, error) {
     error: error instanceof Error ? error.message : String(error)
   });
 }
-function scheduleIndexTask(collection, key, indexOptions, options) {
+function scheduleIndexTask(collection, declaredIndex, emitEvents, options) {
   const scope = resolveIndexTaskScope(collection, options);
-  const indexFingerprint = stableIndexStringify({ key, options: indexOptions });
+  const { key, options: indexOptions } = declaredIndex;
+  const indexFingerprint = declaredIndex.fingerprint;
   const taskKey = `${scope.poolName}:${scope.dbName}:${scope.collectionName}:${indexFingerprint}`;
   const registry = getIndexTaskRegistry(options?.runtime);
   const existing = registry.get(taskKey);
@@ -1051,6 +1135,14 @@ function scheduleIndexTask(collection, key, indexOptions, options) {
           task.status = "failed";
           task.error = error;
           warnIndexFailure(options?.runtime, taskKey, error);
+          emitIndexFailure(options?.runtime, {
+            namespace: scope,
+            taskKey,
+            source: declaredIndex.source,
+            key,
+            options: indexOptions,
+            error: summarizeIndexError(error)
+          }, emitEvents);
           resolve();
         });
       });
@@ -1167,6 +1259,134 @@ function resolveModelHooksFactory(definition) {
   const hooks = toCompatDefinition(definition).hooks;
   return typeof hooks === "function" ? hooks : null;
 }
+function collectModelIndexDefinitions(definition, softDeleteConfig) {
+  const declared = [];
+  if (softDeleteConfig?.enabled && softDeleteConfig.type === "timestamp" && softDeleteConfig.ttl) {
+    const key = { [softDeleteConfig.field]: 1 };
+    const options = { expireAfterSeconds: softDeleteConfig.ttl };
+    declared.push({
+      source: "softDelete",
+      key,
+      options,
+      name: getIndexOptionName(options),
+      fingerprint: stableIndexStringify({ key, options })
+    });
+  }
+  const indexes = toCompatDefinition(definition).indexes;
+  if (!Array.isArray(indexes) || indexes.length === 0) {
+    return declared;
+  }
+  for (const indexSpec of indexes) {
+    if (!isRecord(indexSpec) || !indexSpec.key) {
+      continue;
+    }
+    const { key, ...indexOptions } = indexSpec;
+    declared.push({
+      source: "definition",
+      key,
+      options: indexOptions,
+      name: getIndexOptionName(indexOptions),
+      fingerprint: stableIndexStringify({ key, options: indexOptions })
+    });
+  }
+  return declared;
+}
+async function ensureModelIndexesForCollection(collection, definition, softDeleteConfig, options = {}) {
+  const namespace = toIndexNamespace(resolveIndexTaskScope(collection, options));
+  const declared = collectModelIndexDefinitions(definition, softDeleteConfig);
+  const existingIndexes = await collection.listIndexes();
+  const existing = [];
+  const missing = [];
+  const conflicts = [];
+  for (const declaredIndex of declared) {
+    const existingByName = findExistingIndexByName(existingIndexes, declaredIndex.name);
+    if (existingByName) {
+      if (indexOptionsMatch(existingByName, declaredIndex)) {
+        existing.push({ declared: declaredIndex, existing: existingByName });
+      } else {
+        conflicts.push({
+          declared: declaredIndex,
+          existing: existingByName,
+          reason: "name-conflict"
+        });
+      }
+      continue;
+    }
+    const existingByKey = findExistingIndexByKey(existingIndexes, declaredIndex.key);
+    if (existingByKey) {
+      if (indexOptionsMatch(existingByKey, declaredIndex)) {
+        existing.push({ declared: declaredIndex, existing: existingByKey });
+      } else {
+        conflicts.push({
+          declared: declaredIndex,
+          existing: existingByKey,
+          reason: "options-conflict"
+        });
+      }
+      continue;
+    }
+    missing.push(declaredIndex);
+  }
+  const result = {
+    dryRun: options.dryRun === true,
+    namespace,
+    declared,
+    existing,
+    missing,
+    created: [],
+    conflicts,
+    failed: [],
+    skipped: options.dryRun === true ? missing.map((declaredIndex) => ({ declared: declaredIndex, reason: "dry-run" })) : conflicts.map((conflict) => ({ declared: conflict.declared, reason: conflict.reason }))
+  };
+  if (conflicts.length > 0 && options.throwOnError) {
+    throw createIndexEnsureError("Model index conflicts detected.", result);
+  }
+  if (options.dryRun === true) {
+    return result;
+  }
+  for (const declaredIndex of missing) {
+    try {
+      const createdName = await collection.createIndex(declaredIndex.key, declaredIndex.options);
+      result.created.push({
+        declared: declaredIndex,
+        name: typeof createdName === "string" ? createdName : void 0,
+        result: createdName
+      });
+    } catch (error) {
+      result.failed.push({
+        declared: declaredIndex,
+        error: summarizeIndexError(error)
+      });
+      if (options.throwOnError) {
+        throw createIndexEnsureError(
+          "Model index creation failed.",
+          result,
+          error instanceof Error ? error : void 0
+        );
+      }
+    }
+  }
+  return result;
+}
+function summarizeModelIndexEnsureResults(results) {
+  return results.reduce((totals, result) => ({
+    declared: totals.declared + result.declared.length,
+    existing: totals.existing + result.existing.length,
+    missing: totals.missing + result.missing.length,
+    created: totals.created + result.created.length,
+    conflicts: totals.conflicts + result.conflicts.length,
+    failed: totals.failed + result.failed.length,
+    skipped: totals.skipped + result.skipped.length
+  }), {
+    declared: 0,
+    existing: 0,
+    missing: 0,
+    created: 0,
+    conflicts: 0,
+    failed: 0,
+    skipped: 0
+  });
+}
 function initializeModelV1Methods(target, definition) {
   const methods = toCompatDefinition(definition).methods;
   if (typeof methods !== "function") {
@@ -1191,25 +1411,12 @@ function initializeModelV1Methods(target, definition) {
   }
 }
 function scheduleModelIndexes(collection, definition, softDeleteConfig, options) {
-  if (softDeleteConfig?.enabled && softDeleteConfig.type === "timestamp" && softDeleteConfig.ttl) {
-    const softDeleteIndex = softDeleteConfig;
-    scheduleIndexTask(
-      collection,
-      { [softDeleteIndex.field]: 1 },
-      { expireAfterSeconds: softDeleteIndex.ttl },
-      options
-    );
-  }
-  const indexes = toCompatDefinition(definition).indexes;
-  if (!Array.isArray(indexes) || indexes.length === 0) {
+  const autoIndex = resolveModelAutoIndexOptions(definition, options?.autoIndex);
+  if (!autoIndex.enabled) {
     return;
   }
-  for (const indexSpec of indexes) {
-    if (!indexSpec?.key) {
-      continue;
-    }
-    const { key, ...indexOptions } = indexSpec;
-    scheduleIndexTask(collection, key, indexOptions, options);
+  for (const declaredIndex of collectModelIndexDefinitions(definition, softDeleteConfig)) {
+    scheduleIndexTask(collection, declaredIndex, autoIndex.emitEvents, options);
   }
 }
 
@@ -1777,7 +1984,8 @@ var ModelInstance = class {
       runtime: this.runtime,
       dbName: options.dbName,
       poolName: options.poolName,
-      collectionName: options.collectionName
+      collectionName: options.collectionName,
+      autoIndex: this.runtime.options?.autoIndex
     });
     this._v1InstanceMethods = initializeModelV1Methods(this, options.definition);
   }
@@ -1981,6 +2189,15 @@ var ModelInstance = class {
   listIndexes() {
     return this.collection.listIndexes();
   }
+  ensureIndexes(options = {}) {
+    return ensureModelIndexesForCollection(this.collection, this.definition, this._softDeleteConfig, {
+      ...options,
+      runtime: this.runtime,
+      dbName: this.dbName,
+      poolName: this.poolName,
+      collectionName: this.collectionName
+    });
+  }
   dropIndex(name) {
     return this.collection.dropIndex(name);
   }
@@ -8079,6 +8296,26 @@ function createRuntimeModelInstance(host, name, scope) {
   });
   return instance;
 }
+async function ensureRuntimeModelIndexes(host, options = {}) {
+  const modelNames = options.models ?? Model.list();
+  const models = [];
+  for (const name of modelNames) {
+    const model = host.scopedModel(name, {
+      database: options.database,
+      pool: options.pool
+    });
+    const result = await model.ensureIndexes({
+      dryRun: options.dryRun,
+      throwOnError: options.throwOnError
+    });
+    models.push({ name, result });
+  }
+  return {
+    dryRun: options.dryRun === true,
+    models,
+    totals: summarizeModelIndexEnsureResults(models.map((item) => item.result))
+  };
+}
 
 // src/entry/runtime-core-hosts.ts
 function resolveAdapterCache(state) {
@@ -10787,7 +11024,8 @@ var MonSQLizeRuntime = class {
       namespace: d.namespace,
       log: d.log,
       countQueue: this.options.countQueue,
-      models: this.options.models
+      models: this.options.models,
+      autoIndex: this.options.autoIndex
     };
   }
   async close() {
@@ -10984,6 +11222,10 @@ var MonSQLizeRuntime = class {
     cache.set(name, instance);
     return instance;
   }
+  async ensureModelIndexes(options = {}) {
+    this.ensureConnected();
+    return ensureRuntimeModelIndexes(this, options);
+  }
   // Capability delegation ----------------------------------------------------
   async startSession(options = {}) {
     this.ensureConnected();

package/dist/esm/index.mjs

@@ -980,6 +980,75 @@ function stableIndexStringify(value) {
   }
   return JSON.stringify(value) ?? "undefined";
 }
+function getIndexOptionName(options) {
+  return typeof options.name === "string" && options.name.length > 0 ? options.name : void 0;
+}
+function summarizeIndexError(error) {
+  if (error instanceof Error) {
+    const record = error;
+    return {
+      name: error.name,
+      message: error.message,
+      code: record.code ?? record.codeName
+    };
+  }
+  return {
+    message: String(error)
+  };
+}
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function getExistingIndexKey(index) {
+  return index.key;
+}
+function declaredOptionEntries(options) {
+  return Object.entries(options).filter(([name, value]) => {
+    if (value === void 0) return false;
+    if (name === "background") return false;
+    return true;
+  });
+}
+function indexOptionsMatch(existing, declared) {
+  if (stableIndexStringify(getExistingIndexKey(existing)) !== stableIndexStringify(declared.key)) {
+    return false;
+  }
+  for (const [name, value] of declaredOptionEntries(declared.options)) {
+    const existingValue = existing[name];
+    if (value === false && existingValue === void 0) {
+      continue;
+    }
+    if (stableIndexStringify(existingValue) !== stableIndexStringify(value)) {
+      return false;
+    }
+  }
+  return true;
+}
+function findExistingIndexByName(existingIndexes, name) {
+  if (!name) return void 0;
+  return existingIndexes.find((index) => index.name === name);
+}
+function findExistingIndexByKey(existingIndexes, key) {
+  const fingerprint = stableIndexStringify(key);
+  return existingIndexes.find((index) => stableIndexStringify(getExistingIndexKey(index)) === fingerprint);
+}
+function createIndexEnsureError(message, result, cause) {
+  return createError(ErrorCodes.MONGODB_ERROR, message, [result], cause);
+}
+function resolveModelAutoIndexOptions(definition, runtimeAutoIndex) {
+  const modelAutoIndex = toCompatDefinition(definition).options?.autoIndex;
+  const value = modelAutoIndex ?? runtimeAutoIndex;
+  if (value === false) {
+    return { enabled: false, emitEvents: true };
+  }
+  if (value && typeof value === "object") {
+    return {
+      enabled: value.enabled !== false,
+      emitEvents: value.emitEvents !== false
+    };
+  }
+  return { enabled: true, emitEvents: true };
+}
 function getIndexTaskRegistry(runtime) {
   if (!runtime) {
     return fallbackModelIndexTasks;
@@ -1007,6 +1076,20 @@ function resolveIndexTaskScope(collection, options) {
     };
   }
 }
+function toIndexNamespace(scope) {
+  return {
+    db: scope.dbName,
+    collection: scope.collectionName,
+    poolName: scope.poolName
+  };
+}
+function emitIndexFailure(runtime, payload, emitEvents) {
+  if (!emitEvents) {
+    return;
+  }
+  const emitter = runtime;
+  emitter?.emit?.("model-index-error", payload);
+}
 function warnIndexFailure(runtime, taskKey, error) {
   const logger = runtime;
   logger?.logger?.warn?.("[MonSQLize] model index creation failed", {
@@ -1014,9 +1097,10 @@ function warnIndexFailure(runtime, taskKey, error) {
     error: error instanceof Error ? error.message : String(error)
   });
 }
-function scheduleIndexTask(collection, key, indexOptions, options) {
+function scheduleIndexTask(collection, declaredIndex, emitEvents, options) {
   const scope = resolveIndexTaskScope(collection, options);
-  const indexFingerprint = stableIndexStringify({ key, options: indexOptions });
+  const { key, options: indexOptions } = declaredIndex;
+  const indexFingerprint = declaredIndex.fingerprint;
   const taskKey = `${scope.poolName}:${scope.dbName}:${scope.collectionName}:${indexFingerprint}`;
   const registry = getIndexTaskRegistry(options?.runtime);
   const existing = registry.get(taskKey);
@@ -1034,6 +1118,14 @@ function scheduleIndexTask(collection, key, indexOptions, options) {
           task.status = "failed";
           task.error = error;
           warnIndexFailure(options?.runtime, taskKey, error);
+          emitIndexFailure(options?.runtime, {
+            namespace: scope,
+            taskKey,
+            source: declaredIndex.source,
+            key,
+            options: indexOptions,
+            error: summarizeIndexError(error)
+          }, emitEvents);
           resolve();
         });
       });
@@ -1150,6 +1242,134 @@ function resolveModelHooksFactory(definition) {
   const hooks = toCompatDefinition(definition).hooks;
   return typeof hooks === "function" ? hooks : null;
 }
+function collectModelIndexDefinitions(definition, softDeleteConfig) {
+  const declared = [];
+  if (softDeleteConfig?.enabled && softDeleteConfig.type === "timestamp" && softDeleteConfig.ttl) {
+    const key = { [softDeleteConfig.field]: 1 };
+    const options = { expireAfterSeconds: softDeleteConfig.ttl };
+    declared.push({
+      source: "softDelete",
+      key,
+      options,
+      name: getIndexOptionName(options),
+      fingerprint: stableIndexStringify({ key, options })
+    });
+  }
+  const indexes = toCompatDefinition(definition).indexes;
+  if (!Array.isArray(indexes) || indexes.length === 0) {
+    return declared;
+  }
+  for (const indexSpec of indexes) {
+    if (!isRecord(indexSpec) || !indexSpec.key) {
+      continue;
+    }
+    const { key, ...indexOptions } = indexSpec;
+    declared.push({
+      source: "definition",
+      key,
+      options: indexOptions,
+      name: getIndexOptionName(indexOptions),
+      fingerprint: stableIndexStringify({ key, options: indexOptions })
+    });
+  }
+  return declared;
+}
+async function ensureModelIndexesForCollection(collection, definition, softDeleteConfig, options = {}) {
+  const namespace = toIndexNamespace(resolveIndexTaskScope(collection, options));
+  const declared = collectModelIndexDefinitions(definition, softDeleteConfig);
+  const existingIndexes = await collection.listIndexes();
+  const existing = [];
+  const missing = [];
+  const conflicts = [];
+  for (const declaredIndex of declared) {
+    const existingByName = findExistingIndexByName(existingIndexes, declaredIndex.name);
+    if (existingByName) {
+      if (indexOptionsMatch(existingByName, declaredIndex)) {
+        existing.push({ declared: declaredIndex, existing: existingByName });
+      } else {
+        conflicts.push({
+          declared: declaredIndex,
+          existing: existingByName,
+          reason: "name-conflict"
+        });
+      }
+      continue;
+    }
+    const existingByKey = findExistingIndexByKey(existingIndexes, declaredIndex.key);
+    if (existingByKey) {
+      if (indexOptionsMatch(existingByKey, declaredIndex)) {
+        existing.push({ declared: declaredIndex, existing: existingByKey });
+      } else {
+        conflicts.push({
+          declared: declaredIndex,
+          existing: existingByKey,
+          reason: "options-conflict"
+        });
+      }
+      continue;
+    }
+    missing.push(declaredIndex);
+  }
+  const result = {
+    dryRun: options.dryRun === true,
+    namespace,
+    declared,
+    existing,
+    missing,
+    created: [],
+    conflicts,
+    failed: [],
+    skipped: options.dryRun === true ? missing.map((declaredIndex) => ({ declared: declaredIndex, reason: "dry-run" })) : conflicts.map((conflict) => ({ declared: conflict.declared, reason: conflict.reason }))
+  };
+  if (conflicts.length > 0 && options.throwOnError) {
+    throw createIndexEnsureError("Model index conflicts detected.", result);
+  }
+  if (options.dryRun === true) {
+    return result;
+  }
+  for (const declaredIndex of missing) {
+    try {
+      const createdName = await collection.createIndex(declaredIndex.key, declaredIndex.options);
+      result.created.push({
+        declared: declaredIndex,
+        name: typeof createdName === "string" ? createdName : void 0,
+        result: createdName
+      });
+    } catch (error) {
+      result.failed.push({
+        declared: declaredIndex,
+        error: summarizeIndexError(error)
+      });
+      if (options.throwOnError) {
+        throw createIndexEnsureError(
+          "Model index creation failed.",
+          result,
+          error instanceof Error ? error : void 0
+        );
+      }
+    }
+  }
+  return result;
+}
+function summarizeModelIndexEnsureResults(results) {
+  return results.reduce((totals, result) => ({
+    declared: totals.declared + result.declared.length,
+    existing: totals.existing + result.existing.length,
+    missing: totals.missing + result.missing.length,
+    created: totals.created + result.created.length,
+    conflicts: totals.conflicts + result.conflicts.length,
+    failed: totals.failed + result.failed.length,
+    skipped: totals.skipped + result.skipped.length
+  }), {
+    declared: 0,
+    existing: 0,
+    missing: 0,
+    created: 0,
+    conflicts: 0,
+    failed: 0,
+    skipped: 0
+  });
+}
 function initializeModelV1Methods(target, definition) {
   const methods = toCompatDefinition(definition).methods;
   if (typeof methods !== "function") {
@@ -1174,25 +1394,12 @@ function initializeModelV1Methods(target, definition) {
   }
 }
 function scheduleModelIndexes(collection, definition, softDeleteConfig, options) {
-  if (softDeleteConfig?.enabled && softDeleteConfig.type === "timestamp" && softDeleteConfig.ttl) {
-    const softDeleteIndex = softDeleteConfig;
-    scheduleIndexTask(
-      collection,
-      { [softDeleteIndex.field]: 1 },
-      { expireAfterSeconds: softDeleteIndex.ttl },
-      options
-    );
-  }
-  const indexes = toCompatDefinition(definition).indexes;
-  if (!Array.isArray(indexes) || indexes.length === 0) {
+  const autoIndex = resolveModelAutoIndexOptions(definition, options?.autoIndex);
+  if (!autoIndex.enabled) {
     return;
   }
-  for (const indexSpec of indexes) {
-    if (!indexSpec?.key) {
-      continue;
-    }
-    const { key, ...indexOptions } = indexSpec;
-    scheduleIndexTask(collection, key, indexOptions, options);
+  for (const declaredIndex of collectModelIndexDefinitions(definition, softDeleteConfig)) {
+    scheduleIndexTask(collection, declaredIndex, autoIndex.emitEvents, options);
   }
 }
 
@@ -1760,7 +1967,8 @@ var ModelInstance = class {
       runtime: this.runtime,
       dbName: options.dbName,
       poolName: options.poolName,
-      collectionName: options.collectionName
+      collectionName: options.collectionName,
+      autoIndex: this.runtime.options?.autoIndex
     });
     this._v1InstanceMethods = initializeModelV1Methods(this, options.definition);
   }
@@ -1964,6 +2172,15 @@ var ModelInstance = class {
   listIndexes() {
     return this.collection.listIndexes();
   }
+  ensureIndexes(options = {}) {
+    return ensureModelIndexesForCollection(this.collection, this.definition, this._softDeleteConfig, {
+      ...options,
+      runtime: this.runtime,
+      dbName: this.dbName,
+      poolName: this.poolName,
+      collectionName: this.collectionName
+    });
+  }
   dropIndex(name) {
     return this.collection.dropIndex(name);
   }
@@ -8062,6 +8279,26 @@ function createRuntimeModelInstance(host, name, scope) {
   });
   return instance;
 }
+async function ensureRuntimeModelIndexes(host, options = {}) {
+  const modelNames = options.models ?? Model.list();
+  const models = [];
+  for (const name of modelNames) {
+    const model = host.scopedModel(name, {
+      database: options.database,
+      pool: options.pool
+    });
+    const result = await model.ensureIndexes({
+      dryRun: options.dryRun,
+      throwOnError: options.throwOnError
+    });
+    models.push({ name, result });
+  }
+  return {
+    dryRun: options.dryRun === true,
+    models,
+    totals: summarizeModelIndexEnsureResults(models.map((item) => item.result))
+  };
+}
 
 // src/entry/runtime-core-hosts.ts
 function resolveAdapterCache(state) {
@@ -10773,7 +11010,8 @@ var MonSQLizeRuntime = class {
       namespace: d.namespace,
       log: d.log,
       countQueue: this.options.countQueue,
-      models: this.options.models
+      models: this.options.models,
+      autoIndex: this.options.autoIndex
     };
   }
   async close() {
@@ -10970,6 +11208,10 @@ var MonSQLizeRuntime = class {
     cache.set(name, instance);
     return instance;
   }
+  async ensureModelIndexes(options = {}) {
+    this.ensureConnected();
+    return ensureRuntimeModelIndexes(this, options);
+  }
   // Capability delegation ----------------------------------------------------
   async startSession(options = {}) {
     this.ensureConnected();

package/dist/types/model.d.ts

@@ -62,6 +62,104 @@ export interface VirtualConfig {
     set?: (this: Record<string, unknown>, value: unknown) => void;
 }
 
+export type ModelAutoIndexOptions = boolean | {
+    /** Enable automatic model index creation. Defaults to true for backward compatibility. */
+    enabled?: boolean;
+    /** Emit `model-index-error` when automatic index creation fails. Defaults to true. */
+    emitEvents?: boolean;
+};
+
+export type ModelIndexSource = 'definition' | 'softDelete';
+
+export interface ModelDeclaredIndex {
+    source: ModelIndexSource;
+    key: unknown;
+    options: Record<string, unknown>;
+    name?: string;
+    fingerprint: string;
+}
+
+export interface ModelIndexNamespace {
+    db: string;
+    collection: string;
+    poolName: string;
+}
+
+export interface ModelIndexErrorSummary {
+    name?: string;
+    message: string;
+    code?: unknown;
+}
+
+export interface ModelIndexEnsureExisting {
+    declared: ModelDeclaredIndex;
+    existing: Record<string, unknown>;
+}
+
+export interface ModelIndexConflict {
+    declared: ModelDeclaredIndex;
+    existing?: Record<string, unknown>;
+    reason: string;
+}
+
+export interface ModelIndexCreated {
+    declared: ModelDeclaredIndex;
+    name?: string;
+    result?: unknown;
+}
+
+export interface ModelIndexFailure {
+    declared: ModelDeclaredIndex;
+    error: ModelIndexErrorSummary;
+}
+
+export interface ModelIndexSkipped {
+    declared: ModelDeclaredIndex;
+    reason: string;
+}
+
+export interface ModelEnsureIndexesOptions {
+    /** Return the index diff without creating missing indexes. */
+    dryRun?: boolean;
+    /** Throw a MonSQLize `MONGODB_ERROR` when conflicts or creation failures are found. */
+    throwOnError?: boolean;
+}
+
+export interface ModelEnsureAllIndexesOptions extends ModelEnsureIndexesOptions {
+    /** Limit the operation to specific registered model names. Defaults to all models. */
+    models?: string[];
+    /** Optional database scope for models without their own connection override. */
+    database?: string;
+    /** Optional pool scope for models without their own connection override. */
+    pool?: string;
+}
+
+export interface ModelIndexEnsureResult {
+    dryRun: boolean;
+    namespace: ModelIndexNamespace;
+    declared: ModelDeclaredIndex[];
+    existing: ModelIndexEnsureExisting[];
+    missing: ModelDeclaredIndex[];
+    created: ModelIndexCreated[];
+    conflicts: ModelIndexConflict[];
+    failed: ModelIndexFailure[];
+    skipped: ModelIndexSkipped[];
+}
+
+export interface ModelIndexEnsureSummary {
+    dryRun: boolean;
+    models: Array<{ name: string; result: ModelIndexEnsureResult }>;
+    totals: {
+        declared: number;
+        existing: number;
+        missing: number;
+        created: number;
+        conflicts: number;
+        failed: number;
+        skipped: number;
+    };
+}
+
 /** v1 hooks factory format */
 export type V1HooksFactory<TDocument = Record<string, unknown>> = (
     model: ModelInstance<TDocument>,
@@ -95,6 +193,7 @@ export type V1MethodsFactory<TDocument = Record<string, unknown>> = (
 export interface ModelDefinitionOptions {
     timestamps?: boolean | { createdAt?: string | boolean; updatedAt?: string | boolean };
     validate?: boolean;
+    autoIndex?: ModelAutoIndexOptions;
     softDelete?: boolean | {
         enabled?: boolean;
         field?: string;
@@ -443,6 +542,11 @@ export interface ModelInstance<TDocument = any> {
     createIndexes(specs: Array<{ key: unknown; } & Record<string, unknown>>): Promise<string[]>;
     /** Lists all existing index definitions on the collection. */
     listIndexes(): Promise<Record<string, unknown>[]>;
+    /**
+     * Compares declared model indexes with the database and optionally creates missing indexes.
+     * Does not drop, rename, or rebuild conflicting indexes.
+     */
+    ensureIndexes(options?: ModelEnsureIndexesOptions): Promise<ModelIndexEnsureResult>;
     /**
      * Drops the specified index by name.
      * @param name Index name.

package/dist/types/monsqlize.d.ts

@@ -33,7 +33,7 @@ export interface SSHConfig {
 
 import type { Collection, DbAccessor, HealthView } from './collection';
 import type { Lock, LockOptions, LockStats } from './lock';
-import type { ModelInstance } from './model';
+import type { ModelAutoIndexOptions, ModelEnsureAllIndexesOptions, ModelIndexEnsureSummary, ModelInstance } from './model';
 import type { MongoConnectConfig } from './mongodb';
 import type { ConnectionPoolManagerOptions, PoolConfig, PoolHealthStatus, PoolStats, PoolStrategy } from './pool';
 import type {
@@ -176,6 +176,8 @@ export interface MonSQLizeOptions {
     countQueue?: boolean | { enabled?: boolean; concurrency?: number; maxQueueSize?: number; timeout?: number; };
     /** Model definitions to auto-register on connect. Accepts a file path (string) or an object with { path, pattern?, recursive? }. @since v1.3.0 */
     models?: string | { path: string; pattern?: string; recursive?: boolean; };
+    /** Global automatic model index creation control. Defaults to true for backward compatibility. */
+    autoIndex?: ModelAutoIndexOptions;
     /** Auto-invalidate cache on write operations. @since v1.3.0 */
     cacheAutoInvalidate?: boolean;
 }
@@ -256,6 +258,11 @@ export interface MonSQLizeInstance {
      */
     model<TDocument = any>(name: string): ModelInstance<TDocument>;
     model(name: string): ModelInstance<any>;
+    /**
+     * Ensures declared indexes for registered models.
+     * Use `dryRun: true` for production preflight; execution only creates missing indexes.
+     */
+    ensureModelIndexes(options?: ModelEnsureAllIndexesOptions): Promise<ModelIndexEnsureSummary>;
     /**
      * Start a MongoDB transaction session.
      * @param options Optional transaction options.
@@ -442,6 +449,7 @@ export default class MonSQLize implements MonSQLizeInstance {
     scopedModel(name: string, options?: { database?: string; pool?: string; }): ModelInstance<any>;
     model<TDocument = any>(name: string): ModelInstance<TDocument>;
     model(name: string): ModelInstance<any>;
+    ensureModelIndexes(options?: ModelEnsureAllIndexesOptions): Promise<ModelIndexEnsureSummary>;
     startSession(options?: TransactionOptions): Promise<Transaction>;
     withTransaction<T>(callback: (transaction: Transaction) => Promise<T>, options?: TransactionOptions): Promise<T>;
     withLock<T>(key: string, callback: () => Promise<T>, options?: LockOptions): Promise<T>;

package/dist/types/runtime.d.ts

@@ -1,6 +1,6 @@
 import type { BookmarkClearResult, BookmarkListResult, BookmarkPrewarmResult, DeleteBatchResult, DeleteResult, IncrementOneResult, IndexCreateResult, InsertBatchResult, InsertManyResult, UpdateBatchResult, UpdateResult } from './collection';
 import type { LoggerLike, ExpressionFunction, ExpressionObject } from './base';
-import type { ModelDefinition, ModelInstance as ModelInstanceContract, RegisteredModel, RelationConfig } from './model';
+import type { ModelDefinition, ModelEnsureIndexesOptions, ModelIndexEnsureResult, ModelInstance as ModelInstanceContract, RegisteredModel, RelationConfig } from './model';
 import type { LockOptions, LockStats } from './lock';
 import type { ConnectionPoolManagerOptions, FallbackStrategy, PoolConfig, PoolHealthStatus, PoolRole, PoolStats, PoolStrategy } from './pool';
 import type { SagaDefinition, SagaOrchestratorOptions, SagaResult, SagaStats, SagaStep } from './saga';
@@ -335,6 +335,7 @@ export declare class ModelInstance<TDocument = any> implements ModelInstanceCont
     createIndex(keys: unknown, options?: unknown): Promise<IndexCreateResult>;
     createIndexes(specs: Array<{ key: unknown; } & Record<string, unknown>>): Promise<string[]>;
     listIndexes(): Promise<Record<string, unknown>[]>;
+    ensureIndexes(options?: ModelEnsureIndexesOptions): Promise<ModelIndexEnsureResult>;
     dropIndex(name: string): Promise<unknown>;
     dropIndexes(): Promise<unknown>;
     prewarmBookmarks(keyDims?: unknown, pages?: number[]): Promise<BookmarkPrewarmResult>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "monsqlize",
-  "version": "2.0.3",
+  "version": "2.0.4",
   "description": "TypeScript-native MongoDB ODM with multi-level caching (cache-hub), distributed locks, Saga orchestration, unified expression system (122 operators), connection pool management, ChangeStream sync, slow-query logging, and full v1 API compatibility",
   "type": "commonjs",
   "main": "./dist/cjs/index.cjs",
@@ -18,6 +18,7 @@
     "dist/**/*.cjs",
     "dist/**/*.mjs",
     "dist/**/*.d.ts",
+    "changelogs/v2.0.4.md",
     "changelogs/v2.0.3.md",
     "changelogs/v2.0.2.md",
     "changelogs/v2.0.1.md",
@@ -115,7 +116,7 @@
     "cache-hub": "2.2.4",
     "ioredis": "5.8.2",
     "mongodb": "6.21.0",
-    "schema-dsl": "2.0.8",
+    "schema-dsl": "2.0.9",
     "ssh2": "1.17.0"
   }
 }