@sema-agent/server 7.11.0 → 7.12.0

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

@@ -0,0 +1,371 @@
+/**
+ * #203 §1(design/203 v2 §6 F1)—— 持久化权限规则店的 **local(File)三面束**。
+ *
+ * 车二在 `store-backend.ts` 上写下的那句「local 车道诚实缺席」有一条**明写的解除条件**:「要在 local
+ * 真上,先落 File 形(core 现成 `FilePermissionRuleStoreProvider` 即可当模子)」。本文件就是那一件 ——
+ * 三面里**规则桶那一面直接接线 core 的现成件**(不是照抄:它自带符号链接拒收、写锁、整文件校验和、
+ * 损坏即整份拒读,那几样都不是能顺手复刻对的东西),另外两面(审批记录 / 导入票)core 只给了
+ * `InMemory` 参照物,所以在这里落 File 形。
+ *
+ * ─────────────────────────────────────────────────────────────────────────────────────────────────
+ * 🔴 为什么 File 形的「单进程内 CAS」是**够的**(而不是一次偷工)
+ * ─────────────────────────────────────────────────────────────────────────────────────────────────
+ * SQL 形把 CAS 交给引擎的行锁,是因为多副本共享一张表。local 车道不是那个形状:`LocalBackend` 的构造
+ * 函数在数据根上取 `root/LOCK` 这只 boot pidfile 锁,**同主机第二个实例起不来**(store-backend.ts 的
+ * `LocalBackend` 头注逐字);core 的 `FilePermissionRuleStoreProvider` 自己还在规则目录上另取一把写锁,
+ * 第二个持有者被响亮拒绝而不是交错写。⇒ 在这条车道上「同一时刻只有一个写者」是**被强制**的,不是被
+ * 假设的,于是进程内的 `rev` 比较就是一次真 compare-and-set。
+ * 这条推理有一个已登记的边界(与 core 的 File 规则店同源、不是本文件新增的):跨 PID 命名空间或 NFS
+ * 上 `process.kill(pid,0)` 的活体判据会失效(见 `docs/DEPLOY-PREREQS.md`)。那时该换 SQL 后端 ——
+ * 这正是 store seam 存在的理由。
+ *
+ * ─────────────────────────────────────────────────────────────────────────────────────────────────
+ * 🔴 落盘形:一票据/一记录一行 JSONL 追加日志 + boot 重放,**不是**整文件覆写
+ * ─────────────────────────────────────────────────────────────────────────────────────────────────
+ * 与 `FileApprovalExemptionStore` / `FileSendFileLedger` 同一个模子(core 的 `AppendLog` /
+ * `readJsonlRecords`:追加 + fsync,撕裂的尾行在重放时被丢掉而不是被猜出来)。选它而不是「整份 JSON
+ * 原子改名」的理由是**这两面的写都是逐条的**(一次审批一条、一张票一条),整份覆写会让一次写的代价随
+ * 历史长度线性涨,而且把「两条无关记录」放进同一次 CAS 窗口。
+ * 代价如实登记:日志只增不减(没有紧凑腿)。票有 TTL、记录是审计事实,单用户一台机器上的量级是每天
+ * 几条到几十条 —— 真长到要紧凑时,该做的是紧凑腿(后续件),不是现在为它牺牲崩溃安全。
+ *
+ * ─────────────────────────────────────────────────────────────────────────────────────────────────
+ * 🔴 状态在**内存索引**里,磁盘是它的重放源
+ * ─────────────────────────────────────────────────────────────────────────────────────────────────
+ * 判决(CAS 成不成、票能不能认领)一律读内存索引,写成功后**先追加日志再改索引** —— 反过来(先改索引
+ * 再写盘)会在写失败时留下一个「进程认为已经发生、盘上没有」的事实,重启即回滚,而中间那段时间里
+ * 一次已经被消费掉的票会被当成还能用。
+ */
+import { join } from "node:path";
+import { readdirSync } from "node:fs";
+import { FilePermissionRuleStoreProvider, AppendLog, ensureDir, readJsonlRecords, } from "@sema-agent/core";
+import { z } from "zod";
+import { buildRulePayloadHash } from "./permission-rule-store-sql.js";
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+// 落盘记录的边界 schema(宪法 [2704]:边界必 schema,禁裸 as-cast)
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+//
+// 🔴 这**是**一条边界:磁盘上的字节可能来自上一个版本、来自一次手改、来自一次撕裂写。读回来的东西
+// 若被 as-cast 成域类型,一条缺字段的记录会带着 `undefined` 走进 CAS 与兑付判决。判据用 zod。
+//
+// 🔴 读不出形的**内部**行 ⇒ 整面 fail-closed(codex 对抗复审 R1-F4,验真后修)。
+// 本文件的初版写的是「坏行跳过 —— 一行是一条独立事实」,那句话是**错的**,而且错在最贵的地方:
+// 票日志上的 mint / consume / release 是**同一张票的状态迁移**。一条 `consume` 坏掉而它前面的 `mint`
+// 还读得出 ⇒ 重启后那张票复活成**未认领**,「一次性消费」这条信任边界当场失效(SQL 形靠引擎行锁,
+// 永远不会有这种形)。审批记录同族:一条坏掉的快照会把记录连同 `rev` 回滚到更早的状态。
+// 处置与 core 对**规则文件**的姿势对齐 ——「refusing the whole bucket rather than reporting a partial
+// rule set」:整面拒 + 响亮留痕。失败方向是收紧(兑不动 ⇒ 多问几次),这正是这条轴该倒的方向。
+// **撕裂的尾行不算**:core 的 `readJsonlRecords` 按崩溃尾丢弃它并且**不**报 `onCorrupt` —— 那是每次
+// 非优雅退出的正常落盘形,把它算成损坏会让一次 kill -9 永久锁死这条车道。
+const RuleScopeSchema = z.union([
+    z.object({ kind: z.literal("global") }).strict(),
+    z.object({ kind: z.literal("project"), root: z.string().min(1) }).strict(),
+]);
+const RuleDotSchema = z.object({ actor: z.string().min(1), counter: z.number().int().nonnegative().safe() }).strict();
+const RuleCandidateSchema = z.object({ rule: z.string(), scope: RuleScopeSchema }).strict();
+const ApprovalRecordSchema = z
+    .object({
+    id: z.string().min(1),
+    principal: z.string().optional(),
+    owner: z.union([z.object({ kind: z.literal("principal"), principal: z.string() }).strict(), z.object({ kind: z.literal("local-owner") }).strict()]).optional(),
+    kind: z.enum(["card", "import", "starter"]),
+    state: z.enum(["pending", "approved", "redeemed"]),
+    candidates: z.array(RuleCandidateSchema),
+    createdAt: z.string(),
+    toolCallId: z.string().optional(),
+    boundInputHash: z.string().optional(),
+    rev: z.number().int().nonnegative().safe(),
+    selectedCandidate: z.number().int().nonnegative().safe().optional(),
+    redeemedDots: z.record(z.string(), RuleDotSchema).optional(),
+})
+    .strict();
+/**
+ * 校验产物 → 域类型的**显式**投影。
+ *
+ * 🔴 为什么是一个函数而不是 `.transform(...)` 上挂一个断言:`RuleApprovalRecord.redeemedDots` 的键是
+ * `number`,而 JSON 对象的键恒是字符串 —— zod 只表达得出 `Record<string, …>`,于是「用 zod 直接声明成
+ * 域类型」必然要一次 `as unknown as`,那正是宪法禁的裸断言。逐字段抄写换来的是:core 给
+ * `RuleApprovalRecord` 加一个必填字段时,**这里编译红**(而断言形会静默放行一条缺字段的记录)。
+ * 数字键的还原与 SQL 侧 `redeemed_dots_json` 的回读逐字同一处置。
+ */
+function toApprovalRecord(row) {
+    return {
+        id: row.id,
+        ...(row.principal !== undefined ? { principal: row.principal } : {}),
+        ...(row.owner !== undefined ? { owner: row.owner } : {}),
+        kind: row.kind,
+        state: row.state,
+        candidates: row.candidates,
+        createdAt: row.createdAt,
+        ...(row.toolCallId !== undefined ? { toolCallId: row.toolCallId } : {}),
+        ...(row.boundInputHash !== undefined ? { boundInputHash: row.boundInputHash } : {}),
+        rev: row.rev,
+        ...(row.selectedCandidate !== undefined ? { selectedCandidate: row.selectedCandidate } : {}),
+        ...(row.redeemedDots !== undefined
+            ? { redeemedDots: Object.fromEntries(Object.entries(row.redeemedDots).map(([k, v]) => [Number(k), v])) }
+            : {}),
+    };
+}
+/** 审批记录日志的一行:整条记录的快照(last-wins 重放)或一条丢弃墓碑。 */
+const ApprovalLineSchema = z.union([
+    z.object({ op: z.literal("put"), record: ApprovalRecordSchema }).strict(),
+    z.object({ op: z.literal("discard"), id: z.string().min(1) }).strict(),
+]);
+/** 票日志的一行:铸票 / 认领 / 放回。三个动作各一行,重放顺序即真相。 */
+const TicketLineSchema = z.union([
+    z
+        .object({
+        op: z.literal("mint"),
+        ticketId: z.string().min(1),
+        ownerKey: z.string().min(1),
+        approvalId: z.string().min(1),
+        payloadHash: z.string().min(1),
+        expiresAtMs: z.number().int().nonnegative().safe(),
+    })
+        .strict(),
+    z.object({ op: z.literal("consume"), ticketId: z.string().min(1), atMs: z.number().int().nonnegative().safe() }).strict(),
+    z.object({ op: z.literal("release"), ticketId: z.string().min(1) }).strict(),
+]);
+/**
+ * 一面的**损坏闸**。置位之后该面的每一个方法都响亮拒绝 —— 读与写都拒:一份不完整的授权账既不能用来
+ * 判决,也不能在它上面继续追加(追加只会让下一次重启读到同样残缺的历史)。
+ */
+class CorruptionGate {
+    face;
+    path;
+    onError;
+    reason;
+    constructor(face, path, onError) {
+        this.face = face;
+        this.path = path;
+        this.onError = onError;
+    }
+    /** 记一次内部损坏(幂等:第一条原因就是要报告的那条)。 */
+    trip(reason) {
+        this.reason ??= reason;
+        this.onError?.(`${this.face} at ${this.path} is corrupt: ${reason}`);
+    }
+    get tripped() {
+        return this.reason !== undefined;
+    }
+    /** 每个方法的第一行。文案里带上文件路径与处置 —— 一个运维读到它要知道去看哪个文件。 */
+    assertUsable() {
+        if (this.reason === undefined)
+            return;
+        throw new Error(`refusing to use a corrupt ${this.face} (${this.path}): ${this.reason} — ` +
+            "the permission-rule lane is fail-closed until a person inspects the file (moving it aside restarts the lane with an empty log)");
+    }
+}
+/**
+ * `RuleApprovalRecordStore` 的 File 形。
+ *
+ * CAS 按 `rev`(core 硬条款,理由逐字见 SQL 侧同名类的头注:只比 state 会让批记录的第二个候选上两次
+ * 并发重试都以为自己赢了)。
+ */
+export class FileRuleApprovalRecordStore {
+    rows = new Map();
+    log;
+    gate;
+    constructor(dir, onError) {
+        ensureDir(dir);
+        const path = join(dir, "approvals.jsonl");
+        this.gate = new CorruptionGate("permission-rule approval log", path, onError);
+        // `onCorrupt` = core 对**内部**不可解析行的报告口(崩溃尾它自己丢弃且不报)。不接它就是把一次
+        // 「历史被削掉一块」变成静默 —— #191 门② 说的正是这个形。
+        for (const raw of readJsonlRecords(path, (info) => this.gate.trip(info.reason))) {
+            const parsed = ApprovalLineSchema.safeParse(raw);
+            if (!parsed.success) {
+                // 形不对 = 与「解析不出」同一类事实(版本漂/手改),同样是历史缺了一块 ⇒ 同样 fail-closed。
+                this.gate.trip(`a replayed record does not carry a readable shape: ${parsed.error.message}`);
+                continue;
+            }
+            if (parsed.data.op === "discard")
+                this.rows.delete(parsed.data.id);
+            else
+                this.rows.set(parsed.data.record.id, toApprovalRecord(parsed.data.record));
+        }
+        this.log = new AppendLog(path);
+    }
+    /** 取证/自证用:本面是否因内部损坏而 fail-closed。 */
+    get corrupt() {
+        return this.gate.tripped;
+    }
+    /** 归还本面 eager 持有的日志描述符(束的 `dispose()` 唯一调用点)。`AppendLog` 上没有 finalizer,
+     *  不显式关就是一只跟到进程末尾的 fd —— `LocalBackend` 反复开合(热重载/多根)时按次泄漏。
+     *  关后写面抛 `log_closed`(core 语义):**不重开**,因为「这只店已经交还」与「这条命还能写」
+     *  不能两立,静默重开会让一次 dispose 之后的写落进一份没人再读的日志。 */
+    close() {
+        this.log.close();
+    }
+    async get(id) {
+        this.gate.assertUsable();
+        const r = this.rows.get(id);
+        // 深拷贝出门:调用方(core 的兑付腿)会就地改它再交回 `cas`,共享同一个对象会让 CAS 比的是
+        // 「自己改过的那份」——那等于没有 CAS。
+        return r === undefined ? undefined : structuredClone(r);
+    }
+    async create(record) {
+        this.gate.assertUsable();
+        if (this.rows.has(record.id))
+            throw new Error(`rule approval record ${record.id} already exists`);
+        this.log.append({ op: "put", record }, true); // 先盘后索引(顶注)
+        this.rows.set(record.id, structuredClone(record));
+    }
+    async cas(id, expectRev, next) {
+        this.gate.assertUsable();
+        if (next.rev !== expectRev + 1) {
+            throw new Error(`rule-approval CAS must advance rev by exactly one (expectRev=${expectRev}, next.rev=${next.rev})`);
+        }
+        const cur = this.rows.get(id);
+        if (cur === undefined || cur.rev !== expectRev)
+            return false;
+        this.log.append({ op: "put", record: next }, true);
+        this.rows.set(id, structuredClone(next));
+        return true;
+    }
+    /** 与 SQL 侧同名方法同义(超帽拒绝时收掉 `prepareCcImport` 已落盘的那条 pending 记录)。
+     *  `state === "pending"` 是硬的:已确认/已兑付的记录是一次真人同意的审计事实。 */
+    async discardPendingRecord(recordId) {
+        this.gate.assertUsable();
+        const cur = this.rows.get(recordId);
+        if (cur === undefined || cur.state !== "pending")
+            return false;
+        this.log.append({ op: "discard", id: recordId }, true);
+        this.rows.delete(recordId);
+        return true;
+    }
+}
+/**
+ * CC 导入票的 File 形。四条信任边界(principal 绑定 / TTL / 一次性原子消费 / 载荷绑定)与 SQL 形
+ * **同语义**;唯一不同的是「原子」由谁保证 —— 那边是引擎行锁,这边是单进程 + 单写者(顶注)。
+ */
+export class FileRuleImportTicketStore {
+    rows = new Map();
+    log;
+    gate;
+    constructor(dir, now, onError) {
+        this.now = now ?? Date.now;
+        ensureDir(dir);
+        const path = join(dir, "import-tickets.jsonl");
+        this.gate = new CorruptionGate("permission-rule import-ticket log", path, onError);
+        // 🔴 这一面是四条信任边界里「一次性原子消费」的**唯一**载体(SQL 形靠引擎行锁,File 形靠这份日志)。
+        // 内部坏行 ⇒ 整面 fail-closed:一张票复活成未认领,代价是一次人的同意被重复兑付。
+        for (const raw of readJsonlRecords(path, (info) => this.gate.trip(info.reason))) {
+            const parsed = TicketLineSchema.safeParse(raw);
+            if (!parsed.success) {
+                this.gate.trip(`a replayed record does not carry a readable shape: ${parsed.error.message}`);
+                continue;
+            }
+            const line = parsed.data;
+            if (line.op === "mint") {
+                this.rows.set(line.ticketId, { ownerKey: line.ownerKey, approvalId: line.approvalId, payloadHash: line.payloadHash, expiresAtMs: line.expiresAtMs });
+                continue;
+            }
+            const row = this.rows.get(line.ticketId);
+            if (row === undefined)
+                continue;
+            if (line.op === "consume")
+                row.consumedAtMs = line.atMs;
+            else
+                delete row.consumedAtMs;
+        }
+        this.log = new AppendLog(path);
+    }
+    now;
+    /** 取证/自证用:本面是否因内部损坏而 fail-closed。 */
+    get corrupt() {
+        return this.gate.tripped;
+    }
+    /** 归还本面 eager 持有的日志描述符(理由与姊妹面 {@link FileRuleApprovalRecordStore.close} 逐字同源)。 */
+    close() {
+        this.log.close();
+    }
+    async mint(input) {
+        this.gate.assertUsable();
+        const expiresAtMs = this.now() + input.ttlMs;
+        // 摘要函数与 SQL 形**同一个**(载荷绑定的等式两侧同源;两份实现必然各自漂)。
+        const payloadHash = buildRulePayloadHash(input.candidates);
+        // owner 键:本车道只铸 principal 形的票(local-owner 桶没有跨网络的导入口)。刻意存**明文
+        // principal** 而不是 SQL 侧那把 sha —— 那把 hash 的两条理由(列宽静默截断、local-owner 需要定长
+        // 同域表示)在一份进程内 Map 上都不成立,而明文让一次取证直接读得懂。
+        this.log.append({ op: "mint", ticketId: input.ticketId, ownerKey: input.principal, approvalId: input.approvalId, payloadHash, expiresAtMs }, true);
+        this.rows.set(input.ticketId, { ownerKey: input.principal, approvalId: input.approvalId, payloadHash, expiresAtMs });
+        return { ticketId: input.ticketId, approvalId: input.approvalId, payloadHash, expiresAtMs };
+    }
+    /** 一次性**认领**。四条否定项的判序与 SQL 形逐字相同(unknown → wrong-principal → consumed → expired),
+     *  于是两形的服务端日志归因可比;wire 面把四类折成同一个 404(零存在性 oracle)。 */
+    async consume(ticketId, principal) {
+        this.gate.assertUsable();
+        const row = this.rows.get(ticketId);
+        if (row === undefined)
+            return { ok: false, reason: "unknown" };
+        if (row.ownerKey !== principal)
+            return { ok: false, reason: "wrong-principal" };
+        if (row.consumedAtMs !== undefined)
+            return { ok: false, reason: "consumed" };
+        const nowMs = this.now();
+        if (row.expiresAtMs <= nowMs)
+            return { ok: false, reason: "expired" };
+        this.log.append({ op: "consume", ticketId, atMs: nowMs }, true);
+        row.consumedAtMs = nowMs;
+        return { ok: true, approvalId: row.approvalId, payloadHash: row.payloadHash };
+    }
+    /** 把认领**放回去**。`mustRemainValidMs` = 放回之后至少还要能用多久 —— 撑不过就不算放回成功
+     *  (理由逐字见 SQL 侧 `release` 的头注:承诺一次必然兑现不了的重试比不承诺更坏)。 */
+    async release(ticketId, principal, mustRemainValidMs = 0) {
+        this.gate.assertUsable();
+        const row = this.rows.get(ticketId);
+        if (row === undefined || row.ownerKey !== principal || row.consumedAtMs === undefined)
+            return false;
+        if (row.expiresAtMs <= this.now() + mustRemainValidMs)
+            return false;
+        this.log.append({ op: "release", ticketId }, true);
+        delete row.consumedAtMs;
+        return true;
+    }
+}
+/**
+ * 装配 local 三面束。
+ *
+ * 🔴 `provider` 必须是**单例**(F1):core 的 `FilePermissionRuleStoreProvider` 在第一次取写面时对规则
+ * 目录取一把进程级写锁,每次 `new` 一个就是第二个持有者 —— 而它对第二个持有者是**响亮拒绝**,不是
+ * 排队。所以束在 `LocalBackend` 上按字段持有,`LocalBackend.close()` 调 `dispose()` 释放
+ * (不释放 ⇒ 一次优雅重启会被自己上一条命留下的锁挡在门外,与数据根 `root/LOCK` 同一个病)。
+ *
+ * `onError` 接的是 core 规则文件的**披露面**(读不出来 / 校验和不符 / 撞上符号链接时它答零规则并
+ * 说出来)。接住它打一条 warn 是**必须**的:那条路径上「零规则」与「真的没有规则」在读面上同形,
+ * 不留痕就变成一次静默的 fail-closed(用户会突然被反复询问,却没有任何线索)。
+ */
+export function createFilePermissionRuleStores(root, opts) {
+    const dir = join(root, "permission-rules");
+    ensureDir(dir);
+    const provider = opts?.onError ? new FilePermissionRuleStoreProvider(dir, opts.onError) : new FilePermissionRuleStoreProvider(dir);
+    // 三面共用**同一个**告警口:core 规则文件的披露与本仓两份日志的损坏对运维是同一件事
+    // (「这台机器上的规则面出问题了,去看这个目录」),分成两个 sink 只会让其中一个没人接。
+    const approvals = new FileRuleApprovalRecordStore(dir, opts?.onError);
+    const tickets = new FileRuleImportTicketStore(dir, opts?.now, opts?.onError);
+    return {
+        provider,
+        approvals,
+        tickets,
+        /** 桶数 = 规则目录里的桶文件数(core 的命名:`<64 hex>.json` = 一只 principal 桶,
+         *  `local-owner.json` = 身份缺席桶)。**刻意不数**审批/票的日志文件与收编标记文件 ——
+         *  审计问的是「有没有既有的规则状态」,不是「这个目录里有几个文件」。
+         *
+         *  🔴 读不出目录就**抛**(不 catch 成 0)。目录在装配时刚 `ensureDir` 过,读不动只可能是被外力
+         *  删掉/权限被改 —— 那是「不知道」,不是「零」。回 0 会被休眠行审计读成「确认没有休眠行」,把一次
+         *  读失败伪装成一个结论;审计那侧本来就有 fail-open 臂(warn + 不拒启),让它去处置才是对的分工。 */
+        countBuckets: async () => readdirSync(dir).filter((n) => n === "local-owner.json" || /^[0-9a-f]{64}\.json$/.test(n)).length,
+        /** 三面各自的释放,**两只日志先于 provider**:provider 那步释放的是规则目录的进程级写锁,
+         *  一旦它先松手,同一个根就可能被下一位持有者开起来 —— 而此刻本束的两只 fd 还开着。顺序写死
+         *  在这里,`LocalBackend.close()` 只需调这一只口(与它对其余 file 店逐行关闭的既有纪律同形)。
+         *  幂等:两只 `close()` 与 `provider.dispose()` 都可重入(重复调用是常态 —— 兜底路径与
+         *  `LocalBackend.close()` 会各调一次)。 */
+        dispose: () => {
+            approvals.close();
+            tickets.close();
+            provider.dispose();
+        },
+    };
+}
+//# sourceMappingURL=permission-rule-store-file.js.map

