feat: use schema-dsl runtime for model validation

Author: rockyshi1993

README.md

@@ -189,7 +189,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.
+`schema-dsl` is installed automatically as a runtime dependency of monSQLize. monSQLize creates an isolated `schema-dsl/runtime` instance for each `MonSQLize` runtime, then compiles Model schema callbacks when a Model is bound to that runtime.
 
 ### Manual Model Registration
 
@@ -251,6 +251,34 @@ 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: (dsl) => dsl({
+    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.
+
 ### Automatic Model Loading
 
 ```js
@@ -573,7 +601,7 @@ Key release-readiness 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.
+- `schema-dsl` follows the npm `latest` TypeScript line `schema-dsl@2.1.1`; 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.
 
 ## Roadmap
@@ -593,9 +621,13 @@ Key release-readiness points:
 - Validation ledgers now match the current 56 runnable TypeScript documentation examples.
 - Model v1 methods factory warnings now route through the runtime logger instead of direct console output.
 
+### v2.0.8
+
+- Model schema validation now uses an isolated `schema-dsl/runtime` instance per MonSQLize runtime, with `schemaDsl` configuration for runtime options, extension registration, runtime injection, and validation disablement.
+
 ### v2.0.6
 
-- Dependency alignment to `schema-dsl@2.0.11`, carrying the shared ESM/CJS custom type registry fix to downstream vext applications.
+- Dependency alignment carried the shared schema-dsl 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.
 

changelogs/unreleased.md

@@ -15,6 +15,7 @@
 ## Fixed / changed
 
 - Fixed aggregate direct `.toArray()` to honor cache/meta execution paths, extended `find()` ObjectId auto-conversion to comparison operators, forwarded CountQueue abort signals into MongoDB count options, and added a warning when sync idempotency falls back to in-memory storage.
+- Upgraded `schema-dsl` to `2.1.1` and moved Model schema compilation/validation onto a MonSQLize runtime-scoped `schema-dsl/runtime` engine. `schemaDsl` now supports runtime options, extension registration, external runtime injection, and validation disablement.
 - Added a short-lived read-cache dirty barrier around writes and transaction commits. Cached reads now bypass and avoid refilling query cache while a namespace is being invalidated, reducing stale-cache windows when a process exits between a database write and post-write invalidation.
 - Added optional Change Stream sync idempotency gates (`sync.idempotency`) with per-target keys and duplicate stats, so supervised restarts can skip targets already marked as applied before saving the shared resume token.
 - Added `writePathPolicy` with default `allow-both` behavior and optional `model-only` namespace enforcement across collection, db, legacy, raw, management, batch, and aggregate `$out` / `$merge` write paths.

docs/en/file-dependency-governance.md

@@ -4,10 +4,10 @@ The current root package adopts the **precise version dependency strategy**:
 
 | Dependencies | Strategy | Reasons |
 |------|------|------|
-| `cache-hub` | Exact version `2.2.4` | The npm latest release has passed compatibility verification; the root direct dependency is fixed to 2.2.4, and `schema-dsl@2.0.11` declares the same transitive dependency version |
-| `schema-dsl` | Exact version `2.0.11` | The release chain targets the current non-deprecated TypeScript line; monSQLize relies on schema-dsl for DSL parsing, validation and alias diagnostics, and uses 2.0.11 for type-check and Model schema verification |
+| `cache-hub` | Exact version `2.2.4` | The npm latest release has passed compatibility verification; the root direct dependency is fixed to 2.2.4, and `schema-dsl@2.1.1` declares the same transitive dependency version |
+| `schema-dsl` | Exact version `2.1.1` | The release chain targets the current non-deprecated TypeScript line; monSQLize relies on schema-dsl runtime isolation for Model schema parsing, validation, custom types, and messages, and uses 2.1.1 for type-check and Model schema verification |
 
-> `schema-dsl@2.0.11` is the intended latest for this release chain; the historical `2.3.x` line exists on npm but has been marked as misreleased/deprecated and must not be followed by upgrades.
+> `schema-dsl@2.1.1` is the intended latest for this release chain; the historical `2.3.x` line exists on npm but has been marked as misreleased/deprecated and must not be followed by upgrades.
 
 ## Current Risk
 
@@ -20,8 +20,8 @@ The current root package adopts the **precise version dependency strategy**:
 
 ## Development status
 
-- The root direct `cache-hub` dependency is fixed to `2.2.4`; `schema-dsl@2.0.11` also declares `cache-hub@2.2.4`, so no additional override is needed.
-- `schema-dsl` is fixed to `2.0.11`.
+- The root direct `cache-hub` dependency is fixed to `2.2.4`; `schema-dsl@2.1.1` also declares `cache-hub@2.2.4`, so no additional override is needed.
+- `schema-dsl` is fixed to `2.1.1`.
 - Local sibling `../schema-dsl` is only used for debugging the upstream library itself and is no longer a prerequisite for monSQLize root package installation.
 
 
@@ -36,21 +36,21 @@ npm run release:preflight
 
 ## schema-dsl 2.x upgrade verification
 
-The dependency governance baseline has upgraded and fixed `schema-dsl` from the historical `^1.2.5` to `2.0.11`. The verification standard is as follows:
+The dependency governance baseline has upgraded and fixed `schema-dsl` from the historical `^1.2.5` to `2.1.1`. The verification standard is as follows:
 
-1. The upstream released the **non-deprecated** 2.x latest version on npm: `2.0.11`.
-2. `npm install schema-dsl@2.0.11 --save-exact` followed by `npm run type-check`.
+1. The upstream released the **non-deprecated** 2.x latest version on npm: `2.1.1`.
+2. `npm install schema-dsl@2.1.1 --save-exact` followed by `npm run type-check`.
 3. All model-related unit tests/integration tests passed (covered with `npm run test:unit` and `npm run test:integration`).
 4. `npm run test:examples` all passed.
 5. `npm run release:preflight` still needs to be used as the final access control before release.
-6. This file, Profile, CHANGELOG, and lockfile must be synchronized to `2.0.11`.
+6. This file, Profile, CHANGELOG, and lockfile must be synchronized to `2.1.1`.
 
 ## cache-hub 2.2.4 upgrade verification
 
 The dependency governance baseline has upgraded and fixed `cache-hub` from `1.0.0` to `2.2.4`. The verification standard is as follows:
 
 1. The upstream npm `latest` is `2.2.4`, and the Node.js engine requirement remains `>=18`, matching the current monSQLize baseline.
-2. The root direct dependency resolves to `2.2.4`; `schema-dsl@2.0.11` also declares `cache-hub@2.2.4`.
+2. The root direct dependency resolves to `2.2.4`; `schema-dsl@2.1.1` also declares `cache-hub@2.2.4`.
 3. `npm run type-check`, targeted cache / function-cache tests, website build, and memory probe must pass.
 4. This file, Profile, CHANGELOG, package manifest, and lockfile must be synchronized with the root direct dependency `2.2.4` baseline.
 

docs/en/model.md

@@ -56,6 +56,50 @@ if (user.checkPassword('secret123')) {
 
 ---
 
+## schema-dsl runtime
+
+Model schema callbacks receive the `s` namespace from the MonSQLize instance's isolated `schema-dsl/runtime`. `Model.define()` stores the definition only; schema compilation and validation happen when `msq.model(name)` creates a runtime-bound Model instance.
+
+For the default path, no application import from `schema-dsl` is required:
+
+```javascript
+Model.define('users', {
+    schema: (dsl) => dsl({
+        email: 'email!',
+        name: dsl.string().min(1).max(64).require()
+    })
+});
+
+const msq = new MonSQLize({
+    type: 'mongodb',
+    databaseName: 'app',
+    config: { uri: 'mongodb://127.0.0.1:27017' }
+});
+```
+
+When the application needs custom runtime-local types, messages, locale, or shared schema-dsl state, create or inject a `schema-dsl/runtime` instance through `schemaDsl`:
+
+```javascript
+import { createRuntime } from 'schema-dsl/runtime';
+
+const schemaRuntime = createRuntime({
+    types: {
+        tenantId: { type: 'string', pattern: '^tenant_[a-z0-9]+$' }
+    }
+});
+
+const msq = new MonSQLize({
+    type: 'mongodb',
+    databaseName: 'app',
+    config: { uri: 'mongodb://127.0.0.1:27017' },
+    schemaDsl: { runtime: schemaRuntime }
+});
+```
+
+`schemaDsl` also accepts `{ options, extensions }` when monSQLize should own the runtime, and `schemaDsl: false` when Model schema-dsl validation must be disabled for a migration or test boundary.
+
+---
+
 ## API Reference
 
 

docs/en/recipes.md

@@ -145,7 +145,7 @@ const User = msq.model('users');
 await User.insertOne({ name: 'Ada', email: 'ada@example.com' });
 ```
 
-`schema-dsl` is installed by default with `monsqlize`. Only when the application code directly imports `schema-dsl`, it needs to be declared in the application's own dependencies.
+`schema-dsl` is installed by default with `monsqlize`. Model schema callbacks use the MonSQLize instance's isolated `schema-dsl/runtime`; if application code also needs the same custom types or messages, create a `schema-dsl/runtime` instance and pass it through `schemaDsl`.
 
 ## Troubleshoot according to error code
 

docs/zh/file-dependency-governance.md

@@ -4,10 +4,10 @@
 
 | 依赖 | 策略 | 原因 |
 |------|------|------|
-| `cache-hub` | 精确版本 `2.2.4` | 上游 npm latest 已发布稳定版本并通过兼容验证；根包 direct dependency 固定到 2.2.4，`schema-dsl@2.0.11` 声明的传递依赖同为 2.2.4 |
-| `schema-dsl` | 精确版本 `2.0.11` | 本次发布链路目标为当前非 deprecated 的 TypeScript 正式线；monSQLize 依赖 schema-dsl 统一负责 DSL 解析、验证与 alias diagnostics，并以 2.0.11 执行 type-check 与 Model schema 验证 |
+| `cache-hub` | 精确版本 `2.2.4` | 上游 npm latest 已发布稳定版本并通过兼容验证；根包 direct dependency 固定到 2.2.4，`schema-dsl@2.1.1` 声明的传递依赖同为 2.2.4 |
+| `schema-dsl` | 精确版本 `2.1.1` | 本次发布链路目标为当前非 deprecated 的 TypeScript 正式线；monSQLize 依赖 schema-dsl runtime 隔离能力负责 Model schema 解析、验证、自定义类型和消息，并以 2.1.1 执行 type-check 与 Model schema 验证 |
 
-> `schema-dsl@2.0.11` 是本次发布链路的预期 latest；npm 上历史 `2.3.x` 已标记为误发布 / deprecated，不得跟随升级。
+> `schema-dsl@2.1.1` 是本次发布链路的预期 latest；npm 上历史 `2.3.x` 已标记为误发布 / deprecated，不得跟随升级。
 
 ## 当前风险
 
@@ -19,8 +19,8 @@
 
 ### 开发态
 
-- 根包 direct `cache-hub` 固定为 `2.2.4`；`schema-dsl@2.0.11` 声明的 `cache-hub` 版本同为 `2.2.4`，不需要额外 override。
-- `schema-dsl` 固定为 `2.0.11`。
+- 根包 direct `cache-hub` 固定为 `2.2.4`；`schema-dsl@2.1.1` 声明的 `cache-hub` 版本同为 `2.2.4`，不需要额外 override。
+- `schema-dsl` 固定为 `2.1.1`。
 - 本地 sibling `../schema-dsl` 仅用于上游库自身调试，不再作为 monSQLize 根包安装前提。
 
 ### 发布态
@@ -34,21 +34,21 @@ npm run release:preflight
 
 ## schema-dsl 2.x 升级验证
 
-依赖治理基线已将 `schema-dsl` 从历史 `^1.2.5` 升级并固定到 `2.0.11`，验证标准如下：
+依赖治理基线已将 `schema-dsl` 从历史 `^1.2.5` 升级并固定到 `2.1.1`，验证标准如下：
 
-1. 上游在 npm 发布了**非 deprecated** 的 2.x latest 版本：`2.0.11`。
-2. `npm install schema-dsl@2.0.11 --save-exact` 后通过 `npm run type-check`。
+1. 上游在 npm 发布了**非 deprecated** 的 2.x latest 版本：`2.1.1`。
+2. `npm install schema-dsl@2.1.1 --save-exact` 后通过 `npm run type-check`。
 3. model 相关单测 / 集成测试全通过（随 `npm run test:unit` 与 `npm run test:integration` 覆盖）。
 4. `npm run test:examples` 全通过。
 5. 发布前仍需以 `npm run release:preflight` 作为最终门禁。
-6. 本文件、Profile、CHANGELOG 与 lockfile 必须同步到 `2.0.11`。
+6. 本文件、Profile、CHANGELOG 与 lockfile 必须同步到 `2.1.1`。
 
 ## cache-hub 2.2.4 升级验证
 
 依赖治理基线已将 `cache-hub` 从 `1.0.0` 升级并固定到 `2.2.4`，验证标准如下：
 
 1. 上游 npm `latest` 为 `2.2.4`，Node.js 引擎要求仍为 `>=18`，与 monSQLize 当前基线一致。
-2. 根包 direct dependency 解析到 `2.2.4`；`schema-dsl@2.0.11` 也声明 `cache-hub@2.2.4`。
+2. 根包 direct dependency 解析到 `2.2.4`；`schema-dsl@2.1.1` 也声明 `cache-hub@2.2.4`。
 3. `npm run type-check`、缓存 / function-cache 定向测试、文档站构建与内存探针必须通过。
 4. 本文件、Profile、CHANGELOG、package manifest 与 lockfile 必须同步 root direct dependency 的 `2.2.4` 口径。
 

docs/zh/model.md

@@ -56,6 +56,50 @@ if (user.checkPassword('secret123')) {
 
 ---
 
+## schema-dsl runtime
+
+Model 的 `schema` 回调会收到当前 MonSQLize 实例隔离的 `schema-dsl/runtime` 的 `s` 命名空间。`Model.define()` 只保存定义；实际 schema 编译与验证发生在 `msq.model(name)` 创建绑定到运行时的 Model 实例时。
+
+默认路径下，应用代码不需要直接导入 `schema-dsl`：
+
+```javascript
+Model.define('users', {
+    schema: (dsl) => dsl({
+        email: 'email!',
+        name: dsl.string().min(1).max(64).require()
+    })
+});
+
+const msq = new MonSQLize({
+    type: 'mongodb',
+    databaseName: 'app',
+    config: { uri: 'mongodb://127.0.0.1:27017' }
+});
+```
+
+如果应用需要运行时本地的自定义类型、消息、locale，或要与 monSQLize 共享同一个 schema-dsl 状态，可以通过 `schemaDsl` 注入 `schema-dsl/runtime` 实例：
+
+```javascript
+import { createRuntime } from 'schema-dsl/runtime';
+
+const schemaRuntime = createRuntime({
+    types: {
+        tenantId: { type: 'string', pattern: '^tenant_[a-z0-9]+$' }
+    }
+});
+
+const msq = new MonSQLize({
+    type: 'mongodb',
+    databaseName: 'app',
+    config: { uri: 'mongodb://127.0.0.1:27017' },
+    schemaDsl: { runtime: schemaRuntime }
+});
+```
+
+当 monSQLize 自己持有 runtime 时，`schemaDsl` 也可以传 `{ options, extensions }`；迁移或测试边界需要跳过 Model schema-dsl 验证时，可以设置 `schemaDsl: false`。
+
+---
+
 ## API 参考
 
 ### Model.define(collectionName, definition)

docs/zh/recipes.md

@@ -145,7 +145,7 @@ const User = msq.model('users');
 await User.insertOne({ name: 'Ada', email: 'ada@example.com' });
 ```
 
-`schema-dsl` 已随 `monsqlize` 默认安装。只有应用代码直接导入 `schema-dsl` 时，才需要在应用自己的依赖里声明它。
+`schema-dsl` 已随 `monsqlize` 默认安装。Model 的 schema 回调使用当前 MonSQLize 实例隔离的 `schema-dsl/runtime`；如果应用代码也需要同一组自定义类型或消息，可以创建 `schema-dsl/runtime` 实例并通过 `schemaDsl` 传入。
 
 ## 按错误码排障
 

examples/docs/sync-target-failure.ts

@@ -76,6 +76,7 @@ async function main() {
             'sync manager did not record target failure in time',
         );
 
+        await runtime.startSync();
         await events.insertOne({ type: 'sync.recovered', payload: { step: 2 } });
 
         const recoveredStats = await waitFor(