nodejs-store 1.0.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.
@@ -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`.
 
@@ -119,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
 
@@ -138,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:
@@ -165,6 +172,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
@@ -183,7 +206,7 @@ await store.runAsInternal(() => store.remove('Post', { _id: pid }));
   },
   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 } },
@@ -196,6 +219,94 @@ 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.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,
+  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": "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": [
@@ -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",
@@ -41,6 +43,12 @@
     "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",
+    "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,76 +14,59 @@
 
 const { PermissionError, getContext } = require('../permission');
 const datasource = require('../datasource');
+const { execMongo } = require('../executors/mongo');
+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();
+/** 单库简写：等价于 `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;
+  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;
   }
 }
 
 // ─── 命令执行（唯一 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':
-      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） */
+/** 在指定数据源上执行命令（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);
+    return execMongo(db, cmd);
   }
   return datasource.execSql(source, connection, cmd);
 }
@@ -129,7 +112,8 @@ function resolvePlaceholders(command, { ids = null, steps = [] } = {}) {
 
 module.exports = {
   setConnections,
-  _now,
+  setDb,
+  _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

@@ -16,17 +16,18 @@
  *   - [`id`]：ID 生成与 mutation ID 池遍历
  *   - [`query`]：读路径
  *   - [`write`]：写路径
- *   - [`mutation`]：mutation / upsert / 原生聚合
+ *   - [`mutation`]：mutation / upsert
  */
 
-const { setConnections, _now, _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,
@@ -48,7 +48,7 @@ module.exports = {
   _truthy,
   _newIdPool,
   // ── 内部工具（包内共享） ──
-  _now,
+  _nowFor,
   _ctx,
   _call,
   _exec,

package/src/crud/mutation.js

@@ -5,25 +5,42 @@
  */
 
 const { core: _core, get: _getSchema } = require('../schema');
-const { _call, _ctx, _exec, _now, resolvePlaceholders } = require('./exec');
+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, _now(), _newIdPool(schemaName, data), _ctx(),
+    _core.planMutation(schemaName, data, now, _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; // 首步即根写入
+  // §11.4 静默点收口：规划期降级（如关系不可读被跳过）走统一反馈通道，禁止静默失守
+  for (const d of plan.degraded || []) {
+    _emitFeedback({ ...(d || {}), type: 'mutation_degraded' });
   }
 
-  return rootResult ? _call(() => _core.applyWriteDefaults(schemaName, rootResult)) : null;
+  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;
+  };
+
+  // 单一 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();
 }
 
 /**
@@ -38,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];
@@ -54,19 +75,11 @@ 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);
   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

@@ -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 → 关联 → 还原排序）/ 标准聚合 */
@@ -37,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）。
@@ -48,9 +48,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 +76,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 +87,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();
 }
 
 /** 判断是否存在 */
@@ -96,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);
 }