@sema-agent/server 7.2.0 → 7.3.0

package/dist/approval-card.js

@@ -0,0 +1,237 @@
+/**
+ * #151 车3(design/172 流内审批协议)—— **审批卡的 schema 属主 + 重放腿的纯函数**。
+ *
+ * 本模块只出两样东西,**都不带 IO、不带定时器、不发帧**:
+ *  1. `ApprovalCardSchema` / `ApprovalCardEnvelopeSchema` —— 落库 `approval_asks.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";
+/** 模型自由文本(`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;
+/** 已 redact 的 ask 文案上限(`AskRequest.message` 的投影)。 */
+const MAX_MESSAGE = 8192;
+/**
+ * design/172 §3.1 的**中性投影**——呈卡面看到的全部内容,与 wire 面的既有 `ToolApprovalFrame` 解耦。
+ *
+ * `risk` 的三态形(设计稿 §14.1,core [2794] 回帖后定):`AskRequest.riskAxes?.{irreversible,egress}`
+ * 是 **additive optional**,**缺席 = 引擎未判,不是「安全」**。所以两轴在这里是 `optional()`:
+ * `true` / `false` / **缺席(未标注)** 三态各自可分,投影层**禁把缺席折算成 false** —— 那等于替引擎
+ * 打包票。`requiresRealApproval` 是 core 今天唯一在场的粗粒度安全类标记(必填,车2 已有真值来源)。
+ */
+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(),
+    /** 委派出处(子代 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(),
+    delegation: z
+        .object({
+        parentToolCallId: z.string().max(MAX_IDENT),
+        depth: z.number().int().nonnegative(),
+        agentName: z.string().max(MAX_AGENT_NAME).optional(),
+    })
+        .optional(),
+})
+    .strict();
+/**
+ * `approval_asks.card_json` 里真正存的东西(设计稿 §6.2)。存**信封**而不是裸卡的理由:重放帧要回填
+ * 车2 铸的 `approvalId`(wire 面的回决通道桥 + 消费端与并行 `tool_approval` 帧的去重键),而它不属于
+ * 「卡的内容」——放进卡里会让 schema 的语义边界糊掉。`schemaVersion` 是形的版本闩(与行上的
+ * `schema_version` 列同值,列供 SQL 侧过滤,信封里这份供读面在解出内容**之前**判形)。
+ */
+export const ApprovalCardEnvelopeSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    approvalId: z.string(),
+    card: ApprovalCardSchema,
+})
+    .strict();
+/** 本车铸的信封形版本(写侧=刀 3b,读侧=本文件)。 */
+export const APPROVAL_CARD_SCHEMA_VERSION = 1;
+/**
+ * core 的风险轴(`AskRequest.riskAxes`,[2829]/§14.1)的**边界窄读**。
+ *
+ * 🔴 为什么是 `safeParse` 而不是读 `req.riskAxes`:树上的 core d.ts(5.13.0)**还没有这个键**,
+ * 而字段形已由 core 认领(5.14.0-pre)。窄读让**编译与行为解耦**——今天编译得过、缺席=未标注;
+ * 终版到货后同一行代码自然点亮,不需要回来改一个字。裸 `as` 转型会在两个方向上都出错:既绕过了
+ * 宪法 [2704] 的「边界必 schema」,也会在 core 真发出一个形状不同的键时静默把垃圾投上卡面。
+ *
+ * 未知键被 zod 默认 strip(此处**故意不 `.strict()`**:core additive 加轴时不该让整只 ask 的卡面塌掉);
+ * 形不合(如 `irreversible: "yes"`)⇒ 整个 safeParse 失败 ⇒ 按**缺席**处置 = 「未标注」,
+ * 绝不折算成 `false`(那等于替引擎打包票,§14.1 明令)。
+ */
+const RiskAxesEnvelopeSchema = z.object({
+    riskAxes: z
+        .object({
+        irreversible: z.boolean().optional(),
+        egress: z.boolean().optional(),
+    })
+        .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` 是 core 今天
+ * 唯一在场的粗粒度安全类标记,缺席 = 这不是一次安全类 ask(core 的铸造点语义,不是我们的折算)。
+ */
+export function buildApprovalCard(source, req, requiresRealApproval) {
+    const axes = RiskAxesEnvelopeSchema.safeParse(req);
+    const riskAxes = axes.success ? axes.data.riskAxes : undefined;
+    const toolCallId = clip(source.toolCallId, MAX_IDENT);
+    const sourceTaskId = clip(source.sourceTaskId, MAX_IDENT);
+    const sourceAgentName = clip(source.sourceAgentName, MAX_AGENT_NAME);
+    return {
+        toolName: clip(source.toolName, MAX_IDENT) ?? "",
+        message: clip(source.message, MAX_MESSAGE) ?? "",
+        ...(source.argsOmitted === true ? { argsOmitted: true } : source.args !== undefined ? { args: source.args } : {}),
+        ...(toolCallId !== undefined ? { toolCallId } : {}),
+        risk: {
+            ...(riskAxes?.irreversible !== undefined ? { irreversible: riskAxes.irreversible } : {}),
+            ...(riskAxes?.egress !== undefined ? { egress: riskAxes.egress } : {}),
+            requiresRealApproval,
+        },
+        ...(source.fromSubagent === true ? { fromSubagent: true } : {}),
+        ...(sourceTaskId !== undefined ? { sourceTaskId } : {}),
+        ...(sourceAgentName !== undefined ? { sourceAgentName } : {}),
+        ...(source.delegation
+            ? {
+                delegation: {
+                    parentToolCallId: clip(source.delegation.parentToolCallId, MAX_IDENT) ?? "",
+                    depth: source.delegation.depth,
+                    ...(source.delegation.agentName !== undefined ? { agentName: clip(source.delegation.agentName, MAX_AGENT_NAME) ?? "" } : {}),
+                },
+            }
+            : {}),
+    };
+}
+/** 落库信封的纯构造(写侧;读侧 = `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",
+        schemaVersion: APPROVAL_CARD_SCHEMA_VERSION,
+        askId: input.askId,
+        taskId: input.taskId,
+        kind: "permission",
+        card: input.card,
+        expiresAtMs: input.expiresAtMs,
+        expiresInMs: Math.max(0, input.expiresAtMs - input.nowMs),
+        serverNowMs: input.nowMs,
+        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)
+        return undefined;
+    return {
+        type: "approval_request",
+        schemaVersion: 1,
+        askId: row.askId,
+        taskId: row.taskId,
+        kind: "permission",
+        card: parsed.data.card,
+        expiresAtMs: row.expiresAtMs,
+        expiresInMs: Math.max(0, row.expiresAtMs - nowMs),
+        serverNowMs: 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;
+    for (const row of rows) {
+        const frame = buildReplayFrame(row, nowMs);
+        if (frame === undefined)
+            skipped += 1;
+        else
+            frames.push(frame);
+    }
+    const cap = Math.max(0, 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 }));
+}
+//# sourceMappingURL=approval-card.js.map

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

