@sema-agent/server 7.43.0 → 7.44.0

package/dist/rules-consent.js

@@ -1,134 +1,27 @@
-/**
- * #154 车二 —— **同意车道的 server 半场**(core 5.18.0 design/179 `permission-rule-consent.ts` 的宿主侧)。
- *
- * core 把一条规则进店的路钉成三步:`durable approval record (pending)` → `authenticated confirmation
- * transfer (approved)` → `principal-bound redemption (redeemed)`,而且**只有第三步**够得着写面。core 明写
- * 「The confirmation transfer is an in-process call. **A deployment must reach it only from its
- * authenticated approval channel**」—— 那句话是把一段责任**交给宿主**,不是一段已经完成的检查。本文件就是
- * 那段责任的落点:
- *
- *  · 卡道(兑付口):一次 ask 决议携「不再询问」时,由**这里**去 prepare→confirm→redeem。人是谁 =
- *    回决端点已验明的 principal(不是请求体里的任何字段);规则文本 = **引擎**从被裁决的命令铸的候选
- *    (`prepareCardApproval` 不收调用方候选,core 在那条入口上已经把「写自己的规则」这件事变成不可拼写),
- *    客户端只能说「我选第几个」。
- *
- *  · 导入道(CC settings):`prepare` 读用户交上来的 settings 层、铸 pending 记录 + **server 自铸的票**;
- *    `redeem` 原子消费票、confirm、`redeemRuleBatch`。
- *
- * ─────────────────────────────────────────────────────────────────────────────────────────────────
- * 🔴 票的信任边界四条,**全部是 server 附加的**(不是 core 的语义)
- * ─────────────────────────────────────────────────────────────────────────────────────────────────
- * 亲读 core 的 `mintRuleTicket`(dist,5.22.0):`return \`rt.${candidateIndex}.${recordId}\`` —— 它**没有**
- * TTL、没有签名、没有消费位、没有载荷绑定。core 的票在**进程内**是够的(它的相邻语义是「重放同一次兑付是
- * 幂等的」),但一条跨网络、由客户端保管、可被复制的票需要另外四样:
- *   ① **principal 绑定** —— redeem 的已验明 principal 必须 = prepare 铸票的那一位。跨 principal redeem 与
- *      unknown ticket **同形 404**:两者返回不同的码就是一台存在性 oracle(拿别人的票撞库能探到「它存在」)。
- *   ② **过期** —— `RULE_IMPORT_TICKET_TTL_MS`;过期 redeem 拒。
- *   ③ **一次性原子消费** —— 同票二次 redeem 拒,并发双 redeem **恰一成功**。判据由 SQL 的单条条件
- *      `UPDATE … WHERE consumed_at_ms IS NULL` 回答,**禁 read-then-write**(见 store 那侧的 🔴 注)。
- *   ④ **载荷绑定** —— redeem 应用的规则集 = prepare 时刻的快照。core 已经结构上保证了「规则文本来自记录」,
- *      本层再加一道:票上钉着 prepare 时刻候选集的摘要,redeem 时与记录上的候选集重算比对,不符即拒 ——
- *      于是「篡改记录再拿旧票兑付」这条路上多一道等式,而不是只靠「记录只有我们能写」这一条信念。
- *
- * 命名(CLAUDE.md 工厂律):`build*` = 纯数据;`create*` = 活对象。本文件的 {@link createRuleConsentLane}
- * 返回一个带方法的束 ⇒ `create*`。
- */
 import { randomUUID } from "node:crypto";
 import { recordFailOpen } from "./observability/fail-open.js";
+import { createLogger } from "./observability/logger.js";
 import { MAX_CWD_CHARS } from "./task-cwd.js";
-import { confirmRuleApproval, prepareCardApproval, prepareCcImport, redeemRuleBatch, redeemRuleTicket, removePersistedRule, } from "@sema-agent/core";
+import { confirmRuleApproval, parseAllowRuleText, prepareCardApproval, prepareCcImport, redeemRuleBatch, redeemRuleTicket, removePersistedRule, } from "@sema-agent/core";
 import { buildRulePayloadHash } from "./plugins/permission-rule-store-sql.js";
-/** 导入票的存活窗。人从「看到预览」到「按下确认」是一次交互,不是一段会话——十分钟宽到不会误伤,
- *  窄到一张泄漏的票不会常驻。运维旋钮暂不开(没有部署形要求它可调;要开时走 config.ts 的既有姿势)。 */
 export const RULE_IMPORT_TICKET_TTL_MS = 10 * 60_000;
