monsqlize 2.0.6 → 3.1.0

package/README.md

@@ -1,52 +1,73 @@
 # monSQLize
 
-TypeScript-native MongoDB ODM and enhancement layer with v1-compatible APIs, multi-level caching, distributed locks, transactions, Saga orchestration, model validation, connection pools, Change Stream sync, slow-query logging, and CommonJS / ESM / TypeScript declaration outputs.
+Database-native production data runtime layer for TypeScript services. monSQLize keeps database semantics explicit while adding shared runtime capabilities for caching, transactions, connection pools, models, synchronization, observability, and CommonJS / ESM / TypeScript declaration outputs.
 
 [![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/)
+Quick path: [Installation](https://vextjs.github.io/monSQLize/getting-started) · [Basic Usage](https://vextjs.github.io/monSQLize/basic-operations)
+Configuration reference: [English](https://vextjs.github.io/monSQLize/configuration) · [简体中文](https://vextjs.github.io/monSQLize/zh/configuration)
+Upgrade and security: [Migration Guide](./MIGRATION.md) · [Private Vulnerability Reporting](./SECURITY.md)
+
+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
 ```
 
-monSQLize is currently a MongoDB-focused package. The long-term product direction is to keep the MongoDB-style query experience while gradually extending the same high-level API shape to additional database backends.
-
-## Table of Contents
-
-- [Why monSQLize](#why-monsqlize)
-- [When to Use It](#when-to-use-it)
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Model Layer](#model-layer)
-- [Caching and Performance](#caching-and-performance)
-- [Advanced Capabilities](#advanced-capabilities)
-- [Migration from the MongoDB Driver](#migration-from-the-mongodb-driver)
-- [Compatibility](#compatibility)
-- [Documentation](#documentation)
-- [Development](#development)
-- [Release Status](#release-status)
-- [Roadmap](#roadmap)
-- [License](#license)
-- [Support](#support)
+MongoDB is the first complete adapter. MySQL and PostgreSQL adapters are planned as database-native runtime adapters, not as a transparent promise that every database already accepts the same query syntax.
 
 ## Why monSQLize
 
-monSQLize keeps the MongoDB driver mental model while adding the production features most teams end up building around it:
+monSQLize is not an ORM and it is not just a CRUD wrapper. It is a production data runtime layer: the database driver remains visible, while the operational features teams usually build around the driver are provided in one runtime.
 
-- 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.
+- Database-native adapter APIs: the current stable adapter preserves MongoDB-style CRUD, aggregation, indexes, transactions, and Change Streams.
+- Smart database caching through `cache-hub`, including local memory caching, optional Redis-backed L2 caching, and automatic invalidation.
 - 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.
 - Change Stream sync helpers with resume token storage.
 - Slow-query logging and query diagnostics.
 - CommonJS, ESM, and TypeScript declaration outputs from `dist/**`.
 
+## Adapter Status
+
+| Adapter | Current status | Public entry |
+|---|---|---|
+| MongoDB | Stable and fully implemented | `type: 'mongodb'`, `collection()`, `db()`, `use()`, `pool()` |
+| MySQL | Planned / in development | Not part of the current npm runtime yet |
+| PostgreSQL | Planned / in development | Not part of the current npm runtime yet |
+
+The shared runtime direction is cache consistency, connection lifecycle, transaction helpers, model constraints, synchronization, and observability across adapters. Adapter-native query, transaction, and connection semantics will stay explicit.
+
+## 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 current v3 runtime; use explicit business coordination, idempotency/fencing, or cache bypassing for cross-instance strict flows.
+
+## Write Path Policy
+
+By default, both `collection()` and `model()` may write. Applications that want all writes for selected namespaces to pass through Model defaults, hooks, timestamps, versioning, and soft-delete rules can enable `writePathPolicy`.
+
+```ts
+const msq = new MonSQLize({
+  type: 'mongodb',
+  databaseName: 'app',
+  config: { uri: 'mongodb://localhost:27017' },
+  writePathPolicy: {
+    default: 'model-only',
+    namespaces: {
+      'app.audit_logs': 'allow-both'
+    }
+  }
+});
+```
+
+`model-only` blocks direct collection/db/legacy write surfaces by default, including raw access and `$out` / `$merge` aggregate writes, while Model write and Model management methods remain available. See [Write Path Policy](./docs/en/write-path-policy.md).
+
 ## When to Use It
 
 monSQLize is a good fit when you need:
@@ -54,8 +75,9 @@ monSQLize is a good fit when you need:
 | Scenario | Benefit |
 |---|---|
 | High-concurrency reads | Cache hot data and reduce repeated database work. |
-| MongoDB API compatibility | Keep familiar query syntax while adding higher-level helpers. |
-| Multi-instance services | Use Redis invalidation and distributed locks to keep instances coordinated. |
+| MongoDB API compatibility today | Keep familiar MongoDB syntax while adding higher-level runtime helpers. |
+| A future multi-database runtime boundary | Prepare for MySQL/PostgreSQL adapters without turning SQL into fake MongoDB syntax. |
+| Multi-instance services | Use Redis invalidation and pool health checks to keep instances coordinated. |
 | Transaction-heavy flows | Use `withTransaction()` and transaction-aware helpers instead of hand-rolled lifecycle code. |
 | Model-level ergonomics | Add schema validation, hooks, populate, and custom methods only where needed. |
 | Smooth upgrade from v1 | Keep legacy application source stable while adopting the TypeScript rewrite. |
@@ -68,37 +90,32 @@ monSQLize is usually not the best first choice for pure write-heavy workloads, e
 npm install monsqlize
 ```
 
-Runtime dependencies installed with the package:
-
-- `mongodb` - official MongoDB driver.
-- `schema-dsl` - model schema validation runtime dependency.
-- `cache-hub` - cache and function-cache foundation.
-- `async-lock` - local concurrency lock support.
-- `ioredis` - Redis-backed L2 cache, distributed invalidation, and distributed lock support.
-- `ssh2` - SSH tunnel support for restricted/private network deployment.
+Use Node.js 18 or newer and provide a MongoDB connection URI. Optional Redis, SSH tunnel, cache, Model, and sync features are configured only when your application enables them.
 
 ## Quick Start
 
+The current stable quick start uses the MongoDB adapter.
+
 ### CommonJS
 
 ```js
 const MonSQLize = require('monsqlize');
 
-const db = new MonSQLize({
+const msq = new MonSQLize({
   type: 'mongodb',
   databaseName: 'mydb',
   config: {
     uri: 'mongodb://localhost:27017'
   },
   cache: {
-    enabled: true,
-    ttl: 60_000
+    maxEntries: 10000,
+    defaultTtl: 60_000
   }
 });
 
-await db.connect();
+await msq.connect();
 
-const users = db.collection('users');
+const users = msq.collection('users');
 
 await users.insertOne({
   username: 'john',
@@ -107,23 +124,25 @@ await users.insertOne({
 });
 
 const user = await users.findOne({ email: 'john@example.com' });
-const userById = await users.findOneById('507f1f77bcf86cd799439011');
+const sameUser = await users.findOne({ _id: '507f1f77bcf86cd799439011' });
 
 await users.updateOne(
   { email: 'john@example.com' },
   { $set: { lastLoginAt: new Date() } }
 );
 
-await db.close();
+await msq.close();
 ```
 
+Next, use the [Basic Usage guide](https://vextjs.github.io/monSQLize/basic-operations) for common CRUD, pagination, read cache, and Model entry-point examples.
+
 ### ESM and TypeScript
 
 ```ts
 import MonSQLize from 'monsqlize';
 import type { Collection } from 'monsqlize';
 
-const db = new MonSQLize({
+const msq = new MonSQLize({
   type: 'mongodb',
   databaseName: 'mydb',
   config: {
@@ -131,12 +150,12 @@ const db = new MonSQLize({
   }
 });
 
-await db.connect();
+await msq.connect();
 
-const users: Collection = db.collection('users');
+const users: Collection = msq.collection('users');
 const activeUsers = await users.find({ status: 'active' }).toArray();
 
-await db.close();
+await msq.close();
 ```
 
 Published entry points:
@@ -147,13 +166,13 @@ 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
 
 The Model layer is optional. Use it when you want schema validation, hooks, relations, populate, custom methods, timestamps, soft delete, or optimistic locking.
 
-`schema-dsl` is installed automatically as a runtime dependency of monSQLize. You only need to declare `schema-dsl` in your own app if your application imports it directly.
+Models use the current `schema-dsl/runtime` path through monSQLize. monSQLize creates an isolated schema runtime for each `MonSQLize` instance, then compiles Model schema callbacks when a Model is bound to that runtime.
 
 ### Manual Model Registration
 
@@ -162,7 +181,7 @@ const MonSQLize = require('monsqlize');
 const { Model } = MonSQLize;
 
 Model.define('users', {
-  schema: (dsl) => dsl({
+  schema: (s) => s({
     username: 'string:3-32!',
     email: 'email!',
     password: 'string:6-!',
@@ -198,15 +217,15 @@ Model.define('users', {
   })
 });
 
-const db = new MonSQLize({
+const msq = new MonSQLize({
   type: 'mongodb',
   databaseName: 'mydb',
   config: { uri: 'mongodb://localhost:27017' }
 });
 
-await db.connect();
+await msq.connect();
 
-const User = db.model('users');
+const User = msq.model('users');
 const user = await User.insertOne({
   username: 'john',
   email: 'john@example.com',
@@ -215,29 +234,60 @@ const user = await User.insertOne({
 });
 ```
 
+When a service needs runtime-local custom types, messages, locale, or an already-owned schema-dsl runtime, configure `schemaDsl` on the MonSQLize instance:
+
+```js
+const { createRuntime } = require('schema-dsl/runtime');
+
+const schemaRuntime = createRuntime({
+  types: {
+    tenantId: { type: 'string', pattern: '^tenant_[a-z0-9]+$' }
+  }
+});
+
+Model.define('tenantUsers', {
+  schema: (s) => s({
+    tenantId: 'tenantId!',
+    email: 'email!'
+  })
+});
+
+const msq = new MonSQLize({
+  type: 'mongodb',
+  databaseName: 'mydb',
+  config: { uri: 'mongodb://localhost:27017' },
+  schemaDsl: { runtime: schemaRuntime }
+});
+```
+
+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
 const path = require('path');
 const MonSQLize = require('monsqlize');
 
-const db = new MonSQLize({
+const msq = new MonSQLize({
   type: 'mongodb',
   databaseName: 'mydb',
   config: { uri: 'mongodb://localhost:27017' },
   models: path.join(__dirname, 'models')
 });
 
-await db.connect();
+await msq.connect();
 
-const User = db.model('users');
+const User = msq.model('users');
 ```
 
 ```js
 // models/user.model.js
 module.exports = {
   name: 'users',
-  schema: (dsl) => dsl({
+  schema: (s) => s({
     username: 'string:3-32!',
     email: 'email!'
   }),
@@ -258,27 +308,56 @@ Relative model paths are resolved from `process.cwd()`. In production services,
 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({
+const msq = new MonSQLize({
   type: 'mongodb',
   databaseName: 'mydb',
   config: { uri: 'mongodb://localhost:27017' },
   autoIndex: false
 });
 
-const plan = await db.ensureModelIndexes({ models: ['users'], dryRun: true });
+const plan = await msq.ensureModelIndexes({ models: ['users'], dryRun: true });
 
 if (plan.totals.conflicts === 0) {
-  await db.ensureModelIndexes({ models: ['users'], throwOnError: true });
+  await msq.ensureModelIndexes({ models: ['users'], throwOnError: true });
 }
 ```
 
 `ensureModelIndexes()` creates only missing indexes. It does not drop, rename, or rebuild conflicting indexes.
 
+### Versioned Writes
+
+Models with `options.version` use single-document optimistic concurrency control. When the filter contains a direct `_id`, monSQLize reads the current version automatically. You can still pass an explicit version in the filter or as `expectedVersion` when you want to control the expected version yourself:
+
+```js
+await User.updateOne(
+  { _id: userId },
+  { $set: { status: 'active' } }
+);
+
+await User.replaceOne(
+  { _id: userId },
+  nextUser,
+  { expectedVersion: user.version }
+);
+```
+
+Successful `save()`, `updateOne()`, `replaceOne()`, `findOneAndUpdate()`, and `findOneAndReplace()` advance the version. Stale writes throw a `WRITE_CONFLICT` error.
+
+For `updateMany()` and `updateBatch()`, choose the batch version behavior explicitly when needed:
+
+```js
+await User.updateMany({ status: 'pending' }, { $set: { status: 'active' } }, {
+  versionMode: 'strict' // 'counter' | 'strict' | 'off'
+});
+```
+
+`counter` is the default and only increments the version counter; it is not optimistic locking. `strict` pre-reads matching document IDs and versions, conditionally updates each document, and returns `conflictCount` / `conflictedIds` on the result object.
+
 ### Populate
 
 ```js
 Model.define('posts', {
-  schema: (dsl) => dsl({
+  schema: (s) => s({
     title: 'string:1-200!',
     content: 'string!',
     userId: 'objectId!'
@@ -296,12 +375,20 @@ const userWithPosts = await User.findOne({ username: 'john' })
 
 Populate is supported by `find()`, `findOne()`, `findByIds()`, `findOneById()`, `findAndCount()`, and `findPage()`.
 
+For has-many relations, `skip` and `limit` are applied per parent document after related records are grouped. Nested populate has a default `maxDepth` of `5`; set `maxDepth` on a populate branch when a self-referencing relation needs a different cap.
+
+### Soft Delete Visibility
+
+When `softDelete` is enabled, standard model read paths hide deleted documents by default: `find()`, `findOne()`, `findOneById()`, `findByIds()`, `findPage()`, `findAndCount()`, `count()`, `distinct()`, `aggregate()`, `stream()`, and `explain()`. Pass `withDeleted: true` to include deleted documents or `onlyDeleted: true` to query only deleted documents.
+
+For aggregation, monSQLize prepends a soft-delete `$match` stage before the user pipeline, or after `$geoNear` when that stage is first. Soft-delete filtering inside user-authored `$lookup` pipelines remains the application's responsibility.
+
 ## Caching and Performance
 
-monSQLize can cache collection queries and arbitrary async functions.
+monSQLize can cache collection queries and coordinate local/Redis-backed invalidation for database runtime usage.
 
 ```js
-const users = db.collection('users');
+const users = msq.collection('users');
 
 const hotUser = await users.findOne(
   { email: 'john@example.com' },
@@ -309,51 +396,36 @@ const hotUser = await users.findOne(
 );
 ```
 
-```js
-const { withCache } = require('monsqlize');
-
-async function getUserProfile(userId) {
-  const user = await db.collection('users').findOneById(userId);
-  const orders = await db.collection('orders').find({ userId }).toArray();
-  return { user, orders };
-}
-
-const cachedGetUserProfile = withCache(getUserProfile, {
-  ttl: 300_000,
-  cache: db.getCache()
-});
-
-await cachedGetUserProfile('user-1');
-```
-
 Cache capabilities include:
 
 - In-memory L1 cache.
 - Optional Redis-backed L2 cache.
 - Automatic invalidation after writes.
-- Function-level caching through `withCache()`.
-- In-flight request deduplication.
-- Namespaces, TTLs, statistics, and conditional caching.
+- Cache namespace, TTL, and distributed invalidation controls.
 
 ## Advanced Capabilities
 
 ### Transactions
 
 ```js
-await db.withTransaction(async (session) => {
-  await db.collection('orders').insertOne({ userId, status: 'pending' }, { session });
-  await db.collection('users').updateOne(
+await msq.withTransaction(async (tx) => {
+  await msq.collection('orders').insertOne({ userId, status: 'pending' }, { session: tx.session });
+  await msq.collection('users').updateOne(
     { _id: userId },
     { $inc: { orderCount: 1 } },
-    { session }
+    { session: tx.session }
   );
 });
 ```
 
+Read options such as `session`, `readConcern`, `readPreference`, `collation`, `hint`, `maxTimeMS`, and `allowDiskUse` are forwarded to the MongoDB driver. Query caches are bypassed while a `session` is present, so transaction reads use the driver snapshot instead of a shared cache entry.
+
+Transaction cache invalidations are recorded during the transaction and flushed only after a successful commit. If the transaction aborts, pending invalidations are discarded.
+
 ### Connection Pools
 
 ```js
-const db = new MonSQLize({
+const msq = new MonSQLize({
   type: 'mongodb',
   databaseName: 'main',
   config: { uri: 'mongodb://primary:27017' },
@@ -362,24 +434,13 @@ const db = new MonSQLize({
   ]
 });
 
-const reports = db.pool('analytics').collection('reports');
-```
-
-### Distributed Locks
-
-```js
-await db.withLock('inventory:sku-1', async () => {
-  await db.collection('inventory').updateOne(
-    { sku: 'sku-1' },
-    { $inc: { stock: -1 } }
-  );
-});
+const reports = msq.pool('analytics').collection('reports');
 ```
 
 ### Change Streams
 
 ```js
-const watcher = db.collection('orders').watch([
+const watcher = msq.collection('orders').watch([
   { $match: { 'fullDocument.status': 'pending' } }
 ]);
 
@@ -388,25 +449,6 @@ watcher.on('change', (change) => {
 });
 ```
 
-### Saga Orchestration
-
-```js
-db.defineSaga('checkout', [
-  {
-    name: 'reserveInventory',
-    execute: async (ctx) => reserveInventory(ctx),
-    compensate: async (ctx) => releaseInventory(ctx)
-  },
-  {
-    name: 'chargePayment',
-    execute: async (ctx) => chargePayment(ctx),
-    compensate: async (ctx) => refundPayment(ctx)
-  }
-]);
-
-await db.executeSaga('checkout', { orderId });
-```
-
 ## Migration from the MongoDB Driver
 
 The smallest migration is usually to replace only initialization:
@@ -421,15 +463,15 @@ const nativeUsers = nativeClient.db('mydb').collection('users');
 ```js
 const MonSQLize = require('monsqlize');
 
-const db = new MonSQLize({
+const msq = new MonSQLize({
   type: 'mongodb',
   databaseName: 'mydb',
   config: { uri: 'mongodb://localhost:27017' },
   cache: { enabled: true }
 });
 
-await db.connect();
-const users = db.collection('users');
+await msq.connect();
+const users = msq.collection('users');
 ```
 
 MongoDB-style collection calls can remain unchanged in most cases:
@@ -439,15 +481,15 @@ 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
 
 | Surface | Current Support |
 |---|---|
 | Node.js | `>=18.0.0`; CI covers Node 18 / 20 / 22. |
-| MongoDB driver | `mongodb@6.21.0` runtime baseline; driver 7.2.0 has additional compatibility coverage. |
-| MongoDB server | Memory-server based 6.x / 7.x validation is covered by the project test matrix. |
+| MongoDB driver | `mongodb@6.21.0` runtime baseline; driver 7.5.0 has additional compatibility coverage. |
+| 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. |
@@ -456,25 +498,27 @@ See the current support and verification documents:
 
 - [English documentation](https://github.com/vextjs/monSQLize/blob/main/docs/en/README.md)
 - [Chinese documentation](https://github.com/vextjs/monSQLize/blob/main/docs/zh/README.md)
-- [English recipes](https://github.com/vextjs/monSQLize/blob/main/docs/en/recipes.md)
+- [English common scenarios](https://github.com/vextjs/monSQLize/blob/main/docs/en/recipes.md)
 - [Support matrix](https://github.com/vextjs/monSQLize/blob/main/docs/en/support-matrix.md)
-- [Verification entry points](https://github.com/vextjs/monSQLize/blob/main/docs/en/verification-entrypoints.md)
 - [test/compatibility/README.md](https://github.com/vextjs/monSQLize/blob/main/test/compatibility/README.md)
 - [test/validation/VERIFICATION-PROGRESS.md](https://github.com/vextjs/monSQLize/blob/main/test/validation/VERIFICATION-PROGRESS.md)
 
 ## 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/)
-- `docs/en/**` - default English documentation.
-- `docs/zh/**` - Simplified Chinese documentation.
-- `docs/en/recipes.md` / `docs/zh/recipes.md` - shortest copy-ready paths for common setup scenarios.
-- `examples/**` - TypeScript examples.
-- `test/compatibility/**` - package exports and compatibility guards.
-- `test/validation/**` - verification ledgers and mapping notes.
-
-Historical v1 assets are useful for tracing old behavior, but they are not the current publishing surface for v2.
+- Constructor configuration: [English](https://vextjs.github.io/monSQLize/configuration) · [简体中文](https://vextjs.github.io/monSQLize/zh/configuration)
+- Production rollout: [English](https://vextjs.github.io/monSQLize/production-rollout) · [简体中文](https://vextjs.github.io/monSQLize/zh/production-rollout)
+- Production data migration: [English](https://vextjs.github.io/monSQLize/production-data-migration) · [简体中文](https://vextjs.github.io/monSQLize/zh/production-data-migration)
+- Data tasks API: [English](https://vextjs.github.io/monSQLize/data-tasks) · [简体中文](https://vextjs.github.io/monSQLize/zh/data-tasks)
+- Common scenarios: [English](https://vextjs.github.io/monSQLize/recipes) · [简体中文](https://vextjs.github.io/monSQLize/zh/recipes)
+- Example source: [examples index](https://github.com/vextjs/monSQLize/blob/main/examples/README.md)
+- Documentation source: [docs/en](https://github.com/vextjs/monSQLize/tree/main/docs/en) · [docs/zh](https://github.com/vextjs/monSQLize/tree/main/docs/zh)
+- 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 and v2 assets are useful for tracing old behavior, but they are not the current publishing surface for v3.
 
 ## Development
 
@@ -495,9 +539,9 @@ npm run verify:full
 npm run release:preflight
 ```
 
-Release preflight runs linting, type checks, size guards, runtime checks, compatibility checks, refactor guards, production dependency audit, the default test suite, and `npm pack --dry-run`.
+The package self-check command runs linting, documentation/type/size/runtime/compatibility/refactor guards, the default test suite, 90% source coverage, all runnable examples, the MongoDB server matrix, real dataTasks and CLI integration, production dependency audit, a temporary package-install smoke, and a final `npm pack --dry-run`.
 
-`npm run release:publish` runs the preflight gate once and then calls `npm publish --ignore-scripts` so the final publish step does not repeat the full lifecycle gate. Raw `npm publish` is still guarded by `prepublishOnly`.
+`npm run release:publish` runs the package self-check once and then calls `npm publish --ignore-scripts` so the final publish step does not repeat the full lifecycle check. Raw `npm publish` is still guarded by `prepublishOnly`.
 
 Optional commands:
 
@@ -507,82 +551,30 @@ npm run test:examples
 npm run test:coverage
 npm run test:audit
 npm run test:server-matrix
+npm run test:data-tasks:integration
+npm run test:data-task-cli
+npm run test:pack-install
 npm run test:real-env:private
 ```
 
-`check:docs-examples` verifies the 97/97 bilingual documentation matrix, runnable-example runner parity, shared-example targets, doc-check targets, and user-facing path text.
-
-`test:examples`, `test:server-matrix`, and `config.useMemoryServer` use a fixed `mongodb-memory-server` policy: MongoDB `7.0.14` by default, binaries cached under `.cache/mongodb-memory-server/binaries`, and temporary data paths created under `.cache/mongodb-memory-server/db` with forced cleanup for project-managed paths. Stale managed data paths whose owner PID is no longer alive are pruned before new memory-server launches. Override with `MONSQLIZE_MEMORY_MONGO_BINARY_VERSION`, `MONSQLIZE_REPLSET_BINARY_VERSION`, `MONGOMS_DOWNLOAD_DIR`, or `MONSQLIZE_MEMORY_SERVER_DB_DIR` when needed.
+`check:docs-examples` verifies the bilingual documentation matrix, runnable-example runner parity, shared-example targets, doc-check targets, and user-facing path text.
 
-`test:coverage` is the independent 90% coverage governance gate for the published CJS runtime artifact. `test:audit` checks production dependencies against the npm registry. `test:real-env:private` is intentionally opt-in and expects private environment variables. Coverage and private real-environment checks are not part of the default CI or release gate.
+`test:examples`, `test:server-matrix`, and `config.useMemoryServer` use a fixed `mongodb-memory-server` policy: MongoDB `7.0.37` by default, binaries cached under `.cache/mongodb-memory-server/binaries`, and temporary data paths created under `.cache/mongodb-memory-server/db` with forced cleanup for project-managed paths. The release matrix strictly requires MongoDB `7.0.37` and `8.0.26`; a missing binary, failed probe, or failed combination exits nonzero. Stale managed data paths whose owner PID is no longer alive are pruned before new memory-server launches. Override with `MONSQLIZE_MEMORY_MONGO_BINARY_VERSION`, `MONSQLIZE_REPLSET_BINARY_VERSION`, `MONGOMS_DOWNLOAD_DIR`, or `MONSQLIZE_MEMORY_SERVER_DB_DIR` when needed.
 
-## Release Status
-
-The current release train targets `v2.0.6`.
-
-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.11`; 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.
+`test:coverage` remains an independently runnable 90% governance command for the published CJS runtime plus source-level gap coverage resolved through sourcemaps, and the single-source release preflight requires it. Public CI runs that same preflight in its release-gate job. `test:audit` checks production dependencies against the npm registry. Only `test:real-env:private` remains opt-in because it expects private environment variables.
 
 ## Roadmap
 
-### v2.0.6
-
-- Dependency alignment to `schema-dsl@2.0.11`, carrying the shared ESM/CJS custom type registry fix to downstream vext applications.
-- NodeNext declaration compatibility for ESM consumers through generated `*.d.mts` mirrors and import-side `types` conditions.
-- Restored v1-compatible root option type exports.
-
-### 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.
-- Public transaction and distributed cache invalidator statistics APIs.
-- Standalone documentation-site link safety and bilingual docs consistency fixes.
-- Release preflight alignment for bilingual docs paths and production dependency audit.
-
-### v2.0.2
-
-- Deterministic dependency metadata patch.
-- `ioredis` and `ssh2` are installed with monSQLize by default, so Redis-backed cache/locks and SSH tunnels no longer require a separate dependency install step.
-
-### 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.
-- v1 smooth-upgrade compatibility bridge.
-- Multi-level cache and function-cache support through `cache-hub`.
-- Transactions, business locks, distributed locks, Saga orchestration, connection pools, Change Stream sync, and slow-query logging.
-- Model layer with `schema-dsl` validation, relations, populate, hooks, and custom methods.
-
-### v2.x
-
+- MongoDB remains the stable adapter and the current production runtime.
+- MySQL and PostgreSQL adapters will be introduced as database-native adapters under the same production runtime contract.
+- Adapter status will move from planned to alpha/stable only after runtime support, public types, examples, and verification coverage are present.
+- The project does not currently promise production-ready "one query syntax automatically adapts to every database" behavior.
 - Query analyzer improvements.
 - Automatic index suggestions.
-- Migration tooling.
+- Additional data-task observability and large-scope operational probes.
 - GraphQL integration experiments.
 - More real-environment validation coverage.
 
-### v3.0+
-
-- Unified API experiments for MySQL.
-- Unified API experiments for PostgreSQL.
-- Broader ORM capabilities.
-- Cross-database sync middleware.
-
 ## License
 
 monSQLize is released under the [Apache License 2.0](./LICENSE).