@sema-agent/server 7.141.0 → 7.143.0

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

@@ -1,6 +1,7 @@
 import type { ApprovalAskStore } from "./plugins/approval-ask-store-sql.js";
 import { FileApprovalAskAuditStore } from "./approval-ask-audit-store.js";
 import { type HolderGoneCause } from "./approval-deny-reasons.js";
+import { type ReconcileCheckpointPort } from "./approval-reconciler.js";
 import { type RunStoreReader } from "./user-input-ledger.js";
 import type { Logger } from "./observability/logger.js";
 /** 启动收敛的读数(进启动日志)。 */
@@ -10,17 +11,19 @@ export interface CrashConvergenceReport {
     readonly decided: number;
     readonly inconsistent: number;
     readonly corruptLines: number;
-    /** ask 账半场:按成因词计的、本次收成 VOID 的前世 `STREAM_PENDING` 行数。 */
+    /** ask 账半场:按成因词计的、本次收成 VOID 的前世 `STREAM_PENDING` 行与审计判孤儿的 `PARKING` 行数。 */
     readonly asksVoided: Readonly<Record<HolderGoneCause, number>>;
+    /** 审计判孤儿的 `PARKING` 行里判据 ① 命中、收成 `PARKED` 的行数(停车行其实已提交;每行另有一行 warn 点名)。 */
+    readonly parkingBound: number;
     /** 其中卡信封读不出、成因词是回落(`crashed_before_park`)的行数(同时记 fail-open tag)。 */
     readonly causeUnreadable: number;
 }
 /** 本次收成 VOID 的行数合计 —— 由成因闭集派生(对 `asksVoided` 的每个词求和;闭集加词不需要改这里)。 */
 export declare function totalAsksVoided(report: Pick<CrashConvergenceReport, "asksVoided">): number;