-/** 可重试那一支通告给客户端的等待秒数(`state.rule_import_retry` 的 `retryAfterSec` / `Retry-After`)。
- *  短 —— 它对应的是一次瞬时 store 抖动,不是排队。**单一真源在本文件**:放回认领时要用它判「这张票
- *  还能不能撑过这段窗」,HTTP 层要用它填响应,两处用同一个数才谈得上「承诺兑得出来」。 */
 export const RULE_IMPORT_RETRY_AFTER_SEC = 2;
-/**
- * **全部层合计**的候选上限(codex 交叉复审 round7 [high] 二,验真后修)。
- *
- * 单层 16 KiB 只管住了**请求体**,管不住**下游工作量**:紧凑的合法规则(`Bash(ls)` 十个字符)能让三层
- * 塞进上千条候选,而 core 的 `redeemRuleBatch` 是**逐候选**跑一遍「读店 + CAS 写」的串行循环 —— 一个
- * 已鉴权的请求就能把连接池占满、把响应撑到兆字节。全局限流器默认是关的,拦不住它(一次准入就够了)。
- *
- * 帽数的是 **core 已经解析好的候选**(不是我们自己再数一遍 JSON):零重复解析,而且数的正好是那条串行
- * 循环的**真实**长度。位置在**铸票之前** —— 超限就没有票,那条昂贵的循环一次都跑不起来(代价只剩一条
- * 已铸的 pending 记录,与任何一次没去兑付的 prepare 留下的残余同形)。
- * 200 的取值:一份人手写的 CC settings 极少超过几十条;200 给了一个数量级的余量,又把最坏工作量钉在
- * 「几百次 SQL」而不是「几万次」。
- */
 export const MAX_IMPORT_CANDIDATES = 200;
-// ─────────────────────────────────────────────────────────────────────────────────────────────────
-// #203 §2 —— 撤销面(`GET /v1/rules` + `DELETE /v1/rules`)的车道半场
-// ─────────────────────────────────────────────────────────────────────────────────────────────────
-/**
- * scope 的 **wire 形**:`global` | `project:<root>` 的判别式串(design/203 v2 §6 F5「显式成文」)。
- *
- * 🔴 为什么是一个串而不是把 core 的 `{kind, root}` 对象直接上 wire:这一份表示要同时当**列举结果里的
- * 一列**、**查询参数**、**删除请求体的一个字段**和**分页游标的一部分**。四处若各用各的形,「删掉我刚才
- * 列出来的那一行」就变成一次跨形状翻译 —— 而那正是最容易漂的地方。判别式串在四处逐字相同,而且
- * `project:` 前缀让「这条规则是项目内的」在一眼扫日志时就成立。
- *
- * `root` 里可以含冒号(路径合法),所以只切**第一个**冒号 —— 用 `split(":")` 取 [1] 会把
- * `project:/a:b` 悄悄截成 `/a`,那是一条**放宽面**上的静默改写(更短的 root 覆盖更多 cwd)。
- */
 export function serializeRuleScope(scope) {
     return scope.kind === "global" ? "global" : `project:${scope.root}`;
 }
-/**
- * 🔴 判别式串的**上限,由铸侧的尺派生**(A-054.24,2026-08-19 合并重扫 confirmed —— 修的是「两个数字
- * 各挑各的」这件事本身,不是把某个数字调大一点)。
- *
- * 病:铸侧 `cardRuleScopeRoot` 对 root 长度零把关(入口尺 = `isValidCwd` 的 {@link MAX_CWD_CHARS}),
- * core 与两个店都只校验 `root.min(1)` ⇒ 写面全程无阻;而 `DELETE /v1/rules` 的体 schema 此前独立写死
- * `scope: max(1088)`,且 safeParse 排在 `parseRuleScope`/权限判据**之前** ⇒ 超限 root 的规则
- * `GET /v1/rules` **列得出**、按同一串 DELETE **恒 400**。全仓只有一个 `lane.removeRule` 调用点(直删
- * 店行是无墓碑硬删、会被 sync 的 join 复活),所以那是**一条已列出的常驻放行规则在受支持接口上不可撤**;
- * 唯一的钝器补偿是 `PERMISSION_RULES_ENABLED=false`(关掉全部规则,两口自身随之 501)。
- *
- * ⚠️ 可达性在 A-054.F-A 之后**变严重**:那批把铸侧出口从 `realpath` 改成 `path.resolve`,而 realpath
- * 要求目录真实存在(macOS PATH_MAX=1024 ⇒ 宿主上 root 恒 ≤1023,结构性免疫);`path.resolve` 纯词法、
- * 不碰盘 ⇒ **任何宿主上** 1081..4096 字符的注册 cwd 都能铸出这样一条规则。
- *
- * 取值 = `"project:"` 前缀 + 铸侧 root 的入口尺。`path.resolve` 对「已绝对、无 `..` 段」的路径不加长
- * (`isValidCwd` 两条都要求),故 {@link MAX_CWD_CHARS} 是 root 的真上界。**两侧从此同源**:谁改铸侧
- * 的尺,撤侧自动跟。
- */
 export const MAX_RULE_SCOPE_CHARS = "project:".length + MAX_CWD_CHARS;
