monsqlize 2.0.0 → 2.0.1

package/README.md

@@ -423,7 +423,7 @@ const user = await users.findOne({ email });
 const list = await users.find({ status: 'active' }).toArray();
 ```
 
-The current v2.0.0 release candidate has been validated against the workspace consumers `chat`, `payment`, `user`, `admin`, `search`, `vext`, and `permission-core` without requiring business-source changes in those projects.
+The current v2.0.1 release has been validated against the workspace consumers `chat`, `payment`, `user`, `admin`, `search`, `vext`, and `permission-core` without requiring business-source changes in those projects.
 
 ## Compatibility
 
@@ -490,7 +490,7 @@ npm run test:real-env:private
 
 ## Release Status
 
-The current release candidate is `v2.0.0`.
+The current published release is `v2.0.1`.
 
 Key release-readiness points:
 
@@ -503,6 +503,11 @@ Key release-readiness points:
 
 ## Roadmap
 
+### v2.0.1
+
+- v1 smooth-upgrade compatibility patch for Model actual collection names, scoped pools/databases, automatic-index dedupe, and cache/pool option aliases.
+- Documentation and public types aligned with the current runtime behavior.
+
 ### v2.0.0
 
 - TypeScript-native runtime and declarations.

package/changelogs/README.md

@@ -1,160 +1,163 @@
-# Changelogs 目录说明
-
-本目录存放 monSQLize 各版本的详细变更文档。
-
----
-
-## 📁 目录结构
-
-```
+# Changelogs 目录说明
+
+本目录存放 monSQLize 各版本的详细变更文档。
+
+---
+
+## 📁 目录结构
+
+```
 changelogs/
 ├── README.md           # 本说明文档
 ├── TEMPLATE.md         # 变更文档模板
+├── v2.0.1.md          # v2.0.1 详细变更
 ├── v2.0.0.md          # v2.0.0 详细变更
 └── v1.x.y.md          # 历史版本详细变更（仓库归档）
-```
-
----
-
-## 📝 文档格式
-
-每个版本的详细变更文档包含以下章节：
-
-### 必需章节
-
-1. **版本信息** - 版本号、日期、类型、风险级别、兼容性
-2. **变更摘要** - 一句话总结变更核心内容
-3. **背景说明** - 为什么需要这次变更
-4. **变更内容** - 改了什么
-5. **影响范围** - 影响哪些文件和功能
-6. **详细变更清单** - Added/Changed/Fixed 等分类列表
-7. **验证方法** - 如何验证变更
-
-### 可选章节
-
-- **迁移指南** - 如何升级/降级（如有破坏性变更）
-- **相关资源** - 文档/示例/测试链接
-- **设计决策** - 为什么这样设计
-- **未来改进** - 计划的后续改进
-
----
-
-## 🔍 快速查找
-
-### 按版本类型
-
-- **正式发布**: v2.0.0, v1.0.0
+```
+
+---
+
+## 📝 文档格式
+
+每个版本的详细变更文档包含以下章节：
+
+### 必需章节
+
+1. **版本信息** - 版本号、日期、类型、风险级别、兼容性
+2. **变更摘要** - 一句话总结变更核心内容
+3. **背景说明** - 为什么需要这次变更
+4. **变更内容** - 改了什么
+5. **影响范围** - 影响哪些文件和功能
+6. **详细变更清单** - Added/Changed/Fixed 等分类列表
+7. **验证方法** - 如何验证变更
+
+### 可选章节
+
+- **迁移指南** - 如何升级/降级（如有破坏性变更）
+- **相关资源** - 文档/示例/测试链接
+- **设计决策** - 为什么这样设计
+- **未来改进** - 计划的后续改进
+
+---
+
+## 🔍 快速查找
+
+### 按版本类型
+
+- **正式发布**: v2.0.1, v2.0.0, v1.0.0
 - **功能版本**: v1.x
 - **修复版本**: v1.x.y
-
-### 按功能领域
-
-- **TypeScript 重构与 v1 平滑升级**: v2.0.0
+
+### 按功能领域
+
+- **TypeScript 重构与 v1 平滑升级**: v2.0.1, v2.0.0
 - **实时监听 / 管理功能 / 核心功能**: v1.x 历史版本
-
-### 按风险级别
-
+
+### 按风险级别
+
 - **P0 (Critical)**: v2.0.0
+- **Patch**: v2.0.1
 - **P1 (High)**: v1.x 破坏性或高风险历史版本
 - **P2 (Low)**: v1.x 修复版本
-
----
-
-## ✍️ 如何创建新的变更文档
-
-### 步骤1: 复制模板
-
-```bash
-cp TEMPLATE.md v{版本号}.md
-```
-
-### 步骤2: 填写内容
-
-根据模板章节填写变更信息：
-- 版本信息
-- 变更摘要
-- 背景说明
-- 变更内容
-- 影响范围
-- 详细变更清单
-- 验证方法
-
-### 步骤3: 更新主 CHANGELOG
-
+
+---
+
+## ✍️ 如何创建新的变更文档
+
+### 步骤1: 复制模板
+
+```bash
+cp TEMPLATE.md v{版本号}.md
+```
+
+### 步骤2: 填写内容
+
+根据模板章节填写变更信息：
+- 版本信息
+- 变更摘要
+- 背景说明
+- 变更内容
+- 影响范围
+- 详细变更清单
+- 验证方法
+
+### 步骤3: 更新主 CHANGELOG
+
 在项目根目录的 `CHANGELOG.md` 中：
 - 在"版本概览"表格最上方添加新行
 - 格式：版本列和详情列指向当前发布版本的 `changelogs/v{版本号}.md`
-
-### 步骤4: 提交变更
-
-```bash
-git add CHANGELOG.md changelogs/v{版本号}.md
-git commit -m "docs: 发布 v{版本号}"
-git tag v{版本号}
-git push origin main --tags
-```
-
----
-
-## 📚 模板说明
-
-### TEMPLATE.md
-
-`TEMPLATE.md` 是创建新版本文档的标准模板，包含：
-
-- 完整的章节结构
-- 占位符和示例
-- 注释说明
-- Markdown 格式规范
-
-使用时请：
-1. 复制模板文件
-2. 重命名为对应版本号
-3. 替换所有占位符
-4. 删除不需要的可选章节
-5. 补充完整的变更信息
-
----
-
-## 📊 版本命名规范
-
-遵循[语义化版本](https://semver.org/lang/zh-CN/)：
-
-### 格式: vMAJOR.MINOR.PATCH
-
-- **MAJOR** - 不兼容的 API 变更
-- **MINOR** - 向后兼容的新增功能
-- **PATCH** - 向后兼容的问题修复
-
-### 示例
-
-- `v1.0.0` - 正式发布
-- `v1.1.0` - 新增功能
-- `v1.1.1` - Bug 修复
-- `v2.0.0` - 破坏性变更
-
----
-
-## 🔗 相关资源
-
+
+### 步骤4: 提交变更
+
+```bash
+git add CHANGELOG.md changelogs/v{版本号}.md
+git commit -m "docs: 发布 v{版本号}"
+git tag v{版本号}
+git push origin main --tags
+```
+
+---
+
+## 📚 模板说明
+
+### TEMPLATE.md
+
+`TEMPLATE.md` 是创建新版本文档的标准模板，包含：
+
+- 完整的章节结构
+- 占位符和示例
+- 注释说明
+- Markdown 格式规范
+
+使用时请：
+1. 复制模板文件
+2. 重命名为对应版本号
+3. 替换所有占位符
+4. 删除不需要的可选章节
+5. 补充完整的变更信息
+
+---
+
+## 📊 版本命名规范
+
+遵循[语义化版本](https://semver.org/lang/zh-CN/)：
+
+### 格式: vMAJOR.MINOR.PATCH
+
+- **MAJOR** - 不兼容的 API 变更
+- **MINOR** - 向后兼容的新增功能
+- **PATCH** - 向后兼容的问题修复
+
+### 示例
+
+- `v1.0.0` - 正式发布
+- `v1.1.0` - 新增功能
+- `v1.1.1` - Bug 修复
+- `v2.0.0` - 破坏性变更
+
+---
+
+## 🔗 相关资源
+
 - **主 CHANGELOG**: [../CHANGELOG.md](../CHANGELOG.md)
 - **项目文档**: [GitHub docs](https://github.com/vextjs/monSQLize/tree/main/docs)
 - **使用示例**: [GitHub examples](https://github.com/vextjs/monSQLize/tree/main/examples)
 - **测试用例**: [GitHub test](https://github.com/vextjs/monSQLize/tree/main/test)
-- **语义化版本**: https://semver.org/lang/zh-CN/
-
----
-
-## 📋 变更文档清单
-
+- **语义化版本**: https://semver.org/lang/zh-CN/
+
+---
+
+## 📋 变更文档清单
+
 | 版本 | 文件 | 状态 | 发布日期 |
 |------|------|------|---------|
-| v2.0.0 | v2.0.0.md | ✅ 待发布候选 | 2026-06-01 |
+| v2.0.1 | v2.0.1.md | ✅ 已发布 | 2026-06-03 |
+| v2.0.0 | v2.0.0.md | ✅ 已发布 | 2026-06-01 |
 | v1.x | 仓库历史归档 | ✅ 已发布 | 2025-12-03 起 |
-
----
-
+
+---
+
 **目录版本**: 2.0
-**最后更新**: 2026-06-01
-**维护者**: monSQLize Team
-
+**最后更新**: 2026-06-03
+**维护者**: monSQLize Team
+

package/changelogs/v2.0.0.md

@@ -1,24 +1,24 @@
 # v2.0.0 — 2026-06-01
-
-## Overview
-
-v2.0.0 is a full **TypeScript rewrite** of monSQLize. The public API is preserved — existing v1 code requires only minor configuration adjustments to run on v2.
-
----
-
-## Architecture
-
-| Layer | Change |
-|---|---|
-| Source language | JavaScript → TypeScript (strict mode) |
-| Cache engine | Internal implementation → [`cache-hub`](https://github.com/vextjs/cache-hub) |
-| Internal structure | Flat modules → capability layers + adapter bridge |
-| Type declarations | Hand-maintained `.d.ts` → generated from source (single source of truth) |
-
----
-
+
+## Overview
+
+v2.0.0 is a full **TypeScript rewrite** of monSQLize. The public API is preserved — existing v1 code requires only minor configuration adjustments to run on v2.
+
+---
+
+## Architecture
+
+| Layer | Change |
+|---|---|
+| Source language | JavaScript → TypeScript (strict mode) |
+| Cache engine | Internal implementation → [`cache-hub`](https://github.com/vextjs/cache-hub) |
+| Internal structure | Flat modules → capability layers + adapter bridge |
+| Type declarations | Hand-maintained `.d.ts` → generated from source (single source of truth) |
+
+---
+
 ## Compatibility Notes and Breaking Changes
-
+
 ### B1 — `SagaResult` shape documents v1/v2 aliases
 
 `SagaResult` now exposes the runtime fields and the restored v1/v2 alias fields:
@@ -44,142 +44,142 @@ v2.0.0 is a full **TypeScript rewrite** of monSQLize. The public API is preserve
 ### B2 — `TransactionInfo.status` keeps the v1 `'started'` value
 
 The internal transaction state still uses `'active'`, but `Transaction#getInfo().status` maps it back to `'started'` for v1 callers. Public values are `'pending' | 'started' | 'committed' | 'aborted'`.
