@harrylabsj/kiwi 0.6.0

package/dist/negotiation/recovery/outbound.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbound.js","sourceRoot":"","sources":["../../../src/negotiation/recovery/outbound.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAwCH,0DAA0D;AAC1D,MAAM,UAAU,qBAAqB,CAAC,KAA2B;IAC/D,MAAM,OAAO,GAAuB;QAClC,UAAU,EAAE,cAAc;QAC1B,cAAc,EAAE,KAAK,CAAC,cAAc;QACpC,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,iBAAiB,EAAE,KAAK,CAAC,iBAAiB;QAC1C,cAAc,EAAE,KAAK,CAAC,cAAc;QACpC,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE;QACvB,WAAW,EAAE,KAAK,CAAC,WAAW;KAC/B,CAAC;IACF,OAAO,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;AACtC,CAAC"}

package/dist/negotiation/recovery/recover.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type NegotiationPhase } from "../state/phase.js";
+import type { LedgerEvent } from "../ledger/index.js";
+import type { RecoveryDeps, RecoveryResult } from "./types.js";
+/** 一条本地出站消息的证据（从 Ledger message_sent 事件重建）。 */
+interface OutboundLedgerEntry {
+    message_id: string;
+    wire_digest?: string;
+    wire_payload?: Record<string, unknown>;
+    remote_task_id?: string;
+}
+/** 恢复子系统的审计身份（reconciliation 事件的 sender 侧）。 */
+export declare const RECOVERY_SENDER_IDENTITY = "kiwi.recovery";
+/**
+ * 从 Ledger 事件推断本地会话的 sender_identity（基线 §23 / §25.2）。
+ *
+ * 恢复重放必须以原会话身份打开通道：幂等主键是 (sender_identity, message_id)，
+ * 若硬编码成 "kiwi.recovery"，pending 消息的键与原发送不匹配 → idempotency
+ * check() 返回 new → A2ADirectChannel 真实重发并在 Ledger 产生第二条
+ * message_sent（审计重复，§23）。此处优先取 message_sent 事件的 identity
+ * snapshot（出站身份）；无出站消息时取任一非 reconciliation 事件的
+ * sender_identity（reconciliation 是恢复子系统自身审计，不算会话身份）；全部
+ * 缺失回退 RECOVERY_SENDER_IDENTITY（保持既有兜底）。
+ */
+export declare function deriveSessionIdentity(events: LedgerEvent[]): string;
+/** 第 1 步：从 Ledger 的 state_transition 事件重建本地 phase；无记录时 OPEN。 */
+export declare function deriveLocalPhase(events: LedgerEvent[]): NegotiationPhase;
+/** 从 Ledger 事件收集本地出站消息（message_sent 事件）。 */
+export declare function collectOutbound(events: LedgerEvent[]): OutboundLedgerEntry[];
+export declare class NegotiationRecovery {
+    private readonly deps;
+    constructor(deps: RecoveryDeps);
+    private nowIso;
+    private toView;
+    private reconciliationContent;
+    /** 失败审计：不可调和的原因落 reconciliation error 事件后转人工。 */
+    private required;
+    private makeChannel;
+    /**
+     * 执行八步恢复。任何不确定性 fail-closed → reconciliation_required。
+     */
+    recover(negotiationId: string): Promise<RecoveryResult>;
+    private resumed;
+}
+export {};

package/dist/negotiation/recovery/recover.js