-/** {@link serializeRuleScope} 的逆。读不出形 ⇒ `undefined`(调用方 400,绝不猜一个 global 出来 ——
- *  猜 global 会把一次「删项目内规则」的请求变成一次删不掉任何东西的 no-op,或者更糟)。 */
 export function parseRuleScope(text) {
     if (text === "global")
         return { kind: "global" };
     if (!text.startsWith("project:"))
         return undefined;
     const root = text.slice("project:".length);
-    // 空 root 硬拒:`{kind:"project", root:""}` 在 core 的 `pathWithinRoot` 下**包含每一个 cwd**
-    // (空前缀包含一切)——一条项目内规则就此悄悄升成全局规则(cc-import 那侧同判据,同一条 codex 发现)。
     return root === "" ? undefined : { kind: "project", root };
 }
-/**
- * 桶引用 → 具体的规则店。
- *
- * 🔴 **穷举判别,未知形一律抛**(CLAUDE.md 词表闭集律 + codex 对抗复审 R3-[medium],验真后改)。
- * 第一稿写的是 `kind === "principal" ? 甲 : 乙` 的二分:TS 那侧是穷举的,**运行期不是** —— 本车道是
- * 一个**导出**的束,调用方可以是任何一层(HTTP 路由今天只递裸串,但这条口正是为了将来递结构形才开的)。
- * 于是 `{kind:"principle"}`(拼错)或 `{}` 会静默落进 local-owner 那支 = 一次**跨桶读**;更坏的是
- * 同一个坏值递给 core 的 `removePersistedRule` 时它按 `kind === "local-owner"` 反着判,落到
- * `forPrincipal(undefined)`(空店)—— 列举和撤销**指向两只不同的桶**,而两边都不报错。
- * 身份面上「不认识的形」只有一个正确答案:响亮拒。
- *
- * 🔴 local-owner 桶而 provider 没有 `forLocalOwner` ⇒ 同样**抛**,不静默回落到别的桶。回落到
- * `forPrincipal(…)` 会把「读/删身份缺席桶」变成「读/删某个 principal 的桶」——那是一次跨桶的读或写,
- * 是本车道最不该出的错。报文与 core 的 `removePersistedRule` 同支同措辞(那侧回 `failed` 带
- * `forLocalOwner` 字样),两侧一起读日志时对得上。
- */
 function storeForBucket(provider, ref) {
-    // 裸串 = principal 简写(core `removePersistedRule` 的同款归一,两侧对同一个输入判同一只桶)。
     if (typeof ref === "string")
         return provider.forPrincipal(ref);
-    // `ref.kind` 在类型上是闭集;`switch` 的 default 是**运行期**的那道门(不是死码)。
     switch (ref.kind) {
         case "principal":
             return provider.forPrincipal(ref.principal);
@@ -138,44 +31,52 @@ function storeForBucket(provider, ref) {
             }
             return provider.forLocalOwner();
         default: {
-            // core 给 `RuleOwner` 加员时这里是**编译**红(`never` 赋值失败),不是静默继承某一支。
             const unknown = ref;
             throw new Error(`unrecognised permission-rule bucket reference (${JSON.stringify(unknown)}) — refusing to guess which bucket it names`);
         }
     }
 }
