@sema-agent/server 7.43.0 → 7.44.0

package/dist/approval-card.js

@@ -1,122 +1,23 @@
-/**
- * #151 车3(design/172 流内审批协议)—— **审批卡的 schema 属主 + 重放腿的纯函数**。
- *
- * 本模块只出两样东西,**都不带 IO、不带定时器、不发帧**:
- *  1. `ApprovalCardSchema` / `ApprovalCardEnvelopeSchema` —— 落库 `approval_ask.card_json` 与一切读面
- *     (重放腿=刀 3c、回决端点=车4、对账扫描=车5)共用的**同一份** schema。写侧(刀 3b 的 `ensureAsk`)
- *     与读侧走同一个符号,于是「存的形」与「读的形」不可能各自漂。
- *  2. `buildReplayFrame` / `buildApprovalPreamble` —— 行 → 帧的**纯投影**(设计稿 §5.2)。
- *
- * 🔴 为什么读面必须 `safeParse` 而不是裸 as-cast:`card_json` 是 JSON 列,驱动回读的是 `unknown`。
- * 宪法 [2704](边界必 schema / 禁裸 as-cast / schema 单一属主)在这里是硬约束——一条形状漂了的历史行
- * 若被 as-cast 成 `ApprovalCard`,它会带着 `undefined` 字段一路走到 wire 上,消费端拿到的是「结构上
- * 合法、语义上空」的卡。`safeParse` 让这种行**当场落地为「跳过 + 一次 warn」**(§5.3)。
- *
- * schema 属主裁定(设计稿 §12-2,属主 §14 裁 (a) 变体):v1 的 schema 属主 = server 本仓,server 加
- * **zod 直依赖**(此前 zod 只经 `@sema-agent/registry-core` 传递到场)。抽进 `@sema-agent/registry-core`
- * 的时机 = 出现第二个**运行期**消费者(cli 呈卡校验排期时)——届时是「属主迁移」而不是「复制形状」,
- * 不违单一属主宪法;此刻抽包 = 为不存在的消费者发一轮 registry-core 版本 + floor bump,零收益。
- *
- * 命名(CLAUDE.md 工厂命名律):本文件全部是 `build*` —— 返回值是纯数据(帧对象 / 帧数组 / 计数),
- * 没有方法、没有捕获的行为。
- */
 import { z } from "zod";
 import { ASK_EVIDENCE_ABSENCE_VALUES, MAX_RULE_TEXT_CHARS } from "@sema-agent/core";
 import { redactSecrets } from "./trace/redact.js";
-/** 模型自由文本(`sourceAgentName` / `delegation.agentName`)的限长(设计稿 §6.2)。设计 §3.1 把
- *  「限长 + 脱敏」写成 **server 新增责任**(引擎无此层):spawning model 挑的名字是自由文本,
- *  不能指望壳去截——一条 100KB 的 agentName 在 server 侧就该被拒,而不是变成一张撑爆呈卡面的卡。 */
 export const MAX_AGENT_NAME = 200;
-/** 中性投影里的自由文本/标识符统一限长(工具名、toolCallId、sourceTaskId)。 */
 const MAX_IDENT = 200;
-/**
- * **一条**规则候选的形 —— 同步腿(`ApprovalCardSchema.ruleSuggestions` / `card_json`)与耐久腿
- * (durable park 行的 `PendingCheckpoint.ruleSuggestions`,由 `plugins/checkpoint-store-sql.ts` 窄读)
- * **共用这一份**。
- *
- * 🔴 单一属主(宪法 [2704]「schema 单一属主禁复制」):两条腿投的是 core 的**同一个** `RuleSuggestion`
- * (同步腿 = `AskRequest.ruleSuggestions`,耐久腿 = `PendingAction.ruleSuggestions`,core
- * `checkpoint-store.d.ts` 明写「CONTRACT (same as the synchronous `AskRequest.ruleSuggestions`)」)。
- * 各写一份 zod 必然漂——闭词表 `match` 加词、上限改口径,只改一处就出两种形。
- */
 export const RuleSuggestionSchema = z
     .object({ rule: z.string().max(MAX_RULE_TEXT_CHARS), match: z.enum(["exact", "prefix"]), command: z.string().max(MAX_RULE_TEXT_CHARS) })
     .strict();
-/**
- * {@link RuleSuggestionSchema} 的**不限长**孪生 —— 只判**结构**(两个字符串 + 闭词表 `match`),长度由
- * 调用方在**脱敏之后**自己截。
- *
- * 🔴 为什么必须有它(codex 对抗复审 [medium],验真后修):`redactSecrets` **会变长**(一条
- * `password=…` 换成更长的遮蔽标记)。拿带 `.max()` 的形去校验**脱敏前**的原文,再脱敏,产出的就可能是
- * 一条超限的文本;而任何**回读**路径若再跑一遍同一个函数,那一条会在第二次校验时被整条丢掉 —— 于是
- * 「落库时在、读回时不在」,并且**只发生在有回读的那条腿上**(SQL 有列回读、LOCAL 直接从 blob 投),
- * 两个后端对同一份素材给出不同的卡面。同族先例逐字在 `tool-approval.ts` 的 `persistedRuleShadowed`
- * 发帧点(「先脱敏再截,一次算定」)。
- *
- * ⇒ 正确顺序:**结构判(本 schema)→ 脱敏 → 截长 → 结果按 {@link RuleSuggestionSchema} 必然合形**。
- * 这样函数对自己的输出**幂等**,两条腿同形。
- *
- * 🔴 **未知键 `strip`(合并码重扫放宽,重扫二轮改准形):窄读只判三键结构,多余键剥掉、且不拒收**。
- * base 带 `.strict()`,而 zod 4 的 `.extend()` **保留** strict —— core 给 `RuleSuggestion` 加一个 additive
- * 字段(它对这条面一贯的做法),逐条 `safeParse` 会**条条失败**,于是耐久腿的整只候选静默清零、列落
- * NULL、读口省键,把「有供给」谎报成「无供给」,正是本键存在理由的反面(`checkpoint-store-sql.ts` 顶注与
- * wire 契约都写死「缺席=真的没有候选」)。同步腿的 `buildApprovalCard` 是显式三键投影、对加字段天然免疫
- * ⇒ 不放宽这一份,两条腿会在「上游长一格」这条轴上分家。
- *
- * ⚠️ **写的是 `.strip()` 不是 `.loose()`**(重扫二轮,实测更正):zod 4 的 `loose` = **passthrough** ——
- * 未知键**原样留在** `parsed.data` 里,与本注和契约文写的「多余键剥掉」相反。放宽要的是「不拒收」,
- * 剥键是另一件事,`.loose()` 只做到了前者。旧形下真正在剥键的是 {@link boundedRuleSuggestions} 里那三行
- * 显式投影,于是本 schema 对「剥键」这条判据是**空跑**;而它是**导出符号**,output 类型带 index signature,
- * 任何新消费者拿 `parsed.data` 直投就把上游未知键(其上**没有** `redactSecrets` 覆盖)带上跨租户可见的
- * `GET /v1/approvals`。⇒ 改默认 strip 形:additive 加键照收、未知键当场剥掉,两个意图各自成立。
- * 落库/读回的 {@link ApprovalCardSchema} 仍 `.strict()`(投影只写三键,多余键根本到不了那一层)。
- */
 export const RuleSuggestionRawSchema = RuleSuggestionSchema.extend({ rule: z.string(), command: z.string() }).strip();