@@ -0,0 +1,486 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * 跨进程 context 恢复（基线 §23 Recovery and Reconciliation / 子规范 §27）。
+ *
+ * 八步流程的实现（WP4 后统一走 CounterpartyChannel 唯一接口）：
+ *
+ * ```text
+ * 1. Load local negotiation           ← 从 Ledger 重建本地 phase + 出站消息
+ * 2. Load Ledger high-water mark      ← highWaterMark() + verifyChain()（fail-closed）
+ * 3. Resolve counterparty/profile     ← CounterpartyResolver → CounterpartyProfile
+ * 4. Re-fetch remote task state       ← ChannelHandle.getState()（direct 通道）
+ * 5. Compare acknowledged messages    ← 远端可见 messageId vs 本地 message_sent
+ * 6. Reconcile remote state × Ledger  ← remote ahead: fetch→validate→append；
+ *                                         local pending: 同 id+同 digest 安全重放
+ *                                         （ChannelHandle.send）；不可调和 → 转人工
+ * 7. Expire stale candidates/approvals ← 远端 revision 变化 → 本地出站消息置 stale
+ * 8. Resume scheduler/subscription    ← 返回 resume_task_ids，由调用方恢复轮询
+ * ```
+ *
+ * fail-closed 不变量：恢复过程任何不确定性（链损坏、无法解析 profile、远端不可达、
+ * 未知状态、内容校验失败、pending 无法安全重放、本地终态 vs 远端活跃）一律
+ * reconciliation_required，绝不自动生成新的商业承诺（§23 / §27）。
+ * 恢复只对 a2a-direct 通道生效：hosted 通道有独立的 claim/stale 恢复机制，不走
+ * 本流程（§24）。非 direct 通道 → reconciliation_required（不猜测，§4.6）。
+ */
+import { computeEnvelopeDigest, validateEnvelope, verifyEnvelopeDigest } from "../domain/envelope.js";
+import { NegotiationValidationError } from "../domain/common.js";
+import { isTerminalPhase } from "../state/phase.js";
+import { isTaskState } from "../../a2a/task/index.js";
+import { KNP_ENVELOPE_DATA_KEY } from "../../a2a/server/inbound-message.js";
+import { openChannel, selectChannelCandidate, } from "../../counterparty/index.js";
+const RECOVERY_CAPABILITY = { capability: "knp.a2a.recovery", protocol_version: "1.0" };
+/** 恢复子系统的审计身份（reconciliation 事件的 sender 侧）。 */
+export const RECOVERY_SENDER_IDENTITY = "kiwi.recovery";
+/**
+ * 从 Ledger 事件推断本地会话的 sender_identity（基线 §23 / §25.2）。
+ *
+ * 恢复重放必须以原会话身份打开通道：幂等主键是 (sender_identity, message_id)，
+ * 若硬编码成 "kiwi.recovery"，pending 消息的键与原发送不匹配 → idempotency
+ * check() 返回 new → A2ADirectChannel 真实重发并在 Ledger 产生第二条
+ * message_sent（审计重复，§23）。此处优先取 message_sent 事件的 identity
+ * snapshot（出站身份）；无出站消息时取任一非 reconciliation 事件的
+ * sender_identity（reconciliation 是恢复子系统自身审计，不算会话身份）；全部
+ * 缺失回退 RECOVERY_SENDER_IDENTITY（保持既有兜底）。
+ */
+export function deriveSessionIdentity(events) {
+    for (const event of events) {
+        if (event.event_kind === "message_sent") {
+            return event.identity.sender_identity;
+        }
+    }
+    for (const event of events) {
+        if (event.event_kind !== "reconciliation") {
+            return event.identity.sender_identity;
+        }
+    }
+    return RECOVERY_SENDER_IDENTITY;
+}
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function defaultViewMessageIds(state) {
+    const id = state.task?.status.message?.messageId;
+    return id === undefined ? [] : [id];
+}
+/** 第 1 步：从 Ledger 的 state_transition 事件重建本地 phase；无记录时 OPEN。 */
+export function deriveLocalPhase(events) {
+    let phase = "OPEN";
+    for (const event of events) {
+        if (event.state_transition?.to_phase !== undefined) {
+            phase = event.state_transition.to_phase;
+        }
+    }
+    return phase;
+}
+/** 从 Ledger 事件收集本地出站消息（message_sent 事件）。 */
+export function collectOutbound(events) {
+    const entries = [];
+    for (const event of events) {
+        if (event.event_kind !== "message_sent" || event.message_id === undefined)
+            continue;
+        const entry = { message_id: event.message_id };
+        if (event.wire_digest !== undefined)
+            entry.wire_digest = event.wire_digest;
+        if (event.wire_payload !== undefined)
+            entry.wire_payload = event.wire_payload;
+        if (event.remote_task_id !== undefined)
+            entry.remote_task_id = event.remote_task_id;
+        entries.push(entry);
+    }
+    return entries;
+}
+/** Ledger 中最后一次记录的任务状态（system 观察事件），供 revision 比对。 */
+function lastRecordedTaskState(events) {
+    let state;
+    for (const event of events) {
+        if (event.event_kind !== "system" || event.outcome.kind !== "ok")
+            continue;
+        const result = event.outcome.result;
+        if (result === undefined || typeof result !== "object")
+            continue;
+        const raw = result["task_state"];
+        if (isTaskState(raw))
+            state = raw;
+    }
+    return state;
+}
+/** 校验远端 task 携带的 KNP envelope；返回 messageId → 已校验 envelope。 */
+function extractValidatedEnvelopes(task) {
+    const map = new Map();
+    const validatePart = (part) => {
+        if (part.kind !== "data")
+            return null;
+        const raw = part.data[KNP_ENVELOPE_DATA_KEY];
+        if (raw === undefined)
+            return null;
+        const env = validateEnvelope(raw);
+        if (!verifyEnvelopeDigest(env)) {
+            throw new NegotiationValidationError("state_conflict", "remote task envelope digest mismatch (integrity failure)", "/digest");
+        }
+        return env;
+    };
+    const message = task.status.message;
+    if (message !== undefined) {
+        for (const part of message.parts) {
+            const env = validatePart(part);
+            if (env !== null)
+                map.set(message.messageId, env);
+        }
+    }
+    // artifacts 无 messageId：同样校验（远端内容 untrusted，§4.5），但不键控。
+    for (const artifact of task.artifacts ?? []) {
+        for (const part of artifact.parts)
+            validatePart(part);
+    }
+    return map;
+}
+export class NegotiationRecovery {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    nowIso() {
+        return this.deps.now?.() ?? new Date().toISOString();
+    }
+    toView(state) {
+        const ids = (this.deps.viewMessageIds ?? defaultViewMessageIds)(state);
+        return { task: state.task ?? null, message_ids: [...new Set(ids)] };
+    }
+    reconciliationContent(negotiationId, profile, input) {
+        return {
+            event_kind: "reconciliation",
+            negotiation_id: negotiationId,
+            message_id: input.message_id,
+            remote_context_id: input.remote_context_id,
+            remote_task_id: input.remote_task_id,
+            identity: {
+                sender_identity: RECOVERY_SENDER_IDENTITY,
+                counterparty_identity: profile?.identity ?? "unresolved",
+            },
+            capability: { ...RECOVERY_CAPABILITY },
+            wire_payload: input.wire_payload,
+            outcome: input.outcome,
+            occurred_at: input.occurred_at,
+        };
+    }
+    /** 失败审计：不可调和的原因落 reconciliation error 事件后转人工。 */
+    async required(negotiationId, reason, hwm, phase, remoteState) {
+        try {
+            this.deps.ledger.append(this.reconciliationContent(negotiationId, null, {
+                outcome: { kind: "error", code: "reconciliation_required", message: reason },
+                occurred_at: this.nowIso(),
+            }));
+        }
+        catch (err) {
+            this.deps.log?.("recovery failed to record reconciliation_required evidence", err);
+        }
+        return {
+            status: "reconciliation_required",
+            negotiation_id: negotiationId,
+            reason,
+            replayed_message_ids: [],
+            remote_ahead_appended: 0,
+            stale_message_ids: [],
+            resume_task_ids: [],
+            phase,
+            remote_state: remoteState,
+            high_water_mark: hwm,
+        };
+    }
+    makeChannel(profile, input) {
+        if (this.deps.openChannel !== undefined)
+            return this.deps.openChannel(profile, input);
+        // 默认装配也注入 idempotency：恢复重放复用原 (sender_identity, message_id)
+        // 幂等键 → check() 返回 replayed → 通道不重复落 message_sent（§23/§25.2）。
+        return openChannel(profile, { ledger: this.deps.ledger, idempotency: this.deps.idempotency }, input);
+    }
+    /**
+     * 执行八步恢复。任何不确定性 fail-closed → reconciliation_required。
+     */
+    async recover(negotiationId) {
+        const { ledger, contextMap, resolveCounterparty } = this.deps;
+        const now = this.nowIso();
+        // 1. Load local negotiation（从 Ledger 重建）。
+        let events;
+        let hwm;
+        try {
+            events = ledger.events(negotiationId);
+            hwm = ledger.highWaterMark(negotiationId);
+        }
+        catch (err) {
+            return this.required(negotiationId, `ledger unreadable: ${errMsg(err)}`, emptyHwm(negotiationId));
+        }
+        const phase = deriveLocalPhase(events);
+        const localSent = collectOutbound(events);
+        const localTaskState = lastRecordedTaskState(events);
+        // 恢复重放沿用原会话身份（§23/§25.2）：从 Ledger identity snapshot 取，
+        // 不用硬编码 —— 否则幂等键 (sender_identity, message_id) 错位，通道会
+        // 真实重发并在 Ledger 产生第二条 message_sent。
+        const senderIdentity = deriveSessionIdentity(events);
+        // 2. Ledger high-water mark + 链完整性（损坏即 fail-closed，绝不可信）。
+        const chain = ledger.verifyChain(negotiationId);
+        if (!chain.valid) {
+            return this.required(negotiationId, `ledger chain invalid (${chain.error?.code ?? "unknown"} at index ${chain.error?.index ?? -1})`, hwm, phase);
+        }
+        let map = null;
+        try {
+            map = contextMap.get(negotiationId);
+        }
+        catch (err) {
+            return this.required(negotiationId, `context map corrupt: ${errMsg(err)}`, hwm, phase);
+        }
+        // 3. Resolve counterparty/profile。
+        let profile;
+        try {
+            profile = await resolveCounterparty(negotiationId);
+        }
+        catch (err) {
+            return this.required(negotiationId, `counterparty resolution failed: ${errMsg(err)}`, hwm, phase);
+        }
+        if (profile === null) {
+            if (localSent.length > 0) {
+                return this.required(negotiationId, "outbound messages pending but no counterparty profile", hwm, phase);
+            }
+            return this.resumed(negotiationId, hwm, phase, undefined, [], 0, [], map?.task_ids ?? []);
+        }
+        const contextId = map?.remote_context_id;
+        const taskIds = map?.task_ids ?? [];
+        const activeTaskId = taskIds.at(-1);
+        // 恢复只支持 direct 通道（§24：hosted 有独立的 claim/stale 恢复机制）。
+        // 先按确定性选择判定，不打开非 direct 通道（避免 hosted claim 副作用）。
+        const selected = selectChannelCandidate(profile);
+        if (selected === null || selected.kind !== "a2a-direct") {
+            return this.required(negotiationId, `recovery requires an a2a-direct channel (selected ${selected?.kind ?? "none"})`, hwm, phase);
+        }
+        let handle;
+        try {
+            handle = await this.makeChannel(profile, {
+                negotiation_id: negotiationId,
+                sender_identity: senderIdentity,
+                identity: profile.identity,
+                remote: { context_id: contextId, task_id: activeTaskId },
+            });
+        }
+        catch (err) {
+            return this.required(negotiationId, `channel open failed: ${errMsg(err)}`, hwm, phase);
+        }
+        // 防御性兜底：注入的 openChannel 若返回非 direct handle 仍 fail-closed。
+        if (handle.kind !== "a2a-direct") {
+            return this.required(negotiationId, `recovery requires an a2a-direct channel (opened ${handle.kind})`, hwm, phase);
+        }
+        // 4. Re-fetch remote task state。
+        let view = { task: null, message_ids: [] };
+        let validatedEnvelopes = new Map();
+        if (activeTaskId !== undefined) {
+            let state;
+            try {
+                state = await handle.getState({
+                    negotiation_id: negotiationId,
+                    context_id: contextId,
+                    task_id: activeTaskId,
+                });
+            }
+            catch (err) {
+                this.deps.log?.(`recovery getState(${activeTaskId}) failed`, err);
+                return this.required(negotiationId, `remote task unreachable: ${errMsg(err)}`, hwm, phase);
+            }
+            const task = state.task;
+            if (task !== undefined && task.status.state === "unknown") {
+                return this.required(negotiationId, "remote task state is unknown (fail-closed)", hwm, phase);
+            }
+            if (task !== undefined) {
+                try {
+                    validatedEnvelopes = extractValidatedEnvelopes(task);
+                }
+                catch (err) {
+                    return this.required(negotiationId, `remote task content failed validation: ${errMsg(err)}`, hwm, phase);
+                }
+            }
+            view = this.toView(state);
+        }
+        // 5. Compare acknowledged messages。
+        const remoteIds = new Set(view.message_ids);
+        const localIds = new Set(events.filter((e) => e.message_id !== undefined).map((e) => e.message_id));
+        const remoteAhead = [...remoteIds].filter((id) => !localIds.has(id));
+        const pending = localSent.filter((entry) => !remoteIds.has(entry.message_id));
+        // 6. Reconcile。
+        // 6a. remote ahead：fetch → validate（已做）→ append Ledger。
+        let appended = 0;
+        for (const mid of remoteAhead) {
+            if (ledger.findByMessageId(mid) !== null)
+                continue;
+            const envelope = validatedEnvelopes.get(mid);
+            try {
+                ledger.append(this.reconciliationContent(negotiationId, profile, {
+                    message_id: mid,
+                    remote_context_id: contextId,
+                    remote_task_id: activeTaskId,
+                    wire_payload: envelope === undefined ? undefined : envelope,
+                    outcome: {
+                        kind: "ok",
+                        result: {
+                            remote_ahead_message_id: mid,
+                            remote_state: view.task?.status.state,
+                        },
+                    },
+                    occurred_at: now,
+                }));
+                appended += 1;
+            }
+            catch (err) {
+                return this.required(negotiationId, `failed to append remote-ahead reconciliation: ${errMsg(err)}`, hwm, phase, view.task?.status.state);
+            }
+        }
+        // 6b. local pending：同 message_id + 同 digest → 安全幂等重放；否则转人工。
+        if (pending.length > 0 && contextId === undefined && activeTaskId === undefined) {
+            return this.required(negotiationId, "local pending messages but no remote context/task anchor to continue", hwm, phase);
+        }
+        const replayed = [];
+        for (const entry of pending) {
+            // 幂等守卫：先前一次恢复已重放过该消息（reconciliation 事件记录了
+            // replayed_message_id），不再重复发送、不再重复落账。
+            if (hasReplayEvidence(events, entry.message_id)) {
+                replayed.push(entry.message_id);
+                continue;
+            }
+            const remoteState = view.task?.status.state;
+            if (remoteState !== undefined && isTerminalTaskStateValue(remoteState)) {
+                return this.required(negotiationId, `local message ${entry.message_id} pending but remote task is terminal (${remoteState})`, hwm, phase, remoteState);
+            }
+            // 同 id + 同 digest 校验：重算 envelope digest 与存储的 wire_digest 一致。
+            const digestOk = entry.wire_digest !== undefined &&
+                entry.wire_payload !== undefined &&
+                entry.wire_payload["message_id"] === entry.message_id &&
+                computeEnvelopeDigest(entry.wire_payload) === entry.wire_digest;
+            if (!digestOk) {
+                return this.required(negotiationId, `local message ${entry.message_id} cannot be verified for safe replay (missing/conflicting digest)`, hwm, phase);
+            }
+            const envelope = entry.wire_payload;
+            const ref = {
+                negotiation_id: negotiationId,
+                context_id: contextId,
+                task_id: activeTaskId,
+            };
+            try {
+                const result = await handle.send({ envelope, ref });
+                replayed.push(entry.message_id);
+                ledger.append(this.reconciliationContent(negotiationId, profile, {
+                    message_id: entry.message_id,
+                    remote_context_id: contextId,
+                    remote_task_id: activeTaskId,
+                    outcome: { kind: "ok", result: { replayed_message_id: entry.message_id } },
+                    occurred_at: now,
+                }));
+                // 重放响应可能携带远端新信息（如 counter）：补记 remote ahead。
+                if (result.task !== undefined) {
+                    const replyState = {
+                        channel: "a2a-direct",
+                        state: result.task.status.state,
+                        stable: true,
+                        task: result.task,
+                        message_ids: result.task.status.message?.messageId === undefined
+                            ? []
+                            : [result.task.status.message.messageId],
+                        observed_at: now,
+                    };
+                    const replyView = this.toView(replyState);
+                    for (const mid of replyView.message_ids) {
+                        if (localIds.has(mid) || ledger.findByMessageId(mid) !== null)
+                            continue;
+                        ledger.append(this.reconciliationContent(negotiationId, profile, {
+                            message_id: mid,
+                            remote_context_id: contextId,
+                            remote_task_id: result.task?.id,
+                            outcome: {
+                                kind: "ok",
+                                result: { remote_ahead_message_id: mid, remote_state: result.task?.status.state },
+                            },
+                            occurred_at: now,
+                        }));
+                        appended += 1;
+                    }
+                }
+            }
+            catch (err) {
+                return this.required(negotiationId, `safe replay of ${entry.message_id} failed: ${errMsg(err)}`, hwm, phase);
+            }
+        }
+        // 本地终态 vs 远端活跃：矛盾，不可调和。
+        const remoteState = view.task?.status.state;
+        if (isTerminalPhase(phase) && remoteState !== undefined && !isTerminalTaskStateValue(remoteState)) {
+            return this.required(negotiationId, `local phase ${phase} is terminal but remote task is still ${remoteState}`, hwm, phase, remoteState);
+        }
+        // 7. Expire stale candidates/approvals：远端 revision 变化 → 本地出站消息置 stale。
+        const stale = [];
+        const revisionChanged = localTaskState !== undefined && remoteState !== undefined && localTaskState !== remoteState;
+        if (revisionChanged) {
+            for (const entry of localSent)
+                stale.push(entry.message_id);
+        }
+        if (this.deps.expireStale !== undefined && stale.length > 0) {
+            try {
+                await this.deps.expireStale(negotiationId, stale);
+            }
+            catch (err) {
+                return this.required(negotiationId, `expireStale failed: ${errMsg(err)}`, hwm, phase, remoteState);
+            }
+        }
+        // 8. Resume。
+        return this.resumed(negotiationId, hwm, phase, remoteState, replayed, appended, stale, taskIds);
+    }
+    resumed(negotiationId, hwm, phase, remoteState, replayed = [], appended = 0, stale = [], resumeTaskIds = []) {
+        return {
+            status: "resumed",
+            negotiation_id: negotiationId,
+            replayed_message_ids: replayed,
+            remote_ahead_appended: appended,
+            stale_message_ids: stale,
+            resume_task_ids: resumeTaskIds,
+            phase,
+            remote_state: remoteState,
+            high_water_mark: hwm,
+        };
+    }
+}
+function isTerminalTaskStateValue(value) {
+    return value === "completed" || value === "canceled" || value === "failed";
+}
+/** 该消息是否已有成功重放的 reconciliation 证据（幂等守卫）。 */
+function hasReplayEvidence(events, messageId) {
+    for (const event of events) {
+        if (event.event_kind !== "reconciliation" || event.outcome.kind !== "ok")
+            continue;
+        const result = event.outcome.result;
+        if (result === undefined || typeof result !== "object")
+            continue;
+        if (result["replayed_message_id"] === messageId)
+            return true;
+    }
+    return false;
+}
+/** Ledger 无法读取时的占位高水位（恢复第一步 fail-closed 用）。 */
+function emptyHwm(negotiationId) {
+    return {
+        negotiation_id: negotiationId,
+        count: 0,
+        last_event_id: null,
+        last_event_digest: null,
+        last_recorded_at: null,
+    };
+}
+//# sourceMappingURL=recover.js.map

