nodejs-store 2.4.0 → 2.6.0

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

@@ -38,6 +38,43 @@ function _scalar(rows) {
   return typeof v === 'string' ? Number(v) : v;
 }
 
+/**
+ * 显式 checkout：返回 `{ conn, release }`；`release` 为 async 幂等函数。
+ *
+ * 池形态（pg Pool → `connect()` / mysql2 Pool → `getConnection()`）失败**直接上抛**，
+ * 禁「静默退回 driver 本体」——退回本体可能落到池上另一连接，使事务语义错乱；
+ * 单连接形态直用 driver，release 为 no-op。
+ * pg / mysql 执行器的显式事务句柄均以此为基础（禁第二套 checkout 路径）。
+ */
+async function openAcquire(driver) {
+  if (driver && typeof driver.connect === 'function') {
+    const conn = await driver.connect(); // pg Pool：失败直接上抛
+    let released = false;
+    return {
+      conn,
+      release: async () => {
+        if (released) return;
+        released = true;
+        // pg Client（connect() 返回自身）无 release()，属单连接形态
+        if (typeof conn.release === 'function') conn.release();
+      },
+    };
+  }
+  if (driver && typeof driver.getConnection === 'function') {
+    const conn = await driver.getConnection(); // mysql2 Pool：失败直接上抛
+    let released = false;
+    return {
+      conn,
+      release: async () => {
+        if (released) return;
+        released = true;
+        conn.release();
+      },
+    };
+  }
+  return { conn: driver, release: async () => {} }; // 单连接形态
+}
+
 /** 中立包络 → Mongo 驱动等价返回值 */
 function shapeResult(cmd, out) {
   switch (cmd.kind) {
@@ -49,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':
@@ -62,4 +112,4 @@ function shapeResult(cmd, out) {
   }
 }
 
-module.exports = { createConnection, shapeResult, mongo, mysql, postgres, sqlite };
+module.exports = { createConnection, openAcquire, shapeResult, mongo, mysql, postgres, sqlite };

package/src/executors/mongo.js

@@ -11,6 +11,10 @@
  * 同时命中「值为 null」与「字段缺失」两类文档，而本 store 的三态契约（F-07/H-09）
  * 要求 `null` 只命中显式 null、`$exists:false` 才命中缺失 —— 这与 SQL 侧
  * `col IS NULL`（显式 null）语义对齐。运算对象（`$ne:null`/`$exists`/`$gt`…）不改写。
+ *
+ * Mongo session 事务：本模块只提供原语 `openTransaction`（`startSession` +
+ * `startTransaction`）与 `execMongo(..., session)` 透传；事务的编排（提交/回滚/
+ * 降级声明）由 datasource 层负责。Mongo **无** `SAVEPOINT` 原语，故不提供保存点系列。
  */
 
 /** 递归改写 filter：`field: null`（标量等值）→ `field: {$eq: null, $exists: true}`。 */
@@ -51,52 +55,111 @@ function _normPipeline(cmd) {
   }
 }
 