-/** 本函数读写的那几口(窄形:测试可以直给一只内存店)。 */
-export type CrashConvergenceAskPort = Pick<ApprovalAskStore, "listByState" | "transitionAsk">;
-/** 审计店的两口(收敛半场 + 成因判点)。 */
-export type CrashConvergenceAuditPort = Pick<FileApprovalAskAuditStore, "convergeCrashedAsks" | "causeFor">;
+/** 本函数读写的那几口(窄形:测试可以直给一只内存店)。`getBatch` / `bindBatch` 是判据 ① 执行体的两口。 */
+export type CrashConvergenceAskPort = Pick<ApprovalAskStore, "listByState" | "transitionAsk" | "getBatch" | "bindBatch">;
+/** 审计店的两口(收敛半场 + 持有者没了的判点)。 */
+export type CrashConvergenceAuditPort = Pick<FileApprovalAskAuditStore, "convergeCrashedAsks" | "holderGoneVerdict">;
 /**
  * 启动收敛读哪一份**审计证据**:活的审计店在场就用它;不在场(这一世 `TOOL_APPROVAL_ENABLED` 关着 ⇒ 装配三合取不成立)而盘上有前世的审计账本
  * ⇒ 开一只读它 —— 成因是盘上证据的函数,不随这一世的开关变(否则前世有序关停截断的问在这一世被写成 `crashed_before_park`,审批重新打开那天审计读面
@@ -32,12 +35,16 @@ export declare function openAuditEvidenceForConvergence(live: CrashConvergenceAu
     release: () => void;
 };
 /**
- * 启动收敛(见文件头)。只在数据根独占的车道上调,且必须在本进程铸出第一问之前。幂等跨启动:收过的行已不是 `STREAM_PENDING`,
- * 审计半场有自己的收敛锚;成因读冻结的前世审计账 ⇒ 半途崩溃再启,剩下的行得到与第一次相同的词。
+ * 启动收敛(见文件头)。只在数据根独占的车道上调,且必须在本进程铸出第一问之前。幂等跨启动:收过的行已不在 `STREAM_PENDING` / `PARKING`,
+ * 审计半场有自己的收敛锚;判定与成因读冻结的前世审计账 ⇒ 半途崩溃再启,剩下的行得到与第一次相同的判定与词。
+ * `checkpoints` = 判据 ① 的候选读口,必填、不可缺席(装配点交后端的只读口 `checkpointReadView()`;没有 checkpoint 店的后端交恒空读口):缺席会让判据 ① 恒不命中、
+ * 把已提交的停车行收成 VOID,所以既不给缺省,也不收 `undefined`。
  */
 export declare function convergeCrashedAsksAtBoot(input: {
     askStore: CrashConvergenceAskPort | undefined;
     audit: CrashConvergenceAuditPort | undefined;
+    checkpoints: ReconcileCheckpointPort;
+    logger: Pick<Logger, "warn">;
     now?: () => number;
 }): Promise<CrashConvergenceReport>;
 /**
@@ -45,12 +52,15 @@ export declare function convergeCrashedAsksAtBoot(input: {
  *  · 只在数据根独占的车道上跑 —— 车道事实与用户输入受理账本同一只 `writerGoneEvidenceFor`(local ⇒ `exclusive_data_root`);SQL 车道整步不做。
  *  · ask 店取 `backend.approvalAsk()`,**不看协议开关**:前世开着协议留下的行,今世关着也照收(否则重新打开协议那天它们又变得可决)。
  *  · 审计证据经 {@link openAuditEvidenceForConvergence}(这一世的审批开关不改变成因)。
+ *  · 判据 ① 的候选读口 = 后端的只读口 `backend.checkpointReadView()`,**不看 `DURABLE_APPROVAL`**(前世已提交的停驻不因这一世的开关消失;local 车道它与 durable 装配的那只是同一只店,
+ *    只是不接 run 店的收割探针)。
  *  · 有任何收敛 / 坏行 ⇒ 一行 warn `approval_ask_audit_crash_converged`(零动作不打)。收敛写入抛错 ⇒ 抛出 ⇒ 拒启。
  */
 export declare function runBootCrashConvergence(ctx: {
     backend: {
         readonly kind: "mysql" | "pg" | "local";
         approvalAsk(): CrashConvergenceAskPort;
+        checkpointReadView(): ReconcileCheckpointPort;
     } | undefined;
     runStore: RunStoreReader | undefined;
     liveAudit: CrashConvergenceAuditPort | undefined;

package/dist/approval-crash-convergence.js

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { APPROVAL_ASK_AUDIT_DIR, APPROVAL_ASK_AUDIT_LEDGER, FileApprovalAskAuditStore } from "./approval-ask-audit-store.js";
 import { readStoredCardEnvelope } from "./approval-card.js";
 import { APPROVAL_ENDING_CAUSES } from "./approval-deny-reasons.js";
+import { bindParkingAskAtGate } from "./approval-reconciler.js";
 import { writerGoneEvidenceFor } from "./user-input-ledger.js";
 import { recordFailOpen } from "./observability/fail-open.js";
 const CONVERGE_PAGE = 500;
@@ -17,57 +18,128 @@ export function openAuditEvidenceForConvergence(live, localDataRoot) {
     const opened = new FileApprovalAskAuditStore(localDataRoot);
     return { audit: opened, release: () => opened.close() };
 }
+async function forEachRowInState(store, state, visit) {
+    const seen = new Set();
+    let stayed = 0;
+    for (;;) {
+        const page = (await store.listByState(state, stayed + CONVERGE_PAGE)).filter((r) => !seen.has(r.askId));
+        if (page.length === 0)
+            return;
+        for (const row of page) {
+            seen.add(row.askId);
+            if (!(await visit(row)))
+                stayed += 1;
+        }
+    }
+}
+function refusingToStart(state, row, err) {
+    return new Error(`approval crash convergence: could not close the previous process's ${state === "STREAM_PENDING" ? "pending" : "parking"} approval ask ${row.askId} (task ${row.taskId}): ` +
+        `${err instanceof Error ? err.message : String(err)} — refusing to start, because serving now would leave a card that nothing waits for ` +
+        "decidable with a 200. Fix the data root (disk full / read-only?) and start again.");
+}
 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 audit = input.audit;
+    const audited = audit?.convergeCrashedAsks() ?? { pending: 0, decided: 0, inconsistent: 0, corruptLines: 0 };
     const asksVoided = { [APPROVAL_ENDING_CAUSES.CRASHED_BEFORE_PARK]: 0, [APPROVAL_ENDING_CAUSES.SHUTDOWN_BEFORE_PARK]: 0 };
     let causeUnreadable = 0;
+    let parkingBound = 0;
     const store = input.askStore;
     if (store !== undefined) {
-        const seen = new Set();
-        for (;;) {
-            const page = (await store.listByState("STREAM_PENDING", CONVERGE_PAGE)).filter((r) => !seen.has(r.askId));
-            if (page.length === 0)
-                break;
-            for (const row of page) {
-                seen.add(row.askId);
+        await forEachRowInState(store, "STREAM_PENDING", async (row) => {
+            const envelope = readStoredCardEnvelope(row.cardJson);
+            if (envelope === undefined) {
+                causeUnreadable += 1;
+                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 !== undefined && audit !== undefined ? audit.holderGoneVerdict(envelope.approvalId).cause : APPROVAL_ENDING_CAUSES.CRASHED_BEFORE_PARK;
+            let won;
+            try {
+                won = await store.transitionAsk(row.askId, "STREAM_PENDING", "VOID", { endingCause: reason, updatedAtMs: now() });
+            }
+            catch (err) {
+                throw refusingToStart("STREAM_PENDING", row, err);
+            }
+            if (won)
+                asksVoided[reason] += 1;
+            return true;
+        });
+        if (audit !== undefined) {
+            const orphanOf = (row) => {
                 const envelope = readStoredCardEnvelope(row.cardJson);
-                if (envelope === undefined) {
-                    causeUnreadable += 1;
-                    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}`);
+                if (envelope === undefined)
+                    return undefined;
+                const verdict = audit.holderGoneVerdict(envelope.approvalId);
+                return verdict.orphan ? { approvalId: envelope.approvalId, cause: verdict.cause } : undefined;
+            };
+            let voidedSiblings = [];
+            const gate = {
+                askStore: store,
+                checkpoints: input.checkpoints,
+                warn: (event, fields) => input.logger.warn(event, fields),
+                revoke: (_row, askIds) => {
+                    voidedSiblings = askIds;
+                },
+            };
+            await forEachRowInState(store, "PARKING", async (row) => {
+                const orphan = orphanOf(row);
+                if (orphan === undefined)
+                    return false;
+                voidedSiblings = [];
+                let bound;
+                try {
+                    bound = (await bindParkingAskAtGate(gate, row, now())).bound;
                 }
-                const reason = envelope !== undefined && input.audit !== undefined ? input.audit.causeFor(envelope.approvalId) : APPROVAL_ENDING_CAUSES.CRASHED_BEFORE_PARK;
+                catch (err) {
+                    throw refusingToStart("PARKING", row, err);
+                }
+                if (!bound)
+                    return false;
+                parkingBound += 1;
+                input.logger.warn("approval_crash_convergence_park_committed", {
+                    askId: row.askId,
+                    taskId: row.taskId,
+                    approvalId: orphan.approvalId,
+                    voidedSiblings,
+                    note: "the audit ledger saw no settlement for this approval ask (an orphan of the previous process), but its park row had committed — bound PARKED, decidable through the durable approval endpoint; the commit landed in the window between the park commit and its observation. Same-batch siblings still parking were voided as superseded by this park (batch_bound_elsewhere)",
+                });
+                return true;
+            });
+            await forEachRowInState(store, "PARKING", async (row) => {
+                const orphan = orphanOf(row);
+                if (orphan === undefined)
+                    return false;
                 let won;
                 try {
-                    won = await store.transitionAsk(row.askId, "STREAM_PENDING", "VOID", { deniedReason: reason, updatedAtMs: now() });
+                    won = await store.transitionAsk(row.askId, "PARKING", "VOID", { endingCause: orphan.cause, updatedAtMs: now() });
                 }
                 catch (err) {
-                    throw new Error(`approval crash convergence: could not close the previous process's pending approval ask ${row.askId} (task ${row.taskId}): ` +
-                        `${err instanceof Error ? err.message : String(err)} — refusing to start, because serving now would leave a card that nothing waits for ` +
-                        "decidable with a 200. Fix the data root (disk full / read-only?) and start again.");
+                    throw refusingToStart("PARKING", row, err);
                 }
                 if (won)
-                    asksVoided[reason] += 1;
-            }
+                    asksVoided[orphan.cause] += 1;
+                return true;
+            });
         }
     }
-    return { ...audited, asksVoided, causeUnreadable };
+    return { ...audited, asksVoided, causeUnreadable, parkingBound };
 }
 export async function runBootCrashConvergence(ctx) {
     const { backend, runStore, logger } = ctx;
     if (backend === undefined || runStore === undefined || writerGoneEvidenceFor(backend.kind, runStore).kind !== "exclusive_data_root")
         return undefined;
     const evidence = openAuditEvidenceForConvergence(ctx.liveAudit, ctx.localDataRoot);
-    const converged = await convergeCrashedAsksAtBoot({ askStore: backend.approvalAsk(), audit: evidence.audit }).finally(evidence.release);
-    if (converged.pending > 0 || converged.decided > 0 || converged.inconsistent > 0 || converged.corruptLines > 0 || totalAsksVoided(converged) > 0) {
+    const converged = await convergeCrashedAsksAtBoot({ askStore: backend.approvalAsk(), audit: evidence.audit, checkpoints: backend.checkpointReadView(), logger }).finally(evidence.release);
+    if (converged.pending > 0 || converged.decided > 0 || converged.inconsistent > 0 || converged.corruptLines > 0 || totalAsksVoided(converged) > 0 || converged.parkingBound > 0) {
         logger.warn("approval_ask_audit_crash_converged", {
             pending: converged.pending,
             decided: converged.decided,
             inconsistent: converged.inconsistent,
             corruptLines: converged.corruptLines,
             asksVoided: converged.asksVoided,
+            parkingBound: converged.parkingBound,
             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) 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 by the previous process were converged: each pending ask, and each parking ask the audit ledger judged an orphan, 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 = the previous process completed its orderly shutdown wind-down while the ask was still unsettled); a parking ask whose park row had committed is bound PARKED instead",
         });
     }
     return converged;

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

