nodejs-store 1.0.0 → 1.1.0

package/README.md

@@ -105,6 +105,10 @@ await store.query('User($condition:@c0){...}', params, { namespace: 'tenant_42'
 await store.insert('Order', data, { source: 'pg_cluster', namespace: 'tenant_7' });
 ```
 
+**`routeOverride` is a trusted server-side parameter** — it carries no origin check, so
+forwarding user-controlled input into it lets a caller re-target another tenant's
+`source`/`namespace` (CWE-639 authorization-bypass surface). Never pass raw request data here.
+
 Legacy single-db usage (`init(db)` + schema without `datasource`/`namespace`) is unchanged:
 commands carry `source: 'default'`, `namespace: null`.
 
@@ -165,6 +169,22 @@ await store.runAsInternal(() => store.remove('Post', { _id: pid }));
 - No context set → permission checks disabled (backward compatible).
 - Denied access throws `store.PermissionError` (with `status = 403`).
 
+### Fail-secure mode (opt-in)
+
+"No context" can mean both *system call* and *caller forgot the context* — by default the
+latter silently passes every check (fail-open, kept for backward compatibility). For
+security-sensitive hosts, enable the context requirement once at startup:
+
+```js
+store.setRequireContext(true);
+// now every query/write without a context throws `ERR_NO_CONTEXT:...`
+// internal jobs must be explicit:
+await store.runAsInternal(() => store.remove('Post', { _id: pid }));
+```
+
+`runAsInternal` marks the call as `{ internal: true }`, which is semantically distinct from
+a missing context and always passes. `setRequireContext(false)` restores the default.
+
 ## Schema reference
 
 ```js
@@ -196,6 +216,102 @@ await store.runAsInternal(() => store.remove('Post', { _id: pid }));
 
 Types: `string | int | long | float | double | boolean | array | object | date | any`.
 
+## Advanced API
+
+Everything below is reachable from the exported `store` singleton or the modules it
+re-exports. Options prefixed with `?` are optional.
+
+### `store.buildPipeline(gql, params?)`
+
+Low-level parse — compiles GQL to the command plan **without executing it**, returning
+`{ tokens, ast, pipeline, projection }`. Useful for debugging query shape, asserting
+pushdown behaviour, or building custom tooling. Permissions / computes are **not** applied here.
+
+```js
+const plan = store.buildPipeline('Post($condition:@c0){ title }', { c0: { status: 'draft' } });
+console.log(plan.pipeline);
+```
+
+### `store.syncSchema(opts)`
+
+Pull a SQL backend's physical structure into the registry
+(`introspect → schemaFromRows → mergeSchema(overlay) → register`). It only **reads** the
+structure — it never writes DDL back to the database.
+
+| Option | Type | Meaning |
+| --- | --- | --- |
+| `backend` | `'mysql' \| 'postgres' \| 'sqlite'` | required |
+| `driver` | object | required; prefer a read-only account |
+| `introspectOptions` | object | passed through to introspection (e.g. PG `schema`) |
+| `overlay` | `Array` | local schemaJSON merged on top (permissions / computes / overrides) |
+| `datasource` | string | bind every merged def to this source |
+| `namespace` | string | bind every merged def to this namespace |
+| `registerDefs` | boolean (default `true`) | `false` = return defs without registering |
+
+Returns the merged `schemaJSON[]`.
+
+```js
+const defs = await store.syncSchema({
+  backend: 'postgres', driver: pgPool, overlay: [Post], datasource: 'pg_a',
+});
+```
+
+### `store.setAllowUserPipeline(allow = true)`
+
+Registry-level guard for user-supplied `$pipeline` passthrough. Default is **allow**
+(backward compatible); AI / 问数 hosts should call `store.setAllowUserPipeline(false)` as
+defense in depth. `store.setRequireContext(...)` (fail-secure mode) is documented under
+[Fail-secure mode](#fail-secure-mode-opt-in).
+
+### `store.setFeedbackSink(fn)`
+
+Take over the unified feedback channel used for fallback / degradation / interception
+events. The sink receives one event object; pass `null` (or a non-function) to fall back to
+the default stderr printer.
+
+```js
+store.setFeedbackSink((e) => logger.warn({ code: e.code }, e.hint));
+// event shape: { type, code, layer, message, hint, ... }
+//   type   federation_degraded | sql_pushdown_unsupported | ...
+//   code   crossSourceSort | pushdownUnsupported | ...
+//   layer  federation | dialect | ...
+```
+
+### Low-level modules
+
+The package re-exports its building blocks for advanced hosts:
+
+```js
+const {
+  init, store, Store,
+  aggregate,                    // standalone aggregate(schemaName, pipeline, routeOverride)
+  PermissionError,              // thrown on denied access (status = 403)
+  PushdownUnsupportedError,     // thrown when a command cannot be safely pushed down
+  datasource, schema, permission, crud, executors, feedback, introspect,
+  syncSchema,                   // same function as store.syncSchema
+} = require('nodejs-store');
+
+// introspect.run(backend, driver, options) → normalized structure rows
+const rows = await introspect.run('mysql', pool, {});
+
+// executors.createConnection(kind, driver, options) → SQL datasource descriptor { kind, exec }
+await init({ default: db, pg_a: executors.createConnection('postgres', pgPool) });
+```
+
+- `schema` / `permission` / `feedback` / `datasource` expose the same functions the `store`
+  singleton delegates to (e.g. `datasource.setConnections`, `datasource.hasConnection`,
+  `datasource.isSql`, `datasource.runInTransaction`).
+- **Multi-tenant route override** — pass `{ source, namespace }` as the last argument of any
+  query/write, see [Multi-datasource connections](#multi-datasource-connections).
+
+## Transaction boundary
+
+- **Single SQL source**: `mutation` parent-child step sequences and `remove` (archive + delete) run inside one driver transaction on one checked-out connection — any step failure rolls back the whole sequence.
+- **Each SQL write command** is itself atomic: multi-statement plans (e.g. MySQL write + readback) are transaction-wrapped in the executor.
+- **Mongo sources**: single-document writes are atomic; multi-step `mutation` and `remove` execute sequentially and are **not** atomic across steps (Mongo transactions require a replica set). If your consistency requirement spans steps on Mongo, either use an SQL source for those models or add application-level compensation.
+- **Archive idempotency**: `remove` archives with upsert-by-`_id` semantics, so a retry after partial failure no longer fails on duplicate `_id`.
+- **Cross-source steps** (parent and child bound to different datasources) cannot be atomic — they run sequentially by design.
+
 ## License
 
 [MIT](LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nodejs-store",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Lightweight multi-backend data layer (MongoDB / MySQL / SQLite / PostgreSQL): pure JSON schemas, GQL tree queries compiled to a single query, computed columns, soft-delete and role-based access control",
   "main": "src/index.js",
   "files": [
@@ -9,7 +9,9 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node scripts/test.js"
+    "test": "node scripts/test.js",
+    "test:coverage": "c8 --all --include src/** -x **/rust-store/** --reporter=text --reporter=html --check-coverage --statements 90 --lines 90 --functions 85 --branches 75 node scripts/test.js",
+    "lint": "eslint ."
   },
   "keywords": [
     "mongodb",
@@ -42,5 +44,11 @@
     "mysql2": "^3.24.4",
     "pg": "^8.23.0",
     "rust-store-node": "^1.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "c8": "^10.1.3",
+    "eslint": "^9.39.2",
+    "globals": "^15.15.0"
   }
 }

package/src/core.js

@@ -34,6 +34,12 @@ function _requireDevFallback() {
 }
 
 function _load() {
+  // LOCAL_CORE=1（且非 production）优先加载本地调试产物 —— 使「从相邻 rust-store
+  // 仓库加载」的语义与文档一致；未设置或加载失败再走 npm 依赖。
+  if (process.env.LOCAL_CORE === '1' && process.env.NODE_ENV !== 'production') {
+    const local = _requireDevFallback();
+    if (local && !local.__error) return local;
+  }
   try {
     return require('rust-store-node');
   } catch (e) {

package/src/crud/exec.js

@@ -14,31 +14,40 @@
 
 const { PermissionError, getContext } = require('../permission');
 const datasource = require('../datasource');
+const { get: _getSchema } = require('../schema');
 
 const _PHASE1_IDS = /^\{\{phase1\.ids\}\}$/;
 const _STEP_PH = /^\{\{step\.(\d+)\._id\}\}$/;
 
-/** core 权限类错误消息 → PermissionError（消息与 core 常量保持一致） */
-const _PERMISSION_MSGS = new Set(['无访问权限', '无写入权限', '无删除权限', '无批量写入权限']);
+/**
+ * 权限类错误识别：core 权限错误统一携带 `ERR_PERMISSION:` 稳定前缀（见 core
+ * `command/mod.rs::ERR_PERM_PREFIX`），按**前缀**映射而非具体文案 —— core 文案
+ * 可自由调整，映射不随文案漂移而静默失效。构造 PermissionError 时剥离前缀。
+ */
+const _PERM_PREFIX = 'ERR_PERMISSION:';
 
 /** 设置数据源连接映射（对 `../datasource` 的路由入口做包内透出） */
 const setConnections = datasource.setConnections;
 
-/** 毫秒时间戳（Host 时钟源） */
-function _now() {
-  return Date.now();
+/** 按 schema 的 timestamps 单位产出当前时间戳（'s' → 秒，其余/未启用 → 毫秒） */
+function _nowFor(schemaName) {
+  const unit = _getSchema(schemaName).timestampUnit;
+  return unit === 's' ? Math.floor(Date.now() / 1000) : Date.now();
 }
 
 function _ctx() {
   return getContext() ?? null;
 }
 
-/** 绑定层调用包装：权限类错误映射为 PermissionError */
+/** 绑定层调用包装：权限类错误（`ERR_PERMISSION:` 前缀）映射为 PermissionError */
 function _call(fn) {
   try {
     return fn();
   } catch (e) {
-    if (_PERMISSION_MSGS.has(e && e.message)) throw new PermissionError(e.message);
+    const msg = e && e.message;
+    if (typeof msg === 'string' && msg.startsWith(_PERM_PREFIX)) {
+      throw new PermissionError(msg.slice(_PERM_PREFIX.length));
+    }
     throw e;
   }
 }
@@ -65,6 +74,14 @@ async function _execMongo(db, cmd) {
       await coll.insertOne(cmd.doc);
       return cmd.doc;
     case 'insertMany':
+      if (cmd.upsertById) {
+        // 归档幂等（core planArchiveDocs）：按 _id 逐条覆盖 —— 「归档成功但删除失败」
+        // 的重试不再因 _id 冲突整批失败。SQL 侧由 dialect 的 ON CONFLICT/REPLACE 承接。
+        for (const doc of cmd.docs) {
+          await coll.replaceOne({ _id: doc._id }, doc, { upsert: true });
+        }
+        return { insertedCount: cmd.docs.length };
+      }
       await coll.insertMany(cmd.docs);
       return { insertedCount: cmd.docs.length };
     case 'findOneAndUpdate':
@@ -78,9 +95,10 @@ async function _execMongo(db, cmd) {
   }
 }
 
-/** 在指定数据源上执行命令（Mongo 走原生驱动，SQL 走 translate → exec） */
+/** 在指定数据源上执行命令（Mongo 走原生驱动，SQL 走 translate → exec；
+ * 事务作用域内经 datasource.connectionFor 落到事务专用连接） */
 async function _execOn(source, cmd) {
-  const connection = datasource.getConnection(source);
+  const connection = datasource.connectionFor(source);
   const db = datasource.mongoDb(connection, source, cmd.namespace ?? null);
   if (db) {
     return _execMongo(db, cmd);
@@ -129,7 +147,7 @@ function resolvePlaceholders(command, { ids = null, steps = [] } = {}) {
 
 module.exports = {
   setConnections,
-  _now,
+  _nowFor,
   _ctx,
   _call,
   _exec,

package/src/crud/id.js

@@ -4,18 +4,23 @@
  * ID 供给（Host 随机源） —— 与 core `needs_new_id` 语义对齐
  *
  * core 无随机源：需要新 _id 时由 Host 按序供给，本模块负责生成与遍历。
+ * 随机段使用 crypto 强随机源 8 位 base36（约 41 bit 熵）：Math.random 仅 4 位
+ * （36^4 ≈ 168 万组合），insertMany 同毫秒批量生成时碰撞概率不可忽略（CWE-338）。
  */
 
+const crypto = require('node:crypto');
+
 const { get: _getSchema } = require('../schema');
 
 const _ID_CHARS = 'abcdefghijklmnopqrstuvwxyz0123456789';
 
-/** 按 schema.idPrefix 生成唯一 ID（时间戳36进制 + 随机4位） */
+/** 按 schema.idPrefix 生成唯一 ID（时间戳36进制 + crypto 随机8位） */
 function _generateId(schema) {
   const ts = Date.now().toString(36).toUpperCase();
   let rnd = '';
-  for (let i = 0; i < 4; i++) {
-    rnd += _ID_CHARS[Math.floor(Math.random() * _ID_CHARS.length)];
+  for (let i = 0; i < 8; i++) {
+    // crypto.randomInt 内部拒绝采样，无取模偏差
+    rnd += _ID_CHARS[crypto.randomInt(_ID_CHARS.length)];
   }
   return schema.idPrefix + ts + rnd.toUpperCase();
 }

package/src/crud/index.js

@@ -19,7 +19,7 @@
  *   - [`mutation`]：mutation / upsert / 原生聚合
  */
 
-const { setConnections, _now, _ctx, _call, _exec, _substitute, resolvePlaceholders } = require('./exec');
+const { setConnections, _nowFor, _ctx, _call, _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');
@@ -48,7 +48,7 @@ module.exports = {
   _truthy,
   _newIdPool,
   // ── 内部工具（包内共享） ──
-  _now,
+  _nowFor,
   _ctx,
   _call,
   _exec,

package/src/crud/mutation.js

@@ -5,25 +5,36 @@
  */
 
 const { core: _core, get: _getSchema } = require('../schema');
-const { _call, _ctx, _exec, _now, resolvePlaceholders } = require('./exec');
+const datasource = require('../datasource');
+const { _call, _ctx, _exec, _nowFor, resolvePlaceholders } = require('./exec');
 const { _generateId, _newIdPool } = require('./id');
 
 /** mutation 单条：规划步骤序列 → 依序执行 + 父子 _id 占位符回填 */
 async function _mutationOne(schemaName, data, routeOverride = null) {
   const plan = _call(() =>
-    _core.planMutation(schemaName, data, _now(), _newIdPool(schemaName, data), _ctx(),
+    _core.planMutation(schemaName, data, _nowFor(schemaName), _newIdPool(schemaName, data), _ctx(),
       routeOverride));
 
-  const resolved = [];
-  let rootResult = null;
-  for (const [i, step] of plan.steps.entries()) {
-    const cmd = resolvePlaceholders(step.command, { steps: resolved });
-    const result = await _exec(cmd);
-    resolved.push(result ? (result._id ?? null) : null);
-    if (i === 0) rootResult = result; // 首步即根写入
-  }
+  const runSteps = async () => {
+    const resolved = [];
+    let rootResult = null;
+    for (const [i, step] of plan.steps.entries()) {
+      const cmd = resolvePlaceholders(step.command, { steps: resolved });
+      const result = await _exec(cmd);
+      resolved.push(result ? (result._id ?? null) : null);
+      if (i === 0) rootResult = result; // 首步即根写入
+    }
+
+    return rootResult ? _call(() => _core.applyWriteDefaults(schemaName, rootResult)) : null;
+  };
 
-  return rootResult ? _call(() => _core.applyWriteDefaults(schemaName, rootResult)) : null;
+  // 单一 SQL 源 → 步骤序列整体事务化（同连接同事务，任一步失败整体回滚）；
+  // Mongo 源 / 跨源步骤按原样顺序执行（非原子边界见 README「事务边界」）
+  const sources = [...new Set(plan.steps.map((s) => s.command.source || datasource.DEFAULT_SOURCE))];
+  if (sources.length === 1 && datasource.isSql(sources[0])) {
+    return datasource.runInTransaction(sources[0], runSteps);
+  }
+  return runSteps();
 }
 
 /**
@@ -54,7 +65,7 @@ async function mutation(schemaName, data, routeOverride = null) {
 async function upsert(schemaName, condition, data, options = null, routeOverride = null) {
   const s = _getSchema(schemaName);
   const plan = _call(() => _core.planUpsert(
-    schemaName, condition ?? null, data ?? null, options ?? null, _now(),
+    schemaName, condition ?? null, data ?? null, options ?? null, _nowFor(schemaName),
     s.idPrefix ? _generateId(s) : '', _ctx(), routeOverride,
   ));
   const result = await _exec(plan.command);

package/src/crud/query.js

@@ -6,6 +6,7 @@
  */
 
 const { core: _core, getAsyncFn } = require('../schema');
+const { emit: _emitFeedback } = require('../feedback');
 const { _call, _ctx, _exec, _execOn, resolvePlaceholders } = require('./exec');
 
 /** 执行读命令序列：find 快路径 / 两阶段（取 ID → 关联 → 还原排序）/ 标准聚合 */
@@ -48,9 +49,10 @@ async function query(gql, params = null, routeOverride = null) {
   return _finalize(plan, await _runQueryPlan(plan));
 }
 
-/** GQL 查询（返回单条） */
+/** GQL 查询（返回单条）—— 走 core `planQueryOne`：未显式 `$limit` 时下推 `$limit(1)` */
 async function queryOne(gql, params = null, routeOverride = null) {
-  const items = await query(gql, params, routeOverride);
+  const plan = _call(() => _core.planQueryOne(gql, params ?? {}, _ctx(), routeOverride));
+  const items = await _finalize(plan, await _runQueryPlan(plan));
   return items.length ? items[0] : null;
 }
 
@@ -75,8 +77,8 @@ async function _runFederatedUnit(unit) {
 /**
  * 跨库联邦查询（返回嵌套文档数组）
  *
- * Host 四步：core `planFederated` 拆源 → 逐源执行 → core `mergeFederated`
- * 内存 hash join → 统一后处理（`_finalize`，与单库同一路径）。
+ * Host 四步：core `planFederated` 拆源 → 并行逐源执行（任一源失败整体失败）
+ * → core `mergeFederated` 内存 hash join → 统一后处理（`_finalize`，与单库同一路径）。
  *
  * `postprocess` 取自根单元快照（含全部关系），因此结果形状与单库 `query` 完全一致。
  * 每源取数上限 `MAX_FEDERATION_ROWS` 由 core 强制（超限即报错，拒绝静默全表拉取）；
@@ -86,13 +88,11 @@ async function queryFederated(gql, params = null) {
   const plan = _call(() => _core.planFederated(gql, params ?? {}, _ctx()));
 
   for (const d of plan.degraded || []) {
-    console.warn(`[federation] 降级 ${(d && d.code) || ''}: ${(d && d.message) || ''}`);
+    // 降级事件走统一反馈通道（无 sink 时打 stderr，允许拦截，禁止静默失守）
+    _emitFeedback({ ...(d || {}), type: 'federation_degraded' });
   }
 
-  const results = [];
-  for (const unit of plan.sources || []) {
-    results.push(await _runFederatedUnit(unit));
-  }
+  const results = await Promise.all((plan.sources || []).map(_runFederatedUnit));
 
   const merged = _call(() => _core.mergeFederated(plan, results));
   return _finalize(plan, merged);

package/src/crud/write.js

@@ -5,7 +5,8 @@
  */
 
 const { core: _core, get: _getSchema } = require('../schema');
-const { _call, _ctx, _exec, _now } = require('./exec');
+const datasource = require('../datasource');
+const { _call, _ctx, _exec, _nowFor } = require('./exec');
 const { _generateId } = require('./id');
 
 /** creator 写权限探针：先规划，若 needsProbe 则执行探针命令后重入 */
@@ -22,7 +23,7 @@ async function _planWithProbe(planFn) {
 async function insert(schemaName, data, routeOverride = null) {
   const s = _getSchema(schemaName);
   const plan = _call(() =>
-    _core.planInsert(schemaName, data ?? null, _now(), s.idPrefix ? _generateId(s) : '', _ctx(),
+    _core.planInsert(schemaName, data ?? null, _nowFor(schemaName), s.idPrefix ? _generateId(s) : '', _ctx(),
       routeOverride));
   await _exec(plan.command);
   return plan.returns;
@@ -36,7 +37,7 @@ async function insertMany(schemaName, docs, routeOverride = null) {
   const plan = _call(() => _core.planInsertMany(
     schemaName,
     docs,
-    _now(),
+    _nowFor(schemaName),
     // core 按需消费（仅无 _id 的文档取用），多备无害
     docs.map(() => (s.idPrefix ? _generateId(s) : '')),
     _ctx(),
@@ -54,7 +55,7 @@ async function insertMany(schemaName, docs, routeOverride = null) {
  */
 async function update(schemaName, condition, data, options = null, routeOverride = null) {
   const out = await _planWithProbe((found, doc) => _call(() =>
-    _core.planUpdate(schemaName, condition ?? null, data ?? null, options ?? null, _now(), _ctx(),
+    _core.planUpdate(schemaName, condition ?? null, data ?? null, options ?? null, _nowFor(schemaName), _ctx(),
       found, doc, routeOverride)));
   const result = await _exec(out.command);
   return result ? _call(() => _core.applyWriteDefaults(schemaName, result)) : null;
@@ -63,28 +64,40 @@ async function update(schemaName, condition, data, options = null, routeOverride
 /** 批量更新（支持原生操作符） */
 async function updateMany(schemaName, condition, data, routeOverride = null) {
   const out = _call(() =>
-    _core.planUpdateMany(schemaName, condition ?? null, data ?? null, _now(), _ctx(), routeOverride));
+    _core.planUpdateMany(schemaName, condition ?? null, data ?? null, _nowFor(schemaName), _ctx(), routeOverride));
   const result = await _exec(out.command);
   return { modifiedCount: result.modifiedCount };
 }
 
-/** 删除 —— 原表数据先归档到对应 `_deleted` 附表（附 deletedAt），再物理删除原表数据 */
+/** 删除 —— 原表数据先归档到对应 `_deleted` 附表（附 deletedAt），再物理删除原表数据。
+ * 归档命令带 `upsertById`（幂等），重试不再因 _id 冲突整批失败；单一 SQL 源时
+ * 归档+删除整体事务化（Mongo / 跨源按顺序执行，非原子边界见 README「事务边界」） */
 async function remove(schemaName, condition, routeOverride = null) {
   const out = await _planWithProbe((found, doc) => _call(() =>
     _core.planRemove(schemaName, condition ?? null, _ctx(), found, doc, routeOverride)));
 
-  let archivedCount = 0;
-  if (out.findCommand) {
-    const docs = await _exec(out.findCommand);
-    if (docs.length) {
-      const arch = _call(() => _core.planArchiveDocs(schemaName, docs, _now(), routeOverride));
-      await _exec(arch.command);
-      archivedCount = docs.length;
+  const doRemove = async () => {
+    let archivedCount = 0;
+    if (out.findCommand) {
+      const docs = await _exec(out.findCommand);
+      if (docs.length) {
+        const arch = _call(() => _core.planArchiveDocs(schemaName, docs, _nowFor(schemaName), routeOverride));
+        await _exec(arch.command);
+        archivedCount = docs.length;
+      }
     }
-  }
 
-  const result = await _exec(out.deleteCommand);
-  return { deletedCount: result.deletedCount, archivedCount };
+    const result = await _exec(out.deleteCommand);
+    return { deletedCount: result.deletedCount, archivedCount };
+  };
+
+  const sources = new Set([out.deleteCommand.source || datasource.DEFAULT_SOURCE]);
+  if (out.findCommand) sources.add(out.findCommand.source || datasource.DEFAULT_SOURCE);
+  const arr = [...sources];
+  if (arr.length === 1 && datasource.isSql(arr[0])) {
+    return datasource.runInTransaction(arr[0], doRemove);
+  }
+  return doRemove();
 }
 
 /** 判断是否存在 */

package/src/datasource.js

@@ -18,13 +18,48 @@
  * `{ default: db }`，保证既有单库调用零变更。
  */
 
+const { AsyncLocalStorage } = require('node:async_hooks');
 const { core: _core, get: _getSchema } = require('./schema');
+const { emit: _emitFeedback } = require('./feedback');
 const executors = require('./executors');
 
 const DEFAULT_SOURCE = 'default';
 
 let _connections = Object.create(null);
 
+/** 事务作用域的连接覆盖：source → 事务描述符（见 runInTransaction） */
+const _txStore = new AsyncLocalStorage();
+
+/**
+ * SQL 下推遇到无法安全翻译的组合（core 标记 unsupported）
+ *
+ * 显式报错而非静默执行「缺少该段」的 SQL（会返回错误结果）；
+ * 自动反馈：触发原因见 message，修复指引见 feedback()。
+ */
+class PushdownUnsupportedError extends Error {
+  constructor(source, kind, codes, warnings) {
+    super(`SQL 下推不支持（${kind}）: ${codes.join(', ')}；${warnings.join(' / ')}`);
+    this.name = 'PushdownUnsupportedError';
+    this.source = source;
+    this.kind = kind;
+    this.codes = codes;
+    this.warnings = warnings;
+  }
+
+  /** 转统一反馈事件（与 feedback.emit 的事件形状一致） */
+  feedback() {
+    return {
+      type: 'sql_pushdown_unsupported',
+      code: 'pushdownUnsupported',
+      layer: 'dialect',
+      message: this.message,
+      hint: '改写查询避开该组合，或改用 Mongo 源执行该段取数',
+      source: this.source,
+      kind: this.kind,
+    };
+  }
+}
+
 /** Mongo 形态判别：db 实例（collection 为函数）或 MongoClient（db 为函数且无 collection） */
 function _isMongoHandle(x) {
   return (
@@ -58,6 +93,64 @@ function getConnection(source) {
   return conn;
 }
 
+/** 指定数据源是否已在当前连接映射中配置（辅助动作「软跳过」判定用，如 init 建索引） */
+function hasConnection(source) {
+  return _connections[source] !== undefined;
+}
+
+/** 连接是否为 SQL 执行器描述符（`{ kind, exec }`；Mongo 为驱动实例） */
+function isSqlConnection(connection) {
+  return (
+    !!connection &&
+    typeof connection.kind === 'string' &&
+    typeof connection.exec === 'function'
+  );
+}
+
+/** 数据源名是否绑定 SQL 源 */
+function isSql(source) {
+  return isSqlConnection(getConnection(source));
+}
+
+/**
+ * 当前生效连接：事务作用域内返回覆盖描述符，否则返回全局映射的连接
+ * （`exec.js#_execOn` 经此取连接，使事务内所有命令落到专用连接）
+ */
+function connectionFor(source) {
+  const store = _txStore.getStore();
+  if (store && store.has(source)) return store.get(source);
+  return getConnection(source);
+}
+
+/**
+ * 事务作用域：在单个 SQL 源上以「同连接 + 同事务」执行 fn 内的全部命令
+ *
+ *   - fn 内经 `_exec` 路由到该 source 的命令全部落到事务连接（commit/rollback 一体）；
+ *   - Mongo 源 / 执行器未实现 withTransaction / 多源混合时按原样执行
+ *     （跨源无法原子 —— 信任边界见 README「事务边界」），绝不静默假装已事务化；
+ *   - 事务体抛错统一 rollback 后原样上抛。
+ */
+async function runInTransaction(source, fn) {
+  const conn = getConnection(source);
+  if (!isSqlConnection(conn) || typeof conn.withTransaction !== 'function') {
+    return fn();
+  }
+  const parent = _txStore.getStore();
+  const store = new Map(parent || []);
+  if (store.has(source)) {
+    // 同源嵌套事务：外层已持有该源的事务连接，内层并入外层（不做保存点）
+    return fn();
+  }
+  const txDescriptor = { kind: conn.kind, exec: null };
+  store.set(source, txDescriptor);
+  return _txStore.run(store, () =>
+    conn.withTransaction(async (execOnTx) => {
+      txDescriptor.exec = execOnTx;
+      return fn();
+    }),
+  );
+}
+
 /**
  * Mongo 源：按命令的 `namespace` 解析目标 db（两种形态，绝不猜）
  *
@@ -126,10 +219,15 @@ async function execSql(source, connection, cmd) {
   // Host 兜底：core 标记了无法安全下推的组合（如 $lookup 子 $limit 每父 top-N）时，
   // 绝不执行「缺少该段」的 SQL（会静默返回错误结果），改为显式报错，由调用方降级重查。
   if (Array.isArray(plan.unsupported) && plan.unsupported.length > 0) {
-    const codes = plan.unsupported.map((u) => (u && u.code) || String(u)).join(', ');
-    throw new Error(
-      `SQL 下推不支持（${connection.kind}）: ${codes}；${(plan.warnings || []).join(' / ')}`,
+    const err = new PushdownUnsupportedError(
+      source,
+      connection.kind,
+      plan.unsupported.map((u) => (u && u.code) || String(u)),
+      (plan.warnings || []).map((w) => String(w)),
     );
+    // 自动反馈：拦截即告警（无 sink 时打 stderr），禁止静默失守
+    _emitFeedback(err.feedback());
+    throw err;
   }
   const out = await connection.exec(plan);
   return executors.shapeResult(cmd, out);
@@ -139,10 +237,16 @@ module.exports = {
   DEFAULT_SOURCE,
   setConnections,
   getConnection,
+  hasConnection,
+  isSqlConnection,
+  isSql,
+  connectionFor,
+  runInTransaction,
   mongoDb,
   sourceOfSchema,
   connectionOfSchema,
   dbOfSchema,
   route,
   execSql,
+  PushdownUnsupportedError,
 };

package/src/executors/mysql.js

@@ -23,22 +23,49 @@ function create(driver, _options = {}) {
   if (!driver || typeof driver.execute !== 'function') {
     throw new TypeError('mysql 执行器需要 mysql2/promise 的连接或连接池');
   }
+
+  /** 在指定连接上依序执行 plan.stmts（多语句 plan 由 withTransaction 包事务） */
+  async function runStmts(conn, plan) {
+    let docs = null;
+    let rows = null;
+    let affectedRows = 0;
+    for (const stmt of plan.stmts) {
+      const [raw] = await conn.execute(stmt.text, stmt.params || []);
+      if (Array.isArray(raw)) {
+        rows = raw.map(_plain);
+        if (stmt.rowShape) docs = _core.restoreRows(stmt.rowShape, rows);
+      } else {
+        affectedRows = Number(raw.affectedRows || 0);
+      }
+    }
+    return { docs, rows, affectedRows };
+  }
+
   return {
     kind: 'mysql',
-    async exec(plan) {
-      let docs = null;
-      let rows = null;
-      let affectedRows = 0;
-      for (const stmt of plan.stmts) {
-        const [raw] = await driver.execute(stmt.text, stmt.params || []);
-        if (Array.isArray(raw)) {
-          rows = raw.map(_plain);
-          if (stmt.rowShape) docs = _core.restoreRows(stmt.rowShape, rows);
-        } else {
-          affectedRows = Number(raw.affectedRows || 0);
+    exec: (plan) => runStmts(driver, plan),
+    /**
+     * 事务执行：body(executeOnTx) 的所有 plan 落在同一连接同一事务内，
+     * 成功 commit / 失败 rollback。池自动取专用连接（结束归还）。
+     */
+    async withTransaction(body) {
+      const conn =
+        typeof driver.getConnection === 'function' ? await driver.getConnection() : driver;
+      try {
+        await conn.beginTransaction();
+        const out = await body((plan) => runStmts(conn, plan));
+        await conn.commit();
+        return out;
+      } catch (e) {
+        try {
+          await conn.rollback();
+        } catch (_) {
+          /* rollback 失败不掩盖原始错误 */
         }
+        throw e;
+      } finally {
+        if (conn !== driver && typeof conn.release === 'function') conn.release();
       }
-      return { docs, rows, affectedRows };
     },
   };
 }

package/src/executors/postgres.js

@@ -16,19 +16,58 @@ function create(driver, _options = {}) {
   if (!driver || typeof driver.query !== 'function') {
     throw new TypeError('postgres 执行器需要 pg 的 Pool/Client 实例');
   }
+
+  /** 在指定连接上依序执行 plan.stmts */
+  async function runStmts(conn, plan) {
+    let docs = null;
+    let rows = null;
+    let affectedRows = 0;
+    for (const stmt of plan.stmts) {
+      const res = await conn.query(stmt.text, stmt.params || []);
+      rows = res.rows || [];
+      affectedRows = Number(res.rowCount || 0);
+      if (stmt.rowShape) docs = _core.restoreRows(stmt.rowShape, rows);
+    }
+    return { docs, rows, affectedRows };
+  }
+
   return {
     kind: 'postgres',
-    async exec(plan) {
-      let docs = null;
-      let rows = null;
-      let affectedRows = 0;
-      for (const stmt of plan.stmts) {
-        const res = await driver.query(stmt.text, stmt.params || []);
-        rows = res.rows || [];
-        affectedRows = Number(res.rowCount || 0);
-        if (stmt.rowShape) docs = _core.restoreRows(stmt.rowShape, rows);
+    exec: (plan) => runStmts(driver, plan),
+    /**
+     * 事务执行：显式 BEGIN/COMMIT/ROLLBACK 包住 body 的全部 plan。
+     * Pool 自动 checkout 专用 client（`release()` 归还）；Client 直连直接用。
+     */
+    async withTransaction(body) {
+      let conn = driver;
+      let release = null;
+      if (typeof driver.connect === 'function') {
+        try {
+          const c = await driver.connect();
+          // Pool.connect() → 专用 Client（带 release）；Client.connect() → 自身
+          if (c && typeof c.query === 'function') {
+            conn = c;
+            if (c !== driver && typeof c.release === 'function') release = () => c.release();
+          }
+        } catch (_) {
+          /* checkout 失败退回 driver 本体，事务语义由 BEGIN/COMMIT 保证 */
+        }
+      }
+      try {
+        await conn.query('BEGIN');
+        const out = await body((plan) => runStmts(conn, plan));
+        await conn.query('COMMIT');
+        return out;
+      } catch (e) {
+        try {
+          await conn.query('ROLLBACK');
+        } catch (_) {
+          /* rollback 失败不掩盖原始错误 */
+        }
+        throw e;
+      } finally {
+        if (release) release();
       }
-      return { docs, rows, affectedRows };
     },
   };
 }

package/src/executors/sqlite.js

@@ -25,23 +25,43 @@ function create(db, _options = {}) {
   if (!db || typeof db.prepare !== 'function') {
     throw new TypeError('sqlite 执行器需要 better-sqlite3 Database 实例');
   }
+
+  /** 依序执行 plan.stmts（better-sqlite3 同步单连接） */
+  function runStmts(plan) {
+    let docs = null;
+    let rows = null;
+    let affectedRows = 0;
+    for (const stmt of plan.stmts) {
+      const params = _bind(stmt.params);
+      // 带 RETURNING 的写语句同样返回行 → 必须用 all() 取回；其余写语句用 run() 取影响行数
+      if (!stmt.isWrite || stmt.rowShape) {
+        rows = db.prepare(stmt.text).all(...params);
+        if (stmt.rowShape) docs = _core.restoreRows(stmt.rowShape, rows);
+      } else {
+        affectedRows = Number(db.prepare(stmt.text).run(...params).changes || 0);
+      }
+    }
+    return { docs, rows, affectedRows };
+  }
+
   return {
     kind: 'sqlite',
-    exec(plan) {
-      let docs = null;
-      let rows = null;
-      let affectedRows = 0;
-      for (const stmt of plan.stmts) {
-        const params = _bind(stmt.params);
-        // 带 RETURNING 的写语句同样返回行 → 必须用 all() 取回；其余写语句用 run() 取影响行数
-        if (!stmt.isWrite || stmt.rowShape) {
-          rows = db.prepare(stmt.text).all(...params);
-          if (stmt.rowShape) docs = _core.restoreRows(stmt.rowShape, rows);
-        } else {
-          affectedRows = Number(db.prepare(stmt.text).run(...params).changes || 0);
+    exec: runStmts,
+    /** 事务执行：显式 BEGIN/COMMIT/ROLLBACK（better-sqlite3 默认 autocommit，显式开事务安全） */
+    async withTransaction(body) {
+      db.exec('BEGIN');
+      try {
+        const out = await body(runStmts);
+        db.exec('COMMIT');
+        return out;
+      } catch (e) {
+        try {
+          db.exec('ROLLBACK');
+        } catch (_) {
+          /* rollback 失败不掩盖原始错误 */
         }
+        throw e;
       }
-      return { docs, rows, affectedRows };
     },
   };
 }

package/src/feedback.js

@@ -0,0 +1,39 @@
+'use strict';
+
+/**
+ * 反馈事件通道 —— 兜底/降级/拦截触发的统一出口
+ *
+ * 事件形状（对齐 rust-store 联邦 degraded 契约）::
+ *
+ *   {type, code, layer, message, hint, ...}
+ *     - type  : 事件类别（federation_degraded / sql_pushdown_unsupported ...）
+ *     - code  : 机器可读代码（crossSourceSort / pushdownUnsupported ...）
+ *     - layer : 命中的防护层（federation / dialect ...）
+ *     - message: 人可读描述
+ *     - hint  : 修复指引（供上游排查/加固）
+ *
+ * 默认无 sink 时打 stderr（向后兼容）；宿主可 `setSink(fn)` 接管，
+ * 接入自动反馈闭环（允许被拦截，禁止静默失守）。
+ */
+
+let _sink = null;
+
+/** 注册反馈事件回调 `fn(event)`；传 null/非函数恢复默认 stderr 行为 */
+function setSink(fn) {
+  _sink = typeof fn === 'function' ? fn : null;
+}
+
+/** 产出一条反馈事件：有 sink 回调之；否则打印 stderr（允许拦截，禁止静默） */
+function emit(event) {
+  const e = event || {};
+  if (_sink) {
+    _sink(e);
+    return;
+  }
+  console.error(
+    `[nodejs-store][${e.layer || '?'}/${e.code || '?'}] `
+    + `${e.message || ''}（hint: ${e.hint || '-'}）`,
+  );
+}
+
+module.exports = { setSink, emit };

package/src/index.js

@@ -24,6 +24,7 @@
 const crud = require('./crud');
 const datasource = require('./datasource');
 const executors = require('./executors');
+const feedback = require('./feedback');
 const introspect = require('./introspect');
 const permission = require('./permission');
 const schema = require('./schema');
@@ -51,6 +52,7 @@ class Store {
   /**
    * GQL 查询。`routeOverride`（可选）：`{ source?, namespace? }` 多租户路由，
    * 覆盖命令定位（权限/计算列仍按结构 schema 判定）。下同。
+   * 注意：`routeOverride` 为**受信服务端参数**，禁止透传用户输入（否则可被用于跨源路由，CWE-639）。
    */
   async query(gql, params, routeOverride) {
     return crud.query(gql, params, routeOverride);
@@ -122,6 +124,25 @@ class Store {
     return schema.core.buildPipeline(gql, params ?? {}, permission.getContext() ?? null);
   }
 
+  // ── 宿主接入守卫（Registry 级，对齐 py-store c44001e） ──
+  /** 开关用户 $pipeline 直通（默认允许；AI 问数宿主建议关闭作纵深防御） */
+  setAllowUserPipeline(allow = true) {
+    return schema.setAllowUserPipeline(allow);
+  }
+
+  /**
+   * 开关「上下文强制」（默认关闭 = fail-open）。开启后：所有查询/写入在 ctx 缺失时
+   * 抛 `ERR_NO_CONTEXT`（fail-secure）；内部调用须显式传 `{ internal: true }` 上下文。
+   */
+  setRequireContext(require = true) {
+    return schema.setRequireContext(require);
+  }
+
+  /** 注册反馈事件回调（兜底/降级/拦截的统一出口）；传 null 恢复默认 stderr */
+  setFeedbackSink(fn) {
+    return feedback.setSink(fn);
+  }
+
   // ── 权限控制（AsyncLocalStorage 上下文） ──
   setContext(ctx) {
     return permission.setContext(ctx);
@@ -156,13 +177,10 @@ async function _createIndexesIfNeeded() {
   for (const name of names) {
     const s = schema.get(name);
     // 索引创建是初始化的辅助动作（非命令路由）：schema 绑定的 source 暂未在
-    // 当前连接映射中时跳过，不阻塞 init（命令路由的 fail fast 不在此处）
-    let db;
-    try {
-      db = datasource.dbOfSchema(name); // Mongo 按 (datasource, namespace) 解析；SQL 源返回 null
-    } catch (e) {
-      continue;
-    }
+    // 当前连接映射中时软跳过，不阻塞 init；其余配置错误（namespace 形态不匹配等）
+    // 按 fail-fast 由 dbOfSchema 上抛，不静默吞掉
+    if (!datasource.hasConnection(datasource.sourceOfSchema(name))) continue;
+    const db = datasource.dbOfSchema(name); // Mongo 按 (datasource, namespace) 解析；SQL 源返回 null
     if (!db) continue; // SQL 后端不建索引
 
     const coll = db.collection(s.collection);
@@ -171,7 +189,10 @@ async function _createIndexesIfNeeded() {
     try {
       existingIndexes = await coll.listIndexes().toArray();
     } catch (e) {
-      existingIndexes = [];
+      // 只吞服务器错误（集合尚未存在 → NamespaceNotFound 属 MongoServerError）；
+      // 连接/程序错误按 fail-fast 上抛，不再静默吞掉（对齐 py 侧 PyMongoError 收窄）
+      if (e && e.name === 'MongoServerError') existingIndexes = [];
+      else throw e;
     }
 
     for (const idx of s.indexes || []) {
@@ -226,11 +247,13 @@ module.exports = {
   Store,
   aggregate: crud.aggregate,
   PermissionError: permission.PermissionError,
+  PushdownUnsupportedError: datasource.PushdownUnsupportedError,
   datasource,
   schema,
   permission,
   crud,
   executors,
+  feedback,
   introspect,
   syncSchema,
 };

package/src/schema.js

@@ -52,6 +52,8 @@ function register(defn) {
     namespace: defn.namespace || null,
     idPrefix: defn.idPrefix || '',
     timestamps: defn.timestamps !== false,
+    // 时间戳单位（'ms'/'s'/null=不维护）；值合法性由 core.register 校验
+    timestampUnit: defn.timestamps === 's' ? 's' : (defn.timestamps === false ? null : 'ms'),
     fields: defn.fields || {},
     relations: defn.relations || {},
     computes,
@@ -98,9 +100,24 @@ function list() {
   return core.list();
 }
 
+/** 开关用户 $pipeline 直通（默认允许；AI 问数宿主建议关闭作纵深防御） */
+function setAllowUserPipeline(allow = true) {
+  core.setAllowUserPipeline(Boolean(allow));
+}
+
+/**
+ * 开关「上下文强制」（默认关闭 = fail-open，与 JS 原版语义一致）。
+ *
+ * 开启后：所有 plan 入口遇 ctx 缺失抛 `ERR_NO_CONTEXT` 错误（fail-secure）；
+ * 内部调用（索引创建、归档回填、后台任务等）须显式传 `{ internal: true }` 上下文。
+ */
+function setRequireContext(require = true) {
+  core.setRequireContext(Boolean(require));
+}
+
 /** 取 asyncFn 计算列实现（fnRef 缺省 = 计算列 key 名） */
 function getAsyncFn(fnRef) {
   return _asyncFns[fnRef];
 }
 
-module.exports = { core, register, get, has, list, getAsyncFn };
+module.exports = { core, register, get, has, list, setAllowUserPipeline, setRequireContext, getAsyncFn };