package/dist/plugins/permission-rule-store-sql.d.ts

@@ -237,6 +237,13 @@ export interface PermissionRuleStores {
     provider: SqlPermissionRuleStoreProvider;
     approvals: SqlRuleApprovalRecordStore;
     tickets: SqlRuleImportTicketStore;
+    /** #203 §3 —— boot 期休眠行审计的**窄读口**:库里已有几只桶(`permission_rule` 一行一桶)。
+     *
+     *  🔴 为什么数**桶**而不是数**规则**:数规则要把每一行的 `rules_json` 都读回来再解析(一只桶的规则集
+     *  没有硬上限,顶注 §列宽依据已说明它是 LONGTEXT),那是一次无界的 boot 期扫描 —— 为一条诊断行付这个
+     *  代价不划算。桶数回答的正是审计要问的那个问题(「这台部署上有没有既有的规则状态」),而且是一次
+     *  索引级 `COUNT(*)`。消费点(`boot/permission-rules-audit.ts`)的文案因此逐字说的是 bucket,不是 rule。 */
+    countBuckets(): Promise<number>;
 }
 export declare function createSqlPermissionRuleStores(db: SqlDriver, now?: () => number): PermissionRuleStores;
 //# sourceMappingURL=permission-rule-store-sql.d.ts.map

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

