monsqlize 2.0.6 → 3.1.0

package/CHANGELOG.md

@@ -1,7 +1,7 @@
 # CHANGELOG
 
-> Summary index — current release details are packaged in [changelogs/v2.0.6.md](./changelogs/v2.0.6.md); historical details live in the repository changelog archive.
-> **Last updated**: 2026-06-15
+> Summary index — the v3.1.0 stable release details are in [changelogs/v3.1.0.md](./changelogs/v3.1.0.md); the earlier RC note remains an unpublished rehearsal archive.
+> **Last updated**: 2026-07-15
 
 ---
 
@@ -9,6 +9,9 @@
 
 | Version | Date | Summary | Details |
 |---------|------|---------|---------|
+| [v3.1.0](./changelogs/v3.1.0.md) | 2026-07-15 | Minor: schema-dsl v3 GA consumption, canonical validation errors, and normalized full-document persistence | [View](./changelogs/v3.1.0.md) |
+| [v3.0.0](./changelogs/v3.0.0.md) | 2026-07-14 | Major: two-instance preview/apply/restore data tasks, write-path policy, runtime-scoped schema DSL, stricter OCC/sync/query contracts, and release recovery controls | [View](./changelogs/v3.0.0.md) |
+| [v2.0.7](./changelogs/v2.0.7.md) | Unpublished | Withdrawn patch candidate; never published and superseded by v3.0.0 | [Archive](./changelogs/v2.0.7.md) |
 | [v2.0.6](./changelogs/v2.0.6.md) | 2026-06-15 | Patch: dependency alignment to `schema-dsl@2.0.11` so downstream frameworks inherit the ESM/CJS shared custom type registry fix | [View](./changelogs/v2.0.6.md) |
 | [v2.0.5](./changelogs/v2.0.5.md) | 2026-06-13 | Patch: Model schema adapter delegates DSL type authority to `schema-dsl@2.0.10`, removing the duplicated monSQLize allowlist while preserving legacy aliases and business literals | [View](./changelogs/v2.0.5.md) |
 | [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) |
@@ -449,7 +452,9 @@ const result = await msq.collection('orders').insertOne(dataFromMongoose);
 changelogs/
 ├── README.md          # 变更文档说明
 ├── TEMPLATE.md        # 变更文档模板
-├── v2.0.6.md         # 当前发布详细变更
+├── v3.0.0.md         # 当前 Major 稳定发布详细变更
+├── v2.0.7.md         # 从未发布的历史候选归档
+├── v2.0.6.md         # v2.0.6 详细变更
 ├── v2.0.5.md         # v2.0.5 详细变更
 ├── v2.0.4.md         # v2.0.4 详细变更
 ├── v2.0.3.md         # v2.0.3 详细变更
@@ -506,7 +511,9 @@ changelogs/
 
 ## 相关文档
 
-- [changelogs/v2.0.6.md](./changelogs/v2.0.6.md) - 当前发布详细变更文档
+- [changelogs/v3.0.0.md](./changelogs/v3.0.0.md) - 当前 Major 稳定发布详细变更文档
+- [changelogs/v2.0.7.md](./changelogs/v2.0.7.md) - 从未发布的候选归档
+- [changelogs/v2.0.6.md](./changelogs/v2.0.6.md) - v2.0.6 详细变更文档
 - [changelogs/v2.0.5.md](./changelogs/v2.0.5.md) - v2.0.5 详细变更文档
 - [changelogs/v2.0.4.md](./changelogs/v2.0.4.md) - v2.0.4 详细变更文档
 - [changelogs/v2.0.3.md](./changelogs/v2.0.3.md) - v2.0.3 详细变更文档
@@ -517,5 +524,5 @@ changelogs/
 
 ---
 
-**最后更新**: 2026-06-15
+**最后更新**: 2026-07-10
 

package/MIGRATION.md

