@sema-agent/server 7.43.0 → 7.44.0

package/dist/plugins/adoption-log-sql.js

@@ -1,21 +1,13 @@
 import { createHash } from "node:crypto";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
 export const ADOPTION_LOG_TABLE = "adoption_log";
-/** 弧的阶段(183 §3.2 根级状态机的 form b 投影)。**单调**,只增不减。 */
 export const ADOPTION_PHASE = {
-    /** ② 意图已落库(行在,尚未动任何数据行)。 */
     INTENT: 2,
-    /** ③ 身份轴重绑腿全部完成(与腿的 UPDATE **同一个事务**)。 */
     REBOUND: 3,
-    /** ④ 解析切换 / 配置清单产出。form b 的 server 半场:配置账已物化进 `configs`。 */
     CONFIGS: 4,
-    /** ⑤ 承运腿。**form b 恒零承运**(数据本来就在 SQL)—— 阶段位仍显式推进,好让 form a 上车时挂得上。 */
     CARRIED: 5,
-    /** ⑥ 永久终态。 */
     TERMINAL: 6,
 };
-/** MySQL 协议方言的建表语句(展开进 tidb-pool 的中央 `SCHEMA_STATEMENTS`,与 approval-ask 同姿势:
- *  跟着中央 ensureSchema 在 named-lock 的那条 conn 上建,不绕开 DDL 串行化)。 */
 export const TIDB_ADOPTION_LOG_STATEMENTS = [
     `CREATE TABLE IF NOT EXISTS ${ADOPTION_LOG_TABLE} (
      adoption_id    VARCHAR(64)  NOT NULL,
@@ -38,7 +30,6 @@ export const TIDB_ADOPTION_LOG_STATEMENTS = [
      KEY idx_adoption_log_state (state)
    ) COLLATE utf8mb4_bin`,
 ];
