@sema-agent/server 1.322.0 → 2.0.0

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

@@ -1,4 +1,7 @@
 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();
@@ -23,6 +26,9 @@ 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) {
@@ -41,6 +47,8 @@ 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)
@@ -94,6 +102,7 @@ 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;
@@ -102,6 +111,8 @@ 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]);
     }
@@ -110,12 +121,15 @@ export class TiDBTaskAttachmentStore {
         return rows.length ? rowToRecord(rows[0]) : null;
     }
     async getContent(owner, id) {
-        const meta = await this.get(owner, id);
+        const meta = await this.get(owner, id); // owner 门先过(对象键是 sha,不携 owner——门恒在 meta)
         if (!meta)
             return null;
-        const b = await this.bytes.getBlob(meta.sha256);
+        const b = await this.bytes.getBlob(meta.sha256); // 实现内含 sha 校验(损坏/污染 ⇒ undefined)
         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 {
@@ -124,6 +138,7 @@ export class TiDBTaskAttachmentStore {
                     await this.bytes.deleteBlobs([sha]);
             }
             catch {
+                /* best-effort(见上) */
             }
         }
     }
@@ -159,10 +174,17 @@ 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;
+            return 0; // 无列举面=无孤儿类(local/桩)
+        // 🔴 复审 F2:**边列举边消费**——grace 判据是「对象年龄」不是「孤儿性」,稳态下整个存量语料
+        // (凡超过 grace)都会先进候选集;攒满再分批 ⇒ 内存与语料同阶(20 万对象实测堆 Δ58MB,百万级
+        // ≈290MB,且每 tick 每副本各一份)。改成满 200 就消费,峰值降到 O(200)。
         let removed = 0;
         let batch = [];
         const flush = async () => {
@@ -170,6 +192,11 @@ 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);
@@ -185,6 +212,7 @@ export class TiDBTaskAttachmentStore {
         await flush();
         return removed;
     }
+    /** sweep 的引用对账半场:批内 sha 中仍有 meta 行的子集(单 IN 查询;DISTINCT 免重复行膨胀)。 */
     async referencedShas(shas) {
         if (shas.length === 0)
             return new Set();
@@ -192,6 +220,8 @@ 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 [];
@@ -206,6 +236,7 @@ export class TiDBTaskAttachmentStore {
                     out.push(h);
             }
             catch {
+                /* 复查失败=本轮跳过(宁漏勿误删) */
             }
         }
         return out;
@@ -219,6 +250,7 @@ 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]);
     }
@@ -241,12 +273,14 @@ 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;
     }
@@ -271,10 +305,14 @@ 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 () => {
@@ -282,6 +320,11 @@ 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);
@@ -304,6 +347,8 @@ 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 [];
@@ -318,6 +363,7 @@ export class PgTaskAttachmentStore {
                     out.push(h);
             }
             catch {
+                /* 复查失败=本轮跳过(宁漏勿误删) */
             }
         }
         return out;

package/dist/plugins/task-list-store-sql.d.ts

@@ -1,3 +1,28 @@
+/**
+ * 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 type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type TaskListStore } from "@sema-agent/core";

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

@@ -1,7 +1,10 @@
+// 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_ITEMS_TABLE = "task_list_items";
+/** 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;
@@ -11,12 +14,16 @@ 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,
@@ -48,11 +55,14 @@ 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"
@@ -64,6 +74,8 @@ 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"
@@ -101,6 +113,9 @@ 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_ITEMS_TABLE} WHERE list_key = ? AND id = ?${inTx ? " FOR UPDATE" : ""}`, [listKey, id]));
@@ -125,6 +140,7 @@ 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));
@@ -157,12 +173,17 @@ 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_ITEMS_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-approval-store.d.ts

@@ -1,2 +1,8 @@
+/**
+ * Thin re-export shim (design/158 A12 收编 — see src/plugins/approval-store-sql.ts for the
+ * implementation, now SINGLE-FILE DUAL-DIALECT). Class name, ctor arity, and every exported
+ * type/helper stay EXACTLY as they were so no consumer (store-backend.ts, src/index.ts, the
+ * approval/audit/security-coverage suites) has to move.
+ */
 export { TiDBApprovalStore, mapRow, type ApprovalRow, type ApprovalStatus, } from "./approval-store-sql.js";
 //# sourceMappingURL=tidb-approval-store.d.ts.map

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

