@sema-agent/server 7.43.0 → 7.44.0

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

@@ -1,62 +1,8 @@
-/**
- * #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(),
@@ -74,20 +20,13 @@ const ApprovalRecordSchema = z
     createdAt: z.string(),
     toolCallId: z.string().optional(),
     boundInputHash: z.string().optional(),
+    command: z.string().optional(),
+    edited: z.object({ index: z.number().int().nonnegative().safe(), text: z.string(), at: z.string() }).strict().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,
@@ -99,6 +38,8 @@ function toApprovalRecord(row) {
         createdAt: row.createdAt,
         ...(row.toolCallId !== undefined ? { toolCallId: row.toolCallId } : {}),
         ...(row.boundInputHash !== undefined ? { boundInputHash: row.boundInputHash } : {}),
+        ...(row.command !== undefined ? { command: row.command } : {}),
+        ...(row.edited !== undefined ? { edited: row.edited } : {}),
         rev: row.rev,
         ...(row.selectedCandidate !== undefined ? { selectedCandidate: row.selectedCandidate } : {}),
         ...(row.redeemedDots !== undefined
@@ -106,12 +47,10 @@ function toApprovalRecord(row) {
             : {}),
     };
 }
-/** 审批记录日志的一行:整条记录的快照(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({
@@ -126,10 +65,6 @@ const TicketLineSchema = z.union([
     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;
@@ -140,7 +75,6 @@ class CorruptionGate {
         this.path = path;
         this.onError = onError;
     }
-    /** 记一次内部损坏(幂等:第一条原因就是要报告的那条)。 */
     trip(reason) {
         this.reason ??= reason;
         this.onError?.(`${this.face} at ${this.path} is corrupt: ${reason}`);
@@ -148,7 +82,6 @@ class CorruptionGate {
     get tripped() {
         return this.reason !== undefined;
     }
-    /** 每个方法的第一行。文案里带上文件路径与处置 —— 一个运维读到它要知道去看哪个文件。 */
     assertUsable() {
         if (this.reason === undefined)
             return;
@@ -156,12 +89,6 @@ class CorruptionGate {
             "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;
@@ -170,12 +97,9 @@ export class FileRuleApprovalRecordStore {
         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;
             }
@@ -186,29 +110,22 @@ export class FileRuleApprovalRecordStore {
         }
         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.log.append({ op: "put", record }, true);
         this.rows.set(record.id, structuredClone(record));
     }
     async cas(id, expectRev, next) {
@@ -223,8 +140,6 @@ export class FileRuleApprovalRecordStore {
         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);
@@ -235,10 +150,6 @@ export class FileRuleApprovalRecordStore {
         return true;
     }
 }
-/**
- * CC 导入票的 File 形。四条信任边界(principal 绑定 / TTL / 一次性原子消费 / 载荷绑定)与 SQL 形
- * **同语义**;唯一不同的是「原子」由谁保证 —— 那边是引擎行锁,这边是单进程 + 单写者(顶注)。
- */
 export class FileRuleImportTicketStore {
     rows = new Map();
     log;
@@ -248,8 +159,6 @@ export class FileRuleImportTicketStore {
         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) {
@@ -272,28 +181,20 @@ export class FileRuleImportTicketStore {
         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, opts) {
         this.gate.assertUsable();
         const row = this.rows.get(ticketId);
@@ -303,7 +204,6 @@ export class FileRuleImportTicketStore {
             return { ok: false, reason: "wrong-principal" };
         if (row.consumedAtMs !== undefined)
             return { ok: false, reason: "consumed" };
-        // [4232]③:判定钟(可被同意车道的单调锚覆写)与记账钟(恒真墙钟,写进日志/行)分家 —— 逐字同 SQL 形。
         const stampMs = this.now();
         if (row.expiresAtMs <= (opts?.decisionNowMs ?? stampMs))
             return { ok: false, reason: "expired" };
@@ -311,8 +211,6 @@ export class FileRuleImportTicketStore {
         row.consumedAtMs = stampMs;
         return { ok: true, approvalId: row.approvalId, payloadHash: row.payloadHash };
     }
-    /** 把认领**放回去**。`mustRemainValidMs` = 放回之后至少还要能用多久 —— 撑不过就不算放回成功
-     *  (理由逐字见 SQL 侧 `release` 的头注:承诺一次必然兑现不了的重试比不承诺更坏)。 */
     async release(ticketId, principal, mustRemainValidMs = 0, opts) {
         this.gate.assertUsable();
         const row = this.rows.get(ticketId);
@@ -325,43 +223,17 @@ export class FileRuleImportTicketStore {
         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();

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

@@ -34,6 +34,9 @@ export declare const TIDB_PERMISSION_RULE_STATEMENTS: readonly string[];
 /** {@link TIDB_PERMISSION_RULE_STATEMENTS} 的遍历壳(生产路径走 `tidb-pool.ts` 中央 `ensureSchema`;
  *  本函数留给只需要这三张表的集成测试)。 */
 export declare function ensureTiDBPermissionRuleSchema(pool: MySqlPool): Promise<void>;
+export declare function assertPermissionRuleApprovalSchema(query: (sql: string) => Promise<{
+    rows: Record<string, unknown>[];
+}>, dialect: "tidb" | "pg"): Promise<void>;
 export declare function ensurePgPermissionRuleSchema(q: PgQueryFn): Promise<void>;
 /**
  * 一只桶的**存储键**(纯数据 ⇒ `build*`)。