@@ -0,0 +1,127 @@
+# Migration Guide: monSQLize v1/v2 → v3
+
+This guide starts with the v2.0.6 to v3.0.0 upgrade path, then retains the
+v1-to-v2 compatibility notes for older applications. Review every tightened
+contract that intersects your application before changing the installed major.
+
+## Upgrade from v3.0.0 to v3.1.0
+
+monSQLize v3.1 consumes schema-dsl v3 without installing schema-dsl's legacy
+String prototype extensions. Applications that need those extensions must opt
+in through `schema-dsl/compat` or `schema-dsl/register-string`; monSQLize itself
+continues to use the isolated `schema-dsl/runtime` entry and does not require
+them.
+
+Successful full-document Model validation now persists schema-dsl's normalized
+`data` for `insertOne`, `insertMany`, `insertBatch`, `replaceOne`,
+`findOneAndReplace`, and hydrated document `save()`. Coerced values and schema
+defaults therefore reach MongoDB. The order is model defaults, before hook,
+schema normalization, timestamps, version, then driver write. Replacement
+writes do not apply model defaults, and `save()` has no new before-hook stage.
+
+Validation failures still throw `VALIDATION_ERROR`, and public errors remain
+`{ field, message }`; `field` is mapped from schema-dsl's canonical `path`.
+Update operators and pipelines do not expose a complete final document and are
+not included in normalized-data persistence. If an application relied on
+schema-dsl coercion being discarded before v3.1, review stored value types in a
+staging environment before upgrading.
+
+## Upgrade from v2.0.6 to v3.0.0
+
+### 1. Run the release checks before changing production
+
+Use Node.js 18 or newer, install v3 in a staging branch, and run your own
+Model, cache, sync, transaction, and data rollout tests. monSQLize v3 pins
+`schema-dsl@2.1.6` and keeps the isolated `schema-dsl/runtime` integration.
+
+### 2. Review bounded query and optimistic-locking behavior
+
+- `find()` defaults to 500 documents. Configure an explicit safe limit when a
+  service previously depended on an unbounded result.
+- Versioned single-document Model writes use optimistic concurrency control and
+  may throw `WRITE_CONFLICT` for stale state.
+- Versioned `updateMany()` defaults to `counter`; select `strict` or `off` when
+  that better matches the existing write contract.
+- `updateBatch({ upsert: true })` is rejected. Use `upsertOne()` or MongoDB's
+  native `updateMany(..., { upsert: true })` according to the required semantics.
+
+### 3. Review sync, index, and production guards
+
+- Resume-token persistence failures stop Change Stream sync unless a legacy
+  best-effort option is selected explicitly.
+- `autoIndex: true` now preflights with `listIndexes()`, creates only missing
+  indexes, and reports conflicts. Keep production index rollout reviewed.
+- `production`, `prod`, and `live` all activate production-like safety guards.
+
+### 4. Use the new bounded data-task path for release data
+
+For selected release data and declared indexes, use
+`dataTasks.preview(job)` followed by `dataTasks.apply(job, { approval })`.
+Production jobs require a durable affected-scope backup directory. This feature
+does not replace schema migrations, full database export/import, or disaster
+recovery. See the data-tasks and production-rollout guides before first use.
+
+## Historical v1 to v2 notes
+
+The sections below document intentional behavioural and contract changes between
+monSQLize v1.x and v2.x. Most v2 type-level differences from v1 have been
+softened (optional fields, alias keys, permissive callbacks) so that v1
+fixtures and call sites continue to type-check unchanged. The items below
+are the **deliberately tightened** semantics that v2 keeps for safety; v1
+callers in these spots may need code changes.
+
+## Tightened semantics retained in v2
+
+### 1. `Model.findOne` returns `T | null` (not `T | undefined`)
+
+- v1 returned `undefined` when no document matched.
+- v2 returns `null`, matching the underlying MongoDB driver and removing
+  the `undefined` vs `null` ambiguity.
+- **Migration**: replace `result === undefined` with `result === null`,
+  or use `!result` which works for both.
+
+### 2. `ConnectionPoolManager#selectPool()` returns a typed handle
+
+- v1 returned an opaque object whose shape was not declared.
+- v2 returns a `PoolHandle` interface with documented fields
+  (`name`, `client`, etc.).
+- **Migration**: no source change is required if you only consume fields
+  v2 declares. If your v1 code accessed undeclared fields, declare them
+  through module augmentation or assert through `as unknown as ...`.
+
+### 3. Cache event payloads use `unknown` rather than `any`
+
+- The cache `publish()` / subscriber callback payload type is now
+  `unknown` instead of `any`, forcing call sites to narrow before use.
+- **Migration**: add a runtime check or a type assertion at the
+  consumption point. The wire shape is unchanged.
+
+## Type-level compatibility additions (no source change required)
+
+For reference, v2 type files were extended with the following alias /
+optional fields so that v1 fixtures and runtime payloads continue to
+type-check; you do **not** need to migrate code for these:
+
+- `BatchRetryRecord`: added optional `attempts` (alias of `attempt`) and
+  `success?: boolean`. The runtime now also emits both fields on retry
+  records to match v1.
+- `FindPageOptions`: added top-level `comment?: string` shortcut that
+  mirrors `options.comment`.
+- `SagaContext.get<T = any>`: default generic relaxed from `unknown` to
+  `any` to match v1 ergonomics.
+- `SagaResult.sagaId` / `sagaName`: marked optional alongside
+  `executionId`.
+- `SagaStats`: aliased v2-only fields
+  (`successfulExecutions` / `failedExecutions` / `compensatedExecutions`)
+  are optional; `successCount` / `failureCount` / `compensationCount`
+  remain the v1 primary fields.
+- `MongoSession.transaction?.state`: re-exposed for v1 callers reading
+  `session.transaction?.state`.
+- `SyncConfig.transform`: accepts both v1 single-arg
+  `(document) => ...` and v2 `(document, event) => ...` forms.
+- `Lock.released`: marked `readonly` to match v1.
+- `PoolStats`: counter fields are optional to accept v1 fixture shapes.
+
+If a previously-undocumented field still does not type-check, please
+file an issue with the v1 reproduction so the public types can be
+extended.