@@ -812,6 +812,17 @@ export function createSqlPermissionRuleStores(db, now) {
         provider: new SqlPermissionRuleStoreProvider(db, now),
         approvals: new SqlRuleApprovalRecordStore(db, now),
         tickets: new SqlRuleImportTicketStore(db, now),
+        // 两个方言逐字同形(`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"])})`);
+            return n;
+        },
     };
 }
 //# sourceMappingURL=permission-rule-store-sql.js.map

package/dist/plugins/store-backend.d.ts

@@ -24,7 +24,7 @@ import type { CounterDegradeHook } from "./write-behind-counter.js";
 import { PgRateLimiter } from "./pg-rate-limiter.js";
 import { type SqlSharedMemoryStore, type SharedMemoryScopeAuthorizer } from "./shared-memory-store-sql.js";
 import { type AdoptionLogStore } from "./adoption-log-sql.js";
-import { type PermissionRuleStores } from "./permission-rule-store-sql.js";
+import type { PermissionRuleStoreBundle } from "../rules-consent.js";
 export type RunStore = TiDBRunStore | PgRunStore | FileRunStore;
 /** E18 resume-at eventId→entryId anchor map — tidb/pg/local 3-backend (works LOCAL; needs only the session tree +
  *  this map, no cloud-only checkpoint). Union = the three nominal twins; consumers use put/resolve/deleteBySession.
@@ -138,10 +138,12 @@ export interface StoreBackend {
      *
      * `local` 车道**刻意不给 in-memory twin**:一条规则是「人授权过的持久事实」,进程内 Map 形会在重启时
      * 静默丢掉那份授权,而消费端(下一次同命令的 ask)读到的是「没有规则」——那是**放宽面**上的静默降级。
-     * 诚实缺席(storeWired:false)比一个会遗忘的店正确。要在 local 真上,先落 File 形(core 现成
-     * `FilePermissionRuleStoreProvider` 即可当模子)。
+     * ✅ **#203 §1 已落 File 形**(那条注写下的解除条件逐字是「先落 File 形,core 现成
+     * `FilePermissionRuleStoreProvider` 即可当模子」——本车照办):`local` 现在返回一个**跨重启存活**的
+     * 三面束,storeWired 在单机车道上真为 true。in-memory twin 的禁令不变,它禁的是「会遗忘的店」,
+     * 不是「单机的店」。
      */
