nodejs-store 2.5.0 → 2.7.0

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,221 @@ 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');
+}
+
+// ══════════════════════════════════════════════════════════════════
+// 声明式 schema 迁移（阶段 4；设计见 common-store/迁移设计文档-阶段4.md）
+// 与 py_store/ddl.py 的 migration 段逐字节对齐（parity 锚：tests/migration.test.js）。
+// ══════════════════════════════════════════════════════════════════
+
+/** 类型放宽映射（首批）：值域安全扩大的单向变更；跨大类不在映射内 → Err */
+const WIDEN = {
+  int: ['long', 'float', 'double'],
+  long: ['float', 'double'],
+  float: ['double'],
+};
+
+/** 字段 def → 列 SQL 类型（与 columns 同源；object/array → JSON 文本列） */
+function fieldSqlType(backend, fdef) {
+  const i = idx(backend);
+  const ftype = declaredType(fdef);
+  if (NON_COLUMN.includes(ftype)) return JSON_TYPE[i];
+  if (!Object.prototype.hasOwnProperty.call(TYPES, ftype)) {
+    throw new Error(
+      `迁移生成：字段类型 ${JSON.stringify(ftype)} 未知（支持 ${Object.keys(TYPES).sort()}）`);
+  }
+  return TYPES[ftype][i];
+}
+
+/** default 字面量 → SQL 文本（仅 JSON 标量；SQLite 禁非常量表达式 DEFAULT） */
+function sqlLiteral(v) {
+  if (typeof v === 'boolean') return v ? 'TRUE' : 'FALSE';
+  if (typeof v === 'number') return String(v);
+  if (typeof v === 'string') return `'${v.replace(/'/g, "''")}'`;
+  throw new Error(`迁移生成：default 仅支持 JSON 标量字面量，收到 ${typeof v}`);
+}
+
+/** 主 def → 归档表 def（列 = 主列 + deletedAt；剔除 _id 自增策略；indexes 继承） */
+function archiveDefnOf(defn) {
+  const fields = { ...(defn.fields || {}) };
+  fields.deletedAt = { type: 'number' };
+  if (fields._id && typeof fields._id === 'object') {
+    const { strategy, ...rest } = fields._id;
+    fields._id = rest;
+  }
+  return {
+    ...defn,
+    name: `${defn.name}Deleted`,
+    collection: `${defn.collection || defn.name}_deleted`,
+    fields,
+    timestamps: false,
+    _isArchive: true,
+  };
+}
+
+/** 新旧 schema def 对比 → { changes, errors }（后端无关，纯函数；白名单外记入 errors） */
+function diffDefs(oldDefn, newDefn) {
+  const changes = [];
+  const errors = [];
+  const oldFields = (oldDefn && oldDefn.fields) || {};
+  const newFields = newDefn.fields || {};
+
+  if (oldDefn === null || oldDefn === undefined) {
+    return { changes: [{ op: 'addTable', defn: newDefn }], errors };
+  }
+
+  for (const [name, nf] of Object.entries(newFields)) {
+    if (name === '_id') {
+      const of = oldFields._id;
+      if (of !== undefined && declaredType(of) !== declaredType(nf)) {
+        errors.push(`_id 主键类型变更不支持（${declaredType(of)} → ${declaredType(nf)}）`);
+      }
+      const oStrat = of && typeof of === 'object' ? of.strategy : undefined;
+      const nStrat = nf && typeof nf === 'object' ? nf.strategy : undefined;
+      if (oStrat !== nStrat) {
+        errors.push(`_id 主键策略变更不支持（${JSON.stringify(oStrat)} → ${JSON.stringify(nStrat)}）`);
+      }
+      continue;
+    }
+    const nfType = declaredType(nf);
+    if (!(name in oldFields)) {
+      if (!Object.prototype.hasOwnProperty.call(TYPES, nfType) && !NON_COLUMN.includes(nfType)) {
+        errors.push(`新列 "${name}" 类型 ${JSON.stringify(nfType)} 未知`);
+        continue;
+      }
+      changes.push({
+        op: 'addColumn', name,
+        field: nf && typeof nf === 'object' ? nf : { type: nf },
+      });
+      continue;
+    }
+    const of = oldFields[name];
+    const ofType = declaredType(of);
+    if (ofType === nfType) continue; // 恒等：不上报
+    if (nfType && (WIDEN[ofType] || []).includes(nfType)) {
+      changes.push({ op: 'widenColumn', name, from: ofType, to: nfType });
+    } else {
+      errors.push(
+        `字段 "${name}" 类型 ${JSON.stringify(ofType)} → ${JSON.stringify(nfType)} 非放宽变更`
+        + '（首批仅支持单向放宽：int→long/float/double、long→float/double、float→double）');
+    }
+  }
+  for (const name of Object.keys(oldFields)) {
+    if (!(name in newFields)) {
+      errors.push(`删除字段 "${name}" 不支持（破坏性变更；请显式走数据迁移脚本）`);
+    }
+  }
+
+  const indexKeys = (defn) => (defn.indexes || [])
+    .filter((ix) => ix && typeof ix === 'object' && ix.keys
+      && typeof ix.keys === 'object' && Object.keys(ix.keys).length);
+  const oldIdx = indexKeys(oldDefn);
+  for (const ix of indexKeys(newDefn)) {
+    if (!oldIdx.some((o) => JSON.stringify(o) === JSON.stringify(ix))) {
+      changes.push({ op: 'addIndex', index: ix });
+    }
+  }
+
+  const oldColl = oldDefn.collection || oldDefn.name;
+  const newColl = newDefn.collection || newDefn.name;
+  if (oldColl !== newColl) {
+    errors.push(`collection 改名不支持（${JSON.stringify(oldColl)} → ${JSON.stringify(newColl)}；破坏性变更）`);
+  }
+  return { changes, errors };
+}
+
+/** 新旧 schema def → 迁移 SQL 文本列表（per-dialect；只产文本、不执行） */
+function generateMigration(backend, oldDefn, newDefn) {
+  if (!BACKENDS.includes(backend)) {
+    throw new Error(`迁移生成：不支持的后端 ${JSON.stringify(backend)}（支持 ${BACKENDS.join('/')}）`);
+  }
+  const plan = diffDefs(oldDefn, newDefn);
+  if (plan.errors.length) {
+    throw new Error(
+      'MIGRATION_UNSUPPORTED: ' + plan.errors.join('；')
+      + '（首批白名单：加表/加列/类型放宽/加索引；破坏性变更请走显式数据迁移脚本）');
+  }
+
+  const table = newDefn.collection || newDefn.name;
+  const stmts = [];
+  const order = { addColumn: 0, widenColumn: 1, addIndex: 2 };
+  for (const ch of [...plan.changes].sort((a, b) => (order[a.op] ?? 9) - (order[b.op] ?? 9))) {
+    if (ch.op === 'addTable') {
+      stmts.push(createTable(newDefn, backend));
+      stmts.push(...indexStmts(newDefn, backend));
+      const arch = archiveDefnOf(newDefn);
+      stmts.push(createTable(arch, backend));
+      stmts.push(...indexStmts(arch, backend));
+    } else if (ch.op === 'addColumn') {
+      const ftype = declaredType(ch.field);
+      const colType = fieldSqlType(backend, ch.field);
+      const deflt = ch.field && typeof ch.field === 'object' ? ch.field.default : undefined;
+      let colSql = `${q(backend, ch.name)} ${colType}`;
+      if (deflt !== undefined && deflt !== null) {
+        if (NON_COLUMN.includes(ftype)) {
+          throw new Error(
+            `MIGRATION_UNSUPPORTED: 新列 "${ch.name}"（object/array JSON 列）不支持 DEFAULT`
+            + '（存量行缺失语义由 __present 哨兵表达；default 仅影响新写入）');
+        }
+        colSql += ` DEFAULT ${sqlLiteral(deflt)}`;
+      }
+      stmts.push(`ALTER TABLE ${q(backend, table)} ADD COLUMN ${colSql}`);
+      stmts.push(`ALTER TABLE ${q(backend, `${table}_deleted`)} ADD COLUMN ${colSql}`);
+    } else if (ch.op === 'widenColumn') {
+      const colType = fieldSqlType(backend, newDefn.fields[ch.name]);
+      if (backend === 'sqlite') {
+        throw new Error(
+          'MIGRATION_UNSUPPORTED: SQLite 不支持类型变更 '
+          + `（${ch.from} → ${ch.to} 需重建表）；加列/加索引/加表已支持`);
+      }
+      if (backend === 'mysql') {
+        stmts.push(`ALTER TABLE ${q(backend, table)} MODIFY COLUMN ${q(backend, ch.name)} ${colType}`);
+      } else {
+        stmts.push(
+          `ALTER TABLE ${q(backend, table)} ALTER COLUMN ${q(backend, ch.name)} `
+          + `TYPE ${colType} USING ${q(backend, ch.name)}::${colType}`);
+      }
+    } else if (ch.op === 'addIndex') {
+      stmts.push(...indexStmts({ collection: table, indexes: [ch.index] }, backend));
+    } else {
+      throw new Error(`MIGRATION_UNSUPPORTED: 未知变更 ${ch.op}`);
+    }
+  }
+  return stmts;
 }
 
-module.exports = { generate };
+module.exports = { generate, diffDefs, generateMigration };

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（单连接不归还） */

package/src/feedback.js

@@ -23,6 +23,11 @@ function setSink(fn) {
   _sink = typeof fn === 'function' ? fn : null;
 }
 
+/** 当前 sink（无则 null）——供接管方（如 ask 编排器）保存/恢复现场 */
+function getSink() {
+  return _sink;
+}
+
 /** 产出一条反馈事件：有 sink 回调之；否则打印 stderr（允许拦截，禁止静默） */
 function emit(event) {
   const e = event || {};
@@ -36,4 +41,4 @@ function emit(event) {
   );
 }
 
-module.exports = { setSink, emit };
+module.exports = { setSink, getSink, emit };