@sema-agent/server 7.29.0 → 7.30.0

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

@@ -0,0 +1,236 @@
+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 {
+            await conn.begin();
+            await conn.query(this.q(`INSERT IGNORE INTO ${RETENTION_LEASE_TABLE} (singleton, holder, fencing_token, expires_at_ms) VALUES ('x','',0,0)`, `INSERT INTO ${RETENTION_LEASE_TABLE} (singleton, holder, fencing_token, expires_at_ms) VALUES ('x','',0,0) ON CONFLICT (singleton) DO NOTHING`));
+            const { rows } = await conn.query(this.q(`SELECT holder, fencing_token, expires_at_ms FROM ${RETENTION_LEASE_TABLE} WHERE singleton = 'x' FOR UPDATE`, `SELECT holder, fencing_token, expires_at_ms FROM ${RETENTION_LEASE_TABLE} WHERE singleton = 'x' FOR UPDATE`));
+            const cur = rows[0];
+            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 };
+            }
+            const renewing = curHolder === holder;
+            const fencingToken = renewing ? curToken : curToken + 1;
+            await conn.query(this.q(`UPDATE ${RETENTION_LEASE_TABLE} SET holder = ?, fencing_token = ?, expires_at_ms = ? WHERE singleton = 'x'`, `UPDATE ${RETENTION_LEASE_TABLE} SET holder = $1, fencing_token = $2, expires_at_ms = $3 WHERE singleton = 'x'`), [holder, fencingToken, nowMs + ttlMs]);
+            await conn.commit();
+            return { held: true, fencingToken, holder };
+        }
+        catch (err) {
+            await conn.rollback().catch(() => undefined);
+            throw err;
+        }
+        finally {
+            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;
+        const at = input.held ? input.nowMs : null;
+        const note = input.held ? (input.note ?? null) : null;
+        await exec.query(this.q(`INSERT INTO ${RETENTION_HOLD_TABLE} (domain, held, placed_by, placed_at_ms, note) VALUES (?,?,?,?,?) ` +
+            `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 {
+            await conn.begin();
+            await this.setHoldOn(conn, input);
+            await this.appendAuditOn(conn, input.audit, input.nowMs);
+            await conn.commit();
+        }
+        catch (err) {
+            await conn.rollback().catch(() => undefined);
+            throw err;
+        }
+        finally {
+            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 = [];
+        const params = [];
+        let n = 0;
+        if (input.domain !== undefined) {
+            where.push(this.q(`domain = ?`, `domain = $${++n}`));
+            params.push(input.domain);
+        }
+        if (input.beforeId !== undefined) {
+            where.push(this.q(`id < ?`, `id < $${++n}`));
+            params.push(input.beforeId);
+        }
+        const clause = where.length > 0 ? `WHERE ${where.join(" AND ")}` : "";
+        const { rows } = await this.db.query(this.q(`SELECT id, domain, action, mode, policy_days, fencing_token, deleted, skipped, tombstones, executed_at_ms, error ` +
+            `FROM ${RETENTION_AUDIT_TABLE} ${clause} ORDER BY id DESC LIMIT ?`, `SELECT id, domain, action, mode, policy_days, fencing_token, deleted, skipped, tombstones, executed_at_ms, error ` +
+            `FROM ${RETENTION_AUDIT_TABLE} ${clause} ORDER BY id DESC LIMIT $${++n}`), [...params, limit]);
+        return rows.map((r) => ({
+            id: Number(r.id),
+            domain: String(r.domain ?? ""),
+            action: String(r.action),
+            mode: String(r.mode ?? ""),
+            policyDays: Number(r.policy_days ?? 0),
+            fencingToken: r.fencing_token === null || r.fencing_token === undefined ? null : Number(r.fencing_token),
+            deleted: Number(r.deleted ?? 0),
+            skipped: Number(r.skipped ?? 0),
+            tombstones: Number(r.tombstones ?? 0),
+            executedAtMs: Number(r.executed_at_ms ?? 0),
+            error: r.error === null || r.error === undefined ? null : String(r.error),
+        }));
+    }
+}
+/** 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));
+    }
+}
+//# sourceMappingURL=retention-lane-store-sql.js.map