@@ -0,0 +1,56 @@
+/**
+ * 流内审批协议(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_asks.denied_reason`(VARCHAR(64))——列名沿用车1 的 DDL(本车不改列),
+ * 但它承载的是**终态归因**而不只是「拒绝理由」。读者靠「值属于哪一组」判别是哪条臂写的,这正是两组
+ * 值域不相交这条纪律的用处(`ALL_TERMINAL_REASONS` 的机器判据钉住不相交性)。
+ *
+ * 写点纪律(grep 钉):全仓 `DENIED` 只有**一个**写点 = 收敛器判据 2 的非取消臂(`approval-reconciler.ts`)。
+ */
+/** `DENIED` 终态的归因闭集(v1 单员)。 */
+export declare const DENY_REASONS: {
+    /**
+     * 收敛器判据 2:出处 run 已到**非 suspended 的终局**(completed / blocked / 非取消的 failed)而始终
+     * 没有出现与本 ask 匹配的 checkpoint ⇒ 这只 ask 的投递面永远不会再出现,fail-closed 收 `DENIED`。
+     * 🔴 证据是**行的终局态**(journal 的肯定证据),不是「等够久了」——约束②因此成立。
+     */
+    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 RUN_CANCELLED: "run_cancelled";
+    /** 判据 2 的取消分臂之二:批行已 `ABORTED`(取消腿打过 `abortBatch`)⇒ 同 abort 语义。 */
+    readonly 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`(归因失真)。
+     */
+    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。 */
+    readonly ORPHAN_TTL_EXCEEDED: "orphan_ttl_exceeded";
+};
+export type VoidReason = (typeof VOID_REASONS)[keyof typeof VOID_REASONS];
+/** 两组的并集(机器判据用:值域不相交 + 列宽 ≤ 64 的钉子在 test/approval-reconciler.test.ts)。 */
+export declare const ALL_TERMINAL_REASONS: readonly string[];
+//# sourceMappingURL=approval-deny-reasons.d.ts.map

package/dist/approval-deny-reasons.js

@@ -0,0 +1,54 @@
+/**
+ * 流内审批协议(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_asks.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-reconciler.d.ts

@@ -0,0 +1,167 @@
+/**
+ * 流内审批协议(design/172 §3.0)的**对账收敛器** —— #151 车5。
+ *
+ * 职责一句话:把 `PARKING`(窗到期中选、正在转投递面)这个**唯一的非终态中间态**收敛成
+ * `PARKED | DENIED | VOID`,并在崩溃后补位那些没人打 expire 的孤儿 `STREAM_PENDING` 行。
+ *
+ * ── 判据表 v2(设计稿 §9 尾的五臂汇总,逐字落地;每臂注读口)────────────────────────────────────────
+ *  ① **identity ∧ hash 双等** ⇒ `bindBatch`(判别式返回;`ok:false` ⇒ 降级续判)
+ *     identity = (scope=owner, sessionId, toolCallId, 因果下界 `cp.createdAtMs ≥ ask.createdAtMs`)
+ *     ∧ `cp.boundInputHash === ask.boundInputHash`,**任一侧 hash 缺席 = 不命中**(§9 C2:同 session 内
+ *     `toolCallId` 会被网关重用,只靠 identity 会把旧 ask PARK 到别人的 resume 坐标上,而 `PARKED` 是
+ *     不可回滚的终态)。读口 = `findCheckpointCandidatesForAsk`(§9 C4 窄谓词精确查,无分页假阴性);
+ *     `unparseable` 候选**视同不匹配**(单行读不出不许打断整段扫描,§8 C-6)。
+ *  ② run 终局分臂(读口 `runStore.getRun`):`status ∈ {completed, failed, blocked}`(§8 A-1 词表修正 ——
+ *     `cancelled` 不是 run 状态,取消 = `failed` + `errorCode`)——
+ *       - `failed ∧ errorCode === "cancelled"`,或批行已 `ABORTED` ⇒ `VOID`(取消不是路由失败,§9 C3);
+ *       - 其余终局 ⇒ `DENIED(routing_failure_fail_closed)`。**全仓唯一的 DENIED 写点**(grep 钉)。
+ *  ②′ **bind-once 落选者**(codex round2 R2-3 增补,排在 ② 之前判):批已 `ROUTING_BOUND` 且中选者是
+ *     兄弟 ⇒ `VOID(batch_bound_elsewhere)` —— 迟到进 PARKING 的行(`bindBatch` 的原子事务连坐不到它)
+ *     结构上再也赢不了 bind,当下即可判;不判会让它滞留到 run 终局再被 ② 误报成路由失败。
+ *  ③ else(run 还在跑 / suspended / needs_review / 无行且不满足 ④)⇒ **保持 PARKING** + `deferReconcile`
+ *     touch(推 `updated_at_ms` 排到队尾,配合 `listByState` 的 `ORDER BY updated_at_ms ASC` 解队头堵塞,
+ *     §8 D-4 / §9 C5)。**超时永不产生终态 denial**(约束②)。
+ *  ④ adhoc 双谓词(`sessionId === taskId` ∧ `getRun` 无行,§8 C-2)∧ 窗过 + `ADHOC_GRACE` ⇒ `VOID`
+ *     (归因 `adhoc_leg_no_durable_domain`)。
+ *  ⑤ `createdAtMs` 量的 `ORPHAN_TTL` ⇒ `VOID(orphan_ttl_exceeded)` + warn ——「任何未在 TTL 内收敛的
+ *     PARKING」的最后兜底(§8 A-1 放宽形,不限「getRun 无行」),约束①(遗孤最终可判)。
+ *     🔴 TTL 一律量 immutable 的 `createdAtMs`/`expiresAtMs`,**绝不量 `updatedAtMs`**(它被 ③ 的队列
+ *     轮转每轮刷新,量它的 TTL 永不到期,§9 C5)。
+ *
+ * ── 三条铁则 ────────────────────────────────────────────────────────────────────────────────────
+ *  1. **一经发布的终态不改义**:本模块只从 `PARKING`/`STREAM_PENDING` 出发,`PARKED/DECIDED/DENIED/VOID`
+ *     的行永不再被碰(CAS 的 `WHERE state=?` 谓词是机器保证,不靠调用序自觉)。
+ *  2. **幂等可重放**:两副本同扫无害——每条转移都是带 `from` 态的 CAS,单赢者;输者本轮什么都不做。
+ *  3. **宁可不命中,绝不错配**:判别不出(hash 缺席 / 候选 `unparseable` / 列与 blob 矛盾)一律落 ②③⑤,
+ *     绝不发一张别人的 resume 凭据。
+ *
+ * 命名(CLAUDE.md 工厂命名律):`decideReconcileAction`/`selectGateCandidate` 是纯判定函数;
+ * `createApprovalReconciler` 返回带方法的活对象 ⇒ `create*`。
+ */
+import type { AskRow, ApprovalAskStore } from "./plugins/approval-ask-store-sql.js";
+import type { BatchState } from "./approval-ask-machine.js";
+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 ApprovalRevokeFrame } from "./approval-card.js";
+/** 判据表 v2 的一次判定结果(纯数据;执行器按 kind 分派到店面的一次 CAS)。 */
+export type ReconcileAction = {
+    kind: "bind";
+    gate: {
+        gateToken: string;
+        gateBoundCallId: string | null;
+        gateBoundInputHash: string | null;
+    };
+} | {
+    kind: "deny";
+    reason: DenyReason;
+} | {
+    kind: "void";
+    reason: VoidReason;
+} | {
+    kind: "hold";
+};
+/** {@link decideReconcileAction} 的入参(全部是**已经读好的事实**——纯函数不碰 IO)。 */
+export interface ReconcileInput {
+    ask: AskRow;
+    /** 判据 1 的候选集(读口已按 scope+session+toolCallId+sinceMs 精确查);无 checkpoint 面 ⇒ 空数组。 */
+    candidates: readonly CheckpointAskCandidate[];
+    /** 出处 run 行;`null` = 无行(被 reap / 从未建 / adhoc 腿)。 */
+    run: RunRecord | null;
+    /** 批行当前态;`null` = 本轮未探(还没走到需要它的臂)。`"MISSING"` = 批行不存在。 */
+    batchState: BatchState | "MISSING" | null;
+    /** 批的中选者(`bound_ask_id`);`ROUTING_BOUND` 臂靠它分「中选的是我」与「中选的是兄弟」两种处置。
+     *  缺席/未知 = `null`(与 `batchState: null` 同栏:未探到就不据它下判)。 */
+    batchBoundAskId?: string | null;
+    nowMs: number;
+    adhocGraceMs: number;
+    orphanTtlMs: number;
+    /** `false` ⇒ 跳过判据 1(本轮已经试过 `bindBatch` 且失败,降级续判 ②③④⑤)。缺省 `true`。 */
+    allowBind?: boolean;
+}
+/**
+ * 判据 1 的**硬谓词**(纯函数,§9 C2 + §8 D-2)。
+ *
+ * 返回选中的候选,或 `undefined` = 不命中。逐条:
+ *  - `unparseable` 候选直接出局(读不出 ⇒ 不确定 ⇒ 不命中);
+ *  - `boundCallId` 必须逐字等于 `ask.toolCallId`(读口已按它查,这里是纵深防御);
+ *  - **因果下界**:`cp.createdAtMs >= ask.createdAtMs`(park 不可能早于它要 park 的那次 ask);
+ *  - **hash 双等**:两侧都必须在场且相等 —— 任一侧缺席即不命中(禁「能取到时才比」的可选谓词)。
+ *
+ * 多候选时的取舍:优先 `status === "pending"`(活着的那张 gate),否则取最早的一条(读口按
+ * `created_at ASC` 返回)。两者都满足全部硬谓词,选谁都不会错配;取 pending 只是让 `PARKED` 行落到
+ * 一个还能被 resume 的坐标上,对壳更有用。
+ */
+export declare function selectGateCandidate(ask: AskRow, candidates: readonly CheckpointAskCandidate[]): CheckpointAskCandidate | undefined;
+/** 判据表 v2 的判定(纯函数;顺序 = 设计稿 §9 尾的五臂汇总,注见文件头)。 */
+export declare function decideReconcileAction(input: ReconcileInput): ReconcileAction;
+/** 收敛器一次 tick 的产出(可观测 + 测试断言面)。 */
+export interface ReconcileStats {
+    /** 段一扫到的 `PARKING` 行数。 */
+    scanned: number;
+    /**
+     * 🔴 判据 1 **结构上无法命中**的行数(`bound_input_hash` 列为 NULL ⇒ 双等硬谓词永远不成立)。
+     *
+     * 存在理由(codex 交叉复审 C1,2026-08-06 验真):设计稿 §9 C2 的前提是「`AskRequest.boundInputHash`
+     * core 侧已在场」——**对树上的 core 5.13.0 不成立**:`AskRequest`(core/tool-policy.d.ts:78-90)没有这个
+     * 字段,铸行侧也就无值可存;唯一能算出同一摘要的 `boundInputHashOf`(core/canonical-json)既不在
+     * `index` 导出面也没有 subpath 出口。⇒ 在 core 供值之前,判据 1 恒不命中,PARKING 行只会落 ②③④⑤。
+     * 这个计数把「盲区」变成**可观测量**而不是静默行为(下面每 tick 一条 warn),也是协议开关翻真的前置
+     * 判据之一。
+     */
+    unmatchableNoHash: number;
+    parked: number;
+    denied: number;
+    voided: number;
+    /** 本轮没有产生终态的行:判据 3 的保持,**以及**判据 2/4/5 判出了终态但那条 CAS 干净地输的行
+     *  (别的副本先收走了它)——两者对本轮的意义相同:行没被本实例改动,下轮按新态重判。 */
+    held: number;
+    /** 单行判定/写入抛错被隔离掉的行数(一条坏行不许打断整段扫描)。 */
+    failed: number;
+    /** 段一/段二因**墙钟预算**用尽而提前收工的段数(0/1/2)。>0 ⇒ 依赖在退化,剩余行留给下一轮
+     *  (见 {@link RECONCILE_SEGMENT_BUDGET_MS})。 */
+    budgetExhausted: number;
+    /** 段二:被代打 `expireAsk` 的孤儿 `STREAM_PENDING` 行数(赢 CAS 的)。 */
+    orphansExpired: number;
+}
+/** 撤卡帧的投递面(live only,见 `ApprovalRevokeFrame` 顶注)。收敛器不认识 SSE,只交给这个口。 */
+export type ApprovalRevokeEmitter = (frame: ApprovalRevokeFrame, target: {
+    owner: string | null;
+    sessionId: string;
+    taskId: string;
+}) => void;
+/** 判据 1 的读口(窄接口,不绑具体 checkpoint 店实现——local 车道的店没有这个面,装配点传 undefined)。 */
+export interface ReconcileCheckpointPort {
+    findCheckpointCandidatesForAsk(scope: string, sessionId: string, toolCallId: string, sinceMs: number): Promise<CheckpointAskCandidate[]>;
+}
+/** 判据 2/4 的读口(窄接口,同上)。 */
+export interface ReconcileRunPort {
+    getRun(taskId: string): Promise<RunRecord | undefined>;
+}
+export interface ApprovalReconcilerDeps {
+    askStore: ApprovalAskStore;
+    /** 缺席 ⇒ 判据 1 恒不命中(候选集恒空),行落 ②③④⑤ —— 诚实降级,不是「假装没 checkpoint 就该 DENY」。 */
+    checkpoints?: ReconcileCheckpointPort | undefined;
+    /** 缺席 ⇒ `run` 恒 `null`,判据 2 不成立;durable 腿因此只可能被 ⑤ 兜底(不会被误判 DENIED)。 */
+    runs?: ReconcileRunPort | undefined;
+    logger: Logger;
+    metrics?: Metrics | undefined;
+    /** 每段每 tick 的行数上限(`STREAM_APPROVAL_RECONCILE_BATCH`)。 */
+    batchLimit: number;
+    /** 孤儿代打的宽限(`STREAM_APPROVAL_PENDING_GRACE_MS`)——活属主的窗到期竞争者常态必胜,
+     *  reaper 只在超过它之后才补位(§8 D-1.1:否则 reaper 会跟活属主抢,制造挂死面)。 */
+    pendingGraceMs: number;
+    adhocGraceMs: number;
+    orphanTtlMs: number;
+    emitRevoke?: ApprovalRevokeEmitter | undefined;
+}
+/** {@link createApprovalReconciler} 返回的活对象。 */
+export interface ApprovalReconciler {
+    /** 跑一轮(两段:PARKING 判据表 + 孤儿 STREAM_PENDING 代打)。**永不抛**——单行错误隔离在行内,
+     *  段级错误由调用方(reaper 腿的 throttled catch)兜。 */
+    runOnce(nowMs: number): Promise<ReconcileStats>;
+}
+export declare function createApprovalReconciler(deps: ApprovalReconcilerDeps): ApprovalReconciler;
+//# sourceMappingURL=approval-reconciler.d.ts.map