monsqlize 2.0.5 → 3.0.0

package/README.md

@@ -1,6 +1,6 @@
 # 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)
@@ -8,45 +8,64 @@ TypeScript-native MongoDB ODM and enhancement layer with v1-compatible APIs, mul
 [![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.
 
 ```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 v2 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 +73,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 +88,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 +122,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 +148,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:
@@ -153,7 +170,7 @@ The package root exports only the public package contract. Deep imports into his
 
 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 +179,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 +215,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 +232,58 @@ 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.
+
 ### 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 +304,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 +371,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 +392,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 +430,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 +445,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 +459,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:
@@ -446,7 +484,7 @@ The v2 line has been validated against the workspace consumers `chat`, `payment`
 | 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 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. |
 | Module systems | CommonJS and ESM are both validated. |
 | TypeScript | Public declarations are published from `dist/types/index.d.ts`. |
@@ -456,9 +494,8 @@ 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)
 
@@ -467,12 +504,15 @@ See the current support and verification documents:
 Current TypeScript documentation and examples are the source of truth for the v2 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.
+- 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 assets are useful for tracing old behavior, but they are not the current publishing surface for v2.
 
@@ -495,9 +535,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,76 +547,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.
-
-`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.
+`check:docs-examples` verifies the bilingual documentation matrix, runnable-example runner parity, shared-example targets, doc-check targets, and user-facing path text.
 
-## Release Status
+`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.
 
-The current published release is `v2.0.4`.
-
-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.9`; 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.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).