@@ -1,2 +1,8 @@
+/**
+ * Thin re-export shim (design/158 A12 收编 — see src/plugins/approval-store-sql.ts for the
+ * implementation, now SINGLE-FILE DUAL-DIALECT). Class name, ctor arity, and every exported
+ * type/helper stay EXACTLY as they were so no consumer (store-backend.ts, src/index.ts, the
+ * approval/audit/security-coverage suites) has to move.
+ */
 export { TiDBApprovalStore, mapRow, } from "./approval-store-sql.js";
 //# sourceMappingURL=tidb-approval-store.js.map

package/dist/plugins/tidb-breaker-state.d.ts

@@ -1,2 +1,7 @@
+/**
+ * Re-export shim (design/158 A12 收编) — the real implementation moved to breaker-state-sql.ts
+ * (single-file dual-dialect: `SqlBreakerState` + the `TiDBBreakerState`/`PgBreakerState` ctor subclasses).
+ * Kept so every consumer's `from "./tidb-breaker-state.js"` import keeps working unchanged.
+ */
 export { TiDBBreakerState } from "./breaker-state-sql.js";
 //# sourceMappingURL=tidb-breaker-state.d.ts.map

package/dist/plugins/tidb-breaker-state.js

@@ -1,2 +1,7 @@
+/**
+ * Re-export shim (design/158 A12 收编) — the real implementation moved to breaker-state-sql.ts
+ * (single-file dual-dialect: `SqlBreakerState` + the `TiDBBreakerState`/`PgBreakerState` ctor subclasses).
+ * Kept so every consumer's `from "./tidb-breaker-state.js"` import keeps working unchanged.
+ */
 export { TiDBBreakerState } from "./breaker-state-sql.js";
 //# sourceMappingURL=tidb-breaker-state.js.map

package/dist/plugins/tidb-checkpoint-store.d.ts

@@ -1,2 +1,9 @@
+/**
+ * MySQL-protocol (TiDB) `CheckpointStore` — the implementation now lives in the single-file dual-dialect
+ * `checkpoint-store-sql.ts` (design/158 A12 定型半场). This file is the historical import path: the class
+ * name, ctor shape and the backend-NEUTRAL helpers the LOCAL twin shares (TERMINAL_BACKSTOP_MS /
+ * TERMINAL_GRACE_MS / tokenFingerprint / boundedToolInput / PendingCheckpoint) are re-exported unchanged,
+ * so local-checkpoint-store.ts, store-backend.ts, the dogfood script and every suite are untouched.
+ */
 export { TiDBCheckpointStore, SqlCheckpointStore, TERMINAL_BACKSTOP_MS, TERMINAL_GRACE_MS, tokenFingerprint, boundedToolInput, type PendingCheckpoint, } from "./checkpoint-store-sql.js";
 //# sourceMappingURL=tidb-checkpoint-store.d.ts.map

package/dist/plugins/tidb-checkpoint-store.js

@@ -1,2 +1,9 @@
+/**
+ * MySQL-protocol (TiDB) `CheckpointStore` — the implementation now lives in the single-file dual-dialect
+ * `checkpoint-store-sql.ts` (design/158 A12 定型半场). This file is the historical import path: the class
+ * name, ctor shape and the backend-NEUTRAL helpers the LOCAL twin shares (TERMINAL_BACKSTOP_MS /
+ * TERMINAL_GRACE_MS / tokenFingerprint / boundedToolInput / PendingCheckpoint) are re-exported unchanged,
+ * so local-checkpoint-store.ts, store-backend.ts, the dogfood script and every suite are untouched.
+ */
 export { TiDBCheckpointStore, SqlCheckpointStore, TERMINAL_BACKSTOP_MS, TERMINAL_GRACE_MS, tokenFingerprint, boundedToolInput, } from "./checkpoint-store-sql.js";
 //# sourceMappingURL=tidb-checkpoint-store.js.map

package/dist/plugins/tidb-cost-quota.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Cross-replica per-key CUMULATIVE cost quota (design/30 P0-1). A thin {@link QuotaTracker} over the
+ * shared {@link WriteBehindCounter}: atomic write-behind aggregation, eventually consistent (SOFT
+ * limiting — boundary overspend is bounded by the flush interval and backstopped by the HARD per-task
+ * `maxCostUsd` gate). `scope_key` is opaque (principal today; team/feature later — design/30 N3).
+ */
 import type { Pool } from "mysql2/promise";
 import type { QuotaDecision, QuotaTracker } from "../observability/cost-quota.js";
 import { type CounterDegradeHook } from "./write-behind-counter.js";

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