-/** PostgreSQL 孪生(由 `ensurePgSchema` 在 advisory lock 的那条 client 上调用)。 */
 export async function ensurePgAdoptionLogSchema(q) {
     await q(`CREATE TABLE IF NOT EXISTS ${ADOPTION_LOG_TABLE} (
      adoption_id    VARCHAR(64) COLLATE "C"  NOT NULL,
@@ -76,54 +67,16 @@ function toRow(r) {
         updatedAtMs: Number(r.updated_at_ms),
     };
 }
-/** PG advisory lock 的 32 位对象键(类键固定,对象键 = 名字的 sha256 前 4 字节转有符号 int4)。 */
 const PG_ADOPTION_LOCK_CLASS = 4907;
 function pgLockObjectKey(name) {
     return createHash("sha256").update(name).digest().readInt32BE(0);
 }
-/**
- * 弧锁的名字。**定长**(前缀 14 + 32 位十六进制 = 46 字符)。
- *
- * 🔴 为什么必须 hash 而不是把 principal 直接拼进去(codex R3-F3,亲核属实):TiDB/MySQL 的 `GET_LOCK`
- * 锁名上限是 **64 字符**,而请求面收的 principal 到 190 —— 超过 50 字符的源身份会让取锁**在弧动起来
- * 之前**就失败,而那时意图行已经落库,于是每一次重发、每一次副本 boot 续跑都确定性地再撞一次同一堵墙。
- * (PG 那条腿本来就走 hash 出来的 int4 对象键,这里只是把 MySQL 腿补齐到同一姿势。)
- */
 export function adoptionLockName(fromPrincipal) {
     return `sema_adoption:${createHash("sha256").update(fromPrincipal).digest("hex").slice(0, 32)}`;
 }
-/**
- * 把弧锁名限定到**一个库**的键空间(A-010.13,验真后修)。
- *
- * 🔴 病:两条腿的锁键空间**不等价**。MySQL/TiDB 的 `GET_LOCK` 名字是**服务器实例全局**的
- * (`performance_schema.metadata_locks` 里就是一个进程级命名空间,与你连的是哪个 schema 无关);
- * PG 的 advisory lock 是**每数据库**的(`pg_locks` 的 database 列参与身份)。而锁名此前只 hash 了
- * `fromPrincipal`、前缀写死 `sema_adoption:` —— 于是同一台 MySQL 上并存的两套部署
- * (`aiagent_prod` / `aiagent_staging`,同一个源身份)会**互相抢同一把锁**:一边正在跑弧,另一边
- * 取不到锁、按「在飞」回一份 `stalled` 回执 —— 一个与它自己的库状态完全对不上的答复。切到 PG 同样
- * 两套部署却各跑各的。同一份代码、同一份配置,两个后端上语义不同 = 方言不等价。
- *
- * 🔴 姿势:限定符 = **当前数据库名**(MySQL `DATABASE()` / PG `current_database()`),与 principal
- * 一起进 hash 原像。于是 MySQL 腿被收窄到与 PG 腿同一个键空间语义(每库一把),而不是把 PG 放宽到
- * 实例全局(放宽的那个方向会让**同库**的两副本以为各自持锁,那是真丢互斥,方向错得多)。
- *
- * 🔴 为什么仍然 hash 而不是 `${db}/${name}` 直接拼:`GET_LOCK` 的名字上限是 **64 字符**,而库名没有
- * 本仓能保证的上限。拼接形会让一个长库名的部署在**取锁那一步**才失败,而那时意图行已经落库 ——
- * 每一次重发、每一次 boot 续跑都确定性地再撞一次同一堵墙(与 `adoptionLockName` 自己头注里那条
- * codex R3-F3 是同一个病)。hash 后定长 46 字符,与库名长度无关。
- * 分隔符取 **NUL**(源码里写成转义 `\u0000`,不落裸控制字节 —— 那会让 grep 把整个文件当二进制):
- * 库名可以含 `/`、空格这类字符(MySQL 反引号标识符 / PG 双引号标识符都允许),拿它们当分隔符时
- * `(db="a", name="b/c")` 与 `(db="a/b", name="c")` 会铸出**同一个原像** —— 弱分隔符拼接的经典撞形。
- * NUL 在两种引擎的标识符里都不合法,所以它是真的不可能出现在任何一段里。
- */
 export function qualifyAdoptionLockName(database, name) {
     return `sema_adoption:${createHash("sha256").update(`${database}\u0000${name}`, "utf8").digest("hex").slice(0, 32)}`;
 }
-/**
- * 收编日志店(单文件双方言,SqlDriver 形——checkpoint-store / approval-ask-store 同款)。
- *
- * 每条语句的两方言文本**并排写在调用点**(A12 判据:方言差异必须显式,不许用占位符编号循环拼)。
- */
 export class SqlAdoptionLogStore {
     db;
     constructor(db) {
@@ -132,15 +85,9 @@ export class SqlAdoptionLogStore {
     q(tidb, pg) {
         return this.db.dialect === "tidb" ? tidb : pg;
     }
-    /** 池级只读执行面(phase 0 的 preflight 扫描用——它**零写**,不需要也不该占一条事务连接)。
-     *  写路径一律走 {@link rebindTransaction};把驱动整个暴露出去会让调用方能绕开 phase CAS。 */
     get reader() {
         return this.db;
     }
-    /**
-     * 发起腿的 **insert-or-fetch 原子形**。返回读回的行(可能是别人插的)+ 是否本次插入。
-     * 调用方据 `row.toPrincipal !== toPrincipal` 判「同 from 异 to」⇒ typed 409。
-     */
     async ensureAdoption(row) {
         const emptyLegs = "[]";
         const res = await this.db.query(this.q(`INSERT IGNORE INTO ${ADOPTION_LOG_TABLE} (${COLS}) VALUES (?, ?, ?, ?, 'in_flight', ?, ?, NULL, NULL, NULL, ?, ?)`, `INSERT INTO ${ADOPTION_LOG_TABLE} (${COLS}) VALUES ($1, $2, $3, $4, 'in_flight', $5, $6, NULL, NULL, NULL, $7, $8) ON CONFLICT (from_principal) DO NOTHING`), [row.adoptionId, row.fromPrincipal, row.toPrincipal, ADOPTION_PHASE.INTENT, emptyLegs, emptyLegs, row.nowMs, row.nowMs]);
@@ -158,29 +105,15 @@ export class SqlAdoptionLogStore {
         const res = await exec.query(this.q(`SELECT ${COLS} FROM ${ADOPTION_LOG_TABLE} WHERE from_principal = ?`, `SELECT ${COLS} FROM ${ADOPTION_LOG_TABLE} WHERE from_principal = $1`), [fromPrincipal]);
         return res.rows[0] ? toRow(res.rows[0]) : null;
     }
-    /** I6 server 同族:每副本 boot 必查的在飞名单(**响亮**,不静默跳过)。 */
     async listInFlight(exec = this.db) {
         const res = await exec.query(this.q(`SELECT ${COLS} FROM ${ADOPTION_LOG_TABLE} WHERE state = 'in_flight' ORDER BY created_at_ms ASC`, `SELECT ${COLS} FROM ${ADOPTION_LOG_TABLE} WHERE state = 'in_flight' ORDER BY created_at_ms ASC`), []);
         return res.rows.map(toRow);
     }
-    /**
-     * 迁移事务:腿的全部 UPDATE **与** phase CAS 落在**同一个事务**里。
-     *
-     * 🔴 为什么必须同事务(而不是「先迁完再推 phase」):两句分开就留下一个窗 —— 腿提交了、phase 没推,
-     * 崩溃后接棒副本重跑腿(幂等,零行变化)却把**首次的行数读数**丢了,回执里的 `legs` 会变成一串 0。
-     * 同事务之后这个窗根本不存在:要么「行迁了且 phase=3 且 legs 读数在」,要么什么都没发生。
-     * 任何异常(含唯一键违例 = 跨轴组合冲突)⇒ ROLLBACK ⇒ **源/目的地两侧字节零变更**。
-     */
     async rebindOn(conn, adoptionId, expectPhase, nextPhase, nowMs, work, encodeLegs) {
         try {
             await conn.begin();
             const legs = await work(conn);
-            const cas = await conn.query(
-            // 🔴 谓词里必须带 `state = 'in_flight'`(codex R2-F1..F3 的 F3):被拒的行**故意**停在 phase INTENT
-            // (「两侧字节零变更」要求它一步都别走),所以只判 phase 的 CAS 对一条已 rejected 的行是**满足**的
-            // —— 一个在锁上排队的过期调用方于是能把一条永久拒了的弧推去迁数据。终态永久性是库级不变量,
-            // 这道守卫就该在库里,不在调用方的 if 里。
-            this.q(`UPDATE ${ADOPTION_LOG_TABLE} SET phase = ?, legs = ?, updated_at_ms = ? WHERE adoption_id = ? AND phase = ? AND state = 'in_flight'`, `UPDATE ${ADOPTION_LOG_TABLE} SET phase = $1, legs = $2, updated_at_ms = $3 WHERE adoption_id = $4 AND phase = $5 AND state = 'in_flight'`), [nextPhase, encodeLegs(legs), nowMs, adoptionId, expectPhase]);
+            const cas = await conn.query(this.q(`UPDATE ${ADOPTION_LOG_TABLE} SET phase = ?, legs = ?, updated_at_ms = ? WHERE adoption_id = ? AND phase = ? AND state = 'in_flight'`, `UPDATE ${ADOPTION_LOG_TABLE} SET phase = $1, legs = $2, updated_at_ms = $3 WHERE adoption_id = $4 AND phase = $5 AND state = 'in_flight'`), [nextPhase, encodeLegs(legs), nowMs, adoptionId, expectPhase]);
             if (cas.affected !== 1) {
                 await conn.rollback();
                 return { ok: false, reason: "phase_moved" };
@@ -193,20 +126,11 @@ export class SqlAdoptionLogStore {
                 await conn.rollback();
             }
             catch (rollbackErr) {
-                // 🔴 不空吞(#191 静默降级门):回滚本身失败通常意味着连接已经废了,原始异常才是要上抛的那个,
-                // 但「回滚没成功」是运维必须看见的事 —— 它决定了库里可能留着一段未提交/已废弃的事务状态。
                 console.warn("[adoption-log] rollback after a failed rebind transaction also failed:", rollbackErr);
             }
             throw err;
         }
     }
-    /**
-     * 终态**之后**的迟到行清扫事务(无 phase 变更 —— phase 已经是终态,而终态是永久的)。
-     *
-     * 🔴 它不是「再收编一次」:腿本身幂等,清扫只是把收编**结束后**又落到旧身份下的行(配置未随迁的
-     * 部署会持续制造它们)一并搬过去,并让 `current.residualSourceRows` 有个能归零的动作。
-     * `immutableReport` 一个字节都不动(史实与现势分家,183 §6)。
-     */
     async sweepOn(conn, work) {
         try {
             await conn.begin();
@@ -219,52 +143,29 @@ export class SqlAdoptionLogStore {
                 await conn.rollback();
             }
             catch (rollbackErr) {
-                console.warn("[adoption-log] rollback after a failed sweep transaction also failed:", rollbackErr); // 同上:不空吞
+                console.warn("[adoption-log] rollback after a failed sweep transaction also failed:", rollbackErr);
             }
             throw err;
         }
     }
-    /** 单调 CAS 推进(无数据写的阶段;`false` = 别人已经推过了/相位不符 ⇒ 调用方重读行)。 */
     async advancePhase(adoptionId, expectPhase, nextPhase, nowMs, exec = this.db) {
         const res = await exec.query(this.q(`UPDATE ${ADOPTION_LOG_TABLE} SET phase = ?, updated_at_ms = ? WHERE adoption_id = ? AND phase = ?`, `UPDATE ${ADOPTION_LOG_TABLE} SET phase = $1, updated_at_ms = $2 WHERE adoption_id = $3 AND phase = $4`), [nextPhase, nowMs, adoptionId, expectPhase]);
         return res.affected === 1;
     }
-    /** phase 4:配置账物化(与 phase 推进同一条语句,免得账落了相位没推)。 */
     async putConfigs(adoptionId, expectPhase, nextPhase, configsJson, nowMs, exec = this.db) {
         const res = await exec.query(this.q(`UPDATE ${ADOPTION_LOG_TABLE} SET phase = ?, configs = ?, updated_at_ms = ? WHERE adoption_id = ? AND phase = ?`, `UPDATE ${ADOPTION_LOG_TABLE} SET phase = $1, configs = $2, updated_at_ms = $3 WHERE adoption_id = $4 AND phase = $5`), [nextPhase, configsJson, nowMs, adoptionId, expectPhase]);
         return res.affected === 1;
     }
-    /**
-     * ⑥ 终态:`report` 一次写入,`state='adopted'`。
-     * 🔴 `AND report IS NULL` 是 I4(永久终态 + 不可变史实)的**数据库强形**:即使调用序漂了,快照也
-     * 不可能被第二次写盖掉 —— 「逐字节恒同」于是不依赖调用方自觉。
-     */
     async finalizeAdopted(adoptionId, expectPhase, reportJson, nowMs, exec = this.db) {
         const res = await exec.query(this.q(`UPDATE ${ADOPTION_LOG_TABLE} SET phase = ?, state = 'adopted', report = ?, updated_at_ms = ? WHERE adoption_id = ? AND phase = ? AND report IS NULL`, `UPDATE ${ADOPTION_LOG_TABLE} SET phase = $1, state = 'adopted', report = $2, updated_at_ms = $3 WHERE adoption_id = $4 AND phase = $5 AND report IS NULL`), [ADOPTION_PHASE.TERMINAL, reportJson, nowMs, adoptionId, expectPhase]);
         return res.affected === 1;
     }
-    /** 目的地冲突 ⇒ rejected 终态(源/目的地两侧字节零变更;phase 停在 INTENT)。 */
     async finalizeRejected(adoptionId, code, detail, nowMs, exec = this.db) {
         const res = await exec.query(this.q(`UPDATE ${ADOPTION_LOG_TABLE} SET state = 'rejected', reject_code = ?, reject_detail = ?, updated_at_ms = ? WHERE adoption_id = ? AND state = 'in_flight'`, `UPDATE ${ADOPTION_LOG_TABLE} SET state = 'rejected', reject_code = $1, reject_detail = $2, updated_at_ms = $3 WHERE adoption_id = $4 AND state = 'in_flight'`), [code, detail, nowMs, adoptionId]);
         return res.affected === 1;
     }
-    /**
-     * 本连接所在**数据库**的名字 = 弧锁的键空间限定符(A-010.13,理由见 {@link qualifyAdoptionLockName})。
-     *
-     * 在**交出来的那条连接**上问(不向池要第二条 —— 弧全程单连接,见 `AdoptionLogStore.getById` 的注),
-     * 结果缓存在店上:库名在一条驱动的生命周期里不会变,而每次取锁多打一个往返是白付的。
-     *
-     * 读不出来 ⇒ **响亮抛**,不回落到未限定的旧名字:那正是本条要消灭的形,静默回落等于「修了个寂寞」
-     * 且只在多部署共库的那台机器上才发作(安全轴禁静默 fail-open 的同族判据)。
-     */
     lockKeyspace;
     resolveLockKeyspace(conn) {
-        // 🔴 缓存的是**这一次尝试**,而失败的那一次必须从缓存里消失(codex 对抗复审 R1 [medium],验真后修)。
-        // 病:`??=` 把 promise 本身钉住,于是**一次瞬时**的 `SELECT DATABASE()` 失败(连接抖动、库短暂不可
-        // 达)会被永久缓存 —— 此后每一条弧都复用那个已拒的 promise、连库都不再问一次。而意图行是在取锁
-        // **之前**就落库的,所以首条弧永远停在 in_flight、每次 boot 续跑再撞同一堵墙,整台副本的收编面
-        // 直到重启为止都是死的。一次抖动升级成一次停机,方向完全反了。
-        // 修:只有**解析成功**的读数留在缓存里;拒绝时清掉,下一次真的重问。
         const attempt = (this.lockKeyspace ??= (async () => {
             const res = await conn.query(this.q("SELECT DATABASE() AS db", "SELECT current_database() AS db"));
             const db = res.rows[0]?.db;
@@ -273,29 +174,15 @@ export class SqlAdoptionLogStore {
             }
             return db;
         })());
-        // 清缓存要**认准这一次**(`=== attempt`):否则一次迟到的失败会把别人刚缓存好的成功读数抹掉。
         return attempt.catch((err) => {
             if (this.lockKeyspace === attempt)
                 this.lockKeyspace = undefined;
             throw err;
         });
     }
-    /**
-     * 收编弧的 advisory 锁(183 I1 的 form b 形:「与任何活写互斥」在 SQL 侧 = 一次只有一个副本在推这条弧)。
-     *
-     * **非阻塞取 + 有界轮询**(tidb-pool 的 `acquireEnsureSchemaLock` 同款判据:阻塞式 GET_LOCK 会把并发
-     * 调用方全部park 在 TiDB 的悲观锁行上,既耗它的重试预算又饿死应用自己的 FOR UPDATE 路)。取不到 ⇒
-     * 返回 `undefined`,调用方按「在飞」应答 —— **不假装成功,也不无限等**。
-     *
-     * 🔴 入参 `name` 是**逻辑**锁名(`adoptionLockName(fromPrincipal)`);真正发给引擎的是它被
-     * {@link qualifyAdoptionLockName} 限定到本库之后的形(A-010.13:两方言键空间不等价)。限定发生在
-     * **这里**而不是调用方,因为「键空间是每库还是每实例」是**存储层**的知识,协议层(runner)不该知道。
-     */
     async withLock(name, fn, attempts = 20, sleepMs = 100) {
         const conn = await this.db.connect();
         let held = false;
-        // 🔴 在 try **之外**声明:释放腿(finally)必须用**取锁时用过的那一个**名字。第一版把它 const 在
-        // try 里,于是 finally 只能回头用未限定的 `name` —— 取的是 A、放的是 B,锁会一直持到连接回收。
         let lockName = "";
         try {
             lockName = qualifyAdoptionLockName(await this.resolveLockKeyspace(conn), name);
@@ -308,8 +195,6 @@ export class SqlAdoptionLogStore {
             }
             if (!held)
                 return undefined;
-            // 🔴 把**这一条**连接交出去:整条弧(读 / 事务 / CAS)都跑在它上面,弧内绝不再向池要第二条
-            // ——`connectionLimit=1` 的部署上那第二条永远等不到(codex R3-F2)。
             return await fn(conn);
         }
         finally {
@@ -318,8 +203,6 @@ export class SqlAdoptionLogStore {
                     await conn.query(this.q("SELECT RELEASE_LOCK(?) AS released", "SELECT pg_advisory_unlock($1, $2) AS released"), this.db.dialect === "tidb" ? [lockName] : [PG_ADOPTION_LOCK_CLASS, pgLockObjectKey(lockName)]);
                 }
                 catch (releaseErr) {
-                    // 锁在连接关闭时会自动释放,所以释放失败不该盖掉真正的结果 —— 但同样不空吞:
-                    // 释放失败意味着这把弧锁会一直持到连接回收,下一个副本要多等一会儿,那是要能看见的。
                     console.warn("[adoption-log] releasing the adoption arc lock failed (it auto-frees when the connection closes):", releaseErr);
                 }
             }

package/dist/plugins/approval-ask-store-memory.js

@@ -1,19 +1,5 @@
-/**
- * `InMemoryApprovalAskStore` —— #151 车1,`ApprovalAskStore` 的语义真源(twin 对拆基准)+ LOCAL
- * 车道占位(File 形不在本车,见设计定稿 §7)。单进程内两个 `Map`,方法体全同步(不含 `await` 中断点)——
- * Node 单线程下这就是天然原子:`Promise.all` 发起的并发调用不会在方法体内部交错执行,与
- * `approval-ask-store-sql.ts` 的 CAS UPDATE 语义逐字段一致(SQL twin 对拆套件的基准就是这份实现）。
- *
- * 行为口径与 `SqlApprovalAskStore` 逐条对齐:
- *  - ensureAsk 幂等 upsert(ask_id 已在 ⇒ 返回既有行,不改写;batch 行若不存在则以 OPEN 补齐）。
- *  - transitionAsk 先过 machine 层 `canAskTransition`(非法转移 throw，不返回 false）。
- *  - decideAsk/expireAsk/bindBatch/abortBatch 的双/三步判定顺序与 SQL twin 的事务步骤一一对应
- *    (哪一步先判、判什么、失败时是否触碰另一半状态——照抄，不是「反正内存里原子就随便」）。
- *  - resolveProvisional 故意不经 canAskTransition(同 SQL twin 头注：这是版本化补偿的例外通道）。
- */
 import { canAskTransition } from "../approval-ask-machine.js";
 import { assertIdempotencyKeyShape, ApprovalAskReadAbortedError } from "./approval-ask-store-sql.js";
-/** patch 里真出现的字段搬到行上(未出现的字段维持原值)——`transitionAsk`/`resolveProvisional` 共用。 */
 function applyPatch(row, patch) {
     if (patch.decision !== undefined)
         row.decision = patch.decision;
@@ -50,12 +36,8 @@ export class InMemoryApprovalAskStore {
             });
         }
         const existing = this.asks.get(row.askId);
-        // 幂等命中:行是**别人**插的 ⇒ `inserted: false`(收尾权限判别位,语义见 `EnsureAskResult` 顶注)。
         if (existing)
             return { row: { ...existing }, inserted: false };
-        // 🔴 车4 §12-E:`idempotency_key` 已归**回决专用**,`NewAskRow` 的同名字段随之摘除 ⇒ 铸行不再有
-        // 唯一性可撞(列恒 NULL)。原先在这里镜像 UNIQUE 的那段扫描也随之下车;撞键判定搬到 `decideAsk`
-        // (SQL twin 那侧是 `(task_id, idempotency_key)` 索引在库层拒 ⇒ typed `idempotency_conflict`)。
         const created = {
             askId: row.askId,
             taskId: row.taskId,
@@ -78,7 +60,7 @@ export class InMemoryApprovalAskStore {
             gateToken: null,
             gateBoundCallId: null,
             gateBoundInputHash: null,
-            idempotencyKey: null, // 回决专用列(见上注):铸行恒 NULL,decideAsk 才落。
+            idempotencyKey: null,
             cardJson: row.cardJson,
             schemaVersion: row.schemaVersion,
             expiresAtMs: row.expiresAtMs,
@@ -103,7 +85,7 @@ export class InMemoryApprovalAskStore {
     }
     async decideAsk(askId, batchId, decision) {
         if (decision.idempotencyKey != null)
-            assertIdempotencyKeyShape(decision.idempotencyKey); // F2 卫生门(三 twin 同判)
+            assertIdempotencyKeyShape(decision.idempotencyKey);
         const now = Date.now();
         const batch = this.batches.get(batchId);
         if (!batch || batch.state !== "OPEN") {
@@ -114,10 +96,6 @@ export class InMemoryApprovalAskStore {
         if (!ask || ask.state !== "STREAM_PENDING") {
             return { ok: false, reason: "ask_not_pending", row: ask ? { ...ask } : null };
         }
-        // 🔴 UNIQUE `(task_id, idempotency_key)` 的内存镜像(车4 §12-E)——SQL twin 靠索引在库层拒并把方言
-        // 错误翻成 typed 臂;这里必须同答,否则这个店就不是 SQL twin 的语义真源。判定顺序也照抄 SQL:
-        // 批 CAS(已过)→ ask CAS(已过)→ 才轮到撞键 ⇒ 一条非 STREAM_PENDING 的 ask 拿到的仍是
-        // `ask_not_pending` 而不是 `idempotency_conflict`(哪个先判决定了输者看到的 reason)。
         if (decision.idempotencyKey != null) {
             for (const [id, r] of this.asks) {
                 if (id !== askId && r.taskId === ask.taskId && r.idempotencyKey === decision.idempotencyKey) {
@@ -139,9 +117,6 @@ export class InMemoryApprovalAskStore {
     }
     async expireAsk(askId, batchId) {
         const now = Date.now();
-        // 批行存在性先判(镜像 SQL twin 死锁修后的步⓪,§6-4c 钉):批行缺席=ensureAsk 从未为它建批
-        // (错配 batchId 的编程错误形),如实不赢——不在半空中把 ask 铸成 PARKING(它真正的批还 OPEN,
-        // 状态会被污染)。批 state 不设谓词,与 SQL twin 一致(ROUTING_UNBOUND 兄弟先到属合法续走)。
         const batch = this.batches.get(batchId);
         if (!batch)
             return { won: false, voidedSiblings: [] };
@@ -170,15 +145,12 @@ export class InMemoryApprovalAskStore {
     async bindBatch(batchId, askId, gate) {
         const now = Date.now();
         const batch = this.batches.get(batchId);
-        // 判别式失败臂逐条对齐 SQL twin(见 `BindResult` 头注):批行缺席 = "MISSING";批态不对 ⇒ 回真实态
-        // (ABORTED / ROUTING_BOUND 两条处置完全相反,调用方靠它分臂)。
         if (!batch)
             return { ok: false, batchState: "MISSING" };
         if (batch.state !== "ROUTING_UNBOUND" || batch.boundAskId !== null) {
             return { ok: false, batchState: batch.state, ...(batch.boundAskId !== null ? { boundAskId: batch.boundAskId } : {}) };
         }
         const ask = this.asks.get(askId);
-        // ask 不在 PARKING ⇒ SQL twin 整事务回滚,批停在 ROUTING_UNBOUND;这里同样一个字节都还没改。
         if (!ask || ask.state !== "PARKING")
             return { ok: false, batchState: batch.state };
         batch.state = "ROUTING_BOUND";
@@ -203,7 +175,6 @@ export class InMemoryApprovalAskStore {
         return { ok: true, voidedSiblings };
     }
     async deferReconcile(askId, expectedState, expectedRev, nowMs) {
-        // 纯 touch,**不碰 state**,故意不经 canAskTransition(同态转移在转移表上无出边——见接口注)。
         const row = this.asks.get(askId);
         if (!row || row.state !== expectedState || row.rev !== expectedRev)
             return false;
@@ -231,15 +202,12 @@ export class InMemoryApprovalAskStore {
         return voided;
     }
     async listByState(state, limit) {
-        // 排序键与 SQL twin 逐字同形:`updated_at_ms ASC, created_at_ms ASC`(队列轮转,见 SQL 侧头注)。
         return [...this.asks.values()]
             .filter((r) => r.state === state)
             .sort((a, b) => a.updatedAtMs - b.updatedAtMs || a.createdAtMs - b.createdAtMs)
             .slice(0, limit)
             .map((r) => ({ ...r }));
     }
-    /** `signal` 的 twin 语义(车3 刀 3b):同步实现里没有「在飞」这回事,所以能做也只需做**入口复核** ——
-     *  已 abort 就一条都不读、如实抛,与 SQL twin 的第①条语义逐字一致(第②条在这里天然平凡成立)。 */
     async listPendingByTask(taskId, signal) {
         if (signal?.aborted === true)
             throw new ApprovalAskReadAbortedError("listPendingByTask");
@@ -251,7 +219,6 @@ export class InMemoryApprovalAskStore {
     async listPendingBySession(sessionId, owner, signal) {
         if (signal?.aborted === true)
             throw new ApprovalAskReadAbortedError("listPendingBySession");
-        // 租户门与 SQL twin 逐字同语义:`owner` 必填,`null` 只匹配 owner 为 null 的行(不是「不过滤」)。
         return [...this.asks.values()]
             .filter((r) => r.sessionId === sessionId && r.state === "STREAM_PENDING" && r.owner === owner)
             .sort((a, b) => a.createdAtMs - b.createdAtMs)
@@ -262,8 +229,7 @@ export class InMemoryApprovalAskStore {
         return r ? { ...r } : null;
     }
     async getByIdempotencyKey(taskId, key) {
-        assertIdempotencyKeyShape(key); // F2 卫生门(三 twin 同判)
-        // 键的两维都要匹配(UNIQUE 已改 `(task_id, idempotency_key)`)——租户门是读口自己的责任。
+        assertIdempotencyKeyShape(key);
         for (const r of this.asks.values()) {
             if (r.taskId === taskId && r.idempotencyKey === key)
                 return { ...r };
@@ -271,7 +237,6 @@ export class InMemoryApprovalAskStore {
         return null;
     }
     async resolveProvisional(askId, from, to, patch) {
-        // 🔴 与 SQL twin 同注:故意不经 canAskTransition——版本化补偿的例外通道。
         const row = this.asks.get(askId);
         if (!row || !row.provisional || row.state !== from)
             return false;