nodejs-store 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nodejs-store contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,201 @@
+# nodejs-store
+
+A lightweight multi-backend data layer for Node.js — define your models as pure JSON schemas, query with GQL tree syntax, and get role-based access control out of the box. One unified MongoDB-style dialect runs on **MongoDB, MySQL, SQLite and PostgreSQL**.
+
+This is the Node.js port of [`py-store`](https://github.com/coenddt/py-store) — same schemas, same GQL, same semantics, camelCase API. Both are thin hosts over the shared Rust core in [`rust-store`](https://github.com/coenddt/rust-store).
+
+## Supported backends
+
+| Backend | Notes |
+| --- | --- |
+| MongoDB | native aggregation pipeline (`find`/`aggregate`/`$lookup`) |
+| MySQL | parameterized SQL, `information_schema` introspection |
+| SQLite | parameterized SQL, `sqlite_master` + `PRAGMA` introspection |
+| 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.
+
+## Features
+
+- **Pure JSON schemas, zero code** — a model is just an object: fields, relations, computes, indexes.
+- **Read-time defaults & computed columns** — writes store only user data; reads fill defaults and run `fn`/`asyncFn` computes.
+- **GQL tree queries → one native query** — nested relations resolve in a single query; never hand-write `$lookup` again.
+- **Smart mutation** — `mutation()` auto-detects upsert by `_id` + unique index and recursively fills relation children.
+- **Soft-delete built in** — every schema auto-registers a `<Model>Deleted` archive collection/table; `remove()` archives before deleting.
+- **Permission context** — `AsyncLocalStorage`-based roles (`super_admin`/`admin`/`guest`/`creator`...), schema/field-level read/write whitelists, automatic owner-condition injection.
+- **Async-first** — built on the `mongodb` Node.js driver and a shared Rust core with SQL dialects.
+
+## Installation
+
+```bash
+npm install nodejs-store
+```
+
+Requires Node.js 18+ and one supported backend (MongoDB / MySQL / SQLite / PostgreSQL).
+
+## Quick start
+
+```js
+const { MongoClient } = require('mongodb');
+const { init, store } = require('nodejs-store');
+
+const client = new MongoClient('mongodb://localhost:27017');
+await client.connect();
+await init(client.db('mydb')); // idempotently creates indexes for registered schemas
+
+// Register a schema (pure JSON)
+store.register({
+  name: 'Post',          // model name used in GQL
+  collection: 'posts',   // optional, defaults to name
+  idPrefix: 'PT',        // string _id: prefix + base36 timestamp + random
+  fields: {
+    title: { type: 'string', default: '' },
+    status: { type: 'string', default: 'draft' },
+    tags: { type: 'array', default: [] },
+  },
+  computes: {
+    statusLabel: {
+      type: 'string',
+      depends: ['status'],
+      fn: (doc) => (doc.status || '').toUpperCase(),
+    },
+  },
+  indexes: [{ keys: { status: 1, createdAt: -1 } }],
+});
+
+// Write — only user data; defaults are filled on read
+const doc = await store.insert('Post', { title: 'Hello' });
+
+// Query — GQL tree syntax, values referenced from params via @key
+const items = await store.query(
+  'Post($condition:@c0,$sort:@s1,$limit:@l) { title, status, statusLabel }',
+  { c0: { status: 'draft' }, s1: { createdAt: -1 }, l: 20 },
+);
+```
+
+## Multi-datasource connections
+
+Every schema is located by the triple `(source, namespace, collection)` — the triple must be
+globally unique across the registry (duplicate registration throws instead of silently
+mis-routing).
+
+- `source` — connection key in `init({...})` (default `"default"`).
+- `namespace` — database/schema inside the connection: Mongo db name, PG schema,
+  MySQL database, SQLite attached db. Optional; `null` = connection default.
+- `collection` — table/collection name.
+
+```js
+// Multiple Mongo servers: one source per connection
+await init({ mongo_main: db, pg_a: { kind: 'postgres', exec } });
+
+// Same MongoClient serving multiple databases: declare namespace (db name)
+await init({ cluster: client });
+store.register({ name: 'User', collection: 'users', datasource: 'cluster', namespace: 'tenant_42', ... });
+
+// SQL cross-namespace joins are pushed down natively ("ns_a"."t" JOIN "ns_b"."t");
+// only Mongo cross-db relations fall back to in-memory federation.
+```
+
+**Multi-tenant route override** — one schema definition, N tenants. Any query/write accepts
+a `{ source, namespace }` override that re-targets commands at execution time (permissions
+and computed columns still follow the structural schema):
+
+```js
+await store.query('User($condition:@c0){...}', params, { namespace: 'tenant_42' });
+await store.insert('Order', data, { source: 'pg_cluster', namespace: 'tenant_7' });
+```
+
+Legacy single-db usage (`init(db)` + schema without `datasource`/`namespace`) is unchanged:
+commands carry `source: 'default'`, `namespace: null`.
+
+## GQL syntax
+
+```text
+Model($condition:@c0,$sort:@s1,$skip:@sk,$limit:@l1) {
+  field1, field2, obj.subField,
+  Relation($condition:@c2,$sort:@s3,$limit:@l2) { f3, Nested { f4 } }
+}
+```
+
+- 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.
+
+## Query & write API
+
+```js
+const items  = await store.query(gql, params);            // Array
+const one    = await store.queryOne(gql, params);         // object | null
+const page   = await store.queryWithCount(gql, params);   // { items, total, hasMore, page, pageSize } (pageSize capped at 5000)
+const exists = await store.exists('Post', { _id: pid });
+const n      = await store.count('Post', { status: 'active' });
+
+const doc    = await store.insert('Post', { ... });       // auto _id / createdAt / updatedAt
+const docs   = await store.insertMany('Post', [{ ... }, ...]);
+await store.update('Post', { _id: pid }, { status: 'live' });      // plain fields → $set
+await store.update('Post', { _id: pid }, { $inc: { views: 1 } });  // '$'-prefixed keys pass through as operators
+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:
+
+- `null`/`undefined` values are stripped before persisting; `_id` cannot be changed via `update`.
+- `createdAt`/`updatedAt` (ms) are framework-maintained — do not set them manually.
+- `queryWithCount` accepts `page`/`pageSize` (recommended) or the traditional `$skip`/`$limit` params.
+
+## Permission context
+
+```js
+// Set once per request (in middleware/router layer)
+store.setContext({ userId: uid, roles: ['editor'] });
+
+// Nested-safe role scoping
+store.scopedRoles(['viewer'], () => store.query(gql, params));
+
+// Internal/cron jobs — bypass permission checks
+await store.runAsInternal(() => store.remove('Post', { _id: pid }));
+```
+
+- `super_admin`/`admin`/`internal` roles pass everything; other roles are checked against schema-level and field-level `read`/`write` whitelists; `guest` can never write.
+- `creator` is a pseudo-role resolved by `doc.createdBy === ctx.userId`; schemas granting it automatically get owner conditions injected on queries and ownership checks on update/remove.
+- No context set → permission checks disabled (backward compatible).
+- Denied access throws `store.PermissionError` (with `status = 403`).
+
+## Schema reference
+
+```js
+{
+  name: 'Order',
+  collection: 'orders',
+  idPrefix: 'OD',
+  timestamps: true,                  // default: auto-maintain createdAt/updatedAt (ms)
+  fields: {
+    _id: 'string',                                        // shorthand
+    title: { type: 'string', default: '' },
+    meta: { type: 'object', default: {}, fields: { ... } },  // nested object fields
+  },
+  relations: {
+    items: { model: 'OrderItem', type: 'many', localField: '_id', foreignField: 'orderId' },
+  },
+  computes: {
+    total: { type: 'float', depends: ['amount'], fn: (d) => d.amount * 1.1 },
+    itemCount: { type: 'int', lookup: { $size: { $ifNull: ['$items', []] } } },
+  },
+  indexes: [
+    { keys: { status: 1 } },
+    { keys: { code: 1 }, options: { unique: true } },
+  ],
+  read: ['editor', 'viewer'],        // optional schema-level role whitelists
+  write: ['editor'],
+}
+```
+
+Types: `string | int | long | float | double | boolean | array | object | date | any`.
+
+## License
+
+[MIT](LICENSE)

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "nodejs-store",
+  "version": "1.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": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node scripts/test.js"
+  },
+  "keywords": [
+    "mongodb",
+    "mysql",
+    "sqlite",
+    "postgresql",
+    "data-layer",
+    "query-builder",
+    "odm",
+    "gql",
+    "acl",
+    "aggregation"
+  ],
+  "author": "leo <coen_ddt@qq.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/coenddt/nodejs-store.git"
+  },
+  "bugs": {
+    "url": "https://github.com/coenddt/nodejs-store/issues"
+  },
+  "homepage": "https://github.com/coenddt/nodejs-store#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "better-sqlite3": "^13.0.3",
+    "mongodb": "^6.21.0",
+    "mysql2": "^3.24.4",
+    "pg": "^8.23.0",
+    "rust-store-node": "^1.0.0"
+  }
+}

package/src/core.js

@@ -0,0 +1,55 @@
+'use strict';
+
+/**
+ * rust-store 原生绑定加载器（唯一原生模块入口）
+ *
+ * mongo-store 采用「Rust 单核心 + 双绑定」架构：schema/GQL/权限/计算列/命令规划
+ * 全部在 Rust core 实现，本目录 src/*.js 只是薄 Host 适配层（驱动 IO + 回调 + 占位符）。
+ *
+ * 生产环境**只**从 npm 依赖 `rust-store-node` 加载原生模块。
+ * 开发期若需从相邻 rust-store 仓库的调试产物加载，必须显式设置：
+ *   LOCAL_CORE=1 且 NODE_ENV !== 'production'
+ */
+
+const path = require('path');
+
+function _requireDevFallback() {
+  // 开发期兜底：仅 LOCAL_CORE=1 且非 production 时启用，
+  // 避免生产环境从相邻目录加载任意原生模块。
+  if (process.env.LOCAL_CORE !== '1' || process.env.NODE_ENV === 'production') return null;
+  const devPath = path.join(
+    __dirname,
+    '..',
+    '..',
+    'rust-store',
+    'core-node',
+    'dist',
+    'rust-store-node.node',
+  );
+  try {
+    return require(devPath);
+  } catch (e) {
+    return { __error: `${devPath}: ${e.message.split('\n')[0]}` };
+  }
+}
+
+function _load() {
+  try {
+    return require('rust-store-node');
+  } catch (e) {
+    const fallback = _requireDevFallback();
+    if (fallback && !fallback.__error) return fallback;
+
+    const hints = [`rust-store-node: ${e.message.split('\n')[0]}`];
+    if (fallback && fallback.__error) hints.push(fallback.__error);
+    throw new Error(
+      '无法加载 rust-store 原生核心（rust-store-node 绑定产物）。\n'
+      + '请安装 npm 依赖 rust-store-node；开发期如需从相邻 rust-store 仓库加载，\n'
+      + '请设置 LOCAL_CORE=1（且 NODE_ENV !== \'production\'）并在 rust-store 仓库构建：\n'
+      + '  cargo build --manifest-path core-node/Cargo.toml\n'
+      + hints.join('\n'),
+    );
+  }
+}
+
+module.exports = _load();

package/src/crud/exec.js

@@ -0,0 +1,139 @@
+'use strict';
+
+/**
+ * 命令执行（唯一 IO 边界） + 占位符替换 + core 调用包装
+ *
+ * 全部纯逻辑（GQL 解析、权限、命令规划、结果后处理）都在 Rust core；
+ * 本模块只做 Host 三件事里最底层的一件：把 core 产出的 Command JSON
+ * 路由到对应数据源连接并执行。不确定性输入由本层供给（now 时钟）。
+ *
+ * 路由规则见 `../datasource`：命令自带 `source` / `namespace` 三元组，按 `source`
+ * 选连接、`namespace` 定位连接内的库（Mongo 双形态严格校验），
+ * Mongo 走原生驱动，SQL 走 `translate → exec`。
+ */
+
+const { PermissionError, getContext } = require('../permission');
+const datasource = require('../datasource');
+
+const _PHASE1_IDS = /^\{\{phase1\.ids\}\}$/;
+const _STEP_PH = /^\{\{step\.(\d+)\._id\}\}$/;
+
+/** core 权限类错误消息 → PermissionError（消息与 core 常量保持一致） */
+const _PERMISSION_MSGS = new Set(['无访问权限', '无写入权限', '无删除权限', '无批量写入权限']);
+
+/** 设置数据源连接映射（对 `../datasource` 的路由入口做包内透出） */
+const setConnections = datasource.setConnections;
+
+/** 毫秒时间戳（Host 时钟源） */
+function _now() {
+  return Date.now();
+}
+
+function _ctx() {
+  return getContext() ?? null;
+}
+
+/** 绑定层调用包装：权限类错误映射为 PermissionError */
+function _call(fn) {
+  try {
+    return fn();
+  } catch (e) {
+    if (_PERMISSION_MSGS.has(e && e.message)) throw new PermissionError(e.message);
+    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） */
+async function _execOn(source, cmd) {
+  const connection = datasource.getConnection(source);
+  const db = datasource.mongoDb(connection, source, cmd.namespace ?? null);
+  if (db) {
+    return _execMongo(db, cmd);
+  }
+  return datasource.execSql(source, connection, cmd);
+}
+
+/** Command JSON → 按命令自带的 `source` 路由（不按 collection 反查） */
+async function _exec(cmd) {
+  return _execOn(cmd.source || datasource.DEFAULT_SOURCE, cmd);
+}
+
+/** 深度替换命令中的占位符（命中 resolver 返回非字符串时替换） */
+function _substitute(value, resolver) {
+  if (typeof value === 'string') return resolver(value);
+  if (Array.isArray(value)) return value.map((v) => _substitute(v, resolver));
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) out[k] = _substitute(v, resolver);
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Host 契约：把命令中的占位符替换为执行结果
+ *
+ *   - `{{phase1.ids}}`     → 两阶段查询第一步取回的 id 数组（整值替换）
+ *   - `{{step.<N>._id}}`   → mutation 第 N 步执行结果的 _id
+ *
+ * 未命中的占位符原样保留（便于定位 core 与 Host 的契约漂移）。
+ * Python 侧 `py_store.crud.exec.resolve_placeholders` 为同语义实现，
+ * 两侧共测 `rust-store/fixtures/host/placeholders.json`。
+ */
+function resolvePlaceholders(command, { ids = null, steps = [] } = {}) {
+  return _substitute(command, (s) => {
+    if (_PHASE1_IDS.test(s)) return ids ?? s;
+    const m = s.match(_STEP_PH);
+    if (m) {
+      const idx = Number(m[1]);
+      if (idx < steps.length) return steps[idx];
+    }
+    return s;
+  });
+}
+
+module.exports = {
+  setConnections,
+  _now,
+  _ctx,
+  _call,
+  _exec,
+  _execOn,
+  _substitute,
+  resolvePlaceholders,
+};

package/src/crud/id.js

@@ -0,0 +1,59 @@
+'use strict';
+
+/**
+ * ID 供给（Host 随机源） —— 与 core `needs_new_id` 语义对齐
+ *
+ * core 无随机源：需要新 _id 时由 Host 按序供给，本模块负责生成与遍历。
+ */
+
+const { get: _getSchema } = require('../schema');
+
+const _ID_CHARS = 'abcdefghijklmnopqrstuvwxyz0123456789';
+
+/** 按 schema.idPrefix 生成唯一 ID（时间戳36进制 + 随机4位） */
+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)];
+  }
+  return schema.idPrefix + ts + rnd.toUpperCase();
+}
+
+/** 对齐 core `is_truthy`（字符串仅判空，不 trim） */
+function _truthy(v) {
+  if (v === null || v === undefined || v === false) return false;
+  if (typeof v === 'number') return v !== 0;
+  if (typeof v === 'string') return v.length > 0;
+  return true;
+}
+
+/**
+ * 预生成 mutation 的 ID 池：按数据树逐节点判断是否需要新 _id
+ * （与 core `needs_new_id` 一致：无有效 _id 且 schema 配了 idPrefix），
+ * 保证游标消费顺序与节点顺序对齐（父子 schema 前缀不同也能取对 ID）。
+ */
+function _newIdPool(schemaName, data) {
+  const pool = [];
+  const walk = (name, node) => {
+    const s = _getSchema(name);
+    if (!_truthy(node?._id) && s.idPrefix) {
+      pool.push(_generateId(s));
+    }
+    for (const [key, val] of Object.entries(node || {})) {
+      const rel = s.relations[key];
+      if (!rel || val === null || val === undefined) continue;
+      if (Array.isArray(val)) {
+        for (const child of val) {
+          if (child !== null && child !== undefined) walk(rel.model, child);
+        }
+      } else {
+        walk(rel.model, val);
+      }
+    }
+  };
+  walk(schemaName, data);
+  return pool;
+}
+
+module.exports = { _generateId, _truthy, _newIdPool };

package/src/crud/index.js

@@ -0,0 +1,55 @@
+'use strict';
+
+/**
+ * CRUD 包 —— 薄 Host 适配层（对齐 py-store/src/py_store/crud/ 的分工）
+ *
+ * 全部纯逻辑（GQL 解析、权限、命令规划、结果后处理）都在 Rust core；
+ * 本包只做 Host 三件事：
+ *   1. 命令执行（唯一 IO 边界：按 collection 绑定路由到 Mongo / SQL，见 `../datasource`）
+ *   2. 占位符替换（{{phase1.ids}} / {{step.<N>._id}} 依赖真实执行结果）
+ *   3. 原生回调（asyncFn 计算列两段式：prepareQuery 取 fnRefs → Host await → stripQuery）
+ *
+ * 不确定性输入由本包供给：now（时钟）、newIds（随机 ID，core 按需消费）。
+ *
+ * 模块划分：
+ *   - [`exec`]：命令执行 + 占位符替换 + core 调用包装（唯一 IO 边界）
+ *   - [`id`]：ID 生成与 mutation ID 池遍历
+ *   - [`query`]：读路径
+ *   - [`write`]：写路径
+ *   - [`mutation`]：mutation / upsert / 原生聚合
+ */
+
+const { setConnections, _now, _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');
+
+module.exports = {
+  setConnections,
+  query,
+  queryOne,
+  queryWithCount,
+  queryFederated,
+  insert,
+  insertMany,
+  update,
+  updateMany,
+  remove,
+  exists,
+  count,
+  mutation,
+  upsert,
+  aggregate,
+  // ── Host 契约件（供跨语言同构契约测试与高级用法；下划线表示内部语义） ──
+  _substitute,
+  resolvePlaceholders,
+  _generateId,
+  _truthy,
+  _newIdPool,
+  // ── 内部工具（包内共享） ──
+  _now,
+  _ctx,
+  _call,
+  _exec,
+};

package/src/crud/mutation.js

@@ -0,0 +1,72 @@
+'use strict';
+
+/**
+ * Mutation / Upsert / 原生聚合 —— 规划步骤序列 → 依序执行 + 父子 _id 占位符回填
+ */
+
+const { core: _core, get: _getSchema } = require('../schema');
+const { _call, _ctx, _exec, _now, 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(),
+      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; // 首步即根写入
+  }
+
+  return rootResult ? _call(() => _core.applyWriteDefaults(schemaName, rootResult)) : null;
+}
+
+/**
+ * mutation — 智能持久化
+ *
+ * 自动判断 upsert/insert，支持父子文档关联填充。
+ * `routeOverride` 可选：`{ source?, namespace? }` 多租户路由。
+ */
+async function mutation(schemaName, data, routeOverride = null) {
+  const isArray = Array.isArray(data);
+  const items = isArray ? data : [data];
+
+  if (!items.length) return isArray ? [] : null;
+
+  const results = [];
+  for (const item of items) {
+    results.push(await _mutationOne(schemaName, item, routeOverride));
+  }
+
+  return isArray ? results : results[0];
+}
+
+/**
+ * upsert — 显式条件 upsert
+ *
+ * 与 mutation 不同，upsert 需要调用方显式提供 match 条件，不处理父子关系。
+ */
+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(),
+    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 };