-/** Command JSON → MongoDB 原生驱动调用 */
-async function execMongo(db, cmd) {
+/** Mongo 连接的 client：db 实例取 .client；MongoClient 返回自身 */
+function _clientOf(connection) {
+  if (connection && typeof connection.db === 'function' && typeof connection.collection !== 'function') {
+    return connection; // MongoClient
+  }
+  return (connection && connection.client) || null; // Db.client
+}
+
+/** 合并 session 到 options（session 为空时返回原 options 语义，零回归） */
+function _opts(session, base) {
+  const o = base ? { ...base } : {};
+  if (session) o.session = session;
+  return o;
+}
+
+/**
+ * Mongo 事务句柄：startSession + startTransaction
+ *   - commit/rollback 幂等；release 结束 session；
+ *   - 无保存点原语（Mongo 不支持 SAVEPOINT），嵌套由 datasource 层降级声明。
+ */
+async function openTransaction(connection) {
+  const client = _clientOf(connection);
+  const session = client.startSession();
+  session.startTransaction();
+  let closed = false;
+  return {
+    session,
+    async commit() {
+      if (closed) return;
+      closed = true;
+      await session.commitTransaction();
+    },
+    async rollback() {
+      if (closed) return;
+      closed = true;
+      await session.abortTransaction();
+    },
+    async release() {
+      await session.endSession();
+    },
+  };
+}
+
+/** Command JSON → MongoDB 原生驱动调用（session 非空时全部操作携带该 session） */
+async function execMongo(db, cmd, session) {
   const coll = db.collection(cmd.collection);
   switch (cmd.kind) {
     case 'find': {
       _normFilter(cmd);
-      const opts = cmd.projection ? { projection: cmd.projection } : undefined;
+      const opts = _opts(session, cmd.projection ? { projection: cmd.projection } : undefined);
       return coll.find(cmd.filter, opts).toArray();
     }
     case 'aggregate':
+      // cmd.options 为原生聚合透传项（executeNative 注入；GQL 路径无此键，零回归）
       _normPipeline(cmd);
-      return coll.aggregate(cmd.pipeline).toArray();
+      return coll.aggregate(cmd.pipeline, _opts(session, cmd.options)).toArray();
     case 'countDocuments':
       _normFilter(cmd);
-      return coll.countDocuments(cmd.filter);
+      return coll.countDocuments(cmd.filter, _opts(session));
     case 'findOne': {
       _normFilter(cmd);
-      const opts = cmd.projection ? { projection: cmd.projection } : undefined;
+      const opts = _opts(session, cmd.projection ? { projection: cmd.projection } : undefined);
       return coll.findOne(cmd.filter, opts);
     }
-    case 'insertOne':
-      await coll.insertOne(cmd.doc);
-      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 逐条覆盖 —— 「归档成功但删除失败」
         // 的重试不再因 _id 冲突整批失败。SQL 侧由 dialect 的 ON CONFLICT/REPLACE 承接。
         for (const doc of cmd.docs) {
-          await coll.replaceOne({ _id: doc._id }, doc, { upsert: true });
+          await coll.replaceOne({ _id: doc._id }, doc, _opts(session, { upsert: true }));
         }
         return { insertedCount: cmd.docs.length };
       }
-      await coll.insertMany(cmd.docs);
+      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':
       _normFilter(cmd);
-      return coll.findOneAndUpdate(cmd.filter, cmd.update, cmd.options);
+      return coll.findOneAndUpdate(cmd.filter, cmd.update, _opts(session, cmd.options));
     case 'updateMany':
       _normFilter(cmd);
-      return coll.updateMany(cmd.filter, cmd.update);
+      return coll.updateMany(cmd.filter, cmd.update, _opts(session));
     case 'deleteMany':
       _normFilter(cmd);
-      return coll.deleteMany(cmd.filter);
+      return coll.deleteMany(cmd.filter, _opts(session));
     default:
       throw new Error(`未支持的命令: ${cmd.kind}`);
   }
 }
 
