@sema-agent/server 7.43.0 → 7.44.0

package/dist/plugins/permission-rule-store-sql.js

@@ -1,74 +1,7 @@
-/**
- * #154 车二 —— **持久化权限规则店的 SQL 双方言实装**(core 5.18.0 design/179 + 5.22.0 design/182)。
- *
- * 三张表,三个不同的问题:
- *  · `permission_rule`          —— 一只**桶**(owner)的整份规则状态 + 同步游标面(actor/counter/rev/
- *                                  observed_vector),OCC 靠 `rev` 列。
- *  · `permission_rule_approval` —— core `RuleApprovalRecordStore` 的 SQL 形(durable 审批记录,CAS on rev)。
- *  · `permission_rule_ticket`   —— **server 自铸**的 CC 导入票(principal 绑定 + TTL + 一次性原子消费 +
- *                                  载荷绑定)。core 的 `RuleTicket` 没有这四样中的任何一样(亲读
- *                                  `mintRuleTicket` = `rt.<index>.<recordId>`,零 TTL、零签名、零消费位),
- *                                  所以它们是 **server 附加的信任边界**,自建格。
- *
- * ─────────────────────────────────────────────────────────────────────────────────────────────────
- * 🔴 为什么 `permission_rule` 是**一桶一行**而不是「一规则一行」
- * ─────────────────────────────────────────────────────────────────────────────────────────────────
- * 这个店的**每一个**操作都是全量的:`list()` 读整份、`readRaw()` 读整份、`apply(delta,{expectedRev})`
- * 是**整份状态的一次 OCC 写**(core 明写「Partial landing 在写层不可拼写:要么整个 join 落地、要么一点
- * 都不落」)。core 自己对同族问题的裁定逐字在 `RuleSyncFrontier` 的 JSDoc 里:「persist this as a JSON
- * blob column —— the vector is read and written whole, never queried per-actor; **a row-per-actor table
- * would invite partial updates the semantics cannot express**」。规则集与它是同一种量:CRDT 的收敛性
- * 建立在「整份状态的 join」上,把它拆成行会让「半个 join 落地」在 SQL 层**变得可表达**——而那正是语义
- * 禁止的形。一桶一行还带来一条真收益:OCC 写退化成**单条** `UPDATE … WHERE owner_key=? AND rev=?`,
- * 天然原子,不需要事务、不需要 `FOR UPDATE`、不进本仓在案的悲观锁死锁族。
- *
- * ─────────────────────────────────────────────────────────────────────────────────────────────────
- * 🔴 写面 = **core 的本尊**(A-033.2 / #256 销账,交接件③已兑现)
- * ─────────────────────────────────────────────────────────────────────────────────────────────────
- * 本文件曾整段登记一个上游契约缺口:core 的写面(`PERMISSION_RULE_WRITER` 常量、`PermissionRuleWriter`/
- * `WritablePermissionRuleStore`/`RuleWriteDelta`/`RawRuleSyncState` 类型、`foldDelta`/`writerOf`/
- * `assertRedemptionNotQuarantined`/`assertDeleteDeltaCarriesNoAdd` 函数)当时**不在包的公开导出面上**,
- * 于是本文件按结构满足它:属性名用字面常量、类型在下方一份份**本地镜像**(`RuleWriteDeltaMirror` 等),
- * 并把「求 core 导出写面」列为交接件③。
- *
- * core 2026-08-10 裁定**导出后端契约**(d.ts 原话:「Exported as part of the BACKEND CONTRACT … so an
- * out-of-repo store implementation hangs the same face the file backend does, instead of mirroring the
- * types」),5.33.0 起全部根导出 ⇒ 镜像与手写孪生一并摘除,本文件直接消费 core 的类型与三个共享判据。
- * 这不是洁癖:`foldDelta` 的 d.ts 自陈「Pure — the backends share it so the file and in-memory forms
- * cannot drift in what a delta MEANS」,而本 backend 此前**没有共享它**——一份 delta 在 file 后端与
- * SQL 后端上「意味着什么」可以各自漂,漂的落点是放行面。换装同时把两条判据换成 core 的严格版:
- *   · `assertDeleteDeltaCarriesNoAdd`:core 查 **6 个** add-only 键(add/redemption/rule/command/match/tool)
- *     并要求 `removedDots` 是**非空数组**;本地孪生只查过一个 `rules` 键(那还是 sync-join 的字段名,
- *     打偏了)且对空 `removedDots` 放行 —— 一条删不掉任何 add 的墓碑会让本该已删的规则继续放行。
- *   · `assertRedemptionNotQuarantined`:语义等价(同 dot 即拒),换本尊后报文也与 file 后端一致。
- *
- * 仍然**不实现**的只剩 `sync-join` 那一臂:它的落地管线(`applySyncJoin`)至今是 core 私有的一整条
- * 流水线,复制它才是真的会漂;本 backend 对该 delta **响亮拒绝**(fail-closed,不是静默 no-op),
- * 同步客户端本仓尚未接线,所以这条臂今天零调用点。
- *
- * ─────────────────────────────────────────────────────────────────────────────────────────────────
- * 边界纪律:列回读一律 zod `safeParse`(宪法 [2704] 禁裸 as-cast)。JSON 列是驱动交回的 `unknown`,
- * 一条形状漂了的历史行若被 as-cast 成 `PersistedAllowRule[]`,会带着 `undefined` 字段一路走进
- * `findAdmittingRule` —— 那是**放行面**上的静默垃圾,比读不出来坏得多。读不出来 ⇒ **throw**
- * (core 明令:「a backend that fails to read must not silently report an empty set … it throws」)。
- */
 import { createHash, randomBytes } from "node:crypto";
 import { z } from "zod";
 import { applyTombstones, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, foldDelta, parseAllowRuleText, screenRuleSyncState, PERMISSION_RULE_WRITER, RULE_SYNC_DROP_CODES, } from "@sema-agent/core";
 import { dialectProtocolJsonEncoder } from "./sql-driver.js";
