@sema-agent/server 7.43.0 → 7.44.0

package/dist/plugins/task-attachment-store.js

@@ -1,7 +1,4 @@
 export const TASK_ATTACHMENT_TABLE = "task_attachment";
-/** 物化相对路径(确定性,notice 与真实写盘共用一份推导——两处各算一遍会漂):按 listBySession 序
- *  (created_at_ms, id)分配 `attachments/<name>`;同名撞车时后者前缀 id 头 8 位。名字在上传时已
- *  消毒为安全 basename([A-Za-z0-9._-]),拼接后仍是安全相对路径。 */
 export function materializedRelPaths(atts) {
     const used = new Set();
     const out = new Map();
@@ -26,9 +23,6 @@ function rowToRecord(r) {
         ...(r.bound_at_ms !== null && r.bound_at_ms !== undefined ? { boundAtMs: Number(r.bound_at_ms) } : {}),
     };
 }
-/** 半场②(提交时绑定 + objective 告知)的可测核。fresh 腿硬验证(未知/他人 id → throw(mapTo400));
- *  resume 腿降级(warn+跳过——4xx 会砖存量 task;记录不可变 ⇒ 在场行的 notice 字节恒稳)。
- *  notice 路径从**绑定后的全 session 集**推导(与物化共用 materializedRelPaths),只罗列本次引用的文件。 */
 export async function bindAttachmentsForTask(opts) {
     const found = [];
     for (const id of opts.ids) {
@@ -47,8 +41,6 @@ export async function bindAttachmentsForTask(opts) {
     const lines = found.map((r) => `- ${paths.get(r.id) ?? `attachments/${r.name}`} (${r.mime}, ${r.sizeBytes} bytes)`);
     return { notice: `[attachments] ${found.length} uploaded file(s) are available in the \`attachments/\` directory of your working directory:\n${lines.join("\n")}` };
 }
-/** 半场③(env 建立时物化)的可测核。**fail-loud**:objective 已宣告文件在场,静默缺文件=模型按幻影
- *  文件行动,比 env 建立失败更糟 ⇒ 任一写失败即 throw。幂等:重建沙箱/resume 重写同路径同字节。 */
 export async function materializeAttachmentsInto(env, store, sessionId) {
     const atts = await store.listBySession(sessionId);
     if (atts.length === 0)
@@ -102,7 +94,6 @@ export async function ensurePgTaskAttachmentSchema(q) {
     await q(`CREATE INDEX IF NOT EXISTS idx_att_session ON ${TASK_ATTACHMENT_TABLE} (session_id)`);
     await q(`CREATE INDEX IF NOT EXISTS idx_att_unbound ON ${TASK_ATTACHMENT_TABLE} (created_at_ms)`);
 }
-/** bytes → 4 MiB 块序列(共享切块器,两方言 + 完整性校验共用)。 */
 export class TiDBTaskAttachmentStore {
     pool;
     bytes;
@@ -111,8 +102,6 @@ export class TiDBTaskAttachmentStore {
         this.bytes = bytes;
     }
     async put(rec) {
-        // 次序=bytes 先、meta 后:meta 行在场 ⇒ 对象在场(读侧无半态)。对象键=sha256(去重;
-        // MinioBlobBackend putBlob 幂等,重复内容=同键重放)。半途崩溃只留无 meta 的对象——经 API 不可达。
         await this.bytes.putBlob(rec.sha256, rec.content);
         await this.pool.execute(`INSERT INTO ${TASK_ATTACHMENT_TABLE} (${COLS}) VALUES (?,?,?,?,?,?,?,?,?)`, [rec.id, rec.owner, rec.name, rec.mime, rec.sha256, rec.sizeBytes, rec.sessionId ?? null, rec.createdAtMs, rec.boundAtMs ?? null]);
     }
@@ -121,15 +110,12 @@ export class TiDBTaskAttachmentStore {
         return rows.length ? rowToRecord(rows[0]) : null;
     }
     async getContent(owner, id) {
-        const meta = await this.get(owner, id); // owner 门先过(对象键是 sha,不携 owner——门恒在 meta)
+        const meta = await this.get(owner, id);
         if (!meta)
             return null;
-        const b = await this.bytes.getBlob(meta.sha256); // 实现内含 sha 校验(损坏/污染 ⇒ undefined)
+        const b = await this.bytes.getBlob(meta.sha256);
         return b && b.byteLength === meta.sizeBytes ? b : null;
     }
-    /** 零引用对象删除(best-effort):meta 已删后,sha 仍被其他行引用则对象保留(跨行去重共享)。
-     *  失败只吞不抛——E21 purge 不被对象存储抖动卡死(blob-backend 异步删裁定同旨);无 meta 的对象
-     *  经 API 不可达,彻底清收敛记 follow-up。 */
     async deleteBytesIfUnreferenced(shas) {
         for (const sha of new Set(shas)) {
             try {
@@ -138,7 +124,6 @@ export class TiDBTaskAttachmentStore {
                     await this.bytes.deleteBlobs([sha]);
             }
             catch {
-                /* best-effort(见上) */
             }
         }
     }
@@ -174,17 +159,10 @@ export class TiDBTaskAttachmentStore {
         await this.deleteBytesIfUnreferenced(rows.map((r) => r.sha256));
         return res.affectedRows ?? 0;
     }
-    /** D-1 孤儿对象彻底 GC(clay 拍 2026-07-28):对象存储列举 × meta 行对账。判据保守三层:
-     *  ①只删**真列举到**且 ②零 meta 行引用 且 ③LastModified 过 grace 的对象(上传先行窗口:对象先落、
-     *  meta 行后写——grace 护住 put 竞态,宁漏勿误删,下轮再收);列举失败=整轮 throw(调用方 catch,
-     *  「列不出来」绝不当「没有孤儿」)。 */
     async sweepOrphanObjects(graceMs, nowMs = Date.now()) {
         const lister = this.bytes;
         if (typeof lister.listObjects !== "function")
-            return 0; // 无列举面=无孤儿类(local/桩)
-        // 🔴 复审 F2:**边列举边消费**——grace 判据是「对象年龄」不是「孤儿性」,稳态下整个存量语料
-        // (凡超过 grace)都会先进候选集;攒满再分批 ⇒ 内存与语料同阶(20 万对象实测堆 Δ58MB,百万级
-        // ≈290MB,且每 tick 每副本各一份)。改成满 200 就消费,峰值降到 O(200)。
+            return 0;
         let removed = 0;
         let batch = [];
         const flush = async () => {
@@ -192,11 +170,6 @@ export class TiDBTaskAttachmentStore {
                 return;
             const referenced = await this.referencedShas(batch);
             const orphans = batch.filter((h) => !referenced.has(h));
-            // 🔴 复审 B-F1(数据安全):**删前逐对象复查**。grace 只在列举时刻判过一次,而
-            // 「referencedShas 判零引用 → deleteBlobs」之间落地的同 sha 上传(内容去重 ⇒ 同 key)会让
-            // meta 行在场而对象被本轮删掉 = 永久丢字节(getContent 恒 null、物化 fail-loud)。put 会 PUT
-            // 同键刷新 LastModified,所以删前再 HEAD 一次即可识别;窗口压到 HEAD→DELETE 毫秒级。
-            // 无 headObject 面 ⇒ 保守**不删**(宁留孤儿不误删)。
             const safe = await this.filterStillOrphan(orphans, graceMs, nowMs);
             if (safe.length > 0)
                 removed += await this.bytes.deleteBlobs(safe);
@@ -212,7 +185,6 @@ export class TiDBTaskAttachmentStore {
         await flush();
         return removed;
     }
-    /** sweep 的引用对账半场:批内 sha 中仍有 meta 行的子集(单 IN 查询;DISTINCT 免重复行膨胀)。 */
     async referencedShas(shas) {
         if (shas.length === 0)
             return new Set();
@@ -220,8 +192,6 @@ export class TiDBTaskAttachmentStore {
         const [rows] = await this.pool.query(`SELECT DISTINCT sha256 FROM ${TASK_ATTACHMENT_TABLE} WHERE sha256 IN (${ph})`, shas);
         return new Set(rows.map((r) => String(r.sha256)));
     }
-    /** 删前复查(复审 B-F1):只保留「HEAD 仍在 且 LastModified 仍过 grace」的 hash。无 headObject
-     *  面 ⇒ 返回空集(保守不删);HEAD 抛错 ⇒ 该对象本轮跳过(下轮再收)。 */
     async filterStillOrphan(hashes, graceMs, nowMs) {
         if (hashes.length === 0)
             return [];
@@ -236,7 +206,6 @@ export class TiDBTaskAttachmentStore {
                     out.push(h);
             }
             catch {
-                /* 复查失败=本轮跳过(宁漏勿误删) */
             }
         }
         return out;
@@ -250,7 +219,6 @@ export class PgTaskAttachmentStore {
         this.bytes = bytes;
     }
     async put(rec) {
-        // bytes 先、meta 后(TiDB 同姿,注同)
         await this.bytes.putBlob(rec.sha256, rec.content);
         await this.q(`INSERT INTO ${TASK_ATTACHMENT_TABLE} (${COLS}) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9)`, [rec.id, rec.owner, rec.name, rec.mime, rec.sha256, rec.sizeBytes, rec.sessionId ?? null, rec.createdAtMs, rec.boundAtMs ?? null]);
     }
@@ -273,14 +241,12 @@ export class PgTaskAttachmentStore {
                     await this.bytes.deleteBlobs([sha]);
             }
             catch {
-                /* best-effort(TiDB 同注) */
             }
         }
     }
     async bind(owner, ids, sessionId, boundAtMs) {
         if (ids.length === 0)
             return 0;
-        // PgQueryFn 有意无 rowCount(pg-query.ts 契约)⇒ RETURNING id 数行
         const res = await this.q(`UPDATE ${TASK_ATTACHMENT_TABLE} SET session_id = $1, bound_at_ms = $2 WHERE owner = $3 AND id = ANY($4::varchar[]) RETURNING id`, [sessionId, boundAtMs, owner, ids]);
         return res.rows.length;
     }
@@ -305,14 +271,10 @@ export class PgTaskAttachmentStore {
         await this.deleteBytesIfUnreferenced(res.rows.map((r) => r.sha256));
         return res.rows.length;
     }
-    /** D-1 孤儿对象彻底 GC —— twin of the TiDB store(判据三层同注:真列举/零引用/过 grace)。 */
     async sweepOrphanObjects(graceMs, nowMs = Date.now()) {
         const lister = this.bytes;
         if (typeof lister.listObjects !== "function")
             return 0;
-        // 🔴 复审 F2:**边列举边消费**——grace 判据是「对象年龄」不是「孤儿性」,稳态下整个存量语料
-        // (凡超过 grace)都会先进候选集;攒满再分批 ⇒ 内存与语料同阶(20 万对象实测堆 Δ58MB,百万级
-        // ≈290MB,且每 tick 每副本各一份)。改成满 200 就消费,峰值降到 O(200)。
         let removed = 0;
         let batch = [];
         const flush = async () => {
@@ -320,11 +282,6 @@ export class PgTaskAttachmentStore {
                 return;
             const referenced = await this.referencedShas(batch);
             const orphans = batch.filter((h) => !referenced.has(h));
-            // 🔴 复审 B-F1(数据安全):**删前逐对象复查**。grace 只在列举时刻判过一次,而
-            // 「referencedShas 判零引用 → deleteBlobs」之间落地的同 sha 上传(内容去重 ⇒ 同 key)会让
-            // meta 行在场而对象被本轮删掉 = 永久丢字节(getContent 恒 null、物化 fail-loud)。put 会 PUT
-            // 同键刷新 LastModified,所以删前再 HEAD 一次即可识别;窗口压到 HEAD→DELETE 毫秒级。
-            // 无 headObject 面 ⇒ 保守**不删**(宁留孤儿不误删)。
             const safe = await this.filterStillOrphan(orphans, graceMs, nowMs);
             if (safe.length > 0)
                 removed += await this.bytes.deleteBlobs(safe);
@@ -347,8 +304,6 @@ export class PgTaskAttachmentStore {
         const r = await this.q(`SELECT DISTINCT sha256 FROM ${TASK_ATTACHMENT_TABLE} WHERE sha256 IN (${ph})`, shas);
         return new Set(r.rows.map((row) => String(row.sha256)));
     }
-    /** 删前复查(复审 B-F1):只保留「HEAD 仍在 且 LastModified 仍过 grace」的 hash。无 headObject
-     *  面 ⇒ 返回空集(保守不删);HEAD 抛错 ⇒ 该对象本轮跳过(下轮再收)。 */
     async filterStillOrphan(hashes, graceMs, nowMs) {
         if (hashes.length === 0)
             return [];
@@ -363,7 +318,6 @@ export class PgTaskAttachmentStore {
                     out.push(h);
             }
             catch {
-                /* 复查失败=本轮跳过(宁漏勿误删) */
             }
         }
         return out;

package/dist/plugins/task-list-store-sql.js

@@ -1,62 +1,13 @@
-/**
- * TaskListStore SQL twins(design/151 S3c server pg 半场,[1530] 提货单②)——core 团队共享任务
- * 清单(TaskCreate/TaskUpdate/TaskList 工具族)的 TiDB/PG 双方言实现。挂载缝 = S3c 行为车定
- * (createTaskListTools(store) 已收 store 参数);本文件先就绪 store 半场。
- *
- * 语义真源 = core file 实现(dist/stores/file/task-list-store.js,durable 对 durable)+ [1530] 定谳:
- *  1. **`mutate` 必须后端事务原子**(接口 JSDoc codex S4 F2 句):read-modify-write 全序列进一个
- *     事务;分区锁 = meta 行 `SELECT … FOR UPDATE`(天然 advisory lock,同清单 mutate 串行)。
- *  2. **nextId 只增不回退、与分配同事务**(删最高 id 不复用):`task_list_meta` 单行携 `next_id`,
- *     **永不从存量 MAX 派生**。
- *  3. metadata = JSON 列(`assertJsonMetadata` 在 set 面拦,file/memory 同形);id 任意 string
- *     (工具层走 allocateId 产数字串,接口不排除外部 id)。
- *
- * `list` 序:两个 core 参照本就不同(memory=Map 纯插入序;file=JS 对象序 = integer-like 键数字
- * 升序、其余按插入序殿后)——SQL twin 对齐 **file 形**(durable 参照):`id_num` 物化列(canonical
- * array-index 形才非 NULL)数字升序,非数字 id 按 `sort_seq`(插入序)殿后。set 覆盖已有 id 保位
- * (sort_seq 不变)= 两参照一致的保位语义。`sort_seq` 从 **meta 行计数器同事务分配**(复审 F6:
- * TiDB AUTO_INCREMENT 按 tidb-server 分段缓存,跨节点不单调——「插入序」在多网关部署下会倒序;
- * meta 计数器 = allocateId 同姿势,真单调;覆盖写浪费一个号,单调性无损)。
- *
- * 分区键 `listKey` = 构造参数(file 形的 root 目录对位):谁的清单由挂载点决定(per-team 组装,
- * S3c 行为车),store 层只管字节隔离(VARBINARY / COLLATE "C",roster F2 案)。PG unstorable
- * bytes([1439]):item 正文(subject/description/metadata)= 内容面 lossy(pgSafeJsonStringify,
- * U+FFFD);**身份键 listKey/id 拒绝式**(清洗形变 = 行与查询键错位)。TiDB verbatim。
- */
 import { createHash } from "node:crypto";
-// assertJsonMetadata:core 1.374 起包根导出([1531]§一3——私拷镜像即换,DURABLE_AGENT_HANDLE_RE 同姿势)。
 import { assertJsonMetadata } from "@sema-agent/core";
 import { pgHasUnstorable, pgSafeJsonStringify, PgUnstorableError } from "./pg-safe-json.js";
 export const TASK_LIST_META_TABLE = "task_list_meta";
 export const TASK_LIST_ITEM_TABLE = "task_list_item";
-/**
- * #318 `sessionId ↦ 本表的身份键`:`session:<可读前缀>-<sha256(sessionId) 前 16 位>`。
- *
- * 🔴 为什么不直接把 sessionId 当 listKey:sessionId 是**调用方可自报**的不透明串(提交门
- * `http/server.ts` 只卡 ≤64 **字符** —— [#15] 刻意的宽松提交契约,不卡字节数也不卡字符集)。
- * 而本文件的身份键是字节面严格的:{@link assertListKeyBytes} 对 >190 字节当场拒(TiDB
- * `INSERT IGNORE` 静默截断案),PG twin 对孤代理/NUL 走 {@link PgUnstorableError} 拒。直接透传
- * 的话,一个 64 字符全四字节 emoji 的会话(256 字节)会让**整条请求**在场景装配处 500 —— 而那条腿
- * 只是待办清单。派生一个恒可存的键把这一整类失败模式消掉(既不是 fail-open 也不是 fail-loud,是让
- * 那条臂不存在)。
- *
- * 判据:确定性(同 sessionId 跨副本/跨重启恒同键)、字节安全(纯 ASCII,≤ 8+24+1+16 = 49 字节)、
- * 抗碰撞(摘要取**全串**,可读前缀只为运维肉眼对账)。
- *
- * `session:` 是**命名空间**位:design/147 §6 D2 的团队共享清单将来若按 team 分区,两族键同表不撞。
- * 同族先例 = `env-facts.ts` 的 `scratchpadSessionSegment`(文件名面)——刻意**不**复用彼此的实现:
- * 一个键空间改了算法不该把另一个键空间的存量行全孤儿化。
- *
- * 🔴 属主在**本文件**(而不是消费它的 boot 车道):留存腿(`retention-store-sql.ts`)按同一派生式
- * 批量删本表的行,两个消费点必须读同一个函数 —— 键派生有两份就是「在线删除删得掉、留存腿删不掉」。
- */
 export function taskListKeyFor(sessionId) {
     const readable = sessionId.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 24);
     const digest = createHash("sha256").update(sessionId).digest("hex").slice(0, 16);
     return `session:${readable.length > 0 ? readable : "_"}-${digest}`;
 }
-/** JS 对象 integer-like(array-index)键判別——file 参照的遍历序里数字升序的那一族:canonical
- *  十进制、0 ≤ n < 2^32-1。"01"/"1e3"/负数/超界 = 普通串键(插入序殿后)。 */
 function arrayIndexOf(id) {
     if (!/^(0|[1-9][0-9]*)$/.test(id))
         return null;
@@ -66,16 +17,12 @@ function arrayIndexOf(id) {
 function parseItem(v) {
     return JSON.parse(String(v));
 }
-/** 键长守卫(mailbox twin F5 同案):TiDB `INSERT IGNORE` 对超 190 字节键静默截断——截断 listKey
- *  与全长查询参数字节比对恒 miss(mutate 拿不到分区锁 = 无锁运行)。构造点一次拒清。item 的 id
- *  列超长走非 IGNORE 语句 = 两方言原生 fail-loud,无需前置守卫。 */
 function assertListKeyBytes(listKey) {
     if (Buffer.byteLength(listKey, "utf8") > 190) {
         throw new Error(`TaskListStore: listKey exceeds the 190-byte key column (refusing — a truncated key would desync from its byte-exact lookups)`);
     }
 }
 export async function ensureTiDBTaskListSchema(pool) {
-    // next_sort = sort_seq 计数器(F6:不用 AUTO_INCREMENT——TiDB 分段缓存跨节点不单调)。
     await pool.query(`CREATE TABLE IF NOT EXISTS ${TASK_LIST_META_TABLE} (
     list_key VARBINARY(190) NOT NULL,
     next_id BIGINT NOT NULL,
@@ -107,14 +54,11 @@ export async function ensurePgTaskListSchema(q) {
     PRIMARY KEY (list_key, id)
   )`);
 }
-/** meta 行 ensure(ensure-first 形:先幂等 INSERT 再 FOR UPDATE——「无行 FOR UPDATE + INSERT」的
- *  经典并发死锁/dup 撞车形整个消掉;mutate 已持 meta 行锁时重入 = 同事务无害)。 */
 async function ensureMeta(exec, dialect, listKey) {
     await exec(dialect === "tidb"
         ? `INSERT IGNORE INTO ${TASK_LIST_META_TABLE} (list_key, next_id, next_sort) VALUES (?, 1, 1)`
         : `INSERT INTO ${TASK_LIST_META_TABLE} (list_key, next_id, next_sort) VALUES ($1, 1, 1) ON CONFLICT (list_key) DO NOTHING`, [listKey]);
 }
-/** 事务内的 nextId 分配(定谳 2:与分配同事务、永不 MAX 派生)。 */
 async function allocateOn(exec, dialect, listKey) {
     await ensureMeta(exec, dialect, listKey);
     const rows = await exec(dialect === "tidb"
@@ -126,8 +70,6 @@ async function allocateOn(exec, dialect, listKey) {
         : `UPDATE ${TASK_LIST_META_TABLE} SET next_id = $1 WHERE list_key = $2`, [id + 1, listKey]);
     return String(id);
 }
-/** 事务内的 set(F6:sort_seq 从 meta 计数器分配,与写同事务——meta 行锁顺带把同清单写串行;
- *  覆盖写时 ON DUPLICATE/CONFLICT 不动 sort_seq(保位),浪费的号只增不回,单调性无损)。 */
 async function setOn(exec, dialect, listKey, id, itemJson) {
     await ensureMeta(exec, dialect, listKey);
     const rows = await exec(dialect === "tidb"
@@ -143,17 +85,6 @@ async function setOn(exec, dialect, listKey, id, itemJson) {
         ? `UPDATE ${TASK_LIST_META_TABLE} SET next_sort = ? WHERE list_key = ?`
         : `UPDATE ${TASK_LIST_META_TABLE} SET next_sort = $1 WHERE list_key = $2`, [sort + 1, listKey]);
 }
-/**
- * 整份清单删除(#318 / E21 会话删除级联;codex R1-[high] 验真后加)。
- *
- * 语义 = 「这个 listKey 的清单**不存在过**」:item 行 + meta 行(高水位 `next_id` / 插入序
- * `next_sort`)一并抹掉。⚠️ **meta 行必须一起删**:留着它,同一个 listKey 被重新登记后
- * (会话 id 由调用方自选、删除后可被别人 `register`)新主的第一条任务会从旧主的高水位续号 ——
- * 那是一条跨化身的信息泄漏(「上一位在这里建过 47 条」)。
- *
- * 事务内先对 meta 行 `FOR UPDATE`(与 `mutate` 同一把分区锁)⇒ 与并发的清单写串行,不会删到
- * 一半被插回新行。meta 行不在(从未写过任何任务)= 无锁可拿,DELETE 命中 0 行,幂等。
- */
 export async function deleteTiDBTaskList(pool, listKey) {
     assertListKeyBytes(listKey);
     const c = await pool.getConnection();
@@ -172,7 +103,6 @@ export async function deleteTiDBTaskList(pool, listKey) {
         c.release();
     }
 }
-/** {@link deleteTiDBTaskList} 的 PG 孪生(同语义、同事务姿势)。 */
 export async function deletePgTaskList(pool, listKey) {
     if (pgHasUnstorable(listKey))
         throw new PgUnstorableError("task-list listKey");
@@ -215,9 +145,6 @@ export function createTiDBTaskListStore(pool, listKey) {
         const [rows] = (await q.query(sql, params));
         return rows;
     };
-    // mutate 事务内的读必须**当前读**(FOR UPDATE):TiDB 悲观事务的普通 SELECT 按 start_ts 快照读
-    // (事务开始时点)——分区锁串行后普通读仍看见开锁前的旧值,read-modify-write 静默丢更新(真双库
-    // 套件抓获:8 并发 increment 终值 1)。MySQL 的快照点(首次快照读)不同但同修;顶层单语句无此臂。
     const build = (q, inTx) => ({
         get: async (id) => {
             const [rows] = (await q.query(`SELECT item_json FROM ${TASK_LIST_ITEM_TABLE} WHERE list_key = ? AND id = ?${inTx ? " FOR UPDATE" : ""}`, [listKey, id]));
@@ -242,7 +169,6 @@ export function createTiDBTaskListStore(pool, listKey) {
             ? {}
             : {
                 mutate: (fn) => tx(async (c) => {
-                    // 分区锁(定谳 1):ensure + FOR UPDATE——同 listKey 的并发 mutate 在此串行。
                     await ensureMeta(execOn(c), "tidb", listKey);
                     await c.query(`SELECT next_id FROM ${TASK_LIST_META_TABLE} WHERE list_key = ? FOR UPDATE`, [listKey]);
                     return fn(build(c, true));
@@ -275,17 +201,12 @@ export function createPgTaskListStore(pool, listKey) {
         const res = await q.query(sql, params);
         return res.rows;
     };
-    // 事务内当前读(TiDB 侧同注——PG READ COMMITTED 语句级快照本已看见锁前提交,FOR UPDATE 统一
-    // 双方言姿势,顺带把行锁真拿住)。
     const build = (q, inTx) => ({
         get: async (id) => {
             const { rows } = await q.query(`SELECT item_json FROM ${TASK_LIST_ITEM_TABLE} WHERE list_key = $1 AND id = $2${inTx ? " FOR UPDATE" : ""}`, [listKey, id]);
             return rows.length > 0 ? parseItem(rows[0].item_json) : undefined;
         },
         set: async (id, item) => {
-            // 身份/引用键拒绝式(复审 F8):行键 id 之外,blob 内的 item.id/owner(工具层 ifOwnerIs 守卫
-            // 的比对对象)与 blocks/blockedBy(id 引用)清洗形变会与真实键错位——同落拒绝层;正文
-            // (subject/description/metadata)维持内容面 lossy。
             if (pgHasUnstorable(id) ||
                 pgHasUnstorable(item.id) ||
                 (item.owner !== undefined && pgHasUnstorable(item.owner)) ||

package/dist/plugins/tidb-cost-quota.js

@@ -1,7 +1,6 @@
 import { WriteBehindCounter } from "./write-behind-counter.js";
 export class TiDBCostQuota {
     counter;
-    /** #322:限额=比较参数(行里只有花费);窗长换代经 counter.setWindowMs(桶键语义见那里)。 */
     limitMicroUsd;
     refreshRequested = false;
     refreshIntervalMs;
@@ -23,7 +22,6 @@ export class TiDBCostQuota {
             this.counter.stop();
     }
     check(scopeKey) {
-        // 关断哨兵:零 counter 访问、零 SQL(恒构造的代价必须是 0)。
         if (this.limitMicroUsd <= 0)
             return { allowed: true, usedMicroUsd: 0, limitMicroUsd: 0, retryAfterSec: 0 };
         const used = this.counter.used(scopeKey);
@@ -32,10 +30,9 @@ export class TiDBCostQuota {
     }
     add(scopeKey, micro) {
         if (this.limitMicroUsd <= 0)
-            return; // off ⇒ 不攒本地增量(也就没有要 flush 的东西)
+            return;
         this.counter.addLocal(scopeKey, micro);
     }
-    // write-behind lifecycle (delegated; exposed for the reaper/tests)
     flush() {
         return this.counter.flush();
     }