@sema-agent/server 7.55.0 → 7.57.0

package/deploy/sema-up/chart/values.yaml

@@ -77,7 +77,7 @@ registry:
   nodePort: 30300
   storageSize: 2Gi
   storageClass: ""     # 空=集群默认 SC
-  # [4824] S10 P1:默认管理员名必须是中性值——个人标识串作生产默认值=内部标识外溢(cli 点名案)。
+  # 默认管理员名必须是中性值——个人标识串作生产默认值=内部标识外溢(cli 点名案)。
   adminUser: admin
   adminPassword: ""    # REQUIRED(kube-up 注入)
   sessionSecret: ""    # REQUIRED

package/dist/approval-ask-audit-store.d.ts

@@ -28,13 +28,49 @@ export interface AuditSettleInput {
     settledBy?: string;
     settledAtMs: number;
 }
+/**
+ * [ref] **迟到人工结算点**入参:调用方(两条 HTTP decide 腿)只交 **checkpoint 锚 + 这次结算的事实**,
+ * `approvalId` 的反查与「算不算迟到」的判据**属主在店内**(一处成文,见 {@link FileApprovalAskAuditStore.recordLateSettle})
+ * —— 路由层没有账本索引,让它自己推会造出第二份判据。
+ */
+export interface AuditLateSettleInput {
+    /** checkpoint 锚①:被决议那条 durable 行的 sessionId(`/v1/approvals/:sessionId/decide` 的那把;
+     *  parked 子代形下 = **子会话 id**,与 ask 行的 `sourceTaskId` 同值)。 */
+    sessionId: string;
+    /** checkpoint 锚②:`pendingAction.toolCallId`(tool_approval 门恒在场;别的审批门型可缺席)。 */
+    toolCallId?: string;
+    /** checkpoint 锚③:resume 凭据的**哈希**({@link buildCheckpointAnchorHash};token 本身是 token-as-auth
+     *  的能力凭据,**绝不**落审计盘 —— 账本 0o600 也不是把凭据写进去的理由)。 */
+    checkpointTokenHash?: string;
+    /** 这次人工结算的结果(approve/deny 逐字映射;`expired` 不是本记录的合法值 —— 它是流窗的词)。 */
+    outcome: "allowed" | "denied";
+    /** core `ApprovalSettledBy` 逐字(调用方给,店**不派生**:集中推导正是「窗到期被报成另一个人拒绝」
+     *  的成因,[ref] 件6③ 同律)。今天两条腿恒 `"human"`,但真值以调用方为准。 */
+    settledBy: string;
+    /** 记录时刻 = 那条腿**权威受理**的时刻(不是请求到达的时刻)—— 落行点在 200 之后,见记录种类表。 */
+    settledAtMs: number;
+}
 /** 协调器消费的窄写口(协调器只 import type,不拖实现依赖)。 */
 export interface ApprovalAskAuditSink {
     recordAsk(input: AuditAskInput): void;
     recordSettle(input: AuditSettleInput): void;
     /** 腿闭点(`runWithContext` finally)。只为铸过审计行的 taskId 真落行(店内去重)。 */
     noteLegClosed(taskId: string): void;
+    /** [ref] 迟到人工结算点(HTTP decide 两腿)。**纯观察**:自吞一切失败,不返回受否,绝不改变结算面。 */
+    recordLateSettle(input: AuditLateSettleInput): void;
 }