@@ -3,10 +3,10 @@
  *
  * ## 它治的病(同一件事、四张词表、一词多义)
  * 一张卡没被人答就结束了,今天有四个读面各说各话:审计 settle 行(`expired` 一词盖 TTL 到期 / run 取消 / run 退出清理 / 广播全灭,批内兄弟被撤卡也是同一个词)、
- * 问账 VOID/DENIED 行(`denied_reason` 列)、晚答 404 的判别位、决断口 409 的码(多种成因借 `approval_binding_mismatch` 一个名)。壳读账写不出「已取消」,
+ * 问账 VOID/DENIED 行(成因列)、晚答 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});
+ *  · 问账 VOID/DENIED 行的 `ending_cause` 列 → 决断口 410 `gone.ask` 体的 `cause` 与晚答 404 体的 `cause`(读同一列,经唯一读口 {@link askRowEndingCause});
  *  · `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)。
@@ -16,8 +16,9 @@
  *  · 成因**只从事实读**: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 窗按意义改名。
+ *  · 落列面:问账行的成因落**两列,一列一义**(各 VARCHAR(64)):`approval_ask.ending_cause` = **终态成因**(这一行为什么没被人答就结束了;到 `VOID` / `DENIED` 的转移带着它写),
+ *    `approval_ask.park_trigger` = **转 park 的触发成因**(这一行为什么被转进投递面;只由那一次 `claimTerminal(expire, { cause })` 写,此后不再被写 —— 终态不覆盖它)。
+ *    两只读口各读一列:{@link askRowEndingCause} / {@link askRowParkTrigger}(两张读词表各只被一只读)。
  *
  * ## 为什么 `routing_failure_fail_closed` 也在表里(归因诚实性)
  * 审计面唯一能证明「超时永不产生 denial」的东西是**终态 + 成因**的组合:人拒恒为 `DECIDED(decision=deny)`,路由失败恒为 `DENIED(routing_failure_fail_closed)`,
@@ -71,11 +72,15 @@ export declare const APPROVAL_ENDING_CAUSES: {
      */
     readonly ROUTING_FAILURE: "routing_failure_fail_closed";
     /**
-     * 启动收敛(`approval-crash-convergence.ts`,local 车道):**承载这一问的进程没了** —— 前世进程崩溃 / 被杀,留下的 `STREAM_PENDING` 行在下一次启动、任何卡能开始之前收成 VOID。
-     * 证据是数据根 `LOCK`(前世写者全死),不是「等够久了」。值与 `GET /v1/approvals` `crashConverged[].cause` 是**同一个词**。
+     * 启动收敛(`approval-crash-convergence.ts`,local 车道):**承载这一问的进程没了** —— 前世进程崩溃 / 被杀,留下的 `STREAM_PENDING` 行与审计判为孤儿的 `PARKING` 行
+     * (停车行没提交)在下一次启动、任何卡能开始之前收成 VOID。证据是数据根 `LOCK`(前世写者全死)+ 审计账的孤儿判定,不是「等够久了」。
+     * 值与 `GET /v1/approvals` `crashConverged[].cause` 是**同一个词**(一处判:审计店的 `holderGoneVerdict`)。
      */
     readonly CRASHED_BEFORE_PARK: "crashed_before_park";
-    /** 同上,但承载它的腿是被**有序关停**截断的(审计账本上有本腿的关停记号;关停收尾没能在宽限窗内把这张卡结清),或有序关停期间这张卡被改路停驻(settle 行的成因)。 */
+    /**
+     * 同上,但前世走完了**有序关停**的审批收尾(审计账本上那一世的进程级关停记录落在这张卡的末事件之后 —— 收尾没能在宽限窗内把它结清;是进程的事实,
+     * 不看承载它的腿在不在追踪视野里),或有序关停期间这张卡被改路停驻(settle 行 / 问账行 PARKING 的触发成因)。
+     */
     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";
@@ -117,7 +122,7 @@ export declare const SETTLE_CAUSE_WORDS: {
 };
 /** 一个值是不是非人结局的成因词(审计账读盘用这一只判词)。 */
 export declare function isSettleCause(v: unknown): v is SettleCause;
-/** 「承载这一问的进程没了」的两个成因词(启动收敛写进问账行 `denied_reason`,审计收敛行 `cause` 读同一型)。 */
+/** 「承载这一问的进程没了」的两个成因词(启动收敛写进问账行 `ending_cause`(前世的 `STREAM_PENDING` 与审计判孤儿的 `PARKING`),审计收敛行 `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;
@@ -128,7 +133,7 @@ export type ReconcileVoidCause = typeof APPROVAL_ENDING_CAUSES.RUN_CANCELLED | t
  * (取消赢下 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}。 */
