@sema-agent/server 7.43.0 → 7.44.0

package/dist/plugins/retention-lane-store-sql.js

@@ -1,47 +1,15 @@
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
 import { RETENTION_AUDIT_TABLE, RETENTION_HOLD_TABLE, RETENTION_LEASE_TABLE } from "./retention-store-sql.js";
-/** 审计读面的单页上界(与 roster 名册窗同姿势:读面要有界)。 */
 export const RETENTION_AUDIT_MAX_LIMIT = 200;
-/** 审计读面的缺省页大小。 */
 export const RETENTION_AUDIT_DEFAULT_LIMIT = 50;
-/**
- * 执行面的非破坏性 SQL 三组口(双方言;绑定类在文件底部)。
- *
- * 🔴 本类**删不掉任何业务数据** —— 它写的只有 `retention_lease` 的一行、`retention_hold` 的一列、
- * 与 `retention_audit` 的追加行。破坏性的三条腿在车1 的 `SqlRetentionStore` 上,拿本对象够不着。
- */
 export class SqlRetentionLaneStore {
     db;
     constructor(db) {
         this.db = db;
     }
-    /** 方言取文(两条语句都写在调用点;A12 判据)。 */
     q(tidb, pg) {
         return this.db.dialect === "tidb" ? tidb : pg;
     }
-    // ───────────────────────────── ① sweep 租约(§3)─────────────────────────────
-    /**
-     * 抢/续租一次(单行 CAS)。抢到 ⇒ `{held:true, fencingToken}`;别人正持着 ⇒ `{held:false}`,调用方
-     * **本 tick 零写静默跳过**。
-     *
-     * 事务三步,一步不能省:
-     *  ① `INSERT IGNORE`(PG:`ON CONFLICT DO NOTHING`)一条 `expires_at_ms = 0` 的**哨兵行** —— 它永远
-     *     不会改写一条既存租约(两方言的这两个动词都只在缺行时写);
-     *  ② `SELECT … FOR UPDATE` —— 行现在必定存在,锁真的拿得到;
-     *  ③ 判 + `UPDATE`,同事务提交。
-     *
-     * 🔴 为什么必须先造行、而不是「一条 `UPDATE … WHERE expires_at_ms < now OR holder = self`」了事
-     * (设计稿 §3 写的正是那条裸 UPDATE,本实现是它的**收口**,与车1 hold 哨兵是同一条教训):裸 UPDATE
-     * 在**空表**上影响 0 行 —— 于是首启的两个副本都读到「没抢到」,lane 在一个从没跑过的部署上**永远不
-     * 起**(静默,读数是"每 tick 跳过",看上去像"别人在跑")。补一条无条件 INSERT 又会在两副本同拍首启时
-     * 撞 PK。哨兵 + 行锁把两件事一次解决,并且顺带让 fencing token 的自增判据可以在应用层算。
-     *
-     * 🔴 fencing token 只在**抢租**(holder 变了)时自增,续租不动它:token 的语义是「第几轮**执行权**」,
-     * 一个持续持租的副本跑的是同一段连续执行,给它每 tick 换号会让审计上「同一轮的行」看起来跨了很多轮。
-     *
-     * @param holder 本副本的身份(instanceId);同一 holder 再来 = 续租。
-     * @param ttlMs  租约时长 = 2× sweep 间隔(§3)。
-     */
     async acquire(holder, ttlMs, nowMs) {
         const conn = await this.db.connect();
         try {
@@ -52,8 +20,6 @@ export class SqlRetentionLaneStore {
             const curHolder = String(cur?.holder ?? "");
             const curToken = Number(cur?.fencing_token ?? 0);
             const expiresAtMs = Number(cur?.expires_at_ms ?? 0);
-            // 别人持着且还没过期 ⇒ 不抢(**过期判据用 `>` 而不是 `>=`**:恰好到点的那一刻租约已经不再有效,
-            // 而 `>=` 会让两个副本在同一毫秒上各自认为对方还持着 —— 都不抢,lane 停摆一拍)。
             if (curHolder !== holder && curHolder !== "" && expiresAtMs > nowMs) {
                 await conn.commit();
                 return { held: false, holder: curHolder, expiresAtMs };
@@ -72,56 +38,16 @@ export class SqlRetentionLaneStore {
             conn.release();
         }
     }
-    /**
-     * 「这一轮的执行权还在我手上吗」**并同时续租** —— 每 domain 处理前调一次(§3 丢租即停)。
-     * 返回 `false` = 不再属于我 ⇒ 调用方当场中止本轮。
-     *
-     * 判据三合取写进**一条 CAS 的 WHERE**:holder 是我 ∧ fencing token 还是本轮那个 ∧ **尚未过期**。
-     *  · 第三项是承重的:租约过期而 holder 还写着我,必须读成**不再属于我**(fail-closed)——另一个副本
-     *    随时可能抢走,两个副本同时跑三方法是这条腿最不能出的事。
-     *  · 「复核」与「续租」合成一条语句而不是先读后写(codex 对抗复审 R1-[high],验真后改):
-     *    ① 读+写两条语句之间有窗口,而 CAS 的谓词与更新在引擎里是原子的;
-     *    ② 更要紧的是**续租本身**:`startRetentionLane` 的重入守卫会跳过下一 tick,于是一轮的续租机会
-     *       只有轮首那一次 —— 一轮跑满 2×interval 之后租约自己到期,而本副本毫不知情、继续删下去。
-     *       轮子转多久租约就跟着延多久,那个窗口才真正关上。
-     *
-     * ⚠️ **如实登记的残余**(设计稿 §3 已成文接受,本实现不假装消灭):本调用返回 true 之后、本 domain 的
-     * 破坏性事务提交之前,仍有一个「租约在这中间被别人接管」的理论窗口 —— 关它需要把 fencing token 的
-     * 校验下推进**每一个破坏性事务的 WHERE**(车1 的三只方法),那是跨车的契约改动。补偿按设计稿:
-     * 每条破坏性审计行都带 fencing token,旧轮的写因此**可判别**(§6 的那一列正是为此存在)。
-     * 续租之后,这个窗口的宽度从「一整轮」缩到「一个 domain 的耗时」,且要求租约恰在这段内到期。
-     */
     async renew(holder, fencingToken, ttlMs, nowMs) {
         const { affected } = await this.db.query(this.q(`UPDATE ${RETENTION_LEASE_TABLE} SET expires_at_ms = ? WHERE singleton = 'x' AND holder = ? AND fencing_token = ? AND expires_at_ms > ?`, `UPDATE ${RETENTION_LEASE_TABLE} SET expires_at_ms = $1 WHERE singleton = 'x' AND holder = $2 AND fencing_token = $3 AND expires_at_ms > $4`), [nowMs + ttlMs, holder, fencingToken, nowMs]);
         return affected > 0;
     }
-    /**
-     * 主动让租(优雅停机)——把到期时间归零,**保留 holder 与 token**(它们是审计线索,不是锁本身)。
-     * 谓词带 `holder = ?`:一个已经丢了租的副本在退出时不许把**别人**的租约推倒。
-     */
     async release(holder) {
         await this.db.query(this.q(`UPDATE ${RETENTION_LEASE_TABLE} SET expires_at_ms = 0 WHERE singleton = 'x' AND holder = ?`, `UPDATE ${RETENTION_LEASE_TABLE} SET expires_at_ms = 0 WHERE singleton = 'x' AND holder = $1`), [holder]);
     }
-    // ───────────────────────────── ② legal-hold 的放置/解除(§5)─────────────────────────────
-    /**
-     * 放置或解除一个域的 legal hold —— **同一 PK 的 upsert 改 `held` 列,绝不 INSERT/DELETE 行**
-     * (车1 交接件②,逐字)。
-     *
-     * 🔴 为什么删行是**拆锁**而不是"解除":`retention_hold` 的行同时是**域级互斥哨兵** —— 车1 的三条破坏性
-     * 事务首步就是锁读这一行(`INSERT IGNORE` 补哨兵 → `SELECT … FOR UPDATE`),而 `FOR UPDATE`
-     * **锁不住一条不存在的行**(TiDB 无 gap lock;PG READ COMMITTED 同病)。删掉行 = 下一个 PUT 与一条
-     * 在飞的删除事务又可以同时读到"没有 hold",于是 operator 拿到成功回执之后数据仍被删 —— 那正是 §5 F2
-     * 要消灭的那件事。upsert 让两者抢**同一把行锁**,「PUT 提交完成 ⇒ 其后每个破坏性事务的首读必见
-     * held=1」这句承诺才成立。
-     *
-     * 解除时把 `placed_by/placed_at_ms/note` 一并清空:这张表存的是**当前状态**不是历史,历史在
-     * `retention_audit` 的 `hold_placed`/`hold_released` 行上(追加不更新)。留一个「谁放的」在一条
-     * held=0 的行上,读它的人分不清那是"现在冻结着"还是"上次谁冻过"。
-     */
     async setHold(input) {
         await this.setHoldOn(this.db, input);
     }
-    /** upsert 的**唯一** SQL 文本(自动提交口与事务口共用;见 {@link setHoldAudited} 的头注)。 */
     async setHoldOn(exec, input) {
         const held = input.held ? 1 : 0;
         const by = input.held ? (input.placedBy ?? null) : null;
@@ -131,18 +57,6 @@ export class SqlRetentionLaneStore {
             `ON DUPLICATE KEY UPDATE held = VALUES(held), placed_by = VALUES(placed_by), placed_at_ms = VALUES(placed_at_ms), note = VALUES(note)`, `INSERT INTO ${RETENTION_HOLD_TABLE} (domain, held, placed_by, placed_at_ms, note) VALUES ($1,$2,$3,$4,$5) ` +
             `ON CONFLICT (domain) DO UPDATE SET held = EXCLUDED.held, placed_by = EXCLUDED.placed_by, placed_at_ms = EXCLUDED.placed_at_ms, note = EXCLUDED.note`), [input.domain, held, by, at, note]);
     }
-    /**
-     * 放置/解除 **+ 治理审计行,同一个事务**(codex 对抗复审 R1-[high],验真后加)。
-     *
-     * 🔴 为什么必须原子(与 §6 F5 的「删除与审计同事务」是同一条判据,只是换了一张表):两次独立提交下,
-     * 第二步失败会留下一次**无审计的状态变更**。PUT 那一支是「冻结了但账上没有」;**DELETE 那一支更重**
-     * —— 冻结已经解除、sweep 从下一拍起就能删这个域的数据,而审计里没有任何 `hold_released` 行说明是谁
-     * 在什么时候解的;客户端只看到一个 500,重试之前发生的删除再也无法从账本上追溯回那次释放。
-     * 一张表两条语句、同库同连接 ⇒ 原子性零分布式代价,没有不做的理由。
-     *
-     * `protected` 的两条私有腿(`setHoldOn` / `appendAuditOn`)让本方法与 {@link setHold} /
-     * {@link appendAudit} 共用**同一份 SQL 文本** —— 两处手抄一份 upsert,迟早只改一处。
-     */
     async setHoldAudited(input) {
         const conn = await this.db.connect();
         try {
@@ -159,36 +73,16 @@ export class SqlRetentionLaneStore {
             conn.release();
         }
     }
-    /** 「这个域现在冻结着吗」—— lane 的**省调**预检(§5 v1.3:降级为优化,**不承重**;承重判在车1 的
-     *  店事务内)。零写。 */
     async holdInForce(domain) {
         const { rows } = await this.db.query(this.q(`SELECT held FROM ${RETENTION_HOLD_TABLE} WHERE domain = ?`, `SELECT held FROM ${RETENTION_HOLD_TABLE} WHERE domain = $1`), [domain]);
         return Number(rows[0]?.held ?? 0) === 1;
     }
-    // ───────────────────────────── ③ 审计:非破坏行的写 + 读面(§6)─────────────────────────────
-    /** 非破坏性审计行的追加(属主 = lane / 路由)。破坏性三词由车1 的店在删除同事务内写。 */
     async appendAudit(row, nowMs) {
         await this.appendAuditOn(this.db, row, nowMs);
     }
-    /** 追加的**唯一** SQL 文本(同上)。 */
     async appendAuditOn(exec, row, nowMs) {
         await exec.query(this.q(`INSERT INTO ${RETENTION_AUDIT_TABLE} (domain, action, mode, policy_days, fencing_token, deleted, skipped, tombstones, executed_at_ms, error) VALUES (?,?,?,?,?,?,?,?,?,?)`, `INSERT INTO ${RETENTION_AUDIT_TABLE} (domain, action, mode, policy_days, fencing_token, deleted, skipped, tombstones, executed_at_ms, error) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10)`), [row.domain, row.action, row.mode, row.policyDays, row.fencingToken, row.deleted, row.skipped, row.tombstones, nowMs, row.error ?? null]);
     }
-    /**
-     * 审计读面(keyset 分页,`id` 降序)。
-     *
-     * 排序键 = **自增 `id` 单列**,而不是 roster 那样的 `(时间戳, 次键)` 二元组:`id` 本身就是全序且唯一,
-     * 二元组存在的全部理由(同毫秒兄弟行无 tiebreak ⇒ 漏页/重页)在这里结构上不存在。索引
-     * `idx_retention_audit_domain (domain, id)` 正是为这条查询建的。
-     *
-     * `before` = 上一页最后一行的 `id`(严格小于)。
-     *
-     * 🔴 读上限是 `MAX_LIMIT + 1` 而不是 `MAX_LIMIT`(codex 对抗复审 R1-[medium],验真属实):调用方要判
-     * 「还有没有下一页」就得多取一行,而**页**的上限是 `MAX_LIMIT`。旧形把 limit 无条件夹到 `MAX_LIMIT`
-     * ⇒ 请求 `limit=200` 时 scanned 恒 ≤ 200 ⇒ `hasMore` 恒 false ⇒ **第 201 行之后的审计对这条分页链
-     * 永久不可达**。这一格是「窗的上限」与「探路的那一行」两个不同的数被写成同一个数造成的,
-     * 修法是让它们各是各的:页 ≤ MAX_LIMIT(路由侧保证),读 ≤ MAX_LIMIT+1(本方法)。
-     */
     async listAudit(input) {
         const limit = Math.min(Math.max(1, Math.floor(input.limit)), RETENTION_AUDIT_MAX_LIMIT + 1);
         const where = [];
@@ -221,13 +115,11 @@ export class SqlRetentionLaneStore {
         }));
     }
 }
-/** MySQL-protocol (TiDB) binding。 */
 export class TiDBRetentionLaneStore extends SqlRetentionLaneStore {
     constructor(pool) {
         super(mysqlDriver(pool));
     }
 }
-/** PostgreSQL binding。 */
 export class PgRetentionLaneStore extends SqlRetentionLaneStore {
     constructor(pool) {
         super(pgDriver(pool));