nodejs-store 2.5.0 → 2.6.0

package/README.md

@@ -35,6 +35,7 @@
 - [Schema reference](#schema-reference)
 - [Advanced API](#advanced-api)
 - [Transactions](#transaction-boundary)
+- [Transactional capabilities](#transactional-capabilities)
 - [FAQ](#faq)
 - [Related projects](#related-projects)
 
@@ -210,6 +211,9 @@ GQL tree queries compile to a single native query per backend — never hand-wri
 - **Permission context** — `AsyncLocalStorage`-based roles (`super_admin`/`admin`/`guest`/`creator`...), schema/field-level read/write whitelists, automatic owner-condition injection.
 - **Multi-datasource & multi-tenant** — locate a schema by `(source, namespace, collection)`; re-target per request with a route override.
 - **Async-first, Rust core** — built on the `mongodb` Node.js driver and a shared Rust core with SQL dialects.
+- **Relation predicates in mutations** — filter `update` / `remove` by related-table fields, pushed down to all four backends (previously a silent no-op on MongoDB).
+- **Autoincrement primary keys** — declare `_id` as `{ type: 'int', strategy: 'autoincrement' }` for database-assigned integer IDs, with explicit errors where autoincrement is impossible.
+- **Index DDL** — `schema.indexes` compiles to real `CREATE [UNIQUE] INDEX` statements (per backend, byte-identical); the generator still only emits text.
 
 ## GQL syntax
 
@@ -562,6 +566,18 @@ await init({ default: db, pg_a: executors.createConnection('postgres', pgPool) }
 - Read consistency: only multiple reads inside an explicit session share one transaction connection; reads outside a session do not open an extra transaction.
 - **Cross-source writes (no session)**: a single write call touching ≥2 datasources **cannot be atomic**; it runs sequentially and emits one `non_atomic_write` feedback event (`code: nonAtomic`, with the source list) — degradation is allowed, silence is not. Converge writes onto a single source, or wrap them in `store.session()` (which fails closed on cross-source writes).
 
+## Transactional capabilities
+
+Capabilities aimed at transactional workloads (orders, inventory — write contention plus
+complex reads). Full details, semantics and the explicit-error list:
+**[doc/transaction-capabilities.md](doc/transaction-capabilities.md)** ·
+[中文](doc/transaction-capabilities.zh-CN.md).
+
+- **Relation predicates in mutations** — `updateMany('Inventory', { product: { category: 'meat' } }, { $inc: { stock: 10 } })`: condition keys matching a declared relation become a semi/anti-join, normalized into a preCommand (aggregate fetching `_id`s) plus `_id $in`.
+- **`$group by` one-relation paths** — `by: ['product.category']` compiles to `$lookup`+`$unwind` (Mongo) / `LEFT JOIN` (SQL); `many` paths fail explicitly (fan-out breaks count semantics).
+- **Autoincrement PKs** — `_id: { type: 'int', strategy: 'autoincrement' }`; PG/SQLite read back via `INSERT…RETURNING`, MySQL via insertId; MongoDB and `insertMany` fail explicitly with `AUTOINCREMENT_NOT_SUPPORTED` (no silent ObjectId substitution).
+- **Index DDL** — `schema.indexes` (MongoDB shape) → `CREATE [UNIQUE] INDEX idx_<table>_<cols>` in `ddl.generate`, byte-identical across MySQL/PostgreSQL/SQLite.
+
 ## FAQ
 
 **How do I use one schema for both MongoDB and PostgreSQL in Node.js?**

package/README.zh-CN.md

@@ -34,6 +34,7 @@
 - [Schema 参考](#schema-参考)
 - [高级 API](#高级-api)
 - [事务边界](#事务边界)
+- [事务型能力](#事务型能力)
 - [常见问题](#常见问题)
 - [相关项目](#相关项目)
 
@@ -209,6 +210,9 @@ GQL 树查询会编译为每个后端一条原生查询 —— 再也不必手
 - **权限上下文** —— 基于 `AsyncLocalStorage` 的角色（`super_admin`/`admin`/`guest`/`creator`...）、schema/字段级读写白名单、自动属主条件注入。
 - **多数据源 & 多租户** —— 通过 `(source, namespace, collection)` 定位 schema；按请求用路由覆盖重新定向。
 - **异步优先，Rust 核心** —— 基于 `mongodb` Node.js 驱动与共享的 Rust 核心（含 SQL 方言）。
+- **mutation 关系谓词** —— `update` / `remove` 按关联表字段过滤，下推到全部四个后端（此前 MongoDB 侧是静默 no-op）。
+- **自增主键** —— `_id` 声明 `{ type: 'int', strategy: 'autoincrement' }` 即用数据库自增整数 ID；做不到自增的场景显式报错。
+- **索引 DDL** —— `schema.indexes` 编译为真实 `CREATE [UNIQUE] INDEX` 语句（按后端、逐字节一致）；生成器仍只产文本。
 
 ## GQL 语法
 
@@ -566,6 +570,17 @@ await init({ default: db, pg_a: executors.createConnection('postgres', pgPool) }
   `non_atomic_write` 反馈（`code: nonAtomic`，含涉及源列表）——允许降级、禁止静默。
   把写收敛到单源，或放入 `store.session()` 内（后者对跨源写直接 fail-closed）。
 
+## 事务型能力
+
+面向事务型业务场景（订单、库存——写竞争 + 复杂读）的能力增补。完整语义、用法与显式报错清单：
+**[doc/transaction-capabilities.zh-CN.md](doc/transaction-capabilities.zh-CN.md)** ·
+[English](doc/transaction-capabilities.md).
+
+- **mutation 关系谓词** —— `updateMany('Inventory', { product: { category: 'meat' } }, { $inc: { stock: 10 } })`：条件键命中已声明关系即 semi/anti-join，归一为 preCommand（aggregate 取 `_id`）+ `_id $in`。
+- **`$group by` one 关系路径** —— `by: ['product.category']` 编译为 `$lookup`+`$unwind`（Mongo）/ `LEFT JOIN`（SQL）；many 路径显式报错（扇出破坏计数语义）。
+- **自增主键** —— `_id: { type: 'int', strategy: 'autoincrement' }`；PG/SQLite 经 `INSERT…RETURNING` 回读、MySQL 经 insertId；MongoDB 与 `insertMany` 显式报 `AUTOINCREMENT_NOT_SUPPORTED`（禁 ObjectId 静默顶替）。
+- **索引 DDL** —— `schema.indexes`（Mongo 形态）→ `ddl.generate` 产出 `CREATE [UNIQUE] INDEX idx_<表>_<字段>`，MySQL/PostgreSQL/SQLite 三方言逐字节一致。
+
 ## 常见问题
 
 **如何在 Node.js 中让一份 schema 同时用于 MongoDB 和 PostgreSQL？**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nodejs-store",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Multi-backend data layer for Node.js (MongoDB, MySQL, SQLite, PostgreSQL): pure JSON schemas, GQL tree queries compiled to a single native query, GROUP BY/HAVING aggregation, computed columns, soft-delete and role-based access control",
   "main": "src/index.js",
   "files": [

package/src/crud/write.js

@@ -24,8 +24,14 @@ async function insert(schemaName, data, routeOverride = null) {
   const plan = _call(() =>
     _core.planInsert(schemaName, data ?? null, _nowFor(schemaName), s.idPrefix ? _generateId(s) : '', _ctx(),
       routeOverride));
-  await _exec(plan.command);
-  return plan.returns;
+  const result = await _exec(plan.command);
+  let returns = plan.returns;
+  // 阶段2：autoincrement 主键 —— 执行器已回读自增值，returns 补 `_id`
+  if (returns && typeof returns === 'object' && !returns._id
+      && result && typeof result === 'object' && result._id !== undefined && result._id !== null) {
+    returns = { ...returns, _id: result._id };
+  }
+  return returns;
 }
 
 /** 批量插入（带权限检查，自动生成 _id 和时间戳；空数组直接返回空） */
@@ -33,6 +39,14 @@ async function insertMany(schemaName, docs, routeOverride = null) {
   if (!Array.isArray(docs) || !docs.length) return [];
 
   const s = _getSchema(schemaName);
+  // 阶段2（no-error-masking）：autoincrement 的批量自增值回读不可靠（MySQL 批量
+  // insertId 仅首行、且并发插入会留间隙）→ 显式报错，不静默产出错误 _id
+  const idFdef = (s.fields || {})._id || {};
+  if (idFdef.strategy === 'autoincrement' && docs.some((d) => !(d && d._id))) {
+    throw new Error(
+      'AUTOINCREMENT_NOT_SUPPORTED: insertMany 不支持 autoincrement schema'
+      + '（批量自增值回读不可靠）；请逐条 insert 或显式提供 _id');
+  }
   const plan = _call(() => _core.planInsertMany(
     schemaName,
     docs,
@@ -78,11 +92,46 @@ async function update(schemaName, condition, data, options = null, routeOverride
   return runAtomic(sources, doRun);
 }
 
+/** 执行带 `preCommand` 的命令（阶段1：mutation 关系谓词归一）。
+ * preCommand（aggregate 取命中 `_id`）先行执行，把 `_id` 列表回填进主命令 filter 的
+ * `$in` 占位（core 注入 `"__REL_PRED_IDS__"`）；空集 → `$in: []`（各后端均不命中任何行）。 */
+async function execWithPre(command) {
+  const pre = command && command.preCommand;
+  if (!pre) return _exec(command);
+  const preRows = await _exec(pre);
+  const ids = (preRows || []).filter((d) => d && '_id' in d).map((d) => d._id);
+  return fillPreIds(command, ids);
+}
+
+/** 把 preCommand 取得的 `_id` 列表回填进命令 filter 的 `$in` 占位（递归查找后执行）。
+ * core 注入的占位可能位于 `$and` 数组内（改写条件已有其他键时），故递归遍历。 */
+function fillPreIds(command, ids) {
+  const main = { ...command };
+  delete main.preCommand;
+  const walk = (node) => {
+    if (Array.isArray(node)) {
+      for (const it of node) walk(it);
+      return;
+    }
+    if (node && typeof node === 'object') {
+      for (const [k, v] of Object.entries(node)) {
+        if (v && typeof v === 'object' && v.$in === '__REL_PRED_IDS__') {
+          node[k] = { $in: [...ids] };
+        } else {
+          walk(v);
+        }
+      }
+    }
+  };
+  if (main.filter) walk(main.filter);
+  return _exec(main);
+}
+
 /** 批量更新（支持原生操作符） */
 async function updateMany(schemaName, condition, data, routeOverride = null) {
   const out = _call(() =>
     _core.planUpdateMany(schemaName, condition ?? null, data ?? null, _nowFor(schemaName), _ctx(), routeOverride));
-  const result = await _exec(out.command);
+  const result = await execWithPre(out.command);
   return { modifiedCount: result.modifiedCount };
 }
 
@@ -95,8 +144,15 @@ async function remove(schemaName, condition, routeOverride = null) {
 
   const doRemove = async () => {
     let archivedCount = 0;
+    // 关系谓词：先执行 deleteCommand.preCommand 取命中 _id（归档 find 与删除共用同一列表）
+    const pre = out.deleteCommand && out.deleteCommand.preCommand;
+    let ids = null;
+    if (pre) {
+      const preRows = await _exec(pre);
+      ids = (preRows || []).filter((d) => d && '_id' in d).map((d) => d._id);
+    }
     if (out.findCommand) {
-      const docs = await _exec(out.findCommand);
+      const docs = await (ids !== null ? fillPreIds(out.findCommand, ids) : _exec(out.findCommand));
       if (docs.length) {
         const arch = _call(() => _core.planArchiveDocs(schemaName, docs, _nowFor(schemaName), routeOverride));
         await _exec(arch.command);
@@ -104,7 +160,7 @@ async function remove(schemaName, condition, routeOverride = null) {
       }
     }
 
-    const result = await _exec(out.deleteCommand);
+    const result = await (ids !== null ? fillPreIds(out.deleteCommand, ids) : _exec(out.deleteCommand));
     return { deletedCount: result.deletedCount, archivedCount };
   };
 

package/src/ddl.js

@@ -10,7 +10,9 @@
  *   - 每表必建 __present 哨兵列（形态 ,f1,f2,；同 core write/insert.rs::present_value）；
  *   - timestamps !== false → 追加 createdAt / updatedAt（同 core schema/registry.rs::add_timestamp_fields）；
  *   - 归档表 <collection>_deleted 由 registry 自动派生，本模块按已注册 def 逐表生成（不特判）；
- *   - 不生成 CREATE INDEX（SQL 后端不建索引，schema.indexes 仅元数据，铁律 6）。
+ *   - schema.indexes（Mongo 形态 {keys: {f: 1|-1}, options/inline}）→ CREATE [UNIQUE] INDEX
+ *     （阶段 3 索引落地；原「仅元数据不建索引」铁律 6 子项按用户裁决放开，见
+ *     common-store/事务型能力增补执行文档.md 附录 D）。与 py_store/ddl.py 逐字节对齐。
  *
  * 生成器只产出文本、不执行 —— 不违反铁律 6（绝不写 DDL 回库）。
  * 对齐 py_store/ddl.py（两端输出逐字节一致）。
@@ -38,6 +40,10 @@ const NON_COLUMN = ['object', 'array'];
 // object/array 字段的列类型（JSON 文本列；同 core Backend::json_type_name）
 const JSON_TYPE = ['JSON', 'jsonb', 'TEXT'];
 const ID_TYPE = ['VARCHAR(64)', 'TEXT', 'TEXT'];
+// 阶段2：`_id` 声明 strategy=autoincrement 时的自增列类型（MySQL AUTO_INCREMENT 列
+// 须被索引 —— 表级 PRIMARY KEY 满足；SQLite 语法要求 PRIMARY KEY AUTOINCREMENT 相邻，
+// 由 createTable 的 pk+auto 分支拼接；PG 用 SERIAL）。与 py_store/ddl.py 逐字节对齐。
+const ID_AUTO_TYPE = ['INT AUTO_INCREMENT', 'SERIAL', 'INTEGER'];
 const PRESENT_TYPE = ['VARCHAR(255)', 'TEXT', 'TEXT'];
 const TIMESTAMP_FIELDS = ['createdAt', 'updatedAt'];
 const MYSQL_PRESENT_MAX = 255;
@@ -56,7 +62,7 @@ function declaredType(fieldDef) {
   return fieldDef && typeof fieldDef === 'object' ? fieldDef.type : fieldDef;
 }
 
-/** 返回 [[name, sqlType, pk]]，顺序：声明的字段（标量 / object·array JSON 列）→ timestamps → __present */
+/** 返回 [[name, sqlType, pk, auto]]，顺序：声明的字段（标量 / object·array JSON 列）→ timestamps → __present */
 function columns(defn, backend) {
   const i = idx(backend);
   const cols = [];
@@ -64,12 +70,14 @@ function columns(defn, backend) {
   for (const [name, fdef] of Object.entries(fields)) {
     const ftype = declaredType(fdef);
     if (name === '_id') {
-      cols.push([name, ID_TYPE[i], true]);
+      const strategy = fdef && typeof fdef === 'object' ? fdef.strategy : undefined;
+      cols.push([name, strategy === 'autoincrement' ? ID_AUTO_TYPE[i] : ID_TYPE[i], true,
+        strategy === 'autoincrement']);
       continue;
     }
     if (NON_COLUMN.includes(ftype)) {
       // object/array → 单列 JSON 文本（同 core field_column_ref::Json）
-      cols.push([name, JSON_TYPE[i], false]);
+      cols.push([name, JSON_TYPE[i], false, false]);
       continue;
     }
     if (!Object.prototype.hasOwnProperty.call(TYPES, ftype)) {
@@ -77,17 +85,17 @@ function columns(defn, backend) {
         `DDL 生成：字段 "${defn.name}.${name}" 类型 ${JSON.stringify(ftype)} 未知，支持 ${Object.keys(TYPES).sort()}`,
       );
     }
-    cols.push([name, TYPES[ftype][i], false]);
+    cols.push([name, TYPES[ftype][i], false, false]);
   }
   if (!cols.some((c) => c[2])) {
     throw new Error(`DDL 生成：schema "${defn.name}" 缺少 _id 字段`);
   }
   if (defn.timestamps !== false) {
     for (const ts of TIMESTAMP_FIELDS) {
-      if (!cols.some((c) => c[0] === ts)) cols.push([ts, TYPES.number[i], false]);
+      if (!cols.some((c) => c[0] === ts)) cols.push([ts, TYPES.number[i], false, false]);
     }
   }
-  cols.push(['__present', PRESENT_TYPE[i], false]);
+  cols.push(['__present', PRESENT_TYPE[i], false, false]);
   return cols;
 }
 
@@ -106,13 +114,35 @@ function warnPresentOverflow(defn, cols) {
   }
 }
 
+/** schema.indexes → CREATE [UNIQUE] INDEX 语句列表（阶段 3 索引落地）。
+ * 索引名 `idx_<collection>_<f1>_<f2>`（对齐 SQL 常规命名）；keys 值 1/-1 → ASC/DESC。 */
+function indexStmts(defn, backend) {
+  const out = [];
+  const table = defn.collection || defn.name;
+  for (const idx of defn.indexes || []) {
+    if (!idx || typeof idx !== 'object') continue;
+    const keys = idx.keys;
+    if (!keys || typeof keys !== 'object' || !Object.keys(keys).length) continue;
+    const unique = Boolean(idx.unique || (idx.options && idx.options.unique));
+    const cols = Object.entries(keys)
+      .map(([k, v]) => `${q(backend, k)} ${v === -1 ? 'DESC' : 'ASC'}`)
+      .join(', ');
+    const name = 'idx_' + table + '_' + Object.keys(keys).join('_');
+    out.push(`CREATE ${unique ? 'UNIQUE ' : ''}INDEX ${q(backend, name)} ON ${q(backend, table)} (${cols})`);
+  }
+  return out;
+}
+
 function createTable(defn, backend) {
   const table = defn.collection || defn.name;
   const cols = columns(defn, backend);
   if (backend === 'mysql') warnPresentOverflow(defn, cols);
   const lines = [];
-  for (const [name, ctype, pk] of cols) {
-    if (pk && backend === 'mysql') lines.push(`  ${q(backend, name)} ${ctype} NOT NULL`);
+  for (const [name, ctype, pk, auto] of cols) {
+    if (pk && auto && backend === 'sqlite') {
+      // SQLite 语法要求 AUTOINCREMENT 紧跟 PRIMARY KEY
+      lines.push(`  ${q(backend, name)} ${ctype} PRIMARY KEY AUTOINCREMENT`);
+    } else if (pk && backend === 'mysql') lines.push(`  ${q(backend, name)} ${ctype} NOT NULL`);
     else if (pk) lines.push(`  ${q(backend, name)} ${ctype} PRIMARY KEY`);
     else lines.push(`  ${q(backend, name)} ${ctype}`);
   }
@@ -120,13 +150,40 @@ function createTable(defn, backend) {
   return `CREATE TABLE ${q(backend, table)} (\n` + lines.join(',\n') + '\n);';
 }
 
-/** 生成 DDL 文本（多表以空行分隔）；backend ∈ mysql/postgres/sqlite */
+/** 生成 DDL 文本（多表以空行分隔，每表 CREATE TABLE 后跟其 CREATE INDEX）；backend ∈ mysql/postgres/sqlite
+ *
+ * 按表名去重：同名表只出一次 CREATE TABLE + 索引（防御 core 注册表出现重复名 ——
+ * 上游失守即告警，禁静默；对齐 py_store/ddl.py 的 seen_tables 防御）。 */
 function generate(backend, names) {
   if (!BACKENDS.includes(backend)) {
     throw new Error(`DDL 生成：不支持的后端 ${JSON.stringify(backend)}（支持 ${BACKENDS.join('/')}）`);
   }
   const targets = names && names.length ? Array.from(names) : schema.list();
-  return targets.map((n) => createTable(schema.get(n), backend)).join('\n\n');
+  const blocks = [];
+  const seenTables = new Set();
+  const dup = [];
+  for (const n of targets) {
+    const defn = schema.get(n);
+    const table = defn.collection || n;
+    if (seenTables.has(table)) {
+      dup.push(table);
+      continue;
+    }
+    seenTables.add(table);
+    blocks.push(createTable(defn, backend));
+    blocks.push(...indexStmts(defn, backend));
+  }
+  if (dup.length) {
+    _emitFeedback({
+      type: 'ddl_duplicate_table',
+      code: 'ddlDuplicateTable',
+      layer: 'host',
+      message: `DDL 生成：表 ${[...new Set(dup)].sort()} 重复注册，已去重`,
+      hint: 'schema 注册表出现重复名（见 schemaDuplicateName 告警）；修复注册侧根因',
+      backend,
+    });
+  }
+  return blocks.join('\n\n');
 }
 
 module.exports = { generate };

package/src/executors/index.js

@@ -86,8 +86,21 @@ function shapeResult(cmd, out) {
       return (out.docs && out.docs[0]) || null;
     case 'countDocuments':
       return _scalar(out.rows);
-    case 'insertOne':
-      return cmd.doc;
+    case 'insertOne': {
+      const doc = cmd.doc;
+      // 阶段2：autoincrement 主键 —— doc 无 `_id`（core 不注入）→ 从执行包络回读
+      // 自增值（PG/SQLite RETURNING 走 rows；MySQL/SQLite lastInsertRowid 走 insertId）
+      if (doc && !doc._id) {
+        let rid = null;
+        if (out.rows && out.rows[0] && Object.prototype.hasOwnProperty.call(out.rows[0], '_id')) {
+          rid = out.rows[0]._id;
+        } else if (out.insertId !== null && out.insertId !== undefined) {
+          rid = out.insertId;
+        }
+        if (rid !== null && rid !== undefined) return { ...doc, _id: rid };
+      }
+      return doc;
+    }
     case 'insertMany':
       return { insertedCount: (cmd.docs || []).length };
     case 'updateMany':

package/src/executors/mongo.js

@@ -119,9 +119,19 @@ async function execMongo(db, cmd, session) {
       const opts = _opts(session, cmd.projection ? { projection: cmd.projection } : undefined);
       return coll.findOne(cmd.filter, opts);
     }
-    case 'insertOne':
-      await coll.insertOne(cmd.doc, _opts(session));
-      return cmd.doc;
+    case 'insertOne': {
+      const doc = cmd.doc || {};
+      // 阶段2（no-error-masking）：Mongo 无自增语义 —— `_id` 缺失的文档只可能来自
+      // 声明 strategy=autoincrement 的 schema（常规 schema 该形态已被 core 拦截）。
+      // 禁止 ObjectId 静默顶替自增契约，显式报错。
+      if (!doc._id) {
+        throw new Error(
+          'AUTOINCREMENT_NOT_SUPPORTED: schema 声明了 strategy="autoincrement"，'
+          + 'MongoDB 后端无自增语义（禁 ObjectId 顶替）；请使用 SQL 数据源');
+      }
+      await coll.insertOne(doc, _opts(session));
+      return doc;
+    }
     case 'insertMany':
       if (cmd.upsertById) {
         // 归档幂等（core planArchiveDocs）：按 _id 逐条覆盖 —— 「归档成功但删除失败」
@@ -131,6 +141,11 @@ async function execMongo(db, cmd, session) {
         }
         return { insertedCount: cmd.docs.length };
       }
+      if (cmd.docs.some((d) => !(d && d._id))) {
+        throw new Error(
+          'AUTOINCREMENT_NOT_SUPPORTED: schema 声明了 strategy="autoincrement"，'
+          + 'MongoDB 后端无自增语义（禁 ObjectId 顶替）；请使用 SQL 数据源');
+      }
       await coll.insertMany(cmd.docs, _opts(session));
       return { insertedCount: cmd.docs.length };
     case 'findOneAndUpdate':

package/src/executors/mysql.js

@@ -30,6 +30,7 @@ function create(driver, _options = {}) {
     let docs = null;
     let rows = null;
     let affectedRows = 0;
+    let insertId = null;
     for (const stmt of plan.stmts) {
       const [raw, fields] = await conn.execute(stmt.text, stmt.params || []);
       if (Array.isArray(raw)) {
@@ -37,9 +38,12 @@ function create(driver, _options = {}) {
         if (stmt.rowShape) docs = _core.restoreRows(stmt.rowShape, rows);
       } else {
         affectedRows = Number(raw.affectedRows || 0);
+        // 阶段2：autoincrement 主键写后自增值回读（MySQL 无 RETURNING，insertId =
+        // 本连接最近一次 INSERT 生成的自增值）
+        insertId = Number(raw.insertId);
       }
     }
-    return { docs, rows, affectedRows };
+    return { docs, rows, affectedRows, insertId };
   }
 
   /**

package/src/executors/sqlite.js

@@ -36,6 +36,7 @@ function create(db, _options = {}) {
     let docs = null;
     let rows = null;
     let affectedRows = 0;
+    let insertId = null;
     for (const stmt of plan.stmts) {
       const params = _bind(stmt.params);
       // 带 RETURNING 的写语句同样返回行 → 必须用 all() 取回；其余写语句用 run() 取影响行数
@@ -43,10 +44,14 @@ function create(db, _options = {}) {
         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);
+        const info = db.prepare(stmt.text).run(...params);
+        affectedRows = Number(info.changes || 0);
+        // 阶段2：autoincrement 主键写后自增值回读（非 RETURNING 的 INSERT 走
+        // lastInsertRowid；带 RETURNING 的写语句走上方 rows 分支）
+        insertId = Number(info.lastInsertRowid);
       }
     }
-    return { docs, rows, affectedRows };
+    return { docs, rows, affectedRows, insertId };
   }
 
   /** 显式事务句柄：BEGIN + 幂等 commit/rollback；release 为 no-op（单连接不归还） */