+/** 问账行 `ending_cause` 列的读词表({@link AskRowEndingCause} 的穷举,`satisfies` ⇒ 子集加词而本表没跟 = 编译红)。唯一读者 = {@link askRowEndingCause}。 */
 export declare const ASK_ROW_ENDING_CAUSE_WORDS: {
     readonly routing_failure_fail_closed: true;
     readonly run_cancelled: true;
@@ -142,12 +147,12 @@ export declare const ASK_ROW_ENDING_CAUSE_WORDS: {
     readonly shutdown_before_park: true;
 };
 /**
- * `expire` 终局 claim(窗到期 / 广播全灭 / 有序关停把一张卡转投递面 = `PARKING`)赢下时写进这一行 `denied_reason` 的**触发成因**:这一行此后若走到 `DENIED` / `VOID`,终态成因会覆盖它
- * ({@link AskRowEndingCause});`PARKED` 行的这一格就是「它为什么被转 park」。跨副本的读者(另一进程的悬挂腿轮询、CAS 败方读数)读到 `PARKING` / `PARKED` 时靠它归因,
- * 不替没写的行猜一个词。
+ * `expire` 终局 claim(窗到期 / 广播全灭 / 断连 / 呈不出 / 有序关停把一张卡转投递面 = `PARKING`)赢下时写进这一行 `park_trigger` 的**触发成因**:此后不再被写 ——
+ * 这一行走到 `PARKED` / `DENIED` / `VOID` 之后它仍是「这一行为什么被转 park」(终态成因在另一列,{@link AskRowEndingCause})。跨副本的读者(另一进程的悬挂腿轮询、
+ * 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}。 */
+/** 问账行 `park_trigger` 列的读词表({@link ParkTriggerCause} 的穷举)。唯一读者 = {@link askRowParkTrigger}。 */
 export declare const PARK_TRIGGER_CAUSE_WORDS: {
     readonly ttl_expired: true;
     readonly broadcast_lost: true;
@@ -155,25 +160,24 @@ export declare const PARK_TRIGGER_CAUSE_WORDS: {
     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`(读面缺席即缺席,不替没写的行编一个成因)。返回纯数据。
+ * 🔴 **终态成因的唯一读口**(决断口 410、晚答 404、`GET` 读面、CAS 败方读数、悬挂腿的轮询读这一只):只读 `ending_cause` 一列,不看别的列。
+ * 行不变式由本口守:终态成因只在 `VOID` / `DENIED` 上作数(写者只在到这两态的转移上写它;别的态上读到 ⇒ 不是这一行的事实)—— 按 `state` 穷举(加状态 ⇒ 这里编译红)。
+ * 列值 `null` / 键缺席(没写归因的行)、词表外的词(手改 / 将来版本写的词)或与 state 不配 ⇒ `undefined`(读面缺席即缺席,不替没写的行编一个成因)。返回纯数据。
+ */
+export declare function askRowEndingCause(row: {
+    readonly state: AskState;
+    readonly endingCause?: string | null;
+}): AskRowEndingCause | undefined;
+/**
+ * 🔴 **转 park 触发成因的唯一读口**(跨副本的悬挂腿、CAS 败方读数读这一只):只读 `park_trigger` 一列,不看别的列。
+ * 行不变式由本口守:触发成因只在**走过 `PARKING`** 的行上作数 —— `PARKING` / `PARKED`,以及从 `PARKING` 收成的 `DENIED` / `VOID`(终态不覆盖它);
+ * `STREAM_PENDING` / `DECIDED`(状态机上没有经 `PARKING` 到它们的边)上读到 ⇒ `undefined`。其余与 {@link askRowEndingCause} 同律。
  */
-export declare function causeOfAskRow(row: {
-    readonly state: AskState | "absent";
-    readonly deniedReason?: string | null;
-}): AskRowCause | undefined;
+export declare function askRowParkTrigger(row: {
+    readonly state: AskState;
+    readonly parkTrigger?: string | null;
+}): ParkTriggerCause | undefined;
 /** 非人**结局**的成因(审计 settle 行 `cause`、活卡结局帧 `tool_approval_complete.cause`):闭集去掉决断口 409 的三个词({@link DecisionRefusalCause})—— 那三个词不结束一张卡,只拒一次决议。 */
 export type SettleCause = Exclude<ApprovalEndingCause, DecisionRefusalCause>;
 /** 决断口 409 的成因子集(core 的 `detail.field` → 码;每词一个码,见 `http/resume-legs.ts`)。 */

package/dist/approval-deny-reasons.js

@@ -63,22 +63,37 @@ export const PARK_TRIGGER_CAUSE_WORDS = {
 function isParkTriggerCause(v) {
     return Object.hasOwn(PARK_TRIGGER_CAUSE_WORDS, v);
 }
-export function causeOfAskRow(row) {
-    const stored = row.deniedReason;
+export function askRowEndingCause(row) {
+    const stored = row.endingCause;
     switch (row.state) {
         case "VOID":
         case "DENIED":
-            return stored !== null && stored !== undefined && isAskRowEndingCause(stored) ? { kind: "ending", cause: stored } : undefined;
+            return stored !== null && stored !== undefined && isAskRowEndingCause(stored) ? 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)}`);
+            throw new Error(`askRowEndingCause: unhandled ask row state ${String(unhandled)}`);
+        }
+    }
+}
+export function askRowParkTrigger(row) {
+    const stored = row.parkTrigger;
+    switch (row.state) {
+        case "PARKING":
+        case "PARKED":
+        case "DENIED":
+        case "VOID":
+            return stored !== null && stored !== undefined && isParkTriggerCause(stored) ? stored : undefined;
+        case "DECIDED":
+        case "STREAM_PENDING":
+            return undefined;
+        default: {
+            const unhandled = row.state;
+            throw new Error(`askRowParkTrigger: unhandled ask row state ${String(unhandled)}`);
         }
     }
 }

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

