@sema-agent/server 7.132.0 → 7.134.0

package/dist/approval-ask-audit-store.d.ts

@@ -23,7 +23,7 @@
  *  - **不翻 `streamApproval` 能力位**([ref] 当时的裁 (c);⚠️ **这一位已由 S-384 翻真,不是被本店翻的**):
  *    当年不翻的理由是「该位在 SQL 车道隐含 durable park 兜底,local 给不了」+「local 的 ask 账是进程内
  *    易失形」。后半条已由 `FileApprovalAskStore` 消掉(持久账落地);前半条的答案一直在谓词里 ——
- *    `resolveStreamApprovalGate` 的 `parkFacility` 合取项要求 `backend.checkpoint` 在场 ∧ `DURABLE_APPROVAL`,
+ *    `resolveStreamApprovalGate` 的 park 设施(`checkpointStore`)合取项要求 `backend.checkpoint` 在场 ∧ `DURABLE_APPROVAL`,
  *    所以位报 true 的 local 部署**必然**配齐了 File 形 checkpoint 店(`durable-approval-local-e2e` 第一格
  *    实证:park 行跨双 kill 存活、重启后 decide 驱动 resume 真跑完)。本店与那一位自此无关:它治的是
  *    **活卡窗内崩溃**(park 还没落盘)那一格的零痕迹病,而那一格无论位真位假都不复活 run。
@@ -166,11 +166,16 @@
  * 同源(`store-backend.ts:780` 的 `config.localDataRoot`),数据落 `<root>/approval-ask-audit/`。
  *
  * ## 体量与保留
- * 只在真出卡时写(人批一次 = 3 行),量级 = 人的手速;账本只增不删,压缩是未来件(workflow-notify
- * journal 同款成文)。读面列表按收敛时刻新前旧后、上限 {@link CRASH_CONVERGED_LIST_MAX}(有界 wire)。
+ * 只在真出卡时写(人批一次 = 3 行),量级 = 人的手速。保留 = 审批账本的留存律(律一处成文在 `approval-ask-retention.ts`;维护 tick 按
+ * `APPROVAL_ASK_RETENTION_MS` 调 {@link FileApprovalAskAuditStore.rotateOlderThan}):**整问**删 —— 一问不再欠下一次起服收敛一个答案
+ * (下面的收敛判官此刻不会把它收成孤儿)且它所有记录里最晚的时刻早于 cutoff,它的全部行(铸造 / 决议 / 收敛 / 迟到结算)一起离开文件;
+ * 腿记录(按 taskId)只在没有任何留下的问还认它、且它自己也过窗时才删,于是留下的问的收敛投影(成因 / `resumeSafe`)一字不变;
+ * 认不出的行证不出到期,原样留;发起它的 run 还能动(跑着 / 停驻)的问也留。**只删不改**:留下的行逐字节写回(原子换文件,0o600),删了多少进读数行。
+ * 读面列表按收敛时刻新前旧后、上限 {@link CRASH_CONVERGED_LIST_MAX}(有界 wire)。
  */
 import type { HostDecision } from "./host-decision.js";
 import { AppendLog } from "@sema-agent/core";
+import type { AuditRotationReading } from "./approval-ask-retention.js";
 import { SETTLE_OUTCOME, type HolderGoneCause, type SettleCause } from "./approval-deny-reasons.js";
 /** 数据子目录名(挂在 local 数据根下,与 `workflow-notify/` 同层同形)。 */
 export declare const APPROVAL_ASK_AUDIT_DIR = "approval-ask-audit";
@@ -328,6 +333,8 @@ export declare class FileApprovalAskAuditStore implements ApprovalAskAuditSink,
     private log;
     /** 追加口的铸造座(测试注入席:单条写失败 / 半写的确定性构造;生产恒缺省 = `new AppendLog(path)`)。 */
     private readonly openLog;
+    /** 轮转换文件之后的目录 fsync(测试注入席:失败的确定性构造;生产恒缺省 = {@link fsyncDirectory})。 */
+    private readonly fsyncDir;
     /** boot 重放快照(冻结于构造时刻 = 前世账本;本进程新写的行不进它 —— 收敛只对前世行)。 */
     private readonly replayed;
     /** 前世账本里的腿闭事件(taskId + 行序;decided 臂按「决议行之后」判)。 */
@@ -369,12 +376,12 @@ export declare class FileApprovalAskAuditStore implements ApprovalAskAuditSink,
      */
     constructor(root: string, internals?: {
         appendLog?: (path: string) => AuditAppendPort;
+        fsyncDir?: (dir: string) => void;
     });
     /** 重放的坏值计数(`convergeCrashedAsks().corruptLines`):重放属主跳过的坏行(撕尾不计)+ 成因词表外的行(行在、结清照认,坏值照样计数)。 */
     private corruptLines;
     /** 重放前世账本(共用口 `replayJsonlSkipping`):撕尾 = 未落完的写,静默跳过;坏行跳过 + 逐条计数 / 探针;坏行数另暴露给收敛日志。 */
     private replay;