@@ -14,6 +14,7 @@ export class TiDBCostQuota {
     add(scopeKey, micro) {
         this.counter.addLocal(scopeKey, micro);
     }
+    // write-behind lifecycle (delegated; exposed for the reaper/tests)
     flush() {
         return this.counter.flush();
     }

package/dist/plugins/tidb-file-snapshot-store.d.ts

@@ -1,2 +1,8 @@
+/**
+ * Thin re-export shim (design/158 A12 定型半场) — the real implementation collapsed into
+ * `file-snapshot-store-sql.ts` (single file, dual dialect). Kept so every existing import path
+ * (store-backend.ts, the migration script, the contract/integration/minio-equivalence suites) is
+ * untouched: same class name, same ctor arity, same exported surface.
+ */
 export { TiDBFileSnapshotStore } from "./file-snapshot-store-sql.js";
 //# sourceMappingURL=tidb-file-snapshot-store.d.ts.map

package/dist/plugins/tidb-file-snapshot-store.js

@@ -1,2 +1,8 @@
+/**
+ * Thin re-export shim (design/158 A12 定型半场) — the real implementation collapsed into
+ * `file-snapshot-store-sql.ts` (single file, dual dialect). Kept so every existing import path
+ * (store-backend.ts, the migration script, the contract/integration/minio-equivalence suites) is
+ * untouched: same class name, same ctor arity, same exported surface.
+ */
 export { TiDBFileSnapshotStore } from "./file-snapshot-store-sql.js";
 //# sourceMappingURL=tidb-file-snapshot-store.js.map

package/dist/plugins/tidb-image-bake.d.ts

@@ -1,3 +1,11 @@
+/**
+ * MySQL-protocol (TiDB) BAKE store — the implementation now lives in the single-file dual-dialect
+ * `image-bake-store-sql.ts` (design/158 A12 定型半场). This file is the historical import path: the
+ * class name, ctor shape and every re-exported contract are unchanged, so no consumer moved.
+ *
+ * New code should import from `./image-bake-store-sql.js` (both dialects) and take its CONTRACTS from
+ * `./store-contracts.js` (backend-neutral, design/158 A3 沉底).
+ */
 export { TiDBImageBake, SqlImageBake } from "./image-bake-store-sql.js";
 export type { BakeStatus, BakeState, BakeErrorCode, BakeRecord, BakeEvent, CreateBakeInput, BakeTerminal, BakeRow, } from "./store-contracts.js";
 export { mapBakeRow as mapRow, BAKE_SELECT_COLS as SELECT_COLS } from "./store-contracts.js";

package/dist/plugins/tidb-image-bake.js

@@ -1,3 +1,11 @@
+/**
+ * MySQL-protocol (TiDB) BAKE store — the implementation now lives in the single-file dual-dialect
+ * `image-bake-store-sql.ts` (design/158 A12 定型半场). This file is the historical import path: the
+ * class name, ctor shape and every re-exported contract are unchanged, so no consumer moved.
+ *
+ * New code should import from `./image-bake-store-sql.js` (both dialects) and take its CONTRACTS from
+ * `./store-contracts.js` (backend-neutral, design/158 A3 沉底).
+ */
 export { TiDBImageBake, SqlImageBake } from "./image-bake-store-sql.js";
 export { mapBakeRow as mapRow, BAKE_SELECT_COLS as SELECT_COLS } from "./store-contracts.js";
 //# sourceMappingURL=tidb-image-bake.js.map

package/dist/plugins/tidb-image-index.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Sandbox-image-pool INDEX store (IMAGE-API-DESIGN.md §1, pool design §8).
+ *
+ * Thin re-export shim (design/158 A12 定型半场): the real implementation is the single-file dual-dialect
+ * `image-index-sql.ts` (`SqlImageIndex` + this file's `TiDBImageIndex` ctor subclass). Class name, ctor
+ * arity, and the exported type/helper surface are UNCHANGED — every consumer (store-backend.ts, the unit +
+ * real-DB integration suites) imports from here exactly as before.
+ */
 export { TiDBImageIndex } from "./image-index-sql.js";
 export type { ImageNestedBuildMode, ImageCapabilities, ImagePodContract, ImageStatus, ImageVisibility, ImageIndexEntry, ImageIndexUpsert, ImageViewer, ImageListFilter, ImageRow, } from "./store-contracts.js";
 export { mapImageRow as mapRow } from "./store-contracts.js";

package/dist/plugins/tidb-image-index.js

@@ -1,3 +1,11 @@
+/**
+ * Sandbox-image-pool INDEX store (IMAGE-API-DESIGN.md §1, pool design §8).
+ *
+ * Thin re-export shim (design/158 A12 定型半场): the real implementation is the single-file dual-dialect
+ * `image-index-sql.ts` (`SqlImageIndex` + this file's `TiDBImageIndex` ctor subclass). Class name, ctor
+ * arity, and the exported type/helper surface are UNCHANGED — every consumer (store-backend.ts, the unit +
+ * real-DB integration suites) imports from here exactly as before.
+ */
 export { TiDBImageIndex } from "./image-index-sql.js";
 export { mapImageRow as mapRow } from "./store-contracts.js";
 //# sourceMappingURL=tidb-image-index.js.map

package/dist/plugins/tidb-outcome-ledger.d.ts

@@ -1,2 +1,12 @@
+/**
+ * MySQL-protocol (TiDB) outcome ledger — the implementation now lives in the single-file dual-dialect
+ * `outcome-ledger-sql.ts` (design/158 A12 定型半场), alongside its PG twin so the dialect deltas
+ * (placeholders, JSON encode, the AVG boolean-coercion divergence) read side by side instead of
+ * drifting across two files.
+ *
+ * This file is the historical import path: class name, ctor shape, the shared types and the pure
+ * helpers (`taskSignature` / `deriveOutcome` / `coreOutcomeToLedgerRow`) are unchanged, so
+ * store-backend.ts, the pg twin, and every suite are untouched.
+ */
 export { TiDBOutcomeLedger, taskSignature, deriveOutcome, coreOutcomeToLedgerRow, type MechanicalOutcome, type LlmAssistedOutcome, type SignatureInputs, type RunStatus, type TaskOutcome, } from "./outcome-ledger-sql.js";
 //# sourceMappingURL=tidb-outcome-ledger.d.ts.map

package/dist/plugins/tidb-outcome-ledger.js

@@ -1,2 +1,12 @@
+/**
+ * MySQL-protocol (TiDB) outcome ledger — the implementation now lives in the single-file dual-dialect
+ * `outcome-ledger-sql.ts` (design/158 A12 定型半场), alongside its PG twin so the dialect deltas
+ * (placeholders, JSON encode, the AVG boolean-coercion divergence) read side by side instead of
+ * drifting across two files.
+ *
+ * This file is the historical import path: class name, ctor shape, the shared types and the pure
+ * helpers (`taskSignature` / `deriveOutcome` / `coreOutcomeToLedgerRow`) are unchanged, so
+ * store-backend.ts, the pg twin, and every suite are untouched.
+ */
 export { TiDBOutcomeLedger, taskSignature, deriveOutcome, coreOutcomeToLedgerRow, } from "./outcome-ledger-sql.js";
 //# sourceMappingURL=tidb-outcome-ledger.js.map

package/dist/plugins/tidb-pool.d.ts

@@ -1,11 +1,67 @@
 import mysql from "mysql2/promise";
 import type { Pool, PoolConnection } from "mysql2/promise";
 import type { ServiceConfig } from "../config-types.js";
+/**
+ * Shared TiDB (MySQL wire-compatible) connection pool for the durable Session center (L1).
+ * Owned by `main.ts`; closed on shutdown.
+ *
+ * Read/write pool — this is the persistence center. (The SQL *tool* given to the model must use a
+ * separate read-only pool/credential; never hand this pool to a tool.)
+ */
+/** Build the mysql2 pool options from TiDB config (pure → unit-testable apart from the live connection). */
 export declare function tidbPoolOptions(tidb: NonNullable<ServiceConfig["tidb"]>): mysql.PoolOptions;
 export declare function createTidbPool(config: ServiceConfig): Pool;
+/**
+ * Idempotent schema. `session_event` is the append-only L1 event log (positional slicing by
+ * `(session_id, seq)`); `session_meta` holds the branch leaf + the optimistic-lock counter
+ * (`leaf_seq`) + tenant `owner`.
+ *
+ * ── SCHEMA POLICY (clay 裁,2026-07-26) ─────────────────────────────────────────────────────────────
+ * 本仓 schema 的唯一真源 = **这份代码**(此数组 + `pg-pool.ts` 的 PG 孪生)。口径:
+ *
+ *  1. **删库重建,不做增量。** 尚未上生产、单人本地,存量库一律 DROP DATABASE 重建;因此这里**不再保留
+ *     任何 `ALTER TABLE` 增量 seam**。历史上的 21 条 ADD COLUMN / 3 条 CREATE INDEX / 1 条 MODIFY COLUMN
+ *     已于 2026-07-26 全部折进下面的 `CREATE TABLE`(它们承载的语义已逐条搬成列上的行内注释 —— 那些注释
+ *     是 pre-migration 行为契约的**唯一书面记录**,删注释 = 丢语义)。
+ *  2. **不许再新增 `ALTER TABLE` seam。** 要改列/加列/改可空性 ⇒ 直接改下面的 `CREATE TABLE`,然后重建库。
+ *     (再开增量通道就等于把「代码是真源」变回「代码 + 一串按时间排的补丁才是真源」。)
+ *  3. 生成的全集 SQL 基线导出到 `docs/schema/baseline-mysql.sql`(由本数组机器生成;它是**产物**,不是真源
+ *     —— 冲突时以本文件为准并重新生成)。
+ *
+ * 注意:`ensureSchema` 仍然保留(建表 + advisory lock + image_bake_admit 种子行),只是语句数组现在是纯
+ * CREATE,不再有 information_schema 探针。
+ */
 export declare const SCHEMA_STATEMENTS: readonly string[];
+/** Named MySQL/TiDB advisory lock that serializes the whole `ensureSchema` DDL run (see below). */
 export declare const ENSURE_SCHEMA_LOCK = "sema_ensure_schema";
+/** Acquire {@link ENSURE_SCHEMA_LOCK} on `conn` (the lock is CONNECTION-level, so the caller MUST then run all the
+ *  serialized work on this SAME connection and release with {@link releaseEnsureSchemaLock}). Returns whether it was
+ *  acquired. Exported so test setup that does ad-hoc DDL (e.g. a DROP-then-recreate) can serialize against
+ *  ensureSchema runs using the IDENTICAL lock.
+ *
+ *  Under heavy concurrency (the integration suite fans ~20 callers at the SAME named lock; or a fleet boots N
+ *  replicas at once) a BLOCKING GET_LOCK(name, 30) would park ~19 sessions in a pessimistic WAIT on TiDB's advisory-
+ *  lock row — which both exhausts TiDB's "pessimistic lock retry limit" (surfacing as a thrown error) AND starves the
+ *  app's OWN `SELECT … FOR UPDATE` paths (image-bake admission/lease) of pessimistic-lock budget. So we acquire
+ *  NON-BLOCKING (GET_LOCK(name, 0) returns 0 immediately if held) and POLL with jittered backoff: one holder, the
+ *  rest sleeping (not blocked in-DB). Return false only after exhausting retries (the caller then DEGRADES to
+ *  unserialized rather than blocking boot forever — the DDL is still individually idempotent). */
 export declare function acquireEnsureSchemaLock(conn: PoolConnection, tag?: string): Promise<boolean>;
+/** Release {@link ENSURE_SCHEMA_LOCK} on `conn` (best-effort — the lock also auto-frees when the connection closes). */
 export declare function releaseEnsureSchemaLock(conn: PoolConnection, tag?: string): Promise<void>;
+/** Create tables if absent (+ seed the image-bake admission sentinel). Safe to call on every startup.
+ *
+ *  Per the SCHEMA POLICY on {@link SCHEMA_STATEMENTS} this is a pure CREATE run — there are NO additive
+ *  ALTER/CREATE-INDEX seams and no information_schema probes any more (2026-07-26): the schema contract is
+ *  drop-and-recreate, so every column / index / nullability lives in its `CREATE TABLE`. Do not reintroduce a
+ *  migration loop here; change the CREATE and rebuild the database.
+ *
+ *  Concurrency: callers run this concurrently — tests fan ALL integration suites out in parallel (each
+ *  beforeAll calls ensureSchema), and in production every replica calls it at boot (`--scale service=4`).
+ *  Concurrent DDL on the SAME table makes TiDB race in its schema catalog. We serialize the entire run
+ *  behind {@link ENSURE_SCHEMA_LOCK} (a named GET_LOCK), which is CONNECTION-level — so the lock AND every
+ *  DDL statement run on the one connection we hold here (pooled `pool.query` could land on a different
+ *  connection and silently void the lock). The DDL semantics are unchanged; only the timing is serialized.
+ */
 export declare function ensureSchema(pool: Pool): Promise<void>;
 //# sourceMappingURL=tidb-pool.d.ts.map