@@ -29,6 +29,6 @@ import type { ParkTriggerCause } from "./approval-deny-reasons.js";
  * `batchId` 必须是**行上**的批(幂等命中的存量行可能是别的政策 / 旧版本铸的整腿批,错 scope 的 claim 如实 `absent`)。
  */
 export declare function settleByPolicy(store: Pick<ApprovalAskStore, "claimTerminal">, row: Pick<AskRow, "askId" | "batchId">, policy: UnattendedApprovalPolicy, 
-/** 转 park 的触发成因(窗到期 / 广播全灭 / 有序关停):`park` 政策的 `expire` 赢下 PARKING 时随同一步写进行(`denied_reason`),跨副本的读者据它归因;`deny` 政策落的是一条决议,不带。 */
+/** 转 park 的触发成因(窗到期 / 广播全灭 / 有序关停):`park` 政策的 `expire` 赢下 PARKING 时随同一步写进行(`park_trigger`),跨副本的读者据它归因;`deny` 政策落的是一条决议,不带。 */
 cause: ParkTriggerCause): Promise<AskTerminalClaimOutcome>;
 //# sourceMappingURL=approval-policy-settlement.d.ts.map

package/dist/approval-queue-kind.d.ts

@@ -0,0 +1,27 @@
+/**
+ * **运维审批队列 `pending[]` 的行族闭集** —— 全仓唯一的定义处([ref])。
+ *
+ * ## 规则(一句)
+ * `GET /v1/approvals` 的 `pending[]`(与 `/v1/approvals/stream` 的 `pending` / `resolved` 帧)= **决断口是 `POST /v1/approvals/:id/decide` 的全部行**;
+ * 每一行自报它属于哪一族(`kind`,本闭集一词),消费方**先按 `kind` 分支**,再读那一族的键。数组名仍是决断口的判据(`livePending[]` 的口是
+ * `POST /v1/tool-approvals/:approvalId/respond`,不在本闭集里);本闭集回答的是「同一扇门后面是哪一种卡」。
+ *
+ *  · `checkpoint` —— 停驻门(durable park):行 = 店的 `listPending` 那一行(键集照旧,另带 `kind`),门的 `:id` = 行的 `sessionId`,
+ *    再按 `gateKind`(core 的门型闭集)分路;
+ *  · `peer_inbound` —— 被 `crossSessionInbound: hold` 扣住、等收信方决断的跨会话来信:行 = core 进程级 held 队列那一张卡的投影
+ *    (`peer-inbound-face.ts`),门的 `:id` = 行的 `id`(`peer_inbound:` 前缀的坐标串),决断 = core `PeerHeldQueue.settle`。
+ *
+ * 加一族 = 在 {@link APPROVAL_QUEUE_KINDS} 加一个词:决断口分派、流的键与离场帧({@link approvalQueueKindOfDoorId} 的调用点)
+ * 都是对 {@link ApprovalQueueKind} 的穷举 `switch`,漏一臂 = **编译红**(`test/peer-inbound-approvals.test.ts` 的 P6 钉)。
+ */
+/** 行族闭集(序无义;加词 = 全部穷举点编译红)。 */
+export declare const APPROVAL_QUEUE_KINDS: readonly ["checkpoint", "peer_inbound"];
+export type ApprovalQueueKind = (typeof APPROVAL_QUEUE_KINDS)[number];
+/**
+ * `peer_inbound` 族决断口 id 的前缀 —— 一个 id 是不是这一族,**只**看它(`checkpoint` 族的 id 是会话 id:规范 uuid 或服务现铸的
+ * 内部 id,都不含 `:`,所以两族的 id 空间不交)。
+ */
+export declare const PEER_INBOUND_ID_PREFIX = "peer_inbound:";
+/** 决断口 `:id` 段 → 它属于哪一族(唯一判据:前缀)。前缀对而其余不成形的 id 仍归 `peer_inbound`(那一族自己答 404,不落回停驻门)。 */
+export declare function approvalQueueKindOfDoorId(id: string): ApprovalQueueKind;
+//# sourceMappingURL=approval-queue-kind.d.ts.map