-// ─────────────────────────────────────────────────────────────────────────────────────────────────
-// 写面(core 的后端契约,2026-08-10 裁定导出;本仓 A-033.2 已摘除全部本地镜像)
-// ─────────────────────────────────────────────────────────────────────────────────────────────────
-/**
- * 一只店的写面,或 `undefined`(该 backend 从引擎侧看是只读的)。
- *
- * 与 core 的 `writerOf` 的**唯一**区别是判据更严:core 只看 `apply`/`nextDot` 两个方法在不在(它服务的是
- * 引擎自己的兑付腿),本函数还要求 `readRaw` —— 本仓的消费点(测试/取证)读的是**完整**写面,少一个方法
- * 就该当场判 `undefined`,而不是在调用 `readRaw()` 时炸一个 `not a function`。
- *
- * 结构检查而不是断言:没有这个函数,每个调用点都会各写一次 `as unknown as {…}`,那既是三处宽松断言,
- * 也是三份会各自漂的形状假设。
- */
 export function writerOfSqlRuleStore(store) {
     const w = Reflect.get(store, PERMISSION_RULE_WRITER);
     if (w === null || typeof w !== "object")
@@ -80,18 +13,10 @@ export function writerOfSqlRuleStore(store) {
         return undefined;
     return { nextDot: nextDot, apply: apply, readRaw: readRaw };
 }
-// ─────────────────────────────────────────────────────────────────────────────────────────────────
-// 列回读的边界 schema(宪法 [2704]:边界必 schema,禁裸 as-cast)
-// ─────────────────────────────────────────────────────────────────────────────────────────────────
 const RuleScopeSchema = z.union([
     z.object({ kind: z.literal("global") }).strict(),
-    // root 非空:一条 `{kind:"project", root:""}` 的规则在 `pathWithinRoot` 下会**覆盖每一个 cwd**
-    // (空前缀包含一切)—— 那是把一条项目内规则悄悄升成全局规则(codex round1 [high] 二)。
     z.object({ kind: z.literal("project"), root: z.string().min(1) }).strict(),
 ]);
-/** dot 的两位都是**身份**:actor 非空串,counter 是安全范围内的非负整数。
- *  (codex 交叉复审 round1 [high] 二:裸 `z.number()` 放行 `NaN` / `1e308` / 小数 —— 一个 `NaN` counter
- *  会让 dot 身份比较恒不相等,tombstone 从此删不掉它对应的 add。) */
 const RuleDotSchema = z.object({ actor: z.string().min(1), counter: z.number().int().nonnegative().safe() }).strict();
 const RuleAddSchema = z
     .object({ dot: RuleDotSchema, origin: z.enum(["user", "imported-cc", "starter"]), createdAt: z.string() })
@@ -106,20 +31,12 @@ const PersistedAllowRuleSchema = z
     adds: z.array(RuleAddSchema),
 })
     .strict();
-/** 🔴 `removedDots` **非空**(codex 交叉复审 round2 [high],验真后修):core 的落地管线对空 removedDots
- *  的 tombstone 是**抛错**(「a protocol violation」),而它落到读面上的后果更隐蔽 —— 一条删不掉任何
- *  add 的墓碑会让一条**本该已删**的规则继续放行。`removePersistedRule` 在没有可删对象时压根不铸墓碑,
- *  所以健康数据恒满足这一条;不满足的只可能是版本回退/还原/另一个写者。 */
 const RuleTombstoneSchema = z
     .object({ rule: z.string(), scope: RuleScopeSchema, removedDots: z.array(RuleDotSchema).min(1), deletedBy: RuleDotSchema })
     .strict();
-/** 隔离原因是 core 的**闭集**(`RULE_SYNC_DROP_CODES`)——词表从 core 派生,core 加员时本 schema 自动跟,
- *  绝不手抄一份(手抄的那份会在 core 加员的那天静默拒收一整类合法行)。 */
 const QUARANTINE_REASONS = new Set(Object.entries(RULE_SYNC_DROP_CODES)
     .filter(([, side]) => side.includes("local-quarantined"))
     .map(([code]) => code));