-/**
- * 候选**基数**的 server 执法上限。两条腿同用。
- *
- * 🔴 **两个数,别混**(合并码重扫,档实对齐):core 的契约是 **≤2**(`exact` 恒 index 0,至多再跟一条
- * reviewed `prefix` 形 —— core `checkpoint-store.d.ts` 与 `permission-rule-model.d.ts` 逐字),那是**今天
- * 真实的**上限;本常量是 server 侧的**容忍帽**,刻意留在 4:一个被改坏/未来放宽的上游不该让运维队列
- * 的一行被整只拒收(同步腿这一格进的是 `.strict()` 的卡 schema,收紧到 2 会把「多给一条展示用候选」
- * 变成铸卡失败——在一条纯展示轴上换来一次 park,方向反了)。⇒ 消费端按 **≤4** 布局,契约文同口径成文。
- */
 export const MAX_RULE_SUGGESTIONS = 4;
-/** 已 redact 的 ask 文案上限(`AskRequest.message` 的投影)。 */
 const MAX_MESSAGE = 8192;
-/**
- * #253 件 G1(core 5.33.0 backlog #239)—— `probeCause` 的**防御性上限**三兄弟。
- *
- * 🔴 **它们不是第二个真源**:core 自己在 `normalizeProbeCause` 里已经 cap 过(亲读装树
- * `dist/core/checkpoint-store.js`:`PROBE_REASON_MAX = 200` 管 code、`PROBE_CAUSE_PATH_MAX = 200`
- * 管每一条 `shown`、`PROBE_CAUSE_MAX_SHOWN = 8` 管条数),而那三个常量**没有从包根导出**(亲验
- * `index.d.ts` 零命中)⇒ 抄不了值,只能各写一份。所以这里的姿势是**信封而不是政策**:取与 core 同值
- * (条数取 8),并由 `test/approval-probe-cause-wire.test.ts` 的「至少带到 8」一格看守 —— core 哪天放宽
- * 条数,那一格仍绿(我们少带几条,`total` 逐字保真 ⇒ 消费端算得出「还有 N 条没点名」,不是谎报)。
- *
- * 为什么 `code` 超限是**整只丢**而不是截:`code` 是**机器可读**的因由 id,截出来的是**另一个**码 ——
- * 消费端会把它映射到错误的文案,比没有更坏。`shown` 相反:少点名几条是诚实的省略(`total` 还在)。
- */
 const MAX_PROBE_CAUSE_CODE = 200;
 const MAX_PROBE_CAUSE_PATH = 200;
 const MAX_PROBE_CAUSE_SHOWN = 8;
-/**
- * #253 件 G1 —— 一族**操作数**(`roots` / `further`)的形。`shown` 是可点名的条目,`total` 是这一族的
- * 真实基数。**不变量 `shown.length ≤ total`**:少报条目是诚实的省略(消费端渲「另有 N 条」),
- * 谎报 `total` 是错的。上限见 {@link MAX_PROBE_CAUSE_SHOWN} 顶注(信封,不是政策)。
- */
 const ProbeCauseOperandsSchema = z
     .object({
     shown: z.array(z.string().max(MAX_PROBE_CAUSE_PATH)).max(MAX_PROBE_CAUSE_SHOWN),
     total: z.number().int().nonnegative(),
 })
     .strict();
-/**
- * #253 件 G1 —— `probeCause` 的形(落库/读面共用这一份;窄读入口是 {@link readProbeCause})。
- *
- * `.strict()` 与卡的其余部分同调:落进 `card_json` 的东西是**本仓投出来的**三键,不可能有未知键
- * (未知键在窄读那一层就被 zod 默认 strip 掉了)。
- */
 export const ProbeCauseSchema = z
     .object({
     code: z.string().min(1).max(MAX_PROBE_CAUSE_CODE),
@@ -124,8 +25,6 @@ export const ProbeCauseSchema = z
     further: ProbeCauseOperandsSchema.optional(),
 })
     .strict();
-/** 窄读的入参形:只判**结构**,长度由 {@link readProbeCause} 在判完之后自己截(与
- *  {@link RuleSuggestionRawSchema} 同款分工:先判形、再截,函数对自己的输出幂等)。 */
 const ProbeCauseRawOperandsSchema = z.object({ shown: z.array(z.string()), total: z.number().int().nonnegative() });
 const ProbeCauseEnvelopeSchema = z.object({
     probeCause: z
@@ -136,17 +35,6 @@ const ProbeCauseEnvelopeSchema = z.object({
     })
         .optional(),
 });