package/dist/approval-queue-kind.js

@@ -0,0 +1,6 @@
+export const APPROVAL_QUEUE_KINDS = ["checkpoint", "peer_inbound"];
+export const PEER_INBOUND_ID_PREFIX = "peer_inbound:";
+export function approvalQueueKindOfDoorId(id) {
+    return id.startsWith(PEER_INBOUND_ID_PREFIX) ? "peer_inbound" : "checkpoint";
+}
+//# sourceMappingURL=approval-queue-kind.js.map

package/dist/approval-reconciler.d.ts

@@ -79,7 +79,7 @@ export type GateMatchOutcome =
     kind: "hash_mismatch";
     candidates: number;
 }
-/** 三元组身份就对不上(不是摘要的事):别的 sourceTaskId / 别的 callId / 早于本 ask 的 park。 */
+/** 三元组身份就对不上(不是摘要的事):别的 sourceSessionId / 别的 callId / 早于本 ask 的 park。 */
  | {
     kind: "identity_miss";
 };
@@ -91,8 +91,8 @@ export type GateMatchOutcome =
  * `delegation.parentToolCallId` 是必填字段,铸行时逐字透传进 `parent_tool_call_id` 列 ⇒ **列非 NULL
  * ⇔ delegation 在场**(不需要新列,也不需要回 `req` 里再读一次)。
  *