-
-### B3 — `getPoolStats()` / `getPoolHealth()` return `Record<string, T>`
-
-```ts
-// v1 — array
-getPoolStats(): PoolStats[]
-getPoolHealth(): PoolHealthStatus[]
-
-// v2 — keyed by pool name
-getPoolStats(): Record<string, PoolStats>
-getPoolHealth(): Record<string, PoolHealthStatus>
-```
-
-### B4 — `PoolStats` shape extended
-
-`PoolStats` now includes `connections`, `available`, `waiting`, and `status` fields that were absent in v1 type declarations (but present in the runtime).
-
-### B5 — `getCache()` returns `CacheLike`
-
-```ts
-// v1
-getCache(): MemoryCache
-
-// v2
-getCache(): CacheLike  // MemoryCache | MultiLevelCache | custom adapter
-```
-
-This is a widening: `MemoryCache` is still the default; the return type is broader to accommodate the two new cache modes.
-
----
-
-## New Features
-
-### MultiLevel cache via `cache` option
-
-```ts
-const msq = new MonSQLize({
-  type: 'mongodb',
-  cache: {
-    multiLevel: true,
-    local: { maxEntries: 5000 },
-    remote: MonSQLize.createRedisCacheAdapter('redis://localhost:6379'),
-    policy: { writePolicy: 'local-first-async-remote', backfillLocalOnRemoteHit: true },
-  },
-});
-```
-
-### SSH tunnel support
-
-Connect to MongoDB through a bastion host with no code changes required:
-
-```ts
-const msq = new MonSQLize({
-  type: 'mongodb',
-  config: {
-    uri: 'mongodb://mongo.internal:27017/mydb',
-    ssh: {
-      host: 'bastion.example.com',
-      username: 'deploy',
-      privateKeyPath: '~/.ssh/id_rsa',
-    },
-  },
-});
-```
-
-Requires the optional `ssh2` package: `npm install ssh2`.
-
-### Custom `CacheLike` pass-through (v1 compat)
-
-Passing a custom `CacheLike` instance (e.g. a Redis adapter) directly as `cache` is now supported:
-
-```ts
-const msq = new MonSQLize({
-  type: 'mongodb',
-  cache: MonSQLize.createRedisCacheAdapter('redis://localhost:6379'),
-});
-```
-
-In v1 this silently fell back to a default `MemoryCache`. In v2 it is used directly.
-
-### `HealthView.driver` field
-
-`health()` now returns `driver: { connected: boolean }` alongside the existing fields.
-
-### `ModelInstance` soft-delete and batch methods
-
-`findOneOnlyDeleted`, `countWithDeleted`, `countOnlyDeleted`, `insertBatch`, `updateBatch` are now declared in the public type surface (they existed at runtime in v1 but were not typed).
-
----
-
-## v1 Compatibility Map
-
-| v1 option | v2 equivalent | Status |
-|---|---|---|
-| `cache.maxSize` | `cache.maxEntries` | ✅ auto-mapped |
-| `cache.ttl` | `cache.defaultTtl` | ✅ auto-mapped |
-| `cache.autoInvalidate` | `cacheAutoInvalidate` (top-level) | ✅ both accepted |
-| `cache: CacheLike` | `cache: CacheLike` | ✅ pass-through |
-| `cache: MultiLevelCacheOptions` | `cache: { multiLevel: true, ... }` | ✅ fully supported |
-| `options.database` | `options.databaseName` | ✅ alias preserved |
-| `SagaResult.sagaId` | `SagaResult.sagaId` + `executionId` alias | ✅ |
+
+### B3 — `getPoolStats()` / `getPoolHealth()` return `Record<string, T>`
+
+```ts
+// v1 — array
+getPoolStats(): PoolStats[]
+getPoolHealth(): PoolHealthStatus[]
+
+// v2 — keyed by pool name
+getPoolStats(): Record<string, PoolStats>
+getPoolHealth(): Record<string, PoolHealthStatus>
+```
+
+### B4 — `PoolStats` shape extended
+
+`PoolStats` now includes `connections`, `available`, `waiting`, and `status` fields that were absent in v1 type declarations (but present in the runtime).
+
+### B5 — `getCache()` returns `CacheLike`
+
+```ts
+// v1
+getCache(): MemoryCache
+
+// v2
+getCache(): CacheLike  // MemoryCache | MultiLevelCache | custom adapter
+```
+
+This is a widening: `MemoryCache` is still the default; the return type is broader to accommodate the two new cache modes.
+
+---
+
+## New Features
+
+### MultiLevel cache via `cache` option
+
+```ts
+const msq = new MonSQLize({
+  type: 'mongodb',
+  cache: {
+    multiLevel: true,
+    local: { maxEntries: 5000 },
+    remote: MonSQLize.createRedisCacheAdapter('redis://localhost:6379'),
+    policy: { writePolicy: 'local-first-async-remote', backfillLocalOnRemoteHit: true },
+  },
+});
+```
+
+### SSH tunnel support
+
+Connect to MongoDB through a bastion host with no code changes required:
+
+```ts
+const msq = new MonSQLize({
+  type: 'mongodb',
+  config: {
+    uri: 'mongodb://mongo.internal:27017/mydb',
+    ssh: {
+      host: 'bastion.example.com',
+      username: 'deploy',
+      privateKeyPath: '~/.ssh/id_rsa',
+    },
+  },
+});
+```
+
+Requires the optional `ssh2` package: `npm install ssh2`.
+
+### Custom `CacheLike` pass-through (v1 compat)
+
+Passing a custom `CacheLike` instance (e.g. a Redis adapter) directly as `cache` is now supported:
+
+```ts
+const msq = new MonSQLize({
+  type: 'mongodb',
+  cache: MonSQLize.createRedisCacheAdapter('redis://localhost:6379'),
+});
+```
+
+In v1 this silently fell back to a default `MemoryCache`. In v2 it is used directly.
+
+### `HealthView.driver` field
+
+`health()` now returns `driver: { connected: boolean }` alongside the existing fields.
+
+### `ModelInstance` soft-delete and batch methods
+
+`findOneOnlyDeleted`, `countWithDeleted`, `countOnlyDeleted`, `insertBatch`, `updateBatch` are now declared in the public type surface (they existed at runtime in v1 but were not typed).
+
+---
+
+## v1 Compatibility Map
+
+| v1 option | v2 equivalent | Status |
+|---|---|---|
+| `cache.maxSize` | `cache.maxEntries` | ✅ auto-mapped |
+| `cache.ttl` | `cache.defaultTtl` | ✅ auto-mapped |
+| `cache.autoInvalidate` | `cacheAutoInvalidate` (top-level) | ✅ both accepted |
+| `cache: CacheLike` | `cache: CacheLike` | ✅ pass-through |
+| `cache: MultiLevelCacheOptions` | `cache: { multiLevel: true, ... }` | ✅ fully supported |
+| `options.database` | `options.databaseName` | ✅ alias preserved |
+| `SagaResult.sagaId` | `SagaResult.sagaId` + `executionId` alias | ✅ |
 | `ctx.sagaId` in Saga steps | `ctx.executionId` + `ctx.sagaId` alias | ✅ alias preserved |