-module.exports = { execMongo };
+module.exports = { execMongo, openTransaction };

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,37 +38,75 @@ 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 };
+  }
+
+  /**
+   * 显式事务句柄：池 checkout 专用连接（失败直接上抛，无静默兜底）
+   * + beginTransaction + 幂等 commit/rollback；release 归还连接（单连接为 no-op）。
+   */
+  async function openTransaction() {
+    const { openAcquire } = require('./index'); // 延迟导入：避免与 index 的循环依赖
+    const { conn, release } = await openAcquire(driver);
+    await conn.beginTransaction();
+    let closed = false;
+    return {
+      exec: (plan) => runStmts(conn, plan),
+      async savepoint(name) {
+        /* 保存点（嵌套事务用）；name 由 Host 生成（sp_<n>），非用户输入。
+           MySQL 预备语句协议不支持 SAVEPOINT → 必须走 conn.query */
+        await conn.query(`SAVEPOINT ${name}`);
+      },
+      async releaseSavepoint(name) {
+        await conn.query(`RELEASE SAVEPOINT ${name}`);
+      },
+      async rollbackToSavepoint(name) {
+        await conn.query(`ROLLBACK TO SAVEPOINT ${name}`);
+      },
+      async commit() {
+        if (closed) return;
+        closed = true;
+        await conn.commit();
+      },
+      async rollback() {
+        if (closed) return;
+        closed = true;
+        await conn.rollback();
+      },
+      release,
+    };
+  }
+
+  /** 事务执行：基于 openTransaction（无第二套事务路径），任一失败整体回滚；
+   *  body(exec, tx) 第二参数为事务句柄（供上层读保存点原语），可选——旧单参写法继续可用 */
+  async function withTransaction(body) {
+    const tx = await openTransaction();
+    try {
+      const out = await body(tx.exec, tx);
+      await tx.commit();
+      return out;
+    } catch (e) {
+      try {
+        await tx.rollback();
+      } catch (_) {
+        /* rollback 失败不掩盖原始错误 */
+      }
+      throw e;
+    } finally {
+      await tx.release();
+    }
   }
 
   return {
     kind: 'mysql',
     exec: (plan) => runStmts(driver, plan),
-    /**
-     * 事务执行：body(executeOnTx) 的所有 plan 落在同一连接同一事务内，
-     * 成功 commit / 失败 rollback。池自动取专用连接（结束归还）。
-     */
-    async withTransaction(body) {
-      const conn =
-        typeof driver.getConnection === 'function' ? await driver.getConnection() : driver;
-      try {
-        await conn.beginTransaction();
-        const out = await body((plan) => runStmts(conn, plan));
-        await conn.commit();
-        return out;
-      } catch (e) {
-        try {
-          await conn.rollback();
-        } catch (_) {
-          /* rollback 失败不掩盖原始错误 */
-        }
-        throw e;
-      } finally {
-        if (conn !== driver && typeof conn.release === 'function') conn.release();
-      }
-    },
+    withTransaction,
+    openTransaction,
   };
 }
 

package/src/executors/postgres.js

@@ -32,44 +32,66 @@ function create(driver, _options = {}) {
     return { docs, rows, affectedRows };
   }
 
+  /**
+   * 显式事务句柄：池 checkout 专用 client（失败直接上抛，无静默兜底）
+   * + BEGIN + 幂等 commit/rollback；release 归还连接（单连接为 no-op）。
+   */
+  async function openTransaction() {
+    const { openAcquire } = require('./index'); // 延迟导入：避免与 index 的循环依赖
+    const { conn, release } = await openAcquire(driver);
+    await conn.query('BEGIN');
+    let closed = false;
+    return {
+      exec: (plan) => runStmts(conn, plan),
+      async savepoint(name) {
+        /* 保存点（嵌套事务用）；name 由 Host 生成（sp_<n>），非用户输入 */
+        await conn.query(`SAVEPOINT ${name}`);
+      },
+      async releaseSavepoint(name) {
+        await conn.query(`RELEASE SAVEPOINT ${name}`);
+      },
+      async rollbackToSavepoint(name) {
+        await conn.query(`ROLLBACK TO SAVEPOINT ${name}`);
+      },
+      async commit() {
+        if (closed) return;
+        closed = true;
+        await conn.query('COMMIT');
+      },
+      async rollback() {
+        if (closed) return;
+        closed = true;
+        await conn.query('ROLLBACK');
+      },
+      release,
+    };
+  }
+
+  /** 事务执行：基于 openTransaction（无第二套事务路径），任一失败整体回滚；
+   *  body(exec, tx) 第二参数为事务句柄（供上层读保存点原语），可选——旧单参写法继续可用 */
+  async function withTransaction(body) {
+    const tx = await openTransaction();
+    try {
+      const out = await body(tx.exec, tx);
+      await tx.commit();
+      return out;
+    } catch (e) {
+      try {
+        await tx.rollback();
+      } catch (_) {
+        /* rollback 失败不掩盖原始错误 */
+      }
+      throw e;
+    } finally {
+      await tx.release();
+    }
+  }
+
   return {
     kind: 'postgres',
     exec: (plan) => runStmts(driver, plan),
-    /**
-     * 事务执行：显式 BEGIN/COMMIT/ROLLBACK 包住 body 的全部 plan。
-     * Pool 自动 checkout 专用 client（`release()` 归还）；Client 直连直接用。
-     */
-    async withTransaction(body) {
-      let conn = driver;
-      let release = null;
-      if (typeof driver.connect === 'function') {
-        try {
-          const c = await driver.connect();
-          // Pool.connect() → 专用 Client（带 release）；Client.connect() → 自身
-          if (c && typeof c.query === 'function') {
-            conn = c;
-            if (c !== driver && typeof c.release === 'function') release = () => c.release();
-          }
-        } catch (_) {
-          /* checkout 失败退回 driver 本体，事务语义由 BEGIN/COMMIT 保证 */
-        }
-      }
-      try {
-        await conn.query('BEGIN');
-        const out = await body((plan) => runStmts(conn, plan));
-        await conn.query('COMMIT');
-        return out;
-      } catch (e) {
-        try {
-          await conn.query('ROLLBACK');
-        } catch (_) {
-          /* rollback 失败不掩盖原始错误 */
-        }
-        throw e;
-      } finally {
-        if (release) release();
-      }
-    },
+    withTransaction,
+    openTransaction,
   };
 }
 

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,32 +44,67 @@ 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 };
   }
 