- * 第二维 `sourceTaskId !== sessionId` 把「根腿」摘出去:根腿的 `sourceTaskId` 恒等于会话锚(core 给
- * `AskRequest.sourceTaskId` 填的就是该腿 sessionId),它根本不在任何 fold 里,`parent_tool_call_id`
+ * 第二维 `sourceSessionId !== sessionId` 把「根腿」摘出去:根腿的 `sourceSessionId` 恒等于会话锚(core 给
+ * `AskRequest.sourceSessionId` 填的就是该腿 sessionId),它根本不在任何 fold 里,`parent_tool_call_id`
  * 为 NULL 是它的常态而不是信号。
  *
  * 命中 ⇒ 退出硬相等(判据 1 结构上不命中,行落 ②③④⑤)。实测(test AI 围栏)checkpoint 存的摘要**逐字
@@ -105,11 +105,11 @@ export declare function isAncestorFoldMint(ask: AskRow): boolean;
  * 逐条:
  *  - 祖先层 fold 中途铸点 ⇒ 直接退出(见 {@link isAncestorFoldMint});
  *  - `unparseable` 候选直接出局(读不出 ⇒ 不确定 ⇒ 不命中);
- *  - **身份三元组**:`sourceTaskId` **相等** ∧ `toolCallId` **相等** ∧ 时间维的**因果下界**
+ *  - **身份三元组**:`sourceSessionId` **相等** ∧ `toolCallId` **相等** ∧ 时间维的**因果下界**
  *    `candidate.createdAtMs >= ask.createdAtMs`(⚠️ 第三维**不是等式** —— 把它读成等式会让合法的 park
  *    几乎命不中,行随后落 ②③⑤ 被误判)—— 摘要**不是**身份([ref]③①:
  *    同 args 的两次调用摘要天然相同,只靠摘要硬相等会把第二次投递并进第一次的票);任一维在候选侧
- *    缺席(读不出的 blob 没有 `sourceTaskId`)即身份不成立;
+ *    缺席(读不出的 blob 没有 `sourceSessionId`)即身份不成立;
  *  - **hash 双等**:两侧都必须在场且相等,任一侧缺席一律不 bind;禁「能取到时才比」的可选谓词。
  *    归因分两级(顺序即代码顺序):身份这一层先判 —— 同身份候选为空**且**候选集非空 ⇒ `identity_miss`;
  *    走到 hash 这一层才把缺席记成**单铸** `single_mint`(见 {@link GateMatchOutcome})。