package/dist/negotiation/recovery/recover.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recover.js","sourceRoot":"","sources":["../../../src/negotiation/recovery/recover.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAEtG,OAAO,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,EAAE,eAAe,EAAyB,MAAM,mBAAmB,CAAC;AAO3E,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AAE5E,OAAO,EACL,WAAW,EACX,sBAAsB,GAKvB,MAAM,6BAA6B,CAAC;AAWrC,MAAM,mBAAmB,GAAG,EAAE,UAAU,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,KAAK,EAAW,CAAC;AACjG,+CAA+C;AAC/C,MAAM,CAAC,MAAM,wBAAwB,GAAG,eAAe,CAAC;AAExD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAqB;IACzD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,KAAK,CAAC,UAAU,KAAK,cAAc,EAAE,CAAC;YACxC,OAAO,KAAK,CAAC,QAAQ,CAAC,eAAe,CAAC;QACxC,CAAC;IACH,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,KAAK,CAAC,UAAU,KAAK,gBAAgB,EAAE,CAAC;YAC1C,OAAO,KAAK,CAAC,QAAQ,CAAC,eAAe,CAAC;QACxC,CAAC;IACH,CAAC;IACD,OAAO,wBAAwB,CAAC;AAClC,CAAC;AAED,SAAS,MAAM,CAAC,GAAY;IAC1B,OAAO,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAC1D,CAAC;AAED,SAAS,qBAAqB,CAAC,KAAkB;IAC/C,MAAM,EAAE,GAAG,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,OAAO,EAAE,SAAS,CAAC;IACjD,OAAO,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AACtC,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,gBAAgB,CAAC,MAAqB;IACpD,IAAI,KAAK,GAAqB,MAAM,CAAC;IACrC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,KAAK,CAAC,gBAAgB,EAAE,QAAQ,KAAK,SAAS,EAAE,CAAC;YACnD,KAAK,GAAG,KAAK,CAAC,gBAAgB,CAAC,QAAQ,CAAC;QAC1C,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,4CAA4C;AAC5C,MAAM,UAAU,eAAe,CAAC,MAAqB;IACnD,MAAM,OAAO,GAA0B,EAAE,CAAC;IAC1C,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,KAAK,CAAC,UAAU,KAAK,cAAc,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS;YAAE,SAAS;QACpF,MAAM,KAAK,GAAwB,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC;QACpE,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS;YAAE,KAAK,CAAC,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC;QAC3E,IAAI,KAAK,CAAC,YAAY,KAAK,SAAS;YAAE,KAAK,CAAC,YAAY,GAAG,KAAK,CAAC,YAAY,CAAC;QAC9E,IAAI,KAAK,CAAC,cAAc,KAAK,SAAS;YAAE,KAAK,CAAC,cAAc,GAAG,KAAK,CAAC,cAAc,CAAC;QACpF,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,sDAAsD;AACtD,SAAS,qBAAqB,CAAC,MAAqB;IAClD,IAAI,KAA+B,CAAC;IACpC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,KAAK,CAAC,UAAU,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,KAAK,IAAI;YAAE,SAAS;QAC3E,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QACpC,IAAI,MAAM,KAAK,SAAS,IAAI,OAAO,MAAM,KAAK,QAAQ;YAAE,SAAS;QACjE,MAAM,GAAG,GAAI,MAAkC,CAAC,YAAY,CAAC,CAAC;QAC9D,IAAI,WAAW,CAAC,GAAG,CAAC;YAAE,KAAK,GAAG,GAAG,CAAC;IACpC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,8DAA8D;AAC9D,SAAS,yBAAyB,CAAC,IAAa;IAC9C,MAAM,GAAG,GAAG,IAAI,GAAG,EAA+B,CAAC;IACnD,MAAM,YAAY,GAAG,CAAC,IAAa,EAA8B,EAAE;QACjE,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM;YAAE,OAAO,IAAI,CAAC;QACtC,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;QAC7C,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QACnC,MAAM,GAAG,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,EAAE,CAAC;YAC/B,MAAM,IAAI,0BAA0B,CAClC,gBAAgB,EAChB,0DAA0D,EAC1D,SAAS,CACV,CAAC;QACJ,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC,CAAC;IACF,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC;IACpC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;YACjC,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;YAC/B,IAAI,GAAG,KAAK,IAAI;gBAAE,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;QACpD,CAAC;IACH,CAAC;IACD,wDAAwD;IACxD,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,IAAI,EAAE,EAAE,CAAC;QAC5C,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,KAAK;YAAE,YAAY,CAAC,IAAI,CAAC,CAAC;IACxD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,OAAO,mBAAmB;IACb,IAAI,CAAe;IAEpC,YAAY,IAAkB;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAEO,MAAM;QACZ,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACvD,CAAC;IAEO,MAAM,CAAC,KAAkB;QAC/B,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,cAAc,IAAI,qBAAqB,CAAC,CAAC,KAAK,CAAC,CAAC;QACvE,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,IAAI,EAAE,WAAW,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;IACtE,CAAC;IAEO,qBAAqB,CAC3B,aAAqB,EACrB,OAAmC,EACnC,KAOC;QAED,OAAO;YACL,UAAU,EAAE,gBAAgB;YAC5B,cAAc,EAAE,aAAa;YAC7B,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,iBAAiB,EAAE,KAAK,CAAC,iBAAiB;YAC1C,cAAc,EAAE,KAAK,CAAC,cAAc;YACpC,QAAQ,EAAE;gBACR,eAAe,EAAE,wBAAwB;gBACzC,qBAAqB,EAAE,OAAO,EAAE,QAAQ,IAAI,YAAY;aACzD;YACD,UAAU,EAAE,EAAE,GAAG,mBAAmB,EAAE;YACtC,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,WAAW,EAAE,KAAK,CAAC,WAAW;SAC/B,CAAC;IACJ,CAAC;IAED,iDAAiD;IACzC,KAAK,CAAC,QAAQ,CACpB,aAAqB,EACrB,MAAc,EACd,GAAwB,EACxB,KAAwB,EACxB,WAA0B;QAE1B,IAAI,CAAC;YACH,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CACrB,IAAI,CAAC,qBAAqB,CAAC,aAAa,EAAE,IAAI,EAAE;gBAC9C,OAAO,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,yBAAyB,EAAE,OAAO,EAAE,MAAM,EAAE;gBAC5E,WAAW,EAAE,IAAI,CAAC,MAAM,EAAE;aAC3B,CAAC,CACH,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,4DAA4D,EAAE,GAAG,CAAC,CAAC;QACrF,CAAC;QACD,OAAO;YACL,MAAM,EAAE,yBAAyB;YACjC,cAAc,EAAE,aAAa;YAC7B,MAAM;YACN,oBAAoB,EAAE,EAAE;YACxB,qBAAqB,EAAE,CAAC;YACxB,iBAAiB,EAAE,EAAE;YACrB,eAAe,EAAE,EAAE;YACnB,KAAK;YACL,YAAY,EAAE,WAAW;YACzB,eAAe,EAAE,GAAG;SACrB,CAAC;IACJ,CAAC;IAEO,WAAW,CAAC,OAA4B,EAAE,KAAuB;QACvE,IAAI,IAAI,CAAC,IAAI,CAAC,WAAW,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACtF,4DAA4D;QAC5D,8DAA8D;QAC9D,OAAO,WAAW,CAChB,OAAO,EACP,EAAE,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAChE,KAAK,CACN,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAO,CAAC,aAAqB;QACjC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,mBAAmB,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC;QAC9D,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QAE1B,0CAA0C;QAC1C,IAAI,MAAqB,CAAC;QAC1B,IAAI,GAAwB,CAAC;QAC7B,IAAI,CAAC;YACH,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;YACtC,GAAG,GAAG,MAAM,CAAC,aAAa,CAAC,aAAa,CAAC,CAAC;QAC5C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,IAAI,CAAC,QAAQ,CAClB,aAAa,EACb,sBAAsB,MAAM,CAAC,GAAG,CAAC,EAAE,EACnC,QAAQ,CAAC,aAAa,CAAC,CACxB,CAAC;QACJ,CAAC;QACD,MAAM,KAAK,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;QACvC,MAAM,SAAS,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;QAC1C,MAAM,cAAc,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAC;QACrD,uDAAuD;QACvD,sDAAsD;QACtD,oCAAoC;QACpC,MAAM,cAAc,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAC;QAErD,0DAA0D;QAC1D,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,CAAC,aAAa,CAAC,CAAC;QAChD,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;YACjB,OAAO,IAAI,CAAC,QAAQ,CAClB,aAAa,EACb,yBAAyB,KAAK,CAAC,KAAK,EAAE,IAAI,IAAI,SAAS,aAAa,KAAK,CAAC,KAAK,EAAE,KAAK,IAAI,CAAC,CAAC,GAAG,EAC/F,GAAG,EACH,KAAK,CACN,CAAC;QACJ,CAAC;QAED,IAAI,GAAG,GAA0B,IAAI,CAAC;QACtC,IAAI,CAAC;YACH,GAAG,GAAG,UAAU,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;QACtC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,IAAI,CAAC,QAAQ,CAAC,aAAa,EAAE,wBAAwB,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;QACzF,CAAC;QAED,mCAAmC;QACnC,IAAI,OAAmC,CAAC;QACxC,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,mBAAmB,CAAC,aAAa,CAAC,CAAC;QACrD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,IAAI,CAAC,QAAQ,CAAC,aAAa,EAAE,mCAAmC,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;QACpG,CAAC;QACD,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACrB,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACzB,OAAO,IAAI,CAAC,QAAQ,CAAC,aAAa,EAAE,uDAAuD,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;YAC3G,CAAC;YACD,OAAO,IAAI,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,QAAQ,IAAI,EAAE,CAAC,CAAC;QAC5F,CAAC;QAED,MAAM,SAAS,GAAG,GAAG,EAAE,iBAAiB,CAAC;QACzC,MAAM,OAAO,GAAG,GAAG,EAAE,QAAQ,IAAI,EAAE,CAAC;QACpC,MAAM,YAAY,GAAG,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QAEpC,qDAAqD;QACrD,iDAAiD;QACjD,MAAM,QAAQ,GAAG,sBAAsB,CAAC,OAAO,CAAC,CAAC;QACjD,IAAI,QAAQ,KAAK,IAAI,IAAI,QAAQ,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;YACxD,OAAO,IAAI,CAAC,QAAQ,CAClB,aAAa,EACb,qDAAqD,QAAQ,EAAE,IAAI,IAAI,MAAM,GAAG,EAChF,GAAG,EACH,KAAK,CACN,CAAC;QACJ,CAAC;QAED,IAAI,MAAqB,CAAC;QAC1B,IAAI,CAAC;YACH,MAAM,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE;gBACvC,cAAc,EAAE,aAAa;gBAC7B,eAAe,EAAE,cAAc;gBAC/B,QAAQ,EAAE,OAAO,CAAC,QAAQ;gBAC1B,MAAM,EAAE,EAAE,UAAU,EAAE,SAAS,EAAE,OAAO,EAAE,YAAY,EAAE;aACzD,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,IAAI,CAAC,QAAQ,CAAC,aAAa,EAAE,wBAAwB,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;QACzF,CAAC;QACD,0DAA0D;QAC1D,IAAI,MAAM,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;YACjC,OAAO,IAAI,CAAC,QAAQ,CAClB,aAAa,EACb,mDAAmD,MAAM,CAAC,IAAI,GAAG,EACjE,GAAG,EACH,KAAK,CACN,CAAC;QACJ,CAAC;QAED,iCAAiC;QACjC,IAAI,IAAI,GAAoD,EAAE,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC;QAC5F,IAAI,kBAAkB,GAAG,IAAI,GAAG,EAA+B,CAAC;QAChE,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;YAC/B,IAAI,KAAkB,CAAC;YACvB,IAAI,CAAC;gBACH,KAAK,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC;oBAC5B,cAAc,EAAE,aAAa;oBAC7B,UAAU,EAAE,SAAS;oBACrB,OAAO,EAAE,YAAY;iBACtB,CAAC,CAAC;YACL,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,qBAAqB,YAAY,UAAU,EAAE,GAAG,CAAC,CAAC;gBAClE,OAAO,IAAI,CAAC,QAAQ,CAAC,aAAa,EAAE,4BAA4B,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;YAC7F,CAAC;YACD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;YACxB,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;gBAC1D,OAAO,IAAI,CAAC,QAAQ,CAAC,aAAa,EAAE,4CAA4C,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;YAChG,CAAC;YACD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;gBACvB,IAAI,CAAC;oBACH,kBAAkB,GAAG,yBAAyB,CAAC,IAAI,CAAC,CAAC;gBACvD,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,OAAO,IAAI,CAAC,QAAQ,CAClB,aAAa,EACb,0CAA0C,MAAM,CAAC,GAAG,CAAC,EAAE,EACvD,GAAG,EACH,KAAK,CACN,CAAC;gBACJ,CAAC;YACH,CAAC;YACD,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC5B,CAAC;QAED,oCAAoC;QACpC,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QAC5C,MAAM,QAAQ,GAAG,IAAI,GAAG,CACtB,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAoB,CAAC,CACpF,CAAC;QACF,MAAM,WAAW,GAAG,CAAC,GAAG,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;QACrE,MAAM,OAAO,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC;QAE9E,gBAAgB;QAChB,wDAAwD;QACxD,IAAI,QAAQ,GAAG,CAAC,CAAC;QACjB,KAAK,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;YAC9B,IAAI,MAAM,CAAC,eAAe,CAAC,GAAG,CAAC,KAAK,IAAI;gBAAE,SAAS;YACnD,MAAM,QAAQ,GAAG,kBAAkB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC7C,IAAI,CAAC;gBACH,MAAM,CAAC,MAAM,CACX,IAAI,CAAC,qBAAqB,CAAC,aAAa,EAAE,OAAO,EAAE;oBACjD,UAAU,EAAE,GAAG;oBACf,iBAAiB,EAAE,SAAS;oBAC5B,cAAc,EAAE,YAAY;oBAC5B,YAAY,EAAE,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAE,QAA+C;oBACnG,OAAO,EAAE;wBACP,IAAI,EAAE,IAAI;wBACV,MAAM,EAAE;4BACN,uBAAuB,EAAE,GAAG;4BAC5B,YAAY,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK;yBACtC;qBACF;oBACD,WAAW,EAAE,GAAG;iBACjB,CAAC,CACH,CAAC;gBACF,QAAQ,IAAI,CAAC,CAAC;YAChB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,IAAI,CAAC,QAAQ,CAClB,aAAa,EACb,iDAAiD,MAAM,CAAC,GAAG,CAAC,EAAE,EAC9D,GAAG,EACH,KAAK,EACL,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,CACxB,CAAC;YACJ,CAAC;QACH,CAAC;QAED,4DAA4D;QAC5D,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,SAAS,KAAK,SAAS,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;YAChF,OAAO,IAAI,CAAC,QAAQ,CAClB,aAAa,EACb,sEAAsE,EACtE,GAAG,EACH,KAAK,CACN,CAAC;QACJ,CAAC;QACD,MAAM,QAAQ,GAAa,EAAE,CAAC;QAC9B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,0CAA0C;YAC1C,sCAAsC;YACtC,IAAI,iBAAiB,CAAC,MAAM,EAAE,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC;gBAChD,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;gBAChC,SAAS;YACX,CAAC;YACD,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC;YAC5C,IAAI,WAAW,KAAK,SAAS,IAAI,wBAAwB,CAAC,WAAW,CAAC,EAAE,CAAC;gBACvE,OAAO,IAAI,CAAC,QAAQ,CAClB,aAAa,EACb,iBAAiB,KAAK,CAAC,UAAU,yCAAyC,WAAW,GAAG,EACxF,GAAG,EACH,KAAK,EACL,WAAW,CACZ,CAAC;YACJ,CAAC;YACD,6DAA6D;YAC7D,MAAM,QAAQ,GACZ,KAAK,CAAC,WAAW,KAAK,SAAS;gBAC/B,KAAK,CAAC,YAAY,KAAK,SAAS;gBAC/B,KAAK,CAAC,YAAwC,CAAC,YAAY,CAAC,KAAK,KAAK,CAAC,UAAU;gBAClF,qBAAqB,CAAC,KAAK,CAAC,YAAY,CAAC,KAAK,KAAK,CAAC,WAAW,CAAC;YAClE,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,OAAO,IAAI,CAAC,QAAQ,CAClB,aAAa,EACb,iBAAiB,KAAK,CAAC,UAAU,kEAAkE,EACnG,GAAG,EACH,KAAK,CACN,CAAC;YACJ,CAAC;YAED,MAAM,QAAQ,GAAG,KAAK,CAAC,YAA8C,CAAC;YACtE,MAAM,GAAG,GAAG;gBACV,cAAc,EAAE,aAAa;gBAC7B,UAAU,EAAE,SAAS;gBACrB,OAAO,EAAE,YAAY;aACtB,CAAC;YACF,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC;gBACpD,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;gBAChC,MAAM,CAAC,MAAM,CACX,IAAI,CAAC,qBAAqB,CAAC,aAAa,EAAE,OAAO,EAAE;oBACjD,UAAU,EAAE,KAAK,CAAC,UAAU;oBAC5B,iBAAiB,EAAE,SAAS;oBAC5B,cAAc,EAAE,YAAY;oBAC5B,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,mBAAmB,EAAE,KAAK,CAAC,UAAU,EAAE,EAAE;oBAC1E,WAAW,EAAE,GAAG;iBACjB,CAAC,CACH,CAAC;gBACF,4CAA4C;gBAC5C,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;oBAC9B,MAAM,UAAU,GAAgB;wBAC9B,OAAO,EAAE,YAAY;wBACrB,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK;wBAC/B,MAAM,EAAE,IAAI;wBACZ,IAAI,EAAE,MAAM,CAAC,IAAI;wBACjB,WAAW,EACT,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,SAAS,KAAK,SAAS;4BACjD,CAAC,CAAC,EAAE;4BACJ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC;wBAC5C,WAAW,EAAE,GAAG;qBACjB,CAAC;oBACF,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;oBAC1C,KAAK,MAAM,GAAG,IAAI,SAAS,CAAC,WAAW,EAAE,CAAC;wBACxC,IAAI,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,MAAM,CAAC,eAAe,CAAC,GAAG,CAAC,KAAK,IAAI;4BAAE,SAAS;wBACxE,MAAM,CAAC,MAAM,CACX,IAAI,CAAC,qBAAqB,CAAC,aAAa,EAAE,OAAO,EAAE;4BACjD,UAAU,EAAE,GAAG;4BACf,iBAAiB,EAAE,SAAS;4BAC5B,cAAc,EAAE,MAAM,CAAC,IAAI,EAAE,EAAE;4BAC/B,OAAO,EAAE;gCACP,IAAI,EAAE,IAAI;gCACV,MAAM,EAAE,EAAE,uBAAuB,EAAE,GAAG,EAAE,YAAY,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,EAAE;6BAClF;4BACD,WAAW,EAAE,GAAG;yBACjB,CAAC,CACH,CAAC;wBACF,QAAQ,IAAI,CAAC,CAAC;oBAChB,CAAC;gBACH,CAAC;YACH,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,IAAI,CAAC,QAAQ,CAClB,aAAa,EACb,kBAAkB,KAAK,CAAC,UAAU,YAAY,MAAM,CAAC,GAAG,CAAC,EAAE,EAC3D,GAAG,EACH,KAAK,CACN,CAAC;YACJ,CAAC;QACH,CAAC;QAED,wBAAwB;QACxB,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC;QAC5C,IAAI,eAAe,CAAC,KAAK,CAAC,IAAI,WAAW,KAAK,SAAS,IAAI,CAAC,wBAAwB,CAAC,WAAW,CAAC,EAAE,CAAC;YAClG,OAAO,IAAI,CAAC,QAAQ,CAClB,aAAa,EACb,eAAe,KAAK,yCAAyC,WAAW,EAAE,EAC1E,GAAG,EACH,KAAK,EACL,WAAW,CACZ,CAAC;QACJ,CAAC;QAED,uEAAuE;QACvE,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,MAAM,eAAe,GACnB,cAAc,KAAK,SAAS,IAAI,WAAW,KAAK,SAAS,IAAI,cAAc,KAAK,WAAW,CAAC;QAC9F,IAAI,eAAe,EAAE,CAAC;YACpB,KAAK,MAAM,KAAK,IAAI,SAAS;gBAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QAC9D,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,CAAC,WAAW,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC5D,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC;YACpD,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,IAAI,CAAC,QAAQ,CAClB,aAAa,EACb,uBAAuB,MAAM,CAAC,GAAG,CAAC,EAAE,EACpC,GAAG,EACH,KAAK,EACL,WAAW,CACZ,CAAC;YACJ,CAAC;QACH,CAAC;QAED,aAAa;QACb,OAAO,IAAI,CAAC,OAAO,CACjB,aAAa,EACb,GAAG,EACH,KAAK,EACL,WAAW,EACX,QAAQ,EACR,QAAQ,EACR,KAAK,EACL,OAAO,CACR,CAAC;IACJ,CAAC;IAEO,OAAO,CACb,aAAqB,EACrB,GAAwB,EACxB,KAAwB,EACxB,WAA0B,EAC1B,WAAqB,EAAE,EACvB,QAAQ,GAAG,CAAC,EACZ,QAAkB,EAAE,EACpB,gBAA0B,EAAE;QAE5B,OAAO;YACL,MAAM,EAAE,SAAS;YACjB,cAAc,EAAE,aAAa;YAC7B,oBAAoB,EAAE,QAAQ;YAC9B,qBAAqB,EAAE,QAAQ;YAC/B,iBAAiB,EAAE,KAAK;YACxB,eAAe,EAAE,aAAa;YAC9B,KAAK;YACL,YAAY,EAAE,WAAW;YACzB,eAAe,EAAE,GAAG;SACrB,CAAC;IACJ,CAAC;CACF;AAED,SAAS,wBAAwB,CAAC,KAAmB;IACnD,OAAO,KAAK,KAAK,WAAW,IAAI,KAAK,KAAK,UAAU,IAAI,KAAK,KAAK,QAAQ,CAAC;AAC7E,CAAC;AAED,4CAA4C;AAC5C,SAAS,iBAAiB,CAAC,MAAqB,EAAE,SAAiB;IACjE,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,KAAK,CAAC,UAAU,KAAK,gBAAgB,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,KAAK,IAAI;YAAE,SAAS;QACnF,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QACpC,IAAI,MAAM,KAAK,SAAS,IAAI,OAAO,MAAM,KAAK,QAAQ;YAAE,SAAS;QACjE,IAAK,MAAkC,CAAC,qBAAqB,CAAC,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;IAC5F,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,+CAA+C;AAC/C,SAAS,QAAQ,CAAC,aAAqB;IACrC,OAAO;QACL,cAAc,EAAE,aAAa;QAC7B,KAAK,EAAE,CAAC;QACR,aAAa,EAAE,IAAI;QACnB,iBAAiB,EAAE,IAAI;QACvB,gBAAgB,EAAE,IAAI;KACvB,CAAC;AACJ,CAAC"}

