nodejs-store 2.0.4 → 2.2.0

package/README.md

@@ -98,7 +98,7 @@ Typical concrete scenarios (see [`doc/use-cases/`](doc/use-cases/) for full walk
 
 Being explicit about the boundary saves you time:
 
-- **You want a full ORM with a migration engine.** `nodejs-store` is a *data layer*, not a migration tool. It can **read** a SQL backend's physical structure (`syncSchema` → introspection) but it never writes DDL back. Pair it with your migration tool of choice.
+- **You want a full ORM with a migration engine.** `nodejs-store` is a *data layer*, not a migration tool. It can **read** a SQL backend's physical structure (`syncSchema` → introspection) but it never writes DDL back. Pair it with your migration tool of choice. There is an optional `generateDdl()` that renders `CREATE TABLE` text from your registered schemas — pure text, it never connects to or writes to the database.
 - **You need a type-safe generated client.** Schemas are runtime JSON, not TypeScript types. You get flexibility and cross-language parity (same schema runs in Node and Python), not compile-time type inference.
 - **You only ever use one database and rarely join.** A plain driver (or a single-database ODM/ORM) will be simpler.
 - **You need raw aggregation escape hatches.** `$pipeline` passthrough and `store.aggregate()` were deliberately removed. Use `$condition` / `$group` / `$having` / relations; anything that cannot be safely translated fails **explicitly** rather than silently.
@@ -117,7 +117,7 @@ General positioning, not a benchmark — always verify against each tool's curre
 | Built-in role / field-level RBAC + owner injection | ✅ | ➖ | ➖ (via extensions) | ➖ | ➖ |
 | Read-time computed columns (sync / async / relation-agg) | ✅ | ➖ (getters) | ➖ | ➖ | ➖ |
 | Soft-delete archive table auto-provisioned | ✅ | ➖ | ➖ | ➖ | ➖ |
-| Migration / DDL engine | ➖ (introspection read-only) | ➖ | ✅ | ✅ | ✅ |
+| Migration / DDL engine | ➖ (introspection read-only; optional `generateDdl` text) | ➖ | ✅ | ✅ | ✅ |
 | Static type generation | ➖ (runtime JSON, cross-language parity) | ➖ | ✅ | ⚠️ (decorators + TS) | ✅ |
 | Shared native core across Node & Python | ✅ (Rust `rust-store`) | ➖ | ➖ | ➖ | ➖ |
 
@@ -128,7 +128,7 @@ Positioning only, based on those projects' public documentation at the time of w
 - **vs Mongoose** — Mongoose is MongoDB-only. `nodejs-store` uses a similar MongoDB-style query syntax (`$gt`, `$or`, `$set`, `$inc`) but the same query also runs unchanged against MySQL, SQLite and PostgreSQL.
 - **vs `mongoosql-core`** — the closest in spirit: it also runs Mongoose-style queries on MongoDB, PostgreSQL and MySQL. `nodejs-store` additionally targets SQLite, ships schema-level permissions (role/field whitelists plus `creator` owner-condition injection), read-time computed columns (`fn` / `asyncFn` / relation-`agg`), an auto-provisioned `<Model>Deleted` soft-delete archive, and shares one Rust engine with a Python host so Node.js and Python cannot drift apart.
 - **vs `unsql`** — `unsql` generates SQL from plain JavaScript objects for MySQL, PostgreSQL and SQLite. It does not target MongoDB, and it is a query/CRUD helper rather than a schema-driven data layer with permissions and computed columns.
-- **vs Prisma** — Prisma is a schema DSL plus generated client with a migration engine and compile-time types. `nodejs-store` is a runtime JSON schema with no DDL or migration responsibility (it only *reads* physical structure via introspection) and no type generation — in exchange for one query dialect spanning a document store and three relational stores.
+- **vs Prisma** — Prisma is a schema DSL plus generated client with a migration engine and compile-time types. `nodejs-store` is a runtime JSON schema with no migration engine (it only *reads* physical structure via introspection, and `generateDdl()` only *renders* `CREATE TABLE` text without touching the database) and no type generation — in exchange for one query dialect spanning a document store and three relational stores.
 - **vs TypeORM / Sequelize / Drizzle** — Sequelize and Drizzle are SQL-only; TypeORM models MongoDB separately from its SQL entities. `nodejs-store` treats MongoDB as the primary dialect and compiles the same GQL to SQL for the other three backends.
 
 Short version: use an ORM when you want **compile-time types and migrations**; use `nodejs-store` when you want **one runtime schema + one query dialect spanning MongoDB and SQL**, with RBAC and computed columns built in.
@@ -302,6 +302,38 @@ Notes:
 - `queryWithCount` accepts `page`/`pageSize` (recommended) or the traditional `$skip`/`$limit` params.
 - `updateMany` / `remove` with an **empty condition** (`{}`, `null`, `{ "$and": [] }`) is rejected outright — it never falls through to a full-table write.
 
+### Transactions and raw SQL
+
+```js
+async function transfer() {
+  const rows = await store.executeRaw(
+    'default', 'SELECT * FROM accounts WHERE _id = ? FOR UPDATE', [accId]);
+  await store.executeRaw(
+    'default', 'UPDATE accounts SET balance = ? WHERE _id = ?', [newBalance, accId],
+    true);
+}
+
+await store.transaction('default', transfer);
+```
+
+- `store.transaction(source, fn)` opens a transaction scope on one SQL source: every `executeRaw` / CRUD call inside `fn` lands on that source's transaction connection, with `commit` / `rollback` as one unit (reuses the internal `runInTransaction`). Mongo sources or executors without transactions run `fn` as-is — it never pretends to be atomic.
+- `store.executeRaw(source, sql, params, isWrite)` runs raw SQL, bypassing GQL parsing and dialect translation. Placeholders follow each backend's native style: `?` for MySQL / SQLite, `$1..$n` for PostgreSQL. SQL sources only — a Mongo source throws `RawSqlError` (`store.RawSqlError`).
+- `isWrite=false` (default) returns `{ rows, affectedRows }` with the result-set rows; `isWrite=true` returns the affected-row count.
+
+### DDL generation
+
+```js
+let sql = store.generateDdl('mysql');                       // every registered model
+sql     = store.generateDdl('postgres', ['Course', 'CourseDeleted']);
+```
+
+`store.generateDdl(backend, names)` maps one registered schema def to one `CREATE TABLE` — the inverse of `syncSchema()`, which only *reads*. The generator is **pure text**: it never connects to, or writes to, the database (iron rule 6 still holds).
+
+- Only scalar fields become columns; `object` / `array` fields do not.
+- Every table gets the `__present` sentinel column; `timestamps` models also get `createdAt` / `updatedAt`; the `<collection>_deleted` archive table is generated like any other registered def.
+- No `CREATE INDEX` is emitted — SQL backends keep indexes as metadata only.
+- MySQL `__present` is `VARCHAR(255)`; a schema whose present-token string would overflow emits a `ddlPresentOverflow` feedback event rather than failing silently.
+
 ## Multi-datasource connections
 
 Every schema is located by the triple `(source, namespace, collection)` — the triple must be
@@ -528,7 +560,7 @@ Every registered model automatically gets a `<Model>Deleted` archive collection/
 Yes. Bind a schema to `(source, namespace, collection)` and pass a `{ source, namespace }` route override per request. Treat `routeOverride` as trusted server-side input only.
 
 **Does it run migrations?**
-No. `syncSchema()` only *reads* physical structure via introspection (introspect → merge overlay → register). Schema changes / DDL are your migration tool's job.
+No. `syncSchema()` only *reads* physical structure via introspection (introspect → merge overlay → register). Schema changes / DDL are your migration tool's job. If you want a starting point, `store.generateDdl(backend)` renders `CREATE TABLE` text from the registered schemas — but it is pure text generation: it never runs or writes DDL.
 
 **Can I see the generated query without running it?**
 Yes — `store.buildPipeline(gql, params)` returns the compiled plan (`{ tokens, ast, pipeline, projection }`) with no execution and no permission/compute application.

package/README.zh-CN.md

@@ -97,7 +97,7 @@ MongoDB 是*主方言*：查询以 MongoDB 风格的 GQL 编写，三种关系
 
 明确边界能为你省下时间：
 
-- **你想要带迁移引擎的完整 ORM。** `nodejs-store` 是*数据层*，不是迁移工具。它可以**读取** SQL 后端的物理结构（`syncSchema` → introspection），但从不把 DDL 写回。请与你自选的迁移工具搭配使用。
+- **你想要带迁移引擎的完整 ORM。** `nodejs-store` 是*数据层*，不是迁移工具。它可以**读取** SQL 后端的物理结构（`syncSchema` → introspection），但从不把 DDL 写回。请与你自选的迁移工具搭配使用。另有一个可选的 `generateDdl()`，可从已注册 schema 渲染出 `CREATE TABLE` 文本 —— 纯文本，绝不连接或写入数据库。
 - **你需要带类型安全、自动生成的客户端。** schema 是运行时 JSON，而非 TypeScript 类型。你获得的是灵活性与跨语言一致性（同一份 schema 在 Node 与 Python 中都可用），而不是编译期类型推断。
 - **你只用一种数据库，且几乎不做关联。** 直接用裸驱动（或只针对单一数据库的 ODM/ORM）会更简单。
 - **你需要原生聚合逃生舱。** `$pipeline` 透传与 `store.aggregate()` 已被有意移除。请使用 `$condition` / `$group` / `$having` / 关系；任何无法安全翻译的内容都会**显式**失败，而不会静默降级。
@@ -116,7 +116,7 @@ MongoDB 是*主方言*：查询以 MongoDB 风格的 GQL 编写，三种关系
 | 内置角色 / 字段级 RBAC + 属主注入 | ✅ | ➖ | ➖（通过扩展） | ➖ | ➖ |
 | 读时计算列（同步 / 异步 / 关系聚合） | ✅ | ➖（getter） | ➖ | ➖ | ➖ |
 | 自动置备软删除归档表 | ✅ | ➖ | ➖ | ➖ | ➖ |
-| 迁移 / DDL 引擎 | ➖（introspection 只读） | ➖ | ✅ | ✅ | ✅ |
+| 迁移 / DDL 引擎 | ➖（introspection 只读；可选 `generateDdl` 文本） | ➖ | ✅ | ✅ | ✅ |
 | 静态类型生成 | ➖（运行时 JSON，跨语言一致） | ➖ | ✅ | ⚠️（装饰器 + TS） | ✅ |
 | Node 与 Python 共享原生核心 | ✅（Rust `rust-store`） | ➖ | ➖ | ➖ | ➖ |
 
@@ -127,7 +127,7 @@ MongoDB 是*主方言*：查询以 MongoDB 风格的 GQL 编写，三种关系
 - **vs Mongoose** —— Mongoose 仅支持 MongoDB。`nodejs-store` 使用类似的 MongoDB 风格查询语法（`$gt`、`$or`、`$set`、`$inc`），但同一条查询也能原样跑在 MySQL、SQLite 与 PostgreSQL 上。
 - **vs `mongoosql-core`** —— 精神上最接近：它同样能在 MongoDB、PostgreSQL 与 MySQL 上运行 Mongoose 风格的查询。`nodejs-store` 还额外面向 SQLite，内置 schema 级权限（角色/字段白名单，外加 `creator` 属主条件注入）、读时计算列（`fn` / `asyncFn` / 关系 `agg`）、自动置备的 `<Model>Deleted` 软删除归档，并与 Python 宿主共享同一个 Rust 引擎，因此 Node.js 与 Python 不会产生漂移。
 - **vs `unsql`** —— `unsql` 从普通 JavaScript 对象为 MySQL、PostgreSQL 与 SQLite 生成 SQL。它不面向 MongoDB，且只是一个查询/CRUD 辅助工具，而非带权限与计算列的 schema 驱动数据层。
-- **vs Prisma** —— Prisma 是 schema DSL 加生成的客户端，配有迁移引擎与编译期类型。`nodejs-store` 是运行时 JSON schema，不承担 DDL 或迁移职责（仅通过 introspection *读取*物理结构），也不生成类型 —— 以此换取一套横跨文档库与三种关系库的查询方言。
+- **vs Prisma** —— Prisma 是 schema DSL 加生成的客户端，配有迁移引擎与编译期类型。`nodejs-store` 是运行时 JSON schema，不承担迁移引擎职责（仅通过 introspection *读取*物理结构，`generateDdl()` 也只*渲染* `CREATE TABLE` 文本而不触碰数据库），也不生成类型 —— 以此换取一套横跨文档库与三种关系库的查询方言。
 - **vs TypeORM / Sequelize / Drizzle** —— Sequelize 与 Drizzle 仅支持 SQL；TypeORM 把 MongoDB 与其 SQL 实体分开建模。`nodejs-store` 以 MongoDB 为主方言，并把同一份 GQL 编译为其余三种后端的 SQL。
 
 一句话：想要**编译期类型与迁移**就用 ORM；想要**一份运行时 schema + 一套横跨 MongoDB 与 SQL 的查询方言**，并内置 RBAC 与计算列，就用 `nodejs-store`。
@@ -301,6 +301,38 @@ await store.upsert('Post', { code: 'A1' }, { ... });      // 显式条件的 ups
 - `queryWithCount` 接受 `page`/`pageSize`（推荐）或传统的 `$skip`/`$limit` 参数。
 - 带**空条件**（`{}`、`null`、`{ "$and": [] }`）的 `updateMany` / `remove` 会被直接拒绝 —— 它绝不会退化为全表写入。
 
+### 事务与原生 SQL
+
+```js
+async function transfer() {
+  const rows = await store.executeRaw(
+    'default', 'SELECT * FROM accounts WHERE _id = ? FOR UPDATE', [accId]);
+  await store.executeRaw(
+    'default', 'UPDATE accounts SET balance = ? WHERE _id = ?', [newBalance, accId],
+    true);
+}
+
+await store.transaction('default', transfer);
+```
+
+- `store.transaction(source, fn)` 在单个 SQL 源上开启事务作用域：`fn` 内的每个 `executeRaw` / CRUD 调用都落到该源的事务连接，`commit` / `rollback` 作为一个整体（复用内部的 `runInTransaction`）。Mongo 源或不支持事务的执行器会按原样执行 `fn` —— 绝不假装已原子。
+- `store.executeRaw(source, sql, params, isWrite)` 执行原生 SQL，绕开 GQL 解析与方言翻译。占位符沿用各后端原生风格：MySQL / SQLite 用 `?`，PostgreSQL 用 `$1..$n`。仅限 SQL 源 —— Mongo 源会抛出 `RawSqlError`（`store.RawSqlError`）。
+- `isWrite=false`（默认）返回 `{ rows, affectedRows }` 含结果集行；`isWrite=true` 返回影响行数。
+
+### DDL 生成
+
+```js
+let sql = store.generateDdl('mysql');                       // 所有已注册模型
+sql     = store.generateDdl('postgres', ['Course', 'CourseDeleted']);
+```
+
+`store.generateDdl(backend, names)` 把一个已注册 schema def 映射为一条 `CREATE TABLE` —— 是 `syncSchema()`（只*读取*）的逆操作。生成器是**纯文本**：它绝不连接、也绝不写入数据库（铁律 6 依然成立）。
+
+- 只有标量字段成为列；`object` / `array` 字段不建列。
+- 每张表都会获得 `__present` 哨兵列；`timestamps` 模型还会获得 `createdAt` / `updatedAt`；`<collection>_deleted` 归档表与其它已注册 def 一样生成。
+- 不生成 `CREATE INDEX` —— SQL 后端仅把索引保留为元数据。
+- MySQL 的 `__present` 为 `VARCHAR(255)`；若某 schema 的 present 令牌串会超限，则发出 `ddlPresentOverflow` 反馈事件，而非静默失败。
+
 ## 多数据源连接
 
 每个 schema 由三元组 `(source, namespace, collection)` 定位 —— 该三元组在 registry 内必须
@@ -525,7 +557,7 @@ await init({ default: db, pg_a: executors.createConnection('postgres', pgPool) }
 可以。把 schema 绑定到 `(source, namespace, collection)`，并按请求传入 `{ source, namespace }` 路由覆盖。仅把 `routeOverride` 当作受信的服务端输入。
 
 **它会执行迁移吗？**
-不会。`syncSchema()` 只通过 introspection *读取*物理结构（introspect → 合并 overlay → 注册）。schema 变更 / DDL 是你所用迁移工具的职责。
+不会。`syncSchema()` 只通过 introspection *读取*物理结构（introspect → 合并 overlay → 注册）。schema 变更 / DDL 是你所用迁移工具的职责。若想要一个起点，`store.generateDdl(backend)` 可从已注册 schema 渲染 `CREATE TABLE` 文本 —— 但它只是纯文本生成：绝不执行、也不写入 DDL。
 
 **能否在不运行的情况下查看生成的查询？**
 可以 —— `store.buildPipeline(gql, params)` 返回编译后的计划（`{ tokens, ast, pipeline, projection }`），不执行，也不应用权限/计算列。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nodejs-store",
-  "version": "2.0.4",
+  "version": "2.2.0",
   "description": "Multi-backend data layer for Node.js (MongoDB, MySQL, SQLite, PostgreSQL): pure JSON schemas, GQL tree queries compiled to a single native query, GROUP BY/HAVING aggregation, computed columns, soft-delete and role-based access control",
   "main": "src/index.js",
   "files": [

package/src/crud/exec.js

@@ -15,6 +15,7 @@
 const { PermissionError, getContext } = require('../permission');
 const datasource = require('../datasource');
 const { execMongo } = require('../executors/mongo');
+const { emit: _emitFeedback } = require('../feedback');
 const { get: _getSchema } = require('../schema');
 
 const _PHASE1_IDS = /^\{\{phase1\.ids\}\}$/;
@@ -27,6 +28,36 @@ const _STEP_PH = /^\{\{step\.(\d+)\._id\}\}$/;
  */
 const _PERM_PREFIX = 'ERR_PERMISSION:';
 
+/**
+ * 档位类错误识别：core text2query 档门禁统一携带 `ERR_TEXT2QUERY:` 稳定前缀
+ * （见 core `command/mod.rs::ERR_TEXT2QUERY`），同上按前缀映射。命中即 emit
+ * 反馈事件 `profile_blocked`（自动反馈原则：允许拦截，禁止静默）。
+ */
+const _PROFILE_PREFIX = 'ERR_TEXT2QUERY:';
+
+/**
+ * 从 core 文案 `... [$feature]（功能收缩）` 中提取门禁项名；无 `[..]` 时留白
+ * （null），不伪造 feature —— 缺值必须显式暴露（禁静默兜底）。
+ */
+const _FEATURE_RE = /\[(.+?)\]/;
+
+/** 档位拦截反馈的统一提示（反馈事件契约 §4.6 的一部分；单点定义防文案漂移） */
+const _PROFILE_HINT = '上游（LLM 产出的 GQL / 调用方入参）越界；text2query 档白名单见 SKILL.md §后端无关性与边界';
+
+/**
+ * 档位（profile）拒绝：text2query 档违反功能收缩 / 硬限制
+ *
+ * 与权限错误（`PermissionError`，403）区分：档位拒绝是**调用方合约违反**（400），
+ * 非授权问题（见执行文档 §4.4）。`status` 供上层（HTTP 网关等）映射响应码。
+ */
+class ProfileViolation extends Error {
+  constructor(message, status = 400) {
+    super(message);
+    this.name = 'ProfileViolation';
+    this.status = status;
+  }
+}
+
 /** 设置数据源连接映射（对 `../datasource` 的路由入口做包内透出） */
 const setConnections = datasource.setConnections;
 
@@ -45,7 +76,14 @@ function _ctx() {
   return getContext() ?? null;
 }
 
-/** 绑定层调用包装：权限类错误（`ERR_PERMISSION:` 前缀）映射为 PermissionError */
+/**
+ * 绑定层调用包装：
+ *   - 权限类错误（`ERR_PERMISSION:` 前缀）→ PermissionError
+ *   - 档位类错误（`ERR_TEXT2QUERY:` 前缀）→ emit `profile_blocked` 反馈 + ProfileViolation
+ *
+ * 按前缀映射而非具体文案（core 文案可自由调整，映射不随文案漂移而静默失效）。
+ * 其余异常原样上抛（不吞错）。
+ */
 function _call(fn) {
   try {
     return fn();
@@ -54,6 +92,20 @@ function _call(fn) {
     if (typeof msg === 'string' && msg.startsWith(_PERM_PREFIX)) {
       throw new PermissionError(msg.slice(_PERM_PREFIX.length));
     }
+    if (typeof msg === 'string' && msg.startsWith(_PROFILE_PREFIX)) {
+      const detail = msg.slice(_PROFILE_PREFIX.length);
+      const m = _FEATURE_RE.exec(detail);
+      _emitFeedback({
+        type: 'profile_blocked',
+        code: 'profileBlocked',
+        layer: 'core',
+        profile: 'text2query',
+        feature: m ? m[1] : null,
+        message: detail,
+        hint: _PROFILE_HINT,
+      });
+      throw new ProfileViolation(detail);
+    }
     throw e;
   }
 }
@@ -116,6 +168,8 @@ module.exports = {
   _nowFor,
   _ctx,
   _call,
+  ProfileViolation,
+  _PROFILE_HINT,
   _exec,
   _execOn,
   _substitute,

package/src/crud/index.js

@@ -19,7 +19,7 @@
  *   - [`mutation`]：mutation / upsert
  */
 
-const { setConnections, setDb, _nowFor, _ctx, _call, _exec, _substitute, resolvePlaceholders } = require('./exec');
+const { setConnections, setDb, _nowFor, _ctx, _call, ProfileViolation, _exec, _substitute, resolvePlaceholders } = require('./exec');
 const { _generateId, _truthy, _newIdPool } = require('./id');
 const { query, queryOne, queryWithCount, queryFederated } = require('./query');
 const { insert, insertMany, update, updateMany, remove, exists, count } = require('./write');
@@ -41,6 +41,7 @@ module.exports = {
   count,
   mutation,
   upsert,
+  ProfileViolation,
   // ── Host 契约件（供跨语言同构契约测试与高级用法；下划线表示内部语义） ──
   _substitute,
   resolvePlaceholders,

package/src/crud/query.js

@@ -5,9 +5,34 @@
  * / 跨库联邦（逐源执行 → 内存 hash join）
  */
 
-const { core: _core, getAsyncFn } = require('../schema');
+const { core: _core, getAsyncFn, getProfile } = require('../schema');
 const { emit: _emitFeedback } = require('../feedback');
-const { _call, _ctx, _exec, _execOn, resolvePlaceholders } = require('./exec');
+const {
+  _call, _ctx, _exec, _execOn, resolvePlaceholders, ProfileViolation, _PROFILE_HINT,
+} = require('./exec');
+
+/**
+ * Host 兜底：text2query 档禁用 `routeOverride`（受信参数，禁 AI 侧指定）
+ *
+ * 判决唯一在 core（执行文档 §4.2 ⑤：各 `planQuery*` 入口已判并 Err）；此为第二层
+ * 防护——即使 core 判决被绕过，Host 也不放行受信参数（CWE-639）。命中即 emit
+ * `profile_blocked`，`layer: 'host'` 本身即反馈：core 层未拦住，须回溯加固
+ * （自动反馈原则：允许拦截，禁止静默）。
+ */
+function _guardRouteOverride(routeOverride) {
+  if (routeOverride == null || getProfile() !== 'text2query') return;
+  const detail = 'text2query 档禁用 route_override（受信参数，禁 AI 侧指定）';
+  _emitFeedback({
+    type: 'profile_blocked',
+    code: 'profileBlocked',
+    layer: 'host',
+    profile: 'text2query',
+    feature: 'route_override',
+    message: detail,
+    hint: _PROFILE_HINT,
+  });
+  throw new ProfileViolation(detail);
+}
 
 /** 执行读命令序列：find 快路径 / 两阶段（取 ID → 关联 → 还原排序）/ 标准聚合 */
 async function _runQueryPlan(plan) {
@@ -44,12 +69,14 @@ async function _finalize(plan, items) {
  * 权限/计算列仍按结构 schema 判定（见 multi-datasource-routing-plan.md §6）。
  */
 async function query(gql, params = null, routeOverride = null) {
+  _guardRouteOverride(routeOverride);
   const plan = _call(() => _core.planQuery(gql, params ?? {}, _ctx(), routeOverride));
   return _finalize(plan, await _runQueryPlan(plan));
 }
 
 /** GQL 查询（返回单条）—— 走 core `planQueryOne`：未显式 `$limit` 时下推 `$limit(1)` */
 async function queryOne(gql, params = null, routeOverride = null) {
+  _guardRouteOverride(routeOverride);
   const plan = _call(() => _core.planQueryOne(gql, params ?? {}, _ctx(), routeOverride));
   const items = await _finalize(plan, await _runQueryPlan(plan));
   return items.length ? items[0] : null;
@@ -106,6 +133,7 @@ async function queryFederated(gql, params = null) {
  * pageSize 上限 5000，防止拖库。
  */
 async function queryWithCount(gql, params = null, routeOverride = null) {
+  _guardRouteOverride(routeOverride);
   const plan = _call(() =>
     _core.planQueryWithCount(gql, params ?? {}, _ctx(), null, routeOverride));
   const items = await _finalize(plan, await _runQueryPlan(plan));
@@ -119,4 +147,6 @@ async function queryWithCount(gql, params = null, routeOverride = null) {
   };
 }
 
-module.exports = { query, queryOne, queryWithCount, queryFederated };
+module.exports = {
+  query, queryOne, queryWithCount, queryFederated, _guardRouteOverride,
+};

package/src/datasource.js

@@ -235,6 +235,39 @@ async function execSql(source, connection, cmd) {
   return executors.shapeResult(cmd, out);
 }
 
+/** 原生 SQL 入口的显式错误（非 SQL 源 / 执行器未接入） */
+class RawSqlError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'RawSqlError';
+  }
+}
+
+/**
+ * 在指定 SQL 源上执行原生 SQL（Host 层逃生口，绕开 core 的 dialectTranslate）
+ *
+ *   - 事务作用域内经 `connectionFor` 落到事务专用连接 → 支持 SELECT ... FOR UPDATE；
+ *   - 占位符沿用各后端原生风格（mysql/sqlite 用 `?`，postgres 用 `$1..$n`）；
+ *   - 仅支持 SQL 源；Mongo 源显式报错（绝不静默）；
+ *   - `isWrite=false` 视为读（取行）；`true` 视为写（取影响行数）；
+ *   - 返回 `{ rows, affectedRows }`。
+ *   对齐 py_store/datasource.py#execute_raw。
+ */
+async function executeRaw(source, sql, params = [], isWrite = false) {
+  const conn = connectionFor(source);
+  if (!conn || typeof conn.kind !== 'string') {
+    throw new RawSqlError(
+      `数据源 ${source} 不是 SQL 源（原生 SQL 入口仅支持 mysql/postgres/sqlite）`,
+    );
+  }
+  if (typeof conn.exec !== 'function') {
+    throw new RawSqlError(`SQL 数据源 ${source}(${conn.kind}) 的执行器未接入`);
+  }
+  const stmt = { text: sql, params: Array.from(params || []), isWrite: Boolean(isWrite) };
+  const out = await conn.exec({ stmts: [stmt] });
+  return { rows: out.rows ?? null, affectedRows: Number(out.affectedRows || 0) };
+}
+
 module.exports = {
   DEFAULT_SOURCE,
   setConnections,
@@ -250,5 +283,7 @@ module.exports = {
   dbOfSchema,
   route,
   execSql,
+  executeRaw,
   PushdownUnsupportedError,
+  RawSqlError,
 };

package/src/ddl.js

@@ -0,0 +1,132 @@
+'use strict';
+
+/**
+ * DDL 生成（schema def → CREATE TABLE 文本；纯函数，不连库、不回写）
+ *
+ * 与 core 契约严格对齐（schema→DDL 单向映射）：
+ *   - 标量字段按声明类型建列；object/array 字段建 **JSON 列**（MySQL `JSON` / PG `jsonb` /
+ *     SQLite `TEXT`，同 core dialect::Backend::json_type_name）——落单列存 JSON 文本，
+ *     读侧由 core row::parse_json_col 还原为嵌套对象，跨后端对齐 Mongo 嵌套文档；
+ *   - 每表必建 __present 哨兵列（形态 ,f1,f2,；同 core write/insert.rs::present_value）；
+ *   - timestamps !== false → 追加 createdAt / updatedAt（同 core schema/registry.rs::add_timestamp_fields）；
+ *   - 归档表 <collection>_deleted 由 registry 自动派生，本模块按已注册 def 逐表生成（不特判）；
+ *   - 不生成 CREATE INDEX（SQL 后端不建索引，schema.indexes 仅元数据，铁律 6）。
+ *
+ * 生成器只产出文本、不执行 —— 不违反铁律 6（绝不写 DDL 回库）。
+ * 对齐 py_store/ddl.py（两端输出逐字节一致）。
+ */
+
+const { emit: _emitFeedback } = require('./feedback');
+const schema = require('./schema');
+
+const BACKENDS = ['mysql', 'postgres', 'sqlite'];
+
+// schema 声明类型 → [mysql, postgres, sqlite] 列类型
+const TYPES = {
+  string: ['VARCHAR(255)', 'TEXT', 'TEXT'],
+  int: ['INT', 'INTEGER', 'INTEGER'],
+  long: ['BIGINT', 'BIGINT', 'INTEGER'],
+  number: ['BIGINT', 'BIGINT', 'INTEGER'],
+  float: ['DOUBLE', 'DOUBLE PRECISION', 'REAL'],
+  double: ['DOUBLE', 'DOUBLE PRECISION', 'REAL'],
+  bool: ['TINYINT(1)', 'BOOLEAN', 'INTEGER'],
+  boolean: ['TINYINT(1)', 'BOOLEAN', 'INTEGER'],
+  datetime: ['BIGINT', 'BIGINT', 'INTEGER'],
+  date: ['BIGINT', 'BIGINT', 'INTEGER'],
+};
+const NON_COLUMN = ['object', 'array'];
+// object/array 字段的列类型（JSON 文本列；同 core Backend::json_type_name）
+const JSON_TYPE = ['JSON', 'jsonb', 'TEXT'];
+const ID_TYPE = ['VARCHAR(64)', 'TEXT', 'TEXT'];
+const PRESENT_TYPE = ['VARCHAR(255)', 'TEXT', 'TEXT'];
+const TIMESTAMP_FIELDS = ['createdAt', 'updatedAt'];
+const MYSQL_PRESENT_MAX = 255;
+
+function idx(backend) {
+  return BACKENDS.indexOf(backend);
+}
+
+/** 标识符引用（与 core Backend::quote_ident 一致：mysql 反引号，其余双引号） */
+function q(backend, ident) {
+  if (backend === 'mysql') return '`' + ident.replace(/`/g, '``') + '`';
+  return '"' + ident.replace(/"/g, '""') + '"';
+}
+
+function declaredType(fieldDef) {
+  return fieldDef && typeof fieldDef === 'object' ? fieldDef.type : fieldDef;
+}
+
+/** 返回 [[name, sqlType, pk]]，顺序：声明的字段（标量 / object·array JSON 列）→ timestamps → __present */
+function columns(defn, backend) {
+  const i = idx(backend);
+  const cols = [];
+  const fields = defn.fields || {};
+  for (const [name, fdef] of Object.entries(fields)) {
+    const ftype = declaredType(fdef);
+    if (name === '_id') {
+      cols.push([name, ID_TYPE[i], true]);
+      continue;
+    }
+    if (NON_COLUMN.includes(ftype)) {
+      // object/array → 单列 JSON 文本（同 core field_column_ref::Json）
+      cols.push([name, JSON_TYPE[i], false]);
+      continue;
+    }
+    if (!Object.prototype.hasOwnProperty.call(TYPES, ftype)) {
+      throw new Error(
+        `DDL 生成：字段 "${defn.name}.${name}" 类型 ${JSON.stringify(ftype)} 未知，支持 ${Object.keys(TYPES).sort()}`,
+      );
+    }
+    cols.push([name, TYPES[ftype][i], false]);
+  }
+  if (!cols.some((c) => c[2])) {
+    throw new Error(`DDL 生成：schema "${defn.name}" 缺少 _id 字段`);
+  }
+  if (defn.timestamps !== false) {
+    for (const ts of TIMESTAMP_FIELDS) {
+      if (!cols.some((c) => c[0] === ts)) cols.push([ts, TYPES.number[i], false]);
+    }
+  }
+  cols.push(['__present', PRESENT_TYPE[i], false]);
+  return cols;
+}
+
+/** MySQL __present VARCHAR(255) 容量校验：超限即告警（不静默） */
+function warnPresentOverflow(defn, cols) {
+  const length = cols.reduce((n, c) => n + c[0].length, 0) + cols.length + 1;
+  if (length > MYSQL_PRESENT_MAX) {
+    _emitFeedback({
+      type: 'ddl_present_overflow',
+      code: 'ddlPresentOverflow',
+      layer: 'host',
+      message: `表 ${defn.collection} 的 __present 预估长度 ${length} 超过 MySQL VARCHAR(255)`,
+      hint: '为该表改用 TEXT 列，或减少标量字段；否则写入会被截断/报错，导致 $eq:null / $exists 三态判定错误',
+      schema: defn.name,
+    });
+  }
+}
+
+function createTable(defn, backend) {
+  const table = defn.collection || defn.name;
+  const cols = columns(defn, backend);
+  if (backend === 'mysql') warnPresentOverflow(defn, cols);
+  const lines = [];
+  for (const [name, ctype, pk] of cols) {
+    if (pk && backend === 'mysql') lines.push(`  ${q(backend, name)} ${ctype} NOT NULL`);
+    else if (pk) lines.push(`  ${q(backend, name)} ${ctype} PRIMARY KEY`);
+    else lines.push(`  ${q(backend, name)} ${ctype}`);
+  }
+  if (backend === 'mysql') lines.push(`  PRIMARY KEY (${q(backend, '_id')})`);
+  return `CREATE TABLE ${q(backend, table)} (\n` + lines.join(',\n') + '\n);';
+}
+
+/** 生成 DDL 文本（多表以空行分隔）；backend ∈ mysql/postgres/sqlite */
+function generate(backend, names) {
+  if (!BACKENDS.includes(backend)) {
+    throw new Error(`DDL 生成：不支持的后端 ${JSON.stringify(backend)}（支持 ${BACKENDS.join('/')}）`);
+  }
+  const targets = names && names.length ? Array.from(names) : schema.list();
+  return targets.map((n) => createTable(schema.get(n), backend)).join('\n\n');
+}
+
+module.exports = { generate };

package/src/index.js

@@ -21,8 +21,11 @@
  *   const items = await store.query('Model($condition:@c0) { field1, field2 }', { c0: {} });
  */
 
+const { AsyncLocalStorage } = require('node:async_hooks');
+
 const crud = require('./crud');
 const datasource = require('./datasource');
+const ddl = require('./ddl');
 const executors = require('./executors');
 const feedback = require('./feedback');
 const introspect = require('./introspect');
@@ -30,6 +33,29 @@ const permission = require('./permission');
 const schema = require('./schema');
 const { syncSchema } = require('./sync');
 
+/** 档位 AsyncLocalStorage：记录「进入 text2query 前的原档」，供退出恢复（嵌套安全） */
+const _profileAls = new AsyncLocalStorage();
+
+/**
+ * 以 text2query 档执行（功能收缩 + 硬限制），退出恢复原档位。
+ *
+ * AI 问数链路入口；与 permission.scopedRoles 同构（token-set/reset，嵌套安全）。
+ * 档位是 core 进程级状态（非本 ALS 隔离），ALS 仅记录「进入时的原档」以便正确恢复，
+ * 使异步 / 嵌套调用各自回到自己进入前的档位。进入档位即等效强制携带用户上下文
+ * （core `ensureProfileCtx`，见执行文档 §4.2）。
+ */
+async function text2query(fn) {
+  const prev = schema.getProfile();
+  schema.setProfile('text2query');
+  return _profileAls.run(prev, async () => {
+    try {
+      return await fn();
+    } finally {
+      schema.setProfile(prev);
+    }
+  });
+}
+
 class Store {
   // ── Schema 管理 ──
   register(defn) {
@@ -113,6 +139,33 @@ class Store {
     return syncSchema(opts);
   }
 
+  // ── 事务 + 原生 SQL（复用 datasource.runInTransaction；见 README「事务边界」）──
+  /**
+   * 事务作用域：单 SQL 源「同连接 + 同事务」执行 fn（复用 runInTransaction）
+   *
+   * fn 内 executeRaw / CRUD 均落到该源的事务连接（commit/rollback 一体）；
+   * Mongo 源或执行器未实现 withTransaction 时按原样执行（跨源无法原子），
+   * 绝不静默假装已事务化。单源场景 source 传 'default'。
+   */
+  async transaction(source, fn) {
+    return datasource.runInTransaction(source, fn);
+  }
+
+  /**
+   * 在指定 SQL 源执行原生 SQL（事务内可用；占位符按各后端原生风格）
+   *
+   * mysql/sqlite 用 `?`，postgres 用 `$1..$n`；仅支持 SQL 源（Mongo 源抛 RawSqlError）。
+   * isWrite=false 取行（rows），true 取影响行数（affectedRows）。对齐 py-store store.execute_raw。
+   */
+  async executeRaw(source, sql, params, isWrite) {
+    return datasource.executeRaw(source, sql, params, isWrite);
+  }
+
+  /** 从已注册 schema def 生成指定后端 DDL 文本（纯函数，不连库、不回写；铁律 6） */
+  generateDdl(backend, names) {
+    return ddl.generate(backend, names);
+  }
+
   // ── 底层工具（调试/高级用法） ──
   /** 解析 GQL 并构建 pipeline，返回 `{tokens, ast, pipeline, projection}` */
   buildPipeline(gql, params) {
@@ -133,6 +186,26 @@ class Store {
     return schema.requireContext();
   }
 
+  // ── 查询档位（判决唯一在 core）：standard 默认放开 / text2query 功能收缩 ──
+  /**
+   * 设置查询档位：`'standard'`（默认，功能最大化 + 跨 DB 对齐）/
+   * `'text2query'`（功能收缩 + 硬限制）。进入档即等效强制 ctx；
+   * 未知档由 core 抛错（禁静默回落默认档）。
+   */
+  setProfile(profile) {
+    return schema.setProfile(profile);
+  }
+
+  /** 当前查询档位字符串（对齐 py-store store.get_profile） */
+  getProfile() {
+    return schema.getProfile();
+  }
+
+  /** text2query 便捷上下文（进入设档、退出恢复；同 scopedRoles 的 token-set/reset） */
+  async text2query(fn) {
+    return text2query(fn);
+  }
+
   /** 设置数据源连接映射（多后端路由；对齐 py-store store.set_connections） */
   setConnections(connections) {
     return datasource.setConnections(connections);
@@ -163,6 +236,10 @@ class Store {
 
 /** 自定义权限错误（实例可被 store.PermissionError 捕获） */
 Store.prototype.PermissionError = permission.PermissionError;
+/** 档位拒绝错误（实例可被 store.ProfileViolation 捕获；权限错误另见 PermissionError） */
+Store.prototype.ProfileViolation = crud.ProfileViolation;
+/** 原生 SQL 入口错误（实例可被 store.RawSqlError 捕获） */
+Store.prototype.RawSqlError = datasource.RawSqlError;
 
 const store = new Store();
 
@@ -253,9 +330,13 @@ module.exports = {
   init,
   store,
   Store,
+  text2query,
   PermissionError: permission.PermissionError,
+  ProfileViolation: crud.ProfileViolation,
   PushdownUnsupportedError: datasource.PushdownUnsupportedError,
+  RawSqlError: datasource.RawSqlError,
   datasource,
+  ddl,
   schema,
   permission,
   crud,

package/src/schema.js

@@ -115,9 +115,35 @@ function requireContext() {
   return core.requireContext();
 }
 
+/**
+ * 设置查询档位：`'standard'`（默认，功能最大化 + 跨 DB 对齐）/
+ * `'text2query'`（功能收缩 + 硬限制）
+ *
+ * 判决唯一在 core；未知档位由 core 抛错（禁静默回落到默认档）。
+ */
+function setProfile(profile) {
+  core.setProfile(profile);
+}
+
+/** 当前档位字符串（`'standard'` / `'text2query'`；对齐 py_store.schema.get_profile） */
+function getProfile() {
+  return core.profile();
+}
+
 /** 取 asyncFn 计算列实现（fnRef 缺省 = 计算列 key 名） */
 function getAsyncFn(fnRef) {
   return _asyncFns[fnRef];
 }
 
-module.exports = { core, register, get, has, list, setRequireContext, requireContext, getAsyncFn };
+module.exports = {
+  core,
+  register,
+  get,
+  has,
+  list,
+  setRequireContext,
+  requireContext,
+  setProfile,
+  getProfile,
+  getAsyncFn,
+};