@sema-agent/server 7.43.0 → 7.44.0

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

@@ -1,27 +1,11 @@
 import { mysqlDriver, pgDriver, dialectJsonEncoder } from "./sql-driver.js";
 import { canAskTransition } from "../approval-ask-machine.js";
 import { isDupKeyError } from "./sql-errors.js";
-/**
- * 幂等键的入店卫生门(属主兜底轮 F2,三 twin 同判——SQL 双方言与 InMemory 都从这里过)。
- *
- * 🔴 为什么必须在店门口拒而不是「存什么比什么」:TiDB/MySQL 的 VARCHAR 等值与 UNIQUE 检查带
- * PAD SPACE 语义(utf8mb4_bin 也一样)——`'retry'` 与 `'retry '` 在那侧是**同一个键**,而 PG 与
- * InMemory 的严格字符串比较把它们当两个键 ⇒ 同一份调用方代码在不同后端拿到不同的
- * `idempotency_conflict`/回放结果。键是调用方铸的 opaque 值,首尾空白没有任何合法语义,
- * 在边界上 fail-loud 拒掉,方言分歧面整个消失(比把列改 VARBINARY 更窄、且对三形同时成立)。
- */
 export function assertIdempotencyKeyShape(key) {
     if (key.length === 0 || key.length > 255 || key.trim() !== key) {
         throw new Error(`invalid idempotency key: must be 1-255 chars with no leading/trailing whitespace (got ${JSON.stringify(key.slice(0, 32))}${key.length > 32 ? "…" : ""}, length ${key.length})`);
     }
 }