package/dist/negotiation/recovery/types.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Recovery 契约（基线 §23 / 子规范 §27）。
+ *
+ * 恢复流程八步的接缝定义。WP4 之后，对端访问面收敛为唯一
+ * `CounterpartyChannel` 接口（src/counterparty/channel.ts）：
+ *
+ *   - `resolveCounterparty` 返回 `CounterpartyProfile`（§33 AgentDiscovery 产出，
+ *     含 channel candidates）；
+ *   - `openChannel` 打开一条绑定到 negotiation 的 ChannelHandle
+ *     （send/getState/subscribe/close）；
+ *   - 恢复第 4/6 步经 ChannelHandle.getState/send 访问远端，不再有第二套
+ *     RemoteTaskGateway 契约。
+ *
+ * 「远端不可信」仍落地为：getState 返回的 A2A task / envelope 必须通过
+ * 校验才能进入 Ledger；任何不确定性 fail-closed → reconciliation_required。
+ */
+import type { A2ATaskState } from "../../a2a/client/index.js";
+import type { ChannelHandle, ChannelOpenInput, CounterpartyProfile, RemoteState } from "../../counterparty/index.js";
+import type { IdempotencyStore } from "../idempotency/index.js";
+import type { LedgerHighWaterMark } from "../ledger/index.js";
+import type { NegotiationPhase } from "../state/phase.js";
+/** negotiation_id → 对端通道档案；未知返回 null。 */
+export type CounterpartyResolver = (negotiationId: string) => Promise<CounterpartyProfile | null>;
+/** 由档案打开通道；缺省用 profile 首选候选（openChannel，绝不降级）。 */
+export type ChannelOpener = (profile: CounterpartyProfile, input: ChannelOpenInput) => Promise<ChannelHandle>;
+/** 从 RemoteState 提取远端可见 messageId；缺省取 task.status.message.messageId。 */
+export type RemoteViewMessageIds = (state: RemoteState) => string[];
+export type RecoveryStatus = "resumed" | "reconciliation_required";
+export interface RecoveryResult {
+    status: RecoveryStatus;
+    negotiation_id: string;
+    /** reconciliation_required 时的原因（转人工）。 */
+    reason?: string;
+    /** 安全重放成功的本地 pending messageId 列表（同 message_id + 同 digest）。 */
+    replayed_message_ids: string[];
+    /** remote-ahead 分支落账的 reconciliation 事件数。 */
+    remote_ahead_appended: number;
+    /** 标记为 stale（需失效）的本地 messageId。 */
+    stale_message_ids: string[];
+    /** 恢复后应继续轮询的 taskId 列表。 */
+    resume_task_ids: string[];
+    /** 恢复时重建的本地 phase。 */
+    phase?: NegotiationPhase;
+    /** 远端任务状态（如有）。 */
+    remote_state?: A2ATaskState;
+    high_water_mark: LedgerHighWaterMark;
+}
+export interface RecoveryDeps {
+    /** 本地权威审计链（§22 / §23 第 2、5 步）。 */
+    ledger: import("../ledger/index.js").LedgerStore;
+    /** negotiation_id ↔ 远端 contextId/taskId（§9.2）。 */
+    contextMap: import("../context-map/index.js").ContextMapStore;
+    /**
+     * 协议幂等（§20 / §23）。缺省装配通道时注入：恢复重放沿用原
+     * (sender_identity, message_id) 幂等键 → check() 返回 replayed → 通道不重复
+     * 落 message_sent（§25.2）。注入 openChannel 时由注入方负责。
+     */
+    idempotency?: IdempotencyStore;
+    /** 对端通道档案解析（第 3 步）。 */
+    resolveCounterparty: CounterpartyResolver;
+    /** 打开通道（第 3 步后）；缺省用 profile 首选候选。 */
+    openChannel?: ChannelOpener;
+    /** 从 RemoteState 提取远端已确认 messageId；缺省取 task.status.message.messageId。 */
+    viewMessageIds?: RemoteViewMessageIds;
+    /** 第 7 步失效接缝：把 stale 的候选/批准标记为过期（WP 接线方实现）。 */
+    expireStale?: (negotiationId: string, staleMessageIds: string[]) => void | Promise<void>;
+    /** 可注入时钟（RFC 3339）。 */
+    now?: () => string;
+    log?: (message: string, err?: unknown) => void;
+}