+/**
+ * [ref]:decide 两腿消费的**更窄写口** —— 只有迟到结算这一个动词。
+ * 刻意不把整个 {@link ApprovalAskAuditSink} 递给 HTTP 层:铸造 / 决议 / 腿闭三点的属主是协调器,
+ * 路由层拿到它们只会长出第二个写者(与 {@link ApprovalAskAuditReadFace} 同一条窄口纪律)。
+ */
+export type ApprovalLateSettleSink = Pick<ApprovalAskAuditSink, "recordLateSettle">;
+/**
+ * checkpoint resume 凭据 → 审计行可落的锚(sha256 前 16 hex)。
+ * 单向、不可逆、不足以拿去 resume;够用来把审计行 join 回 checkpoint 平面(取证时对手上的 token 现算)。
+ * 形与长度的唯一属主在此(两条腿都调它,不各自 `createHash`)。
+ */
+export declare function buildCheckpointAnchorHash(token: string): string;
 /** v1.1 §6 两分臂(闭集)。 */
 export type CrashOrphanState = "pending" | "decided";
 /** `GET /v1/approvals` additive 键 `crashConverged` 的行形(wire 键集刻意窄:args/卡体不上列表,
@@ -63,6 +99,15 @@ export interface CrashConvergedRow {
 export interface ApprovalAskAuditReadFace {
     listCrashConverged(scope: string | undefined): CrashConvergedRow[];
 }
+/**
+ * [ref]:`late_settle` 行上 `approvalId === null` 的**成因词**(闭集;缺席 = 反查唯一命中,身份是真的)。
+ * 「反查不到不得静默」:身份说不清的时候写的是「说不清 + 为什么」,不是不写、也不是编一个 id。
+ * 闭集纪律([ref] + 本店 `crash_converged.orphanState` 先例):重放读到**词表外**的值 ⇒ 整行折坏行计数,
+ * 不折 `undefined` —— 折了就等于把「说不清且原因是 X」静默降级成「说不清、没原因」。
+ * 与身份字段的**交叉不变式**(写口自带,重放侧同样强制):`approvalId === null` ⇔ 本词在场;身份说不清
+ * 时 `taskId` 必须缺席(挑一条铸造行填 = 张冠李戴)。
+ */
+export type LateSettleUnresolved = "ambiguous_anchor";
 export declare class FileApprovalAskAuditStore implements ApprovalAskAuditSink, ApprovalAskAuditReadFace {
     /** 账本绝对路径(测试/取证按文件字节对账 —— 崩溃语义的真源是文件,不是内存投影)。 */
     readonly ledgerPath: string;
@@ -83,6 +128,21 @@ export declare class FileApprovalAskAuditStore implements ApprovalAskAuditSink,
     /** 本进程铸过审计行、且腿闭信号可达的 taskId(腿闭去重 + 防无关腿刷账本)。 */
     private readonly openLegTasks;
     private convergedOnce;
+    /**
+     * [ref] 反查索引 ①:**checkpoint 锚 → 铸造行身份**。与 {@link replayed} 刻意分家 —— 那张表是
+     * 「前世账本」快照(收敛只对前世行),而迟到决议要认的是**前世 + 本进程**两段账(人可以在重启前批,
+     * 也可以在重启后批)。键形 = {@link FileApprovalAskAuditStore.callAnchorKey}(会话轴的两把键见
+     * {@link FileApprovalAskAuditStore.indexAsk});弱桶另见下一个字段。
+     */
+    private readonly askByCallAnchor;
+    /** [ref] 反查索引 ①b:**无 toolCallId** 的铸造行(只能按会话认);与 A 桶分开是为了不让「有 callId 的
+     *  锚」误命中「另一只没写 callId 的 ask」—— 归并会把两条不同的 ask 折成一条。 */
+    private readonly askBySessionOnly;
+    /** [ref] 反查索引 ②:走过 park 路由的窗到期(`settle{outcome:"expired", parkRouted:true}`)——
+     *  「这次决议算不算迟到」的**唯一**判据来源。 */
+    private readonly parkExpired;
+    /** [ref] 反查索引 ③:approvalId → 铸造坐标(命中后回填 late 行的 `taskId`)。 */
+    private readonly askTaskId;
     /**
      * boot 期 fail-stop:mkdir/重放失败**拒启**(File 店族同律)。root = local 数据根
      * (`config.localDataRoot`;与 `LocalBackend` 同源,见头注装配段)。
@@ -103,11 +163,50 @@ export declare class FileApprovalAskAuditStore implements ApprovalAskAuditSink,
     private group;
     /** append + fsync(逐行落盘:进程猝死不丢已记的行 —— 本店的全部价值就在崩溃时刻)。
      *  运行期失败**响亮不阻断**:审批可用性不押在审计盘上(盘满/只读时人还得能批),但丢行必须在遥测
-     *  显形([ref] 三件套,census 登记行同批)。 */
+     *  显形([ref] 三件套,census 登记行同批)。
+     *  🔴 返回**这条记录是否真的落盘并 fsync 成功**([ref] codex R1-F2 采):迟到结算的 late 判据只认
+     *  落了盘的前置事实 —— 调用方据此决定要不要把这条记录喂进反查索引(见 {@link recordAsk}/
+     *  {@link recordSettle})。没有这个返回值,索引会把一条**只在内存里**的 ask/park 事实当证据,
+     *  后来铸出的 `late_settle` 行在同一个账本文件里无法复核。 */
     private append;
+    /** [ref] 锚键 A(精确):会话 + 工具调用 id。会话轴登记**两把** —— 见 {@link indexAsk}。 */
+    private static callAnchorKey;
+    /**
+     * [ref]:把一条铸造行放进反查索引。
+     * 会话轴登记 `sessionId` 与 `sourceTaskId` **两把**:parked 后台子代的 checkpoint 上
+     * `cp.sessionId` 是**子会话 id**(= ask 行的 `sourceTaskId`),而 ask 行的 `sessionId` 是**宿主**
+     * 会话(铸造点取的是 `origin.sessionId`,继承链闭包携宿主身份)—— 只登记一把会让委派子代那条腿
+     * 的迟到决议恒反查不到。顶层 run 上两者同值,登记去重后是同一把。
+     */
+    private indexAsk;
+    /** [ref]:决议行进 late 判据索引(只认 `expired ∧ parkRouted` —— 别的终局都不是「转 durable 等人」)。 */
+    private indexSettle;
     recordAsk(input: AuditAskInput): void;
     recordSettle(input: AuditSettleInput): void;
     noteLegClosed(taskId: string): void;
+    /**
+     * [ref] **迟到人工结算点**(判据的唯一属主;两条 HTTP decide 腿只交锚,不自己推)。
+     *
+     * 三步:
+     *  1. **反查**:checkpoint 锚 → 铸造行身份。**锚带 `toolCallId` 时,`(会话, toolCallId)` 精确桶是
+     *     唯一权威**;两侧都没有调用锚时才退到会话弱桶(= 该会话下没写 toolCallId 的铸造行)。会话轴
+     *     登记两把(宿主会话 / 子会话,见 {@link indexAsk})。
+     *     🔴 **弱桶绝不与精确桶合并**(codex R1-F3 采,两条真路径):①同会话有一条**无调用锚**的历史
+     *     park 行、而本次决的那只 checkpoint 从未在本账本留过铸造行(headless park / 换过账本,头注明写
+     *     这是合法形)⇒ 合并后唯一候选是那条历史行,行会写成「approvalId/taskId = 历史那只、toolCallId =
+     *     这一只」的自相矛盾审计行;②精确唯一命中被同会话弱候选拖成假 `ambiguous_anchor`,一个**本可
+     *     确定**的身份被降级。弱证据不足以证明「这一次决的就是它」,证不出就不写(步骤 2 同一条纪律)。
+     *  2. **late 门**:候选里筛出账本已有 `settle{outcome:"expired", parkRouted:true}` 的那些。
+     *     筛空 ⇒ **一行不写**。理由是不编事实:证不出「窗到期已转 durable」,这次决议就只是一次普通的
+     *     durable decide(headless 提交的 park、SQL 车道搬来的账本、或本店根本没记过这只 ask),
+     *     写 `lateAfterExpiry:true` 会把推断当成事实上账 —— 那比缺一行更坏(审计行是要被当证据引的)。
+     *  3. **落行**:唯一命中 ⇒ 带真 `approvalId` + 铸造 `taskId`;多条同锚命中 ⇒ `approvalId:null` +
+     *     `unresolved:"ambiguous_anchor"`(**不静默**:身份说不清照样留行,锚全在行上给人去 join)。
+     *
+     * 纯观察:自吞一切失败(append 的响亮留痕在 {@link append} 里),不返回受否 —— 结算面绝不因审计写不动
+     * 而改变(与 `recordAsk`/`recordSettle` 同姿态,裁 (c) 的行为面红线)。
+     */
+    recordLateSettle(input: AuditLateSettleInput): void;
     /**
      * boot 崩溃收敛器(装配层在构造后、协调器开始服务前调一次;幂等跨 boot)。
      * 判据 = 头注「boot 收敛判据」段(一处成文,不复述)。返回两分臂计数 + 坏行数供 boot 日志。

package/dist/approval-ask-audit-store.js

@@ -1,8 +1,12 @@
+import { createHash } from "node:crypto";
 import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, writeSync } from "node:fs";
 import { join } from "node:path";
 import { recordFailOpen } from "./observability/fail-open.js";
 export const APPROVAL_ASK_AUDIT_DIR = "approval-ask-audit";
 export const CRASH_CONVERGED_LIST_MAX = 200;
+export function buildCheckpointAnchorHash(token) {
+    return createHash("sha256").update(token, "utf8").digest("hex").slice(0, 16);
+}
 function readLedgerRecord(u) {
     if (u === null || typeof u !== "object" || Array.isArray(u))
         return undefined;
@@ -75,6 +79,43 @@ function readLedgerRecord(u) {
                 return undefined;
             return { kind: "crash_converged", approvalId, orphanState, convergedAtMs };
         }
+        case "late_settle": {
+            const idV = o.approvalId;
+            const approvalId = typeof idV === "string" ? idV : idV === null ? null : undefined;
+            const outcomeV = o.outcome;
+            const outcome = outcomeV === "allowed" || outcomeV === "denied" ? outcomeV : undefined;
+            const settledBy = s("settledBy");
+            const settledAtMs = num("settledAtMs");
+            const sessionId = s("sessionId");
+            if (approvalId === undefined || outcome === undefined || settledBy === undefined || settledAtMs === undefined || sessionId === undefined)
+                return undefined;
+            if (bool("lateAfterExpiry") !== true)
+                return undefined;
+            const toolCallId = s("toolCallId");
+            const checkpointTokenHash = s("checkpointTokenHash");
+            const taskId = s("taskId");
+            const unresolvedV = o.unresolved;
+            if (unresolvedV !== undefined && unresolvedV !== "ambiguous_anchor")
+                return undefined;
+            const unresolved = unresolvedV === "ambiguous_anchor" ? "ambiguous_anchor" : undefined;
+            if ((approvalId === null) !== (unresolved !== undefined))
+                return undefined;
+            if (approvalId === null && taskId !== undefined)
+                return undefined;
+            return {
+                kind: "late_settle",
+                approvalId,
+                outcome,
+                settledBy,
+                lateAfterExpiry: true,
+                settledAtMs,
+                sessionId,
+                ...(toolCallId !== undefined ? { toolCallId } : {}),
+                ...(checkpointTokenHash !== undefined ? { checkpointTokenHash } : {}),
+                ...(taskId !== undefined ? { taskId } : {}),
+                ...(unresolved !== undefined ? { unresolved } : {}),
+            };
+        }
         default:
             return undefined;
     }
@@ -89,6 +130,10 @@ export class FileApprovalAskAuditStore {
     convergedRows = [];
     openLegTasks = new Set();
     convergedOnce = false;
+    askByCallAnchor = new Map();
+    askBySessionOnly = new Map();
+    parkExpired = new Set();
+    askTaskId = new Map();
     constructor(root, internals) {
         this.writeBytes = internals?.writeBytes ?? ((fd, buf, off, len) => writeSync(fd, buf, off, len));
         const dir = join(root, APPROVAL_ASK_AUDIT_DIR);
@@ -133,6 +178,7 @@ export class FileApprovalAskAuditStore {
                         g.ask = rec;
                         g.askLine = line;
                     }
+                    this.indexAsk(rec);
                     break;
                 }
                 case "settle": {
@@ -141,8 +187,11 @@ export class FileApprovalAskAuditStore {
                         g.settle = rec;
                         g.settleLine = line;
                     }
+                    this.indexSettle(rec);
                     break;
                 }
+                case "late_settle":
+                    break;
                 case "leg_closed":
                     this.replayedLegClosed.push({ taskId: rec.taskId, line });
                     break;
@@ -183,19 +232,48 @@ export class FileApprovalAskAuditStore {
             while (off < buf.length)
                 off += this.writeBytes(this.fd, buf, off, buf.length - off);
             fsyncSync(this.fd);
+            return true;
         }
         catch (err) {
             this.tailDirty = true;
             recordFailOpen("server.approval-ask-audit.append-failed", `kind=${rec.kind} err=${err instanceof Error ? err.message : String(err)}`);
+            return false;
+        }
+    }
+    static callAnchorKey(session, toolCallId) {
+        return `${session}\u0000${toolCallId}`;
+    }
+    indexAsk(rec) {
+        this.askTaskId.set(rec.approvalId, rec.taskId);
+        const sessions = new Set();
+        if (rec.sessionId !== undefined)
+            sessions.add(rec.sessionId);
+        if (rec.sourceTaskId !== undefined)
+            sessions.add(rec.sourceTaskId);
+        for (const session of sessions) {
+            const bucket = rec.toolCallId !== undefined ? this.askByCallAnchor : this.askBySessionOnly;
+            const key = rec.toolCallId !== undefined ? FileApprovalAskAuditStore.callAnchorKey(session, rec.toolCallId) : session;
+            let ids = bucket.get(key);
+            if (!ids) {
+                ids = new Set();
+                bucket.set(key, ids);
+            }
+            ids.add(rec.approvalId);
         }
     }
+    indexSettle(rec) {
+        if (rec.outcome === "expired" && rec.parkRouted === true)
+            this.parkExpired.add(rec.approvalId);
+    }
     recordAsk(input) {
         if (input.legTracked)
             this.openLegTasks.add(input.taskId);
-        this.append({ kind: "ask", ...input });
+        if (this.append({ kind: "ask", ...input }))
+            this.indexAsk(input);
     }
     recordSettle(input) {
-        this.append({ kind: "settle", ...input });
+        if (this.append({ kind: "settle", ...input }))
+            this.indexSettle(input);
     }
     noteLegClosed(taskId) {
         if (!this.openLegTasks.has(taskId))
@@ -203,6 +281,29 @@ export class FileApprovalAskAuditStore {
         this.openLegTasks.delete(taskId);
         this.append({ kind: "leg_closed", taskId, closedAtMs: Date.now() });
     }
+    recordLateSettle(input) {
+        const candidates = input.toolCallId !== undefined
+            ? (this.askByCallAnchor.get(FileApprovalAskAuditStore.callAnchorKey(input.sessionId, input.toolCallId)) ?? new Set())
+            : (this.askBySessionOnly.get(input.sessionId) ?? new Set());
+        const parked = [...candidates].filter((id) => this.parkExpired.has(id));
+        if (parked.length === 0)
+            return;
+        const only = parked.length === 1 ? parked[0] : undefined;
+        const taskId = only !== undefined ? this.askTaskId.get(only) : undefined;
+        this.append({
+            kind: "late_settle",
+            approvalId: only ?? null,
+            outcome: input.outcome,
+            settledBy: input.settledBy,
+            lateAfterExpiry: true,
+            settledAtMs: input.settledAtMs,
+            sessionId: input.sessionId,
+            ...(input.toolCallId !== undefined ? { toolCallId: input.toolCallId } : {}),
+            ...(input.checkpointTokenHash !== undefined ? { checkpointTokenHash: input.checkpointTokenHash } : {}),
+            ...(taskId !== undefined ? { taskId } : {}),
+            ...(only === undefined ? { unresolved: "ambiguous_anchor" } : {}),
+        });
+    }
     convergeCrashedAsks() {
         if (this.convergedOnce)
             return { pending: 0, decided: 0, inconsistent: 0, corruptLines: this.corruptLines };

package/dist/approval-card.d.ts

@@ -49,30 +49,76 @@ export declare const MAX_RULE_OFFERS = 4;
  * 几条规则),混成一个数会让「上游把 batch 放宽到 6 条成员」误伤到 offer 条数这条无关轴。
  */
 export declare const MAX_RULE_OFFER_BATCH_MEMBERS = 8;
+/**
+ * **一条**「不再询问」OFFER 的形(core 5.58.0 / [ref] §3.1 —— **BREAKING**,取代退役的
+ * `RuleSuggestion`)。同步腿(`ApprovalCardSchema.ruleOffers` / `card_json`)与耐久腿(durable park 行的
+ * `PendingCheckpoint.ruleOffers`,由 `plugins/checkpoint-store-sql.ts` 窄读)**共用这一份**。
+ *
+ * 🔴 单一属主(宪法 [ref]「schema 单一属主禁复制」):两条腿投的是 core 的**同一个** `RuleOffer`
+ * (同步腿 = `AskRequest.ruleOffers`,耐久腿 = `PendingAction.ruleOffers`,core
+ * `checkpoint-store.d.ts` 明写「CONTRACT (same as the synchronous `AskRequest.ruleOffers`)」)。
+ * 各写一份 zod 必然漂——闭词表 `match`/`kind` 加词、上限改口径,只改一处就出两种形。
+ *
+ * 🔴 **闭集判别联合,`kind` 是判别位**(core d.ts 逐字:"A CLOSED discriminated union"):
+ *  · `single` —— 一条覆盖**整串**命令的规则(exact 精确形,或简单命令的 reviewed prefix 形);
+ *  · `batch`  —— 复合命令的**逐段合取**批:选它 = **一次对全部 `rules` 说 yes**,批内**无**逐条子选择。
+ *    成员是判别联合([ref] B3:`command` 逐段 Bash 规则 | `directoryRead` cd 段铸的目录只读授权)。
+ *    `uncoveredSegments` 是铸批时刻的**诚实溢出披露**(既不被本批覆盖、也不被卡的覆盖快照覆盖的段数),
+ *    `0` 读作「这批兑完,这条复合命令在那份快照的眼里就全覆盖了」;`uncoveredDetail`(§3.5,additive)
+ *    逐段说**为什么**还没被覆盖(闭三词集),行数恒等于 count(count 是真源,明细缺席不是断言)。
+ *
+ * 🔴 **序即契约**(core 逐字,消费端可以依赖):至多 2 条;whole-string exact single 在场时**恒 index 0**;
+ * batch 至多一条、**恒末位**。所以本仓一切截断都必须是**取前缀**(保序、保原始下标),绝不重排。
+ */
+/**
+ * [ref] §3.5 —— `uncoveredDetail` **行数**的 server 容忍帽(理由与 {@link MAX_RULE_OFFER_BATCH_MEMBERS}
+ * 同源:纯展示轴上的一条改坏/放宽的上游不该把一行撑爆)。⚠️ 超帽的处置是**丢整座**而不是截断:core 契约
+ * 明写「`uncoveredDetail.length === uncoveredSegments` whenever the seat is present」且「count 座是真源、
+ * 明细缺席不是断言」——截过的座会让一个按契约校验等式的消费端把整只 batch 判假,缺席则只是少一行解释。
+ */
+export declare const MAX_UNCOVERED_DETAIL_ROWS = 32;
 export declare const RuleOfferSchema: z.ZodUnion<readonly [z.ZodObject<{
     kind: z.ZodLiteral<"single">;
     rule: z.ZodString;
     match: z.ZodEnum<{
         exact: "exact";
         prefix: "prefix";
+        wildcard: "wildcard";
+        subpath: "subpath";
     }>;
     command: z.ZodString;
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"batch">;
-    rules: z.ZodArray<z.ZodObject<{
+    rules: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        kind: z.ZodLiteral<"command">;
         rule: z.ZodString;
         match: z.ZodEnum<{
             exact: "exact";
             prefix: "prefix";
+            wildcard: "wildcard";
+            subpath: "subpath";
         }>;
         command: z.ZodString;
         segment: z.ZodString;
-    }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"directoryRead">;
+        rule: z.ZodString;
+        directory: z.ZodString;
+        segment: z.ZodString;
+    }, z.core.$strict>]>>;
     uncoveredSegments: z.ZodNumber;
+    uncoveredDetail: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        segment: z.ZodString;
+        reason: z.ZodEnum<{
+            redirection: "redirection";
+            no_rule_form: "no_rule_form";
+            cap_overflow: "cap_overflow";
+        }>;
+    }, z.core.$strict>>>;
 }, z.core.$strict>]>;
 /**
- * {@link RuleOfferSchema} 的**不限长**孪生 —— 只判**结构**(闭词表 `kind`/`match` + 若干字符串),长度由
- * 调用方在**脱敏之后**自己截。
+ * {@link RuleOfferSchema} 的**不限长**孪生 —— 只判**结构**(闭词表 `kind`/`match`/`reason` + 若干字符串),
+ * 长度由调用方在**脱敏之后**自己截。
  *
  * 🔴 为什么必须有它(codex 交叉复审 [medium],验真后修):`redactSecrets` **会变长**(一条
  * `password=…` 换成更长的遮蔽标记)。拿带 `.max()` 的形去校验**脱敏前**的原文,再脱敏,产出的就可能是
@@ -100,7 +146,11 @@ export declare const RuleOfferSchema: z.ZodUnion<readonly [z.ZodObject<{
  * 落库/读回的 {@link ApprovalCardSchema} 仍 `.strict()`(投影只写已知键,多余键根本到不了那一层)。
  *
  * 🔴 **判别联合上的 strip 要逐臂加**(zod 4:`z.union` 自己没有 unknownKeys 政策,政策在成员上)——
- * 两臂各自 `.strip()`,否则 batch 臂对 additive 加键仍是 strict 的,而那正是本注要拆的雷。
+ * 两臂各自 `.strip()`,batch 成员的两臂亦然,否则对 additive 加键仍是 strict 的,而那正是本注要拆的雷。
+ *
+ * 🔴 **闭词表不在放宽之列**([ref] B3 与 [ref] 词表纪律):`kind`(offer 与成员两级)/`match`/`reason`
+ * 是闭集 —— 集外词 = 判假 = 整只 offer 丢(成员级的未知 `kind` 丢的是整只 batch,不是那一个成员;理由见
+ * {@link RuleOfferBatchMemberSchema} 顶注)。「additive 加键照收」与「闭集加词即拒」是两条轴,别混。
  */
 export declare const RuleOfferRawSchema: z.ZodUnion<readonly [z.ZodObject<{
     kind: z.ZodLiteral<"single">;
@@ -108,25 +158,69 @@ export declare const RuleOfferRawSchema: z.ZodUnion<readonly [z.ZodObject<{
     match: z.ZodEnum<{
         exact: "exact";
         prefix: "prefix";
+        wildcard: "wildcard";
+        subpath: "subpath";
     }>;
     command: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{
     kind: z.ZodLiteral<"batch">;
-    rules: z.ZodArray<z.ZodObject<{
+    rules: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        kind: z.ZodLiteral<"command">;
         rule: z.ZodString;
         match: z.ZodEnum<{
             exact: "exact";
             prefix: "prefix";
+            wildcard: "wildcard";
+            subpath: "subpath";
         }>;
         command: z.ZodString;
         segment: z.ZodString;
-    }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"directoryRead">;
+        rule: z.ZodString;
+        directory: z.ZodString;
+        segment: z.ZodString;
+    }, z.core.$strip>]>>;
     uncoveredSegments: z.ZodNumber;
+    uncoveredDetail: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        segment: z.ZodString;
+        reason: z.ZodEnum<{
+            redirection: "redirection";
+            no_rule_form: "no_rule_form";
+            cap_overflow: "cap_overflow";
+        }>;
+    }, z.core.$strip>>>;
 }, z.core.$strip>]>;
