@sema-agent/server 7.10.0 → 7.11.0

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

@@ -0,0 +1,817 @@
+/**
+ * #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 的**写面**(`PERMISSION_RULE_WRITER` 常量、`PermissionRuleWriter`/`WritablePermissionRuleStore`/
+ * `RuleWriteDelta`/`RawRuleSyncState` 类型、`foldDelta`/`applySyncJoin`/`writerOf`/
+ * `assertRedemptionNotQuarantined`/`assertDeleteDeltaCarriesNoAdd` 函数)**全部不在 `@sema-agent/core`
+ * 的公开导出面上**(亲读 `dist/index.d.ts`;`exports` map 只开 `.`/`./bench`/`./fixtures`,深路径
+ * import 被封)。core 的原话是「a host cannot hold one, so no API-level path to the store bypasses the
+ * consent protocol」——那条纪律针对的是「宿主自己往店里写」,而**一个宿主提供的 backend** 恰恰必须持有
+ * 写面才能被 `redeemRuleTicket` 使用(core 的 `writerOf(store)` 读的就是这个属性)。
+ *
+ * ⇒ 本文件按**结构**满足写面:属性名用 core 的字面常量 `"__semaPermissionRuleWriter"`,类型在下方
+ *   本地镜像(`RuleWriteDeltaMirror` 等)。这**是**一次形状复制,违反「schema 单一属主」的字面——
+ *   处置不是隐瞒而是登记:①镜像类型逐字对着 core 的 d.ts 写,并在 `test/permission-rule-store-*.test.ts`
+ *   里用**结构可赋值性**钉住(core 改形 ⇒ 编译红);②`sync-join` 那一臂**不实现**——它的落地管线
+ *   (`applySyncJoin`)是 core 私有的一整条流水线,复制它才是真的会漂;本 backend 对该 delta **响亮拒绝**
+ *   (fail-closed,不是静默 no-op),同步客户端本仓尚未接线,所以这条臂今天零调用点。
+ *   ③ 求 core 导出写面(或提供一个 `createSqlBackedRuleStore` 适配器)已列入交接件。
+ *
+ * ─────────────────────────────────────────────────────────────────────────────────────────────────
+ * 边界纪律:列回读一律 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, parseAllowRuleText, sameScope, screenRuleSyncState, RULE_SYNC_DROP_CODES, } from "@sema-agent/core";
+import { mysqlDriver, pgDriver, dialectProtocolJsonEncoder } from "./sql-driver.js";
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+// core 私有写面的**本地镜像**(顶注 §「上游契约缺口」逐条理由)
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+/** core `permission-rule-store.ts` 的 `PERMISSION_RULE_WRITER` 字面值(逐字)。`writerOf(store)` 读的
+ *  就是这把键——它是 core 与 backend 之间**事实上的**协议名,只是没被导出。 */
+export const PERMISSION_RULE_WRITER_KEY = "__semaPermissionRuleWriter";
+/**
+ * core 私有 `writerOf` 的**本地对偶**:一只店的写面,或 `undefined`(该 backend 从引擎侧看是只读的)。
+ *
+ * 结构检查而不是断言 —— 它同时是本仓消费点(测试/诊断)读写面的**唯一**入口:没有这个函数,每个调用点
+ * 都会各写一次 `as unknown as {…}`,那既是三处宽松断言,也是三份会各自漂的形状假设。
+ */
+export function writerOfSqlRuleStore(store) {
+    const w = Reflect.get(store, PERMISSION_RULE_WRITER_KEY);
+    if (w === null || typeof w !== "object")
+        return undefined;
+    const nextDot = Reflect.get(w, "nextDot");
+    const apply = Reflect.get(w, "apply");
+    const readRaw = Reflect.get(w, "readRaw");
+    if (typeof nextDot !== "function" || typeof apply !== "function" || typeof readRaw !== "function")
+        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() })
+    .strict();
+const PersistedAllowRuleSchema = z
+    .object({
+    rule: z.string(),
+    tool: z.literal("Bash"),
+    match: z.enum(["exact", "prefix"]),
+    command: z.string(),
+    scope: RuleScopeSchema,
+    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({
+    rule: z.string(),
+    scope: RuleScopeSchema,
+    add: RuleAddSchema,
+    reason: z.custom(isQuarantineReason, { message: "not a registered permission-rule quarantine reason" }),
+    atMs: z.number().int().nonnegative().safe(),
+})
+    .strict();
+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
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+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,
+    owner_kind VARCHAR(32) NOT NULL,
+    principal VARCHAR(512) NULL,
+    -- actor/counter:本副本的 dot 铸造轴(design/182 §4.2 的 replica identity + minted high water)。
+    actor VARCHAR(190) NOT NULL,
+    counter BIGINT NOT NULL DEFAULT 0,
+    -- rev:OCC 计数器(禁叫 version —— 那个词留给形/schema 版本,schema-naming 门③ 咬)。
+    rev BIGINT NOT NULL DEFAULT 0,
+    rules_json LONGTEXT NOT NULL,
+    tombstones_json LONGTEXT NOT NULL,
+    quarantined_json LONGTEXT NOT NULL,
+    -- observed_vector_json:同步游标面(design/182 §5.1 的观测向量)。整读整写的 JSON blob——
+    -- core 明令不得拆成一 actor 一行(会让「半个更新」变得可表达)。
+    observed_vector_json LONGTEXT NULL,
+    last_round_at_ms BIGINT NULL,
+    -- checksum:core \`ruleStoreChecksum\` 同精神的完整性指纹(**只覆盖内容三列**,不含 rev/counter)。
+    -- 读回不符 ⇒ throw(绝不静默当空店 —— core 对读失败的姿势明令如此)。
+    checksum VARCHAR(190) NOT NULL,
+    created_at_ms BIGINT NOT NULL,
+    updated_at_ms BIGINT NOT NULL,
+    PRIMARY KEY (owner_key)
+  ) COLLATE utf8mb4_bin`,
+    `CREATE TABLE IF NOT EXISTS ${PERMISSION_RULE_APPROVAL_TABLE} (
+    record_id VARCHAR(190) NOT NULL,
+    owner_key VARCHAR(190) NOT NULL,
+    owner_kind VARCHAR(32) NOT NULL,
+    principal VARCHAR(512) NULL,
+    kind VARCHAR(32) NOT NULL,
+    state VARCHAR(32) NOT NULL,
+    rev BIGINT NOT NULL DEFAULT 0,
+    candidates_json LONGTEXT NOT NULL,
+    selected_candidate INT NULL,
+    redeemed_dots_json LONGTEXT NULL,
+    tool_call_id VARCHAR(255) NULL,
+    bound_input_hash VARCHAR(255) NULL,
+    -- created_at_iso:core 的 \`RuleApprovalRecord.createdAt\` 是 ISO **字符串**,逐字回放(不是毫秒列,
+    -- 故不带 _ms 后缀);排序/清扫另用 created_at_ms。
+    created_at_iso VARCHAR(64) NOT NULL,
+    created_at_ms BIGINT NOT NULL,
+    updated_at_ms BIGINT NOT NULL,
+    PRIMARY KEY (record_id),
+    KEY idx_permission_rule_approval_owner (owner_key)
+  ) COLLATE utf8mb4_bin`,
+    `CREATE TABLE IF NOT EXISTS ${PERMISSION_RULE_TICKET_TABLE} (
+    ticket_id VARCHAR(190) NOT NULL,
+    -- owner_key:principal 绑定(F1 ①)。redeem 的 authenticated principal 必须算出同一把键,
+    -- 否则与 unknown ticket **同形 404**(禁存在性 oracle)。
+    owner_key VARCHAR(190) NOT NULL,
+    principal VARCHAR(512) NOT NULL,
+    approval_id VARCHAR(190) NOT NULL,
+    -- payload_hash:载荷绑定(F1 ④)。= prepare 时刻候选集的规范摘要;redeem 时与记录上的候选集
+    -- 重算比对,不符 ⇒ 拒(篡改/重放不可扩权)。
+    payload_hash VARCHAR(190) NOT NULL,
+    payload_json LONGTEXT NOT NULL,
+    expires_at_ms BIGINT NOT NULL,
+    -- consumed_at_ms:一次性消费位(F1 ③)。消费 = 单条条件 UPDATE(WHERE consumed_at_ms IS NULL),
+    -- **禁 read-then-write** —— 并发双 redeem 必须恰一成功,那只能由引擎的行锁回答。
+    consumed_at_ms BIGINT NULL,
+    created_at_ms BIGINT NOT NULL,
+    PRIMARY KEY (ticket_id),
+    KEY idx_permission_rule_ticket_owner (owner_key)
+  ) 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);
+}
+export async function ensurePgPermissionRuleSchema(q) {
+    await q(`CREATE TABLE IF NOT EXISTS ${PERMISSION_RULE_TABLE} (
+    owner_key VARCHAR(190) COLLATE "C" NOT NULL,
+    owner_kind VARCHAR(32) COLLATE "C" NOT NULL,
+    principal VARCHAR(512) COLLATE "C",
+    actor VARCHAR(190) COLLATE "C" NOT NULL,
+    counter BIGINT NOT NULL DEFAULT 0,
+    rev BIGINT NOT NULL DEFAULT 0,
+    rules_json TEXT COLLATE "C" NOT NULL,
+    tombstones_json TEXT COLLATE "C" NOT NULL,
+    quarantined_json TEXT COLLATE "C" NOT NULL,
+    observed_vector_json TEXT COLLATE "C",
+    last_round_at_ms BIGINT,
+    checksum VARCHAR(190) COLLATE "C" NOT NULL,
+    created_at_ms BIGINT NOT NULL,
+    updated_at_ms BIGINT NOT NULL,
+    PRIMARY KEY (owner_key)
+  )`);
+    await q(`CREATE TABLE IF NOT EXISTS ${PERMISSION_RULE_APPROVAL_TABLE} (
+    record_id VARCHAR(190) COLLATE "C" NOT NULL,
+    owner_key VARCHAR(190) COLLATE "C" NOT NULL,
+    owner_kind VARCHAR(32) COLLATE "C" NOT NULL,
+    principal VARCHAR(512) COLLATE "C",
+    kind VARCHAR(32) COLLATE "C" NOT NULL,
+    state VARCHAR(32) COLLATE "C" NOT NULL,
+    rev BIGINT NOT NULL DEFAULT 0,
+    candidates_json TEXT COLLATE "C" NOT NULL,
+    selected_candidate INT,
+    redeemed_dots_json TEXT COLLATE "C",
+    tool_call_id VARCHAR(255) COLLATE "C",
+    bound_input_hash VARCHAR(255) 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)`);
+    await q(`CREATE TABLE IF NOT EXISTS ${PERMISSION_RULE_TICKET_TABLE} (
+    ticket_id VARCHAR(190) COLLATE "C" NOT NULL,
+    owner_key VARCHAR(190) COLLATE "C" NOT NULL,
+    principal VARCHAR(512) COLLATE "C" NOT NULL,
+    approval_id VARCHAR(190) COLLATE "C" NOT NULL,
+    payload_hash VARCHAR(190) COLLATE "C" NOT NULL,
+    payload_json TEXT COLLATE "C" NOT NULL,
+    expires_at_ms BIGINT NOT NULL,
+    consumed_at_ms BIGINT,
+    created_at_ms BIGINT NOT NULL,
+    PRIMARY KEY (ticket_id)
+  )`);
+    await q(`CREATE INDEX IF NOT EXISTS idx_permission_rule_ticket_owner ON ${PERMISSION_RULE_TICKET_TABLE} (owner_key)`);
+}
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+// 纯函数(桶键 / 摘要 / 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";
+    if (Array.isArray(v))
+        return `[${v.map(canonicalJson).join(",")}]`;
+    const entries = Object.entries(v)
+        .filter(([, val]) => val !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${entries.map(([k, val]) => `${JSON.stringify(k)}:${canonicalJson(val)}`).join(",")}}`;
+}
+/**
+ * core `foldDelta` 的**语义镜像**:把一次 redemption-add 折进原始规则集。
+ *
+ * 逐字对着 core 的 JSDoc 与 in-memory 参照物写:同 (rule, scope) 归一组,组内 adds 按 **dot 身份**并集
+ * (同 dot 重放 ⇒ 恒等,这正是 core「一次兑付恒铸一个 dot,重放多少次都只有一个 add」的落点)。
+ */
+function foldAdd(rules, delta) {
+    const next = rules.map((r) => ({ ...r, adds: [...r.adds] }));
+    const hit = next.find((r) => r.rule === delta.rule && sameScope(r.scope, delta.scope));
+    if (hit === undefined) {
+        next.push({ rule: delta.rule, tool: delta.tool, match: delta.match, command: delta.command, scope: delta.scope, adds: [delta.add] });
+        return next;
+    }
+    if (!hit.adds.some((a) => a.dot.actor === delta.add.dot.actor && a.dot.counter === delta.add.dot.counter))
+        hit.adds.push(delta.add);
+    return next;
+}
+/** core `assertRedemptionNotQuarantined` 的语义镜像:**任何** (rule, scope) 下与本 delta 同 dot 的
+ *  隔离行都让这次写响亮失败——dot 只铸一次,被隔离钉住的 dot 再出现就是「复活」形。 */
+function assertNotQuarantined(quarantined, delta) {
+    const hit = quarantined.find((q) => q.add.dot.actor === delta.add.dot.actor && q.add.dot.counter === delta.add.dot.counter);
+    if (hit !== undefined) {
+        throw new Error(`refusing to fold a redemption whose dot (${hit.add.dot.actor}#${hit.add.dot.counter}) is quarantined (${hit.reason}) — ` +
+            `re-entry requires a NEW consent (a new ask, a new record, a new dot)`);
+    }
+}
+/** core `assertDeleteDeltaCarriesNoAdd` 的语义镜像(联合已让它不可拼写,但 JS 调用方不受联合约束 ⇒ 执行它)。 */
+function assertDeleteCarriesNoAdd(delta) {
+    // `Reflect.get` 而不是 `as unknown as {…}`:这一行的**全部目的**就是看一个联合类型里不存在的键在不在
+    // (JS 调用方不受联合约束),用断言去表达「我知道它可能有个类型上没有的键」既绕过类型面又触类型卫生门。
+    const smuggled = Reflect.get(delta, "rules");
+    if (smuggled !== undefined)
+        throw new Error("a tighten-delete delta must carry a tombstone and nothing else");
+    if (delta.tombstone === undefined || delta.tombstone.removedDots === undefined)
+        throw new Error("a tighten-delete delta must carry a tombstone");
+}
+/** {@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);
+    if (text === undefined)
+        throw new Error(`permission_rule.${column} is absent for bucket ${ownerKey}; refusing to guess its content`);
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch (err) {
+        throw new Error(`permission_rule.${column} for bucket ${ownerKey} is not valid JSON (${err instanceof Error ? err.message : String(err)})`);
+    }
+    const parsed = schema.safeParse(json);
+    if (!parsed.success)
+        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;
+    now;
+    durability = "durable";
+    fidelity = "json";
+    ownerKey;
+    constructor(db, owner, now = Date.now) {
+        this.db = db;
+        this.owner = owner;
+        this.now = now;
+        this.ownerKey = buildRuleOwnerKey(owner);
+    }
+    enc(v, label) {
+        return dialectProtocolJsonEncoder(this.db.dialect)(v, label);
+    }
+    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];
+        if (row === undefined)
+            return { ...EMPTY_BUCKET, rules: [], tombstones: [], quarantined: [] };
+        const rules = parseColumn(z.array(PersistedAllowRuleSchema), row.rules_json, "rules_json", this.ownerKey);
+        const tombstones = parseColumn(z.array(RuleTombstoneSchema), row.tombstones_json, "tombstones_json", this.ownerKey);
+        const quarantined = parseColumn(z.array(QuarantinedRuleAddSchema), row.quarantined_json, "quarantined_json", this.ownerKey);
+        const observedVector = row.observed_vector_json === null || row.observed_vector_json === undefined ? undefined : parseColumn(FrontierSchema, row.observed_vector_json, "observed_vector_json", this.ownerKey);
+        const state = {
+            actor: String(row.actor ?? ""),
+            counter: Number(row.counter ?? 0),
+            rev: Number(row.rev ?? 0),
+            rules,
+            tombstones,
+            quarantined,
+            ...(observedVector !== undefined ? { observedVector } : {}),
+        };
+        const expected = buildRuleBucketChecksum({ rules, tombstones, quarantined, ...(observedVector !== undefined ? { observedVector } : {}) });
+        if (String(row.checksum ?? "") !== expected) {
+            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;
+        });
+        if (badTombstone !== undefined) {
+            throw new Error(`permission_rule bucket ${this.ownerKey} carries a tombstone whose rule text the single validator refuses or does not spell canonically (${badTombstone.rule}) — ` +
+                `refusing the whole bucket rather than keeping a rule alive under a tombstone that can never match it`);
+        }
+        const screened = screenRuleSyncState({ rules, tombstones });
+        if (screened.rejected.length > 0) {
+            const names = screened.rejected.map((r) => `${r.rule}(${r.reason})`).join(", ");
+            throw new Error(`permission_rule bucket ${this.ownerKey} carries rows the single validator refuses [${names}] — ` +
+                `refusing the whole bucket rather than authorizing a rule whose text and matcher metadata disagree`);
+        }
+        return state;
+    }
+    /** 桶行的**创建**(幂等)。actor 是本 backend 自铸的**副本身份**(design/182:replica identity,
+     *  NEVER a person identity)——一只桶一个,首次落行时定,之后永不变。 */
+    async ensureBucket() {
+        const nowMs = this.now();
+        const empty = { rules: [], tombstones: [], quarantined: [] };
+        await this.db.query(this.q(`INSERT IGNORE INTO ${PERMISSION_RULE_TABLE} (owner_key, owner_kind, principal, actor, counter, rev, rules_json, tombstones_json, quarantined_json, observed_vector_json, last_round_at_ms, checksum, created_at_ms, updated_at_ms)
+         VALUES (?, ?, ?, ?, 0, 0, ?, ?, ?, NULL, NULL, ?, ?, ?)`, `INSERT INTO ${PERMISSION_RULE_TABLE} (owner_key, owner_kind, principal, actor, counter, rev, rules_json, tombstones_json, quarantined_json, observed_vector_json, last_round_at_ms, checksum, created_at_ms, updated_at_ms)
+         VALUES ($1, $2, $3, $4, 0, 0, $5, $6, $7, NULL, NULL, $8, $9, $10) ON CONFLICT (owner_key) DO NOTHING`), [
+            this.ownerKey,
+            this.owner.kind,
+            this.owner.kind === "principal" ? this.owner.principal : null,
+            `sql-${randomBytes(6).toString("hex")}`,
+            this.enc([], "permission_rule.rules_json"),
+            this.enc([], "permission_rule.tombstones_json"),
+            this.enc([], "permission_rule.quarantined_json"),
+            buildRuleBucketChecksum(empty),
+            nowMs,
+            nowMs,
+        ]);
+    }
+    async list() {
+        const s = await this.read();
+        return { rules: applyTombstones(s.rules, s.tombstones), tombstones: s.tombstones, rev: s.rev, checksum: buildRuleBucketChecksum({ rules: s.rules, tombstones: s.tombstones, quarantined: s.quarantined, ...(s.observedVector !== undefined ? { observedVector: s.observedVector } : {}) }) };
+    }
+    async quarantined() {
+        return (await this.read()).quarantined;
+    }
+    get [PERMISSION_RULE_WRITER_KEY]() {
+        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++) {
+                const { rows } = await this.db.query(this.q(`SELECT actor, counter FROM ${PERMISSION_RULE_TABLE} WHERE owner_key = ?`, `SELECT actor, counter FROM ${PERMISSION_RULE_TABLE} WHERE owner_key = $1`), [this.ownerKey]);
+                const row = rows[0];
+                if (row === undefined)
+                    throw new Error(`permission_rule bucket ${this.ownerKey} vanished while minting a dot`);
+                const cur = Number(row.counter);
+                const next = cur + 1;
+                const { affected } = await this.db.query(this.q(`UPDATE ${PERMISSION_RULE_TABLE} SET counter = ?, updated_at_ms = ? WHERE owner_key = ? AND counter = ?`, `UPDATE ${PERMISSION_RULE_TABLE} SET counter = $1, updated_at_ms = $2 WHERE owner_key = $3 AND counter = $4`), [next, this.now(), this.ownerKey, cur]);
+                if (affected === 1)
+                    return { actor: String(row.actor), counter: next };
+            }
+            throw new Error(`could not mint a permission-rule dot for bucket ${this.ownerKey} after ${NEXT_DOT_MAX_ATTEMPTS} attempts`);
+        },
+        readRaw: async () => {
+            await this.ensureBucket();
+            const s = await this.read();
+            return {
+                actor: s.actor,
+                counter: s.counter,
+                rev: s.rev,
+                rules: structuredClone(s.rules),
+                tombstones: structuredClone(s.tombstones),
+                ...(s.observedVector !== undefined ? { observedVector: structuredClone(s.observedVector) } : {}),
+                quarantined: structuredClone(s.quarantined),
+            };
+        },
+        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");
+            }
+            await this.ensureBucket();
+            const cur = await this.read();
+            if (cur.rev !== opts.expectedRev)
+                return { conflict: true, rev: cur.rev };
+            let nextRules = cur.rules;
+            let nextTombstones = cur.tombstones;
+            if (delta.kind === "redemption-add") {
+                assertNotQuarantined(cur.quarantined, delta);
+                nextRules = foldAdd(cur.rules, delta);
+            }
+            else {
+                assertDeleteCarriesNoAdd(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"),
+                this.enc(cur.quarantined, "permission_rule.quarantined_json"),
+                buildRuleBucketChecksum(body),
+                nowMs,
+                this.ownerKey,
+                opts.expectedRev,
+            ]);
+            if (affected === 0) {
+                const again = await this.read();
+                return { conflict: true, rev: again.rev };
+            }
+            return { rev: opts.expectedRev + 1 };
+        },
+    };
+}
+/**
+ * SQL 双方言的 {@link PermissionRuleStoreProvider}。
+ *
+ * `forPrincipal(undefined)` 恒解析成**零规则**店(core 硬条款:未鉴权任务解析到零规则而不是一只共享桶
+ * —— 放宽面上的 fail-closed 是「更少的允许」,绝不是「一只共享的」)。
+ */
+export class SqlPermissionRuleStoreProvider {
+    db;
+    now;
+    constructor(db, now = Date.now) {
+        this.db = db;
+        this.now = now;
+    }
+    forPrincipal(principal) {
+        if (typeof principal !== "string" || principal === "")
+            return ZERO_RULE_STORE;
+        return new SqlPermissionRuleStore(this.db, { kind: "principal", principal }, this.now);
+    }
+    forLocalOwner() {
+        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",
+};
+export function createTiDBPermissionRuleStoreProvider(pool, now) {
+    return new SqlPermissionRuleStoreProvider(mysqlDriver(pool), now);
+}
+export function createPgPermissionRuleStoreProvider(pool, now) {
+    return new SqlPermissionRuleStoreProvider(pgDriver(pool), now);
+}
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+// 审批记录店(core `RuleApprovalRecordStore` 的 SQL 形)
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+/**
+ * durable 审批记录。CAS **按 rev**,不按 state —— core 的原话:批记录的第二个候选会 redeemed→redeemed,
+ * 只比 state 的两次并发重试会**都**认为自己看到了预期状态,各铸一个 dot、各写一次,后者静默覆盖前者的
+ * `redeemedDots`。那正是「一次同意变成两个 add、一条删掉的规则复活」的机制。
+ */
+export class SqlRuleApprovalRecordStore {
+    db;
+    now;
+    constructor(db, now = Date.now) {
+        this.db = db;
+        this.now = now;
+    }
+    q(tidbSql, pgSql) {
+        return this.db.dialect === "tidb" ? tidbSql : pgSql;
+    }
+    enc(v, label) {
+        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 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 kind = z.enum(["card", "import", "starter"]).safeParse(row.kind);
+        const state = z.enum(["pending", "approved", "redeemed"]).safeParse(row.state);
+        if (!kind.success || !state.success) {
+            throw new Error(`${PERMISSION_RULE_APPROVAL_TABLE} row ${id} carries an unreadable kind/state (${String(row.kind)}/${String(row.state)})`);
+        }
+        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),
+            ...(ownerKind === "principal" ? { principal: principal ?? "" } : { owner: { kind: "local-owner" } }),
+            kind: kind.data,
+            state: state.data,
+            candidates,
+            createdAt: String(row.created_at_iso),
+            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.selected_candidate !== null && row.selected_candidate !== undefined ? { selectedCandidate: Number(row.selected_candidate) } : {}),
+            ...(redeemedDots !== undefined ? { redeemedDots } : {}),
+        };
+    }
+    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)`), [
+            record.id,
+            buildRuleOwnerKey(owner),
+            owner.kind,
+            owner.kind === "principal" ? owner.principal : null,
+            record.kind,
+            record.state,
+            record.rev,
+            this.enc(record.candidates, "permission_rule_approval.candidates_json"),
+            record.selectedCandidate ?? null,
+            record.redeemedDots === undefined ? null : this.enc(record.redeemedDots, "permission_rule_approval.redeemed_dots_json"),
+            record.toolCallId ?? null,
+            record.boundInputHash ?? null,
+            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`), [
+            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"),
+            this.now(),
+            id,
+            expectRev,
+        ]);
+        return affected === 1;
+    }
+}
+/** prepare 时刻候选集的规范摘要(载荷绑定 F1 ④ 的判据)。纯数据 ⇒ `build*`。 */
+export function buildRulePayloadHash(candidates) {
+    return createHash("sha256").update(canonicalJson(candidates), "utf8").digest("hex");
+}
+export class SqlRuleImportTicketStore {
+    db;
+    now;
+    constructor(db, now = Date.now) {
+        this.db = db;
+        this.now = now;
+    }
+    q(tidbSql, pgSql) {
+        return this.db.dialect === "tidb" ? tidbSql : pgSql;
+    }
+    async mint(input) {
+        const nowMs = this.now();
+        const expiresAtMs = nowMs + input.ttlMs;
+        const payloadHash = buildRulePayloadHash(input.candidates);
+        await this.db.query(this.q(`INSERT INTO ${PERMISSION_RULE_TICKET_TABLE} (ticket_id, owner_key, principal, approval_id, payload_hash, payload_json, expires_at_ms, consumed_at_ms, created_at_ms)
+         VALUES (?, ?, ?, ?, ?, ?, ?, NULL, ?)`, `INSERT INTO ${PERMISSION_RULE_TICKET_TABLE} (ticket_id, owner_key, principal, approval_id, payload_hash, payload_json, expires_at_ms, consumed_at_ms, created_at_ms)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, NULL, $8)`), [
+            input.ticketId,
+            buildRuleOwnerKey({ kind: "principal", principal: input.principal }),
+            input.principal,
+            input.approvalId,
+            payloadHash,
+            dialectProtocolJsonEncoder(this.db.dialect)(input.candidates, "permission_rule_ticket.payload_json"),
+            expiresAtMs,
+            nowMs,
+        ]);
+        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) {
+        const nowMs = this.now();
+        const ownerKey = buildRuleOwnerKey({ kind: "principal", principal });
+        // 预读:①取不可变的 approvalId/payloadHash(于是认领之后零 I/O);②给四类拒绝一个准确归因。
+        const row = await this.readRow(ticketId);
+        if (row === undefined)
+            return { ok: false, reason: "unknown" };
+        if (row.ownerKey !== ownerKey)
+            return { ok: false, reason: "wrong-principal" };
+        if (row.consumedAtMs !== undefined)
+            return { ok: false, reason: "consumed" };
+        if (row.expiresAtMs <= nowMs)
+            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`), [nowMs, ticketId, ownerKey, nowMs]);
+        // 认领成功 ⇒ 直接用预读那份不可变值返回,**不再发任何一条语句**(这正是本次修复的全部内容)。
+        if (affected === 1)
+            return { ok: true, approvalId: row.approvalId, payloadHash: row.payloadHash };
+        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) {
+        // 🔴 codex 交叉复审 round6 [medium](验真后修):`expires_at_ms` 也进 WHERE,而且比的是
+        // **now + 通告的重试窗**,不是 now。理由:调用方拿本方法的返回值去决定要不要对客户端说
+        // 「稍后拿同一张票重试」——若这张票在那几秒里就会过期,那句话是**必然兑现不了**的承诺
+        // (客户端等完 Retry-After 回来只会收到 404,而且这一轮的确认已经丢了)。撑不过窗 ⇒ 如实回 false,
+        // 调用方于是按不可重试报(四类同形 404),不给一条注定走死的路。
+        const nowMs = 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;
+    }
+    async readRow(ticketId) {
+        const { rows } = await this.db.query(this.q(`SELECT owner_key, approval_id, payload_hash, expires_at_ms, consumed_at_ms FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE ticket_id = ?`, `SELECT owner_key, approval_id, payload_hash, expires_at_ms, consumed_at_ms FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE ticket_id = $1`), [ticketId]);
+        const row = rows[0];
+        if (row === undefined)
+            return undefined;
+        return {
+            ownerKey: String(row.owner_key),
+            approvalId: String(row.approval_id),
+            payloadHash: String(row.payload_hash),
+            expiresAtMs: Number(row.expires_at_ms),
+            ...(row.consumed_at_ms === null || row.consumed_at_ms === undefined ? {} : { consumedAtMs: Number(row.consumed_at_ms) }),
+        };
+    }
+}
+export function createSqlPermissionRuleStores(db, now) {
+    return {
+        provider: new SqlPermissionRuleStoreProvider(db, now),
+        approvals: new SqlRuleApprovalRecordStore(db, now),
+        tickets: new SqlRuleImportTicketStore(db, now),
+    };
+}
+//# sourceMappingURL=permission-rule-store-sql.js.map