@sema-agent/server 7.43.0 → 7.44.0

package/dist/boot/retention-lane.js

@@ -1,31 +1,10 @@
-import { recordFailOpen } from "../observability/fail-open.js"; // #157:上报臂的登记式兜底(F 类,census 第 28 行)
-/** 同 domain 连续失败多少次算「卡住了」(fail-loud 的阈值)。`5` 与 reaper 家族的
- *  `REAPER_FAILURE_WARN_THRESHOLD` 同值同理由:一次抖动(一次重连、一次超时)正是容错要吸收的,
- *  只有**连败**才越过「可诊断」这条线。 */
+import { recordFailOpen } from "../observability/fail-open.js";
 export const RETENTION_SWEEP_STUCK_THRESHOLD = 5;
-/** 租约 TTL = 本倍数 × sweep 间隔(设计稿 §3)。`2` = 允许一轮跑满一个完整间隔还有余量,再多就该让位。 */
 export const RETENTION_LEASE_TTL_FACTOR = 2;
-/** 一天的毫秒数(cutoff 换算;本地常量,避免为一个数字引一整只时间工具)。 */
 const DAY_MS = 86_400_000;
-/**
- * lane **自持的** boot 不变式(设计稿 §7,codex F3)—— 与 core 的 `assertRetentionCapability` 是两道门,
- * 各答各的问题:
- *  · core 那道问的是「**锁着**的策略会不会盖在一只删不了的店上」——只在 locked 时说话;
- *  · **本道**问的是「lane 开着的时候,它真的能删吗」——**不看 locked 状态**。
- *
- * 为什么后者必须存在:core 的门在 `locked=false` 时整条放行,于是
- *  ① `RETENTION_SWEEP_INTERVAL_SEC>0` 而 policy 缺席 = 没有有效 cutoff 的 sweep(每 tick 什么都算不出来,
- *     读数一路 0,看起来像"没有候选");
- *  ② unlocked policy × 一只 `"none"` 的店照样过检 —— 部署于是**广告了一个不执行的留存面**:能力位说
- *     `{mode,maxAgeDays}`、审计表也在长,而那只店的行谁都没在删。
- * 两者都在**启动期**拒(安全控件不得半开),不是让运维从一台"启动成功、什么也没删"的机器上猜。
- *
- * @param locked 只进文案(让拒启信息能说清"你锁没锁都一样拒");**判据本身不读它** —— 这一格的存在
- *               就是为了让"不看 locked"这句话在签名上可见,而不是靠注释声明。
- */
 export function assertRetentionLaneWirable(input) {
     if (input.intervalSec <= 0)
-        return; // lane 关 ⇒ 本门整条不判(缺省姿态,#210「缺席不在律内」)
+        return;
     const lockNote = input.locked === true ? " (the retentionPolicy key is LOCKED, but this gate refuses either way)" : "";
     if (input.policy === undefined) {
         throw new Error(`RETENTION_SWEEP_INTERVAL_SEC=${input.intervalSec} arms the managed-retention sweep lane, but RETENTION_MAX_AGE_DAYS is not ` +
@@ -38,11 +17,6 @@ export function assertRetentionLaneWirable(input) {
             `executor — the destructive store methods live on the SQL backends only (DB_BACKEND=mysql|pg); the local/file backend honestly ` +
             `declares retention:"none" and nothing would delete a row${lockNote}. Run a SQL backend, or set RETENTION_SWEEP_INTERVAL_SEC=0.`);
     }
-    // 三方法俱全:声明位说 `managed` 不等于方法在场(一个第三方 store 可以只写声明)。逐个点名缺的那个,
-    // 因为运维要能从这句话直接查到是哪一面没接上。
-    // 逐个方法名走**闭集常量**而不是断言成 `Record<string, unknown>`:`executor[m]` 在 `m` 是键联合时
-    // 类型上就是「那几个方法的联合」,`typeof … !== "function"` 直接判得了 —— 一处宽松断言都不需要,
-    // 而且契约面加一个方法时这张表漏补是**编译红**(`satisfies` 那一行),不是运行期漏检。
     const executor = input.executor;
     const CONTRACT_METHODS = ["listRetentionDomains", "previewRetention", "expireCheckpoints", "deleteExpiredSessions", "deleteOrphanToolResults"];
     for (const m of CONTRACT_METHODS) {
@@ -52,8 +26,6 @@ export function assertRetentionLaneWirable(input) {
                 `half-implemented retention face.`);
         }
     }
-    // 每只被 lane 消费的店都必须诚实声明 managed。`store: undefined` 的行跳过(那一面这台压根没装,
-    // 与 core 的同款判据逐字同姿势 —— 缺席的店不是"不删",它是"没有行"）。
     const notManaged = input.stores.filter((s) => s.store !== undefined && s.store.retention !== "managed").map((s) => s.name);
     if (notManaged.length > 0) {
         throw new Error(`RETENTION_SWEEP_INTERVAL_SEC=${input.intervalSec} arms the managed-retention sweep lane, but these wired store(s) do NOT declare ` +
@@ -61,10 +33,6 @@ export function assertRetentionLaneWirable(input) {
             `while nothing deletes them. Wire a backend whose stores are managed, or set RETENTION_SWEEP_INTERVAL_SEC=0.`);
     }
 }
-/**
- * 跑**一轮** sweep(纯函数式的一拍:自己不排期、不建定时器)。导出是判据面的需要 ——
- * 一个只能靠真定时器推进的 lane 要么让判据睡真时间,要么让判据去证一个假时钟。
- */
 export async function runRetentionSweepOnce(ctx) {
     const claim = await ctx.lease.acquire();
     if (!claim.held)
@@ -77,8 +45,6 @@ export async function runRetentionSweepOnce(ctx) {
     let ranDomains = 0;
     let lostLease = false;
     for (const domain of domains) {
-        // ── 丢租即停:复核在**每 domain 前**(文件头时序契约②)。中止后不写任何"我中止了"的审计行 ——
-        //    那一行会带着一个已经不属于我们的 fencing token 落进不可变账。
         if (!(await ctx.lease.renew(fencingToken))) {
             lostLease = true;
             ctx.logger.warn("retention_sweep_lease_lost", {
@@ -90,16 +56,12 @@ export async function runRetentionSweepOnce(ctx) {
             break;
         }
         try {
-            // hold 预检(§5 v1.3:**省调优化,不承重**)。它省掉的是「一个冻结的大租户每轮仍然跑三条跨表
-            // 事务」;承重的判据在店事务内的哨兵行锁上,所以这里读到 false 而事务内读到 true 是**合法**的
-            // (那时店自己零删全 skip)。
             if (ctx.holdInForce !== undefined && (await ctx.holdInForce(domain))) {
                 await ctx.audit.append({ domain, action: "skipped_legal_hold", mode: ctx.mode, policyDays, fencingToken, deleted: 0, skipped: 0, tombstones: 0 });
                 ranDomains++;
                 streaks?.set(domain, 0);
                 continue;
             }
-            // ── 模式分家(§4)。两支**物理分开**:破坏性方法名只出现在 enforce 那一支里。
             if (ctx.mode === "audit-only") {
                 await sweepDomainAuditOnly(ctx, { domain, cutoffMs, policyDays, fencingToken });
             }
@@ -116,11 +78,8 @@ export async function runRetentionSweepOnce(ctx) {
     }
     return { ranDomains, totalDomains: domains.length, lostLease, held: true, fencingToken };
 }
-/** audit-only 支(§4):**一条破坏性方法都不调**,只把候选计数记进一行 `audit_only`。 */
 async function sweepDomainAuditOnly(ctx, d) {
     const p = await ctx.executor.previewRetention({ domain: d.domain, cutoffMs: d.cutoffMs });
-    // 三候选数进 receipt 的三列(设计稿 §6 逐字:「audit_only 行 = preview 三数」)。列名沿用
-    // deleted/skipped/tombstones 而不是另开三列:同一张追加表两套列语义会让读它的 SQL 必须先分支 action。
     await ctx.audit.append({
         domain: d.domain,
         action: "audit_only",
@@ -132,13 +91,6 @@ async function sweepDomainAuditOnly(ctx, d) {
         tombstones: p.toolResults,
     });
 }
-/**
- * enforce 支(§3):三方法按**依赖序** —— 先让过期的 checkpoint 过门(它是会话树的一条活引用腿),
- * 再删会话树(它落的墓碑是孤儿结果的域归属证据),最后清孤儿结果。倒过来任何一步都会让下一步少删一批,
- * 靠"下一拍自然收敛"补 —— 那是把一个可以现在做对的顺序换成一个延迟。
- *
- * 🔴 破坏性审计行**不在这里写**(§6 F5:店在删除同事务内已写)。receipt 只做二次确认与日志。
- */
 async function sweepDomainEnforce(ctx, d) {
     const input = {
         domain: d.domain,
@@ -150,7 +102,7 @@ async function sweepDomainEnforce(ctx, d) {
     const toolResults = await ctx.executor.deleteOrphanToolResults(input);
     const touched = checkpoints.deleted + sessions.deleted + toolResults.deleted;
     if (touched > 0) {
-        ctx.metrics.inc("retention_rows_swept_total", { domain: "" }, touched); // 域不进标签(高基数);域维在审计表上
+        ctx.metrics.inc("retention_rows_swept_total", { domain: "" }, touched);
         ctx.logger.info("retention_swept", {
             domain: d.domain,
             fencingToken: d.fencingToken,
@@ -162,16 +114,7 @@ async function sweepDomainEnforce(ctx, d) {
         });
     }
 }
-/**
- * 单 domain 失败的记账(§3:`failed` 行 + 继续下一 domain;连败 ≥ 阈值 ⇒ 指标 + 一次性 warn)。
- *
- * 🔴 整段**总不抛**:它是 catch 臂里的收尾,一个 poison error(`Symbol.toPrimitive` 抛)或一条抛异常的
- * 日志/审计写口若从这里逃出去,就会打断 for 循环、饿死后面每一个 domain —— 那正是 per-domain 隔离
- * 存在的理由的反面(reapers.ts 的 per-scope 循环踩过同一形,注释在彼)。
- */
 async function recordDomainFailure(ctx, d) {
-    // poison error(抛异常的 `Symbol.toPrimitive`/`toString`)⇒ 落一句**自陈**的占位文案而不是空转:
-    // 审计行里写着「原因取不出来」比写着 "unknown error" 诚实,读账的人据此知道该去看进程日志。
     let message;
     try {
         message = d.err instanceof Error ? d.err.message : String(d.err);
@@ -179,8 +122,6 @@ async function recordDomainFailure(ctx, d) {
     catch {
         message = "<error object whose toString() itself threw — see the process log for the raw rejection>";
     }
-    /** 审计行落地了吗 —— 进下面那条 warn 的 meta。**不是装饰**:审计写不进去时,`retention_audit` 里
-     *  会缺这一条 `failed` 行,而运维只有从日志里读到这一位才知道"账本自己也断了"。 */
     let auditRowWritten = true;
     try {
         await ctx.audit.append({
@@ -196,8 +137,6 @@ async function recordDomainFailure(ctx, d) {
         });
     }
     catch {
-        // 审计写口自己坏了(库不可达 —— 通常就是上一步失败的同一个原因)。下面那条 warn 仍要发出去,
-        // 并且**带上这一位**:否则「审计表里没有这条 failed 行」看起来会像"这一轮根本没跑到这个域"。
         auditRowWritten = false;
     }
     const streaks = ctx.streaks;
@@ -207,8 +146,6 @@ async function recordDomainFailure(ctx, d) {
         ctx.logger.warn("retention_sweep_domain_failed", { domain: d.domain, fencingToken: d.fencingToken, consecutiveFailures: streak, auditRowWritten, err: message });
         if (streak >= RETENTION_SWEEP_STUCK_THRESHOLD) {
             ctx.metrics.inc("retention_sweep_stuck", {}, 1);
-            // 一次性:阈值一到就打一条、并把计数归零,于是**仍然坏着**的域每再连败一个完整阈值才报一次
-            // (不是首次之后永远静音,也不是每轮刷屏)——与 `createThrottledReaperCatch` 逐字同形。
             ctx.logger.warn("retention_sweep_stuck", {
                 domain: d.domain,
                 consecutiveFailures: streak,
@@ -219,29 +156,13 @@ async function recordDomainFailure(ctx, d) {
         }
     }
     catch {
-        // 上报**自己**抛了(poison error 的 toString / 一条抛异常的 logger transport)。这里绝不能让它逃出去:
-        // 逃出去会打断 per-domain 循环、饿死后面每一个域 —— 而 per-domain 隔离正是这条腿存在的理由
-        // (reapers.ts 的 per-scope 循环踩过同一形)。走登记过的 F 类兜底口,于是这条臂有计数、有探针行、
-        // 有一次性 warn,而不是一次无痕的沉默(#157 / FAIL-OPEN-CENSUS 第 28 行)。
         recordFailOpen("server.retention.sweep-report-dropped", `domain=${d.domain}`);
     }
 }
-/**
- * 起 lane,返回控制器(`undefined` = lane 关着,**根本没建**定时器)。
- *
- * 三条与 reaper 家族同款的纪律:
- *  · `unref()` 紧跟 `setInterval` —— 定时器绝不可持住进程;
- *  · **重入守卫**:一轮的时长随域数与库延迟增长,越过 interval 就会叠罗汉压同一批行(邻居五腿同形)。
- *    ⚠️ 守卫的代价是「一轮里只有轮首那一次续租机会」——所以每 domain 前那条 `renew` 是承重的,不是装饰;
- *  · 一轮内部的任何异常都在轮内被吞掉并记账(`runRetentionSweepOnce` 的 per-domain catch),这里再兜一层
- *    是为了「租约抢占本身失败」这种**轮外**故障 —— 它不该变成一条 unhandled rejection 把进程带走。
- */
 export function startRetentionLane(ctx) {
     if (ctx.intervalSec <= 0)
         return undefined;
-    const streaks = ctx.streaks ?? new Map(); // 跨轮存活:必须建在 setInterval **之外**
-    /** 在飞那一轮(`undefined` = 空闲)。它同时是重入守卫与 `stop()` 的等待对象 —— 一个变量两用刻意为之:
-     *  两个变量必然在某次改动后不同步,而不同步的方向是「stop 以为没人在跑」。 */
+    const streaks = ctx.streaks ?? new Map();
     let inFlight;
     let stopped = false;
     const runOnce = () => {
@@ -254,8 +175,6 @@ export function startRetentionLane(ctx) {
                 ctx.logger.warn("retention_sweep_round_failed", { err: err instanceof Error ? err.message : String(err) });
             }
             catch {
-                // 同 `recordDomainFailure` 的上报臂:一条抛异常的 logger transport 不许把这条 `.catch` 变成
-                // 一个 floating rejection(Node 默认处理下会带走整个进程)。
                 recordFailOpen("server.retention.sweep-report-dropped", "round");
             }
         })
@@ -270,8 +189,6 @@ export function startRetentionLane(ctx) {
         stop: async () => {
             stopped = true;
             clearInterval(timer);
-            // 等在飞那一轮落地。`inFlight` 自己已经把所有异常吞掉了(上面的 catch),所以这里不会抛;
-            // 再挂一条 catch 是因为收尾链绝不该被一条清理腿打断 —— 哪怕是被将来某次改动引入的新抛点。
             await inFlight?.catch(() => undefined);
         },
     };