nodejs-store 1.1.0 → 2.0.0

package/README.md

@@ -10,7 +10,7 @@ This is the Node.js port of [`py-store`](https://github.com/coenddt/py-store)
 | --- | --- |
 | MongoDB | native aggregation pipeline (`find`/`aggregate`/`$lookup`) |
 | MySQL | parameterized SQL, `information_schema` introspection |
-| SQLite | parameterized SQL, `sqlite_master` + `PRAGMA` introspection |
+| SQLite | parameterized SQL, `sqlite_master` + `PRAGMA` introspection. **Sync driver** (`better-sqlite3`): calls block the event loop by design — for high-concurrency hot paths prefer MySQL/PostgreSQL/MongoDB, or isolate SQLite in a dedicated process |
 | PostgreSQL | parameterized SQL (`$n`), `RETURNING` support |
 
 GQL tree queries compile to a single native query per backend — never hand-write `$lookup` or raw SQL again.
@@ -123,7 +123,11 @@ Model($condition:@c0,$sort:@s1,$skip:@sk,$limit:@l1) {
 
 - Values come from the params object: `{ c0: {...}, s1: {...} }`.
 - Object sub-fields use dot notation; relations are declared in the schema (`type: 'many' | 'one'`) and resolved automatically — **do not hand-write `$lookup`**.
-- `$pipeline` passes a raw aggregation through as-is (no compute/defaults/permission trimming) — use with care; prefer `store.aggregate(model, pipeline)` for group/sum needs.
+
+> **Breaking change**: user `$pipeline` passthrough and `store.aggregate()` were removed
+> (raw aggregation escape hatch). A GQL containing `$pipeline` now fails explicitly instead
+> of being silently ignored. Use `$condition`/`$sort`/`$skip`/`$limit` + relations; normalized
+> aggregation (`$group`/`$sum`) is being redesigned and will return under a single GQL syntax.
 
 ## Query & write API
 
@@ -142,7 +146,6 @@ await store.updateMany('Post', { type: t }, { status: 'live' });
 const r      = await store.remove('Post', { _id: pid });  // archives to <collection>_deleted first
 await store.mutation('Post', { ... });                    // smart upsert + recursive relation children
 await store.upsert('Post', { code: 'A1' }, { ... });      // explicit-condition upsert (no relation handling)
-const rows   = await store.aggregate('Post', pipeline);   // native aggregation
 ```
 
 Notes:
@@ -203,7 +206,7 @@ a missing context and always passes. `setRequireContext(false)` restores the def
   },
   computes: {
     total: { type: 'float', depends: ['amount'], fn: (d) => d.amount * 1.1 },
-    itemCount: { type: 'int', lookup: { $size: { $ifNull: ['$items', []] } } },
+    itemCount: { type: 'int', agg: { $count: 'items' } },
   },
   indexes: [
     { keys: { status: 1 } },
@@ -256,13 +259,6 @@ const defs = await store.syncSchema({
 });
 ```
 
-### `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
@@ -284,7 +280,6 @@ 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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nodejs-store",
-  "version": "1.1.0",
+  "version": "2.0.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": [
@@ -43,7 +43,7 @@
     "mongodb": "^6.21.0",
     "mysql2": "^3.24.4",
     "pg": "^8.23.0",
-    "rust-store-node": "^1.0.0"
+    "rust-store-node": "^2.0.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",

package/src/crud/exec.js

@@ -14,6 +14,7 @@
 
 const { PermissionError, getContext } = require('../permission');
 const datasource = require('../datasource');
+const { execMongo } = require('../executors/mongo');
 const { get: _getSchema } = require('../schema');
 
 const _PHASE1_IDS = /^\{\{phase1\.ids\}\}$/;
@@ -29,6 +30,11 @@ const _PERM_PREFIX = 'ERR_PERMISSION:';
 /** 设置数据源连接映射（对 `../datasource` 的路由入口做包内透出） */
 const setConnections = datasource.setConnections;
 
+/** 单库简写：等价于 `setConnections({ default: db })`（对齐 py_store.crud.exec.set_db） */
+function setDb(db) {
+  datasource.setConnections({ [datasource.DEFAULT_SOURCE]: db });
+}
+
 /** 按 schema 的 timestamps 单位产出当前时间戳（'s' → 秒，其余/未启用 → 毫秒） */
 function _nowFor(schemaName) {
   const unit = _getSchema(schemaName).timestampUnit;
@@ -54,54 +60,13 @@ function _call(fn) {
 
 // ─── 命令执行（唯一 IO 边界） ────────────────────────────────
 
-/** Command JSON → MongoDB 原生驱动调用 */
-async function _execMongo(db, cmd) {
-  const coll = db.collection(cmd.collection);
-  switch (cmd.kind) {
-    case 'find': {
-      const opts = cmd.projection ? { projection: cmd.projection } : undefined;
-      return coll.find(cmd.filter, opts).toArray();
-    }
-    case 'aggregate':
-      return coll.aggregate(cmd.pipeline).toArray();
-    case 'countDocuments':
-      return coll.countDocuments(cmd.filter);
-    case 'findOne': {
-      const opts = cmd.projection ? { projection: cmd.projection } : undefined;
-      return coll.findOne(cmd.filter, opts);
-    }
-    case 'insertOne':
-      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':
-      return coll.findOneAndUpdate(cmd.filter, cmd.update, cmd.options);
-    case 'updateMany':
-      return coll.updateMany(cmd.filter, cmd.update);
-    case 'deleteMany':
-      return coll.deleteMany(cmd.filter);
-    default:
-      throw new Error(`未支持的命令: ${cmd.kind}`);
-  }
-}
-
 /** 在指定数据源上执行命令（Mongo 走原生驱动，SQL 走 translate → exec；
  * 事务作用域内经 datasource.connectionFor 落到事务专用连接） */
 async function _execOn(source, cmd) {
   const connection = datasource.connectionFor(source);
   const db = datasource.mongoDb(connection, source, cmd.namespace ?? null);
   if (db) {
-    return _execMongo(db, cmd);
+    return execMongo(db, cmd);
   }
   return datasource.execSql(source, connection, cmd);
 }
@@ -147,6 +112,7 @@ function resolvePlaceholders(command, { ids = null, steps = [] } = {}) {
 
 module.exports = {
   setConnections,
+  setDb,
   _nowFor,
   _ctx,
   _call,

package/src/crud/index.js

@@ -16,17 +16,18 @@
  *   - [`id`]：ID 生成与 mutation ID 池遍历
  *   - [`query`]：读路径
  *   - [`write`]：写路径
- *   - [`mutation`]：mutation / upsert / 原生聚合
+ *   - [`mutation`]：mutation / upsert
  */
 
-const { setConnections, _nowFor, _ctx, _call, _exec, _substitute, resolvePlaceholders } = require('./exec');
+const { setConnections, setDb, _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');
-const { mutation, upsert, aggregate } = require('./mutation');
+const { mutation, upsert } = require('./mutation');
 
 module.exports = {
   setConnections,
+  setDb,
   query,
   queryOne,
   queryWithCount,
@@ -40,7 +41,6 @@ module.exports = {
   count,
   mutation,
   upsert,
-  aggregate,
   // ── Host 契约件（供跨语言同构契约测试与高级用法；下划线表示内部语义） ──
   _substitute,
   resolvePlaceholders,

package/src/crud/mutation.js

@@ -6,15 +6,21 @@
 
 const { core: _core, get: _getSchema } = require('../schema');
 const datasource = require('../datasource');
+const { emit: _emitFeedback } = require('../feedback');
 const { _call, _ctx, _exec, _nowFor, resolvePlaceholders } = require('./exec');
 const { _generateId, _newIdPool } = require('./id');
 
 /** mutation 单条：规划步骤序列 → 依序执行 + 父子 _id 占位符回填 */
-async function _mutationOne(schemaName, data, routeOverride = null) {
+async function _mutationOne(schemaName, data, now, routeOverride = null) {
   const plan = _call(() =>
-    _core.planMutation(schemaName, data, _nowFor(schemaName), _newIdPool(schemaName, data), _ctx(),
+    _core.planMutation(schemaName, data, now, _newIdPool(schemaName, data), _ctx(),
       routeOverride));
 
+  // §11.4 静默点收口：规划期降级（如关系不可读被跳过）走统一反馈通道，禁止静默失守
+  for (const d of plan.degraded || []) {
+    _emitFeedback({ ...(d || {}), type: 'mutation_degraded' });
+  }
+
   const runSteps = async () => {
     const resolved = [];
     let rootResult = null;
@@ -49,9 +55,13 @@ async function mutation(schemaName, data, routeOverride = null) {
 
   if (!items.length) return isArray ? [] : null;
 
+  // §11.3 确定性输入：一次 mutation 调用共用一个 now
+  // （数组内多条 + 父子步骤 + 默认值 / 计算列全部同值）
+  const now = _nowFor(schemaName);
+
   const results = [];
   for (const item of items) {
-    results.push(await _mutationOne(schemaName, item, routeOverride));
+    results.push(await _mutationOne(schemaName, item, now, routeOverride));
   }
 
   return isArray ? results : results[0];
@@ -72,12 +82,4 @@ async function upsert(schemaName, condition, data, options = null, routeOverride
   return result ? _call(() => _core.applyWriteDefaults(schemaName, result)) : null;
 }
 
-// ─── 原生聚合 ────────────────────────────────────────────────
-
-/** 对指定 schema 执行 MongoDB 原生聚合查询 */
-async function aggregate(schemaName, pipeline, routeOverride = null) {
-  const cmd = _call(() => _core.planAggregate(schemaName, pipeline ?? [], routeOverride));
-  return _exec(cmd);
-}
-
-module.exports = { mutation, upsert, aggregate };
+module.exports = { mutation, upsert };

package/src/crud/query.js

@@ -38,8 +38,7 @@ async function _finalize(plan, items) {
  * GQL 查询（返回数组）
  *
  * 支持的 params 键（通过 GQL 的 @key 引用）:
- *   $condition / $sort / $skip / $limit / $pipeline
- * 使用 $pipeline 时，框架不追加 compute 层、不补默认值、不裁剪，完全由用户控制。
+ *   $condition / $sort / $skip / $limit
  *
  * `routeOverride`（多租户路由，可选）：`{ source?, namespace? }`，覆盖命令定位，
  * 权限/计算列仍按结构 schema 判定（见 multi-datasource-routing-plan.md §6）。

package/src/crud/write.js

@@ -109,7 +109,7 @@ async function exists(schemaName, condition, routeOverride = null) {
 
 /** 统计符合条件的文档数量 */
 async function count(schemaName, filter = null, routeOverride = null) {
-  const cmd = _call(() => _core.planCount(schemaName, filter ?? null, routeOverride));
+  const cmd = _call(() => _core.planCount(schemaName, filter ?? null, _ctx(), routeOverride));
   return _exec(cmd);
 }
 

package/src/datasource.js

@@ -210,14 +210,11 @@ function route(cmd) {
  * 使上层（crud/*）对 Mongo / SQL 两条路径无感。
  */
 async function execSql(source, connection, cmd) {
-  if (typeof connection.exec !== 'function') {
-    throw new Error(
-      `SQL 数据源 ${source}(${connection.kind}) 的执行器未接入（见执行文档 Phase 4）`,
-    );
-  }
   const plan = _core.dialectTranslate(connection.kind, cmd);
   // Host 兜底：core 标记了无法安全下推的组合（如 $lookup 子 $limit 每父 top-N）时，
   // 绝不执行「缺少该段」的 SQL（会静默返回错误结果），改为显式报错，由调用方降级重查。
+  // 先于执行器检查 —— 命令本身不可安全下推时，报下推不支持而非「执行器未接入」
+  // （对齐 py_store/datasource.py#exec_sql 的检查次序）。
   if (Array.isArray(plan.unsupported) && plan.unsupported.length > 0) {
     const err = new PushdownUnsupportedError(
       source,
@@ -229,6 +226,11 @@ async function execSql(source, connection, cmd) {
     _emitFeedback(err.feedback());
     throw err;
   }
+  if (typeof connection.exec !== 'function') {
+    throw new Error(
+      `SQL 数据源 ${source}(${connection.kind}) 的执行器未接入（见执行文档 Phase 4）`,
+    );
+  }
   const out = await connection.exec(plan);
   return executors.shapeResult(cmd, out);
 }

package/src/executors/_values.js

@@ -0,0 +1,55 @@
+'use strict';
+
+/**
+ * 驱动原始值归一（SQL 执行器共用）
+ *
+ * `pg` / `mysql2` 对**精确数值列**默认返回**字符串**：
+ * - `pg`：`int8`(20) / `numeric`(1700) → string；
+ * - `mysql2`：`DECIMAL` / `NEWDECIMAL`(246) → string。
+ *
+ * 而 Mongo 驱动对这些值返回 `number`。未归一 → 同一查询在 SQL 后端返回 `"8"`、Mongo 返回
+ * `8`（**静默类型失真**，`JSON.stringify` 对拍与用户代码都能看到差异）。
+ *
+ * 归一**只依据驱动给出的列类型元数据**（`pg` 的 `res.fields[].dataTypeID`、`mysql2` 的
+ * `fields[].columnType`），因此**不会**误伤真正的字符串列（如 `_id` / `status`）。
+ *
+ * 与 py-store 的 `py_store/executors/_values.py`（`Decimal` → 数值）同源同责。
+ */
+
+/** pg 的数值类型 OID（int2/int4/int8/float4/float8/numeric） */
+const PG_NUMERIC_OIDS = new Set([20, 21, 23, 700, 701, 1700]);
+
+/** mysql2 的数值 columnType（DECIMAL/TINY/SHORT/LONG/FLOAT/DOUBLE/LONGLONG/INT24/NEWDECIMAL） */
+const MYSQL_NUMERIC_TYPES = new Set([0, 1, 2, 3, 4, 5, 8, 9, 246]);
+
+/** 字符串数值 → number；非有限数值（如超长整数溢出为 Infinity）保持原样，不静默改值 */
+function toNumber(v) {
+  if (typeof v !== 'string' || v === '') return v;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : v;
+}
+
+/**
+ * 行集归一：按列类型元数据把**数值列**的字符串值转 `number`。
+ *
+ * @param {object[]} rows   驱动返回的行
+ * @param {object[]|undefined} fields 列元数据（`dataTypeID` for pg / `columnType` for mysql2）
+ * @param {'postgres'|'mysql'} kind 驱动种类
+ */
+function normalizeRows(rows, fields, kind) {
+  if (!rows || !rows.length || !fields || !fields.length) return rows;
+  const numeric = [];
+  for (let i = 0; i < fields.length; i += 1) {
+    const t = kind === 'postgres' ? fields[i].dataTypeID : fields[i].columnType;
+    const hit = kind === 'postgres' ? PG_NUMERIC_OIDS.has(t) : MYSQL_NUMERIC_TYPES.has(t);
+    if (hit) numeric.push(fields[i].name);
+  }
+  if (!numeric.length) return rows;
+  return rows.map((row) => {
+    const out = { ...row };
+    for (const k of numeric) out[k] = toNumber(out[k]);
+    return out;
+  });
+}
+
+module.exports = { MYSQL_NUMERIC_TYPES, PG_NUMERIC_OIDS, normalizeRows, toNumber };

package/src/executors/index.js

@@ -12,12 +12,17 @@
  * （`crud/query|write|mutation`）透明：上层只看到同一套返回值语义。
  */
 
+const mongo = require('./mongo');
 const mysql = require('./mysql');
 const postgres = require('./postgres');
 const sqlite = require('./sqlite');
 
 const _BACKENDS = { mysql, postgres, sqlite };
 
+// 注意：sqlite 执行器基于 better-sqlite3 同步驱动，调用期间会阻塞事件循环
+// （设计选择，非缺陷）——高并发主链路请用 mysql/postgres/mongo，或为 SQLite
+// 单独起独立进程；详见 ./sqlite.js 模块头「同步阻塞说明」。
+
 /** 创建 SQL 数据源连接描述符 `{ kind, exec }`（driver 为对应驱动实例/连接） */
 function createConnection(kind, driver, options) {
   const mod = _BACKENDS[kind];
@@ -57,4 +62,4 @@ function shapeResult(cmd, out) {
   }
 }
 
-module.exports = { createConnection, shapeResult, mysql, postgres, sqlite };
+module.exports = { createConnection, shapeResult, mongo, mysql, postgres, sqlite };

package/src/executors/mongo.js

@@ -0,0 +1,102 @@
+'use strict';
+
+/**
+ * Mongo 执行器（驱动：mongodb 原生）
+ *
+ * 只做「Command JSON → 原生驱动调用」（铁律 1/3）：全部纯逻辑（GQL 解析、权限、
+ * 命令规划、结果后处理）都在 Rust core。对齐 ``py-store/src/py_store/executors/mongo.py``。
+ *
+ * 唯一原生边界改写：`_explicitNull` —— 把「字段 = null」的**等值条件**编译为
+ * 「字段存在且为 null」（`{$eq: null, $exists: true}`）。理由：Mongo 原生把 `{f: null}`
+ * 同时命中「值为 null」与「字段缺失」两类文档，而本 store 的三态契约（F-07/H-09）
+ * 要求 `null` 只命中显式 null、`$exists:false` 才命中缺失 —— 这与 SQL 侧
+ * `col IS NULL`（显式 null）语义对齐。运算对象（`$ne:null`/`$exists`/`$gt`…）不改写。
+ */
+
+/** 递归改写 filter：`field: null`（标量等值）→ `field: {$eq: null, $exists: true}`。 */
+function _explicitNull(v) {
+  if (Array.isArray(v)) return v.map(_explicitNull);
+  if (v && typeof v === 'object') {
+    const out = {};
+    for (const [k, val] of Object.entries(v)) {
+      if (k.startsWith('$') && (val !== null && typeof val === 'object')) {
+        out[k] = _explicitNull(val);
+      } else if (k.startsWith('$')) {
+        out[k] = val;
+      } else if (val !== null && typeof val === 'object') {
+        out[k] = _explicitNull(val);
+      } else if (val === null) {
+        out[k] = { $eq: null, $exists: true };
+      } else {
+        out[k] = val;
+      }
+    }
+    return out;
+  }
+  return v;
+}
+
+function _normFilter(cmd) {
+  if (cmd.filter && typeof cmd.filter === 'object' && !Array.isArray(cmd.filter)) {
+    cmd.filter = _explicitNull(cmd.filter);
+  }
+}
+
+function _normPipeline(cmd) {
+  if (!Array.isArray(cmd.pipeline)) return;
+  for (const stage of cmd.pipeline) {
+    if (stage && typeof stage === 'object' && stage.$match && typeof stage.$match === 'object') {
+      stage.$match = _explicitNull(stage.$match);
+    }
+  }
+}
+
+/** Command JSON → MongoDB 原生驱动调用 */
+async function execMongo(db, cmd) {
+  const coll = db.collection(cmd.collection);
+  switch (cmd.kind) {
+    case 'find': {
+      _normFilter(cmd);
+      const opts = cmd.projection ? { projection: cmd.projection } : undefined;
+      return coll.find(cmd.filter, opts).toArray();
+    }
+    case 'aggregate':
+      _normPipeline(cmd);
+      return coll.aggregate(cmd.pipeline).toArray();
+    case 'countDocuments':
+      _normFilter(cmd);
+      return coll.countDocuments(cmd.filter);
+    case 'findOne': {
+      _normFilter(cmd);
+      const opts = cmd.projection ? { projection: cmd.projection } : undefined;
+      return coll.findOne(cmd.filter, opts);
+    }
+    case 'insertOne':
+      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':
+      _normFilter(cmd);
+      return coll.findOneAndUpdate(cmd.filter, cmd.update, cmd.options);
+    case 'updateMany':
+      _normFilter(cmd);
+      return coll.updateMany(cmd.filter, cmd.update);
+    case 'deleteMany':
+      _normFilter(cmd);
+      return coll.deleteMany(cmd.filter);
+    default:
+      throw new Error(`未支持的命令: ${cmd.kind}`);
+  }
+}
+
+module.exports = { execMongo };

package/src/executors/mysql.js

@@ -10,6 +10,7 @@
  */
 
 const { core: _core } = require('../schema');
+const { normalizeRows } = require('./_values');
 
 /** mysql2 返回 RowDataPacket 实例，转普通对象后再交 core（绑定层只认纯 JSON） */
 function _plain(row) {
@@ -30,9 +31,9 @@ function create(driver, _options = {}) {
     let rows = null;
     let affectedRows = 0;
     for (const stmt of plan.stmts) {
-      const [raw] = await conn.execute(stmt.text, stmt.params || []);
+      const [raw, fields] = await conn.execute(stmt.text, stmt.params || []);
       if (Array.isArray(raw)) {
-        rows = raw.map(_plain);
+        rows = normalizeRows(raw.map(_plain), fields, 'mysql');
         if (stmt.rowShape) docs = _core.restoreRows(stmt.rowShape, rows);
       } else {
         affectedRows = Number(raw.affectedRows || 0);

package/src/executors/postgres.js

@@ -10,6 +10,7 @@
  */
 
 const { core: _core } = require('../schema');
+const { normalizeRows } = require('./_values');
 
 /** 创建执行器描述符（可直接作为 `init(connections)` 的一个 SQL 数据源连接） */
 function create(driver, _options = {}) {
@@ -24,7 +25,7 @@ function create(driver, _options = {}) {
     let affectedRows = 0;
     for (const stmt of plan.stmts) {
       const res = await conn.query(stmt.text, stmt.params || []);
-      rows = res.rows || [];
+      rows = normalizeRows(res.rows || [], res.fields, 'postgres');
       affectedRows = Number(res.rowCount || 0);
       if (stmt.rowShape) docs = _core.restoreRows(stmt.rowShape, rows);
     }

package/src/executors/sqlite.js

@@ -7,6 +7,11 @@
  * 产出，本模块不拼任何 SQL；带 `rowShape` 的语句结果交 core `restoreRows` 还原为
  * 嵌套文档。返回值是中立包络 `{ docs, rows, affectedRows }`，由 `./index.js`
  * 依 command.kind 塑形为 Mongo 驱动等价返回值。
+ *
+ * ⚠️ 同步阻塞说明：better-sqlite3 是**同步驱动**，`prepare/all/run` 在 async 契约内
+ * 仍会**阻塞事件循环**（本模块保持同步调用是有意为之的设计选择：单连接语义最简、
+ * 无跨线程开销）。高并发主链路请改用 MySQL / PostgreSQL / MongoDB 数据源，
+ * 或为 SQLite 单独起独立进程隔离阻塞面——本执行器不适合多请求共享的事件循环热路径。
  */
 
 const { core: _core } = require('../schema');
@@ -26,7 +31,7 @@ function create(db, _options = {}) {
     throw new TypeError('sqlite 执行器需要 better-sqlite3 Database 实例');
   }
 
-  /** 依序执行 plan.stmts（better-sqlite3 同步单连接） */
+  /** 依序执行 plan.stmts（better-sqlite3 同步单连接；同步调用会阻塞事件循环，见模块头说明） */
   function runStmts(plan) {
     let docs = null;
     let rows = null;

package/src/index.js

@@ -108,11 +108,6 @@ class Store {
     return crud.upsert(schemaName, condition, data, options, routeOverride);
   }
 
-  // ── 原生聚合 ──
-  async aggregate(schemaName, pl, routeOverride) {
-    return crud.aggregate(schemaName, pl, routeOverride);
-  }
-
   // ── 结构同步（SQL 数据源：introspect → schemaFromRows → mergeSchema → register） ──
   async syncSchema(opts) {
     return syncSchema(opts);
@@ -125,17 +120,22 @@ class Store {
   }
 
   // ── 宿主接入守卫（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);
+  setRequireContext(needCtx = true) {
+    return schema.setRequireContext(needCtx);
+  }
+
+  /** 「上下文强制」开关当前值（对齐 py-store store.require_context） */
+  requireContext() {
+    return schema.requireContext();
+  }
+
+  /** 设置数据源连接映射（多后端路由；对齐 py-store store.set_connections） */
+  setConnections(connections) {
+    return datasource.setConnections(connections);
   }
 
   /** 注册反馈事件回调（兜底/降级/拦截的统一出口）；传 null 恢复默认 stderr */
@@ -214,7 +214,15 @@ async function _createIndexesIfNeeded() {
 
         await coll.createIndex(Object.entries(keys), finalOptions);
       } catch (e) {
-        console.error(`[MongoStore] 创建索引失败 ${s.collection}: ${e && e.message ? e.message : e}`);
+        // 索引创建失败不阻塞 init（辅助动作），但必须走统一反馈通道：
+        // 无 sink 时由 feedback 默认落 stderr（不双份打印），宿主可 setFeedbackSink 接管
+        feedback.emit({
+          type: 'index_create_failed',
+          code: 'indexCreateFailed',
+          layer: 'host',
+          message: `创建索引失败 ${s.collection}: ${e && e.message ? e.message : e}`,
+          hint: '检查该集合的索引定义与连接权限；索引缺失不影响读写，相关查询将退化为全表扫描',
+        });
       }
     }
   }
@@ -245,7 +253,6 @@ module.exports = {
   init,
   store,
   Store,
-  aggregate: crud.aggregate,
   PermissionError: permission.PermissionError,
   PushdownUnsupportedError: datasource.PushdownUnsupportedError,
   datasource,

package/src/introspect/_shared.js

@@ -0,0 +1,28 @@
+'use strict';
+
+/**
+ * introspect 共享工具（mysql / postgres 复用，避免复制粘贴式重复）
+ *
+ * 两后端 `_INDEXES` 查询产出的行形态不同（MySQL `nonUnique` 取反、PG `unique` 直取），
+ * 由调用方以 `uniqueOf(row)` 参数化该差异；归并逻辑本身逐行一致，抽为单份实现。
+ */
+
+/**
+ * 把 `{table,name,column,...}` 索引行按 `(table, name)` 归并出
+ * `{table, name, columns, unique}` 数组（`unique` 取 `uniqueOf(row)` 的 0/1）
+ */
+function groupIndexes(rows, uniqueOf) {
+  const byKey = new Map();
+  for (const r of rows) {
+    const key = `${r.table}::${r.name}`;
+    let entry = byKey.get(key);
+    if (!entry) {
+      entry = { table: r.table, name: r.name, columns: [], unique: uniqueOf(r) };
+      byKey.set(key, entry);
+    }
+    entry.columns.push(r.column);
+  }
+  return [...byKey.values()];
+}
+
+module.exports = { groupIndexes };

package/src/introspect/mysql.js

@@ -7,6 +7,8 @@
  * 交 core `schemaFromRows` 做纯映射。建议使用只读账号；库名取当前连接的 `DATABASE()`。
  */
 
+const { groupIndexes } = require('./_shared');
+
 const _TABLES = `
   SELECT table_name AS name
   FROM information_schema.tables
@@ -42,20 +44,8 @@ const _INDEXES = `
   WHERE table_schema = DATABASE()
   ORDER BY table_name, index_name, seq_in_index`;
 
-/** 把 `{table,name,nonUnique,column}` 行按索引名归并出 columns 数组 */
-function _groupIndexes(rows) {
-  const byKey = new Map();
-  for (const r of rows) {
-    const key = `${r.table}::${r.name}`;
-    let entry = byKey.get(key);
-    if (!entry) {
-      entry = { table: r.table, name: r.name, columns: [], unique: Number(r.nonUnique) ? 0 : 1 };
-      byKey.set(key, entry);
-    }
-    entry.columns.push(r.column);
-  }
-  return [...byKey.values()];
-}
+// MySQL 行携带 nonUnique（1=非唯一）→ 取反为 unique 标志；归并逻辑共享见 _shared.js
+const _uniqueOf = (r) => (Number(r.nonUnique) ? 0 : 1);
 
 async function introspect(driver, { database = null } = {}) {
   if (!driver || typeof driver.execute !== 'function') {
@@ -91,7 +81,7 @@ async function introspect(driver, { database = null } = {}) {
       pk: c.columnKey === 'PRI' ? 1 : 0,
     })),
     fks,
-    indexes: _groupIndexes(indexRows),
+    indexes: groupIndexes(indexRows, _uniqueOf),
   };
 }
 

package/src/introspect/postgres.js

@@ -7,6 +7,8 @@
  * 产出规范化行 JSON，交 core `schemaFromRows` 做纯映射。建议使用只读账号。
  */
 
+const { groupIndexes } = require('./_shared');
+
 const _TABLES = `
   SELECT table_name AS name
   FROM information_schema.tables
@@ -63,20 +65,8 @@ const _INDEXES = `
   WHERE ns.nspname = $1 AND NOT ix.indisprimary
   ORDER BY t.relname, i.relname`;
 
-/** 把 `{table,name,unique,column}` 行按索引名归并出 columns 数组 */
-function _groupIndexes(rows) {
-  const byKey = new Map();
-  for (const r of rows) {
-    const key = `${r.table}::${r.name}`;
-    let entry = byKey.get(key);
-    if (!entry) {
-      entry = { table: r.table, name: r.name, columns: [], unique: Number(r.unique) };
-      byKey.set(key, entry);
-    }
-    entry.columns.push(r.column);
-  }
-  return [...byKey.values()];
-}
+// PG 行已带 unique（0/1）→ 直取；归并逻辑共享见 _shared.js
+const _uniqueOf = (r) => Number(r.unique);
 
 async function introspect(driver, opts = {}) {
   if (!driver || typeof driver.query !== 'function') {
@@ -106,7 +96,7 @@ async function introspect(driver, opts = {}) {
       pk: Number(c.pk) || 0,
     })),
     fks: fks.rows,
-    indexes: _groupIndexes(indexRows.rows),
+    indexes: groupIndexes(indexRows.rows, _uniqueOf),
   };
 }
 

package/src/permission.js

@@ -11,6 +11,8 @@
 
 const { AsyncLocalStorage } = require('node:async_hooks');
 
+const { core } = require('./schema');
+
 const _als = new AsyncLocalStorage();
 
 /** 设置当前请求的上下文，每次请求开始时调用一次 */
@@ -41,6 +43,47 @@ async function runAsInternal(fn) {
   return _als.run(next, () => fn());
 }
 
+// ─── core 权限方法包装（对齐 py_store.permission 的同名薄包装） ──────
+
+/** 接受 schema 对象或 schema 名称 */
+function _model(schema) {
+  return typeof schema === 'string' ? schema : schema.name;
+}
+
+function canReadSchema(schema, ctx) {
+  return core.canRead(_model(schema), ctx ?? null);
+}
+
+function canWriteSchema(schema, ctx) {
+  return core.canWrite(_model(schema), ctx ?? null);
+}
+
+function shouldInjectOwnerCondition(schema, ctx) {
+  return core.shouldInjectOwner(_model(schema), ctx ?? null);
+}
+
+function mergeOwnerCondition(schema, ctx, condition) {
+  const out = core.mergeOwnerCondition(_model(schema), ctx ?? null, condition ?? null);
+  // core 在「不注入」时返回 null（无法区分原条件为 null）→ 原样返回入参条件
+  return out === null || out === undefined ? condition : out;
+}
+
+function getReadableFields(schema, ctx) {
+  return core.readableFields(_model(schema), ctx ?? null);
+}
+
+function getReadableRelations(schema, ctx) {
+  return core.readableRelations(_model(schema), ctx ?? null);
+}
+
+function getWritableFields(schema, ctx) {
+  return core.writableFields(_model(schema), ctx ?? null);
+}
+
+function filterWritableData(schema, ctx, data) {
+  return core.filterWritableData(_model(schema), ctx ?? null, data);
+}
+
 // ─── 自定义错误 ──────────────────────────────────────────────
 
 class PermissionError extends Error {
@@ -56,5 +99,13 @@ module.exports = {
   getContext,
   scopedRoles,
   runAsInternal,
+  canReadSchema,
+  canWriteSchema,
+  shouldInjectOwnerCondition,
+  mergeOwnerCondition,
+  getReadableFields,
+  getReadableRelations,
+  getWritableFields,
+  filterWritableData,
   PermissionError,
 };

package/src/schema.js

@@ -100,19 +100,19 @@ 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));
+function setRequireContext(needCtx = true) {
+  core.setRequireContext(Boolean(needCtx));
+}
+
+/** 「上下文强制」开关当前值（对齐 py_store.schema.require_context） */
+function requireContext() {
+  return core.requireContext();
 }
 
 /** 取 asyncFn 计算列实现（fnRef 缺省 = 计算列 key 名） */
@@ -120,4 +120,4 @@ function getAsyncFn(fnRef) {
   return _asyncFns[fnRef];
 }
 
-module.exports = { core, register, get, has, list, setAllowUserPipeline, setRequireContext, getAsyncFn };
+module.exports = { core, register, get, has, list, setRequireContext, requireContext, getAsyncFn };