-
----
-
-## JSDoc Coverage
-
-All public API surface now carries complete English JSDoc:
-
-- `types/collection.d.ts` — 49 Collection / DbAccessor / AdminAccessor methods
-- `types/model.d.ts` — 44 ModelInstance methods
-- `types/monsqlize.d.ts` — 43 MonSQLize interface methods
-- `types/lock.d.ts` — Lock / LockManager
-- `types/saga.d.ts` — SagaOrchestrator / SagaContext / SagaStep
-- `types/transaction.d.ts` — Transaction / TransactionManager / CacheLockManager
-- `types/runtime.d.ts` — MemoryCache / MultiLevelCache / FunctionCache
-
----
-
-## v1 Compatibility Fixes (included in this release)
-
-### API / Runtime
-- **`findAndCount`**: return value includes `documents` as a backward-compat alias for `data` (`{ data, total, documents }`)
-- **`findOneById` / `findByIds`**: `options.cache` now restores v1-style read-through TTL caching.
-- **Runtime query defaults**: built-in defaults now match v1 (`maxTimeMS=2000`, `findLimit=10`, `slowQueryMs=500`, `findPageMaxLimit=500`).
-- **`LockManager` TTL**: explicit lock TTL values are no longer silently capped by `maxDuration`.
-- **`withCache(fn)`**: default behavior now matches v1 (`ttl=60000`, `namespace='fn'`, `enableStats=true`).
-- **`adaptLegacyCacheLike`**: exported as both a named import and `MonSQLize.adaptLegacyCacheLike`
-- **`MultiLevelCache`**: exported as both a named import and `MonSQLize.MultiLevelCache`
-- **Error messages**: `createValidationError` default message `参数校验失败`; `createCursorError` default `游标无效`
-- **`FunctionCache.defaultTTL`**: v1 option `defaultTTL` now accepted as an alias for `ttl`; v1 code using `new FunctionCache(db, { defaultTTL: 60000 })` works without changes
-- **Read query meta wrapper**: `find` / `findOne` / `count` / `aggregate` / `distinct` now restore the v1 `{ data, meta }` result shape when `options.meta` is enabled.
-- **`FunctionCache` defaults and stats**: `new FunctionCache()` is supported, the default namespace is restored to `action`, and stats include `totalTime` / `avgTime`.
-- **Batch writes**: `insertBatch` / `deleteBatch` retry defaults are restored to `3` attempts and `1000ms`; `updateBatch` now supports `onError='retry'`, `retryAttempts`, `retryDelay`, and `onRetry`.
-- **Model hooks**: flat hooks support `beforeInsert` / `afterInsert` aliases and now cover bulk/upsert/findOneAnd* write paths.
-
+
+---
+
+## JSDoc Coverage
+
+All public API surface now carries complete English JSDoc:
+
+- `types/collection.d.ts` — 49 Collection / DbAccessor / AdminAccessor methods
+- `types/model.d.ts` — 44 ModelInstance methods
+- `types/monsqlize.d.ts` — 43 MonSQLize interface methods
+- `types/lock.d.ts` — Lock / LockManager
+- `types/saga.d.ts` — SagaOrchestrator / SagaContext / SagaStep
+- `types/transaction.d.ts` — Transaction / TransactionManager / CacheLockManager
+- `types/runtime.d.ts` — MemoryCache / MultiLevelCache / FunctionCache
+
+---
+
+## v1 Compatibility Fixes (included in this release)
+
+### API / Runtime
+- **`findAndCount`**: return value includes `documents` as a backward-compat alias for `data` (`{ data, total, documents }`)
+- **`findOneById` / `findByIds`**: `options.cache` now restores v1-style read-through TTL caching.
+- **Runtime query defaults**: built-in defaults now match v1 (`maxTimeMS=2000`, `findLimit=10`, `slowQueryMs=500`, `findPageMaxLimit=500`).
+- **`LockManager` TTL**: explicit lock TTL values are no longer silently capped by `maxDuration`.
+- **`withCache(fn)`**: default behavior now matches v1 (`ttl=60000`, `namespace='fn'`, `enableStats=true`).
+- **`adaptLegacyCacheLike`**: exported as both a named import and `MonSQLize.adaptLegacyCacheLike`
+- **`MultiLevelCache`**: exported as both a named import and `MonSQLize.MultiLevelCache`
+- **Error messages**: `createValidationError` default message `参数校验失败`; `createCursorError` default `游标无效`
+- **`FunctionCache.defaultTTL`**: v1 option `defaultTTL` now accepted as an alias for `ttl`; v1 code using `new FunctionCache(db, { defaultTTL: 60000 })` works without changes
+- **Read query meta wrapper**: `find` / `findOne` / `count` / `aggregate` / `distinct` now restore the v1 `{ data, meta }` result shape when `options.meta` is enabled.
+- **`FunctionCache` defaults and stats**: `new FunctionCache()` is supported, the default namespace is restored to `action`, and stats include `totalTime` / `avgTime`.
+- **Batch writes**: `insertBatch` / `deleteBatch` retry defaults are restored to `3` attempts and `1000ms`; `updateBatch` now supports `onError='retry'`, `retryAttempts`, `retryDelay`, and `onRetry`.
+- **Model hooks**: flat hooks support `beforeInsert` / `afterInsert` aliases and now cover bulk/upsert/findOneAnd* write paths.
+
 ### Type Declarations
 - **`FindAndCountResult`**: includes `documents?: TSchema[]` optional backward-compat alias
 - **`SagaResult`**: includes `completedStepNames?: string[]` (ordered step names, v1 compat) and `errorCause?: unknown`