-    permissionRule(): PermissionRuleStores | undefined;
+    permissionRule(): PermissionRuleStoreBundle | undefined;
     /** SendUserFile scope↔object ledger (multi-tenant list/revoke handle; the hashed key segment hides the
      *  mapping from URLs). REQUIRED on all backends (works local — one JSONL, like approvalExemption). */
     sendFileLedger(): SendFileLedger;
@@ -239,8 +241,12 @@ export declare function snapshotBoundsFromConfig(config: ServiceConfig): FileSna
  */
 export declare function counterStoreLabel(store: unknown, kind: string | undefined): string;
 /** Build the durable-store backend for `config.dbBackend`. Does NOT connect (the pool connects lazily; the
- *  reachability probe is the caller's first `ensureSchema`). Returns undefined when no DB is configured. */
-export declare function createStoreBackend(config: ServiceConfig): StoreBackend | undefined;
+ *  reachability probe is the caller's first `ensureSchema`). Returns undefined when no DB is configured.
+ *
+ *  `onWarn` (additive, optional) is the boot-time warning sink the LOCAL backend needs for core's
+ *  permission-rule DISCLOSURE face (#203 §1): an unreadable / checksum-mismatched / symlinked rule file
+ *  answers ZERO rules and says so — swallowing that turns a fail-closed degrade into a silent one. */
+export declare function createStoreBackend(config: ServiceConfig, onWarn?: (msg: string, meta?: Record<string, unknown>) => void): StoreBackend | undefined;
 /** boot 期打开 store 后端的**统一入口**:构造 + ensureSchema 同罩一层降级臂。
  *
  *  为什么必须把 `createStoreBackend()` 也罩进来(2026-07-28 修):clay 1.292 拍的口径是「裸 boot

package/dist/plugins/store-backend.js

@@ -8,7 +8,7 @@
  */
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { FileStorageBackend, FileSessionRepo, DEFAULT_SNAPSHOT_BOUNDS } from "@sema-agent/core";
+import { AdoptionError, FileStorageBackend, FileSessionRepo, DEFAULT_SNAPSHOT_BOUNDS } from "@sema-agent/core";
 import { FileWorkflowJournalStore } from "@sema-agent/core";
 import { TiDBOutcomeLedger, PgOutcomeLedger } from "./outcome-ledger-sql.js";
 import { FileOutcomeSink } from "./file-outcome-sink.js";
@@ -43,7 +43,9 @@ import { PgSessionStore } from "./pg-session-storage.js";
 import { TiDBSharedMemoryStore, PgSharedMemoryStore } from "./shared-memory-store-sql.js";
 import { TiDBAdoptionLogStore, PgAdoptionLogStore } from "./adoption-log-sql.js";
 // #154 车二:持久化权限规则店(三面一束)。`mysqlDriver`/`pgDriver` 是既有的方言中立 seam。
+// #203 §1:local 车道的 File 三面束(core 现成 provider + 本仓 File 形审批记录/导入票)。
 import { createSqlPermissionRuleStores } from "./permission-rule-store-sql.js";
+import { createFilePermissionRuleStores } from "./permission-rule-store-file.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
 /** Build the snapshot-BLOB object-store backend from config, or undefined to fall back to the SqlBlobBackend default.
  *  When `config.snapshotBlobStore` (MINIO_* env) is set, the E19/2c file-snapshot stores route ONLY the blob BYTES to
@@ -202,13 +204,29 @@ class LocalBackend {
     workflowJournalStore;
     /** design/73 §1 — owner-only JSONL outcome-fact sink (stateless append; no fd held). */
     outcomeSinkInst;
-    constructor(root, config) {
+    /** boot 期的告警口(`openStoreBackendWithFallback` 把它接到 logger.warn 上)。可选:直接 `new` 一只
+     *  LocalBackend 的测试/工具不必装配日志面 —— 缺席时 core 的披露仍留在 core 那侧,只是本仓不复述。 */
+    onWarn;
+    constructor(root, config, onWarn) {
+        this.onWarn = onWarn;
         // The fileBackend ctor mkdirs `root` + takes the boot pidfile lock — a same-host SECOND instance FAILS FAST.
         // Re-throw with a clear operator message (the raw core error is "another instance owns this data dir").
+        //
+        // 🔴 core 5.23.0([3372] 提货批件④):这个构造器现在有**第二个**拒绝面 —— design/183 的 I6 adoption
+        // boot 门(`dist/stores/file/index.js:45` 的 `assertAdoptionBootGate`):数据根下 `adoption.json` 是
+        // 在飞标记 ⇒ `AdoptionError("adoption_in_flight")`,标记读不出 ⇒ `"adoption_marker_corrupt"`。
+        // 原来的 catch 是 **catch-all**,会把它一并改写成下面那句 boot-lock 文案 —— 那是**误诊**:它给的两条
+        // 出路对 adoption 在飞都不对,而「把 LOCAL_DATA_ROOT 指到一个空目录」更是直接劝运维**丢下一个迁移
+        // 到一半的数据根**;`AdoptionError` 的类型身份与 typed `code` 也在改写中被抹掉。
+        // ⇒ `AdoptionError` **原样穿过**:core 的拒绝句本就是写给人读的(点名在飞的那条弧,并给出「resume
+        // adoptLocalDataRoot 到完成,或修 adoption.json」的出路),我们没有更好的话可说,包一层只会更差。
+        // 包装只留给真正的 boot-lock 类失败(那句文案的适用条件)。
         try {
             this.fileBackend = new FileStorageBackend({ root, ...(config.rewindSnapshotMaxMb !== undefined ? { snapshotBounds: { maxBytes: Math.round(config.rewindSnapshotMaxMb * 1024 * 1024) } } : {}) }); // REWIND_SNAPSHOT_MAX_MB
         }
         catch (e) {
+            if (e instanceof AdoptionError)
+                throw e;
             throw new Error(`DB_BACKEND=local cannot open data dir ${root}: ${e instanceof Error ? e.message : String(e)} ` +
                 "(another HTTP service / run-local instance may own it; stop it first or set LOCAL_DATA_ROOT to a free dir)");
         }
@@ -235,6 +253,10 @@ class LocalBackend {
         this.sendFileLedgerStore.dispose(); // release the sendfile-ledger append fd (lazy — may never have opened)
         this.workflowJournalStore.dispose(); // release the per-run journal-ledger fds
         this.checkpointStoreInst?.close(); // release the checkpoint ledger fd (lazy, may never have been built)
+        // #203 §1: release core's permission-rule DIRECTORY write lock (lazy — may never have been built).
+        // Same discipline as root/LOCK below: an un-released writer lock tells the next boot that a live process
+        // owns the rule directory, and core refuses the second holder LOUDLY rather than queueing.
+        this.permissionRuleStoresInst?.dispose();
         await this.fileBackend.dispose(); // MUST release root/LOCK so a graceful restart can re-acquire the data dir
     }
     run() { return this.runStore; }
@@ -244,9 +266,22 @@ class LocalBackend {
      *  new 一个就等于每个消费者各拿一份互不可见的账(而 SQL twin 天然共享一张表)。易失代价 +
      *  「local 车道默认不上协议」的裁定见 StoreBackend.approvalAsk() 的接口注。 */
     approvalAsk() { return this.approvalAskStore; }
-    /** #154 车二:local 车道**诚实缺席**(理由逐字见 `StoreBackend.permissionRule()` 的接口注:
-     *  一个会在重启时遗忘授权的规则店,在放宽面上比没有店更坏)。 */
-    permissionRule() { return undefined; }
+    /** #203 §1:local 车道的 File 三面束。**必须**是 singleton —— core 的 File provider 在第一次取写面时
+     *  对规则目录取一把进程级写锁,第二个持有者被**响亮拒绝**(不是排队),所以每次 `new` 一个就等于给
+     *  自己造一次「另一个进程占着这个目录」的假象。`close()` 里 `dispose()` 释放它(与数据根 `root/LOCK`
+     *  同一条纪律:不释放 ⇒ 优雅重启被自己上一条命留下的锁挡在门外)。惰性建:没开旋钮的部署不该因为
+     *  一个从不使用的面而在数据根里长出目录、更不该白占一把写锁。 */
+    permissionRule() {
+        if (!this.permissionRuleStoresInst) {
+            this.permissionRuleStoresInst = createFilePermissionRuleStores(this.fileBackend.root, {
+                // core 规则文件的披露面(读不出 / 校验和不符 / 撞上符号链接 ⇒ 答零规则**并说出来**)。
+                // 不接住它就是一次静默的 fail-closed:用户突然被反复询问,而日志里一个字都没有。
+                onError: (message) => this.onWarn?.("permission_rule_store_disclosure", { message }),
+            });
+        }
+        return this.permissionRuleStoresInst;
+    }
+    permissionRuleStoresInst;
     sendFileLedger() { return this.sendFileLedgerStore; } // singleton — append fd lives in the instance
     /** Durable HITL / plan-review parking on the LOCAL lane. Lazy singleton (the inner core store holds
      *  an append fd). taskId join ← FileRunStore; E21 owner guard ← LocalSessionStore.ownerOf (same root). */
@@ -302,10 +337,14 @@ export function counterStoreLabel(store, kind) {
     return store ? `shared(${kind ?? "unknown"})` : "in-process";
 }
 /** Build the durable-store backend for `config.dbBackend`. Does NOT connect (the pool connects lazily; the
- *  reachability probe is the caller's first `ensureSchema`). Returns undefined when no DB is configured. */
-export function createStoreBackend(config) {
+ *  reachability probe is the caller's first `ensureSchema`). Returns undefined when no DB is configured.
+ *
+ *  `onWarn` (additive, optional) is the boot-time warning sink the LOCAL backend needs for core's
+ *  permission-rule DISCLOSURE face (#203 §1): an unreadable / checksum-mismatched / symlinked rule file
+ *  answers ZERO rules and says so — swallowing that turns a fail-closed degrade into a silent one. */
+export function createStoreBackend(config, onWarn) {
     if (config.dbBackend === "local")
-        return new LocalBackend(config.localDataRoot ?? join(homedir(), ".ai-agent"), config);
+        return new LocalBackend(config.localDataRoot ?? join(homedir(), ".ai-agent"), config, onWarn);
     if (config.dbBackend === "pg") {
         if (!config.pg)
             return undefined;
@@ -335,12 +374,22 @@ export async function openStoreBackendWithFallback(config, logger) {
     const mayFallback = config.dbBackend === "local" ? !config.dbBackendExplicit : config.sessionBackend === "auto";
     let backend;
     try {
-        backend = createStoreBackend(config);
+        // 包一层箭头而不是直接传 `logger.warn`:后者会把方法从它的接收者上摘下来,一个带 `this` 的
+        // logger 实现会在第一次真披露时炸——而那一刻正是最不该炸的时候(本仓 fail-loud 病族先例)。
+        backend = createStoreBackend(config, (msg, meta) => logger.warn(msg, meta));
         // connects + creates schema (also the reachability probe).
         if (backend)
             await backend.ensureSchema();
     }
     catch (err) {
+        // 🔴 core 5.23.0([3372] 提货批,codex 复审 high 抓获、验真后修):**I6 adoption 门不许被降级臂吃掉**。
+        // 1.292 拍的降级裁定说的是「只读 FS / mkdir 失败」那一类——它们的意思是「这台机器存不了盘」,降级到
+        // 内存是诚实的等价物。`AdoptionError` 说的是完全不同的一句话:「这份数据**有主、正在搬**」(design/183
+        // I6:数据根的 `adoption.json` 在飞,或标记读不出)。对后者降级 = **在搬家途中另开一个写者**,而那正是
+        // I6 门存在的全部理由;更坏的是它还会留下一行「DB 不可达」的 warn,把运维支去查连通性。
+        // ⇒ 与显式 DB_BACKEND 同待遇:无条件 fail-loud,穿过 `mayFallback`。
+        if (err instanceof AdoptionError)
+            throw err;
         if (!mayFallback)
             throw err;
         // S5 (SILENT-FALLBACK P0-b): one boot warn was the ONLY trace of "this replica is not persisting".