@sema-agent/server 7.10.0 → 7.12.0

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

@@ -0,0 +1,83 @@
+import { FilePermissionRuleStoreProvider, type RuleApprovalRecord, type RuleApprovalRecordStore, type RuleScope } from "@sema-agent/core";
+import { type RuleImportTicket, type RuleTicketRedeemResult } from "./permission-rule-store-sql.js";
+import type { PermissionRuleStoreBundle } from "../rules-consent.js";
+/**
+ * `RuleApprovalRecordStore` 的 File 形。
+ *
+ * CAS 按 `rev`(core 硬条款,理由逐字见 SQL 侧同名类的头注:只比 state 会让批记录的第二个候选上两次
+ * 并发重试都以为自己赢了)。
+ */
+export declare class FileRuleApprovalRecordStore implements RuleApprovalRecordStore {
+    private readonly rows;
+    private readonly log;
+    private readonly gate;
+    constructor(dir: string, onError?: (message: string) => void);
+    /** 取证/自证用:本面是否因内部损坏而 fail-closed。 */
+    get corrupt(): boolean;
+    /** 归还本面 eager 持有的日志描述符(束的 `dispose()` 唯一调用点)。`AppendLog` 上没有 finalizer,
+     *  不显式关就是一只跟到进程末尾的 fd —— `LocalBackend` 反复开合(热重载/多根)时按次泄漏。
+     *  关后写面抛 `log_closed`(core 语义):**不重开**,因为「这只店已经交还」与「这条命还能写」
+     *  不能两立,静默重开会让一次 dispose 之后的写落进一份没人再读的日志。 */
+    close(): void;
+    get(id: string): Promise<RuleApprovalRecord | undefined>;
+    create(record: RuleApprovalRecord): Promise<void>;
+    cas(id: string, expectRev: number, next: RuleApprovalRecord): Promise<boolean>;
+    /** 与 SQL 侧同名方法同义(超帽拒绝时收掉 `prepareCcImport` 已落盘的那条 pending 记录)。
+     *  `state === "pending"` 是硬的:已确认/已兑付的记录是一次真人同意的审计事实。 */
+    discardPendingRecord(recordId: string): Promise<boolean>;
+}
+/**
+ * CC 导入票的 File 形。四条信任边界(principal 绑定 / TTL / 一次性原子消费 / 载荷绑定)与 SQL 形
+ * **同语义**;唯一不同的是「原子」由谁保证 —— 那边是引擎行锁,这边是单进程 + 单写者(顶注)。
+ */
+export declare class FileRuleImportTicketStore {
+    private readonly rows;
+    private readonly log;
+    private readonly gate;
+    constructor(dir: string, now?: () => number, onError?: (message: string) => void);
+    private readonly now;
+    /** 取证/自证用:本面是否因内部损坏而 fail-closed。 */
+    get corrupt(): boolean;
+    /** 归还本面 eager 持有的日志描述符(理由与姊妹面 {@link FileRuleApprovalRecordStore.close} 逐字同源)。 */
+    close(): void;
+    mint(input: {
+        ticketId: string;
+        principal: string;
+        approvalId: string;
+        candidates: ReadonlyArray<{
+            rule: string;
+            scope: RuleScope;
+        }>;
+        ttlMs: number;
+    }): Promise<RuleImportTicket>;
+    /** 一次性**认领**。四条否定项的判序与 SQL 形逐字相同(unknown → wrong-principal → consumed → expired),
+     *  于是两形的服务端日志归因可比;wire 面把四类折成同一个 404(零存在性 oracle)。 */
+    consume(ticketId: string, principal: string): Promise<RuleTicketRedeemResult>;
+    /** 把认领**放回去**。`mustRemainValidMs` = 放回之后至少还要能用多久 —— 撑不过就不算放回成功
+     *  (理由逐字见 SQL 侧 `release` 的头注:承诺一次必然兑现不了的重试比不承诺更坏)。 */
+    release(ticketId: string, principal: string, mustRemainValidMs?: number): Promise<boolean>;
+}
+/** local 车道的三面束 + 生命周期。`dispose()` 释放 core File provider 的写锁(见 {@link createFilePermissionRuleStores})。 */
+export interface FilePermissionRuleStores extends PermissionRuleStoreBundle {
+    provider: FilePermissionRuleStoreProvider;
+    approvals: FileRuleApprovalRecordStore;
+    tickets: FileRuleImportTicketStore;
+    dispose(): void;
+}
+/**
+ * 装配 local 三面束。
+ *
+ * 🔴 `provider` 必须是**单例**(F1):core 的 `FilePermissionRuleStoreProvider` 在第一次取写面时对规则
+ * 目录取一把进程级写锁,每次 `new` 一个就是第二个持有者 —— 而它对第二个持有者是**响亮拒绝**,不是
+ * 排队。所以束在 `LocalBackend` 上按字段持有,`LocalBackend.close()` 调 `dispose()` 释放
+ * (不释放 ⇒ 一次优雅重启会被自己上一条命留下的锁挡在门外,与数据根 `root/LOCK` 同一个病)。
+ *
+ * `onError` 接的是 core 规则文件的**披露面**(读不出来 / 校验和不符 / 撞上符号链接时它答零规则并
+ * 说出来)。接住它打一条 warn 是**必须**的:那条路径上「零规则」与「真的没有规则」在读面上同形,
+ * 不留痕就变成一次静默的 fail-closed(用户会突然被反复询问,却没有任何线索)。
+ */
+export declare function createFilePermissionRuleStores(root: string, opts?: {
+    onError?: (message: string) => void;
+    now?: () => number;
+}): FilePermissionRuleStores;
+//# sourceMappingURL=permission-rule-store-file.d.ts.map

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