+function isSupportedRuleMatch(match) {
+    switch (match) {
+        case "exact":
+        case "prefix":
+            return true;
+        default: {
+            const unknown = match;
+            void unknown;
+            return false;
+        }
+    }
+}
+const unknownReasonLogger = createLogger();
+function confirmRefusalWord(reason) {
+    switch (reason) {
+        case "edit_disabled":
+        case "edit_binding_mismatch":
+            return "edit-unsupported";
+        case "edit_rejected":
+            return "edit-rejected";
+        case "record_not_found":
+        case "selection_missing":
+        case "selection_invalid":
+        case "selection_mismatch":
+        case "batch_takes_no_selection":
+        case "not_pending":
+        case "conflict":
+            return "confirm-refused";
+        default: {
+            const unknown = reason;
+            unknownReasonLogger.warn("confirmRefusalWord: unknown ConfirmRefusalReason from core (dist/core version skew?) — folded to confirm-refused", { reason: String(unknown) });
+            return "confirm-refused";
+        }
+    }
+}
 export function createRuleConsentLane(stores, opts) {
-    const deps = { provider: stores.provider, approvals: stores.approvals };
+    const deps = { provider: stores.provider, approvals: stores.approvals, cardEdits: true };
     const ticketTtlMs = opts?.ticketTtlMs ?? RULE_IMPORT_TICKET_TTL_MS;
     const newTicketId = opts?.newTicketId ?? (() => randomUUID());
     const monotonic = opts?.monotonic ?? (() => performance.now());
-    /**
-     * [4232]③/[4235]③ —— **本进程铸出的票**的单调锚台账。
-     *
-     * 病灶(test 真机两条读数):`expiresAtMs = 铸票时刻的墙钟 + TTL`。墙钟在铸票与兑付之间被拨动 ⇒
-     *  ·(前拨)真实只过 3 秒的票被判过期;
-     *  ·(铸票时钟本身慢了 11 分钟,随后被 NTP 纠正)票**出生即过期** —— `expiresAtMs` 换算出的时刻
-     *    比这张票真实铸出的时刻还早一分钟。
-     * core [4235]③ 的判词「从票据内部无解」是对的:`mintedAt` 与 `expiresAt` 同源同错,行里没有第二个基准。
-     * 但**铸票与兑付发生在同一个进程**时,进程自己有第二个基准 —— 单调钟。于是判定钟改成
-     *   `判定 now = 铸票时刻的墙钟 + (单调钟现在 − 单调钟铸票时)`
-     * 即「签发与判定同源单调锚」。它**给不了票额外寿命**:投影严格按单调钟前进,真实走满 TTL 就必然越过
-     * `expiresAtMs`(负控钉在 db-integration 里)。记账列(`consumed_at_ms`)一律仍是真墙钟。
-     *
-     * 🔴 **射程边界 —— 未闭合的残余,如实登记**(codex 对抗复审 R1 [high] 四,验真后**接受**):本锚只活在
-     * 当前进程的 Map 里。prepare 与 redeem 被负载均衡分到**不同副本**时(不需要故障,常规轮询就够),
-     * `decisionClock` 返回 undefined、store 退回该副本的墙钟 —— 那台副本若有钟偏,有效票**仍会**出生即过期。
-     * 也就是说本修把缺陷从「所有兑付」缩小到「跨副本兑付」,**没有消灭它**;正确性因此隐含依赖了一条
-     * 没人声明过的会话粘滞。不要把这条注读成「已解」。
-     *
-     * 收口方向(下一批,不在本小件批射程):把判定权威换成**两副本共享的那口钟 —— 数据库自己的钟**:
-     * 铸票时 `expires_at_ms = <db now> + ttl`、兑付时 `WHERE expires_at_ms > <db now>`
-     * (MySQL `CAST(UNIX_TIMESTAMP(NOW(3))*1000 AS SIGNED)` / PG `(EXTRACT(EPOCH FROM clock_timestamp())*1000)::bigint`)。
-     * 那一形对**所有**副本同时成立,还能把本台账整个删掉。记账列仍走进程墙钟(两钟分家的语义不变)。
-     */
     const anchors = new Map();
-    /** 台账只服务「本进程铸、本进程兑」的窗,所以按单调钟自清:超过一个 TTL 的锚已经不可能改变任何判定。
-     *  另加一个硬帽,免得一条只 prepare 不 redeem 的路径把 Map 撑大(每条锚两个 number,帽住即够)。 */
     const ANCHOR_CAP = 4096;
     const pruneAnchors = (nowMono) => {
         for (const [id, a] of anchors) {
@@ -184,7 +85,6 @@ export function createRuleConsentLane(stores, opts) {
         }
         if (anchors.size <= ANCHOR_CAP)
             return;
-        // 仍然超帽 ⇒ 丢最老的(Map 迭代序 = 插入序 = 铸票序)。丢掉只是退回墙钟判定,不产生错判方向。
         const excess = anchors.size - ANCHOR_CAP;
         let dropped = 0;
         for (const id of anchors.keys()) {
@@ -193,22 +93,12 @@ export function createRuleConsentLane(stores, opts) {
             anchors.delete(id);
         }
     };
-    /**
-     * 本进程铸的票 ⇒ 单调投影;别处铸的 ⇒ `undefined`(store 退回墙钟,既有行为逐字不变)。
-     *
-     * 🔴 `Math.ceil` 不是装饰:①`performance.now()` 是**小数**毫秒,而 `expires_at_ms` 是 BIGINT 列 ——
-     * 小数直接绑进 PG 会 `invalid input syntax for type bigint`(真双库当场逮到,mysql2 那侧则会静默接受,
-     * 正是「一个方言绿一个方言红」的经典形);②取整方向必须**保守**:判定式是 `expires_at_ms > 判定 now`,
-     * 判定 now 取小 = 票更晚过期,所以向上取整才不会白送半毫秒寿命。
-     */
     const decisionClock = (ticketId) => {
         const a = anchors.get(ticketId);
         return a === undefined ? undefined : { decisionNowMs: Math.ceil(a.mintedAtWall + (monotonic() - a.mintedAtMono)) };
     };
     return {
         async persistCardRule(input) {
-            // 🔴 候选**由引擎铸**(core `prepareCardApproval` 不收调用方候选;那条入口上「写自己的规则」
-            // 结构上不可拼写)。本层只把「人选了哪一个」翻译成下标。
             const prepared = await prepareCardApproval({
                 principal: input.principal,
                 toolName: input.toolName,
@@ -221,22 +111,50 @@ export function createRuleConsentLane(stores, opts) {
             if (prepared === undefined) {
                 return { ok: false, reason: "no-candidates", detail: "the rule lane cannot speak for this command (compound / redirection / unsupported tool)" };
             }
-            const index = prepared.candidates.findIndex((c) => c.rule === input.ruleText);
-            const ticket = index < 0 ? undefined : prepared.tickets[index];
-            if (index < 0 || ticket === undefined) {
-                return { ok: false, reason: "unknown-candidate", detail: "the chosen rule text is not one the engine minted for this command" };
+            const redemption = input.redemption;
+            let ticket;
+            if (redemption.kind === "offered") {
+                const index = prepared.candidates.findIndex((c) => c.rule === redemption.ruleText);
+                const offered = index < 0 ? undefined : prepared.tickets[index];
+                if (index < 0 || offered === undefined) {
+                    return { ok: false, reason: "unknown-candidate", detail: "the chosen rule text is not one the engine minted for this command" };
+                }
+                const confirmed = await confirmRuleApproval({ approvalId: prepared.approvalId, principal: input.principal, selectedCandidate: index, deps });
+                if (!confirmed.ok)
+                    return { ok: false, reason: "confirm-refused", detail: confirmed.reason };
+                ticket = offered;
+            }
+            else {
+                if (input.boundInputHash === undefined) {
+                    return { ok: false, reason: "edit-unsupported", detail: "this approval card carries no bound-input digest — an edited rule has nothing to bind to" };
+                }
+                const confirmed = await confirmRuleApproval({
+                    approvalId: prepared.approvalId,
+                    principal: input.principal,
+                    editedCandidate: { text: redemption.text, boundInputHash: input.boundInputHash },
+                    deps,
+                });
+                if (!confirmed.ok)
+                    return { ok: false, reason: confirmRefusalWord(confirmed.reason), detail: confirmed.detail?.message ?? confirmed.reason };
+                const minted = confirmed.mintedCandidate;
+                if (minted === undefined) {
+                    return { ok: false, reason: "confirm-refused", detail: "the edited confirmation landed without a minted candidate — nothing to redeem" };
+                }
+                const canonical = parseAllowRuleText(minted.rule);
+                if ("reject" in canonical) {
+                    return { ok: false, reason: "edit-rejected", detail: `the canonical spelling the engine minted does not re-parse: ${canonical.reject.message}` };
+                }
+                if (!isSupportedRuleMatch(canonical.rule.match)) {
+                    return { ok: false, reason: "edit-rejected", detail: `the edited rule resolves to an unsupported match form (${String(canonical.rule.match)})` };
+                }
+                ticket = minted.ticket;
             }
-            const confirmed = await confirmRuleApproval({ approvalId: prepared.approvalId, principal: input.principal, selectedCandidate: index, deps });
-            if (!confirmed.ok)
-                return { ok: false, reason: "confirm-refused", detail: confirmed.reason };
             const redeemed = await redeemRuleTicket({ ticket, principal: input.principal, deps });
             if (redeemed.status !== "redeemed")
                 return { ok: false, reason: "redeem-refused", detail: redeemed.reason };
             return { ok: true, rule: redeemed.rule, rev: redeemed.rev, alreadyRedeemed: redeemed.alreadyRedeemed };
         },
         async prepareImport(principal, layers) {
-            // core 的 `CcImportLayer.readFile` 是一条**注入的**读口 —— 云端部署没有用户的文件系统,内容由
-            // 调用方交上来(这是本仓的部署形,不是绕过:读的仍然只是 allow 桶,拒/问桶是收紧方向、另有通道)。
             const ccLayers = layers.map((l) => ({
                 layer: l.layer,
                 path: l.path,
@@ -244,11 +162,7 @@ export function createRuleConsentLane(stores, opts) {
                 readFile: async () => l.content,
             }));
             const { preview, approvalId } = await prepareCcImport({ layers: ccLayers, principal, deps });
-            // 帽在**铸票之前**(见 {@link MAX_IMPORT_CANDIDATES}):没有票 ⇒ 那条逐候选的串行 SQL 循环跑不起来。
             if (preview.candidates.length > MAX_IMPORT_CANDIDATES) {
-                // core 在**返回预览之前**就把 pending 记录落了盘 ⇒ 这次不做的导入会留一条永远没人要的行。
-                // 收掉它(codex round8 [medium]:被拒的 prepare 不该在共享库里长东西)。best-effort:收不掉
-                // 也只是留一条 pending 孤儿,不影响任何判决 —— 但**绝不**因此把 413 变成 500。
                 try {
                     await stores.approvals.discardPendingRecord?.(approvalId);
                 }
@@ -257,8 +171,6 @@ export function createRuleConsentLane(stores, opts) {
                 }
                 return { ok: false, reason: "too-many-candidates", candidates: preview.candidates.length };
             }
-            // [4232]③:铸票**当拍**同时钉下两只钟 —— 墙钟锚取 `minted.expiresAtMs - ttlMs`(= store 自己用的
-            // 那个铸票时刻,不另取一次 `Date.now()`:两处各取一次会让锚与行差出一跳的量),单调锚取本进程单调钟。
             const mintedAtMono = monotonic();
             const minted = await stores.tickets.mint({ ticketId: newTicketId(), principal, approvalId, candidates: preview.candidates, ttlMs: ticketTtlMs });
             pruneAnchors(mintedAtMono);
@@ -266,65 +178,33 @@ export function createRuleConsentLane(stores, opts) {
             return { ok: true, preview, ticket: minted.ticketId, expiresAtMs: minted.expiresAtMs };
         },
         async redeemImport(principal, ticket) {
-            // ①②③ 一次原子**认领**同时回答(principal 绑定 / 未过期 / 未认领);四类拒绝在 wire 面同形。
-            // [4232]③:判定钟走本进程的单调锚(本进程没铸过这张票 ⇒ undefined ⇒ store 退回墙钟)。
             const clock = decisionClock(ticket);
             const consumed = await stores.tickets.consume(ticket, principal, clock);
             if (!consumed.ok)
                 return { ok: false, reason: "ticket-unusable", detail: consumed.reason };
-            // 🔴 codex round1 [high] 一(验真后修):认领**之后**的每一步都可能失败,而旧形把认领当终局 ⇒
-            // 一次 store 抖动就永久烧掉这张票,客户端拿到与「票不存在」同形的 404,重试无门。
-            // 处置:裁定性拒绝(载荷被篡改 / 记录不存在)**留着**认领(重试不改判);不确定/瞬时失败**放回**
-            // 认领并标 `retryable`。放回不打开双兑付的门(认领仍是单持有者),兑付腿本身按 core 的设计幂等。
-            // 🔴 codex 交叉复审 round3 [high] 一(验真后修):返回值是**「认领确实放回去了吗」**,不是 void。
-            // 旧形无条件回 `retryable: true`,而释放本身也可能失败(同一场 store 故障往往两跳一起挂)——
-            // 那就变成对客户端**撒谎**:它拿着一张其实已经烧掉的票去重试,只会收到 404,人的确认永久丢失。
-            // 判据必须是「释放**确认**成功」;没确认就不许承诺重试(如实按不可重试报,四类同形 404)。
             const releaseClaim = async () => {
                 try {
-                    // 🔴 判定钟**当场重取**,不复用 `consume` 那次的读数(F-B,2026-08-17 合并码扫描)。同锚(同一张票的
-                    // `mintedAtWall`/`mintedAtMono`)、同尺(同一只单调钟),但**读数必须是现在**:
-                    //  · `consume` 问的是向后看的问题(此刻窗还开着吗);`release` 问的是向前看的问题(这张票能不能
-                    //    活过我即将通告的 Retry-After)。第二问只有在**释放这一刻**问才有意义。
-                    //  · capture 与这里之间隔着 consume 两往返 + approvals.get + confirmRuleApproval 的 CAS/OCC +
-                    //    最多 MAX_IMPORT_CANDIDATES 条候选的串行兑付循环,而本闭包**只在店退化时**才被走到 ——
-                    //    缺陷发作时这段恰恰最长(秒级 vs 2s 的窗),旧注那句「重取一次投影只会多走几微秒」说的是
-                    //    重取的**成本**,却被当成了流逝量的上界,那是两件事。
-                    //  · 单调钟不回退 ⇒ 冻结读数恒 ≤ 新读数 ⇒ 误差全部落在 **permissive** 一侧,而 store 侧 `release`
-                    //    的头注把这道门定义成保守门(「承诺一次必然兑现不了的重试比不承诺更坏」)。
-                    // 本进程没铸过这张票时两处都回 undefined(store 退回墙钟),语义逐字不变。
                     return await stores.tickets.release(ticket, principal, RULE_IMPORT_RETRY_AFTER_SEC * 1000, decisionClock(ticket));
                 }
                 catch (err) {
-                    // 放不回去 = 回到「认领即烧票」的旧形(属主这一轮不能重试,票随 TTL 消失)。**不**把一次
-                    // 已经失败的请求再变成一次抛错;但也**不**静默 —— 登记的 F 类兜底,理由逐字见 tag 词表。
                     recordFailOpen("server.rules.ticket-claim-release-failed", err instanceof Error ? err.message : String(err));
                     return false;
                 }
             };
-            /** 「不确定」那一支的统一收口:**释放确认成功**才承诺可重试。 */
             const indeterminate = async (detail) => {
-                // 放回之后这张票至少要能撑过我们通告的等待窗 —— 撑不过就不承诺重试(见 store 侧 `release` 头注)。
                 const released = await releaseClaim();
                 return { ok: false, reason: "record-unusable", detail, ...(released ? { retryable: true } : {}) };
             };
             try {
-                // ④ 载荷绑定:记录上的候选集必须与铸票时刻的快照同摘要。
                 const record = await stores.approvals.get(consumed.approvalId);
                 if (record === undefined)
                     return { ok: false, reason: "record-unusable", detail: "the approval record behind this ticket is gone" };
                 if (buildRulePayloadHash(record.candidates) !== consumed.payloadHash) {
                     return { ok: false, reason: "payload-mismatch", detail: "the approval record's candidates changed after the ticket was minted" };
                 }
-                // 🔴 确认是**一次性状态跃迁**,不是每次兑付都要过的门:重试一张**放回过认领**的票时,记录
-                // 早已不是 `pending` 了(core 的崩溃序:`redeemRuleTicket` 在调用写面**之前**就把记录推到
-                // `redeemed`,所以哪怕一个候选都没落地,状态也已经变了)。对已确认的记录再调一次
-                // `confirmRuleApproval` 会拿到 `not_pending` —— 把它当拒绝就等于「放回了认领却永远兑不动」,
-                // round1/round3/round5 那一串修复到此全部白做。判据用记录**自己的状态**,不是猜错误串。
                 if (record.state === "pending") {
                     const confirmed = await confirmRuleApproval({ approvalId: consumed.approvalId, principal, deps });
                     if (!confirmed.ok) {
-                        // `conflict` = CAS 输给了一个并发写者(瞬时);其余是裁定(记录不存在/状态不对)。
                         if (confirmed.reason === "conflict")
                             return await indeterminate(confirmed.reason);
                         return { ok: false, reason: "record-unusable", detail: confirmed.reason };
@@ -332,19 +212,8 @@ export function createRuleConsentLane(stores, opts) {
                 }
                 const result = await redeemRuleBatch({ approvalId: consumed.approvalId, principal, deps });
                 if ("status" in result) {
-                    // core 的 refused 里既有裁定也有瞬时(OCC 用尽 / 店读不出来)——分不清就按**可重试**放回:
-                    // 兑付是幂等的,多放一次认领最坏是多跑一遍同样的重放;烧掉一张真票是不可逆的。
                     return await indeterminate(result.reason);
                 }
-                // 🔴 codex 交叉复审 round5 [high] 二(验真后修):core 的 `redeemRuleBatch` 把**逐候选**的失败
-                // 记在 `skippedAtRedeem` 里,顶层照样返回一个 ImportResult —— 只判顶层 `status` 会把「一半没落地」
-                // 当成功回 200,而认领已经烧掉,那一半再也补不回来。
-                // 为什么这条车道可以把「非空 skippedAtRedeem」一律当**不确定**:候选在 `prepareCcImport` 那一步
-                // 就已经全过了同一个验证器(过不了的进 `preview.skipped`,压根不进记录),所以兑付期的逐候选拒绝
-                // 实际只剩「店读不出/写不进 / OCC 用尽 / 隔离栅栏」这类**瞬时或异常**成因。重放是幂等的
-                // (记录里存着每个候选已铸的 dot),所以放回认领让人重试,代价上界只是再跑一遍同样的重放。
-                // 残留(如实登记):真出现一条**永久**被拒的候选时,客户端会一直拿到 503 直到票到期(10 分钟)——
-                // 有界、且不破坏任何已落地的规则;要更好得让 core 把逐候选拒绝分成瞬时/裁定两类,已列后续件。
                 if (result.skippedAtRedeem.length > 0) {
                     return await indeterminate(`partial import: ${result.skippedAtRedeem.length} candidate(s) did not land (${result.skippedAtRedeem.map((x) => x.reason).join("; ")})`);
                 }
@@ -355,21 +224,12 @@ export function createRuleConsentLane(stores, opts) {
             }
         },
         async listRules(bucket) {
-            // `list()` 已经把墓碑折算掉(`applyTombstones`)⇒ 这里拿到的就是**活着**的规则,治理面看到的
-            // 与引擎放行时看到的是同一份。空桶 = 空表 + rev 0,不是错误(「这个人没有规则」是合法状态)。
             const stored = await storeForBucket(stores.provider, bucket).list();
             const rows = stored.rules.map((r) => ({ rule: r.rule, scope: serializeRuleScope(r.scope), tool: r.tool, match: r.match, command: r.command, adds: r.adds }));
             rows.sort((a, b) => (a.scope < b.scope ? -1 : a.scope > b.scope ? 1 : a.rule < b.rule ? -1 : a.rule > b.rule ? 1 : 0));
             return { rows, rev: stored.rev };
         },
         async removeRule(input) {
-            // 🔴 一行也不自己写:OCC 重试、墓碑铸造、`stillLive` 的读回全在 core 那条原语里,而它的语义
-            // (add-wins、observed-remove、失败必须由读回确认「什么都没写」)是 core 的单一属主。
-            // 桶引用**原样**递下去(裸串走 core 的 principal 简写臂,结构形走 owner 臂)——我方不在这里
-            // 归一成 owner 对象:core 5.24.0 的 `removePersistedRule` 自己就做那次归一(`typeof === "string"`),
-            // 多归一一次等于把上游的简写语义抄一份到下游,抄件会漂。local-owner 而 provider 无 `forLocalOwner`
-            // 的那支也归 core:它回的是 `failed` + 报文含 `forLocalOwner`(C13 判据),比抛错更适合这条
-            // 三态返回的口。
             return await removePersistedRule({ rule: input.rule, scope: input.scope, principal: input.principal, provider: stores.provider });
         },
     };