monsqlize 2.0.6 → 3.1.0

package/SECURITY.md

@@ -0,0 +1,21 @@
+# Security Policy
+
+## Supported Versions / 支持版本
+
+Security fixes target the current published major line and its latest patch.
+For the v3 release line, upgrade to the newest `3.x` patch before reporting.
+Older majors may receive fixes only when the maintainers announce an extended
+support window.
+
+## Reporting a Vulnerability / 报告安全问题
+
+Use [GitHub private vulnerability reporting](https://github.com/vextjs/monSQLize/security/advisories/new).
+Do not open a public issue for an undisclosed vulnerability.
+
+- Include the affected version, minimal reproduction, impact, and any known workaround.
+- Maintainers aim to acknowledge a complete report within 72 hours, then coordinate validation, a fix, and a disclosure window through the private advisory.
+
+## Sensitive Data / 敏感信息与日志
+
+- Do not include credentials, private connection strings, or personal data in public issues, pull requests, examples, or logs.
+- Redact production documents while keeping enough query shape and metadata to reproduce the issue.

package/changelogs/README.md

@@ -10,6 +10,11 @@
 changelogs/
 ├── README.md           # 本说明文档
 ├── TEMPLATE.md         # 变更文档模板
+├── v3.0.0.md          # v3.0.0 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 详细变更
 ├── v2.0.2.md          # v2.0.2 详细变更
 ├── v2.0.1.md          # v2.0.1 详细变更
@@ -46,19 +51,21 @@ changelogs/
 
 ### 按版本类型
 
-- **正式发布**: v2.0.3, v2.0.2, v2.0.1, v2.0.0, v1.0.0
+- **未发布归档**: v2.0.7
+- **正式发布**: v3.0.0, v2.0.6, v2.0.5, v2.0.4, v2.0.3, v2.0.2, v2.0.1, v2.0.0, v1.0.0
 - **功能版本**: v1.x
 - **修复版本**: v1.x.y
 
 ### 按功能领域
 
-- **TypeScript 重构与 v1 平滑升级**: v2.0.3, v2.0.2, v2.0.1, v2.0.0
+- **TypeScript 生产运行时与 v1 平滑升级**: v3.0.0, v2.0.6, v2.0.5, v2.0.4, v2.0.3, v2.0.2, v2.0.1, v2.0.0
 - **实时监听 / 管理功能 / 核心功能**: v1.x 历史版本
 
 ### 按风险级别
 
 - **P0 (Critical)**: v2.0.0
-- **Patch**: v2.0.3, v2.0.2, v2.0.1
+- **Major**: v3.0.0
+- **Patch**: v2.0.6, v2.0.5, v2.0.4, v2.0.3, v2.0.2, v2.0.1
 - **P1 (High)**: v1.x 破坏性或高风险历史版本
 - **P2 (Low)**: v1.x 修复版本
 
@@ -153,6 +160,11 @@ git push origin main --tags
 
 | 版本 | 文件 | 状态 | 发布日期 |
 |------|------|------|---------|
+| v3.0.0 | v3.0.0.md | ✅ 已发布 | 2026-07-14 |
+| v2.0.7 | v2.0.7.md | 未发布归档 | - |
+| v2.0.6 | v2.0.6.md | ✅ 已发布 | 2026-06-15 |
+| v2.0.5 | v2.0.5.md | ✅ 已发布 | 2026-06-13 |
+| v2.0.4 | v2.0.4.md | ✅ 已发布 | 2026-06-12 |
 | v2.0.3 | v2.0.3.md | ✅ 已发布 | 2026-06-11 |
 | v2.0.2 | v2.0.2.md | ✅ 已发布 | 2026-06-09 |
 | v2.0.1 | v2.0.1.md | ✅ 已发布 | 2026-06-03 |
@@ -162,6 +174,6 @@ git push origin main --tags
 ---
 
 **目录版本**: 2.0
-**最后更新**: 2026-06-11
+**最后更新**: 2026-07-10
 **维护者**: monSQLize Team
 

package/changelogs/v2.0.7.md

@@ -0,0 +1,63 @@
+# monSQLize v2.0.7 (unpublished archive)
+
+> Prepared date: 2026-06-16
+> Release status: Never published; superseded by v3.0.0
+> Type: Withdrawn patch candidate
+> Compatibility: Contains compatibility-impacting behavior changes; see below
+
+This candidate must not be tagged or published. Its accumulated public additions and compatibility-impacting changes require a major release, so the canonical release inventory and upgrade guidance moved to [v3.0.0](./v3.0.0.md). The detail below is retained only as historical review evidence.
+
+## Summary
+
+The withdrawn v2.0.7 candidate collected release-readiness work after v2.0.6: model optimistic concurrency, transaction cache invalidation, Change Stream sync ordering, soft-delete read visibility, MongoDB driver option forwarding, batch-write retry behavior, distributed invalidation, and bounded production data tasks.
+
+## Compatibility-impacting changes
+
+- Versioned Model single-document writes now enforce true optimistic concurrency control: stale writes throw `WRITE_CONFLICT`, and writes without `expectedVersion`, `version`, or a direct `_id` automatic lookup path may throw `INVALID_ARGUMENT`.
+- Versioned `updateMany()` defaults to `counter`, which increments version counters without optimistic locking. Use `versionMode: 'strict'` for per-document conditional updates or `versionMode: 'off'` for compatibility behavior.
+- `find()` now defaults to `findLimit: 500`; explicit positive `limit` and `skip` values are bounded by `findMaxLimit` and `findMaxSkip`. `limit(0)` intentionally keeps MongoDB's unlimited cursor semantics.
+- Change Stream resume token persistence is strict by default: token save/load failures stop synchronization unless `strictSave: false` / `strictLoad: false` is configured for legacy best-effort behavior.
+- `updateBatch({ upsert: true })` is rejected because `updateBatch` walks existing matching `_id` values and cannot express MongoDB's single-document `updateMany(..., { upsert: true })` insert semantics. Use `upsertOne()` or native `updateMany(..., { upsert: true })` instead.
+- `dropDatabase()` treats `NODE_ENV=production`, `prod`, and `live` as production-like environments that require `allowProduction: true`.
+- Soft-delete filtering now covers the standard Model read surface including `findPage`, ID reads, `distinct`, `aggregate`, `stream`, and `explain`.
+- Populate `skip` / `limit` for has-many relations is applied per parent document, and nested populate is capped by `maxDepth` (default `5`).
+- `ConnectionPoolManager.addPool()` now applies the same strict pool config validation as the public validator before opening a client.
+- Change Stream `collections: ['*']` now means all collections rather than a literal collection named `*`.
+
+## Changed
+
+- Package metadata now describes monSQLize as a database-native TypeScript data runtime and no longer promotes business locks or Saga orchestration as primary package capabilities.
+- Business lock and Saga documentation remains available for existing callers, but hidden compatibility pages now state the current runtime boundaries and recommend application/framework-level orchestration for new payment/order flows.
+- `npm run test:unit` now delegates to `test/run-tests.cjs unit`, matching the maintained unit suite instead of a stale hand-written file list.
+- Validation ledgers now reflect the current 56 runnable TypeScript documentation examples.
+- `initializeModelV1Methods()` now reports factory failures through the runtime logger when available instead of writing directly to `console.warn`.
+- Versioned models now enforce true optimistic concurrency control for single-document writes: direct `_id` filters automatically read the current version, callers may override with `expectedVersion` / `version`, and stale writes throw `WRITE_CONFLICT`.
+- Versioned `updateMany()` now supports explicit modes: `counter` for native batch version counters, `strict` for per-document conditional updates, and `off` for compatibility escape hatches.
+- Transaction cache invalidations are recorded during the transaction and replayed only after a successful commit; commit retry now handles `UnknownTransactionCommitResult`.
+- Change Stream sync events are processed serially so target writes and resume token persistence stay ordered; resume token files use atomic replacement, strict load validation, and backup files in file mode; unexpected stream close events now mark sync as stopped in stats.
+- Soft-delete filters now cover the standard model read surface, including `findPage`, ID reads, `distinct`, `aggregate`, `stream`, and `explain`.
+- MongoDB read paths now forward driver options such as `session`, `readConcern`, `readPreference`, `collation`, `hint`, `maxTimeMS`, and aggregation options instead of dropping them through a narrow whitelist.
+- Query caches now avoid session-scoped reads and build stable cache keys only from result-shaping options.
+- Distributed cache invalidation now uses separate Redis publish/subscribe connections when a Redis instance is provided and reports subscription failures.
+- Batch insert retry now retries only the failed unordered subset after partial success instead of replaying the full chunk.
+- `find()` now defaults to `findLimit: 500`, validates explicit `limit`/`skip` values against configurable `findMaxLimit` and `findMaxSkip` caps, and documents that `limit(0)` intentionally keeps MongoDB's unlimited semantics.
+- `findPage().offsetJump.maxSkip` is now enforced against the runtime `findMaxSkip` cap before using skip-based page jumps.
+- `dropDatabase()` now treats `NODE_ENV=production`, `prod`, and `live` as production-like environments that require `allowProduction: true`.
+- Aggregate pipelines ending in `$out` or `$merge` now bypass aggregate result caching and invalidate the target collection's read caches after successful execution.
+- Fire-and-forget distributed cache invalidation and transaction timeout abort paths now catch/log failures instead of leaving unhandled rejections.
+- `findPage` cursor anchors now read nested dot-path sort fields correctly, query read helpers accept `project` as a projection alias, and documentation clarifies ObjectId `maxDepth` conversion limits plus process-level Model registration.
+- `updateMany(..., { upsert: true })` documentation now states MongoDB's native no-match branch inserts only one derived document, so it is not a per-input bulk upsert replacement for `updateBatch`.
+- Added `msq.dataTasks` for bounded production tasks: `plan`, `dryRun`, `run`, `verify`, plus helper methods for explicit index sync, filtered data sync, field transforms, affected-document snapshots, and verification.
+- Added the `monsqlize data-task` CLI with `plan`, `dry-run`, `run`, and `verify` actions. Production writes require `--confirm-production`.
+- Added data task docs, production rollout guidance, API index entries, and a runnable `examples/docs/data-tasks.ts` example.
+
+## Verification
+
+- `npm run lint`
+- `npm run check:docs-examples`
+- `npm run type-check`
+- `npm run check:sizes:strict`
+- `npm run test:unit`
+- `npm test`
+- `npm run test:audit`
+- `npm pack --dry-run --json`

package/changelogs/v3.0.0.md

@@ -0,0 +1,99 @@
+# monSQLize v3.0.0
+
+> Release date: 2026-07-15
+> Release status: Released
+> Type: Major
+> Stable predecessor: v2.0.6
+
+## Summary
+
+v3.0.0 consolidates the unpublished v2.0.7 work into a major release. It adds bounded production data tasks, Model-only write-path enforcement, runtime-scoped schema-dsl integration, stricter synchronization and optimistic-locking behavior, and production release controls. The major version is intentional because several defaults and failure contracts are stricter than v2.0.6.
+
+## Public capability inventory
+
+### 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 `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.
+- Write-task environments are restricted to `development`, `test`, `staging`, `production`, `prod`, or `live`; unknown or misspelled names fail planning instead of silently bypassing production gates.
+- Data task locks use a renewable lease in the target database, coordinate separate processes, and stop writes after ownership is lost.
+- Data task planning uses a bounded stream independent of the public `findLimit`, exact write-time document CAS includes unexpected-field detection, and expired local leases fail closed before another write.
+
+### Write-path policy
+
+- Added `writePathPolicy` with permissive `allow-both` default behavior and optional `model-only` enforcement by namespace.
+- Guards cover collection, database, legacy, raw client, management, batch, and aggregate `$out` / `$merge` write paths.
+- Model writes and Model management methods remain available for namespaces assigned to `model-only`.
+
+### Runtime-scoped schema DSL
+
+- Upgraded `schema-dsl` to `2.1.6` and moved Model schema compilation to an isolated `schema-dsl/runtime` owned by each connected monSQLize runtime.
+- Added `schemaDsl` options for runtime options, extension registration, external runtime injection, and explicit validation disablement.
+- External runtimes remain application-owned and are not disposed by `MonSQLize.close()`.
+
+### Model consistency and query bounds
+
+- Versioned single-document writes now use optimistic concurrency control. Stale writes throw `WRITE_CONFLICT`.
+- Added `updateMany()` / `updateBatch()` version modes: `counter`, `strict`, and `off` where supported.
+- `find()` now defaults to `findLimit: 500`; positive `limit` and `skip` values are bounded by `findMaxLimit` and `findMaxSkip`. `limit(0)` keeps MongoDB's unlimited cursor semantics.
+- Soft-delete filtering now covers the standard Model read surface, including `findPage`, ID reads, `distinct`, `aggregate`, `stream`, and `explain`.
+- Populate has-many `skip` / `limit` is applied per parent and nested populate is capped by `maxDepth` (default `5`).
+
+### Synchronization, cache, and operational safety
+
+- Change Stream targets are processed in order; resume-token persistence is atomic and strict by default.
+- Added optional per-target sync idempotency gates and explicit failure/restart state handling.
+- Transaction cache invalidations are replayed after successful commit; query caches skip session-scoped reads and avoid refill during write-side invalidation barriers.
+- `autoIndex: true` preflights with `listIndexes()`, skips matching indexes, creates only missing indexes, and reports conflicts without dropping or rebuilding indexes.
+- `dropDatabase()` treats `production`, `prod`, and `live` as production-like environments requiring `allowProduction: true`.
+- Data-task apply and restore use before/current-image compare-and-set filters, bounded source and backup sizes, ordered manifest checkpoint batches, and fsync-backed atomic backup files.
+- Saga step timeouts use `OPERATION_TIMEOUT`, abort the cooperative context signal, and never trigger retries; failed runtime connection attempts await partial resource cleanup before returning.
+- Runtime dependencies are pinned to `schema-dsl@2.1.6` and `ioredis@5.11.1`; Node 18-compatible test tooling uses `mongodb-memory-server@10.4.3`.
+- The release server matrix now strictly requires MongoDB 7.0.37 and 8.0.26 across standalone, replica-set, Driver 6/7, and DataTask integration paths; unavailable combinations fail release preflight instead of being recorded as a successful skip.
+- Release candidates must be clean, have a valid installed dependency graph, and already exist on `origin`; the same preflight also verifies the docs site and packaged `MIGRATION.md` / `SECURITY.md` consumer guidance.
+- A manual pre-tag authentication workflow verifies the repository's current npm publish credential with `npm whoami` without creating a tag or publishing.
+- Build and test artifact cleanup retries transient Windows filesystem contention, so repeated release-gate compilation does not fail on short-lived `ENOTEMPTY`, `EPERM`, or `EBUSY` races.
+- GitHub workflows use `actions/setup-node@v6`, avoiding the retired Node 20 action runtime while preserving the explicit Node 18/20/22 package test matrix.
+- Stable Pages deployment separates immutable release-tag content from current release tooling, so historical stable tags can rebuild their tagged docs with the current audited website toolchain and link gate without deploying unpublished branch content; current releases still require the complete website verification chain.
+
+## Compatibility-impacting changes
+
+Review these changes before upgrading from v2.0.6:
+
+1. Versioned Model single-document writes can now throw `WRITE_CONFLICT` or `INVALID_ARGUMENT` where v2 behavior could write without a usable expected version.
+2. Versioned `updateMany()` defaults to `counter`; choose `strict` for per-document conditional writes or `off` for compatibility behavior.
+3. `find()` applies a default limit of 500 and validates positive limits/skips against configured caps.
+4. Resume-token load/save failures stop Change Stream synchronization unless legacy best-effort options are selected explicitly.
+5. `updateBatch({ upsert: true })` is rejected. Use `upsertOne()` or native `updateMany(..., { upsert: true })` according to the required insert semantics.
+6. `dropDatabase()` has a broader production-like environment guard.
+7. Soft-delete reads, has-many populate paging, nested populate depth, pool validation, and wildcard Change Stream collection filters now follow the documented stricter behavior.
+8. Production Jobs require `preview -> approval -> apply`, a durable affected-scope backup directory, and a new preview after any source/target/index drift.
+
+## Upgrade checklist
+
+1. Run the complete release preflight on the exact commit to be tagged.
+2. Audit versioned Model writes and select an explicit batch version mode where the default is not desired.
+3. Review services that depend on unlimited `find()` results and configure bounded limits deliberately.
+4. Decide whether Change Stream resume-token persistence should remain strict; document any best-effort override.
+5. Inventory direct write paths before enabling `writePathPolicy: { default: 'model-only' }`.
+6. Keep `autoIndex: false` in production rollout paths unless startup-time asynchronous creation is deliberately accepted; use data-task index plans for reviewed production changes.
+7. For historical data changes, follow `preview -> review -> apply`; use `previewRestore -> restore` only when rollback is required, and retain the full database restore point until acceptance completes.
+
+## Release acceptance
+
+The release is publishable only when all of the following pass on the release commit:
+
+- lint, docs-example coverage, TypeScript/tsd checks, strict file-size checks
+- complete unit/integration suites and source coverage thresholds
+- examples and MongoDB server matrix
+- real dataTasks and CLI integration probes
+- package dry-run plus temporary-install CJS, ESM, dataTasks, schema-dsl, types, MIGRATION/SECURITY, bin, help, and version smoke tests
+- clean-install docs-site type, build, internal-link, and dependency-audit verification
+- 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.