@sema-agent/server 7.122.0 → 7.124.0

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

@@ -3,20 +3,21 @@ import { join } from "node:path";
 import { AppendLog, ensureDir, isHostDecider } from "@sema-agent/core";
 import { recordFailOpen } from "./observability/fail-open.js";
 import { replayJsonlSkipping } from "./observability/corrupt-read-seat.js";
+import { isSettleCause, SETTLE_OUTCOME } from "./approval-deny-reasons.js";
 export const APPROVAL_ASK_AUDIT_DIR = "approval-ask-audit";
 export const APPROVAL_ASK_AUDIT_LEDGER = "ledger.jsonl";
 export const CRASH_CONVERGED_LIST_MAX = 200;
-export const AUDIT_SHUTDOWN_CAUSE_WORDS = { shutdown_before_park: true };
+const SETTLE_OUTCOME_WORDS = new Set(Object.values(SETTLE_OUTCOME));
+function isSettleOutcome(v) {
+    return typeof v === "string" && SETTLE_OUTCOME_WORDS.has(v);
+}
 export function buildCheckpointAnchorHash(token) {
     return createHash("sha256").update(token, "utf8").digest("hex").slice(0, 16);
 }
-function isAuditShutdownCause(v) {
-    return typeof v === "string" && Object.hasOwn(AUDIT_SHUTDOWN_CAUSE_WORDS, v);
-}
-function readShutdownCause(v) {
+function readSettleCause(v) {
     if (v === undefined)
         return { cause: undefined, outOfSet: false };
-    if (isAuditShutdownCause(v))
+    if (isSettleCause(v))
         return { cause: v, outOfSet: false };
     return { cause: undefined, outOfSet: true };
 }
@@ -70,11 +71,11 @@ function readLedgerRecord(u, noteOutOfSetSeat) {
             const approvalId = s("approvalId");
             const settledAtMs = num("settledAtMs");
             const outcomeV = o.outcome;
-            const outcome = outcomeV === "allowed" || outcomeV === "denied" || outcomeV === "expired" ? outcomeV : undefined;
+            const outcome = isSettleOutcome(outcomeV) ? outcomeV : undefined;
             if (approvalId === undefined || settledAtMs === undefined || outcome === undefined)
                 return undefined;
             const settledBy = s("settledBy");
-            const cause = readShutdownCause(o.cause);
+            const cause = readSettleCause(o.cause);
             if (cause.outOfSet)
                 noteOutOfSetSeat();
             return {
@@ -279,7 +280,7 @@ export class FileApprovalAskAuditStore {
         }
     }
     indexSettle(rec) {
-        if (rec.outcome === "expired" && rec.parkRouted === true)
+        if (rec.outcome === SETTLE_OUTCOME.EXPIRED && rec.parkRouted === true)
             this.parkExpired.add(rec.approvalId);
     }
     recordAsk(input) {

package/dist/approval-crash-convergence.d.ts

@@ -1,6 +1,6 @@
 import type { ApprovalAskStore } from "./plugins/approval-ask-store-sql.js";
 import { FileApprovalAskAuditStore } from "./approval-ask-audit-store.js";
-import { type HolderGoneReason } from "./approval-deny-reasons.js";
+import { type HolderGoneCause } from "./approval-deny-reasons.js";
 import { type RunStoreReader } from "./user-input-ledger.js";
 import type { Logger } from "./observability/logger.js";
 /** 启动收敛的读数(进启动日志)。 */
@@ -11,7 +11,7 @@ export interface CrashConvergenceReport {
     readonly inconsistent: number;
     readonly corruptLines: number;
     /** ask 账半场:按成因词计的、本次收成 VOID 的前世 `STREAM_PENDING` 行数。 */
-    readonly asksVoided: Readonly<Record<HolderGoneReason, number>>;
+    readonly asksVoided: Readonly<Record<HolderGoneCause, number>>;
     /** 其中卡信封读不出、成因词是回落(`crashed_before_park`)的行数(同时记 fail-open tag)。 */
     readonly causeUnreadable: number;
 }

package/dist/approval-crash-convergence.js

@@ -2,7 +2,7 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { APPROVAL_ASK_AUDIT_DIR, APPROVAL_ASK_AUDIT_LEDGER, FileApprovalAskAuditStore } from "./approval-ask-audit-store.js";
 import { ApprovalCardEnvelopeSchema } from "./approval-card.js";
-import { VOID_REASONS } from "./approval-deny-reasons.js";
+import { APPROVAL_ENDING_CAUSES } from "./approval-deny-reasons.js";
 import { writerGoneEvidenceFor } from "./user-input-ledger.js";
 import { recordFailOpen } from "./observability/fail-open.js";
 const CONVERGE_PAGE = 500;
@@ -20,7 +20,7 @@ export function openAuditEvidenceForConvergence(live, localDataRoot) {
 export async function convergeCrashedAsksAtBoot(input) {
     const now = input.now ?? Date.now;
     const audited = input.audit?.convergeCrashedAsks() ?? { pending: 0, decided: 0, inconsistent: 0, corruptLines: 0 };
-    const asksVoided = { [VOID_REASONS.HOLDER_CRASHED]: 0, [VOID_REASONS.HOLDER_SHUTDOWN]: 0 };
+    const asksVoided = { [APPROVAL_ENDING_CAUSES.CRASHED_BEFORE_PARK]: 0, [APPROVAL_ENDING_CAUSES.SHUTDOWN_BEFORE_PARK]: 0 };
     let causeUnreadable = 0;
     const store = input.askStore;
     if (store !== undefined) {
@@ -34,9 +34,9 @@ export async function convergeCrashedAsksAtBoot(input) {
                 const envelope = ApprovalCardEnvelopeSchema.safeParse(row.cardJson);
                 if (!envelope.success) {
                     causeUnreadable += 1;
-                    recordFailOpen("server.approval-crash-convergence.cause-unreadable", `ask ${row.askId} (task ${row.taskId}): card envelope unreadable — cause defaulted to ${VOID_REASONS.HOLDER_CRASHED}`);
+                    recordFailOpen("server.approval-crash-convergence.cause-unreadable", `ask ${row.askId} (task ${row.taskId}): card envelope unreadable — cause defaulted to ${APPROVAL_ENDING_CAUSES.CRASHED_BEFORE_PARK}`);
                 }
-                const reason = envelope.success && input.audit !== undefined ? input.audit.causeFor(envelope.data.approvalId) : VOID_REASONS.HOLDER_CRASHED;
+                const reason = envelope.success && input.audit !== undefined ? input.audit.causeFor(envelope.data.approvalId) : APPROVAL_ENDING_CAUSES.CRASHED_BEFORE_PARK;
                 let won;
                 try {
                     won = await store.transitionAsk(row.askId, "STREAM_PENDING", "VOID", { deniedReason: reason, updatedAtMs: now() });
@@ -67,7 +67,7 @@ export async function runBootCrashConvergence(ctx) {
             corruptLines: converged.corruptLines,
             asksVoided: converged.asksVoided,
             causeUnreadable: converged.causeUnreadable,
-            note: "approval asks left pending by the previous process were converged: each such ask is now VOID in the ask ledger (the decision endpoint answers 410 gone.ask with this cause as deniedReason) and is listed under GET /v1/approvals crashConverged when the audit ledger saw it (cause crashed_before_park = the process crashed; cause shutdown_before_park = an orderly shutdown cut the leg off before it closed or before its park committed)",
+            note: "approval asks left pending by the previous process were converged: each such ask is now VOID in the ask ledger (the decision endpoint answers 410 gone.ask with this cause) and is listed under GET /v1/approvals crashConverged when the audit ledger saw it (cause crashed_before_park = the process crashed; cause shutdown_before_park = an orderly shutdown cut the leg off before it closed or before its park committed)",
         });
     }
     return converged;

package/dist/approval-deny-reasons.d.ts

@@ -1,69 +1,181 @@
 /**
- * 流内审批协议([ref] §3.0 对账三约束)的**终态归因词表** —— [ref] 车5。
+ * **审批席「这张卡为什么没被人答」的一只闭集** —— {@link APPROVAL_ENDING_CAUSES}。
  *
- * 两组常量、**两个不相交的值域**(车5 §8 C-1 裁定,与车4 F34 同向):
- *  - {@link DENY_REASONS} —— `DENIED` 终态的归因。v1 是**单员闭集**:`routing_failure_fail_closed`。
- *  - {@link VOID_REASONS} —— `VOID` 终态的归因。
+ * ## 它治的病(同一件事、四张词表、一词多义)
+ * 一张卡没被人答就结束了,今天有四个读面各说各话:审计 settle 行(`expired` 一词盖 TTL 到期 / run 取消 / run 退出清理 / 广播全灭,批内兄弟被撤卡也是同一个词)、
+ * 问账 VOID/DENIED 行(`denied_reason` 列)、晚答 404 的判别位、决断口 409 的码(多种成因借 `approval_binding_mismatch` 一个名)。壳读账写不出「已取消」,
+ * 也分不出「重取坐标再决」与「改答案再决」。收成**一张表、一个词、各面同读**:
+ *  · 审计 settle 行的 `cause`(非人结局必填,人答缺席;`settle(verdict)` 判别联合逼每个非人调用点点名一个)与活卡结局帧 `tool_approval_complete` 的 additive `cause`(同一个词,同一条律);
+ *  · 问账 VOID/DENIED 行的 `denied_reason` 列 → 决断口 410 `gone.ask` 体的 `cause` 与晚答 404 体的 `cause`(读同一列,经唯一读口 {@link causeOfAskRow});
+ *  · `GET /v1/approvals` `crashConverged[].cause`(本表的 {@link HolderGoneCause} 两词子集);
+ *  · 决断口 409 的码:`binding_changed` / `answer_invalid` / `outcome_cell_invalid` 三词各归一个码。`retriable` 不由成因说 —— 三词都出自 core 的
+ *    `checkpoint.invalid_outcome`,由 `http/resume-legs.ts` 的 core 码 → 处置一张表派生(一个意思:卡仍 pending、行重新 park)。
  *
- * 🔴 为什么必须分两组、禁混值域:§3.0 的对账约束②是「**超时永不产生 denial**」,而审计面唯一能证明这条
- * 的东西就是终态 + 归因的组合。人拒恒为 `DECIDED(decision=deny)`(车4 §8),路由失败恒为
- * `DENIED(routing_failure_fail_closed)`,撤卡/取消/遗孤恒为 `VOID(<VOID_REASONS 之一>)`——三者在
- * wire 与审计上全程可分。若两组共用一个值域(或某个值同时可落两种终态),「这条 deny 是人做的、还是
- * 路由失败、还是超时兜底」就再也无法从行上读出来,归因诚实性(§6.1)当场失效。
+ * ## 规则
+ *  · 词表属主一处(本文件);加一个成因 = 加一个词:决断类词 ⇒ 409 码表(`http/resume-legs.ts` 的 `WIRE_CODE_OF_DECISION_REFUSAL`)的穷举编译红,结局类词 ⇒ 读盘词表 {@link SETTLE_CAUSE_WORDS} 的穷举编译红。
+ *  · 成因**只从事实读**:run 行 `errorCode:"cancelled"`、钟到、emit 零接收、停车行 / 问账行的列、`detail.field`;不读拒句散文。
+ *  · 「停驻行的格式比本引擎新」**不是**本表的词:它只有 core 一个来源(`checkpoint.unsupported_version` + `detail.reason:"version_newer"`,原码镜像);服务层不从续跑上下文的写者版本推断成因。
+ *  · **人答的结局(`allowed` / `denied`)没有 cause**:`cause` 在场 ⇔ 非人结局。
+ *  · 落列面:问账行的成因写进 `approval_ask.denied_reason`(VARCHAR(64)),一列按 `state` 承载两种意思 —— VOID / DENIED 行上是**终态成因**,PARKING / PARKED 行上是
+ *    **转 park 的触发成因**;读它只经 {@link causeOfAskRow}(按 state 穷举分派,两张读词表只被它读)。列名将在下一个 DDL 窗按意义改名。
  *
- * 落列面:两组值都写进 `approval_ask.denied_reason`(VARCHAR(64))——列名沿用车1 的 DDL(本车不改列),
- * 但它承载的是**终态归因**而不只是「拒绝理由」。读者靠「值属于哪一组」判别是哪条臂写的,这正是两组
- * 值域不相交这条纪律的用处(`ALL_TERMINAL_REASONS` 的机器判据钉住不相交性)。
- *
- * 写点纪律(grep 钉):全仓 `DENIED` 只有**一个**写点 = 收敛器判据 2 的非取消臂(`approval-reconciler.ts`)。
- * 启动收敛(进程没了)落的是 VOID 不是 DENIED:状态机上 `STREAM_PENDING` 没有到 DENIED 的边(DENIED 只在「已路由去 park」之后),
- * 而承载它的进程没了 = 这条腿死了 = abort 语义。
+ * ## 为什么 `routing_failure_fail_closed` 也在表里(归因诚实性)
+ * 审计面唯一能证明「超时永不产生 denial」的东西是**终态 + 成因**的组合:人拒恒为 `DECIDED(decision=deny)`,路由失败恒为 `DENIED(routing_failure_fail_closed)`,
+ * 撤卡 / 取消 / 遗孤恒为 `VOID(<成因>)` —— 三者在 wire 与审计上全程可分。终态(问账行的 `state`)是判别位,成因词在同一张表里:一个成因只落一种终态
+ * (写点各自的类型固定了这一点:对账器的 `DENIED` 写点只收 {@link ReconcileDenyCause},`VOID` 写点只收 {@link ReconcileVoidCause})。
+ * 全仓 `DENIED` 只有**一个**写点 = 对账器判据 2 的非取消臂(`approval-reconciler.ts`);启动收敛(进程没了)落的是 VOID 不是 DENIED:状态机上
+ * `STREAM_PENDING` 没有到 DENIED 的边(DENIED 只在「已路由去 park」之后),而承载它的进程没了 = 这条腿死了 = abort 语义。
+ */
+import type { AskState } from "./approval-ask-machine.js";
+/**
+ * 审计 settle 行 `outcome` 的三词 —— **全仓唯一**的定义处(wire 契约锚:`tool_approval_complete.outcome` 与审计行同三词)。
+ * `allowed` / `denied` = 一次**决议**(人答,或行上读回来的决议);`expired` = 这次等待**没有等到决议就结束了**(非人结局,恒带 {@link ApprovalEndingCause})。
  */
-/** `DENIED` 终态的归因闭集(v1 单员)。 */
-export declare const DENY_REASONS: {
+export declare const SETTLE_OUTCOME: {
+    readonly ALLOWED: "allowed";
+    readonly DENIED: "denied";
+    readonly EXPIRED: "expired";
+};
+export type SettleOutcome = (typeof SETTLE_OUTCOME)[keyof typeof SETTLE_OUTCOME];
+/** 非人结局的**穷尽**成因(每个非人 `settle` 调用点必须点名一个)。成员的语义随成员。 */
+export declare const APPROVAL_ENDING_CAUSES: {
+    /** 窗到期:这张卡的等待窗(行上一次铸定的绝对 deadline)走完,没有人答。 */
+    readonly TTL_EXPIRED: "ttl_expired";
+    /** emit 广播全灭:两族帧都没送到任何连接(emit 返回零接收)—— 这张卡从未送达任何人。 */
+    readonly BROADCAST_LOST: "broadcast_lost";
+    /** 承载这张卡的流没了:断连强转 park(`parkOpenAsksForTask`,断连臂的事实 = 这个 wire run 的承载流断了;卡曾送达过,只是不会再有人从那条流上答它)。 */
+    readonly STREAM_DISCONNECTED: "stream_disconnected";
     /**
-     * 收敛器判据 2:出处 run 已到**非 suspended 的终局**(completed / blocked / 非取消的 failed)而始终
-     * 没有出现与本 ask 匹配的 checkpoint ⇒ 这只 ask 的投递面永远不会再出现,fail-closed 收 `DENIED`。
-     * 🔴 证据是**行的终局态**(journal 的肯定证据),不是「等够久了」——约束②因此成立。
+     * 这张卡呈不出去:兜底臂(行不可用 / 身份不定 / 悬挂无行,`unattendedOutcome` 的 `persisted_row_unusable` / `ensure_indeterminate` / `unreached_no_row`)—— 持久行证不出属主或读不成,
+     * 本次登记根本没把卡呈到任何投递面;同 askId 的其余本地登记按这个词随行收场。与 `broadcast_lost`(emit 零接收)是两个事实。
      */
-    readonly ROUTING_FAILURE: "routing_failure_fail_closed";
-};
-export type DenyReason = (typeof DENY_REASONS)[keyof typeof DENY_REASONS];
-/** `VOID` 终态的归因闭集。 */
-export declare const VOID_REASONS: {
-    /** 判据 2 的取消分臂(§9 C3):run `failed ∧ errorCode==="cancelled"` ⇒ 取消不是路由失败,收 VOID。 */
+    readonly UNDELIVERABLE: "undeliverable";
+    /** run 被取消:出处 run 的中止信号触发(取消动词 / 非 detach 断连),或对账器读到 run 行 `failed ∧ errorCode==="cancelled"`(判据 2 的取消分臂,§9 C3:取消不是路由失败,收 VOID)。 */
     readonly RUN_CANCELLED: "run_cancelled";
+    /** run 结束清理:承载这张卡的那条腿的作用域退出(正常返回或抛出)时卡还挂着。 */
+    readonly RUN_EXITED: "run_exited";
     /** 判据 2 的取消分臂之二:批行已 `ABORTED`(取消腿打过 `abortBatch`)⇒ 同 abort 语义。 */
     readonly BATCH_ABORTED: "batch_aborted";
+    /** 批内兄弟被赢家的原子撤卡连坐(窗到期赢家把同批其余 `STREAM_PENDING` 兄弟一起撤成 VOID)的「没了」。 */
+    readonly BATCH_SIBLING_WITHDRAWN: "batch_sibling_withdrawn";
     /**
-     * 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`(归因失真)。
+     * 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 的迟到行由收敛器补判——就是这条臂。不这么判的后果:该行滞留到 run 终局,
+     * 然后被判据 2 误报成 `routing_failure_fail_closed`(归因失真)。
      */
     readonly BATCH_BOUND_ELSEWHERE: "batch_bound_elsewhere";
-    /** 判据 4:adhoc 腿(`sessionId === taskId` ∧ `getRun` 无行)窗过 + 宽限 —— 该腿形**结构上**没有
-     *  durable 对账域(一次性 taskId 不进 runStore,park 目的地不可寻址),流死即 abort 语义。
-     *  🔴 落 VOID 不落 DENIED:VOID 不是 denial,约束②不被触碰。 */
-    readonly ADHOC_LEG_NO_DURABLE_DOMAIN: "adhoc_leg_no_durable_domain";
-    /** 判据 5:任何在 `STREAM_APPROVAL_ORPHAN_TTL_MS` 内仍未收敛的 `PARKING` 行(量 immutable 的
-     *  `createdAtMs`,§9 C5)—— 约束①(遗孤最终可判)的最后兜底,带一条 warn。 */
+    /**
+     * 收敛器判据 2:出处 run 已到**非 suspended 的终局**(completed / blocked / 非取消的 failed)而始终没有出现与本 ask 匹配的 checkpoint ⇒ 这只 ask 的投递面永远不会再出现,
+     * fail-closed 收 `DENIED`。🔴 证据是**行的终局态**(journal 的肯定证据),不是「等够久了」——「超时永不产生 denial」因此成立。
+     */
+    readonly ROUTING_FAILURE: "routing_failure_fail_closed";
+    /**
+     * 启动收敛(`approval-crash-convergence.ts`,local 车道):**承载这一问的进程没了** —— 前世进程崩溃 / 被杀,留下的 `STREAM_PENDING` 行在下一次启动、任何卡能开始之前收成 VOID。
+     * 证据是数据根 `LOCK`(前世写者全死),不是「等够久了」。值与 `GET /v1/approvals` `crashConverged[].cause` 是**同一个词**。
+     */
+    readonly CRASHED_BEFORE_PARK: "crashed_before_park";
+    /** 同上,但承载它的腿是被**有序关停**截断的(审计账本上有本腿的关停记号;关停收尾没能在宽限窗内把这张卡结清),或有序关停期间这张卡被改路停驻(settle 行的成因)。 */
+    readonly SHUTDOWN_BEFORE_PARK: "shutdown_before_park";
+    /** 判据 5:任何在 `STREAM_APPROVAL_ORPHAN_TTL_MS` 内仍未收敛的 `PARKING` 行(量 immutable 的 `createdAtMs`,§9 C5)—— 遗孤最终可判的最后兜底,带一条 warn。 */
     readonly ORPHAN_TTL_EXCEEDED: "orphan_ttl_exceeded";
     /**
-     * 启动收敛(`approval-crash-convergence.ts`,local 车道):**承载这一问的进程没了** —— 前世进程崩溃 / 被杀,留下的
-     * `STREAM_PENDING` 行在下一次启动、任何卡能开始之前收成 VOID。证据是数据根 `LOCK`(前世写者全死),不是「等够久了」。
-     * 🔴 值与 `GET /v1/approvals` `crashConverged[].cause` 是**同一个词**(审计店的 `CrashConvergedCause` 从本表取型):
-     * 同一问在两个读面上只有一个成因词。
+     * 判据 4:adhoc 腿(`sessionId === taskId` ∧ `getRun` 无行)窗过 + 宽限 —— 该腿形**结构上**没有 durable 对账域(一次性 taskId 不进 runStore,park 目的地不可寻址),流死即 abort 语义。
+     * 🔴 落 VOID 不落 DENIED:VOID 不是 denial,「超时永不产生 denial」不被触碰。
      */
-    readonly HOLDER_CRASHED: "crashed_before_park";
-    /** 同上,但承载它的腿是被**有序关停**截断的(审计账本上有本腿的关停记号;关停收尾没能在宽限窗内把这张卡结清)。 */
-    readonly HOLDER_SHUTDOWN: "shutdown_before_park";
+    readonly ADHOC_LEG_NO_DURABLE_DOMAIN: "adhoc_leg_no_durable_domain";
+    /** 决议绑的动作 / 输入被换了(core `detail.field` ∈ `boundCallId` / `boundInputHash`,不论写者版本 —— 绑定值由写者引擎铸进卡帧、调用方原样回传、core 等值比较):重取 pending 列表换坐标再决。 */
+    readonly BINDING_CHANGED: "binding_changed";
+    /** 决议体里的 `answer` 不合法(core `detail.field` = `answer`):把答案改对再决。 */
+    readonly ANSWER_INVALID: "answer_invalid";
+    /** 决议体里某一格不合法(`hostDecision` / `approver` / `boundGrantDigest`,或 plan / dry-run 审阅门上 editedPlan / reason 的内容净化被拒):把那一格改对再决。 */
+    readonly OUTCOME_CELL_INVALID: "outcome_cell_invalid";
 };
-export type VoidReason = (typeof VOID_REASONS)[keyof typeof VOID_REASONS];
-/** 「承载这一问的进程没了」的两个成因词(启动收敛写进问账行 `deniedReason`,审计收敛行 `cause` 读同一型)。 */
-export type HolderGoneReason = typeof VOID_REASONS.HOLDER_CRASHED | typeof VOID_REASONS.HOLDER_SHUTDOWN;
-/** 两组的并集(机器判据用:值域不相交 + 列宽 ≤ 64 的钉子在 test/approval-reconciler.test.ts)。 */
-export declare const ALL_TERMINAL_REASONS: readonly string[];
+export type ApprovalEndingCause = (typeof APPROVAL_ENDING_CAUSES)[keyof typeof APPROVAL_ENDING_CAUSES];
+/** 全部成因词(机器判据用:值域互不相同 + 列宽 ≤ 64 的钉子在 test/approval-reconciler.test.ts)。 */
+export declare const ALL_APPROVAL_ENDING_CAUSES: readonly ApprovalEndingCause[];
+/**
+ * 审计 settle 行 `cause` 的读盘词表(S-929 形):{@link SettleCause} 的穷举,`satisfies Record<SettleCause, true>` ⇒ 闭集加一个非决断类的词而本表没跟 = **编译红**(多一个词同样红);
+ * 判定走 `Object.hasOwn`,原型链上的名字不算词。决断类三词({@link DecisionRefusalCause})拒一次决议、不结束一张卡 ⇒ 不是 settle 行的成因,读到它们照词表外处置(计坏行)。
+ * 唯一读者 = {@link isSettleCause}。
+ */
+export declare const SETTLE_CAUSE_WORDS: {
+    readonly ttl_expired: true;
+    readonly broadcast_lost: true;
+    readonly stream_disconnected: true;
+    readonly undeliverable: true;
+    readonly run_cancelled: true;
+    readonly run_exited: true;
+    readonly batch_aborted: true;
+    readonly batch_sibling_withdrawn: true;
+    readonly batch_bound_elsewhere: true;
+    readonly routing_failure_fail_closed: true;
+    readonly crashed_before_park: true;
+    readonly shutdown_before_park: true;
+    readonly orphan_ttl_exceeded: true;
+    readonly adhoc_leg_no_durable_domain: true;
+};
+/** 一个值是不是非人结局的成因词(审计账读盘用这一只判词)。 */
+export declare function isSettleCause(v: unknown): v is SettleCause;
+/** 「承载这一问的进程没了」的两个成因词(启动收敛写进问账行 `denied_reason`,审计收敛行 `cause` 读同一型)。 */
+export type HolderGoneCause = typeof APPROVAL_ENDING_CAUSES.CRASHED_BEFORE_PARK | typeof APPROVAL_ENDING_CAUSES.SHUTDOWN_BEFORE_PARK;
+/** 对账器 `DENIED` 终态的成因(单员:全仓 DENIED 只有一个写点)。 */
+export type ReconcileDenyCause = typeof APPROVAL_ENDING_CAUSES.ROUTING_FAILURE;
+/** 对账器 `VOID` 终态的成因(判据 2 取消分臂 / 批已 ABORTED / bind-once 落选者 / 判据 4 adhoc / 判据 5 遗孤 TTL)。 */
+export type ReconcileVoidCause = typeof APPROVAL_ENDING_CAUSES.RUN_CANCELLED | typeof APPROVAL_ENDING_CAUSES.BATCH_ABORTED | typeof APPROVAL_ENDING_CAUSES.BATCH_BOUND_ELSEWHERE | typeof APPROVAL_ENDING_CAUSES.ADHOC_LEG_NO_DURABLE_DOMAIN | typeof APPROVAL_ENDING_CAUSES.ORPHAN_TTL_EXCEEDED;
+/**
+ * 问账行(`approval_ask`)上**终态成因**能落的词(决断口 410 `gone.ask` 体与晚答 404 体的 `cause` 的值域):对账器的 DENIED / VOID 写点 + 启动收敛 + 店内的 VOID 写点
+ * (取消赢下 VOID ⇒ `run_cancelled` / `run_exited`,兄弟被撤卡 ⇒ `batch_sibling_withdrawn`)。窗到期 / 广播全灭 / 决断类的词只落审计 settle 行或 409 码,不落这一列。
+ */
+export type AskRowEndingCause = ReconcileDenyCause | ReconcileVoidCause | HolderGoneCause | typeof APPROVAL_ENDING_CAUSES.RUN_EXITED | typeof APPROVAL_ENDING_CAUSES.BATCH_SIBLING_WITHDRAWN;
+/** 问账行 `denied_reason` 列在 VOID / DENIED 行上的读词表({@link AskRowEndingCause} 的穷举,`satisfies` ⇒ 子集加词而本表没跟 = 编译红)。唯一读者 = {@link causeOfAskRow}。 */
+export declare const ASK_ROW_ENDING_CAUSE_WORDS: {
+    readonly routing_failure_fail_closed: true;
+    readonly run_cancelled: true;
+    readonly run_exited: true;
+    readonly batch_aborted: true;
+    readonly batch_sibling_withdrawn: true;
+    readonly batch_bound_elsewhere: true;
+    readonly adhoc_leg_no_durable_domain: true;
+    readonly orphan_ttl_exceeded: true;
+    readonly crashed_before_park: true;
+    readonly shutdown_before_park: true;
+};
+/**
+ * `expire` 终局 claim(窗到期 / 广播全灭 / 有序关停把一张卡转投递面 = `PARKING`)赢下时写进这一行 `denied_reason` 的**触发成因**:这一行此后若走到 `DENIED` / `VOID`,终态成因会覆盖它
+ * ({@link AskRowEndingCause});`PARKED` 行的这一格就是「它为什么被转 park」。跨副本的读者(另一进程的悬挂腿轮询、CAS 败方读数)读到 `PARKING` / `PARKED` 时靠它归因,
+ * 不替没写的行猜一个词。
+ */
+export type ParkTriggerCause = typeof APPROVAL_ENDING_CAUSES.TTL_EXPIRED | typeof APPROVAL_ENDING_CAUSES.BROADCAST_LOST | typeof APPROVAL_ENDING_CAUSES.STREAM_DISCONNECTED | typeof APPROVAL_ENDING_CAUSES.UNDELIVERABLE | typeof APPROVAL_ENDING_CAUSES.SHUTDOWN_BEFORE_PARK;
+/** 问账行 `denied_reason` 在 `PARKING` / `PARKED` 行上的读词表({@link ParkTriggerCause} 的穷举)。唯一读者 = {@link causeOfAskRow}。 */
+export declare const PARK_TRIGGER_CAUSE_WORDS: {
+    readonly ttl_expired: true;
+    readonly broadcast_lost: true;
+    readonly stream_disconnected: true;
+    readonly undeliverable: true;
+    readonly shutdown_before_park: true;
+};
+/** 问账行成因的读数:`kind` 说这一个词在这一行上是哪种意思(终态成因 / 转 park 的触发成因)。 */
+export type AskRowCause = {
+    readonly kind: "ending";
+    readonly cause: AskRowEndingCause;
+} | {
+    readonly kind: "park_trigger";
+    readonly cause: ParkTriggerCause;
+};
+/**
+ * 🔴 **问账行成因的唯一读口**:`denied_reason` 一列按 `state` 承载两种意思,本函数按 `state` 穷举分派(加状态 ⇒ 这里编译红),读者不自己先判 state 再查表:
+ *  · `VOID` / `DENIED` ⇒ 终态成因({@link AskRowEndingCause};决断口 410、晚答 404、CAS 败方读数、悬挂腿的轮询读这一种);
+ *  · `PARKING` / `PARKED` ⇒ 转 park 的触发成因({@link ParkTriggerCause};跨副本的悬挂腿与 CAS 败方读这一种);
+ *  · `DECIDED` / `STREAM_PENDING` / `absent`(败方读数的「行不在」)⇒ 无成因。
+ * 列值 `null` / 键缺席(没写归因的存量行)或与 state 不配的词(手改 / 将来版本写的词)⇒ `undefined`(读面缺席即缺席,不替没写的行编一个成因)。返回纯数据。
+ */
+export declare function causeOfAskRow(row: {
+    readonly state: AskState | "absent";
+    readonly deniedReason?: string | null;
+}): AskRowCause | undefined;
+/** 非人**结局**的成因(审计 settle 行 `cause`、活卡结局帧 `tool_approval_complete.cause`):闭集去掉决断口 409 的三个词({@link DecisionRefusalCause})—— 那三个词不结束一张卡,只拒一次决议。 */
+export type SettleCause = Exclude<ApprovalEndingCause, DecisionRefusalCause>;
+/** 决断口 409 的成因子集(core 的 `detail.field` → 码;每词一个码,见 `http/resume-legs.ts`)。 */
+export type DecisionRefusalCause = typeof APPROVAL_ENDING_CAUSES.BINDING_CHANGED | typeof APPROVAL_ENDING_CAUSES.ANSWER_INVALID | typeof APPROVAL_ENDING_CAUSES.OUTCOME_CELL_INVALID;
 //# sourceMappingURL=approval-deny-reasons.d.ts.map

package/dist/approval-deny-reasons.js

@@ -1,14 +1,85 @@
-export const DENY_REASONS = {
-    ROUTING_FAILURE: "routing_failure_fail_closed",
-};
-export const VOID_REASONS = {
+export const SETTLE_OUTCOME = { ALLOWED: "allowed", DENIED: "denied", EXPIRED: "expired" };
+export const APPROVAL_ENDING_CAUSES = {
+    TTL_EXPIRED: "ttl_expired",
+    BROADCAST_LOST: "broadcast_lost",
+    STREAM_DISCONNECTED: "stream_disconnected",
+    UNDELIVERABLE: "undeliverable",
     RUN_CANCELLED: "run_cancelled",
+    RUN_EXITED: "run_exited",
     BATCH_ABORTED: "batch_aborted",
+    BATCH_SIBLING_WITHDRAWN: "batch_sibling_withdrawn",
     BATCH_BOUND_ELSEWHERE: "batch_bound_elsewhere",
-    ADHOC_LEG_NO_DURABLE_DOMAIN: "adhoc_leg_no_durable_domain",
+    ROUTING_FAILURE: "routing_failure_fail_closed",
+    CRASHED_BEFORE_PARK: "crashed_before_park",
+    SHUTDOWN_BEFORE_PARK: "shutdown_before_park",
     ORPHAN_TTL_EXCEEDED: "orphan_ttl_exceeded",
-    HOLDER_CRASHED: "crashed_before_park",
-    HOLDER_SHUTDOWN: "shutdown_before_park",
+    ADHOC_LEG_NO_DURABLE_DOMAIN: "adhoc_leg_no_durable_domain",
+    BINDING_CHANGED: "binding_changed",
+    ANSWER_INVALID: "answer_invalid",
+    OUTCOME_CELL_INVALID: "outcome_cell_invalid",
+};
+export const ALL_APPROVAL_ENDING_CAUSES = Object.values(APPROVAL_ENDING_CAUSES);
+export const SETTLE_CAUSE_WORDS = {
+    ttl_expired: true,
+    broadcast_lost: true,
+    stream_disconnected: true,
+    undeliverable: true,
+    run_cancelled: true,
+    run_exited: true,
+    batch_aborted: true,
+    batch_sibling_withdrawn: true,
+    batch_bound_elsewhere: true,
+    routing_failure_fail_closed: true,
+    crashed_before_park: true,
+    shutdown_before_park: true,
+    orphan_ttl_exceeded: true,
+    adhoc_leg_no_durable_domain: true,
+};
+export function isSettleCause(v) {
+    return typeof v === "string" && Object.hasOwn(SETTLE_CAUSE_WORDS, v);
+}
+export const ASK_ROW_ENDING_CAUSE_WORDS = {
+    routing_failure_fail_closed: true,
+    run_cancelled: true,
+    run_exited: true,
+    batch_aborted: true,
+    batch_sibling_withdrawn: true,
+    batch_bound_elsewhere: true,
+    adhoc_leg_no_durable_domain: true,
+    orphan_ttl_exceeded: true,
+    crashed_before_park: true,
+    shutdown_before_park: true,
+};
+function isAskRowEndingCause(v) {
+    return Object.hasOwn(ASK_ROW_ENDING_CAUSE_WORDS, v);
+}
+export const PARK_TRIGGER_CAUSE_WORDS = {
+    ttl_expired: true,
+    broadcast_lost: true,
+    stream_disconnected: true,
+    undeliverable: true,
+    shutdown_before_park: true,
 };
-export const ALL_TERMINAL_REASONS = [...Object.values(DENY_REASONS), ...Object.values(VOID_REASONS)];
+function isParkTriggerCause(v) {
+    return Object.hasOwn(PARK_TRIGGER_CAUSE_WORDS, v);
+}
+export function causeOfAskRow(row) {
+    const stored = row.deniedReason;
+    switch (row.state) {
+        case "VOID":
+        case "DENIED":
+            return stored !== null && stored !== undefined && isAskRowEndingCause(stored) ? { kind: "ending", cause: stored } : undefined;
+        case "PARKING":
+        case "PARKED":
+            return stored !== null && stored !== undefined && isParkTriggerCause(stored) ? { kind: "park_trigger", cause: stored } : undefined;
+        case "DECIDED":
+        case "STREAM_PENDING":
+        case "absent":
+            return undefined;
+        default: {
+            const unhandled = row.state;
+            throw new Error(`causeOfAskRow: unhandled ask row state ${String(unhandled)}`);
+        }
+    }
+}
 //# sourceMappingURL=approval-deny-reasons.js.map

package/dist/approval-policy-settlement.d.ts

@@ -23,9 +23,12 @@
  */
 import type { ApprovalAskStore, AskRow, AskTerminalClaimOutcome } from "./plugins/approval-ask-store-sql.js";
 import type { UnattendedApprovalPolicy } from "./tool-approval.js";
+import type { ParkTriggerCause } from "./approval-deny-reasons.js";
 /**
  * 按部署政策给这一只 ask 行打原子终局 claim(见文件头:四个调用点、两个意图、答案自足)。`row` 只取 scope 两维 ——
  * `batchId` 必须是**行上**的批(幂等命中的存量行可能是别的政策 / 旧版本铸的整腿批,错 scope 的 claim 如实 `absent`)。
  */
-export declare function settleByPolicy(store: Pick<ApprovalAskStore, "claimTerminal">, row: Pick<AskRow, "askId" | "batchId">, policy: UnattendedApprovalPolicy): Promise<AskTerminalClaimOutcome>;
+export declare function settleByPolicy(store: Pick<ApprovalAskStore, "claimTerminal">, row: Pick<AskRow, "askId" | "batchId">, policy: UnattendedApprovalPolicy, 
+/** 转 park 的触发成因(窗到期 / 广播全灭 / 有序关停):`park` 政策的 `expire` 赢下 PARKING 时随同一步写进行(`denied_reason`),跨副本的读者据它归因;`deny` 政策落的是一条决议,不带。 */
+cause: ParkTriggerCause): Promise<AskTerminalClaimOutcome>;
 //# sourceMappingURL=approval-policy-settlement.d.ts.map

package/dist/approval-policy-settlement.js

@@ -10,7 +10,8 @@ function unattendedClaimIntent(policy) {
         }
     }
 }
-export function settleByPolicy(store, row, policy) {
-    return store.claimTerminal(row.askId, row.batchId, unattendedClaimIntent(policy));
+export function settleByPolicy(store, row, policy, cause) {
+    const intent = unattendedClaimIntent(policy);
+    return store.claimTerminal(row.askId, row.batchId, intent, intent === "expire" ? { cause } : undefined);
 }
 //# sourceMappingURL=approval-policy-settlement.js.map

package/dist/approval-reconciler.d.ts

@@ -5,7 +5,7 @@ import type { CheckpointAskCandidate } from "./plugins/checkpoint-store-sql.js";
 import { type RunRecord } from "./plugins/store-contracts.js";
 import type { Logger } from "./observability/logger.js";
 import type { Metrics } from "./observability/metrics.js";
-import { type DenyReason, type VoidReason } from "./approval-deny-reasons.js";
+import { type ReconcileDenyCause, type ReconcileVoidCause } from "./approval-deny-reasons.js";
 import { type ApprovalRevokeFrame } from "./approval-card.js";
 import type { ParkCommitWatch } from "./plugins/park-commit-watch.js";
 /** 判据表 v2 的一次判定结果(纯数据;执行器按 kind 分派到店面的一次 CAS)。 */
@@ -18,10 +18,10 @@ export type ReconcileAction = {
     };
 } | {
     kind: "deny";
-    reason: DenyReason;
+    reason: ReconcileDenyCause;
 } | {
     kind: "void";
-    reason: VoidReason;
+    reason: ReconcileVoidCause;
 } | {
     kind: "hold";
 };

package/dist/approval-reconciler.js

@@ -1,7 +1,7 @@
 import { CANCELLED_CODE } from "./run-cancel-context.js";
 import { settleByPolicy } from "./approval-policy-settlement.js";
 import { isTerminalRunStatus } from "./plugins/store-contracts.js";
-import { DENY_REASONS, VOID_REASONS } from "./approval-deny-reasons.js";
+import { APPROVAL_ENDING_CAUSES } from "./approval-deny-reasons.js";
 import { buildRevokeFrame } from "./approval-card.js";
 import { encodeCheckpointScope } from "./security.js";
 const RECONCILE_STORE_TIMEOUT_MS = 10_000;
@@ -61,21 +61,21 @@ export function decideReconcileAction(input) {
         }
     }
     if (batchState === "ABORTED")
-        return { kind: "void", reason: VOID_REASONS.BATCH_ABORTED };
+        return { kind: "void", reason: APPROVAL_ENDING_CAUSES.BATCH_ABORTED };
     if (batchState === "ROUTING_BOUND" && input.batchBoundAskId != null && input.batchBoundAskId !== ask.askId) {
-        return { kind: "void", reason: VOID_REASONS.BATCH_BOUND_ELSEWHERE };
+        return { kind: "void", reason: APPROVAL_ENDING_CAUSES.BATCH_BOUND_ELSEWHERE };
     }
     if (run !== null && isTerminalRunStatus(run.status)) {
         if (run.status === "failed" && run.errorCode === CANCELLED_CODE) {
-            return { kind: "void", reason: VOID_REASONS.RUN_CANCELLED };
+            return { kind: "void", reason: APPROVAL_ENDING_CAUSES.RUN_CANCELLED };
         }
-        return { kind: "deny", reason: DENY_REASONS.ROUTING_FAILURE };
+        return { kind: "deny", reason: APPROVAL_ENDING_CAUSES.ROUTING_FAILURE };
     }
     if (run === null && ask.sessionId === ask.taskId && nowMs > ask.expiresAtMs + adhocGraceMs) {
-        return { kind: "void", reason: VOID_REASONS.ADHOC_LEG_NO_DURABLE_DOMAIN };
+        return { kind: "void", reason: APPROVAL_ENDING_CAUSES.ADHOC_LEG_NO_DURABLE_DOMAIN };
     }
     if (nowMs - ask.createdAtMs >= orphanTtlMs)
-        return { kind: "void", reason: VOID_REASONS.ORPHAN_TTL_EXCEEDED };
+        return { kind: "void", reason: APPROVAL_ENDING_CAUSES.ORPHAN_TTL_EXCEEDED };
     void candidates;
     return { kind: "hold" };
 }
@@ -157,10 +157,10 @@ export function createApprovalReconciler(deps) {
                 const won = await withDeadline(askStore.transitionAsk(ask.askId, "PARKING", "VOID", { deniedReason: action.reason, updatedAtMs: nowMs }), "transitionAsk(VOID)");
                 if (!won)
                     return { outcome: "held", match: gateMatch };
-                if (action.reason === VOID_REASONS.ORPHAN_TTL_EXCEEDED) {
+                if (action.reason === APPROVAL_ENDING_CAUSES.ORPHAN_TTL_EXCEEDED) {
                     warn("approval_ask_orphan_voided", { askId: ask.askId, taskId: ask.taskId, ageMs: nowMs - ask.createdAtMs, ttlMs: orphanTtlMs });
                 }
-                revoke(ask, [ask.askId], action.reason === VOID_REASONS.BATCH_BOUND_ELSEWHERE ? "superseded_by_park" : "aborted", nowMs);
+                revoke(ask, [ask.askId], action.reason === APPROVAL_ENDING_CAUSES.BATCH_BOUND_ELSEWHERE ? "superseded_by_park" : "aborted", nowMs);
                 return { outcome: "voided", match: gateMatch };
             }
             case "hold": {
@@ -274,7 +274,7 @@ export function createApprovalReconciler(deps) {
                 if (row.expiresAtMs + pendingGraceMs >= nowMs)
                     continue;
                 try {
-                    const res = await withDeadline(settleByPolicy(askStore, row, unattendedPolicy), "claimTerminal(orphan)");
+                    const res = await withDeadline(settleByPolicy(askStore, row, unattendedPolicy, APPROVAL_ENDING_CAUSES.TTL_EXPIRED), "claimTerminal(orphan)");
                     if (!res.claimed)
                         continue;
                     stats.orphansExpired += 1;

package/dist/approval.d.ts

@@ -58,7 +58,7 @@ export declare function singleUserAutoAcceptBaselineApplies(config: GateIntentVi
  *    HIGH;与 env 墓碑族同谱系)。v4.3.0 的轮询门形(APPROVAL_REQUIRE + DB backend + DURABLE_APPROVAL 未设)在
  *    5.0.0 只剩 core 每任务 warn——**原先拦、现在放**(方向反转)。「留 undefined 让 core warn」对新配置是
  *    曝露误配,对升级存量是门静默消失,后者必须响亮。
- *  · **热路径**(S-668 波 2 ④,`config-center/apply-effective.ts` 的审批组 stage):对**候选视图**
+ *  · **热路径**(S-668 波 2 ④,`web-admin-client/apply-effective.ts` 的审批组 stage):对**候选视图**
  *    (活配置 + 候选名单)判,拒因 ⇒ 审批组**整组拒**、活配置零变化、世代账停旧代。进程在跑,拒启不是选项;
  *    而放行一份「没有 checkpoint 店可停车」的名单 = 单用户 auto-accept 基线仍在、名单静默不生效。
  *  · **每个任务的装配**(S-1144,`boot/resolve-spec.ts` 的 `resolveSpec` 头一道):对**活配置**判,拒因 ⇒ 请求 501

package/dist/approval.js

@@ -58,7 +58,7 @@ export function buildForceDurableGateInertNotice(input) {
         event: "center_force_durable_gate_inert",
         fields: {
             durableApproval: input.durableApproval,
-            note: "this deployment resolves per-principal entitlements from config-center, but it has NO checkpoint store " +
+            note: "this deployment resolves per-principal entitlements from web-admin, but it has NO checkpoint store " +
                 (input.durableApproval
                     ? "(DURABLE_APPROVAL=true, yet the configured backend exposes no checkpoint face)"
                     : "(DURABLE_APPROVAL is off)") +

package/dist/audit.d.ts

@@ -48,7 +48,7 @@ export declare function buildSessionAuditLocal(root: string, sessionId: string):
  * 🔴 **会话视图的读面口 —— `GET /v1/sessions/:id` 的全部取法(整读 / `?tail` / `?before` / `?blobCap` / `?message=N`)共用这一只**。
  * 次序 = **选 → 脱 → 截**(路由 `http/routes/sessions.ts`):整条消息的选窗不切字符串,先选窗不改任何一条的脱敏读数、只把脱敏的量降到选中的那几条;
  * `blobCap` 的截断会切字符串(预览切在密钥中间,半截密钥认不出来)⇒ 截断恒在脱敏之后。
- * `messages` 缺席 ⇒ 不铸键;非数组 ⇒ 深扫;其余键(`owner` / `promptEpoch` / `model` …)逐字。字节没变 ⇒ **同一引用**。
+ * `messages` 缺席 ⇒ 不铸键;非数组 ⇒ 深扫;其余键(`owner` / `promptEpoch` / `model` …)逐字。每条消息都回同一引用 ⇒ **同一引用**(带结构叶的消息恒重建,见 {@link readByTable})。
  */
 export declare function redactSessionViewForRead<V extends object>(view: V): V;
 /** Window `messages` — `tail=N` (last N) or `before=<offset>&limit=N` ([max(0,before-N), before)).