chore: prepare v2.0.4 release

Author: rockyshi1993

CHANGELOG.md

@@ -1,14 +1,15 @@
 # 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
 
 ---
 
 ## Version Overview
 
 | 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,13 +502,14 @@ 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) - 项目说明
 - [docs/](https://github.com/vextjs/monSQLize/blob/main/docs/index.md) - API 文档
 
 ---
 
-**最后更新**: 2026-06-11
+**最后更新**: 2026-06-12
 

README.md

@@ -39,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.
@@ -253,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
@@ -497,19 +518,25 @@ 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:
 
 - TypeScript rewrite completed for the current runtime and test entry 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.

changelogs/unreleased.md

@@ -4,10 +4,10 @@
 
 - No unreleased fixes yet.
 
+## Changed
+
+- No unreleased changes yet.
+
 ## Documentation
 
-- Added the complete English and Simplified Chinese documentation entry near the top of the README.
-- Refined the documentation home hero alignment and replaced the sparse hero mark with a lightweight animated data-flow scene.
-- Expanded the documentation home footer into a bilingual VextJS-style resource section with the VextJS organization link and project navigation.
-- Aligned the documentation home feature grid with the hero content width and centered the hero visual weight.
-- Fine-tuned the documentation home hero illustration vertical offset for a more balanced first fold.
+- No unreleased documentation changes yet.

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.

docs/en/cache-and-function-cache.md

@@ -89,14 +89,14 @@ The current official example is `examples/cache/with-cache.ts`. During verificat
 
 ## 5. Redis and Distributed Capabilities
 
-The current repository has restored:
+Available entries:
 
 - `createRedisCacheAdapter`
 - `DistributedCacheInvalidator`
 
 The first example batch does **not** depend on Redis because:
 
-1. Its goal is to establish a minimal runnable example loop.
+1. Its goal is to provide a minimal runnable example path.
 2. Redis-related capabilities require explicit runtime configuration. `ioredis` is already installed with monsqlize.
 3. The first formal documentation entry should not be coupled to distributed cache environment setup.
 

docs/en/capability-index.md

@@ -1,40 +1,40 @@
 # Advanced Capability Index
 
-This page is the formal entry index for capabilities restored in the current TypeScript version of `monSQLize`.
+This page lists the stable capability entry points in the current TypeScript version of `monSQLize`.
 
 Principles:
 
-- First state what the current repository formally owns.
-- Then point to the corresponding documentation and runnable examples in this repository.
+- Start with the API entry points users can call.
+- Then point to the corresponding documentation and runnable examples.
 
 ## Current Capability Overview
 
-| Capability | Current formal entry | Current status | Notes |
-|------------|----------------------|----------------|-------|
-| Model | `msq.model()` / `MonSQLize.Model` | ✅ Restored | Minimal registry / features loop is in place |
-| transaction / lock | `startSession()` / `withTransaction()` / `withLock()` / `acquireLock()` / `tryAcquireLock()` | ✅ Restored | Current runtime / types / unit / integration coverage is closed |
-| pool | `pool()` / `ConnectionPoolManager` | ✅ Restored | Minimal multi-pool loop is in place |
-| sync | `startSync()` / `stopSync()` / `getSyncStats()` | ✅ Restored | Minimal lifecycle / manager loop is in place |
-| slow-query-log | `recordSlowQuery()` / `getSlowQueryLogs()` | ✅ Restored | Manager / queue / runtime façade are in place |
-| saga | `defineSaga()` / `executeSaga()` / `getSagaStats()` | ✅ Restored | Orchestrator / runtime façade are in place |
+| Capability | Recommended entry | Notes |
+|------------|----------------------|-------|
+| Model | `msq.model()` / `MonSQLize.Model` | Supports model registration, relations, virtuals, populate, and common query entries |
+| transaction / lock | `startSession()` / `withTransaction()` / `withLock()` / `acquireLock()` / `tryAcquireLock()` | Supports transaction wrappers, local business locks, and distributed lock entries |
+| pool | `pool()` / `ConnectionPoolManager` | Supports multi-pool configuration, selection strategies, fallback, and status inspection |
+| sync | `startSync()` / `stopSync()` / `getSyncStats()` | Supports Change Stream sync start, stop, and status inspection |
+| slow-query-log | `recordSlowQuery()` / `getSlowQueryLogs()` | Supports slow-query recording, querying, and runtime management |
+| saga | `defineSaga()` / `executeSaga()` / `getSagaStats()` | Supports Saga definition, execution, compensation, and stats queries |
 
 ## 1. Model
 
-The current repository formally restores:
+Available entries:
 
 - `Model.define/get/list/undefine/redefine`
 - `msq.model()`
 - relations / virtuals / populate
 - `findOneById()` / `findByIds()` / `findAndCount()`
 
-Current Model entries:
+Model documentation and examples:
 
 - Docs: `docs/model.md`, `docs/populate.md`, `docs/relations.md`
 - Example: `examples/docs/model.ts`
 
 ## 2. transaction / lock
 
-The current repository formally restores:
+Available entries:
 
 - `startSession()`
 - `withTransaction()`
@@ -51,7 +51,7 @@ More advanced distributed lock strategies will continue to be documented in this
 
 ## 3. pool
 
-The current repository formally restores:
+Available entries:
 
 - `pool()`
 - `ConnectionPoolManager`
@@ -64,19 +64,19 @@ This is the current entry point for:
 
 ## 4. sync / slow-query-log / saga
 
-The current repository formally restores the minimal public surface for:
+Available entries:
 
 - sync: contract / manager / lifecycle
 - slow-query-log: manager / queue / runtime façade
 - saga: orchestrator / runtime façade
 
-The repository already provides topic pages and runnable examples:
+These capabilities include topic pages and runnable examples:
 
 - sync: `docs/sync-backup.md`, examples `examples/docs/sync.ts` and `examples/docs/sync-target-failure.ts`
 - slow-query-log: `docs/slow-query-log.md`, example `examples/docs/slow-query-log.ts`
 - saga: `docs/saga-transaction.md`, `docs/saga-advanced.md`, example `examples/docs/saga.ts`
 
-The next expansion focus is runtime fault injection, real deployment topology, and performance boundaries rather than filling in basic entry points.
+Future documentation will continue to cover runtime fault injection, real deployment topology, and performance boundaries.
 
 ## 5. Recommended Entries in This Repository