@@ -210,13 +210,13 @@ All public API surface now carries complete English JSDoc:
 - GitHub Actions publish flow now runs `release:preflight` once before `npm publish --ignore-scripts`, avoiding duplicate `prepublishOnly` lifecycle execution inside the final publish step while preserving raw `npm publish` safeguards.
 
 ---
-
-## Migration Notes
-
-Most v1 applications will **run without modification**. The steps below apply only if you hit one of the breaking changes.
-
-1. **`getPoolStats()` / `getPoolHealth()`** — if you iterate the result as an array, switch to `Object.values(msq.getPoolStats())`.
-2. **`Saga context`** — replace `ctx.sagaId` with `ctx.executionId` inside step handlers.
-3. **`getCache()` narrowing** — if you assigned the result to a `MemoryCache` typed variable, widen the type to `CacheLike`.
-4. **`cache.maxSize`** — still works transparently; rename to `maxEntries` at your convenience.
-5. **`slow-query-log queryHash`** — v2 now normalizes the hash from stable identity fields (`database|db`、`collection|coll`、`operation|op`、`queryShape|query`) and stores a 16-character digest. Historical slow-query-log records remain readable, but new and old aggregation keys are not guaranteed to stay continuous. This release does **not** include an automatic migration script; if your downstream analytics depend on historical key continuity, migrate those records explicitly before or during rollout.
+
+## Migration Notes
+
+Most v1 applications will **run without modification**. The steps below apply only if you hit one of the breaking changes.
+
+1. **`getPoolStats()` / `getPoolHealth()`** — if you iterate the result as an array, switch to `Object.values(msq.getPoolStats())`.
+2. **`Saga context`** — replace `ctx.sagaId` with `ctx.executionId` inside step handlers.
+3. **`getCache()` narrowing** — if you assigned the result to a `MemoryCache` typed variable, widen the type to `CacheLike`.
+4. **`cache.maxSize`** — still works transparently; rename to `maxEntries` at your convenience.
+5. **`slow-query-log queryHash`** — v2 now normalizes the hash from stable identity fields (`database|db`、`collection|coll`、`operation|op`、`queryShape|query`) and stores a 16-character digest. Historical slow-query-log records remain readable, but new and old aggregation keys are not guaranteed to stay continuous. This release does **not** include an automatic migration script; if your downstream analytics depend on historical key continuity, migrate those records explicitly before or during rollout.