@sema-agent/server 7.132.0 → 7.133.0

package/dist/approval-ask-audit-store.js

@@ -1,7 +1,9 @@
-import { createHash } from "node:crypto";
-import { join } from "node:path";
-import { AppendLog, ensureDir, isHostDecider } from "@sema-agent/core";
+import { createHash, randomBytes } from "node:crypto";
+import { closeSync, existsSync, fsyncSync, openSync, readFileSync, renameSync, unlinkSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { AppendLog, ensureDir, isHostDecider, writeThenLink } from "@sema-agent/core";
 import { recordFailOpen } from "./observability/fail-open.js";
+import { ownerOfCheckpointScope } from "./security.js";
 import { replayJsonlSkipping } from "./observability/corrupt-read-seat.js";
 import { isSettleCause, SETTLE_OUTCOME } from "./approval-deny-reasons.js";
 export const APPROVAL_ASK_AUDIT_DIR = "approval-ask-audit";
@@ -168,10 +170,157 @@ const LEDGER_SHAPE = {
         return rec === undefined ? undefined : { rec, outOfSetCause };
     },
 };
+function foldLedger(records) {
+    const groups = new Map();
+    const legClosed = [];
+    const shutdownMarks = [];
+    const group = (approvalId, line) => {
+        let g = groups.get(approvalId);
+        if (!g) {
+            g = { firstLine: line };
+            groups.set(approvalId, g);
+        }
+        return g;
+    };
+    for (const { rec, line } of records) {
+        switch (rec.kind) {
+            case "ask": {
+                const g = group(rec.approvalId, line);
+                if (g.ask === undefined) {
+                    g.ask = rec;
+                    g.askLine = line;
+                }
+                break;
+            }
+            case "settle": {
+                const g = group(rec.approvalId, line);
+                if (g.settle === undefined) {
+                    g.settle = rec;
+                    g.settleLine = line;
+                }
+                break;
+            }
+            case "late_settle":
+                break;
+            case "leg_closed":
+                legClosed.push({ taskId: rec.taskId, line });
+                break;
+            case "interrupted_by_shutdown":
+                shutdownMarks.push({ taskId: rec.taskId, line });
+                break;
+            case "crash_converged": {
+                const g = group(rec.approvalId, line);
+                g.converged = rec;
+                g.convergedLine = line;
+                break;
+            }
+            default: {
+                const unreachable = rec;
+                throw new Error(`approval-ask-audit fold: unreachable record ${String(unreachable)}`);
+            }
+        }
+    }
+    return { groups, legClosed, shutdownMarks };
+}
+function legEvidenceOf(g, records, afterLine, beforeLine = Number.POSITIVE_INFINITY) {
+    const ask = g.ask;
+    if (!ask.legTracked)
+        return undefined;
+    return records.some((r) => r.taskId === ask.taskId && r.line > afterLine && r.line < beforeLine);
+}
+function judgeOrphan(g, legClosed) {
+    if (g.ask === undefined || g.converged !== undefined)
+        return undefined;
+    if (g.settle === undefined) {
+        return legEvidenceOf(g, legClosed, g.askLine ?? 0) === true ? "inconsistent" : "pending";
+    }
+    if (g.settle.outcome === "allowed" && legEvidenceOf(g, legClosed, g.settleLine ?? 0) === false)
+        return "decided";
+    return undefined;
+}
+function readLedgerLine(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw.toString("utf8"));
+    }
+    catch (err) {
+        return { unparsable: err };
+    }
+    return { rec: readLedgerRecord(parsed, () => { }) };
+}
+function recordOfLine(raw) {
+    const read = readLedgerLine(raw);
+    return "rec" in read ? read.rec : undefined;
+}
+function replaceFileBytes(target, bytes) {
+    const staging = join(dirname(target), ".tmp", `${APPROVAL_ASK_AUDIT_LEDGER}.${process.pid}.${randomBytes(6).toString("hex")}.rotate`);
+    try {
+        writeThenLink(staging, bytes);
+        renameSync(staging, target);
+    }
+    finally {
+        if (existsSync(staging))
+            unlinkSync(staging);
+    }
+}
+function fsyncDirectory(dir) {
+    const fd = openSync(dir, "r");
+    try {
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function splitLedgerBytes(bytes) {
+    const lines = [];
+    let start = 0;
+    for (let i = bytes.indexOf(0x0a, start); i !== -1; i = bytes.indexOf(0x0a, start)) {
+        lines.push(bytes.subarray(start, i));
+        start = i + 1;
+    }
+    return { lines, tail: bytes.subarray(start) };
+}
+function approvalIdOf(rec) {
+    switch (rec.kind) {
+        case "ask":
+        case "settle":
+        case "crash_converged":
+        case "late_settle":
+            return rec.approvalId;
+        case "leg_closed":
+        case "interrupted_by_shutdown":
+            return undefined;
+        default: {
+            const unreachable = rec;
+            throw new Error(`approval-ask-audit: unreachable record ${String(unreachable)}`);
+        }
+    }
+}
+function atMsOf(rec) {
+    switch (rec.kind) {
+        case "ask":
+            return rec.mintedAtMs;
+        case "settle":
+        case "late_settle":
+            return rec.settledAtMs;
+        case "crash_converged":
+            return rec.convergedAtMs;
+        case "leg_closed":
+            return rec.closedAtMs;
+        case "interrupted_by_shutdown":
+            return rec.atMs;
+        default: {
+            const unreachable = rec;
+            throw new Error(`approval-ask-audit: unreachable record ${String(unreachable)}`);
+        }
+    }
+}
 export class FileApprovalAskAuditStore {
     ledgerPath;
     log;
     openLog;
+    fsyncDir;
     replayed = new Map();
     replayedLegClosed = [];
     replayedShutdownMarks = [];
@@ -185,6 +334,7 @@ export class FileApprovalAskAuditStore {
     askTaskId = new Map();
     constructor(root, internals) {
         this.openLog = internals?.appendLog ?? ((p) => new AppendLog(p));
+        this.fsyncDir = internals?.fsyncDir ?? fsyncDirectory;
         const dir = join(root, APPROVAL_ASK_AUDIT_DIR);
         ensureDir(dir);
         this.ledgerPath = join(dir, APPROVAL_ASK_AUDIT_LEDGER);
@@ -193,59 +343,20 @@ export class FileApprovalAskAuditStore {
     corruptLines = 0;
     replay() {
         const { records, skipped } = replayJsonlSkipping(this.ledgerPath, "approval-ask-audit", LEDGER_SHAPE);
-        this.corruptLines = skipped;
-        let line = 0;
-        for (const { rec, outOfSetCause } of records) {
-            line += 1;
-            if (outOfSetCause)
-                this.corruptLines += 1;
-            switch (rec.kind) {
-                case "ask": {
-                    const g = this.group(rec.approvalId, line);
-                    if (g.ask === undefined) {
-                        g.ask = rec;
-                        g.askLine = line;
-                    }
-                    this.indexAsk(rec);
-                    break;
-                }
-                case "settle": {
-                    const g = this.group(rec.approvalId, line);
-                    if (g.settle === undefined) {
-                        g.settle = rec;
-                        g.settleLine = line;
-                    }
-                    this.indexSettle(rec);
-                    break;
-                }
-                case "late_settle":
-                    break;
-                case "leg_closed":
-                    this.replayedLegClosed.push({ taskId: rec.taskId, line });
-                    break;
-                case "interrupted_by_shutdown":
-                    this.replayedShutdownMarks.push({ taskId: rec.taskId, line });
-                    break;
-                case "crash_converged": {
-                    const g = this.group(rec.approvalId, line);
-                    g.converged = rec;
-                    g.convergedLine = line;
-                    break;
-                }
-                default: {
-                    const unreachable = rec;
-                    throw new Error(`approval-ask-audit replay: unreachable record ${String(unreachable)}`);
-                }
-            }
-        }
-    }
-    group(approvalId, line) {
-        let g = this.replayed.get(approvalId);
-        if (!g) {
-            g = { firstLine: line };
+        this.corruptLines = skipped + records.filter((r) => r.outOfSetCause).length;
+        const fold = foldLedger(records.map(({ rec }, i) => ({ rec, line: i + 1 })));
+        for (const [approvalId, g] of fold.groups)
             this.replayed.set(approvalId, g);
+        for (const r of fold.legClosed)
+            this.replayedLegClosed.push(r);
+        for (const r of fold.shutdownMarks)
+            this.replayedShutdownMarks.push(r);
+        for (const { rec } of records) {
+            if (rec.kind === "ask")
+                this.indexAsk(rec);
+            else if (rec.kind === "settle")
+                this.indexSettle(rec);
         }
-        return g;
     }
     append(rec) {
         try {
@@ -346,18 +457,12 @@ export class FileApprovalAskAuditStore {
                 this.convergedRows.push({ row: this.projectRow(g, g.converged.orphanState, g.converged.convergedAtMs, this.causeOf(g)), owner: g.ask.owner });
                 continue;
             }
-            let orphanState;
-            if (g.settle === undefined) {
-                if (this.legEvidence(g, this.replayedLegClosed, g.askLine ?? 0) === true) {
-                    inconsistent += 1;
-                    continue;
-                }
-                orphanState = "pending";
-            }
-            else if (g.settle.outcome === "allowed" &&
-                this.legEvidence(g, this.replayedLegClosed, g.settleLine ?? 0) === false) {
-                orphanState = "decided";
+            const verdict = judgeOrphan(g, this.replayedLegClosed);
+            if (verdict === "inconsistent") {
+                inconsistent += 1;
+                continue;
             }
+            const orphanState = verdict;
             if (orphanState === undefined)
                 continue;
             const convergedAtMs = Date.now();
@@ -379,13 +484,7 @@ export class FileApprovalAskAuditStore {
     causeOf(g) {
         const after = g.settleLine ?? g.askLine ?? 0;
         const before = g.convergedLine ?? Number.POSITIVE_INFINITY;
-        return this.legEvidence(g, this.replayedShutdownMarks, after, before) === true ? "shutdown_before_park" : "crashed_before_park";
-    }
-    legEvidence(g, records, afterLine, beforeLine = Number.POSITIVE_INFINITY) {
-        const ask = g.ask;
-        if (!ask.legTracked)
-            return undefined;
-        return records.some((r) => r.taskId === ask.taskId && r.line > afterLine && r.line < beforeLine);
+        return legEvidenceOf(g, this.replayedShutdownMarks, after, before) === true ? "shutdown_before_park" : "crashed_before_park";
     }
     projectRow(g, orphanState, convergedAtMs, cause) {
         const ask = g.ask;
@@ -401,18 +500,117 @@ export class FileApprovalAskAuditStore {
             orphanState,
             ...(orphanState === "decided" ? { originalDecision: "approve", ...(g.settle !== undefined ? { decidedAtMs: g.settle.settledAtMs } : {}) } : {}),
             convergedAtMs,
-            resumeSafe: orphanState === "pending" && this.legEvidence(g, this.replayedLegClosed, g.askLine ?? 0) === false,
+            resumeSafe: orphanState === "pending" && legEvidenceOf(g, this.replayedLegClosed, g.askLine ?? 0) === false,
         };
     }
     listCrashConverged(scope) {
         const rows = [];
+        const owner = scope === undefined ? undefined : ownerOfCheckpointScope(scope);
         for (const e of this.convergedRows) {
-            if (scope !== undefined && e.owner !== scope)
+            if (owner !== undefined && e.owner !== owner)
                 continue;
             rows.push(e.row);
         }
         return rows;
     }
+    rotateOlderThan(cutoffMs, keepAnchors) {
+        let bytes;
+        try {
+            bytes = readFileSync(this.ledgerPath);
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return { droppedAsks: 0, droppedRecords: 0, keptRecords: 0 };
+            throw err;
+        }
+        const { lines, tail } = splitLedgerBytes(bytes);
+        const entries = lines.map((raw) => ({ raw, terminated: true, rec: recordOfLine(raw) }));
+        if (tail.length > 0)
+            entries.push({ raw: tail, terminated: false, rec: recordOfLine(tail) });
+        const numbered = entries.flatMap((e, i) => (e.rec !== undefined ? [{ rec: e.rec, line: i + 1 }] : []));
+        const fold = foldLedger(numbered);
+        const lastAt = new Map();
+        const anchorsOf = new Map();
+        for (const { rec } of numbered) {
+            const id = approvalIdOf(rec);
+            if (typeof id !== "string")
+                continue;
+            lastAt.set(id, Math.max(lastAt.get(id) ?? Number.NEGATIVE_INFINITY, atMsOf(rec)));
+            const cells = rec.kind === "ask" ? [rec.taskId, rec.sessionId, rec.sourceTaskId] : rec.kind === "late_settle" ? [rec.taskId, rec.sessionId] : [];
+            const list = anchorsOf.get(id) ?? [];
+            for (const c of cells)
+                if (c !== undefined)
+                    list.push(c);
+            anchorsOf.set(id, list);
+        }
+        const dropped = new Set();
+        for (const [id, at] of lastAt) {
+            if (at >= cutoffMs)
+                continue;
+            if ((anchorsOf.get(id) ?? []).some((a) => keepAnchors.has(a)))
+                continue;
+            const g = fold.groups.get(id);
+            const verdict = g === undefined ? undefined : judgeOrphan(g, fold.legClosed);
+            if (verdict === "pending" || verdict === "decided")
+                continue;
+            dropped.add(id);
+        }
+        const claimedTasks = new Set();
+        for (const [id, g] of fold.groups)
+            if (!dropped.has(id) && g.ask !== undefined)
+                claimedTasks.add(g.ask.taskId);
+        const keep = (rec) => {
+            if (rec === undefined)
+                return true;
+            switch (rec.kind) {
+                case "ask":
+                case "settle":
+                case "crash_converged":
+                    return !dropped.has(rec.approvalId);
+                case "late_settle":
+                    return rec.approvalId !== null ? !dropped.has(rec.approvalId) : rec.settledAtMs >= cutoffMs;
+                case "leg_closed":
+                case "interrupted_by_shutdown":
+                    return atMsOf(rec) >= cutoffMs || claimedTasks.has(rec.taskId) || keepAnchors.has(rec.taskId);
+                default: {
+                    const unreachable = rec;
+                    throw new Error(`approval-ask-audit rotate: unreachable record ${String(unreachable)}`);
+                }
+            }
+        };
+        const kept = entries.filter((e) => keep(e.rec));
+        const droppedRecords = entries.length - kept.length;
+        if (droppedRecords === 0)
+            return { droppedAsks: 0, droppedRecords: 0, keptRecords: entries.length };
+        this.log?.close();
+        this.log = undefined;
+        const NEWLINE = Buffer.from([0x0a]);
+        replaceFileBytes(this.ledgerPath, Buffer.concat(kept.flatMap((e) => (e.terminated ? [e.raw, NEWLINE] : [e.raw]))));
+        for (const id of dropped) {
+            this.replayed.delete(id);
+            this.askTaskId.delete(id);
+            this.parkExpired.delete(id);
+        }
+        for (const bucket of [this.askByCallAnchor, this.askBySessionOnly]) {
+            for (const [key, ids] of bucket) {
+                for (const id of dropped)
+                    ids.delete(id);
+                if (ids.size === 0)
+                    bucket.delete(key);
+            }
+        }
+        const survivors = this.convergedRows.filter((e) => !dropped.has(e.row.approvalId));
+        this.convergedRows.length = 0;
+        for (const e of survivors)
+            this.convergedRows.push(e);
+        try {
+            this.fsyncDir(dirname(this.ledgerPath));
+        }
+        catch (err) {
+            recordFailOpen("server.approval-ask-audit.rotate-dir-fsync-failed", `path=${this.ledgerPath} err=${err instanceof Error ? err.message : String(err)}`);
+        }
+        return { droppedAsks: dropped.size, droppedRecords, keptRecords: kept.length };
+    }
     close() {
         this.log?.close();
         this.log = undefined;

package/dist/approval-ask-machine.d.ts

@@ -15,6 +15,21 @@ export declare const BATCH_TERMINAL: ReadonlySet<BatchState>;
  * 都在这里),放这里不引新依赖边。
  */
 export declare const MAX_DECISION_NOTE_CHARS = 2048;
+/**
+ * 回决回执上「理由记上了吗」(`noteRecorded`)一格的**唯一判官与唯一组句器** —— 两口回决(live
+ * `POST /v1/tool-approvals/:id/respond` 与耐久 `POST /v1/tasks/:taskId/asks/:askId/decision`)的每一个 200
+ * 回体(PARKED 行经赎回腿受理的那一腿除外:它的理由走检查点回决链、不写 ask 行,尚无「记在哪张行」的定义,契约里点名为未覆盖)都经这两只函数说这件事,
+ * 不在各自的回体字面量里手写第二份。
+ *
+ * 三态同一份契约:请求**没带** `note` ⇒ 键缺席(不是 `false`);带了 ⇒ `true | false`:`true` = **已确认**持久行上那段文本就是这次提交的
+ * (逐字相等才算 —— 文本真的相同就不是谎,哪怕是别人写的);`false` = **没确认**(行上是别人的理由 / 这台没有店 / 店抖动而确认读也读不到 ——
+ * 不知道不许说成成功),不是「这台部署有没有店」。耐久回决口手里恒有那一行,它的 `false` 就是「行上不是这次那段」。
+ */
+export declare function noteLandedOnRow(requestNote: string | undefined, rowNote: string | null): boolean;
+/** {@link noteLandedOnRow} 的组句器:只在请求带了 `note` 时铸 `noteRecorded`(`landed` 由调用方按各自能证明的事实给)。 */
+export declare function noteRecordedReceipt(requestNote: string | undefined, landed: boolean): {
+    noteRecorded?: boolean;
+};
 /** ask 转移合法性(表驱动,含拒绝同值自环——STREAM_PENDING→STREAM_PENDING 不在表里,故 false)。 */
 export declare function canAskTransition(from: AskState, to: AskState): boolean;
 /** 批转移合法性,同形。 */

package/dist/approval-ask-machine.js

@@ -2,6 +2,12 @@ import { createHash } from "node:crypto";
 export const ASK_TERMINAL = new Set(["DECIDED", "PARKED", "DENIED", "VOID"]);
 export const BATCH_TERMINAL = new Set(["ROUTING_BOUND", "ABORTED"]);
 export const MAX_DECISION_NOTE_CHARS = 2048;
+export function noteLandedOnRow(requestNote, rowNote) {
+    return requestNote !== undefined && rowNote === requestNote;
+}
+export function noteRecordedReceipt(requestNote, landed) {
+    return requestNote === undefined ? {} : { noteRecorded: landed };
+}
 const ASK_TRANSITIONS = {
     STREAM_PENDING: ["DECIDED", "PARKING", "VOID"],
     PARKING: ["PARKED", "DENIED", "VOID"],

package/dist/approval-ask-retention.d.ts

@@ -0,0 +1,136 @@
+/**
+ * **审批账本的留存律**(一处成文;问账三形 + local 审计账同一条)。
+ *
+ * ## 律
+ * 一问一旦**结了**,且它**最后一次动静**早于 `now − APPROVAL_ASK_RETENTION_MS`,它在审批账本里的全部记录就在维护拍上**整问**删掉;
+ * 没结的问永不按龄删;删只删整问,从不改写留下的记录;每次真删了东西都有读数。`APPROVAL_ASK_RETENTION_MS=0` = 不删(永久保留)。
+ *
+ * **「结了」= 该问在它那本账里到了终局,且它挂靠的东西都不再能动**。后半句对两本账同一条:
+ *  · **挂靠**:问行 / 审计组上的三格 —— 发起它的 run(`task_id`)、宿主会话(`session_id`)、发问那条腿的会话(`source_task_id`);
+ *  · **还能动**:run 账上 `RUN_STATUS_CLASS` 的 live / parked 两类(跑着、停驻在门上);后台子代账上 running / parked 的子代(子代的问
+ *    记在**宿主** run 与宿主会话名下 —— 继承链闭包携宿主身份 —— 而子代可以比宿主 run 活得久,所以子代的宿主 run、宿主会话与它自己的会话
+ *    都算挂靠);以及 checkpoint 店里**每一只待决的 checkpoint**(停驻不论是谁的 —— run、后台子代、workflow 子代 —— 都是一只待决 checkpoint,
+ *    它的会话 = 停驻那条腿的会话 = 那条腿上问行的 `source_task_id`):一个来源盖住所有停驻,不必逐个枚举会停驻的东西。
+ * 还能动的东西会回读或续写它挂靠的问 —— 会话授权的争议判据按「这次调用在这条腿上有没有行」读问账(没有行 = 从没问过 ⇒ 一揽子放行可以
+ * 代答;拒绝行若被删,就成了代答),停驻问的迟到结算要审计账里那一问的前置事实。所以一次清扫先列出还能动的东西的挂靠集
+ * ({@link collectMovableAnchors}),两本账都把挂靠在集里的问整只跳过。
+ * 前半句各账一句,判据都住在各自的属主里(本文件不复述,只排期与读数):
+ *  · 问账(Memory / File / SQL 三形同两只动词,各是一条语句):`reapSettledAsks` —— 行在终态(`ASK_TERMINAL`)且不是 provisional
+ *    (版本化补偿还能改它)∧ `updatedAtMs` 早于 cutoff ∧ run 不在还能动的集里;`reapEmptyBatches` —— 批是问的容器,批里已经没有问
+ *    ∧ 批自己的 `updatedAtMs` 也早于 cutoff 才删。
+ *  · 审计账(`FileApprovalAskAuditStore.rotateOlderThan`,local 车道):这一问不再欠下一次起服收敛一个答案(起服收敛的判官此刻不会把它收成孤儿)
+ *    ∧ run 不在还能动的集里 ∧ 该问所有记录里最晚的时刻早于 cutoff ⇒ 整问的行一起离开文件,留下的行逐字节不变。
+ *
+ * ## 为什么挂在维护 tick 上、而不是托管留存车道
+ * 那条车道(`boot/retention-lane.ts`)只认 SQL 后端、缺省关,在 local 上根本不存在 —— 用它就做不到「File 与 SQL 同一条律、缺省生效」。
+ * 维护 tick 是所有按龄删行的腿的宿主(多副本各扫各的、幂等):问账的删除谓词是纯行谓词,两副本同扫只是一方删到零行。
+ *
+ * ## 节律
+ * 一次清扫至多每 {@link APPROVAL_ASK_RETENTION_PASS_MS} 一次(首拍即跑):窗以天计,清扫的迟到以小时计,无关紧要;而一次清扫的成本
+ * (SQL 上按状态扫终态行、local 上重读并重写审计账)不该每分钟付一次。问账一批至多 {@link APPROVAL_ASK_REAP_BATCH} 只,一次清扫内连删到
+ * 不满一批为止(积压按批渐进清空,每条语句都短)。
+ *
+ * ## 读数
+ * 每条语句(一次店动词调用)要么删了并交回删掉的行数、要么一行没删就抛 —— 读数按语句累计、计数器按语句当场加,一次清扫半途失败时
+ * 已经删掉的照样进 `approval_ask_retention_swept`(带 `incomplete: true`),错误再抛给维护 tick 的节流 catch。删掉的行没有第二次读数的机会。
+ */
+import type { ApprovalAskStore } from "./plugins/approval-ask-store-sql.js";
+import type { FileApprovalAskAuditStore } from "./approval-ask-audit-store.js";
+import type { Logger } from "./observability/logger.js";
+import type { Metrics } from "./observability/metrics.js";
+import type { BackgroundAgentRecord } from "@sema-agent/core";
+/** 缺省保留窗:30 天。 */
+export declare const APPROVAL_ASK_RETENTION_DEFAULT_MS: number;
+/**
+ * 正值的下限:1 天(低于即钳到 1 天并点名)。还能动的 run 的问本来就不删(见文件头);下限管的是**刚结束**的 run:
+ * 客户端在 run 结束后还可能对它的卡做幂等重试 / 晚答(决断口回放首决、晚答口回 409 / 410 而不是 404),一天吸收这一段。
+ */
+export declare const APPROVAL_ASK_RETENTION_FLOOR_MS = 86400000;
+/** 两次清扫之间的最短间隔(见文件头「节律」)。 */
+export declare const APPROVAL_ASK_RETENTION_PASS_MS = 3600000;
+/** 问账一批至多删多少只问(批行同界);列 run 账时的一页也取这个数。 */
+export declare const APPROVAL_ASK_REAP_BATCH = 500;
+/**
+ * 「还能动」的 run 状态词 —— 从 `RUN_STATUS_CLASS` 派生(parked 类在前、live 类在后),不手抄词表:run 账加一个词,它当场归一类。
+ * 🔴 **次序是承重的**(codex 验证轮 V2 / 验证二轮 W2):run 账按状态一词一查,两次查询之间 run 可以换态。停驻 → 跑着 → 再停驻:
+ * 途中被**续跑**(parked → live)的 run 在跑着那一查里在;续跑**失败退回**停驻(parked → live → parked,`resume-legs` 的可重试拒臂把 run 放回
+ * suspended、checkpoint 不换)在末一查里在。只在途中「跑着 → 停驻 → 跑着」两头都漏 —— 它无害:停驻之后的问只会更新(停驻那一刻的问比
+ * cutoff 新),早于 cutoff 的旧问属于已经结束的腿(续跑换新 legKey,争议判据按腿读),迟到决议也早在那些腿续跑时就受理过了;停驻本身另由
+ * 待决 checkpoint 那一源盖住。漏一条还要途中换三次态以上。
+ */
+export declare const MOVABLE_RUN_STATUSES: readonly string[];
+/** 审计账一次轮转的读数:删掉的问数 / 删掉的行数(含无主的腿记录)/ 留下的行数。 */
+export interface AuditRotationReading {
+    droppedAsks: number;
+    droppedRecords: number;
+    keptRecords: number;
+}
+/** 一次清扫的读数(进 `approval_ask_retention_swept` 行)。 */
+export interface ApprovalAskRetentionReading {
+    cutoffMs: number;
+    asks: number;
+    batches: number;
+    auditAsks: number;
+    auditRecords: number;
+}
+/** 问账 / 审计账 / run 账各自的窄口(测试用字面量驱动同一段生产代码;生产传整只店)。 */
+export type ApprovalAskReapPort = Pick<ApprovalAskStore, "reapSettledAsks" | "reapEmptyBatches">;
+export type AuditRotationPort = Pick<FileApprovalAskAuditStore, "rotateOlderThan">;
+export interface MovableRunPort {
+    listRuns(opts: {
+        status?: string;
+        limit: number;
+        cursor?: {
+            createdAt: string;
+            taskId: string;
+        };
+    }): Promise<ReadonlyArray<{
+        taskId: string;
+        sessionId: string;
+        createdAt: string;
+    }>>;
+}
+/** checkpoint 店的窄口:每一只待决 checkpoint 的会话(不按门型过滤 —— 运维队列 `listPending` 会藏起门型读不出、却仍能被决的行)。 */
+export interface MovableCheckpointPort {
+    listPendingSessionIds(): Promise<readonly string[]>;
+}
+/** 后台子代账的窄口(core `BackgroundAgentStore` 的两只运维面)。 */
+export interface MovableBackgroundAgentPort {
+    listScopes?(): Promise<string[]>;
+    listByScope(scope: string): Promise<ReadonlyArray<{
+        owner: string;
+        sessionId?: string;
+        parentSessionId?: string;
+        rootSessionId?: string;
+        status: BackgroundAgentRecord["status"];
+    }>>;
+}
+/**
+ * 还能动的东西的**挂靠集**(见文件头):run 账上每个 {@link MOVABLE_RUN_STATUSES} 词按 `listRuns` 的键集游标翻页列全,收 run id 与它的会话;
+ * 后台子代账逐 scope 一次列全(不带状态过滤 ⇒ 每个 scope 一次快照,子代在两种能动态之间换不会漏),能动的子代收它的 owner(task 作用域 =
+ * 宿主 run;会话作用域 = 会话)、宿主会话两格与它自己的会话;checkpoint 店的待决行一次列全,收它的会话。任一账读不出 ⇒ 抛 ⇒ 这次清扫
+ * 一行不删(证不出哪些不能动,就不删);
+ * 子代账在场却枚举不了 scope(缺 `listScopes`)同样抛。列与删之间新起的东西,它的问都比 cutoff 新,不会被删;终局不会回到能动。
+ */
+export declare function collectMovableAnchors(input: {
+    runs: MovableRunPort;
+    backgroundAgents: MovableBackgroundAgentPort | undefined;
+    /** 缺席 = 本部署没有后端(没有可列的停驻;后端在场就一定交得出读口 —— `StoreBackend.checkpointReadView` 必选,没有 checkpoint 店的后端交恒空读口)。调用方取后端自己的那只读口,不看这一世开没开 durable 停驻 —— 前世 / 别的副本留下的停驻照样在店里。 */
+    checkpoints: MovableCheckpointPort | undefined;
+}): Promise<ReadonlySet<string>>;
+/**
+ * 一次清扫:先列还能动的东西的挂靠集,再用同一个 cutoff 与同一只集敲问账(问 / 批各按批删到不满一批)、再轮转审计账。每条语句的删除数当场进计数
+ * `approval_ask_retention_rows_deleted_total{ledger}`;真删了东西 ⇒ 一行 `approval_ask_retention_swept`(半途失败也打,带 `incomplete: true`,
+ * 然后把错误原样抛给调用方 —— 维护 tick 的具名节流 catch 接住,连败即 warn)。
+ */
+export declare function runApprovalAskRetentionPass(input: {
+    askStore: ApprovalAskReapPort | undefined;
+    audit: AuditRotationPort | undefined;
+    runs: MovableRunPort;
+    backgroundAgents: MovableBackgroundAgentPort | undefined;
+    checkpoints: MovableCheckpointPort | undefined;
+    cutoffMs: number;
+    logger: Pick<Logger, "info">;
+    metrics: Pick<Metrics, "inc">;
+}): Promise<ApprovalAskRetentionReading>;
+//# sourceMappingURL=approval-ask-retention.d.ts.map