@@ -123,6 +123,17 @@ export declare function classifyGateMatch(ask: AskRow, candidates: readonly Chec
 export declare function selectGateCandidate(ask: AskRow, candidates: readonly CheckpointAskCandidate[]): CheckpointAskCandidate | undefined;
 /** 判据表 v2 的判定(纯函数;顺序 = 设计稿 §9 尾的五臂汇总,注见文件头)。 */
 export declare function decideReconcileAction(input: ReconcileInput): ReconcileAction;
+/** 判据 1 执行体({@link bindParkingAskAtGate})一次尝试的结果。没绑上 ⇒ 交回批的真实态,周期扫据它续判 ②③④⑤。 */
+export type GateBindAttempt = {
+    bound: true;
+    match: GateMatchOutcome;
+} | {
+    bound: false;
+    match?: GateMatchOutcome;
+    batchState: BatchState | "MISSING" | null;
+    batchBoundAskId: string | null;
+    irreversibleBatch: boolean;
+};
 /** 收敛器一次 tick 的产出(可观测 + 测试断言面)。 */
 export interface ReconcileStats {
     /** 段一扫到的 `PARKING` 行数。 */
@@ -167,10 +178,10 @@ export interface ReconcileStats {
      *
      * 🔴 **今天恒零,而且是结构性的**(扫描P2,2026-08-12 亲读验真;登记而不假称已解):读口
      * `findCheckpointCandidatesForAsk` 按 `session_id = ask.sessionId` 查,`session_id` 列写的是
-     * `cp.sessionId`,而 core 每个 checkpoint 铸点都填 `sourceTaskId: sessionId`
+     * `cp.sessionId`,而 core 每个 checkpoint 铸点都填 `sourceSessionId: sessionId`
      * (`runner/prepare-task.js` 四处;`checkpoint-store.d.ts` 逐字「= sessionId at the mint」)⇒ 读口
-     * 返回的候选恒满足 `c.sourceTaskId === ask.sessionId`;而判据 1 命中要 `c.sourceTaskId ===
-     * ask.sourceTaskId`,祖先层否决要 `ask.sourceTaskId !== ask.sessionId` —— 两者互斥,这一臂在生产
+     * 返回的候选恒满足 `c.sourceSessionId === ask.sessionId`;而判据 1 命中要 `c.sourceSessionId ===
+     * ask.sourceSessionId`,祖先层否决要 `ask.sourceSessionId !== ask.sessionId` —— 两者互斥,这一臂在生产
      * 接线下一次也不会被返回。
      *
      * 所以**别把零读数当健康信号**(与 {@link unmatchableNoHash} 的「恒零才是健康态」正相反:那条能非零,
@@ -202,7 +213,7 @@ export type ApprovalRevokeEmitter = (frame: ApprovalRevokeFrame, target: {
     sessionId: string;
     taskId: string;
 }) => void;
-/** 判据 1 的读口(窄接口,不绑具体 checkpoint 店实现——local 车道的店没有这个面,装配点传 undefined)。 */
+/** 判据 1 的读口(窄接口,不绑具体 checkpoint 店实现;三个后端的 checkpoint 店都有这一面,后端的只读口 `checkpointReadView()` 也交它 —— 起服收敛读那一口)。 */
 export interface ReconcileCheckpointPort {
     findCheckpointCandidatesForAsk(scope: string, sessionId: string, toolCallId: string, sinceMs: number): Promise<CheckpointAskCandidate[]>;
 }
@@ -245,5 +256,26 @@ export interface ApprovalReconciler {
      *  段级错误由调用方(reaper 腿的 throttled catch)兜。 */
     runOnce(nowMs: number): Promise<ReconcileStats>;
 }
+/**
+ * {@link bindParkingAskAtGate} 的依赖(三个调用方交同一形):批 / 绑两口、判据 1 的候选读口、warn 与撤卡两个出口。
+ */
+export interface GateBindDeps {
+    readonly askStore: Pick<ApprovalAskStore, "getBatch" | "bindBatch">;
+    /** 缺席 ⇒ 候选集恒空 ⇒ 判据 1 恒不命中(诚实降级,与 {@link ApprovalReconcilerDeps.checkpoints} 同一句)。 */
+    readonly checkpoints: ReconcileCheckpointPort | undefined;
+    /** warn 的出口(调用方保证它不抛 —— 可观测面绝不成为故障源)。 */
+    readonly warn: (event: string, fields: Record<string, unknown>) => void;
+    /** 被 `bindBatch` 连坐的兄弟的撤卡帧(帧是通知,真源是行;失败不回滚 CAS)。 */
+    readonly revoke: (row: AskRow, askIds: readonly string[], reason: ApprovalRevokeFrame["reason"], nowMs: number) => void;
+}
+/**
+ * 🔴 **判据 1 的唯一执行体**([ref] 起一只判官;[ref] 起三个调用方):⓪ 批态先读 → 候选读口 → {@link classifyGateMatch} → 命中即 `bindBatch`
+ * (+ 被连坐兄弟的撤卡帧)。调用方:
+ *  · 周期扫(`createApprovalReconciler` 的 `reconcileOne`)—— 不命中 / 绑失败时拿回批的真实态,续判 ②③④⑤;
+ *  · park 提交那一拍(`bindCommittedPark`)—— 只问「这一行此刻能不能收口」,不命中即止(其余臂是周期扫的事);
+ *  · local 车道起服收敛(`approval-crash-convergence.ts`)—— 审计判为孤儿的前世 `PARKING` 行:命中 ⇒ `PARKED`;不命中 ⇒ 调用方收 `VOID`。
+ * 判据、读口、写口一个字都不分叉:事件路径与起服都是本函数的即时调用,不是第二份判据。
+ */
+export declare function bindParkingAskAtGate(deps: GateBindDeps, ask: AskRow, nowMs: number, deadlineMs?: number): Promise<GateBindAttempt>;
 export declare function createApprovalReconciler(deps: ApprovalReconcilerDeps): ApprovalReconciler;
 //# sourceMappingURL=approval-reconciler.d.ts.map