-    private group;
     /** append + fsync(逐行落盘:进程猝死不丢已记的行 —— 本店的全部价值就在崩溃时刻;写口 = 共用的 `AppendLog`:单次 `writeSync` 一行、末段在打开与每次追加前修(撕尾截、完整末行补换行)、失败的写截回开写处)。
      *  运行期失败**响亮不阻断**:审批可用性不押在审计盘上(盘满/只读时人还得能批),但丢行必须在遥测
      *  显形([ref] 三件套,census 登记行同批)。
@@ -445,18 +452,29 @@ export declare class FileApprovalAskAuditStore implements ApprovalAskAuditSink,
     /** S-929 收敛行的成因注(判据见头注「收敛行的 `cause`」):组的最后一个事件行之后、收敛行(若已收敛)之前,有本 taskId 的
      *  有序关停记号 ⇒ `shutdown_before_park`;否则 `crashed_before_park`。 */
     private causeOf;
-    /**
-     * 🔴 **S-945([ref])—— 腿证据只对被追踪的 ask 行作数**:一处成文,三处读(pending 臂的腿闭反证门 / decided 臂 / 收敛行成因注)。
-     * 腿闭行与有序关停记号都只按 `taskId` 落;委派 / 后台子代 ask 行的 `taskId` 是**宿主** run(出处),承载它的不是宿主腿(铸造时
-     * `legTracked:false`)⇒ 宿主腿的这两类记录对它什么都不证明(修前反证门不看 `legTracked`:宿主腿闭把子代未结清卡判成 inconsistent、不列孤儿)。
-     * 返回 `undefined` = 这一行没有可作证的腿;否则 = 本 taskId 在 `(afterLine, beforeLine)` 之间有没有该类记录。
-     */
-    private legEvidence;
     private projectRow;
-    /** scope 门与 `listLivePending` 逐字同律:`undefined` = operator 全量(含 owner null 行);串 = 只见
-     *  `owner === scope` 的行(null-owner 行对 principal 不可见,fail-closed 宁少列不超范围;`"__none__"`
-     *  未鉴权哨兵自然恒空)。 */
+    /** scope 门与 `listLivePending` 逐字同律(同一只 checkpoint scope 解码):`undefined` = operator 全量(含 owner null 行);
+     *  `_` = 匿名那一组 = owner null 的行;其余串 = 只见 `owner === scope` 的行(null-owner 行对具名主体不列,宁少列不超范围)。 */
     listCrashConverged(scope: string | undefined): CrashConvergedRow[];
+    /**
+     * **留存轮转**(审批账本留存律的审计账半场;律一处成文在 `approval-ask-retention.ts`,判据见头注「体量与保留」)。维护 tick 是唯一调用方。
+     *
+     * 读的是**文件**(前世 + 本进程两段账,行序即语义序),不是构造时冻结的前世快照:本进程铸的问要按它此刻在盘上的样子判「结了没有」。
+     * 判「结了」= 它挂靠的格(铸造行的 `taskId` / `sessionId` / `sourceTaskId`)都不在 `keepAnchors`(还能动的东西的挂靠集,由清扫从 run 账与
+     * 后台子代账列出)∧ {@link judgeOrphan} 此刻不欠它答案 —— 停驻 run / 能动子代的问(窗到期转 durable、迟到结算还要这组前置事实)、活卡
+     * (铸了没决)与批了腿没闭的问多老都留。删的单位是**整问**:
+     *  · 一问的最后动静 = 它所有记录(铸造 / 决议 / 收敛 / 迟到结算)里最晚的时刻;早于 cutoff ∧ 不欠答案 ⇒ 这一问的全部行删;
+     *  · 腿记录(按 taskId)只在它自己也早于 cutoff ∧ 没有任何留下的问是这个 taskId ∧ 这个 taskId 不在挂靠集时才删 —— 留下的问的收敛投影(成因 / `resumeSafe`)读得到的腿证据一条不少;
+     *  · 身份说不清的迟到结算(`approvalId:null`)按它自己的时刻;认不出的行(腐行 / 词表外)证不出到期 ⇒ 原样留;
+     *    末尾没换行的那一段原样留在末尾(不补换行),由追加口下次打开时按 core 的同一只判词修(解析成对象补换行、撕尾截断)。
+     * 只删不改:留下的每一行按**原字节**写回(按换行字节切段,不经解码 —— 非 UTF-8 的字节一个不变),原子换文件({@link replaceFileBytes}:
+     * 0o600;换上之前失败 ⇒ 原文件原样,错误抛给维护 tick 的节流 catch;换上之后只剩目录 fsync,失败走 F 类 tag、读数照交);
+     * 追加口先收,下一次 append 在新文件上惰性重开。没有可删的行 ⇒ 文件一字不动、不重写。
+     *
+     * 内存同步剪:被删的问离开迟到结算的反查索引(之后对它的迟到决议证不出「窗到期已转 durable」⇒ 一行不写 —— 盘上查无前置事实的行不许写)、
+     * 离开 `crashConverged` 读面与前世快照。前世快照里留下的组与腿记录的行序不动(它们只在起服收敛那一拍被读,彼此仍自洽)。
+     */
+    rotateOlderThan(cutoffMs: number, keepAnchors: ReadonlySet<string>): AuditRotationReading;
     /** 收追加口(优雅关闭腿;SIGKILL 下不跑也不丢 —— 每行已 fsync)。core `AppendLog.close()` 自己吞 `closeSync` 的错、不抛(全函数),本店不再包 catch。 */
     close(): void;
 }

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"],