-/**
- * `AskRequest.probeCause`(以及耐久路同值的 `RiskDescriptor.probeCause`)的**边界窄读** —— 活卡帧与
- * `card_json` 的**唯一**铸造点,两面因此结构性同值(不是两处各挑一次键的巧合)。
- *
- * 🔴 姿势与 `RiskAxesEnvelopeSchema` 一致:`safeParse` 而不是裸 `as`(宪法 [2704] 边界必 schema)。
- * 形不合 ⇒ **按缺席处置**(绝不半解出一个残缺结构上卡面);未知键被 zod 默认 strip(core additive
- * 加键不该让整只 ask 的卡面塌掉)。
- *
- * 🔴 截长的两条不同判据(理由全文见 {@link MAX_PROBE_CAUSE_CODE} 顶注):`code` 超限 ⇒ **整只丢**
- * (截出来的是另一个机器码);`shown` 超限 ⇒ **截条目**,`total` 逐字保真。
- */
 export function readProbeCause(req) {
     const parsed = ProbeCauseEnvelopeSchema.safeParse(req);
     const raw = parsed.success ? parsed.data.probeCause : undefined;
@@ -156,8 +44,6 @@ export function readProbeCause(req) {
         return undefined;
     const family = (f) => ({
         shown: f.shown.slice(0, MAX_PROBE_CAUSE_SHOWN).map((p) => (p.length > MAX_PROBE_CAUSE_PATH ? p.slice(0, MAX_PROBE_CAUSE_PATH) : p)),
-        // 不变量兜底:上游若少报 total(`total < shown.length`),取二者较大者 —— 与 core 的
-        // `Math.max(total, shown.length)` 同向,永不让消费端算出负数的「另有 N 条」。
         total: Math.max(f.total, Math.min(f.shown.length, MAX_PROBE_CAUSE_SHOWN)),
     });
     return {
@@ -166,27 +52,10 @@ export function readProbeCause(req) {
         ...(raw.further !== undefined ? { further: family(raw.further) } : {}),
     };
 }
-/**
- * #263 件 G2(core 5.35.0 design/252 G-2)—— `ruleEvidence` 的**防御性上限**两兄弟(信封非政策,
- * 与 {@link MAX_PROBE_CAUSE_CODE} 家族同姿势:core 侧值来自引擎自己的治理层,没有导出上限可抄)。
- * `dot.actor` 是身份串(规则属主 id),256 取 core `APPROVER_ATTRIBUTION_MAX_CHARS` 的同族语义;
- * dots 条数的真实域 = 同一条规则文本的并发批准数(个位数),16 是纯防御臂。
- * 🔴 dots 超限 / actor 超限 ⇒ **整只丢**而不是截:core 契约明写「The set is the identity」——截过的
- * 集合、截过的 actor 名的是**另一个**身份,比缺席更坏(与 probeCause `code` 超限同判据)。
- */
 const MAX_EVIDENCE_DOT_ACTOR = 256;
 const MAX_EVIDENCE_DOTS = 16;
-/** 五词缺席词表——单一属主 = core 的 `ASK_EVIDENCE_ABSENCE_VALUES`(闭集常量,不在本仓抄词;
- *  上游加词时这里自动跟随)。`z.custom` 而不是 `z.enum`:后者要非空元组字面量型,从 readonly 数组
- *  常量过去只能 `as unknown as`(类型卫生门禁),而运行期判据本来就是「在 core 词表里」这一件事。 */
 const AskEvidenceAbsenceSchema = z.custom((v) => typeof v === "string" && ASK_EVIDENCE_ABSENCE_VALUES.includes(v));
-/** 一颗规则 add dot(core `RuleDot`:add 的持久身份 `{actor, counter}`)。 */
 const RuleDotSchema = z.object({ actor: z.string().min(1).max(MAX_EVIDENCE_DOT_ACTOR), counter: z.number().int().nonnegative() }).strict();
-/**
- * #263 件 G2 —— `AskRequest.ruleEvidence` 的形(帧 / `card_json` / 读面共用;窄读入口是
- * {@link readRuleEvidence})。三对成员各 = 值**或**五词命名缺席(`AskEvidenceAbsence`),core 引擎
- * 盖章的证据恰一在场;server 只判形转录,**永不**自铸缺席词(server 铸词 = 谎报「某一层没报」)。
- */
 export const RuleEvidenceSchema = z
     .object({
     orgRevision: z.number().finite().optional(),
@@ -197,8 +66,6 @@ export const RuleEvidenceSchema = z
     personalRuleDotsAbsent: AskEvidenceAbsenceSchema.optional(),
 })
     .strict();
-/** 窄读的入参形(不限长孪生,分工同 {@link ProbeCauseEnvelopeSchema}):只判结构,长度/脱敏由
- *  {@link readRuleEvidence} 判完之后一次算定。 */
 const RuleEvidenceEnvelopeSchema = z.object({
     ruleEvidence: z
         .object({
@@ -211,18 +78,6 @@ const RuleEvidenceEnvelopeSchema = z.object({
     })
         .optional(),
 });
-/**
- * `AskRequest.ruleEvidence`(core 5.35.0 design/252 G-2)的**边界窄读**——活卡帧(`ToolApprovalFrame.
- * ruleEvidence`)与 `card_json`(`buildApprovalCard`)的**唯一**铸造点,两面结构性同值(与
- * {@link readProbeCause} 同款分工)。姿势逐条:
- *  · `safeParse`,形不合 ⇒ 按缺席处置(宪法 [2704]);未知键 strip(core additive 加键不塌卡)。
- *  · **恰一不变量**:一对成员(值 / 缺席词)**双在场** ⇒ 整只丢——那是矛盾证据(引擎盖章的恰一,
- *    双在场只可能是第三方 producer 的坏行),半解上卡比缺席更坏。双缺席**容忍**(老 producer 行)。
- *  · `orgRule` 内容族(管理员写的规则文本)⇒ `redactSecrets` 后截 `MAX_RULE_TEXT_CHARS`,**先脱敏
- *    再截一次算定**(`persistedRuleShadowed` R2-[medium] 教训:redact 会变长,两面各截会漂);空串丢整只。
- *  · `dots.actor` 身份串 ⇒ `redactSecrets`(对正常 id 恒等);超限**整只丢**(见上限顶注,身份不可截)。
- *  · `orgRevision` / 缺席词 verbatim(数值 / 闭集词,非内容)。
- */
 export function readRuleEvidence(req) {
     const parsed = RuleEvidenceEnvelopeSchema.safeParse(req);
     const raw = parsed.success ? parsed.data.ruleEvidence : undefined;
@@ -257,122 +112,25 @@ export function readRuleEvidence(req) {
         ...(raw.personalRuleDotsAbsent !== undefined ? { personalRuleDotsAbsent: raw.personalRuleDotsAbsent } : {}),
     };
 }
-/**
- * design/172 §3.1 的**中性投影**——呈卡面看到的全部内容,与 wire 面的既有 `ToolApprovalFrame` 解耦。
- *
- * `risk` 的三态形(设计稿 §14.1,core [2794] 回帖后定):`AskRequest.riskAxes?.{irreversible,egress}`
- * 是 **additive optional**,**缺席 = 引擎未判,不是「安全」**。所以两轴在这里是 `optional()`:
- * `true` / `false` / **缺席(未标注)** 三态各自可分,投影层**禁把缺席折算成 false** —— 那等于替引擎
- * 打包票。`requiresRealApproval` 是**粗粒度**安全类标记,两侧的在场契约**不同、别混**:core 侧是
- * `AskRequest.requiresRealApproval?: boolean`(**可选、只在为真时带**,缺席 = 这不是一次安全类 ask,是
- * 正常的否定形而不是坏形);本卡面这一格是**必填 boolean**,由车2 的入参归一化(`=== true`)而来。
- * 它与两轴是两件事而不是新旧替代——原注写的「core 今天唯一在场的标记」是 `riskAxes` 上树之前的现势话,
- * 自 core **5.14.0**(其 CHANGELOG 的 `AskRequest.riskAxes` additive 条)起两者并存。
- */
 export const ApprovalCardSchema = z
     .object({
     toolName: z.string().max(MAX_IDENT),
-    /** 已 redact(车2 `redactDeep`)。 */
     message: z.string().max(MAX_MESSAGE),
-    /** 已 redactDeep + **字节**帽(设计稿 §6.5:`Buffer.byteLength`,不是 `.length` 的 UTF-16 单元)。 */
     args: z.unknown().optional(),
     argsOmitted: z.literal(true).optional(),
     toolCallId: z.string().max(MAX_IDENT).optional(),
     risk: z
         .object({
-        /** 缺席 = 未标注(禁折算 false)。 */
         irreversible: z.boolean().optional(),
-        /** 缺席 = 未标注(禁折算 false)。 */
         egress: z.boolean().optional(),
         requiresRealApproval: z.boolean(),
     })
         .strict(),
-    /**
-     * [2942]/[2943] **ADDITIVE**:`true` ⇔ 这只 ask 的门来自运维治理层(语义、判定缝与「缺席 ≠ false」
-     * 的硬条款逐字见 `tool-approval.ts` 的 `ToolApprovalFrame.governanceForced` 与
-     * `governance-ask-marks.ts` 顶注)。放在**卡的顶层**而不是 `risk` 里:`risk` 讲的是引擎对这次操作的
-     * 风险判定(不可逆/出网/安全类),本键讲的是**门是谁下的**,两件事。
-     *
-     * ⚠️ **回滚窗的行为(codex 交叉复审 round1 [high],验真后按「真实但内生」收下)**。形版本闩
-     * (`schemaVersion`)**不动**:additive optional 键在 `.strict()` 下对**旧行**无碍(缺席合法),代价
-     * 全在**回滚方向** —— 一个降级回旧二进制的副本读到带本键的新行,`safeParse` 会失败,两条读面各自:
-     *   · 重放腿(`buildReplayFrame`)⇒ 该行**跳过** + 一次 warn(§5.3),不炸流;
-     *   · `askBroadcast` 幂等命中该行 ⇒ 走「持久行不可用」臂 ⇒ `"unavailable"` = **park 路由**
-     *     (tool-approval.ts 的 `persisted-row-unusable`)。park 是本协议的 fail-safe 出口:人仍可经
-     *     durable gate 补批 —— 不是「批准凭空消失」,更不是把它折算成 deny。
-     * 这个代价是**任何** additive 键在一个 `.strict()` schema 下的内生代价,不是本键独有:bump 到
-     * `schemaVersion: 2` 只会更糟(旧读面 `z.literal(1)` 直接全量拒收**所有**新行,连缺席本键的行都收不了)。
-     * ⇒ 处置 = 不改形版本;**发车条款**写进 CHANGELOG:整队滚前(不留长期混版窗),回滚窗内新卡降级为
-     * park(fail-safe),回滚窗结束即自愈。
-     */
     governanceForced: z.literal(true).optional(),
-    /**
-     * #144(core 5.25.0 [3438]/[3443],**ADDITIVE**):这次 ask **命中了**一条用户的持久 allow 规则,
-     * 但规则**清不掉**它 —— 值 = 那条被越级的规则**原文**(语义、消音边界与「缺席 ≠ 没有规则」的
-     * 硬条款逐字见 `tool-approval.ts` 的 `ToolApprovalFrame.persistedRuleShadowed`)。
-     *
-     * 放在**卡的顶层**、与 `governanceForced` 并列而不是塞进 `risk`:`risk` 是引擎对这次**操作**的风险
-     * 判定,这一格讲的是「你那条规则怎么了」——两件事。与 `governanceForced` 也**刻意分列**:那个说
-     * 「门是运维下的」,这个说「有一条你的规则在场但被越级」,两者可以同时在场也可以各自单独在场
-     * (governance 是不可消音的三个来源之一,doctrine `always` 与工具自带 egress/irreversible mark 是另两个)。
-     *
-     * 值域 = **用户内容族**(规则原文是人写的文本,core 侧已过 `inlineUntrusted` 200 cap):
-     * 写侧在**上游**(`tool-approval.ts` 发帧点)过 `redactSecrets` 再交进来,本层只截长(`clip`)。
-     * UNTRUSTED-for-display,同 `message`/`args` 待遇。
-     *
-     * 回滚窗代价与 `governanceForced` **逐字同族**(见上一段那条 ⚠️):`.strict()` 下旧二进制读不动带本键的
-     * 新行 ⇒ 重放跳过 + 幂等重入走 park(fail-safe),`schemaVersion` 不动。
-     */
     persistedRuleShadowed: z.string().max(MAX_RULE_TEXT_CHARS).optional(),
-    /**
-     * #154 车二(core 5.18.0 design/179):引擎为这次 ask 铸的**规则候选**(`Bash(git status)` 精确 /
-     * `Bash(git status:*)` 词界前缀)—— 呈卡面据它渲「不再询问」。
-     *
-     * 🔴 **在场性即承诺**:这一格只在**规则店真装配**(`RunnerDeps.permissionRuleStore` 在场 ⇔ manifest
-     * 的 `permissionRules.storeWired: true`)时投影。店缺席仍投 = 给客户端渲一格它按下去无处可兑的
-     * 「不再询问」,那是 wire 谎言,比缺席更坏(判据逐字见 `core-keyset-guard.ts` ④ 面本键那一段)。
-     * 缺席 ⇒ 这只 ask 没有可兑的候选(命令不可匹配,或本部署没接店),两种都读作「本卡无此选项」。
-     * 值**逐字**取自 core(闭词表 `match` + 引擎铸的文本),server 不重铸、不重排。
-     *
-     * ⚠️ **兑付面的射程,如实说清**(codex 交叉复审 round1 [medium],验真后按「真实但已知」登记):
-     * 本键随卡进 `card_json`,于是重放帧也带它;而它的兑付通道**只有一条** —— 重放帧自己携带的
-     * `approvalId` 所指的那条 live 回决口(`POST /v1/tool-approvals/:id/respond` 的 `persistRule`)。
-     * 那条口是**进程内**的(pending map 随副本走),所以:同副本重连 ⇒ 兑得动;换副本/重启之后 ⇒ 那个
-     * `approvalId` 已经 404,人只能走 durable 回决口(`POST /v1/tasks/:id/asks/:askId/decision`),
-     * 而**那条口 v1 不带规则位**(它的 zod 体是 `.strict()`,多给一个 `persistRule` 是响亮 400,不是静默丢)。
-     * 这不是本键独有的射程:`approvalId` 本身就是同一个可用性信封(卡还能不能被这条通道决,取决于它)。
-     * ⇒ 处置 = 不缩键(缩了,同副本重连这条真实可用的路也一起没了),把「durable 回决腿的规则位」
-     * 登记为后续件(车4 域)。
-     */
     ruleSuggestions: z.array(RuleSuggestionSchema).max(MAX_RULE_SUGGESTIONS).optional(),
-    /**
-     * #253 件 G1(core 5.33.0 backlog #239,判据帖 [3930] G1;**ADDITIVE**)——这次 ask **为什么**被
-     * 收紧的**结构化**因由:`{ code, roots:{shown,total}, further?:{shown,total} }`。
-     *
-     * 🔴 **结构就是契约**(core d.ts 逐字:"render the entries as data, never re-derive structure by
-     * splitting or joining them"):`code` 是机器可读的因由 id(`<domain>.<snake_case>`),两个操作数族
-     * 各自带**真实基数** `total` —— `shown` 被省略时 `shown.length < total`,消费端据此渲「另有 N 条」。
-     * 引擎交出的是 code + 数组,**永不**是写好的句子;句子归呈卡端按本地语言渲。所以本层**逐字透传结构**,
-     * 不拍扁成文本、不重排、不合并两族。
-     *
-     * 🔴 **缺席 ≠「没有原因」**:只有「maybe 档收紧 ∧ 探针真给了 cause」的 ask 才有它。绝大多数 ask
-     * 压根不经这条路(缺席),而**判得出可回滚**的调用根本不会变成 ask。
-     *
-     * 🔴 与 `message` **刻意分列、不合并**(判据帖 G1 的负控):`message` 是分类器/模型看得见的输入面,
-     * 把一份随路径变化的操作数清单挤进去会污染判定输入;本键是**展示面**的结构化数据。
-     *
-     * 回滚窗代价与 `governanceForced` / `persistedRuleShadowed` **逐字同族**(见那两条的 ⚠️):
-     * `.strict()` 下旧二进制读不动带本键的新行 ⇒ 重放跳过 + 幂等重入走 park(fail-safe),`schemaVersion` 不动。
-     */
     probeCause: ProbeCauseSchema.optional(),
-    /**
-     * #263 件 G2(core 5.35.0 design/252 G-2):这只 ask 背后的**规则出处证据**——org 快照 revision /
-     * 命中的 org 规则原文 / 被越级的个人规则 add dots,每员 = 值或五词命名缺席。展示/对账元数据,
-     * **永不**是裁决输入(core 契约逐字:removing it would leave every decision byte-identical)。
-     * 回滚窗代价与 `probeCause` 逐字同族(`.strict()` 下旧二进制读不动新行 ⇒ 重放跳过 + park fail-safe)。
-     */
     ruleEvidence: RuleEvidenceSchema.optional(),
-    /** 委派出处(子代 ask 才在场;判别键 = `fromSubagent`,core RB-39②)。 */
     fromSubagent: z.literal(true).optional(),
     sourceTaskId: z.string().max(MAX_IDENT).optional(),
     sourceAgentName: z.string().max(MAX_AGENT_NAME).optional(),
@@ -385,12 +143,6 @@ export const ApprovalCardSchema = z
         .optional(),
 })
     .strict();
-/**
- * `approval_ask.card_json` 里真正存的东西(设计稿 §6.2)。存**信封**而不是裸卡的理由:重放帧要回填
- * 车2 铸的 `approvalId`(wire 面的回决通道桥 + 消费端与并行 `tool_approval` 帧的去重键),而它不属于
- * 「卡的内容」——放进卡里会让 schema 的语义边界糊掉。`schemaVersion` 是形的版本闩(与行上的
- * `schema_version` 列同值,列供 SQL 侧过滤,信封里这份供读面在解出内容**之前**判形)。
- */
 export const ApprovalCardEnvelopeSchema = z
     .object({
     schemaVersion: z.literal(1),
@@ -398,26 +150,7 @@ export const ApprovalCardEnvelopeSchema = z
     card: ApprovalCardSchema,
 })
     .strict();
-/** 本车铸的信封形版本(写侧=刀 3b,读侧=本文件)。 */
 export const APPROVAL_CARD_SCHEMA_VERSION = 1;
-/**
- * core 的风险轴(`AskRequest.riskAxes`,[2829]/§14.1)的**边界窄读**。
- *
- * ✅ **已点亮**:`riskAxes` 现在既在类型面也在真码面(树上 core 5.16.0,`core/tool-policy.d.ts` 的
- * `readonly riskAxes?: {…}`;package.json 的 floor 已抬到 `^5.16.0`)。窄读当初写下时的现势前提是
- * 「树上 core d.ts(5.13.0)还没有这个键、字段形只由 core 认领」——该键自 core **5.14.0** 起就在
- * (其 CHANGELOG 的 `AskRequest.riskAxes` additive 条),那句现势话早已过期,**别再据它判断「core 还没
- * 供值 ⇒ 卡面 risk 恒缺席」**。判在不在场以**装树的 d.ts 为准**,不要读注里的版本号
- * (同族销账见 `tool-approval.ts` 的 `readBoundInputHash` 头注,#164)。
- *
- * 🔴 保留 `safeParse` 而不改成直读 `req.riskAxes` 的理由不变(它从来不只是等字段):窄读让**编译与行为
- * 解耦**,缺席=未标注;裸 `as` 转型会在两个方向上都出错——既绕过宪法 [2704] 的「边界必 schema」,也会在
- * core 发出一个形状不同的键(或加轴)时静默把垃圾投上卡面。
- *
- * 未知键被 zod 默认 strip(此处**故意不 `.strict()`**:core additive 加轴时不该让整只 ask 的卡面塌掉);
- * 形不合(如 `irreversible: "yes"`)⇒ 整个 safeParse 失败 ⇒ 按**缺席**处置 = 「未标注」,
- * 绝不折算成 `false`(那等于替引擎打包票,§14.1 明令)。
- */
 const RiskAxesEnvelopeSchema = z.object({
     riskAxes: z
         .object({
@@ -426,31 +159,15 @@ const RiskAxesEnvelopeSchema = z.object({
     })
         .optional(),
 });
-/** 自由文本的**截断**(不是拒绝):卡必须还是要送到人手上——`toolName`/`message` 少几个字仍可决策,
- *  而整只 ask 因为一个 200KB 的 agentName 落不了库/上不了 wire 才是真事故(设计稿 §6.2 的 `.max()`
- *  在 server 侧的落实形,E-5 钉)。`undefined` 透传(缺席 ≠ 空串)。 */
 function clip(s, max) {
     if (s === undefined)
         return undefined;
     return s.length > max ? s.slice(0, max) : s;
 }
-/**
- * design/172 §3.1 的**中性投影**(设计稿 §6.2)—— 写侧的唯一铸造点。
- *
- * `risk` 三态(§14.1):两轴 `optional`,`true`/`false`/**缺席(未标注)** 各自可分。`req` 是 core 交来的
- * `AskRequest`(可能带、也可能不带 `riskAxes`),按 `unknown` 窄读;`requiresRealApproval` 走**独立入参**
- * (车2 已归一化的 boolean),不从 `req` 里读。core 侧它是可选、只在为真时带,缺席 = 这不是一次安全类
- * ask(core 的铸造点语义,不是我们的折算);卡面这一格恒在,`false` 就是那个否定形的如实投影。
- * (原注写的「core 今天唯一在场的粗粒度标记」自 core 5.14.0 的 `riskAxes` 起过期,见 `ApprovalCardSchema`
- * 头注。)
- */
 export function buildApprovalCard(source, req, requiresRealApproval) {
     const axes = RiskAxesEnvelopeSchema.safeParse(req);
     const riskAxes = axes.success ? axes.data.riskAxes : undefined;
-    // #253 件 G1:`probeCause` 与两轴同款,从 `req`(core 的 AskRequest)窄读 —— 发帧点用**同一个**函数
-    // 铸帧上那一份,于是「帧与卡同值」是结构事实而不是两处各挑一次键的巧合(§6.5 同款判据)。
     const probeCause = readProbeCause(req);
-    // #263 件 G2:`ruleEvidence` 同款(readRuleEvidence 是帧/卡唯一铸造点,redact+截长在函数内一次算定)。
     const ruleEvidence = readRuleEvidence(req);
     const toolCallId = clip(source.toolCallId, MAX_IDENT);
     const sourceTaskId = clip(source.sourceTaskId, MAX_IDENT);
@@ -466,18 +183,10 @@ export function buildApprovalCard(source, req, requiresRealApproval) {
             ...(riskAxes?.egress !== undefined ? { egress: riskAxes.egress } : {}),
             requiresRealApproval,
         },
-        // [2942]/[2943]:只在为真时投影(`=== true` 严判:非布尔真值不得把一张普通卡染成治理卡)。
         ...(source.governanceForced === true ? { governanceForced: true } : {}),
-        // #144:被越级的规则原文。**空串不投**(core 的四个 mint 点只在真有命中规则时带这个键 ⇒ 空串不是
-        // 「有一条空规则」而是坏值;投一个空串会让壳渲一行「你的规则 ⟨⟩ 仍在」)。截长同 `message` 待遇。
         ...(shadowedRule !== undefined && shadowedRule !== "" ? { persistedRuleShadowed: shadowedRule } : {}),
-        // #253 件 G1:结构化探针因由 —— 与活卡帧**同一个**窄读函数(`readProbeCause`),两面结构性同值;
-        // 形不合/缺席 ⇒ 不铸键(语义见 `ApprovalCardSchema.probeCause` 顶注)。
         ...(probeCause !== undefined ? { probeCause } : {}),
-        // #263 件 G2:规则出处证据 —— 同款同源(`readRuleEvidence`);形不合/缺席 ⇒ 不铸键。
         ...(ruleEvidence !== undefined ? { ruleEvidence } : {}),
-        // #154 车二:候选**逐字**投影(空数组 ⇒ 不投键 —— 「没有候选」与「本部署不供候选」在卡面上都读作
-        // 「本卡无此选项」,铸一个空数组只会让消费端多一条无意义的分支)。拷贝一份:卡不与调用方共享可变引用。
         ...(source.ruleSuggestions !== undefined && source.ruleSuggestions.length > 0
             ? { ruleSuggestions: source.ruleSuggestions.map((s) => ({ rule: s.rule, match: s.match, command: s.command })) }
             : {}),
@@ -495,18 +204,9 @@ export function buildApprovalCard(source, req, requiresRealApproval) {
             : {}),
     };
 }
-/** 落库信封的纯构造(写侧;读侧 = `ApprovalCardEnvelopeSchema.safeParse`,**同一个 schema**)。 */
 export function buildApprovalCardEnvelope(approvalId, card) {
     return { schemaVersion: APPROVAL_CARD_SCHEMA_VERSION, approvalId, card };
 }
-/**
- * design/172 §3.1 的呈卡帧(设计稿 §4.1)—— **live 铸造**形(重放形见 {@link buildReplayFrame},
- * 两者投的是同一种帧,区别只在 `card` 的来源:这里是刚投影出来的,那里是从行上回读的)。
- *
- * `expiresAtMs` **入参**而不是在这里现算:同一只 ask 的窗**只铸一次**(§3.1「永不赋新 deadline」),
- * 调用点已经算好了它(既是定时器时长的来源,也是落库 `expires_at_ms` 的值)——在这里重算会铸出第二个
- * 真源,而两个真源必然漂。
- */
 export function buildApprovalRequestFrame(input) {
     return {
         type: "approval_request",
@@ -521,22 +221,9 @@ export function buildApprovalRequestFrame(input) {
         approvalId: input.approvalId,
     };
 }
-/** 撤卡帧的纯构造(`build*`:返回纯数据,无方法无捕获行为)。`askIds` 拷贝一份 —— 调用方传进来的多是
- *  store 返回的数组,帧不该与它共享可变引用。 */
 export function buildRevokeFrame(batchId, askIds, reason, serverNowMs) {
     return { type: "approval_revoke", schemaVersion: 1, batchId, askIds: [...askIds], reason, serverNowMs };
 }
-/**
- * 持久行 → 重放帧(设计稿 §5.2 逐字)。
- *
- * 三条不变量都在这几行里:
- *  - **坏行不炸开流**:`safeParse` 失败 ⇒ 返回 `undefined`(调用方跳过 + 记一次 warn,§5.3)。
- *  - **不续窗**:`expiresAtMs` 逐字回读,**永不重铸**;`expiresInMs` 由它与 `nowMs` 现算 ⇒ 同一张卡
- *    连续两次重放必然严格单调减(机器判据 = §10 钉 B-2)。
- *  - **零写**:本函数不碰 store —— 重放腿只读,不 `transitionAsk`、不改 `expires_at_ms`、不重挂定时器。
- *    过窗未收敛的行(`expiresInMs === 0`)**仍然重放**,不在这里代打 `expireAsk` CAS(那会制造第五个
- *    竞争者;收敛是车2 的窗到期竞争者与车5 恢复扫描的职责)。
- */
 export function buildReplayFrame(row, nowMs) {
     const parsed = ApprovalCardEnvelopeSchema.safeParse(row.cardJson);
     if (!parsed.success)
@@ -554,15 +241,6 @@ export function buildReplayFrame(row, nowMs) {
         approvalId: parsed.data.approvalId,
     };
 }
-/**
- * 开流 preamble 的行集 → 帧集(设计稿 §5.3 的读面帽 + 坏行跳过)。
- *
- * 帽的方向:超限时**只投最新的 N 张**——未决卡的价值随时间倒序递减(最老的那些多半已经在别处过窗/
- * 被收敛),而壳的呈卡面容量有限。丢弃是**读面**行为,不写库、不改状态;写侧的准入门(设计稿 §0 X-2)
- * 是另一件事,在刀 3b。
- *
- * `replayMax <= 0` 视作「不投」(运维显式关掉重放),不当成「无帽」。
- */
 export function buildApprovalPreamble(rows, nowMs, replayMax) {
     const frames = [];
     let skipped = 0;
@@ -577,7 +255,6 @@ export function buildApprovalPreamble(rows, nowMs, replayMax) {
     const dropped = Math.max(0, frames.length - cap);
     return { frames: dropped > 0 ? frames.slice(frames.length - cap) : frames, skipped, dropped };
 }
-/** preamble 帧的 SSE 投递形(具名事件,**不带 `id:`** —— 它不是账本行,不参与 Last-Event-ID 游标)。 */
 export function buildApprovalPreambleSseFrames(frames) {
     return frames.map((f) => ({ event: f.type, data: f }));
 }

package/dist/approval-deny-reasons.js

@@ -1,54 +1,12 @@
-/**
- * 流内审批协议(design/172 §3.0 对账三约束)的**终态归因词表** —— #151 车5。
- *
- * 两组常量、**两个不相交的值域**(车5 §8 C-1 裁定,与车4 F34 同向):
- *  - {@link DENY_REASONS} —— `DENIED` 终态的归因。v1 是**单员闭集**:`routing_failure_fail_closed`。
- *  - {@link VOID_REASONS} —— `VOID` 终态的归因。
- *
- * 🔴 为什么必须分两组、禁混值域:§3.0 的对账约束②是「**超时永不产生 denial**」,而审计面唯一能证明这条
- * 的东西就是终态 + 归因的组合。人拒恒为 `DECIDED(decision=deny)`(车4 §8),路由失败恒为
- * `DENIED(routing_failure_fail_closed)`,撤卡/取消/遗孤恒为 `VOID(<VOID_REASONS 之一>)`——三者在
- * wire 与审计上全程可分。若两组共用一个值域(或某个值同时可落两种终态),「这条 deny 是人做的、还是
- * 路由失败、还是超时兜底」就再也无法从行上读出来,归因诚实性(§6.1)当场失效。
- *
- * 落列面:两组值都写进 `approval_ask.denied_reason`(VARCHAR(64))——列名沿用车1 的 DDL(本车不改列),
- * 但它承载的是**终态归因**而不只是「拒绝理由」。读者靠「值属于哪一组」判别是哪条臂写的,这正是两组
- * 值域不相交这条纪律的用处(`ALL_TERMINAL_REASONS` 的机器判据钉住不相交性)。
- *
- * 写点纪律(grep 钉):全仓 `DENIED` 只有**一个**写点 = 收敛器判据 2 的非取消臂(`approval-reconciler.ts`)。
- */
-/** `DENIED` 终态的归因闭集(v1 单员)。 */
 export const DENY_REASONS = {
-    /**
-     * 收敛器判据 2:出处 run 已到**非 suspended 的终局**(completed / blocked / 非取消的 failed)而始终
-     * 没有出现与本 ask 匹配的 checkpoint ⇒ 这只 ask 的投递面永远不会再出现,fail-closed 收 `DENIED`。
-     * 🔴 证据是**行的终局态**(journal 的肯定证据),不是「等够久了」——约束②因此成立。
-     */
     ROUTING_FAILURE: "routing_failure_fail_closed",
 };
-/** `VOID` 终态的归因闭集。 */
 export const VOID_REASONS = {
-    /** 判据 2 的取消分臂(§9 C3):run `failed ∧ errorCode==="cancelled"` ⇒ 取消不是路由失败,收 VOID。 */
     RUN_CANCELLED: "run_cancelled",
-    /** 判据 2 的取消分臂之二:批行已 `ABORTED`(取消腿打过 `abortBatch`)⇒ 同 abort 语义。 */
     BATCH_ABORTED: "batch_aborted",
-    /**
-     * bind-once 的**落选者**(codex 交叉复审 round2 R2-3,2026-08-06 验真):批已 `ROUTING_BOUND` 且
-     * `bound_ask_id` 是**别人**——本行永远赢不了 `bindBatch`(谓词要求 `state='ROUTING_UNBOUND'`),
-     * 却又不是路由失败(投递面好好的,只是这个决策点选了兄弟)。172 §3.0 的 bind-once 字面就是「非中选
-     * 兄弟收敛 VOID」;`bindBatch` 的原子事务只连坐它当时看得见的 PARKING 兄弟,**之后**才进入 PARKING 的
-     * 迟到行(late `ensureAsk` + `expireAsk` 不查批态,设计如此)由收敛器补判——就是这条臂。
-     * 不这么判的后果:该行滞留到 run 终局,然后被判据 2 误报成 `routing_failure_fail_closed`(归因失真)。
-     */
     BATCH_BOUND_ELSEWHERE: "batch_bound_elsewhere",
-    /** 判据 4:adhoc 腿(`sessionId === taskId` ∧ `getRun` 无行)窗过 + 宽限 —— 该腿形**结构上**没有
-     *  durable 对账域(一次性 taskId 不进 runStore,park 目的地不可寻址),流死即 abort 语义。
-     *  🔴 落 VOID 不落 DENIED:VOID 不是 denial,约束②不被触碰。 */
     ADHOC_LEG_NO_DURABLE_DOMAIN: "adhoc_leg_no_durable_domain",
-    /** 判据 5:任何在 `STREAM_APPROVAL_ORPHAN_TTL_MS` 内仍未收敛的 `PARKING` 行(量 immutable 的
-     *  `createdAtMs`,§9 C5)—— 约束①(遗孤最终可判)的最后兜底,带一条 warn。 */
     ORPHAN_TTL_EXCEEDED: "orphan_ttl_exceeded",
 };
-/** 两组的并集(机器判据用:值域不相交 + 列宽 ≤ 64 的钉子在 test/approval-reconciler.test.ts)。 */
 export const ALL_TERMINAL_REASONS = [...Object.values(DENY_REASONS), ...Object.values(VOID_REASONS)];
 //# sourceMappingURL=approval-deny-reasons.js.map

package/dist/approval-hmac.js

@@ -1,43 +1,8 @@
-/**
- * design/80 D-G: approval-envelope HMAC (INTEGRITY, not identity). Split out of `security.ts` (design/158
- * A13; consumers import from HERE — [2354] cleared the security.ts compat re-exports; verifyDirectDoorProof in
- * ./principal-jwt.ts imports {@link verifyApprovalHmac} from here for the combined proof).
- *
- * ✅ WIRED into the resolve path (was "🔴 SCAFFOLD — NOT YET WIRED" — that claim went STALE; a 2026-07-25 doc-rot
- * sweep traced the real call chain: {@link verifyApprovalHmac} ← `verifyDirectDoorProof` ←  * routes at `http/server.ts`(resumeCheckpoint 链;A9 拆分后行级坐标弃用,文件级指路+grep verifyDirectDoorProof 取证). So "not wired" was wrong; "not turned on" is right, and turning it
- * on is a DEPLOYMENT + KEY-PROVISIONING task (sema-registry mints/rotates the set), not a coding task.
- *
- * FULL activation chain (an independent 2026-07-25 cross-check caught the first draft of this note naming only the
- * leaf conditions — record it completely so a deployment engineer isn't surprised): the crypto branch lives ONLY
- * under the durable-checkpoint /decide path, whose route block is gated on `deps.checkpointStore`
- * (A9 拆分后行级坐标弃用:grep `deps.checkpointStore` in `http/server.ts` resumeCheckpoint 链), which needs `backend?.checkpoint && config.durableApproval` (A10 后住 `src/boot/stores.ts`/装配表:grep `durableApproval` in main.ts+boot/). That is NOT
- * an extra thing to remember, because `directDoorActive` ALREADY requires `DURABLE_APPROVAL=true` by construction
- * (config.ts approval 域,grep `directDoorActive` — and see the 🔴 note above it: without it, checkpointStore is undefined, this branch is
- * skipped, and the LEGACY trusted-header /decide becomes live = a full crypto bypass). So `directDoorActive` really
- * is the single load-bearing switch — it just transitively implies the durable store, rather than being independent
- * of it. A half-configured door refuses to boot (config.ts 同域 boot 不变量,grep `half-configured`/`门 D-G`), so "looks on, verifies nothing" is impossible.
- * This is the crypto FOUNDATION for D-G (the direct-connect approval door): it proves the decision envelope
- * `{checkpointToken, boundCallId, boundInputHash, decision}` was not tampered in transit. It is INTEGRITY, NOT
- * identity — `isOperator(principal)` stays the identity gate (a valid MAC says "the bytes are intact", never
- * "this is the operator").
- * The KEY-SET shape here is PROVISIONAL — sema-registry owns the final secret format; only parseApprovalHmacKeys
- * changes if it differs. Replay protection is the checkpointToken's SINGLE-USE nature (a replayed MAC names an
- * already-resolved token → the resolve CAS fails already_resolved), so no separate replay cache is needed.
- */
 import { createHmac, timingSafeEqual } from "node:crypto";
 export function approvalHmacMessage(env) {
     return JSON.stringify([env.sessionId, env.boundCallId ?? null, env.boundInputHash ?? null, env.decision, env.reason ?? null]);
 }
-/** 签名载荷里 `reason` 的字符上限。**拒**而不是截 —— 截断在这条路径上**结构上不可行**:服务端截过的字节
- *  与签名方签的字节必然不同,MAC 恒不匹配,"截断"只会把一个可诊断的 413 变成一个费解的 401。
- *  取 4096 与本仓既有的人写文本上限同档(`MAX_ELICIT_MESSAGE_CHARS` / `MAX_AGENT_TEXT_CHARS`)。 */
 export const MAX_APPROVAL_REASON_CHARS = 4_096;
-/**
- * design/80 D-G: verify the INTEGRITY of an approval-decision envelope. Returns true iff `mac` (hex) equals
- * HMAC-SHA256(canonical-envelope) under ANY key in the set — the `kid`-hinted key first, then the rest (so a MAC
- * signed with a key being rotated out still verifies during the overlap). `timingSafeEqual` avoids a timing
- * oracle. An empty key-set ⇒ false (caller decides whether absence = skip-because-inactive or fail-closed).
- */
 export function verifyApprovalHmac(env, mac, kid, keys) {
     if (keys.length === 0)
         return false;