-  return {
-    kind: 'sqlite',
-    exec: runStmts,
-    /** 事务执行：显式 BEGIN/COMMIT/ROLLBACK（better-sqlite3 默认 autocommit，显式开事务安全） */
-    async withTransaction(body) {
-      db.exec('BEGIN');
-      try {
-        const out = await body(runStmts);
+  /** 显式事务句柄：BEGIN + 幂等 commit/rollback；release 为 no-op（单连接不归还） */
+  async function openTransaction() {
+    db.exec('BEGIN');
+    let closed = false;
+    return {
+      exec: runStmts,
+      async savepoint(name) {
+        /* 保存点（嵌套事务用）；name 由 Host 生成（sp_<n>），非用户输入 */
+        db.exec(`SAVEPOINT ${name}`);
+      },
+      async releaseSavepoint(name) {
+        db.exec(`RELEASE SAVEPOINT ${name}`);
+      },
+      async rollbackToSavepoint(name) {
+        db.exec(`ROLLBACK TO SAVEPOINT ${name}`);
+      },
+      async commit() {
+        if (closed) return;
+        closed = true;
         db.exec('COMMIT');
-        return out;
-      } catch (e) {
-        try {
-          db.exec('ROLLBACK');
-        } catch (_) {
-          /* rollback 失败不掩盖原始错误 */
-        }
-        throw e;
+      },
+      async rollback() {
+        if (closed) return;
+        closed = true;
+        db.exec('ROLLBACK');
+      },
+      async release() {},
+    };
+  }
+
+  /** 事务执行：基于 openTransaction（无第二套事务路径），任一失败整体回滚；
+   *  body(exec, tx) 第二参数为事务句柄（供上层读保存点原语），可选——旧单参写法继续可用 */
+  async function withTransaction(body) {
+    const tx = await openTransaction();
+    try {
+      const out = await body(tx.exec, tx);
+      await tx.commit();
+      return out;
+    } catch (e) {
+      try {
+        await tx.rollback();
+      } catch (_) {
+        /* rollback 失败不掩盖原始错误 */
       }
-    },
-  };
+      throw e;
+    } finally {
+      await tx.release();
+    }
+  }
+
+  return { kind: 'sqlite', exec: runStmts, withTransaction, openTransaction };
 }
 
 module.exports = { create };