+/** {@link RuleOfferRawSchema} 的输出形(结构已判、文本未限长)—— 素材铸点在它上面做派生一致性与座尺两道后判。 */
+export type RuleOfferRaw = z.infer<typeof RuleOfferRawSchema>;
+/**
+ * [ref] §3.5 —— `uncoveredDetail` 明细座的**座级**预筛,两条腿在 {@link RuleOfferRawSchema} 判形之前
+ * 各调一次。
+ *
+ * 为什么要在整体判形之前单独筛这一座:core 明写「ABSENCE(an older minter, a degraded consumer's re-emit)
+ * is not a claim」且 count 座是真源 —— 一座坏掉的明细(集外 reason / 非数组 / 与 count 不等 / 超帽)是
+ * **展示轴**上的损坏,正确处置是「丢这一座、留 batch 本体」;让它把整只 batch 判假会把一条真可兑的合取批
+ * 从卡上抹掉(方向反了:少一行解释是难看,少一只可兑的 offer 是把人的选项吃掉)。
+ * 座被丢**必须留痕**([ref]:F 类 fail-open 走 `recordFailOpen`,计数 + 一次 warn)。
+ * 只做浅层判别(不校验成员、不解构别的键),判形权威仍只有 zod 一处。
+ */
+export declare function screenUncoveredDetailSeat(item: unknown): unknown;
+/**
+ * [ref] B3 的**前一形**:pre-7.2 的 batch 成员没有 `kind`(那一形只有一种成员 —— 逐段 Bash 规则的四键),
+ * 而本仓的耐久腿在 park 行 `pendingAction.ruleOffers` 里**已经落了**这种成员(`checkpoint.rule_suggestions`
+ * 列),同步腿在 core 7.1.0 npm 字节下(本分支落 main 候 7.2.x)收到的也是它。B3 的降级臂说的是「`kind`
+ * 不识 ⇒ 丢整批」;一个**缺席**的 `kind` 不是「不识」——旧形恰好只有一种成员,缺席就是 `command`,零歧义。
+ * 所以这里做的是**已知旧形的 additive 回填**(浅层:仅当成员是对象、无 `kind` 键、且四个文本键在场时补
+ * `kind:"command"`),不是放宽闭集:带着一个陌生 `kind` 值的成员一个字节不动,照旧在 zod 处判假丢整批。
+ * 不回填的代价是真实的:滚动升级窗里,老二进制铸的每一条 park 行在新二进制的读面上整只 batch 消失
+ * (「有供给」谎报成「无供给」,本键存在理由的反面)。
+ */
+export declare function backfillLegacyBatchMemberKind(item: unknown): unknown;
 /**
  * 卡面/帧面共用的 offer **投影型**(= {@link RuleOfferSchema} 的输出形)。判别位 `kind` 上闭集,
- * 消费端(SDK/cli 渲染)按 core 契约分臂;`batch.rules` 成员带 `segment` 渲染座(core 明写
- * 「渲染座、永不参与裁决」,与 rule/command 同为 UNTRUSTED-for-display)。
+ * 消费端(SDK/cli 渲染)按 core 契约分臂;`batch.rules` 成员是判别联合(`command` | `directoryRead`),
+ * 各自带 `segment` 渲染座(core 明写「渲染座、永不参与裁决」,与 rule/command/directory 同为
+ * UNTRUSTED-for-display);`uncoveredDetail` additive 明细座。
  */
 export type RuleOfferProjection = z.infer<typeof RuleOfferSchema>;
 /**
@@ -134,6 +228,11 @@ export type RuleOfferProjection = z.infer<typeof RuleOfferSchema>;
  * 分臂,抽成具名函数)。为什么不 `structuredClone`/展开:显式逐键投影是本模块对「上游 additive
  * 加键」的免疫层(见 {@link RuleOfferRawSchema} 顶注)——加键到不了 `card_json`,strip 语义在
  * 投影处兑现,不靠 schema 层兜。
+ *
+ * 到这里的素材已经过素材铸点的结构窄读(`tool-approval.ts` `boundRuleOfferTexts` 拿 {@link RuleOfferRawSchema}
+ * 判过形)⇒ 两级 `kind` 的运行期 `default` 臂在健康进程里不可达;它们守的是「本仓 dist 与 core 版本不同步」
+ * 那一形([ref] 词表范式:core 加臂 ⇒ `satisfies never` 编译红由人裁投影形;运行期撞到未知臂响亮抛,绝不把一个
+ * 不认识的臂当 batch/command 硬投)。
  */
 export declare function copyRuleOffer(o: RuleOffer): RuleOfferProjection;
 /**
@@ -242,20 +341,38 @@ export declare const ApprovalCardSchema: z.ZodObject<{
         match: z.ZodEnum<{
             exact: "exact";
             prefix: "prefix";
+            wildcard: "wildcard";
+            subpath: "subpath";
         }>;
         command: z.ZodString;
     }, z.core.$strict>, z.ZodObject<{
         kind: z.ZodLiteral<"batch">;
-        rules: z.ZodArray<z.ZodObject<{
+        rules: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            kind: z.ZodLiteral<"command">;
             rule: z.ZodString;
             match: z.ZodEnum<{
                 exact: "exact";
                 prefix: "prefix";
+                wildcard: "wildcard";
+                subpath: "subpath";
             }>;
             command: z.ZodString;
             segment: z.ZodString;
-        }, z.core.$strict>>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"directoryRead">;
+            rule: z.ZodString;
+            directory: z.ZodString;
+            segment: z.ZodString;
+        }, z.core.$strict>]>>;
         uncoveredSegments: z.ZodNumber;
+        uncoveredDetail: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            segment: z.ZodString;
+            reason: z.ZodEnum<{
+                redirection: "redirection";
+                no_rule_form: "no_rule_form";
+                cap_overflow: "cap_overflow";
+            }>;
+        }, z.core.$strict>>>;
     }, z.core.$strict>]>>>;
     ruleOffersAbsence: z.ZodOptional<z.ZodEnum<{
         mandated: "mandated";
@@ -323,20 +440,38 @@ export declare const ApprovalCardEnvelopeSchema: z.ZodObject<{
             match: z.ZodEnum<{
                 exact: "exact";
                 prefix: "prefix";
+                wildcard: "wildcard";
+                subpath: "subpath";
             }>;
             command: z.ZodString;
         }, z.core.$strict>, z.ZodObject<{
             kind: z.ZodLiteral<"batch">;
-            rules: z.ZodArray<z.ZodObject<{
+            rules: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                kind: z.ZodLiteral<"command">;
                 rule: z.ZodString;
                 match: z.ZodEnum<{
                     exact: "exact";
                     prefix: "prefix";
+                    wildcard: "wildcard";
+                    subpath: "subpath";
                 }>;
                 command: z.ZodString;
                 segment: z.ZodString;
-            }, z.core.$strict>>;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"directoryRead">;
+                rule: z.ZodString;
+                directory: z.ZodString;
+                segment: z.ZodString;
+            }, z.core.$strict>]>>;
             uncoveredSegments: z.ZodNumber;
+            uncoveredDetail: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                segment: z.ZodString;
+                reason: z.ZodEnum<{
+                    redirection: "redirection";
+                    no_rule_form: "no_rule_form";
+                    cap_overflow: "cap_overflow";
+                }>;
+            }, z.core.$strict>>>;
         }, z.core.$strict>]>>>;
         ruleOffersAbsence: z.ZodOptional<z.ZodEnum<{
             mandated: "mandated";