-/**
- * #151 车3 刀 3b(§14.2 遗留记账):两条**重放读口**被调用方的 deadline 掐断时抛的具名错误。
- *
- * 具名类而不是「按 message 文本判别」:错误文案是给人看的,拿它当控制流 = 上游改一句人话下游静默失效
- * (#90 工程规范 v3 门②)。调用方(开流 preamble)对它的处置与其余读错误一样 —— fail-open、零卡、一次
- * warn —— 所以它今天没有专门的分支;类在这里是为了让**将来**想分「超时 vs 店真报错」的消费点有得分。
- */
 export class ApprovalAskReadAbortedError extends Error {
     constructor(where) {
         super(`approval-ask read ${where} aborted by caller`);
@@ -31,14 +15,6 @@ export class ApprovalAskReadAbortedError extends Error {
 function abortedReadError(where) {
     return new ApprovalAskReadAbortedError(where);
 }
-/**
- * 把一次在飞的读与调用方的 `AbortSignal` 竞速(#151 车3 刀 3b)。
- *
- * 🔴 **它做到什么、做不到什么**(诚实边界,同 {@link ApprovalAskStore.listPendingBySession} 的注):
- * 本仓的 `SqlDriver` 没有取消 seam,所以这里能做的是「让**调用方**不再被吊住」,不是「让**库**停下来」。
- * 输掉竞速的那条 promise 仍在飞——它的 rejection 必须被接住(否则变成 unhandled rejection),它的成功
- * 结果被丢弃(纯读,零副作用)。监听器用完即摘(`once` + finally 清理),不给长命 signal 攒 listener。
- */
 async function withReadSignal(op, signal, where) {
     if (!signal)
         return op;
@@ -47,8 +23,8 @@ async function withReadSignal(op, signal, where) {
         onAbort = () => reject(abortedReadError(where));
         signal.addEventListener("abort", onAbort, { once: true });
     });
-    aborted.catch(() => undefined); // 竞速赢家是 op 时,这条 promise 无人 await —— 先给它一个处理者
-    void op.catch(() => undefined); // 同理:竞速输了的 op 的 rejection 也必须有处理者
+    aborted.catch(() => undefined);
+    void op.catch(() => undefined);
     try {
         return await Promise.race([op, aborted]);
     }
@@ -57,56 +33,8 @@ async function withReadSignal(op, signal, where) {
             signal.removeEventListener("abort", onAbort);
     }
 }
-// ─────────────────────────────────────────────────────────────────────────────────────────────────
-// DDL
-// ─────────────────────────────────────────────────────────────────────────────────────────────────
 export const APPROVAL_ASK_TABLE = "approval_ask";
 export const APPROVAL_BATCH_TABLE = "approval_batch";
-/**
- * TiDB/MySQL-protocol 侧的两条建表语句,**抽成导出数组**(车3 刀 3a):`tidb-pool.ts` 的
- * `SCHEMA_STATEMENTS` 用 `...TIDB_APPROVAL_ASK_STATEMENTS` 展开它们,于是这两张表随中央
- * `ensureSchema` 一起在 **named-lock 的那条 `conn`** 上建 —— 把一个 pool 级 ensure 函数塞进
- * `SCHEMA_STATEMENTS` 的执行循环里做不到这点(会绕开 DDL 串行化),所以真源必须是**语句文本**。
- * 下面的 `ensureTiDBApprovalAskSchema` 保留为遍历这个数组的薄壳(集成测试直接调它建表,
- * 不必为了建两张表去拉起整套中央 schema)。
- *
- * SCHEMA POLICY 同 `tidb-pool.ts` 头注:纯 CREATE,禁 ALTER 增量 seam,改列直接改这里 + 重建库
- * (`docs/schema/baseline-mysql.sql` 是由这些文本机器录制出的**产物**,永不手改)。
- *
- * ── 列宽的**测量依据**(#192 A10;U2 逐列取证在档)──────────────────────────────────────────────────
- * 本表家族原先一律 VARCHAR(255),是"先建表后想"的产物。按"每列的值到底由谁铸、有没有入口上限"重新裁:
- *
- *  收窄(有硬上限背书,证据即上限本身):
- *   · `ask_id` / `batch_id` / `bound_ask_id` → 64:`deriveAskId`/`deriveBatchId` 恒是 sha256 hex 取前
- *     64 字符(`approval-ask-machine.ts` deterministicId),按构造不可能更长。
- *   · `task_id` → 64:入口 `UUIDV7_RE`(`security.ts:134`)只放行 36 字符的规范 uuidv7;与兄弟列
- *     `task_run.task_id VARCHAR(64)` 同宽(此前 255 是本家族独有的偏离,无依据)。
- *   · `session_id` → 64:提交入口硬拒 >64(`http/server.ts` "sessionId must be at most 64 characters"),
- *     与 `session_meta`/`task_run` 同宽。
- *   · `owner` → 190:`assertPrincipalShape` 的 `PRINCIPAL_MAX_LENGTH = 190`(`security.ts` 的同名导出常量,
- *     刻意不钉行号 —— 旧注写的 `security.ts:350` 已随该文件编辑漂走)硬拒更长者;
- *     全仓每一根 owner/scope 轴都是 190,此前 255 同样是无依据偏离。
- *   · `gate_token` → 120:它抄的是 checkpoint 的 token(core `mintCheckpointToken` = 16 字节 hex = 32 字符),
- *     取与**被抄那一列** `checkpoint.token VARCHAR(120)` 同宽 —— 同一个值在两张表上宽度必须一致,
- *     否则抄的那一步就是一道静默截断。512 是原先的 16 倍冗余。
- *
- *  🔑 上面四条收窄之所以**不引入任何新暴露面**,靠的不是入口断言而是一条更硬的事实:同一个 session_id /
- *     task_id / owner **早就**同时躺在 `session_meta.session_id VARCHAR(64)` / `task_run.task_id VARCHAR(64)` /
- *     `task_run.owner VARCHAR(190)` 里。任何长到能撑爆本表新宽度的值,在写到那几张**更中心**的表时就已经
- *     先炸了 —— 本表此前的 255 从来不是一道额外的安全余量,只是一处与全仓不一致的偏离。
- *     ⇒ 收窄的风险上界 = 0;真正要担心的是反过来:留着 255 会让人误以为这里可以存更长的 id。
- *
- *  🔴 **刻意不收窄**(测量结果不支持,记在这里免得下一个人以为是漏了):
- *   · `source_task_id` / `tool_call_id` / `parent_tool_call_id` / `gate_bound_call_id` —— 这四列的值是
- *     **模型/引擎铸的原始 id**,服务端在写行这一步**没有任何长度断言**(`approval-card.ts` 的
- *     `MAX_IDENT` 只裁了给人看的那份 card 投影,不是本列)。没有入口上限就收窄 = 把"存不下"这件事
- *     推迟到 INSERT 才炸(MySQL 更糟:静默截断),换来的只是几十字节。要收窄,先补入口断言
- *     (照 `assertPrincipalShape`/`assertIdempotencyKeyShape` 的姿势),那是另一件事。
- *   · `bound_input_hash` / `gate_bound_input_hash` —— 按约定是 sha256 hex(64),但 `readBoundInputHash`
- *     只校验"非空字符串",没校长度/字形 ⇒ 同上,先有断言再谈收窄。
- *   · `idempotency_key` —— 255 **正是**入口断言的上限本身(zod `.max(255)` + 店内 `assertIdempotencyKeyShape`
- *     双执法),宽度与上限同源,恰好正确,动它反而制造截断面。
- */
 export const TIDB_APPROVAL_ASK_STATEMENTS = [
     `CREATE TABLE IF NOT EXISTS ${APPROVAL_BATCH_TABLE} (
     batch_id VARCHAR(64) NOT NULL,
@@ -168,8 +96,6 @@ export const TIDB_APPROVAL_ASK_STATEMENTS = [
     KEY idx_ask_state (state)
   ) COLLATE utf8mb4_bin`,
 ];
-/** {@link TIDB_APPROVAL_ASK_STATEMENTS} 的遍历壳——生产路径走 `tidb-pool.ts` 的中央 `ensureSchema`
- *  (那里展开了同一份数组),本函数留给只需要这两张表的集成测试。 */
 export async function ensureTiDBApprovalAskSchema(pool) {
     for (const stmt of TIDB_APPROVAL_ASK_STATEMENTS)
         await pool.query(stmt);
@@ -223,8 +149,6 @@ export async function ensurePgApprovalAskSchema(q) {
     CONSTRAINT uq_approval_ask_idem UNIQUE (task_id, idempotency_key)
   )`);
     await q(`CREATE INDEX IF NOT EXISTS idx_ask_task_state ON ${APPROVAL_ASK_TABLE} (task_id, state)`);
-    // 车3 §5.1:sync 腿开流重放读口(listPendingBySession)的支撑索引 —— MySQL twin 的
-    // `KEY idx_ask_session_state (session_id, state)` 同形。
     await q(`CREATE INDEX IF NOT EXISTS idx_ask_session_state ON ${APPROVAL_ASK_TABLE} (session_id, state)`);
     await q(`CREATE INDEX IF NOT EXISTS idx_ask_batch ON ${APPROVAL_ASK_TABLE} (batch_id)`);
     await q(`CREATE INDEX IF NOT EXISTS idx_ask_state ON ${APPROVAL_ASK_TABLE} (state)`);
@@ -234,10 +158,6 @@ const ASK_COLS = "ask_id, task_id, source_task_id, session_id, owner, batch_id,
     "gate_bound_call_id, gate_bound_input_hash, idempotency_key, card_json, schema_version, expires_at_ms, " +
     "created_at_ms, updated_at_ms";
 const BATCH_COLS = "batch_id, task_id, state, bound_ask_id, rev, created_at_ms, updated_at_ms";
-/** JSON 列的读出:**本层只做存取,不解释**——返回类型即 `unknown`,把「这是什么形」的责任留给消费方。
- *  两个 JSON 列的 schema 属主都不在本车:`decision_actor` = design/171 ActorAssertion 形(车4 回决端点
- *  消费,届时按宪法 [2704] 立 schema 后 safeParse);`card_json` = 172 §3.1 呈卡帧载荷(车3 wire 面属主)。
- *  故此处刻意不铸内域类型(无 as),持久层对这两列保持透明字节存取语义。 */
 function parseJsonColumn(v) {
     return JSON.parse(String(v));
 }
@@ -292,8 +212,6 @@ function mapBatchRow(r) {
         updatedAtMs: Number(r.updated_at_ms),
     };
 }
-/** 动态 SET 列清单(`transitionAsk`/`resolveProvisional` 用):只收 patch 里真出现的字段,`decisionActor`
- *  按内容面 JSON 编码器序列化。`updatedAtMs` 不在这里——调用方把它拼进固定尾列(所有转移恒推进它）。 */
 function patchColumns(patch, json) {
     const out = [];
     if (patch.decision !== undefined)
@@ -316,14 +234,9 @@ function patchColumns(patch, json) {
         out.push(["provisional", patch.provisional ? 1 : 0]);
     return out;
 }
-/** 第 n 个(1-based)绑定参数的占位符文本。TiDB 用位置序 `?`(n 被忽略);PG 需要显式编号 `$n`——
- *  两种转移(transitionAsk/resolveProvisional)的列集合按 patch 内容动态变化,固定的两段式 SQL 文本
- *  写不出来,因此占位符本身也必须按方言现场生成(与 background-agent-store-sql.ts 的 guard 占位符
- *  构造同精神:方言差异仍然显式——分支在这一个函数里,不是被某个跨方言的抽象吞掉）。 */
 function ph(dialect, n) {
     return dialect === "tidb" ? "?" : `$${n}`;
 }
-/** 双方言 `ApprovalAskStore`。见文件头注的 CAS 铁则 + 方言差异清单。 */
 export class SqlApprovalAskStore {
     db;
     constructor(db) {
@@ -335,44 +248,24 @@ export class SqlApprovalAskStore {
     json(value) {
         return dialectJsonEncoder(this.db.dialect)(value);
     }
-    /** 唯一键冲突判别 —— 判据属主 = `sql-errors.ts`(A-032 P1-①)。`decideAsk` 用它把 `(task_id,
-     *  idempotency_key)` 撞键翻成 typed 的 `idempotency_conflict` 臂,不让驱动错误对象漏给消费层;
-     *  旧形 tidb 臂只认 errno,只带 `code` 的驱动错误会漏判成"真障碍"。 */
     isDupKey(e) {
         return isDupKeyError(this.db.dialect, e);
     }
-    /**
-     * 🔴 失败臂的回读**必须走当前这条 `conn`**,不许调 `this.getAsk`/`this.getBatch`(codex 复审 F1,
-     * 2026-08-06 真缺陷,池大小=1 的钉上实测挂死 25s)。原因:那两个读口走**池级** `this.db.query`,而
-     * 此刻本方法还攥着自己的事务连接(要到 `finally` 才 release)——于是「回读在等一条新连接,而唯一
-     * 那条连接要等回读返回才释放」= 确定性死锁。池大于 1 时它退化成「同时走到失败臂的并发数 ≥ 池大小
-     * 就整池饿死」,是同一个缺陷的更难复现形,不是另一个问题。
-     *
-     * 调用点纪律:**先 `conn.rollback()` 再调这两个**。回滚之后连接回到 autocommit,这条 SELECT 自成
-     * 一个事务 ⇒ 读到的是最新已提交视图(正是失败臂要如实上报的东西),不受本事务快照的影响——两方言
-     * 在这一点上同义,不必再纠结 InnoDB 读视图与 TiDB start_ts 的差别。
-     */
     async getAskOn(conn, askId) {
         const { rows } = await conn.query(this.q(`SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE ask_id = ?`, `SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE ask_id = $1`), [askId]);
         return rows[0] ? mapAskRow(rows[0]) : null;
     }
-    /** {@link getAskOn} 的批侧同形(同一条纪律:失败臂回读走本连接)。 */
     async getBatchOn(conn, batchId) {
         const { rows } = await conn.query(this.q(`SELECT ${BATCH_COLS} FROM ${APPROVAL_BATCH_TABLE} WHERE batch_id = ?`, `SELECT ${BATCH_COLS} FROM ${APPROVAL_BATCH_TABLE} WHERE batch_id = $1`), [batchId]);
         return rows[0] ? mapBatchRow(rows[0]) : null;
     }
     async ensureAsk(row) {
         const now = row.createdAtMs;
-        /** 本次 ask 插入的 affected 行数(1 = 真插入 / 0 = 幂等命中)——判别位的**唯一**来源,见
-         *  {@link EnsureAskResult}。两方言各自的语句形不同(`INSERT IGNORE` vs `ON CONFLICT DO NOTHING`),
-         *  但 affected 的语义是同一个,`SqlDriver` 已把 mysql2 的 `affectedRows` 与 pg 的 `rowCount` 归一。 */
         let insertedRows = 0;
         const conn = await this.db.connect();
         try {
             await conn.begin();
             await conn.query(this.q(`INSERT IGNORE INTO ${APPROVAL_BATCH_TABLE} (batch_id, task_id, state, rev, created_at_ms, updated_at_ms) VALUES (?, ?, 'OPEN', 0, ?, ?)`, `INSERT INTO ${APPROVAL_BATCH_TABLE} (batch_id, task_id, state, rev, created_at_ms, updated_at_ms) VALUES ($1, $2, 'OPEN', 0, $3, $4) ON CONFLICT (batch_id) DO NOTHING`), [row.batchId, row.taskId, now, now]);
-            // 🔴 `idempotency_key` **不在 INSERT 列清单里**(车4 §12-E 双写者收口):该列已归回决专用,只有
-            // `decideAsk` 赢 CAS 时写它,铸行恒 NULL。留在这里的 NULL 字面量就是这条纪律的落笔处。
             const askInsert = await conn.query(this.q(`INSERT IGNORE INTO ${APPROVAL_ASK_TABLE} (ask_id, task_id, source_task_id, session_id, owner, batch_id, tool_call_id, leg_key, parent_tool_call_id, bound_input_hash, state, provisional, rev, decision, decision_actor, decision_note, decided_at_ms, denied_reason, gate_token, gate_bound_call_id, gate_bound_input_hash, idempotency_key, card_json, schema_version, expires_at_ms, created_at_ms, updated_at_ms) ` +
                 "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'STREAM_PENDING', 0, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, ?, ?, ?, ?, ?)", `INSERT INTO ${APPROVAL_ASK_TABLE} (ask_id, task_id, source_task_id, session_id, owner, batch_id, tool_call_id, leg_key, parent_tool_call_id, bound_input_hash, state, provisional, rev, decision, decision_actor, decision_note, decided_at_ms, denied_reason, gate_token, gate_bound_call_id, gate_bound_input_hash, idempotency_key, card_json, schema_version, expires_at_ms, created_at_ms, updated_at_ms) ` +
                 "VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, 'STREAM_PENDING', 0, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, $11, $12, $13, $14, $15) ON CONFLICT (ask_id) DO NOTHING"), [
@@ -400,7 +293,6 @@ export class SqlApprovalAskStore {
                 await conn.rollback();
             }
             catch {
-                /* ignore */
             }
             throw err;
         }
@@ -410,12 +302,9 @@ export class SqlApprovalAskStore {
         const out = await this.getAsk(row.askId);
         if (!out)
             throw new Error(`ensureAsk: row vanished after insert (askId=${row.askId})`);
-        // 判别位取**提交那一刻**引擎报的 affected,不是事后回读推断的:回读发生在提交之后,那时并发的
-        // 第二个调用可能已经改过行,任何「从行上反推谁插的」都是又一次猜。
         return { row: out, inserted: insertedRows > 0 };
     }
     async transitionAsk(askId, from, to, patch) {
-        // machine 层先判(非法转移=编程错误,throw 而非返回 false——设计定稿 §4 原话)。
         if (!canAskTransition(from, to)) {
             throw new Error(`approval-ask-store.transitionAsk: illegal ask transition ${from} -> ${to} (askId=${askId})`);
         }
@@ -427,33 +316,26 @@ export class SqlApprovalAskStore {
         const setSql = cols.map((c) => `${c} = ${ph(dialect, ++n)}`).join(", ");
         const askIdPh = ph(dialect, ++n);
         const fromPh = ph(dialect, ++n);
-        // `rev = rev + 1`(恒变列,MySQL 同值 UPDATE affectedRows=0 坑——见文件头注 CAS 铁则②)。
         const res = await this.db.query(`UPDATE ${APPROVAL_ASK_TABLE} SET ${setSql}, rev = rev + 1 WHERE ask_id = ${askIdPh} AND state = ${fromPh}`, [...vals, askId, from]);
         return res.affected === 1;
     }
     async decideAsk(askId, batchId, decision) {
         if (decision.idempotencyKey != null)
-            assertIdempotencyKeyShape(decision.idempotencyKey); // F2 卫生门:进事务前拒
+            assertIdempotencyKeyShape(decision.idempotencyKey);
         const now = Date.now();
         const conn = await this.db.connect();
         try {
             await conn.begin();
-            // ① 批必须还 OPEN(自增写 rev 保证 affected 语义在 CLIENT_FOUND_ROWS 关闭下仍=1;=0 ⇒ 批已封)。
             const batchRes = await conn.query(this.q(`UPDATE ${APPROVAL_BATCH_TABLE} SET rev = rev + 1, updated_at_ms = ? WHERE batch_id = ? AND state = 'OPEN'`, `UPDATE ${APPROVAL_BATCH_TABLE} SET rev = rev + 1, updated_at_ms = $1 WHERE batch_id = $2 AND state = 'OPEN'`), [now, batchId]);
             if (batchRes.affected !== 1) {
                 await conn.rollback();
                 return { ok: false, reason: "batch_closed", row: await this.getAskOn(conn, askId) };
             }
-            // ② ask 必须还 STREAM_PENDING;单赢者 CAS。回决幂等键随决议**同一条语句**落列(车4 §12-E):
-            //    分两步写会开一个「已 DECIDED 但键还没落」的窗口,同 key 重试在窗口内读不到键 ⇒ 会去打第二次
-            //    CAS(输)再报 409,把一次合法回放变成冲突。同一 UPDATE ⇒ 键与终态同生共死。
-            let askRes; // 显式标注:`let x;` 是 evolving-any,本仓按强类型用
+            let askRes;
             try {
                 askRes = await conn.query(this.q(`UPDATE ${APPROVAL_ASK_TABLE} SET state='DECIDED', decision=?, decision_actor=?, decision_note=?, decided_at_ms=?, idempotency_key=?, rev=rev+1, updated_at_ms=? WHERE ask_id=? AND state='STREAM_PENDING'`, `UPDATE ${APPROVAL_ASK_TABLE} SET state='DECIDED', decision=$1, decision_actor=$2, decision_note=$3, decided_at_ms=$4, idempotency_key=$5, rev=rev+1, updated_at_ms=$6 WHERE ask_id=$7 AND state='STREAM_PENDING'`), [decision.decision, decision.decisionActor == null ? null : this.json(decision.decisionActor), decision.decisionNote ?? null, now, decision.idempotencyKey ?? null, now, askId]);
             }
             catch (err) {
-                // `(task_id, idempotency_key)` 撞键 = 同一 key 已被本 task 内**另一条** ask 的回决占用。这是调用方
-                // 键管理的问题(不是 CAS 竞争),翻成 typed 臂交给端点译 409——方言 errno/SQLSTATE 不出店。
                 if (this.isDupKey(err)) {
                     await conn.rollback();
                     return { ok: false, reason: "idempotency_conflict", row: await this.getAskOn(conn, askId) };
@@ -471,7 +353,6 @@ export class SqlApprovalAskStore {
                 await conn.rollback();
             }
             catch {
-                /* ignore */
             }
             throw err;
         }
@@ -488,39 +369,23 @@ export class SqlApprovalAskStore {
         const conn = await this.db.connect();
         try {
             await conn.begin();
-            // ⓪ 锁序不变量(真双库 §6-4b 死锁实抓,2026-08-05):凡同一事务触碰批行+ask 行者,**一律批行先**
-            //    (decideAsk/bindBatch/abortBatch 皆批先;expireAsk 原是 ask 先 ⇒ 与 decideAsk 构成 AB-BA,
-            //    TiDB 悲观锁当场 `Deadlock found`)。这里用无谓词的 rev 自增先取批行锁作序列化点——
-            //    带 state 谓词的转移放后面(谓词不符时部分引擎不留锁,序列化点会失效)。ask CAS 输时整个
-            //    事务回滚,这次自增一并撤销,无痕。
             const lockRes = await conn.query(this.q(`UPDATE ${APPROVAL_BATCH_TABLE} SET rev=rev+1 WHERE batch_id=?`, `UPDATE ${APPROVAL_BATCH_TABLE} SET rev=rev+1 WHERE batch_id=$1`), [batchId]);
             if (lockRes.affected !== 1) {
-                await conn.rollback(); // 批行不存在 = ensureAsk 从未为它建批(编程错误形,如实不赢)
+                await conn.rollback();
                 return { won: false, voidedSiblings: [] };
             }
-            // ① 中选:ask STREAM_PENDING → PARKING(单赢者;输 = 已被回决/取消,整体放弃)。
             const askRes = await conn.query(this.q(`UPDATE ${APPROVAL_ASK_TABLE} SET state='PARKING', rev=rev+1, updated_at_ms=? WHERE ask_id=? AND state='STREAM_PENDING'`, `UPDATE ${APPROVAL_ASK_TABLE} SET state='PARKING', rev=rev+1, updated_at_ms=$1 WHERE ask_id=$2 AND state='STREAM_PENDING'`), [now, askId]);
             if (askRes.affected !== 1) {
                 await conn.rollback();
                 return { won: false, voidedSiblings: [] };
             }
-            // ② 批 OPEN → ROUTING_UNBOUND(已是 ROUTING_UNBOUND = 兄弟先到,affected=0 也算成功续走③——不检查
-            //    affected,批状态无论如何这一刻都已经是 ROUTING_UNBOUND 或更前进)。
             await conn.query(this.q(`UPDATE ${APPROVAL_BATCH_TABLE} SET state='ROUTING_UNBOUND', rev=rev+1, updated_at_ms=? WHERE batch_id=? AND state='OPEN'`, `UPDATE ${APPROVAL_BATCH_TABLE} SET state='ROUTING_UNBOUND', rev=rev+1, updated_at_ms=$1 WHERE batch_id=$2 AND state='OPEN'`), [now, batchId]);
-            // ③ 兄弟撤卡:PG 用 RETURNING 单语句拿名单;TiDB 无 RETURNING,同事务先 SELECT 后 UPDATE。
             let voidedSiblings;
             if (this.db.dialect === "pg") {
                 const res = await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='VOID', rev=rev+1, updated_at_ms=$1 WHERE batch_id=$2 AND state='STREAM_PENDING' AND ask_id<>$3 RETURNING ask_id`, [now, batchId, askId]);
                 voidedSiblings = res.rows.map((r) => String(r.ask_id));
             }
             else {
-                // 🔴 `FOR UPDATE` + 按选出的 id 列表更新(车5 同病修,与 `bindBatch` 的 PARKING 臂逐字同形——
-                // 那里的完整论证见该处注):裸 SELECT 是**非锁定读**,它与随后那条宽谓词 UPDATE 不是同一个行集
-                // (`transitionAsk`/`decideAsk` 不走批锁,可以在两条语句之间把某个兄弟搬进/搬出 STREAM_PENDING)。
-                // 搬进的会被 UPDATE 改成 VOID 却**不在**返回名单里(撤卡帧漏发 ⇒ 壳上留一张已作废的卡),搬出的
-                // 会在名单里却没被改(撤卡帧误发)。PG 的 RETURNING 与 InMemory 都返回「真正被改的那一组」,
-                // 所以裸读会造出一个**只在 MySQL 方言上**成立的协议分歧。锁序:本方法已先取批行锁(步⓪),
-                // 此处再取 ask 行锁,与文件头注的「批先 ask 后」一致。
                 const sel = await conn.query(`SELECT ask_id FROM ${APPROVAL_ASK_TABLE} WHERE batch_id=? AND state='STREAM_PENDING' AND ask_id<>? FOR UPDATE`, [batchId, askId]);
                 voidedSiblings = sel.rows.map((r) => String(r.ask_id));
                 if (voidedSiblings.length > 0) {
@@ -539,7 +404,6 @@ export class SqlApprovalAskStore {
                 await conn.rollback();
             }
             catch {
-                /* ignore */
             }
             throw err;
         }
@@ -552,44 +416,25 @@ export class SqlApprovalAskStore {
         const conn = await this.db.connect();
         try {
             await conn.begin();
-            // bind-once:批 ROUTING_UNBOUND → ROUTING_BOUND + bound_ask_id(WHERE bound_ask_id IS NULL 是第二道
-            // 保险——state 谓词已经把并发者挡在外面,这里双保险防「同一批被 bind 两次」哪怕未来状态机被误改）。
             const batchRes = await conn.query(this.q(`UPDATE ${APPROVAL_BATCH_TABLE} SET state='ROUTING_BOUND', bound_ask_id=?, rev=rev+1, updated_at_ms=? WHERE batch_id=? AND state='ROUTING_UNBOUND' AND bound_ask_id IS NULL`, `UPDATE ${APPROVAL_BATCH_TABLE} SET state='ROUTING_BOUND', bound_ask_id=$1, rev=rev+1, updated_at_ms=$2 WHERE batch_id=$3 AND state='ROUTING_UNBOUND' AND bound_ask_id IS NULL`), [askId, now, batchId]);
             if (batchRes.affected !== 1) {
-                // 判别式的信息来源 = 批行的真实态。🔴 回读**放在 rollback 之后、走池上的独立读**,不在本事务内读:
-                // TiDB 的事务快照按 start_ts 取,同事务内的普通 SELECT 可能读到 BEGIN 时刻的旧值(InnoDB 的读视图
-                // 规则又与它不同)——两方言在这一点上不等价,而本车恰恰要靠这个值分 ABORTED / ROUTING_BOUND 两条
-                // **处置相反**的臂。事务已回滚(本事务除了那条 affected=0 的 CAS 什么也没写),池上重读是干净的
-                // 已提交视图,双方言同义。
                 await conn.rollback();
                 const cur = await this.getBatchOn(conn, batchId);
                 if (!cur)
                     return { ok: false, batchState: "MISSING" };
                 return { ok: false, batchState: cur.state, ...(cur.boundAskId !== null ? { boundAskId: cur.boundAskId } : {}) };
             }
-            // 中选 ask PARKING → PARKED(带 gate 三件)。
             const askRes = await conn.query(this.q(`UPDATE ${APPROVAL_ASK_TABLE} SET state='PARKED', gate_token=?, gate_bound_call_id=?, gate_bound_input_hash=?, rev=rev+1, updated_at_ms=? WHERE ask_id=? AND state='PARKING'`, `UPDATE ${APPROVAL_ASK_TABLE} SET state='PARKED', gate_token=$1, gate_bound_call_id=$2, gate_bound_input_hash=$3, rev=rev+1, updated_at_ms=$4 WHERE ask_id=$5 AND state='PARKING'`), [gate.gateToken, gate.gateBoundCallId ?? null, gate.gateBoundInputHash ?? null, now, askId]);
             if (askRes.affected !== 1) {
                 await conn.rollback();
-                // ask 不在 PARKING(被别的竞争者收走)⇒ 整事务回滚,批**没有**被绑上。如实报批的回滚后真值:
-                // 它仍是 ROUTING_UNBOUND(上一步的 CAS 谓词已经证明了这一点,连同本次自增一起撤销)。
                 return { ok: false, batchState: "ROUTING_UNBOUND" };
             }
-            // 其余 PARKING 兄弟 → VOID,**名单随成功臂回传**(车5 §8 A-4):撤卡帧的 `askIds` 就是它。
-            // 读法与 expireAsk 逐字同形:PG `RETURNING` 单语句;TiDB 无 RETURNING ⇒ 同事务先 SELECT 后 UPDATE。
             let voidedSiblings;
             if (this.db.dialect === "pg") {
                 const res = await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='VOID', rev=rev+1, updated_at_ms=$1 WHERE batch_id=$2 AND state='PARKING' AND ask_id<>$3 RETURNING ask_id`, [now, batchId, askId]);
                 voidedSiblings = res.rows.map((r) => String(r.ask_id));
             }
             else {
-                // 🔴 `FOR UPDATE` + 按选出的 id 逐条更新(codex 复审 F2,2026-08-06):裸 SELECT 是非锁定读,
-                // 它与随后那条宽谓词 UPDATE **不是**同一个行集——`transitionAsk` 不走批锁,可以在两条语句之间
-                // 把某个兄弟搬进/搬出 PARKING。搬进的会被 UPDATE 改成 VOID 却**不在**返回名单里(撤卡帧漏发 ⇒
-                // 壳上留一张已作废的卡),搬出的会在名单里却没被改(撤卡帧误发)。PG 的 RETURNING 与 InMemory
-                // 都返回「真正被改的那一组」,所以裸读会造出一个**只在 MySQL 方言上**成立的协议分歧。
-                // 修法:锁定读把行集钉死,再只更新这批 id ⇒ 返回名单恒等于被改集合,三形同义。
-                // 锁序:本方法已先取批行锁(上面那条 CAS),此处再取 ask 行锁,与文件头注的「批先 ask 后」一致。
                 const sel = await conn.query(`SELECT ask_id FROM ${APPROVAL_ASK_TABLE} WHERE batch_id=? AND state='PARKING' AND ask_id<>? FOR UPDATE`, [batchId, askId]);
                 voidedSiblings = sel.rows.map((r) => String(r.ask_id));
                 if (voidedSiblings.length > 0) {
@@ -605,7 +450,6 @@ export class SqlApprovalAskStore {
                 await conn.rollback();
             }
             catch {
-                /* ignore */
             }
             throw err;
         }
@@ -623,17 +467,12 @@ export class SqlApprovalAskStore {
                 await conn.rollback();
                 return [];
             }
-            // 只撤 STREAM_PENDING(设计定稿字面:「整批 STREAM_PENDING→VOID」)——已 DECIDED 的兄弟不受影响
-            // (§3.0 原话),PARKING/PARKED/DENIED 同样不在这条 UPDATE 的谓词里,保持不动。
             let voided;
             if (this.db.dialect === "pg") {
                 const res = await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='VOID', rev=rev+1, updated_at_ms=$1 WHERE batch_id=$2 AND state='STREAM_PENDING' RETURNING ask_id`, [now, batchId]);
                 voided = res.rows.map((r) => String(r.ask_id));
             }
             else {
-                // 🔴 同 `expireAsk`/`bindBatch` 的锁定读改造(车5 同病修):非锁定读的名单与宽谓词 UPDATE 的
-                // 行集不是同一个 ⇒ 撤卡帧漏发/误发,且分歧只在 MySQL 方言上成立。锁序:批行锁(上一条 CAS)
-                // 已取,此处再取 ask 行锁。
                 const sel = await conn.query(`SELECT ask_id FROM ${APPROVAL_ASK_TABLE} WHERE batch_id=? AND state='STREAM_PENDING' FOR UPDATE`, [batchId]);
                 voided = sel.rows.map((r) => String(r.ask_id));
                 if (voided.length > 0) {
@@ -649,7 +488,6 @@ export class SqlApprovalAskStore {
                 await conn.rollback();
             }
             catch {
-                /* ignore */
             }
             throw err;
         }
@@ -657,17 +495,6 @@ export class SqlApprovalAskStore {
             conn.release();
         }
     }
-    /**
-     * 🔴 排序键是 `updated_at_ms`(车5 §8 D-4;codex 三轮补抓:原先按 `created_at_ms` 排,`deferReconcile`
-     * 就是**空转**的)。这条读口与 `deferReconcile` 是一对:收敛器每轮取前 `limit` 条,判不出终局的行用
-     * `deferReconcile` 推 `updated_at_ms` 把自己排到队尾,下一轮新行才轮得到。若这里仍按建行时间排,
-     * 推 `updated_at_ms` 对顺序毫无影响 ⇒ 一旦 `limit` 被若干长驻 PARKING 行占满,每轮扫到的永远是同一批,
-     * 后来的审批被无限饿死(§5 旋钮那句「超出下轮接着扫」也就不成立)。
-     * 次级键 `created_at_ms` 只为**确定性**:同毫秒的行不至于在两次扫描间乱序(分页/限流下的稳定序)。
-     *
-     * 🔴 配套纪律(§9 C5):任何 TTL 判据一律量 immutable 的 `createdAtMs`/`expiresAtMs`,**绝不量
-     * `updatedAtMs`**——它被队列轮转每轮刷新,量它的 TTL 永不到期。
-     */
     async listByState(state, limit) {
         const { rows } = await this.db.query(this.q(`SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE state = ? ORDER BY updated_at_ms ASC, created_at_ms ASC LIMIT ?`, `SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE state = $1 ORDER BY updated_at_ms ASC, created_at_ms ASC LIMIT $2`), [state, limit]);
         return rows.map(mapAskRow);
@@ -681,8 +508,6 @@ export class SqlApprovalAskStore {
     async listPendingBySession(sessionId, owner, signal) {
         if (signal?.aborted === true)
             throw abortedReadError("listPendingBySession");
-        // 租户门的两段谓词文本(见接口注):`owner = ?` 对 NULL 恒 UNKNOWN ⇒ 无租户身份的部署形必须走
-        // `owner IS NULL`,否则这条读口在那些部署上恒回零行(一条静默失效的重放面,比报错更难发现)。
         const { rows } = await withReadSignal(this.db.query(owner === null
             ? this.q(`SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE session_id = ? AND state = 'STREAM_PENDING' AND owner IS NULL ORDER BY created_at_ms ASC`, `SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE session_id = $1 AND state = 'STREAM_PENDING' AND owner IS NULL ORDER BY created_at_ms ASC`)
             : this.q(`SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE session_id = ? AND state = 'STREAM_PENDING' AND owner = ? ORDER BY created_at_ms ASC`, `SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE session_id = $1 AND state = 'STREAM_PENDING' AND owner = $2 ORDER BY created_at_ms ASC`), owner === null ? [sessionId] : [sessionId, owner]), signal, "listPendingBySession");
@@ -695,20 +520,15 @@ export class SqlApprovalAskStore {
         return rows[0] ? mapAskRow(rows[0]) : null;
     }
     async getByIdempotencyKey(taskId, key) {
-        assertIdempotencyKeyShape(key); // F2 卫生门:坏形键不做注定方言分歧的查询
-        // 谓词跟 UNIQUE `(task_id, idempotency_key)` 逐字对齐 ⇒ 至多一行,且天然带租户门(见接口注)。
+        assertIdempotencyKeyShape(key);
         const { rows } = await this.db.query(this.q(`SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE task_id = ? AND idempotency_key = ?`, `SELECT ${ASK_COLS} FROM ${APPROVAL_ASK_TABLE} WHERE task_id = $1 AND idempotency_key = $2`), [taskId, key]);
         return rows[0] ? mapAskRow(rows[0]) : null;
     }
     async deferReconcile(askId, expectedState, expectedRev, nowMs) {
-        // 纯 touch:**不碰 state**(见接口注——同态转移在状态机表上无出边,这里刻意走另一扇门),只推
-        // `updated_at_ms` 与恒变的 `rev`。`AND state=? AND rev=?` 双谓词 = 两副本同扫时的单赢者门。
         const res = await this.db.query(this.q(`UPDATE ${APPROVAL_ASK_TABLE} SET updated_at_ms = ?, rev = rev + 1 WHERE ask_id = ? AND state = ? AND rev = ?`, `UPDATE ${APPROVAL_ASK_TABLE} SET updated_at_ms = $1, rev = rev + 1 WHERE ask_id = $2 AND state = $3 AND rev = $4`), [nowMs, askId, expectedState, expectedRev]);
         return res.affected === 1;
     }
     async resolveProvisional(askId, from, to, patch) {
-        // 🔴 故意不经 canAskTransition:这是设计定稿 §3.0/§4 明说的「provisional 行的版本化补偿」——终态→终态
-        // 的例外通道,机器表把终态定义为「无出边」,这里走的是另一扇门(WHERE provisional=1 AND state=from）。
         const dialect = this.db.dialect;
         const dyn = patchColumns(patch, (v) => this.json(v));
         const cols = ["state", "provisional", ...dyn.map(([c]) => c), "updated_at_ms"];
@@ -730,13 +550,11 @@ export class SqlApprovalAskStore {
         return rows[0] ? mapBatchRow(rows[0]) : null;
     }
 }
-/** MySQL-protocol(TiDB)绑定。 */
 export class TiDBApprovalAskStore extends SqlApprovalAskStore {
     constructor(pool) {
         super(mysqlDriver(pool));
     }
 }
-/** PostgreSQL 绑定。 */
 export class PgApprovalAskStore extends SqlApprovalAskStore {
     constructor(pool) {
         super(pgDriver(pool));

package/dist/plugins/approval-exemption-store.js

@@ -1,22 +1,6 @@
-/**
- * Per-session per-toolName approval exemption ("本会话不再询问",
- * design: sema-internal server/docs/design/APPROVAL-SESSION-EXEMPTION.md).
- *
- * SEMANTICS (the boundary that keeps this an APPROVAL MEMORY, not a policy loosen): a granted row makes the
- * F4 ask-gate SKIP the human ask for that (sessionId, canonicalToolName) — it is consulted ONLY after
- * `APPROVAL_DENY` and `APPROVAL_NEVER_AUTO` (both always win), and never touches the session-policy layer
- * (tighten-only stays intact). Keyed in CANONICAL tool-name space (the same rename-smuggling discipline as
- * the require/deny sets). Lifecycle = session-bound: E21 session DELETE purges via deleteBySession.
- *
- * Four twins behind one interface (the resume-anchor pattern): TiDB/PG = durable cross-replica SQL rows
- * (idempotent upsert on the (session_id, tool_name) PK); File = per-session JSONL append log (fsync — a
- * lost grant re-asks, but a torn log must not FABRICATE one), hydrated on boot, torn-tail-safe; Memory =
- * tests / ephemeral. Consumers treat store FAILURE as fail-closed (ask anyway) — enforced at the call site.
- */
 import { join } from "node:path";
 import { existsSync, readdirSync, rmSync } from "node:fs";
 import { AppendLog, ensureDir, readJsonlRecords, sanitizePathComponent } from "@sema-agent/core";
-// ─── TiDB / MySQL twin ───────────────────────────────────────────────────────────────────────────────────
 export class TiDBApprovalExemptionStore {
     pool;
     constructor(pool) {
@@ -24,8 +8,7 @@ export class TiDBApprovalExemptionStore {
     }
     async grant(sessionId, toolName, grantedBy) {
         await this.pool.query("INSERT INTO approval_exemption (session_id, tool_name, granted_by, created_at) VALUES (?,?,?,?) " +
-            "ON DUPLICATE KEY UPDATE granted_by = VALUES(granted_by)", // created_at keeps the first grant
-        [sessionId, toolName, grantedBy, new Date()]);
+            "ON DUPLICATE KEY UPDATE granted_by = VALUES(granted_by)", [sessionId, toolName, grantedBy, new Date()]);
     }
     async has(sessionId, toolName) {
         const [rows] = await this.pool.query("SELECT 1 FROM approval_exemption WHERE session_id = ? AND tool_name = ?", [sessionId, toolName]);
@@ -48,7 +31,6 @@ export class TiDBApprovalExemptionStore {
         return r.affectedRows;
     }
 }
-// ─── PG twin (dialect twin of the TiDB store — same contract, $n placeholders + ON CONFLICT) ─────────────
 export class PgApprovalExemptionStore {
     pool;
     constructor(pool) {
@@ -85,7 +67,6 @@ export class PgApprovalExemptionStore {
         return res.rowCount ?? 0;
     }
 }
-// ─── Memory twin (tests / ephemeral) ─────────────────────────────────────────────────────────────────────
 export class MemoryApprovalExemptionStore {
     bySession = new Map();
     async grant(sessionId, toolName, grantedBy) {
@@ -129,7 +110,6 @@ export class FileApprovalExemptionStore {
     pathFor(sessionId) {
         return join(this.dir, `${sanitizePathComponent(sessionId)}.jsonl`);
     }
-    /** Replay every session log (torn-tail-safe; last-wins with revoke tombstones). Index keyed by the SANITIZED id. */
     hydrate() {
         let names;
         try {
@@ -211,13 +191,9 @@ export class FileApprovalExemptionStore {
             log.close();
             this.logs.delete(key);
         }
-        // 🔴 unlink BEFORE dropping the index, and FAIL LOUD if the file survives: a
-        // swallowed rm would let hydrate() resurrect purged exemptions after a restart — an E21 right-to-delete
-        // violation with PRIVILEGE attached (auto-approve rights), unlike the inert anchor-store twin. Throwing
-        // here aborts the caller's session purge before it deletes the session metadata (fail-loud, retryable).
         const path = this.pathFor(sessionId);
         try {
-            rmSync(path, { force: true }); // force: missing file is fine (idempotent delete)
+            rmSync(path, { force: true });
         }
         catch (e) {
             if (existsSync(path))
@@ -226,14 +202,12 @@ export class FileApprovalExemptionStore {
         this.bySession.delete(key);
         return removed;
     }
-    /** Release every open append-log fd (LocalBackend.close → graceful-restart re-open). */
     dispose() {
         for (const log of this.logs.values()) {
             try {
                 log.close();
             }
             catch {
-                /* best-effort */
             }
         }
         this.logs.clear();