-/** 🔴 词表从 core 的表**派生**(而不是抄一份字面量):`RuleQuarantineReason` 是 `RULE_SYNC_DROP_CODES`
- *  中「会把 LOCAL 行搬进隔离区」的那一侧。抄一份的那天 core 加员,本 schema 会静默拒收一整类合法行。 */
 const isQuarantineReason = (v) => typeof v === "string" && QUARANTINE_REASONS.has(v);
 const QuarantinedRuleAddSchema = z
     .object({
@@ -133,26 +50,10 @@ const QuarantinedRuleAddSchema = z
 const FrontierSchema = z.record(z.string(), z.number().int().nonnegative().safe());
 const RuleCandidateSchema = z.object({ rule: z.string(), scope: RuleScopeSchema }).strict();
 const RedeemedDotsSchema = z.record(z.string(), RuleDotSchema);
-// ─────────────────────────────────────────────────────────────────────────────────────────────────
-// DDL
-// ─────────────────────────────────────────────────────────────────────────────────────────────────
+const RuleEditedSchema = z.object({ index: z.number().int().nonnegative().safe(), text: z.string(), at: z.string() }).strict();
 export const PERMISSION_RULE_TABLE = "permission_rule";
 export const PERMISSION_RULE_APPROVAL_TABLE = "permission_rule_approval";
 export const PERMISSION_RULE_TICKET_TABLE = "permission_rule_ticket";
-/**
- * MySQL-protocol(TiDB)侧的三条建表语句。真源在本文件(与 PG twin 并排,方言差异一眼可对);
- * `tidb-pool.ts` 的 `SCHEMA_STATEMENTS` 用 `...TIDB_PERMISSION_RULE_STATEMENTS` 展开,于是三张表跟着
- * 中央 `ensureSchema` 在 **named-lock 的那条 conn** 上建(同 `TIDB_APPROVAL_ASK_STATEMENTS` 先例)。
- *
- * 列宽依据(#192 A10 的「每列的值由谁铸、有没有入口上限」口径):
- *  · `owner_key` / `record_id` / `ticket_id` / `approval_id` / `payload_hash` / `checksum` → 190:
- *    全是本仓自铸的键类值(sha256 hex 64 / uuid 36 / `sha256:` 前缀 71),190 是全仓键轴的统一宽度。
- *  · `principal` → 512:principal 入口上限是 `PRINCIPAL_MAX_LENGTH = 190`(`security.ts`),这里给
- *    名类宽度 512 是**上界宽于入口**的方向(绝不制造静默截断面)。
- *  · `actor` → 190:本 backend 自铸的副本身份(`sql-<12 hex>`),按构造 ≤ 20 字符。
- *  · 内容列一律 LONGTEXT / TEXT:一只桶的规则集没有硬上限(导入一份大 settings 就能过 64K TEXT 墙)。
- *  · 毫秒列一律 `_ms` 后缀;OCC 列一律叫 `rev`(`version` 是形/schema 版本的保留词)。
- */
 export const TIDB_PERMISSION_RULE_STATEMENTS = [
     `CREATE TABLE IF NOT EXISTS ${PERMISSION_RULE_TABLE} (
     owner_key VARCHAR(190) NOT NULL,
@@ -190,6 +91,13 @@ export const TIDB_PERMISSION_RULE_STATEMENTS = [
     redeemed_dots_json LONGTEXT NULL,
     tool_call_id VARCHAR(255) NULL,
     bound_input_hash VARCHAR(255) NULL,
+    -- #340:卡记录上**被裁决命令的原字节**(core 卡编辑面覆盖门的输入:「编辑后的规则必须仍然容纳
+    -- 这条命令」)。LONGTEXT:命令行没有入口上限,VARCHAR 会造一个静默截断面,而截断过的命令与原命令
+    -- 是两条不同的命令 —— 覆盖门会据一条**我们自己改过**的命令做判断。batch 记录上恒 NULL。
+    command LONGTEXT NULL,
+    -- #340:那条人手改的候选的出身(\`{index,text,at}\` 整读整写)。两个臂(decision-edited /
+    -- offered-redeemed)在审计面的**唯一**判别位;core 也据它做同一份编辑的幂等重放。
+    edited_json LONGTEXT NULL,
     -- created_at_iso:core 的 \`RuleApprovalRecord.createdAt\` 是 ISO **字符串**,逐字回放(不是毫秒列,
     -- 故不带 _ms 后缀);排序/清扫另用 created_at_ms。
     created_at_iso VARCHAR(64) NOT NULL,
@@ -225,12 +133,36 @@ export const TIDB_PERMISSION_RULE_STATEMENTS = [
     KEY idx_permission_rule_ticket_expires (expires_at_ms)
   ) COLLATE utf8mb4_bin`,
 ];
-/** {@link TIDB_PERMISSION_RULE_STATEMENTS} 的遍历壳(生产路径走 `tidb-pool.ts` 中央 `ensureSchema`;
- *  本函数留给只需要这三张表的集成测试)。 */
 export async function ensureTiDBPermissionRuleSchema(pool) {
     for (const stmt of TIDB_PERMISSION_RULE_STATEMENTS)
         await pool.query(stmt);
 }
+function isMissingColumnError(err, dialect) {
+    if (err === null || typeof err !== "object")
+        return false;
+    const code = Reflect.get(err, "code");
+    if (dialect === "pg")
+        return code === "42703";
+    return Reflect.get(err, "errno") === 1054 || code === "ER_BAD_FIELD_ERROR";
+}
+export async function assertPermissionRuleApprovalSchema(query, dialect) {
+    try {
+        await query(`SELECT command, edited_json FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE 1=0`);
+    }
+    catch (err) {
+        if (!isMissingColumnError(err, dialect))
+            throw err;
+        throw new Error(`${PERMISSION_RULE_APPROVAL_TABLE} is missing the #340 card-edit columns (command / edited_json) — refusing to start. ` +
+            `The approval card now accepts a person-EDITED rule text, and the engine's coverage gate reads the adjudicated ` +
+            `command back off this record; the record also carries which candidate was edited. This repository ships no ` +
+            `ALTER TABLE migrations, so the table must be recreated: run \`DROP TABLE ${PERMISSION_RULE_APPROVAL_TABLE};\` on the ` +
+            `${dialect === "pg" ? "PostgreSQL" : "MySQL-protocol"} backend and restart — the schema is recreated at boot. ` +
+            `The cost is bounded: this table holds pending/settled approval RECORDS (the audit trail of who said yes to which ` +
+            `rule), not the rules themselves — persisted rules live in ${PERMISSION_RULE_TABLE} and are untouched. Dropping it ` +
+            `loses in-flight CC-import previews (re-runnable) and the historical record trail. ` +
+            `Underlying probe error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
 export async function ensurePgPermissionRuleSchema(q) {
     await q(`CREATE TABLE IF NOT EXISTS ${PERMISSION_RULE_TABLE} (
     owner_key VARCHAR(190) COLLATE "C" NOT NULL,
@@ -262,15 +194,15 @@ export async function ensurePgPermissionRuleSchema(q) {
     redeemed_dots_json TEXT COLLATE "C",
     tool_call_id VARCHAR(255) COLLATE "C",
     bound_input_hash VARCHAR(255) COLLATE "C",
+    -- #340 两格(MySQL 孪生的行内注写了理由:命令原字节是覆盖门的输入、edited 是两臂的判别位)。
+    command TEXT COLLATE "C",
+    edited_json TEXT COLLATE "C",
     created_at_iso VARCHAR(64) COLLATE "C" NOT NULL,
     created_at_ms BIGINT NOT NULL,
     updated_at_ms BIGINT NOT NULL,
     PRIMARY KEY (record_id)
   )`);
     await q(`CREATE INDEX IF NOT EXISTS idx_permission_rule_approval_owner ON ${PERMISSION_RULE_APPROVAL_TABLE} (owner_key)`);
-    // 保留期腿的支撑索引(MySQL 孪生的行内注写了理由:这张表按设计永久留审计事实,无索引的清扫谓词
-    // 是一次随史增长的全表扫)。PG 侧是独立 CREATE INDEX —— 存量库上 `IF NOT EXISTS` 会**真的补建**,
-    // 与 MySQL 侧「索引写在 CREATE TABLE 里、存量表拿不到」的不对称如实登记在 reapExpired 的注里。
     await q(`CREATE INDEX IF NOT EXISTS idx_permission_rule_approval_sweep ON ${PERMISSION_RULE_APPROVAL_TABLE} (state, created_at_ms)`);
     await q(`CREATE TABLE IF NOT EXISTS ${PERMISSION_RULE_TICKET_TABLE} (
     ticket_id VARCHAR(190) COLLATE "C" NOT NULL,
@@ -287,30 +219,13 @@ export async function ensurePgPermissionRuleSchema(q) {
     await q(`CREATE INDEX IF NOT EXISTS idx_permission_rule_ticket_owner ON ${PERMISSION_RULE_TICKET_TABLE} (owner_key)`);
     await q(`CREATE INDEX IF NOT EXISTS idx_permission_rule_ticket_expires ON ${PERMISSION_RULE_TICKET_TABLE} (expires_at_ms)`);
 }
-// ─────────────────────────────────────────────────────────────────────────────────────────────────
-// 纯函数(桶键 / 摘要 / delta 折叠)
-// ─────────────────────────────────────────────────────────────────────────────────────────────────
-/**
- * 一只桶的**存储键**(纯数据 ⇒ `build*`)。
- *
- * 🔴 为什么 hash 而不是把 principal 直接当主键:①principal 是自由文本身份串,做主键会让**长度**与
- * **排序规则**变成安全面(一个 191 字符的 principal 在 190 宽的列上被静默截断 ⇒ 两个身份共用一只桶,
- * 那是一次跨租户放行);②`local-owner` 那一员**没有** principal,需要一个同域的定长表示。
- * 种别前缀让两族键不可能相撞(`principal:` vs `local-owner`)。
- */
 export function buildRuleOwnerKey(owner) {
     const material = owner.kind === "principal" ? `principal:${owner.principal}` : "local-owner";
     return createHash("sha256").update(material, "utf8").digest("hex");
 }
-/** 内容三列 + 观测向量的完整性指纹(core `ruleStoreChecksum` 同精神;**不含** rev/counter —— 那两样
- *  是元数据轴,`nextDot` 只动 counter 就不该迫使重算内容指纹)。
- *
- *  导出(纯数据 ⇒ `build*`)是为了让**取证测试**能造一条「指纹自洽但语义矛盾」的行 —— 那正是
- *  codex round1 [high] 二的形:一条只靠指纹是拦不住的坏行,必须由语义筛拦。 */
 export function buildRuleBucketChecksum(body) {
     return `sha256:${createHash("sha256").update(canonicalJson(body), "utf8").digest("hex")}`;
 }
-/** 稳定序 JSON(键排序递归)——摘要必须与键序无关,否则同一份内容会算出两个指纹。 */
 function canonicalJson(v) {
     if (v === null || typeof v !== "object")
         return JSON.stringify(v) ?? "null";
@@ -321,10 +236,7 @@ function canonicalJson(v) {
         .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
     return `{${entries.map(([k, val]) => `${JSON.stringify(k)}:${canonicalJson(val)}`).join(",")}}`;
 }
-/** {@link SqlPermissionRuleStore} 的 dot 铸造 CAS 重试上限。有界:一个无界循环只会把「争不过」变成
- *  挂死;用尽 ⇒ 响亮抛错,由 core 的兑付腿(它自己也有有界重试)如实回 refused。 */
 const NEXT_DOT_MAX_ATTEMPTS = 8;
-/** 空桶的读出形(core `EMPTY_READ` 同值:桶不存在 = 零规则,不是错误)。 */
 const EMPTY_BUCKET = { actor: "", counter: 0, rev: 0, rules: [], tombstones: [], quarantined: [] };
 function parseColumn(schema, raw, column, ownerKey) {
     const text = typeof raw === "string" ? raw : raw === null || raw === undefined ? undefined : String(raw);
@@ -342,9 +254,6 @@ function parseColumn(schema, raw, column, ownerKey) {
         throw new Error(`permission_rule.${column} for bucket ${ownerKey} does not carry a readable shape: ${parsed.error.message}`);
     return parsed.data;
 }
-// ─────────────────────────────────────────────────────────────────────────────────────────────────
-// 店本体
-// ─────────────────────────────────────────────────────────────────────────────────────────────────
 class SqlPermissionRuleStore {
     db;
     owner;
@@ -364,7 +273,6 @@ class SqlPermissionRuleStore {
     q(tidbSql, pgSql) {
         return this.db.dialect === "tidb" ? tidbSql : pgSql;
     }
-    /** 桶行的读出。不存在 ⇒ {@link EMPTY_BUCKET}(零规则,不是错误);存在但形不合/指纹不符 ⇒ **throw**。 */
     async read() {
         const { rows } = await this.db.query(this.q(`SELECT actor, counter, rev, rules_json, tombstones_json, quarantined_json, observed_vector_json, checksum FROM ${PERMISSION_RULE_TABLE} WHERE owner_key = ?`, `SELECT actor, counter, rev, rules_json, tombstones_json, quarantined_json, observed_vector_json, checksum FROM ${PERMISSION_RULE_TABLE} WHERE owner_key = $1`), [this.ownerKey]);
         const row = rows[0];
@@ -388,20 +296,6 @@ class SqlPermissionRuleStore {
             throw new Error(`permission_rule bucket ${this.ownerKey} failed its integrity check (stored ${String(row.checksum)}, computed ${expected}) — ` +
                 `refusing the whole bucket rather than reporting a partial rule set`);
         }
-        // 🔴 codex 交叉复审 round1 [high] 二(验真后修):**形对 ≠ 语义安全**。
-        // 上面的 zod 只保证「这是一条 PersistedAllowRule 的形状」,指纹只保证「这些字节没被改过」——
-        // 两者都拦不住一条**自洽但语义矛盾**的行:`rule: "Bash(ls)"` 配 `match:"prefix", command:"rm"`。
-        // 而 core 的匹配器(`ruleAdmitsCommand`/`findAdmittingRule`)信的是 `match`/`command` 两个**去规范化**
-        // 字段,不重新解析 `rule` ⇒ 这样一行会放行一条它显示的规则根本没描述的命令。成因不必是攻击:
-        // 版本回退、备份还原、另一个写者,都会造出它。
-        // 判据用 core **导出的** `screenRuleSyncState`(它内部就是 design/182 §3.1 的 `normalizePersistedRule`:
-        // 从 `rule` 文本经**同一个**验证器重投影,与存的字段逐字比对)—— 不是我方另写一份等式(那必然会漂)。
-        // 处置 = **整桶拒绝**(throw),与上面的指纹臂同姿势:core 明令「refused (fail-closed), never repaired
-        // toward either side」,而修一半、留一半会让「这只桶到底有哪些规则」变成两个答案。
-        // 🔴 codex round2 [high](验真后修):`screenRuleSyncState` 只筛 **allow 行**,不看墓碑 ——
-        // 而墓碑的 `rule` 文本正是它与被删行的**唯一**配对键(`applyTombstones` 按 (rule, scope) 归组)。
-        // 一条文本非规范/验证器拒收的墓碑配不上任何一行 ⇒ 它删不掉任何东西,而调用方以为删掉了:
-        // 一条**本该已删**的规则继续放行。判据同样用 core 导出的**那一个**验证器(不是另写一份等式)。
         const badTombstone = tombstones.find((t) => {
             const parsed = parseAllowRuleText(t.rule);
             return "reject" in parsed || parsed.rule.rule !== t.rule;
@@ -418,8 +312,6 @@ class SqlPermissionRuleStore {
         }
         return state;
     }
-    /** 桶行的**创建**(幂等)。actor 是本 backend 自铸的**副本身份**(design/182:replica identity,
-     *  NEVER a person identity)——一只桶一个,首次落行时定,之后永不变。 */
     async ensureBucket() {
         const nowMs = this.now();
         const empty = { rules: [], tombstones: [], quarantined: [] };
@@ -449,21 +341,6 @@ class SqlPermissionRuleStore {
         return this.writer;
     }
     writer = {
-        /**
-         * 铸下一个 dot。**方言同形的有界 CAS 循环**:读到 `counter=c` ⇒ 打
-         * `UPDATE … SET counter = c+1 WHERE owner_key = ? AND counter = c`,`affected === 1` 才认领 `c+1`。
-         *
-         * 🔴 为什么不是「事务 + `SELECT … FOR UPDATE`」(第一版就是那样,真双库当场红):
-         *  · `BEGIN PESSIMISTIC` 是 **TiDB 方言**,真 MySQL 上是语法错误(本机 MySQL 9.x 直接拒);
-         *  · 换成裸 `BEGIN` 也只是换一种锁形,却把一条**悲观锁腿**引进本仓在案的死锁族(MySQL vs TiDB
-         *    的锁语义分歧),而这一格根本不需要锁:分配一个单调计数器正是 CAS 的教科书形。
-         * 🔴 也不是 `SET counter = counter + 1` 那条「原子自增」:它在引擎里确实原子,但 mysql2 **没有**
-         * `RETURNING`,自增之后要另起一次 SELECT 才知道自己拿到了几 —— 那一跳之间又是一次竞态。
-         * CAS 把「加一」与「知道加到了几」变成同一件事,两个方言逐字同形。
-         *
-         * 一次 read-then-write(读 counter、加一、无条件写)会在两个并发兑付上发出**同一个 dot** ——
-         * 那等于把两次人的同意折成一次 add,是这段代码存在的全部理由。
-         */
         nextDot: async () => {
             await this.ensureBucket();
             for (let attempt = 0; attempt < NEXT_DOT_MAX_ATTEMPTS; attempt++) {
@@ -493,8 +370,6 @@ class SqlPermissionRuleStore {
             };
         },
         apply: async (delta, opts) => {
-            // 🔴 fail-closed(顶注 ②):同步落地管线是 core 私有的一整条流水线,复制它才是真的会漂。
-            // 响亮拒绝而不是静默 no-op —— 静默 no-op 会让一个「join 已落地」的调用方带着错误的信念继续。
             if (delta.kind === "sync-join") {
                 throw new Error("the SQL permission-rule backend does not implement the sync-join landing pipeline (core's applySyncJoin is not on the package's public export face); " +
                     "no sync client is wired in this deployment, so this arm has no caller — see permission-rule-store-sql.ts header");
@@ -505,8 +380,6 @@ class SqlPermissionRuleStore {
                 return { conflict: true, rev: cur.rev };
             let nextRules = cur.rules;
             let nextTombstones = cur.tombstones;
-            // A-033.2(#256):两条判据 + 折叠本体全部走 core 的共享件(`foldDelta` 的 d.ts:「the backends share
-            // it so the file and in-memory forms cannot drift in what a delta MEANS」)。此前这三处是本地孪生。
             if (delta.kind === "redemption-add") {
                 assertRedemptionNotQuarantined(cur.quarantined, delta);
                 nextRules = foldDelta(cur.rules, delta);
@@ -515,19 +388,12 @@ class SqlPermissionRuleStore {
                 assertDeleteDeltaCarriesNoAdd(delta);
                 nextTombstones = [...cur.tombstones, delta.tombstone];
             }
-            // 🔴 codex 交叉复审 round5 [high] 一(验真后修)——**只写读得回来的东西**。
-            // 读面比写面严(空 root 的 project scope、空 removedDots 的墓碑…都会让整桶拒),于是一个宽松的
-            // 上游入口可以写进一条**自己再也读不回来**的行:一次「成功」的导入把这位租户的桶永久毒死。
-            // 判据用的是**同一组** schema(不是另写一份等式),所以两面永不可能各自漂;违反 ⇒ 响亮拒绝,
-            // 绝不落盘(fail-closed:宁可这次写失败,也不留一条让整桶不可读的行)。
             const writable = z.object({ rules: z.array(PersistedAllowRuleSchema), tombstones: z.array(RuleTombstoneSchema) }).safeParse({ rules: nextRules, tombstones: nextTombstones });
             if (!writable.success) {
                 throw new Error(`refusing to write a permission_rule bucket this backend could not read back: ${writable.error.message}`);
             }
             const body = { rules: nextRules, tombstones: nextTombstones, quarantined: cur.quarantined, ...(cur.observedVector !== undefined ? { observedVector: cur.observedVector } : {}) };
             const nowMs = this.now();
-            // OCC = **单条条件 UPDATE**(`WHERE owner_key=? AND rev=?`)。affected===0 ⇒ 有人先落了,如实回
-            // conflict + 当前 rev(调用方重读重试;core 的 applyRedemption 自带有界重试循环)。
             const { affected } = await this.db.query(this.q(`UPDATE ${PERMISSION_RULE_TABLE} SET rules_json = ?, tombstones_json = ?, quarantined_json = ?, checksum = ?, rev = rev + 1, updated_at_ms = ? WHERE owner_key = ? AND rev = ?`, `UPDATE ${PERMISSION_RULE_TABLE} SET rules_json = $1, tombstones_json = $2, quarantined_json = $3, checksum = $4, rev = rev + 1, updated_at_ms = $5 WHERE owner_key = $6 AND rev = $7`), [
                 this.enc(nextRules, "permission_rule.rules_json"),
                 this.enc(nextTombstones, "permission_rule.tombstones_json"),
@@ -545,12 +411,6 @@ class SqlPermissionRuleStore {
         },
     };
 }
-/**
- * SQL 双方言的 {@link PermissionRuleStoreProvider}。
- *
- * `forPrincipal(undefined)` 恒解析成**零规则**店(core 硬条款:未鉴权任务解析到零规则而不是一只共享桶
- * —— 放宽面上的 fail-closed 是「更少的允许」,绝不是「一只共享的」)。
- */
 export class SqlPermissionRuleStoreProvider {
     db;
     now;
@@ -567,20 +427,10 @@ export class SqlPermissionRuleStoreProvider {
         return new SqlPermissionRuleStore(this.db, { kind: "local-owner" }, this.now);
     }
 }
-/** 未鉴权解析到的零规则店。**刻意不复用** core 的 `EMPTY_RULE_STORE`:那一份声明的 durability 是
- *  实现细节,而这一格的语义是「这条腿没有身份 ⇒ 没有规则」,自持一份让它不随上游默认值漂。 */
 const ZERO_RULE_STORE = {
     list: async () => ({ rules: [], tombstones: [], rev: 0 }),
     durability: "process-local",
 };
-// ─────────────────────────────────────────────────────────────────────────────────────────────────
-// 审批记录店(core `RuleApprovalRecordStore` 的 SQL 形)
-// ─────────────────────────────────────────────────────────────────────────────────────────────────
-/**
- * durable 审批记录。CAS **按 rev**,不按 state —— core 的原话:批记录的第二个候选会 redeemed→redeemed,
- * 只比 state 的两次并发重试会**都**认为自己看到了预期状态,各铸一个 dot、各写一次,后者静默覆盖前者的
- * `redeemedDots`。那正是「一次同意变成两个 add、一条删掉的规则复活」的机制。
- */
 export class SqlRuleApprovalRecordStore {
     db;
     now;
@@ -595,12 +445,13 @@ export class SqlRuleApprovalRecordStore {
         return dialectProtocolJsonEncoder(this.db.dialect)(v, label);
     }
     async get(id) {
-        const { rows } = await this.db.query(this.q(`SELECT record_id, owner_kind, principal, kind, state, rev, candidates_json, selected_candidate, redeemed_dots_json, tool_call_id, bound_input_hash, created_at_iso FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE record_id = ?`, `SELECT record_id, owner_kind, principal, kind, state, rev, candidates_json, selected_candidate, redeemed_dots_json, tool_call_id, bound_input_hash, created_at_iso FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE record_id = $1`), [id]);
+        const { rows } = await this.db.query(this.q(`SELECT record_id, owner_kind, principal, kind, state, rev, candidates_json, selected_candidate, redeemed_dots_json, tool_call_id, bound_input_hash, command, edited_json, created_at_iso FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE record_id = ?`, `SELECT record_id, owner_kind, principal, kind, state, rev, candidates_json, selected_candidate, redeemed_dots_json, tool_call_id, bound_input_hash, command, edited_json, created_at_iso FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE record_id = $1`), [id]);
         const row = rows[0];
         if (row === undefined)
             return undefined;
         const candidates = parseColumn(z.array(RuleCandidateSchema), row.candidates_json, "candidates_json", id);
         const dotsRaw = row.redeemed_dots_json === null || row.redeemed_dots_json === undefined ? undefined : parseColumn(RedeemedDotsSchema, row.redeemed_dots_json, "redeemed_dots_json", id);
+        const edited = row.edited_json === null || row.edited_json === undefined ? undefined : parseColumn(RuleEditedSchema, row.edited_json, "edited_json", id);
         const kind = z.enum(["card", "import", "starter"]).safeParse(row.kind);
         const state = z.enum(["pending", "approved", "redeemed"]).safeParse(row.state);
         if (!kind.success || !state.success) {
@@ -608,8 +459,6 @@ export class SqlRuleApprovalRecordStore {
         }
         const ownerKind = String(row.owner_kind);
         const principal = row.principal === null || row.principal === undefined ? undefined : String(row.principal);
-        // 身份两族(design/182 §4.5):v1 记录只带 principal;local-owner 记录只带 owner。**绝不同时带两个**
-        // (core:两者不一致的记录是矛盾的、不可兑付的)。
         const redeemedDots = dotsRaw === undefined ? undefined : Object.fromEntries(Object.entries(dotsRaw).map(([k, v]) => [Number(k), v]));
         return {
             id: String(row.record_id),
@@ -621,6 +470,8 @@ export class SqlRuleApprovalRecordStore {
             rev: Number(row.rev ?? 0),
             ...(row.tool_call_id !== null && row.tool_call_id !== undefined ? { toolCallId: String(row.tool_call_id) } : {}),
             ...(row.bound_input_hash !== null && row.bound_input_hash !== undefined ? { boundInputHash: String(row.bound_input_hash) } : {}),
+            ...(row.command !== null && row.command !== undefined ? { command: String(row.command) } : {}),
+            ...(edited !== undefined ? { edited } : {}),
             ...(row.selected_candidate !== null && row.selected_candidate !== undefined ? { selectedCandidate: Number(row.selected_candidate) } : {}),
             ...(redeemedDots !== undefined ? { redeemedDots } : {}),
         };
@@ -628,9 +479,9 @@ export class SqlRuleApprovalRecordStore {
     async create(record) {
         const nowMs = this.now();
         const owner = record.owner ?? { kind: "principal", principal: record.principal ?? "" };
-        await this.db.query(this.q(`INSERT INTO ${PERMISSION_RULE_APPROVAL_TABLE} (record_id, owner_key, owner_kind, principal, kind, state, rev, candidates_json, selected_candidate, redeemed_dots_json, tool_call_id, bound_input_hash, created_at_iso, created_at_ms, updated_at_ms)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, `INSERT INTO ${PERMISSION_RULE_APPROVAL_TABLE} (record_id, owner_key, owner_kind, principal, kind, state, rev, candidates_json, selected_candidate, redeemed_dots_json, tool_call_id, bound_input_hash, created_at_iso, created_at_ms, updated_at_ms)
-         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15)`), [
+        await this.db.query(this.q(`INSERT INTO ${PERMISSION_RULE_APPROVAL_TABLE} (record_id, owner_key, owner_kind, principal, kind, state, rev, candidates_json, selected_candidate, redeemed_dots_json, tool_call_id, bound_input_hash, command, edited_json, created_at_iso, created_at_ms, updated_at_ms)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, `INSERT INTO ${PERMISSION_RULE_APPROVAL_TABLE} (record_id, owner_key, owner_kind, principal, kind, state, rev, candidates_json, selected_candidate, redeemed_dots_json, tool_call_id, bound_input_hash, command, edited_json, created_at_iso, created_at_ms, updated_at_ms)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17)`), [
             record.id,
             buildRuleOwnerKey(owner),
             owner.kind,
@@ -643,35 +494,28 @@ export class SqlRuleApprovalRecordStore {
             record.redeemedDots === undefined ? null : this.enc(record.redeemedDots, "permission_rule_approval.redeemed_dots_json"),
             record.toolCallId ?? null,
             record.boundInputHash ?? null,
+            record.command ?? null,
+            record.edited === undefined ? null : this.enc(record.edited, "permission_rule_approval.edited_json"),
             record.createdAt,
             nowMs,
             nowMs,
         ]);
     }
-    /**
-     * 丢弃一条**从未被确认**的记录(codex 交叉复审 round8 [medium],可控半场)。
-     *
-     * 用处只有一个:`prepareCcImport` 会在**返回预览之前**就把 pending 记录落盘,所以「预览超帽、这次导入
-     * 不做了」这条路会留下一条永远没人要的行。`WHERE state = 'pending'` 是硬的 —— 已确认/已兑付的记录是
-     * 一次真人同意的**审计事实**,任何路径都不许把它删掉(那条轴上的清理属于保留期策略,不是本方法)。
-     * 不是 core `RuleApprovalRecordStore` 的成员(那个接口只有 get/cas/create),故命名上与它区分。
-     */
     async discardPendingRecord(recordId) {
         const { affected } = await this.db.query(this.q(`DELETE FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE record_id = ? AND state = 'pending'`, `DELETE FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE record_id = $1 AND state = 'pending'`), [recordId]);
         return affected === 1;
     }
-    /** compare-and-set on `rev`(core 硬条款)。`next.rev` 必须是 `expectRev + 1`;不是 ⇒ 响亮拒绝
-     *  (一个不推进的 CAS 会让两次写互相覆盖而两边都以为自己赢了)。 */
     async cas(id, expectRev, next) {
         if (next.rev !== expectRev + 1) {
             throw new Error(`rule-approval CAS must advance rev by exactly one (expectRev=${expectRev}, next.rev=${next.rev})`);
         }
-        const { affected } = await this.db.query(this.q(`UPDATE ${PERMISSION_RULE_APPROVAL_TABLE} SET state = ?, rev = ?, candidates_json = ?, selected_candidate = ?, redeemed_dots_json = ?, updated_at_ms = ? WHERE record_id = ? AND rev = ?`, `UPDATE ${PERMISSION_RULE_APPROVAL_TABLE} SET state = $1, rev = $2, candidates_json = $3, selected_candidate = $4, redeemed_dots_json = $5, updated_at_ms = $6 WHERE record_id = $7 AND rev = $8`), [
+        const { affected } = await this.db.query(this.q(`UPDATE ${PERMISSION_RULE_APPROVAL_TABLE} SET state = ?, rev = ?, candidates_json = ?, selected_candidate = ?, redeemed_dots_json = ?, edited_json = ?, updated_at_ms = ? WHERE record_id = ? AND rev = ?`, `UPDATE ${PERMISSION_RULE_APPROVAL_TABLE} SET state = $1, rev = $2, candidates_json = $3, selected_candidate = $4, redeemed_dots_json = $5, edited_json = $6, updated_at_ms = $7 WHERE record_id = $8 AND rev = $9`), [
             next.state,
             next.rev,
             this.enc(next.candidates, "permission_rule_approval.candidates_json"),
             next.selectedCandidate ?? null,
             next.redeemedDots === undefined ? null : this.enc(next.redeemedDots, "permission_rule_approval.redeemed_dots_json"),
+            next.edited === undefined ? null : this.enc(next.edited, "permission_rule_approval.edited_json"),
             this.now(),
             id,
             expectRev,
@@ -679,19 +523,7 @@ export class SqlRuleApprovalRecordStore {
         return affected === 1;
     }
 }
-/**
- * [4232]③ 同族的 **GC 宽限**:`reapExpired` 只收「按墙钟至少已死一个完整 TTL」的票行。
- *
- * 为什么需要它:判定侧改单调锚之后,一张「按墙钟已过期、按单调钟还在窗内」的票是**可兑付**的;
- * 若 GC 仍按 `expires_at_ms <= now` 收行,判定修好了而行先没了 —— 用户拿到的从 `expired` 变成 `unknown`,
- * 缺陷只是换了个归因。宽限一个 TTL 覆盖住「铸票时钟慢了不到一个 TTL」这一族(含 [4232]③ 的真实构造)。
- *
- * 残余(如实登记,不假称已解):墙钟被拨慢**超过**一个 TTL 时,行仍可能在单调窗内被收。彻底解需要行上
- * 存单调基准,而单调基准跨进程无意义(core [4235] 的判词)。补偿是现成的:prepare 廉价,重铸一张即可
- * ——这正是 core 建议的姿态(「接受 + 票廉价重铸」)。
- */
 export const RULE_IMPORT_TICKET_GC_GRACE_MS = 10 * 60_000;
-/** prepare 时刻候选集的规范摘要(载荷绑定 F1 ④ 的判据)。纯数据 ⇒ `build*`。 */
 export function buildRulePayloadHash(candidates) {
     return createHash("sha256").update(canonicalJson(candidates), "utf8").digest("hex");
 }
@@ -723,31 +555,10 @@ export class SqlRuleImportTicketStore {
         ]);
         return { ticketId: input.ticketId, approvalId: input.approvalId, payloadHash, expiresAtMs };
     }
-    /**
-     * **一次性原子认领**(F1 ③)。四个条件全部写在 `WHERE` 里 —— ticket 身份、principal 绑定、未过期、
-     * 未认领 —— 于是并发双 redeem 由引擎的行锁裁决,恰一条 `affected === 1`。
-     *
-     * 🔴 **认领的 UPDATE 是这条方法的最后一次 I/O**(codex 交叉复审 round4 [high],验真后修)。
-     * 旧形是「先 UPDATE 认领、再 SELECT 取 approvalId/payloadHash」——那条 SELECT 失败时本方法**抛错**,
-     * 而调用方(`redeemImport`)此时还没进它的恢复 `try`,于是**没有任何人去放回认领**:票被永久烧掉,
-     * 重试收到不可重试的 404,人的确认凭空消失。改法不是加一层 catch,而是**把那次读挪到认领之前**:
-     * `approval_id` / `payload_hash` 自铸票起就是**不可变**列,先读与后读读到的是同一份字节。
-     *
-     * 🔴 **这仍然不是 read-then-write**(禁令的语义没有松动):**裁决**依旧只由那条条件 `UPDATE` 的
-     * `WHERE` 做出 —— 预读的三条否定项只用来**短路 + 归因**(把拒绝分成 unknown/wrong-principal/
-     * expired/consumed 四类给服务端日志;wire 面把四类折成同一个 404)。预读说「可以」而 UPDATE 命中零行,
-     * 只可能是我们在这两跳之间输给了一个并发认领者 —— 如实报 `consumed`,而不是把这次失败当成成功。
-     */
     async consume(ticketId, principal, opts) {
-        // 🔴 [4232]③/[4235]③ 两只钟分家(**判定** vs **记账**),缺一不可:
-        //  · `decisionNowMs` = 判定钟。缺席 ⇒ 墙钟(既有行为逐字不变);在场 ⇒ 调用方给的**单调锚投影**
-        //    (铸票时刻的墙钟 + 自铸票起单调钟走过的量)。它只进那条 `expires_at_ms > ?` 的 WHERE。
-        //  · `stampMs` = 记账钟,恒为真墙钟。写进 `consumed_at_ms` 的必须是「这件事在挂钟上什么时候发生」,
-        //    审计行不许被判定侧的投影污染(任务书自审第三镜:记账钟不动,只改判定钟)。
         const stampMs = this.now();
         const decisionNowMs = opts?.decisionNowMs ?? stampMs;
         const ownerKey = buildRuleOwnerKey({ kind: "principal", principal });
-        // 预读:①取不可变的 approvalId/payloadHash(于是认领之后零 I/O);②给四类拒绝一个准确归因。
         const row = await this.readRow(ticketId);
         if (row === undefined)
             return { ok: false, reason: "unknown" };
@@ -758,34 +569,11 @@ export class SqlRuleImportTicketStore {
         if (row.expiresAtMs <= decisionNowMs)
             return { ok: false, reason: "expired" };
         const { affected } = await this.db.query(this.q(`UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET consumed_at_ms = ? WHERE ticket_id = ? AND owner_key = ? AND consumed_at_ms IS NULL AND expires_at_ms > ?`, `UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET consumed_at_ms = $1 WHERE ticket_id = $2 AND owner_key = $3 AND consumed_at_ms IS NULL AND expires_at_ms > $4`), [stampMs, ticketId, ownerKey, decisionNowMs]);
-        // 认领成功 ⇒ 直接用预读那份不可变值返回,**不再发任何一条语句**(这正是本次修复的全部内容)。
         if (affected === 1)
             return { ok: true, approvalId: row.approvalId, payloadHash: row.payloadHash };
-        return { ok: false, reason: "consumed" }; // 预读三项刚刚都成立过 ⇒ 只可能是输给了并发认领者
+        return { ok: false, reason: "consumed" };
     }
-    /**
-     * **认领的释放**(codex 交叉复审 round1 [high] 一,验真后修)。
-     *
-     * `consume` 是一次**认领**(claim),不是「这件事已经做完了」。认领之后还有三步会失败:读记录、
-     * 载荷比对、confirm+批量兑付。旧形把认领当终局 ⇒ 一次数据库抖动就让票**永久**烧掉,而调用方拿到的
-     * 是与「票不存在」同形的 404:重试无门、最终状态对客户端不可判。
-     *
-     * ⇒ 认领之后**只有裁定性拒绝**才留着消费位(载荷被篡改、记录不存在 —— 重试不改判);**不确定/瞬时**
-     * 的失败(store 抛错、CAS 冲突)把认领**放回去**,让属主重试。放回去不会打开双兑付的门:同一时刻
-     * 只有一个持有者(认领本身仍是单条条件 UPDATE),而兑付腿(`redeemRuleBatch`)按 core 的设计是
-     * **幂等**的(记录里存着每个候选已铸的 dot,重放只会重放同一个 dot)。
-     *
-     * 残留(如实登记,不假称已解):认领与释放之间**硬崩**会把票留在已认领态 —— 它随 TTL 自然消失,
-     * 期间属主可以重新走 prepare 拿一张新票(导入是幂等的:同一条规则再兑付只是同一个 dot 的重放)。
-     * 要彻底消灭它需要一条带租约到期的认领状态机,属协议改动,列为后续件。
-     */
     async release(ticketId, principal, mustRemainValidMs = 0, opts) {
-        // 🔴 codex 交叉复审 round6 [medium](验真后修):`expires_at_ms` 也进 WHERE,而且比的是
-        // **now + 通告的重试窗**,不是 now。理由:调用方拿本方法的返回值去决定要不要对客户端说
-        // 「稍后拿同一张票重试」——若这张票在那几秒里就会过期,那句话是**必然兑现不了**的承诺
-        // (客户端等完 Retry-After 回来只会收到 404,而且这一轮的确认已经丢了)。撑不过窗 ⇒ 如实回 false,
-        // 调用方于是按不可重试报(四类同形 404),不给一条注定走死的路。
-        // `decisionNowMs`(判定钟)与 `consume` 同源同义 —— 本语句只有判定,没有记账列可写。
         const nowMs = opts?.decisionNowMs ?? this.now();
         const { affected } = await this.db.query(this.q(`UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET consumed_at_ms = NULL WHERE ticket_id = ? AND owner_key = ? AND consumed_at_ms IS NOT NULL AND expires_at_ms > ?`, `UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET consumed_at_ms = NULL WHERE ticket_id = $1 AND owner_key = $2 AND consumed_at_ms IS NOT NULL AND expires_at_ms > $3`), [ticketId, buildRuleOwnerKey({ kind: "principal", principal }), nowMs + mustRemainValidMs]);
         return affected === 1;
@@ -804,34 +592,7 @@ export class SqlRuleImportTicketStore {
         };
     }
 }
-/**
- * 孤儿 pending 审批记录的保留期(A-010.17)。
- *
- * 判据是「**可证已死**」,不是一个拍脑袋的时长:一条 pending 记录只能经 `redeemRuleTicket` 走活,
- * 而兑付要么发生在铸它的**那一次请求内**(`persistCardRule` 的 prepare→confirm→redeem 三步同请求),
- * 要么要拿一张导入票 —— 而票自铸起最多活 {@link RULE_IMPORT_TICKET_TTL_MS}(10 分钟,`consume` 的
- * `expires_at_ms > now` 是硬条件)。所以创建时刻早于「now − 票 TTL」的 pending 记录**再也不可能**
- * 被兑付。24 小时是在这条上界之上再压两个数量级的余量,留给运维「昨天那次导入怎么没成」的排查窗。
- *
- * 🔴 **只收 pending**。`approved` / `redeemed` 是一次真人同意的**审计事实**(与 `discardPendingRecord`
- * 的 `WHERE state = 'pending'` 同一条硬约束,也与收编把这张表判成 D2「史实不改写」同源)——
- * 保留期策略动不到它们,本腿一行都不碰。
- */
 export const RULE_PENDING_APPROVAL_RETENTION_MS = 24 * 60 * 60_000;
-/**
- * 保留期腿**每轮**最多删多少行(codex R2 [high])。
- *
- * 为什么必须有界:`permission_rule_approval` 按设计**永久**留 approved/redeemed 的审计事实(收编把它
- * 判成 D2「史实不改写」,`discardPendingRecord` 的 `WHERE state='pending'` 也是同一条硬约束)——
- * 也就是说这张表**只增不减**。一条无界 DELETE 在首次开清扫、或一次长期没跑的部署上,会在一个事务里
- * 处理整个积压。500 的取值:一轮的最坏工作量钉在「几百行删除」这个数量级,而常态每轮的真实行数是个位数
- * (一次 prepare 留一行);积压按轮渐进清空,每轮都是完整语义,绝不留半干净状态。
- *
- * ⚠️ 两方言的**索引到货方式不对称**,如实登记:PG 侧是独立的 `CREATE INDEX IF NOT EXISTS`,存量库
- * 下次 `ensureSchema` 就补建;MySQL 侧索引写在 `CREATE TABLE` 里,而本仓 schema 口径是「启动 DDL 是唯一
- * 真源、不发 ALTER」⇒ **存量表拿不到这两个索引**,要靠一次删库重建(与 7.8.0 / 7.10.0 两次 BREAKING 窗
- * 同口径)。在那之前,MySQL 存量库上这条腿仍是全表扫 —— 但每轮 500 行的上界让它的**单次**代价仍然有界。
- */
 export const RULE_REAP_BATCH = 500;
 export function createSqlPermissionRuleStores(db, now) {
     const q = (tidb, pg) => (db.dialect === "tidb" ? tidb : pg);
@@ -840,30 +601,12 @@ export function createSqlPermissionRuleStores(db, now) {
         approvals: new SqlRuleApprovalRecordStore(db, now),
         tickets: new SqlRuleImportTicketStore(db, now),
         reapExpired: async (nowMs) => {
-            // 两条 DELETE **不包事务**:它们互相独立、各自幂等,一条失败不该把另一条已删的行回滚回来
-            // (维护腿的既有姿势 —— 邻居 reaper 腿全是独立语句)。
-            //
-            // 🔴 **每 tick 有界**(codex 对抗复审 R2 [high],验真后修):第一版是两条**无界** DELETE。
-            // 首次开清扫(或一次长时间没跑的部署)会在**一个事务**里删掉整个积压 —— 一条能跑很久、锁很多行、
-            // 把 binlog/WAL 顶起来的语句;而调用点当时又没有重入守卫,一旦耗时越过 tick 间隔,下一轮就叠上来。
-            // 收成每轮 {@link RULE_REAP_BATCH} 行:积压按轮**渐进**清空(每轮都是完整语义,不留半干净状态),
-            // 单条语句的最坏时长与库大小脱钩。调用侧另配了 in-flight 守卫(`boot/reapers.ts`)。
-            const deadTickets = await db.query(q(`DELETE FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE expires_at_ms <= ? LIMIT ${RULE_REAP_BATCH}`, 
-            // PG 的 DELETE 没有 LIMIT ⇒ 用 ctid 子查询限行(PG 侧的标准写法;`ctid` 是物理行号,
-            // 子查询里带 LIMIT 才是被支持的那一形)。两方言的**语义**相同:本轮最多删这么多行。
-            `DELETE FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE ctid IN (SELECT ctid FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE expires_at_ms <= $1 LIMIT ${RULE_REAP_BATCH})`), 
-            // [4232]③:减去 {@link RULE_IMPORT_TICKET_GC_GRACE_MS} —— 判定侧走单调锚之后,
-            // 「按墙钟已过期、按单调钟还在窗内」的票是可兑付的,GC 不能抢在它前面把行收走。
-            [nowMs - RULE_IMPORT_TICKET_GC_GRACE_MS]);
+            const deadTickets = await db.query(q(`DELETE FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE expires_at_ms <= ? LIMIT ${RULE_REAP_BATCH}`, `DELETE FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE ctid IN (SELECT ctid FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE expires_at_ms <= $1 LIMIT ${RULE_REAP_BATCH})`), [nowMs - RULE_IMPORT_TICKET_GC_GRACE_MS]);
             const orphanPending = await db.query(q(`DELETE FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE state = 'pending' AND created_at_ms < ? LIMIT ${RULE_REAP_BATCH}`, `DELETE FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE ctid IN (SELECT ctid FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE state = 'pending' AND created_at_ms < $1 LIMIT ${RULE_REAP_BATCH})`), [nowMs - RULE_PENDING_APPROVAL_RETENTION_MS]);
             return deadTickets.affected + orphanPending.affected;
         },
-        // 两个方言逐字同形(`COUNT(*)` 无方言差),所以刻意**不**走 `q(tidb, pg)` 的双串姿势 —— 那会造出
-        // 两份可以各自漂的同一句 SQL。参数空数组:本语句没有绑定位。
         countBuckets: async () => {
             const { rows } = await db.query(`SELECT COUNT(*) AS n FROM ${PERMISSION_RULE_TABLE}`, []);
-            // PG 的 `COUNT(*)` 走 bigint ⇒ 驱动交回**字符串**;mysql2 交回 number。`Number()` 是两侧共同的收口,
-            // 读不出数(列缺席/NaN)⇒ 响亮抛,绝不静默当 0(0 会被审计读成「确认没有休眠行」= 假结论)。
             const n = Number(rows[0]?.["n"] ?? Number.NaN);
             if (!Number.isFinite(n))
                 throw new Error(`${PERMISSION_RULE_TABLE} bucket count came back unreadable (${String(rows[0]?.["n"])})`);