nodejs-store 2.1.0 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nodejs-store",
-  "version": "2.1.0",
+  "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/ddl.js

@@ -4,7 +4,9 @@
  * DDL 生成（schema def → CREATE TABLE 文本；纯函数，不连库、不回写）
  *
  * 与 core 契约严格对齐（schema→DDL 单向映射）：
- *   - 只对 scalar 字段建列（object/array 不建列；同 core dialect::scalar_column）；
+ *   - 标量字段按声明类型建列；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 逐表生成（不特判）；
@@ -33,6 +35,8 @@ const TYPES = {
   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'];
@@ -52,18 +56,22 @@ function declaredType(fieldDef) {
   return fieldDef && typeof fieldDef === 'object' ? fieldDef.type : fieldDef;
 }
 
-/** 返回 [[name, sqlType, pk]]，顺序：声明的标量字段 → timestamps → __present */
+/** 返回 [[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 (NON_COLUMN.includes(ftype)) continue;
     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()}`,

package/src/index.js

@@ -21,6 +21,8 @@
  *   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');
@@ -31,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) {
@@ -161,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);
@@ -191,6 +236,8 @@ 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;
 
@@ -283,7 +330,9 @@ module.exports = {
   init,
   store,
   Store,
+  text2query,
   PermissionError: permission.PermissionError,
+  ProfileViolation: crud.ProfileViolation,
   PushdownUnsupportedError: datasource.PushdownUnsupportedError,
   RawSqlError: datasource.RawSqlError,
   datasource,

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,
+};