monsqlize 3.0.0 → 3.1.0

package/CHANGELOG.md

@@ -1,7 +1,7 @@
 # CHANGELOG
 
-> Summary index — current stable v3.0.0 details are in [changelogs/v3.0.0.md](./changelogs/v3.0.0.md); v2.0.7 was never published and remains an audit archive.
-> **Last updated**: 2026-07-14
+> 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,7 @@
 
 | 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) |

package/MIGRATION.md

@@ -4,6 +4,28 @@ 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

package/README.md

@@ -4,7 +4,7 @@ Database-native production data runtime layer for TypeScript services. monSQLize
 
 [![npm version](https://img.shields.io/npm/v/monsqlize.svg)](https://www.npmjs.com/package/monsqlize)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
-[![MongoDB](https://img.shields.io/badge/MongoDB-6.x%20%2F%207.x-green.svg)](https://www.mongodb.com/)
+[![MongoDB](https://img.shields.io/badge/MongoDB-7.x%20%2F%208.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/)
@@ -14,6 +14,8 @@ Upgrade and security: [Migration Guide](./MIGRATION.md) · [Private Vulnerabilit
 
 The npm `latest` dist-tag and GitHub Pages are the stable channel; `main` may contain the next release. Pages deployment accepts only a versioned Git tag whose package version is already present on npm, so unpublished APIs are not promoted as stable documentation.
 
+This source tree contains the stable `3.1.0` release candidate, pinned to verified registry `schema-dsl@3.0.0`. The v3 package remains subject to the full release gate before its immutable tag and npm publication.
+
 ```bash
 npm install monsqlize
 ```
@@ -44,7 +46,7 @@ The shared runtime direction is cache consistency, connection lifecycle, transac
 
 ## Runtime Consistency Contract
 
-monSQLize coordinates cache, transactions, sync, and queues inside the runtime, but it does not provide a global strict-consistency kernel. MongoDB transactions keep MongoDB session ACID semantics. Query caching is opt-in, and write-side cache invalidation is explicit: use `cache.invalidate` for precise entries or `autoInvalidate` / `cache.autoInvalidate` for broad invalidation. Cache invalidation runs after successful writes or transaction commit and is best-effort; Redis/L2 cache and Pub/Sub invalidation provide eventual cross-instance coherence rather than atomic cache/DB commits. Change Stream sync is at-least-once; custom targets should be idempotent by change event `_id`, and `sync.idempotency` can record per-target replay markers when a durable store is provided. Transaction cache locks are process-local in the v2 runtime; use explicit business coordination, idempotency/fencing, or cache bypassing for cross-instance strict flows.
+monSQLize coordinates cache, transactions, sync, and queues inside the runtime, but it does not provide a global strict-consistency kernel. MongoDB transactions keep MongoDB session ACID semantics. Query caching is opt-in, and write-side cache invalidation is explicit: use `cache.invalidate` for precise entries or `autoInvalidate` / `cache.autoInvalidate` for broad invalidation. Cache invalidation runs after successful writes or transaction commit and is best-effort; Redis/L2 cache and Pub/Sub invalidation provide eventual cross-instance coherence rather than atomic cache/DB commits. Change Stream sync is at-least-once; custom targets should be idempotent by change event `_id`, and `sync.idempotency` can record per-target replay markers when a durable store is provided. Transaction cache locks are process-local in the current v3 runtime; use explicit business coordination, idempotency/fencing, or cache bypassing for cross-instance strict flows.
 
 ## Write Path Policy
 
@@ -164,7 +166,7 @@ Published entry points:
 | ESM | `dist/esm/index.mjs` |
 | Types | `dist/types/index.d.ts` |
 
-The package root exports only the public package contract. Deep imports into historical `lib/**` files are not part of the v2 publishing surface.
+The package root exports only the public package contract. Deep imports into historical `lib/**` files are not part of the v3 publishing surface.
 
 ## Model Layer
 
@@ -261,6 +263,8 @@ const msq = new MonSQLize({
 For monSQLize-only Model validation, no direct application import from `schema-dsl` is required. Direct application imports should use `schema-dsl/runtime` when they need to share the same isolated runtime state with monSQLize.
 Use `schemaDsl: { extensions }` when monSQLize should own the runtime and register extension definitions. When the application owns the schema-dsl lifecycle, configure that runtime directly, including `runtime.registerExtensions([...])`, and inject it with `schemaDsl: { runtime }`. If the default `schema-dsl/runtime` entry cannot be resolved or does not expose the required runtime APIs, monSQLize throws `INVALID_CONFIG`; validation is disabled only when `schemaDsl: false` or `schemaDsl: { enabled: false }` is set explicitly.
 
+For `insertOne`, `insertMany`, `insertBatch`, `replaceOne`, `findOneAndReplace`, and hydrated document `save()`, successful schema validation now forwards schema-dsl's normalized `data` into the actual write. Public errors remain `{ field, message }`, mapped from canonical upstream `path/message`. Update operators and pipelines are intentionally outside this complete-document normalization contract.
+
 ### Automatic Model Loading
 
 ```js
@@ -477,7 +481,7 @@ const user = await users.findOne({ email });
 const list = await users.find({ status: 'active' }).toArray();
 ```
 
-The v2 line 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 v3 line 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
 
@@ -485,7 +489,7 @@ The v2 line has been validated against the workspace consumers `chat`, `payment`
 |---|---|
 | Node.js | `>=18.0.0`; CI covers Node 18 / 20 / 22. |
 | MongoDB driver | `mongodb@6.21.0` runtime baseline; driver 7.5.0 has additional compatibility coverage. |
-| MongoDB server | Memory-server based 6.x / 7.x validation is covered by the project test matrix. |
+| MongoDB server | Memory-server based 7.x / 8.x validation is covered by the strict project test matrix. |
 | Module systems | CommonJS and ESM are both validated. |
 | TypeScript | Public declarations are published from `dist/types/index.d.ts`. |
 | Package license | Apache-2.0. |
@@ -501,7 +505,7 @@ See the current support and verification documents:
 
 ## Documentation
 
-Current TypeScript documentation and examples are the source of truth for the v2 package:
+Current TypeScript documentation and examples are the source of truth for the v3 package:
 
 - Complete docs: [English](https://vextjs.github.io/monSQLize/) · [简体中文](https://vextjs.github.io/monSQLize/zh/)
 - Constructor configuration: [English](https://vextjs.github.io/monSQLize/configuration) · [简体中文](https://vextjs.github.io/monSQLize/zh/configuration)
@@ -514,7 +518,7 @@ Current TypeScript documentation and examples are the source of truth for the v2
 - Compatibility checks: [test/compatibility](https://github.com/vextjs/monSQLize/tree/main/test/compatibility)
 - Verification mapping: [test/validation](https://github.com/vextjs/monSQLize/tree/main/test/validation)
 
-Historical v1 assets are useful for tracing old behavior, but they are not the current publishing surface for v2.
+Historical v1 and v2 assets are useful for tracing old behavior, but they are not the current publishing surface for v3.
 
 ## Development
 

package/changelogs/v3.0.0.md

@@ -1,6 +1,6 @@
 # monSQLize v3.0.0
 
-> Release date: 2026-07-14
+> Release date: 2026-07-15
 > Release status: Released
 > Type: Major
 > Stable predecessor: v2.0.6
@@ -14,7 +14,7 @@ v3.0.0 consolidates the unpublished v2.0.7 work into a major release. It adds bo
 ### Bounded production data tasks
 
 - Added the named `dataTasks` facade with `preview()`, `apply()`, `previewRestore()`, and `restore()` for two independent source/target instances. CommonJS exposes the same root facade through destructuring; it is not an instance API.
-- Added collection-level `indexes[]`, filtered `data`, explicit `fields` / `source-id` identity, deterministic pipeline/handler transforms, approval drift fingerprints, affected-scope BSON backup packages, verification, and reversible restore-safety packages.
+- Added collection-level `indexes[]`, filtered `data`, explicit `fields` / `source-id` identity, deterministic `rename` / `set` / `unset` field adjustments, approval drift fingerprints, affected-scope BSON backup packages, verification, and reversible restore-safety packages.
 - Consolidated data tasks on one `DataTaskJob` contract and the named `dataTasks.preview/apply/previewRestore/restore` service; the unpublished instance runner and step configuration were removed.
 - Consolidated the CLI on `preview`, `apply`, `preview-restore`, and `restore`, with task files directly exporting the same Job configuration.
 - Production apply requires explicit `targetEnvironment`, a durable `backup.dir`, and a non-expired preview approval bound to the job, source, target, and target indexes.
@@ -95,3 +95,5 @@ The release is publishable only when all of the following pass on the release co
 - npm registry, dist-tag, Git tag, GitHub Release, and Pages post-publish acceptance
 
 See the bilingual release preflight guides and production rollout guides for commands and recovery procedures.
+
+> Contract correction (2026-07-15): the original GitHub Release text used the inaccurate phrase “pipeline/handler transforms.” The shipped and documented v3 contract supports only `rename`, `set`, and `unset`. This repository correction is the source for the next patch; editing the already-published GitHub Release remains a separate authorized release-maintenance action.

package/changelogs/v3.1.0-rc.0.md

@@ -0,0 +1,23 @@
+# monSQLize v3.1.0-rc.0
+
+> Release status: Local rehearsal candidate; not published, tagged, pushed, or committed.
+> Candidate date: 2026-07-15
+
+## Purpose
+
+This candidate validates monSQLize against the identity-bound local `schema-dsl@3.0.0-rc.0` tarball. npm `latest` remains `monsqlize@3.0.0`; final `3.1.0` publication requires schema-dsl v3 GA plus the repository's normal release authority and external checks.
+
+## Changes
+
+- Pins the rehearsal dependency to `schema-dsl@3.0.0-rc.0` and continues to use only the isolated `schema-dsl/runtime` integration for Model compilation and validation.
+- Narrows the upstream validation bridge to `valid`, `data`, and canonical `errors[].path/message/keyword`; monSQLize no longer consumes schema-dsl's deprecated `field/type/expected` aliases.
+- Keeps `Model.validate()` public results stable as `{ valid, errors: [{ field, message }], data }`, mapping `field` from upstream `path`.
+- Persists successful normalized `data` for `insertOne`, `insertMany`, `insertBatch`, `replaceOne`, `findOneAndReplace`, and hydrated document `save()`.
+- Applies bulk defaults before before-hooks, performs schema normalization before timestamps/version fields, and validates replacements before optimistic-lock reads.
+- Rejects valid results whose normalized `data` is null, primitive, or an array before any driver operation. Failed validation data snapshots are never written.
+
+## Deliberate boundaries
+
+- Update operators and pipelines do not represent a complete final document and are not included in normalized-data persistence.
+- `isRequired()` / `isOptional()` are not required by monSQLize and are not added to schema-dsl for this migration.
+- This candidate is evidence only. It is not a release authorization and must not be published.

package/changelogs/v3.1.0.md

@@ -0,0 +1,24 @@
+# monSQLize v3.1.0
+
+> Release date: 2026-07-15
+
+## Highlights
+
+- Pins the production dependency to registry `schema-dsl@3.0.0` and continues to compile Model schemas only through the isolated `schema-dsl/runtime` integration.
+- Consumes the canonical schema-dsl validation result (`valid`, normalized `data`, and `errors[].path/message/keyword`) without relying on deprecated upstream `field/type/expected` aliases.
+- Keeps `Model.validate()` compatible for monSQLize callers as `{ valid, errors: [{ field, message }], data }`, deriving `field` from the canonical upstream path.
+- Persists successful normalized data across the six complete-document write paths: `insertOne`, `insertMany`, `insertBatch`, `replaceOne`, `findOneAndReplace`, and hydrated document `save()`.
+- Applies bulk defaults before before-hooks, normalizes before timestamps/version fields, and validates replacement documents before optimistic-lock reads.
+- Rejects null, primitive, or array normalized results before any driver operation; failed validation snapshots are never written.
+- Preserves timestamps on hydrated `save()` when versioning is disabled, including documents normalized by schema-dsl.
+- Includes the maintained Node 24 GitHub Actions runtime, release metadata checks, TypeScript lint coverage, shared memory-server policy, coverage/package/license budgets, derived-artifact dry-run cleanup, and the lightweight data-task CLI bundle introduced after v3.0.0.
+
+## Compatibility boundaries
+
+- Update operators and pipelines are partial mutations, so they are intentionally outside normalized complete-document persistence.
+- `isRequired()` and `isOptional()` are not required by monSQLize; schema definitions already expose the required/optional state needed by this integration.
+- The public monSQLize validation error shape remains stable even though its upstream adapter now consumes schema-dsl's canonical error fields.
+
+## Verification
+
+- The release candidate must pass `npm run release:preflight`, the Node 18/20/22 remote matrix, packed CJS/ESM/TypeScript/CLI consumers, the MongoDB 7/8 server matrix, production dependency audit, and the documentation browser gates.