@zhushanwen/session-delivery 2.0.0 → 2.2.0

package/dist/index.d.mts

@@ -9,12 +9,11 @@
  * v2 增量（投递所有权内核，v2 设计批次——设计文档未入 git，裁决随本仓 commit
  * 历史可溯）：
  * 条目状态机/lane/条目双形态（活跃条目 + 终局记录）/entriesFull()+projection() 双视图；行为实现在
- * 本包 src/delivery.ts。lane 字面量中的 'steer' 是投递车道语义名（设计 §1.1 术语表
- * /D1），非 pi API 词汇——intent → 底层参数的翻译在适配器内部，本包只记录车道，
+ * 本包 src/delivery.ts。lane 字面量中的 'steer' 是投递路径语义名（设计 §1.1 术语表
+ * /D1），非 pi API 词汇——intent → 底层参数的翻译在适配器内部，本包只记录投递路径，
  * 零依赖纪律对 lane 不破例。
  *
- * v3 增量（统一消息投递内核，设计 .tmp/tech-design/unified-delivery.md §3.5，波 1
- * 纯增量零行为变化——装配不传新参数 = v2 行为逐字节不变）：
+ * v3 增量（统一消息投递内核，设计 .tmp/tech-design/unified-delivery.md §3.5）：
  * - DeliveryStore 持久化存储端口（persist / ack / discard / loadUndelivered /
  *   loadTerminalIds / hasTerminal）：耐久承诺先于投递尝试；终局写持久终局；判重
  *   第三级查持久记录。两个实现在两半区适配层（runtime 半区磁盘 outbox / port 半区
@@ -28,8 +27,8 @@
  *   已完结 id 索引（loadTerminalIds 播种 + 终局即时登记）→ 持久记录（store.hasTerminal）。
  *   entriesFull() 的 tombstones 视图字段与结构保持（双视图消费方零改动），元素类型
  *   由 DeliveryTerminalRecord 承载。
- * - 受理即出站模式（DeliveryDispatchMode）：'on-accept' 旁路忙闲门禁与合批窗口；
- *   缺省 'queue-hold' = v2 队列持有行为不变。
+ * - 受理即出站（唯一出站形态，v2 队列持有分支已删）：受理后立即 port.send，无
+ *   忙闲门禁、无合批窗口（合批归 port 提交侧承载）。
  */
 /** 投递意图（D3）：turn 边界抢占 / run 结束后注入，均含 idle 唤醒语义。 */
 type DeliveryIntent = 'interrupt-at-turn-boundary' | 'after-run';
@@ -119,7 +118,7 @@ type SendReceipt = {
 interface DeliveryPort {
     /** 本通路支持的 payload kind（D9 fail-fast）。 */
     supportedPayloads: readonly DeliveryPayload['kind'][];
-    /** 主 agent 是否空闲。 */
+    /** 主 agent 是否空闲（受理即出站下内核不读——port 契约与诊断面保留）。 */
     isIdle(): boolean;
     /**
      * 投递消息（intent → pi 参数的翻译在适配器内部）。
@@ -132,12 +131,15 @@ interface DeliveryPort {
      * 处置 = 用户显式失败 + 重启应用。
      */
     send(msg: DeliveryMessage, intent: DeliveryIntent): Promise<SendReceipt | void> | SendReceipt | void;
-    /** agent_settled 边沿订阅（D8）。缺省时 busy 条目留守至外部 flush/send 触发。返回退订函数。 */
+    /**
+     * agent_settled 边沿订阅（D8）：边沿即 flush 触发（retain 失败留守条目的重投时机）。
+     * 缺省时留守条目归外部 flush/send 触发。返回退订函数。
+     */
     subscribeSettled?(cb: () => void): () => void;
 }
 /**
  * 送达凭据三档（v3，ADR-0074 词条扩展；提交方申报制，缺省 'marker'）：
- * - 'marker'：出站文本尾附裸标记、送达以回执命中为准（文本车道主通路）。
+ * - 'marker'：出站文本尾附裸标记、送达以回执命中为准（文本投递路径主通路）。
  * - 'acceptance'：受理即送达——无回执锚点条目的「受理 = 送达」是唯一可判事实，
  *   port.send 受理成功即落 delivered 终态（v1 记账口径 / D9⑤ 显式例外）。
  * - 'details-id'（v3 新增）：通知条目送达判定 = 对话记录中出现 details 携带本条目
@@ -150,19 +152,25 @@ interface DeliveryPort {
 type DeliveryReceiptAnchor = 'marker' | 'acceptance' | 'details-id';
 /**
  * 失败保留策略（v3）：port.send 失败（首败，ADR-0122 无内核自动重试）时条目的处置。
- * - 'forget'：首败即停 + 显式上报后从内核移除（runtime 文本车道现状；重试决策归
+ * - 'forget'：首败即停 + 显式上报后从内核移除（缺省 text 现状；重试决策归
  *   消费方——人看页面通知可重发）。store 已 persist 的记录同步 discard（失败条目
  *   无判重语义，防重启后被 loadUndelivered 复活成死条目）。
  * - 'retain'：失败条目留守——内存态转回 queued 等下一 settled 边沿 / 外部 flush
  *   重入队（事件驱动，无定时器）；store 记录保留（不 ack 不 discard），重启后经
- *   loadUndelivered 重入队（通知车道无人值守语义，与账本现状同构）。
+ *   loadUndelivered 重入队（通知投递路径无人值守语义，与账本现状同构）。
+ * - 'failed'（chat-flow-consistency 第 11 条）：受理失败条目转 **failed 终态留守**——
+ *   不自动重投（无 retain 的边沿重投，等用户处置：resync 重试 / cancel 撤销）、
+ *   不 store.discard（重启后经 loadUndelivered 重放，重放带 transcript 判重防线），
+ *   与断连 failInFlight 的 failed 同态同出路（队列区一行 + 重试入口双呈现）。
  *
  * 缺省按载荷类型：custom = 'retain' / text = 'forget'（§3.4 提交选项缺省值表：
- * 交互在席 vs 无人值守），提交方可显式覆写。sendChecked 挂起条目恒 'forget'（同步
- * 失败回执契约与 retain 重投矛盾——调用方已收到失败，重投会产生「失败但送达」的
- * 矛盾观测；显式申报 retain 时按 forget 处置并一次性 warn）。
+ * 交互在席 vs 无人值守），提交方可显式覆写。sendChecked 挂起条目缺省/显式 'retain'
+ * 按 'forget' 处置（同步失败回执契约与 retain 边沿重投矛盾——调用方已收到失败，
+ * 自动重投会产生「失败但送达」的矛盾观测；一次性 warn）；显式 'failed' 放行——
+ * waiter reject 是受理口径通知，failed 留守是条目状态，两者不矛盾（failed 不自动
+ * 重投，「失败但送达」观测不存在）。
  */
-type DeliveryFailurePolicy = 'forget' | 'retain';
+type DeliveryFailurePolicy = 'forget' | 'retain' | 'failed';
 /**
  * 送达凭据检查函数（v3，'details-id' 凭据的判定承载形态）：判定「对话记录中是否已
  * 存在 details 携带该 id 的通知条目」。由装配方注入实现（实现读对话记录——pi 半区
@@ -178,7 +186,7 @@ type DeliveryProofCheck = (id: string) => boolean;
 interface DeliveryStoreRecord {
     /** 客户端幂等 id（= 条目 id）。 */
     id: string;
-    /** 投递车道（重入队时按原车道重报）。 */
+    /** 投递路径（重入队时按原路径重报）。 */
     lane: DeliveryLane;
     /** 载荷（原样）。 */
     payload: DeliveryPayload;
@@ -194,16 +202,20 @@ interface DeliveryStoreRecord {
     meta?: DeliveryMeta;
 }
 /**
- * 持久化存储端口（v3，统一语言词条「持久化存储端口」）：内核与耐久面的唯一接口。
+ * 持久化存储端口（v3，统一语言词条「持久化存储端口」）：内核与耐久层的唯一接口。
  * 两个实现在两半区适配层（本包零 fs 零 pi 知识）：runtime 半区 = 磁盘 outbox 文件
- * （文本车道，波 4 接线）；port 半区 = session entry 读写（通知车道，波 2 接线）。
+ * （文本投递路径，波 4 接线）；port 半区 = session entry 读写（通知投递路径，波 2 接线）。
  *
  * 内核行为契约（设计 §3.5.1）：
  * - persist：send 受理前调用（耐久承诺先于投递尝试，与账本 record 先于 deliver 同
  *   律）。persist 抛错 = 承诺未落 → 内核拒收该条目（send 返回 persist-failed /
  *   sendChecked 同步 throw），不进入投递流程。
- * - ack：终局 delivered / cancelled 后调用（写持久终局——已撤销消息的防复活凭据
- *   同样在持久终局记录里）。ack 抛错不回滚状态机（终局事实已发生），warn 留痕。
+ * - ack：终局 delivered / cancelled 时调用（写持久终局——已撤销消息的防复活凭据
+ *   同样在持久终局记录里）。磁盘权威（2026-10-30 用户裁决「内存终态必须以磁盘确认为
+ *   准」）：ack 先于内存终态登记，抛错 = 持久终局未写入 → 内核不登记内存终态（条目
+ *   留守活跃集非终态）并显式上报分型错误 DeliveryAckPersistError；外部送达事实不
+ *   回滚，恢复后可能重投（at-least-once 显式接受）。实现方须遵守同序：自身内存派生
+ *   数据只在落盘成功后登记。
  * - discard：forget 失败条目的记录无痕移除（无终局无判重语义——区别于 ack，不进
  *   终局记录，防重启后 loadUndelivered 把已弃条目当未投递复活）。
  * - loadUndelivered：供重启 / 重放时重入队（装配方启动时取回未终局记录重新提交）。
@@ -220,7 +232,7 @@ interface DeliveryStoreRecord {
 interface DeliveryStore {
     /** 受理前写入记录（耐久承诺先于投递尝试）。抛错 = 承诺未写入，内核拒收。 */
     persist(record: DeliveryStoreRecord): void;
-    /** 终局（delivered / cancelled）后写持久终局（从待投差集移除、进终局记录）。 */
+    /** 终局（delivered / cancelled）写持久终局（从待投差集移除、进终局记录）。抛错 = 持久终局未写入 → 内核不登记内存终态（磁盘权威，见上方契约）。 */
     ack(id: string): void;
     /** forget 失败条目的记录无痕移除（无终局形态，区别于 ack）。 */
     discard(id: string): void;
@@ -235,11 +247,6 @@ interface DeliveryStore {
 interface DeliveryConfig {
     /** 默认意图：'interrupt-at-turn-boundary'（D3）。 */
     intent?: DeliveryIntent;
-    /** 合批窗口（ms）：0 = 关；>0 = 滑动窗口合批。 */
-    mergeWindowMs?: number;
-    /** 合批依赖谓词（D4 must-fix #1）。true 时 send() 走合批窗口，false/缺省时立即投。
-     *  禁止用 isIdle 代替。 */
-    mergeHoldActive?: () => boolean;
     /** 去重配置（条数 LRU）。 */
     dedupe?: {
         maxKeys: number;
@@ -258,7 +265,7 @@ interface DeliveryConfig {
      * （受理 ≠ 送达——SendReceipt 注释口径的机制化落地）。**显式例外：sendChecked 的
      * 同步 settle 维持受理口径不变**——session_manager send 的「立即受理确认」契约
      * 锚定在受理时点，后移到送达会让 agent 工具调用阻塞至目标 session 当前 turn 结束
-     * （steer 类车道可达数十秒）。本注释即接口口径权威声明。
+     * （steer 类投递路径可达数十秒）。本注释即接口口径权威声明。
      *
      * outcome 'rejected' = 失败终局通知（ADR-0122 首败即停：send 失败一次即移除条目并
      * 逐条回调；断连事件 failInFlight 转 failed 终态同样逐条回调）。重试决策归消费方，
@@ -269,7 +276,7 @@ interface DeliveryConfig {
      */
     onSettled?: (msg: DeliveryMessage, outcome: 'delivered' | 'rejected') => void;
     /**
-     * 持久化存储端口（v3）。缺省 undefined = 无耐久面（v2 行为：纯内存条目集）——
+     * 持久化存储端口（v3）。缺省 undefined = 无耐久层（v2 行为：纯内存条目集）——
      * 既有 runtime 装配不传 = 逐字节不变（波 1 零行为变化锚）。提供时内核行为契约见
      * DeliveryStore（受理前 persist / 终局 ack / forget 失败 discard / 构造期
      * loadTerminalIds 播种判重索引）。
@@ -280,25 +287,11 @@ interface DeliveryConfig {
      * 缺省 undefined = details-id 条目无法经 confirmDeliveredByProof 确认（留守 in-flight）。
      */
     proofCheck?: DeliveryProofCheck;
-    /**
-     * 出站运行模式（v3，受理即出站 / 队列持有的模式参数；设计 §3.5.6）：
-     * - 'queue-hold'（缺省）= v2 队列持有行为：busy gate（isIdle + 在途内查）排队 +
-     *   settled 边沿驱动 flush + 合批窗口出站。
-     * - 'on-accept' = 受理即出站：受理后立即 port.send（忙闲门禁旁路——承重前提 =
-     *   底层唯一队列忙时不拒，适配层保证）；合批窗口不用（队列唯一化后无组批时机，
-     *   合批归 port 提交侧承载），config.mergeWindowMs>0 与提交方 merge:true 被忽略；
-     *   in-flight 防重保留（内核自身并发保护，非忙闲门禁）；retain 失败留守条目仍经
-     *   settled 边沿 / 外部 flush 重投。
-     * runtime 装配不传 = v2 队列持有行为不变（波 1 只实现不接线）。
-     */
-    dispatchMode?: 'queue-hold' | 'on-accept';
 }
 /** 投递句柄（createDelivery 返回）。 */
 interface DeliveryHandle {
-    /** 唯一常规入口（D4 入口收敛）；合批窗口 + 空闲零延迟立即投。 */
-    send(msg: DeliveryMessage, opts?: {
-        merge?: boolean;
-    }): void;
+    /** 唯一常规入口（D4 入口收敛）；受理即出站立即投。 */
+    send(msg: DeliveryMessage): void;
     /** 入队 + 可达性同步确认。reject = 入队失败。 */
     sendChecked(msg: DeliveryMessage): Promise<void>;
     /** 强制投递尝试（shutdown flush / 外部重触发 / settled 边沿内部复用）。 */
@@ -309,8 +302,8 @@ interface DeliveryHandle {
     dispose(): void;
 }
 /**
- * 投递车道（D1）。lane 在条目创建时由 runtime 内核适配层判定（读权威 occupancy
- * 派生视图 + 内核自身队列态，单一判定源）后记录，此后不变。三档为投递车道语义名
+ * 投递路径（D1）。lane 在条目创建时由 runtime 内核适配层判定（读权威 occupancy
+ * 派生视图 + 内核自身队列态，单一判定源）后记录，此后不变。三档为投递路径语义名
  * （设计 §1.1 术语表），非底层通道 API 词汇。
  */
 type DeliveryLane = 'direct' | 'steer' | 'queued';
@@ -322,6 +315,11 @@ type DeliveryLane = 'direct' | 'steer' | 'queued';
  * - in-flight/queued → cancelled：用户撤销（delivery.cancel）
  * - in-flight → failed：断连事件驱动的未确认终局（failInFlight，ADR-0122——pi 连接
  *   断开时结果未知，显式失败交用户处置）
+ * - queued → failed：出站投递受理失败（onFailure='failed'，chat-flow-consistency
+ *   第 11 条——文本投递受理失败留守 failed 行，与断连未确认同出路，等用户处置）
+ * - failed → delivered：确定性送达事实（resync transcript 预检命中 / 迟到送达回执，
+ *   第 11 条歧义性终结——首败时文本可能已进 transcript，delivered 事实终结 failed
+ *   猜测，行随事实消失）
  * - failed → queued：用户重试（resync 单条重报）；failed → cancelled：用户移除
  * 帧派生视图四态差异：cancelled 不进 session.delivery 帧（D5③），协议侧帧 state 无此值。
  */
@@ -335,7 +333,7 @@ interface DeliveryEntry {
     /** 客户端幂等 id（= 协议层 clientUuid；裸标记身份源 D2，判重锚 D5②）。 */
     id: string;
     state: DeliveryEntryState;
-    /** 投递车道（创建时判定后记录，不变，D1）。 */
+    /** 投递路径（创建时判定后记录，不变，D1）。 */
     lane: DeliveryLane;
     /** 载荷（一期仅 text，DeliveryPayload 联合保留扩展位）。 */
     payload: DeliveryPayload;
@@ -394,22 +392,25 @@ interface DeliveryEntriesProjection {
 /**
  * 投递所有权内核实现：createDelivery（v2）。
  *
- * 在 v1 投递循环（入队 → dedupe → 合批窗口 → busy gate → port.send → settled 边沿
- * 驱动）之上升级为条目制所有权内核（v2 设计批次 D9①②③⑤ / D5②③ / D3，单元 u1——
+ * 在 v1 投递循环之上升级为条目制所有权内核（v2 设计批次 D9①②③⑤ / D5②③ / D3，单元 u1——
  * 设计文档未入 git，裁决随本仓 commit 历史可溯）。零 pi 依赖不变：确认/回收由适配器（runtime
  * registry）调 handle 方法驱动。
  *
- * 五态状态机（D9①，types.ts 迁移表）+ 本文件登记的两处实施扩展：
+ * 五态状态机（D9①，types.ts 迁移表）+ 本文件登记的实施扩展：
  * - queued → in-flight：出站投递被受理（两阶段回执第一阶段，D2）
  * - in-flight → delivered：confirmDelivered（送达回执，D2）
  * - in-flight → queued：requeue（对账回收重投，D3）
  * - queued/failed → cancelled：cancel（本地移除 + tombstone / 用户 × 移除）
  * - in-flight → failed：断连事件驱动的未确认终局（failInFlight，ADR-0122）
+ * - queued → failed：出站投递受理失败留守（onFailure='failed'，chat-flow-consistency
+ *   第 11 条——与断连未确认同出路，等用户处置）
  * - failed → queued：requeue（用户重试/resync 单条重报）
- * - [扩展①] queued → delivered：confirmDelivered 也接受 queued 态——服务 reattach
- *   场景 rebuild 直确认重建（D3②：适配器扫描 transcript 判 delivered 后 send 重建
- *   + confirmDelivered 一步落终态），以及出站批次在途时送达回执先于受理回执到达
- *   的竞态形态（message_end 比 RPC resolve 快，事实优先）。
+ * - [扩展①] queued/failed → delivered：confirmDelivered 也接受 queued 与 failed
+ *   态——queued 服务 reattach 场景 rebuild 直确认重建（D3②：适配器扫描 transcript
+ *   判 delivered 后 send 重建 + confirmDelivered 一步落终态），以及出站批次在途时
+ *   送达回执先于受理回执到达的竞态形态（message_end 比 RPC resolve 快，事实优先）；
+ *   failed 服务第 11 条受理失败的歧义性终结——迟到的送达回执 / resync 的 transcript
+ *   预检命中即确定性送达事实，行随事实消失。
  * - [扩展②] cancel 对 in-flight 两段式：首次调用只标记待收回（条目留守 in-flight，
  *   返回 reclaim-requested，适配器驱动 clear_queue 收回）；适配器收回确认后再次
  *   cancel(id) 终结为 cancelled + tombstone。收回失败不再调 → 条目留守原态
@@ -420,11 +421,14 @@ interface DeliveryEntriesProjection {
  *   合批分段中途失败时已登记段留守 in-flight（等回执/对账），仅未受理段按失败处理。
  *
  * 失败语义（ADR-0122 首败即停，2026-10-05 用户裁决，backoff 自动重试链退役）：
- * port.send 失败（含 accepted:false）一次即收尾——checked 条目 reject + 从内核移除；
- * 非 checked 条目 onSettled('rejected') 逐条显式上报 + 从内核移除。唯一例外：拒绝
- * 回执为 deferred 形态（设计内等待，DeliveryDeferReason——如 port 合批提交窗 hold）
- * 不计首败，条目留守等投递端下一边沿重提（onSendDeferred）。重试决策归消费方
- * （人看页面通知、agent 收失败回执），内核只做忠实投递与事实上报。
+ * port.send 失败（含 accepted:false）一次即收尾——处置按条目 onFailure 策略分流：
+ * forget 条目 checked reject + 从内核移除；非 checked forget 条目 onSettled('rejected')
+ * 逐条显式上报 + 从内核移除；failed 条目（chat-flow-consistency 第 11 条）转 failed
+ * 终态留守（不自动重投，等用户处置：resync 重试 / cancel 撤销），checked waiter
+ * reject 照常（受理口径通知与条目状态正交）。唯一例外：拒绝回执为 deferred 形态
+ * （设计内等待，DeliveryDeferReason——如 port 合批提交窗 hold）不计首败，条目留守
+ * 等投递端下一边沿重提（onSendDeferred）。重试决策归消费方（人看页面通知、agent
+ * 收失败回执），内核只做忠实投递与事实上报。
  *
  * onSettled 记账口径（D9⑤ 升级）：
  * - 'delivered' = 送达口径：仅 confirmDelivered 驱动回调（受理只转 in-flight，
@@ -456,39 +460,39 @@ interface DeliveryEntriesProjection {
  * 终局（store.ack）。条目 id = opts.id ?? 内部生成；未传 id 的消息不参与幂等判重
  * （v1「无 dedupe 配置不去重」语义保持）。
  *
- * v3 增量（波 1 纯增量零行为变化——装配不传新参数 = v2 行为逐字节不变）：
+ * v3 增量（统一消息投递内核，设计 unified-delivery §3.5）：
  * - DeliveryStore 端口（config.store）：send/sendChecked 受理前先 persist（耐久承诺
  *   先于投递尝试；persist 抛错 = 承诺未落 → 拒收 rejected('persist-failed')，条目
- *   回滚不入队不投递）；终局 delivered / cancelled 后 ack（finalizeEntry / drain）；
- *   forget 失败条目 discard（无终局语义的记录无痕移除，防重启复活）。ack / 判重
- *   查询的 store 异常降级 warn 留痕、状态机照常（终局事实已发生 / 探测降级同
- *   safeIsIdle 型）；persist 异常 fail-fast 拒收（承诺语义）。
+ *   回滚不入队不投递）；终局 delivered / cancelled 时 ack（finalizeEntry / drain）；
+ *   forget 失败条目 discard（无终局语义的记录无痕移除，防重启复活）。ack 先于内存
+ *   终态登记（磁盘权威，2026-10-30 用户裁决「内存终态必须以磁盘确认为准」）：写盘
+ *   失败 → 内存不登记终态（条目留守活跃集非终态）+ 分型错误 DeliveryAckPersistError
+ *   显式上报——外部送达事实不回滚，恢复后可能重投（at-least-once 显式接受）；判重
+ *   查询（hasTerminal）异常保守放行 + warn；persist 异常 fail-fast 拒收（承诺语义）。
  * - 送达凭据三档（receiptAnchor）：'details-id' 与 'marker' / 'acceptance' 并列
  *   （ADR-0074 词条扩展）。details-id 条目受理后维持 in-flight 等回执（同 marker）；
  *   判定逻辑以可注入凭据检查函数（config.proofCheck）承载，调用点 =
  *   handle.confirmDeliveredByProof(id)——装配方在回执证据到达时调用，内核按条目
  *   凭据档位分派（非 details-id 条目一律拒绝，防误确认）。
- * - 失败保留策略（opts.onFailure：'forget' | 'retain'，缺省 custom=retain /
+ * - 失败保留策略（opts.onFailure：'forget' | 'retain' | 'failed'，缺省 custom=retain /
  *   text=forget）：retain 条目首败后内存态转回 queued 留守（下一 settled 边沿 /
  *   外部 flush 重入队，事件驱动无定时器；失败轮不主动重投——防 idle 同步失败循环），
- *   store 记录保留（重启经 loadUndelivered 重入队）；forget 条目维持现状首败即停。
- *   sendChecked 挂起条目恒 forget（同步失败回执契约与 retain 重投矛盾，显式申报
- *   retain 按 forget 处置 + 一次性 warn）。
- * - 受理即出站模式（config.dispatchMode: 'on-accept'）：忙闲门禁旁路（受理后立即
- *   port.send，承重前提 = 底层唯一队列忙时不拒）+ 合批窗口不用（队列唯一化后无
- *   组批时机，合批归 port 提交侧）；in-flight 防重保留。生产装配恒为 'on-accept'
- *   （runtime session-delivery-registry 与 extensions/shared/delivery-port 均显式
- *   传参）；缺省 'queue-hold' = v2 队列持有行为（busy gate 排队 + settled 边沿
- *   flush + 合批窗口），现为仅本包测试装配消费的非生产形态（零行为变化锚）——
- *   其代码路径物理删除（含缺省值翻转 on-accept 与既有测试显式传参）留待后续
- *   清理波（登记：docs/todo/unified-delivery-residuals.md #1）。
+ *   store 记录保留（重启经 loadUndelivered 重入队）；forget 条目维持现状首败即停；
+ *   failed 条目转 failed 终态留守（无自动重投，等用户 resync 重试 / cancel 撤销——
+ *   chat-flow-consistency 第 11 条）。sendChecked 挂起条目缺省/显式 retain 按 forget
+ *   处置（同步失败回执契约与 retain 重投矛盾）；显式 failed 放行（reject 是受理口径
+ *   通知，failed 留守是条目状态，不自动重投故无矛盾观测）。
+ * - 受理即出站（v3，唯一出站形态）：受理后立即 port.send（忙闲门禁旁路——承重
+ *   前提 = 底层唯一队列忙时不拒，适配层保证）；无合批窗口（队列唯一化后无组批
+ *   时机，合批归 port 提交侧承载）；in-flight 防重保留（内核自身并发保护）；
+ *   retain 失败留守条目经 settled 边沿 / 外部 flush 重投（事件驱动，无定时器）。
+ *   v2 队列持有形态（busy gate 排队 + 合批窗口）已随队列持有分支退役删除。
  *
- * 其余 v1/v2 机制逐条保持：busy gate（isIdle + 内核在途内查双条件——hasPendingMessages
- * 自镜像四件套已按 msg-pipeline-debloat D2 拆除，busy 判定内查 active 表）、合批窗口、
- * settled 边沿驱动、dedupe LRU、dispose 语义（丢弃不触发 onSettled、checked 挂起
- * reject）。[ADR-0122 退役登记] backoff 自动重试链、port.send settle 挂死兜底
+ * 其余 v1/v2 机制逐条保持：settled 边沿驱动（send / flush / 边沿统一出站触发）、
+ * dedupe LRU、dispose 语义（丢弃不触发 onSettled、checked 挂起 reject）。
+ * [ADR-0122 退役登记] backoff 自动重试链、port.send settle 挂死兜底
  * （60s）、watchdog 30s 定时复核、无订阅装配 busy 退避轮询——时间平抑/补偿类机制
- * 全部删除，busy 等待归 settled 边沿与外部触发。depth() 口径保持 v1 = 尚未受理的
+ * 全部删除。depth() 口径保持 v1 = 尚未受理的
  * 消息数（受理转 in-flight 后不计；「在途未确认」数经 entriesFull() 全量视图消费）。
  */
 
@@ -504,17 +508,15 @@ interface DeliveryWarnSink {
 }
 /** createDelivery 配置（DeliveryConfig + warn 出口注入）。 */
 type DeliveryConfigWithWarn = DeliveryConfig & DeliveryWarnSink;
-/** send/sendChecked 提交选项（v1 `{ merge? }` 的超集，向后兼容）。 */
+/** send/sendChecked 提交选项。 */
 interface DeliverySubmitOptions {
-    /** 合批窗口判定覆盖（v1 既有）。 */
-    merge?: boolean;
     /**
      * 客户端幂等 id（= 条目 id = 协议层 clientUuid，D2 裸标记身份源/D5② 判重锚）。
      * 显式提供时参与幂等判重：命中活跃条目或 tombstone 即吞（resync 重报/重放去重）。
      * 缺省内部生成、不参与判重。
      */
     id?: string;
-    /** 投递车道（D1）：适配器判定后传入记录；缺省 'direct'（既有调用方语义）。 */
+    /** 投递路径（D1）：适配器判定后传入记录；缺省 'direct'（既有调用方语义）。 */
     lane?: DeliveryLane;
     /**
      * 送达回执锚申报（msg-pipeline-debloat D1 申报制；v3 三档，ADR-0074 词条扩展）：
@@ -529,8 +531,8 @@ interface DeliverySubmitOptions {
      *   后维持 in-flight 等回执（同 'marker'），终局由装配方调 handle.confirmDeliveredByProof
      *   驱动（判定逻辑经 config.proofCheck 注入，内核零 pi 知识）。
      *
-     * 缺省 'marker' 是刻意的保守取向：无标记提交点漏申报的代价 = 复发已知死锁形态
-     * （in-flight 永挂、gate 恒关，有全链诊断可查，可见）；误申报 'acceptance' 的代价
+   * 缺省 'marker' 是刻意的保守取向：无标记提交点漏申报的代价 = 复发已知死锁形态
+   * （in-flight 永挂——条目无人确认终态，有全链诊断可查，可见）；误申报 'acceptance' 的代价
      * = 静默丢送达确认语义（更隐蔽）。两害取可见者。新增无标记投递来源必须显式申报
      * 'acceptance' 或 'details-id' 并登记来源清单（ADR-0074 词条）。
      */
@@ -538,13 +540,16 @@ interface DeliverySubmitOptions {
     /**
      * 失败保留策略（v3）：port.send 首败时本条目的处置（ADR-0122 无内核自动重试不变
      * ——retain 不是重试机制，是失败条目的留存策略）。
-     * - 'forget' = 首败即停 + 显式上报后移除（runtime 文本车道现状；store 已 persist
-     *   的记录同步 discard）。
+     * - 'forget' = 首败即停 + 显式上报后移除；store 已 persist 的记录同步 discard。
      * - 'retain' = 失败条目留守：内存态转回 queued 等下一 settled 边沿 / 外部 flush
      *   重入队；store 记录保留（重启经 loadUndelivered 重入队）。
+     * - 'failed' = 受理失败转 failed 终态留守（chat-flow-consistency 第 11 条）：不自动
+     *   重投、不 discard，等用户处置（resync 重试 / cancel 撤销），与断连 failInFlight
+     *   的 failed 同态同出路。
      * 缺省按载荷类型：custom = 'retain' / text = 'forget'（§3.4 缺省值表：交互在席 vs
-     * 无人值守）。sendChecked 挂起条目恒 forget（同步失败回执契约与 retain 重投矛盾；
-     * 显式申报 retain 时按 forget 处置 + 一次性 warn）。
+     * 无人值守）。sendChecked 挂起条目缺省/显式 retain 按 forget 处置（同步失败回执
+     * 契约与 retain 重投矛盾；一次性 warn）；显式 failed 放行——waiter reject 是受理
+     * 口径通知，failed 留守是条目状态，两者不矛盾（failed 不自动重投）。
      */
     onFailure?: DeliveryFailurePolicy;
     /**
@@ -610,7 +615,7 @@ interface DeliveryHandleV2 extends DeliveryHandle {
      * 的条目生效——调 config.proofCheck(id)（对话记录中出现 details 携带本条目 id 的
      * 通知条目的判定，由装配方注入实现），true → confirmDelivered（终局化 + onSettled
      * 回调），false → 留守。非 details-id 条目（marker / acceptance 有各自判定通路）、
-     * 未注入 proofCheck、proofCheck 抛错（降级 warn 视为未送达，同 safeIsIdle 型）时
+     * 未注入 proofCheck、proofCheck 抛错（降级 warn 视为未送达，保守放行型降级）时
      * 一律返回 false 不转移。装配方在回执证据到达（message_end 等）或重放扫描时对本
      * 批候选条目调用，内核保证凭据档位分派（误确认在结构上不可达）。
      * 幂等：未知/已终态 no-op。@returns 是否发生了状态转移。
@@ -642,7 +647,21 @@ interface DeliveryHandleV2 extends DeliveryHandle {
      * 待收回（扩展②两段式）；已终态幂等返回既有 tombstone。
      */
     cancel(id: string): DeliveryCancelResult;
-    /** 全量取回文本（forceQuit，D9③）：条目清空 + 全部记 cancelled tombstone。 */
+    /**
+     * 原位替换条目内容（chat-flow-consistency D6 edit 原语）：语义 = 替换指定条目的 payload
+     * 且**条目 id 与排队位置均不变**——上层只见「替换内容，位置保持」，收回-全部-保序重投是
+     * registry 编排层组合 requeue 的内部细节，本原语不感知 pi。
+     * 接受 queued（未触达底层通道，替换后出站即新文本；持有期排队的常态）/ failed（留守行
+     * 编辑，替换后由调用方 requeue 重投）/ in-flight（registry 收回路径：clear_queue 已把
+     * 文本收回后、requeue 重投前的窗口内替换）。拒绝：终态/未知 id（false）、queued 但已在
+     * 出站批内（受理登记窗口——文本可能已进底层通道，替换会双投，调用方按悬空窗口处置）。
+     * msg.payload 同步替换引用（onSettled per-message 契约的消费方拿到替换后内容）。
+     */
+    edit(id: string, payload: DeliveryPayload): boolean;
+    /**
+     * 全量取回文本（forceQuit，D9③）：条目清空 + 全部记 cancelled tombstone（ack 写盘
+     * 失败的条目除外——文本照常返回，条目转 failed 留守，见 drain 实现的磁盘权威序注释）。
+     */
     drain(): DrainResult;
 }
 /** cancel(id) 结果（D-3 偏差：cancelled 形态携带条目快照含 payload 全文供草稿恢复）。 */
@@ -676,7 +695,7 @@ declare function createDelivery(port: DeliveryPort, config?: DeliveryConfigWithW
  *
  * 判别形态依据（设计 §3.3 D4 尾注）：本包与消费方（runtime registry）是进程内同包
  * 调用边界——编译期类型可得，instanceof 是最简判别且免词表；与跨进程 WS 边界的
- * 分类码形态（CompactErrorCode）不构成双轨。
+ * error envelope 分类码形态不构成双轨。
  */
 /**
  * 「用户主动回收」对挂起 sendChecked waiter 的 reject 错误类。
@@ -698,6 +717,28 @@ declare class DeliveryReclaimError extends Error {
     readonly entryId: string | undefined;
     constructor(kind: 'cancelled' | 'drained', entryId?: string);
 }
+/**
+ * 「终局事实已发生，但持久终局（store.ack）写入失败」的分型错误（2026-10-30 用户裁决
+ * 「磁盘为准」：内存终态必须以磁盘确认为准）。
+ *
+ * 产生点（delivery.ts ackStore）：confirmDelivered / cancel / drain 终局化时先写持久
+ * 终局，store.ack 抛错即包装为本类——内核不登记内存终态（条目留守活跃集非终态，判重
+ * 与恢复以磁盘为唯一权威），由各终局入口捕获留痕并显式上报。
+ *
+ * 语义边界：外部送达事实不可回滚（消息已实际发出）——写盘失败期间该条不视为已终态，
+ * 恢复（重启重放 / 下一回执边沿重驱动）后可能重投，at-least-once 语义被显式接受
+ * （宁可可能重投，不做内存单方终态）。
+ *
+ * 结构化字段：
+ * - entryId：终局写入失败的条目 id。
+ * - state：本应落定的终态（'delivered' | 'cancelled'）——文案按它分叉：delivered 强调
+ *   送达事实已成立；cancelled 强调本地撤销意图已发生但持久撤销凭据未落。
+ */
+declare class DeliveryAckPersistError extends Error {
+    readonly entryId: string;
+    readonly state: 'delivered' | 'cancelled';
+    constructor(entryId: string, state: 'delivered' | 'cancelled', cause?: unknown);
+}
 
 /**
  * 磁盘 outbox —— DeliveryStore 的 runtime 半区实现（统一消息投递设计 §3.5.1 / §3.8
@@ -721,6 +762,8 @@ declare class DeliveryReclaimError extends Error {
  * 设计 §3.5.1「两个实现在两半区适配层」）；目录与文件路径由装配方（runtime 侧）动态
  * 推导后以字符串传入。崩溃写入的中途半行由读取容错覆盖（JSON.parse 失败 warn 跳过）
  * ——最坏丢一行 = 最坏多投一次，与「必达优先于去重」语义一致，不需要原子替换协议。
+ * 读失败（文件存在但不可读）显式分型上抛 DiskStoreReadError，不折叠成空结果（见
+ * ensureLoaded 注释）；文件不存在 = 合法空态。
  */
 
 /** fs 窄接口（注入点；生产 = node:fs 适配，测试 = 内存替身）。 */
@@ -752,6 +795,16 @@ interface DiskDeliveryStore extends DeliveryStore {
      */
     attachSegments(id: string, segments: readonly unknown[]): void;
 }
+/**
+ * outbox 读失败错误（显式分型：读失败 ≠ 空文件）。文件存在但不可读（权限 / 瞬时 fs
+ * 故障）时由 ensureLoaded 抛出——判别形态与 DeliveryReclaimError 同理（进程内同包
+ * 调用边界，instanceof 最简判别）。
+ */
+declare class DiskStoreReadError extends Error {
+    /** outbox 文件路径（诊断定位）。 */
+    readonly file: string;
+    constructor(file: string, cause?: unknown);
+}
 declare function createDiskDeliveryStore(deps: DiskDeliveryStoreDeps): DiskDeliveryStore;
 
-export { type CustomPayload, type DeliveryCancelResult, type DeliveryConfig, type DeliveryConfigWithWarn, type DeliveryDeferReason, type DeliveryEntriesFull, type DeliveryEntriesProjection, type DeliveryEntry, type DeliveryEntryState, type DeliveryFailurePolicy, type DeliveryHandle, type DeliveryHandleV2, type DeliveryIntent, type DeliveryLane, type DeliveryMessage, type DeliveryMeta, type DeliveryPayload, type DeliveryPort, type DeliveryProofCheck, type DeliveryReceiptAnchor, DeliveryReclaimError, type DeliverySendResult, type DeliveryStore, type DeliveryStoreRecord, type DeliverySubmitOptions, type DeliveryTerminalRecord, type DeliveryWarnSink, type DiskDeliveryStore, type DiskDeliveryStoreDeps, type DiskStoreFs, type DrainResult, type SendReceipt, type TextPayload, createDelivery, createDiskDeliveryStore };
+export { type CustomPayload, DeliveryAckPersistError, type DeliveryCancelResult, type DeliveryConfig, type DeliveryConfigWithWarn, type DeliveryDeferReason, type DeliveryEntriesFull, type DeliveryEntriesProjection, type DeliveryEntry, type DeliveryEntryState, type DeliveryFailurePolicy, type DeliveryHandle, type DeliveryHandleV2, type DeliveryIntent, type DeliveryLane, type DeliveryMessage, type DeliveryMeta, type DeliveryPayload, type DeliveryPort, type DeliveryProofCheck, type DeliveryReceiptAnchor, DeliveryReclaimError, type DeliverySendResult, type DeliveryStore, type DeliveryStoreRecord, type DeliverySubmitOptions, type DeliveryTerminalRecord, type DeliveryWarnSink, type DiskDeliveryStore, type DiskDeliveryStoreDeps, type DiskStoreFs, DiskStoreReadError, type DrainResult, type SendReceipt, type TextPayload, createDelivery, createDiskDeliveryStore };

package/dist/index.mjs

@@ -9,6 +9,19 @@ var DeliveryReclaimError = class extends Error {
     this.entryId = entryId;
   }
 };
+var DeliveryAckPersistError = class extends Error {
+  entryId;
+  state;
+  constructor(entryId, state, cause) {
+    super(
+      state === "delivered" ? `delivery delivered but terminal record not persisted; recovery may redeliver (id=${entryId})` : `entry cancelled locally but terminal record not persisted; recovery may redeliver (id=${entryId})`,
+      { cause }
+    );
+    this.name = "DeliveryAckPersistError";
+    this.entryId = entryId;
+    this.state = state;
+  }
+};
 
 // src/lru.ts
 var LruSet = class {
@@ -43,8 +56,7 @@ var LruSet = class {
 
 // src/delivery.ts
 var DEFAULT_CONFIG = {
-  intent: "interrupt-at-turn-boundary",
-  mergeWindowMs: 0
+  intent: "interrupt-at-turn-boundary"
 };
 var DEFAULT_DELIVERED_WINDOW = 50;
 function isThenable(v) {
@@ -103,14 +115,6 @@ function settleChecked(batch, err, checkedPending) {
   checkedPending.push(...kept);
   return rejected;
 }
-function safeIsIdle(port, onFault) {
-  try {
-    return port.isIdle();
-  } catch (err) {
-    onFault?.(err);
-    return false;
-  }
-}
 function resolveWarnSink(config) {
   return config?.warn ?? ((msg, err) => {
     console.warn(`[session-delivery] ${msg}`, err ?? "");
@@ -126,16 +130,13 @@ function createDelivery(port, config) {
   const terminalIndex = /* @__PURE__ */ new Set();
   const terminalRecords = /* @__PURE__ */ new Map();
   let checkedRetainWarned = false;
-  let mergeIgnoredWarned = false;
   const deliveredLog = [];
   const checkedPending = [];
   let inflightBatch = [];
   let inFlight = false;
-  let mergeTimer;
   let disposed = false;
   let settledUnsub;
   let missingKeyWarned = false;
-  let probeFaultWarned = false;
   let idSeq = 0;
   const dedupSet = config?.dedupe ? new LruSet(config.dedupe.maxKeys) : null;
   const changeSubs = /* @__PURE__ */ new Set();
@@ -156,12 +157,12 @@ function createDelivery(port, config) {
       meta: e.msg.meta
     });
   }
-  function ackStore(id) {
+  function ackStore(id, state) {
     if (!store) return;
     try {
       store.ack(id);
     } catch (err) {
-      warn(`store.ack failed (terminal record not persisted; id=${id})`, err);
+      throw new DeliveryAckPersistError(id, state, err);
     }
   }
   function safeHasTerminal(id) {
@@ -207,19 +208,6 @@ function createDelivery(port, config) {
       warn(`onSettled callback threw (outcome=${outcome}); isolated from delivery state machine`, err);
     }
   }
-  function warnProbeFault(err) {
-    if (probeFaultWarned) return;
-    probeFaultWarned = true;
-    warn("port busy probe (isIdle) threw; conservatively treating as busy", err);
-  }
-  function isBusySafe() {
-    if (!safeIsIdle(port, warnProbeFault)) return true;
-    return hasInFlightEntries();
-  }
-  function hasInFlightEntries() {
-    for (const e of active) if (e.state === "in-flight") return true;
-    return false;
-  }
   function inRegistry(e) {
     return activeIndex.get(e.id) === e;
   }
@@ -228,6 +216,7 @@ function createDelivery(port, config) {
     return false;
   }
   function finalizeEntry(e, state) {
+    ackStore(e.id, state);
     const batchIdx = inflightBatch.indexOf(e);
     if (batchIdx !== -1) inflightBatch.splice(batchIdx, 1);
     const idx = active.indexOf(e);
@@ -239,7 +228,6 @@ function createDelivery(port, config) {
     e.settledAt = ts;
     terminalIndex.add(e.id);
     terminalRecords.set(e.id, { id: e.id, state, lane: e.lane, settledAt: ts });
-    ackStore(e.id);
     if (state === "delivered") {
       resolveWaitersOf(e);
       deliveredLog.push(e);
@@ -247,6 +235,25 @@ function createDelivery(port, config) {
     }
     notifyChange();
   }
+  function parkAsFailed(e) {
+    const batchIdx = inflightBatch.indexOf(e);
+    if (batchIdx !== -1) inflightBatch.splice(batchIdx, 1);
+    const ts = now();
+    e.state = "failed";
+    e.updatedAt = ts;
+    e.settledAt = ts;
+    notifyChange();
+  }
+  function cancelFinalize(e) {
+    try {
+      finalizeEntry(e, "cancelled");
+    } catch (err) {
+      if (!(err instanceof DeliveryAckPersistError)) throw err;
+      warn(`store.ack failed; cancel not terminalized, entry parked failed (id=${e.id})`, err);
+      parkAsFailed(e);
+      throw err;
+    }
+  }
   function removeActive(e) {
     const idx = active.indexOf(e);
     if (idx !== -1) active.splice(idx, 1);
@@ -268,30 +275,11 @@ function createDelivery(port, config) {
       }
     }
   }
-  function clearMergeTimer() {
-    if (mergeTimer !== void 0) {
-      clearTimeout(mergeTimer);
-      mergeTimer = void 0;
-    }
-  }
-  function armMergeTimer() {
-    if (cfg.mergeWindowMs <= 0) return;
-    mergeTimer = setTimeout(() => {
-      mergeTimer = void 0;
-      flush();
-    }, cfg.mergeWindowMs);
-  }
-  function resetMergeTimer() {
-    clearMergeTimer();
-    armMergeTimer();
-  }
   function ensureSettledSub() {
     if (settledUnsub || !port.subscribeSettled) return;
     settledUnsub = port.subscribeSettled(() => {
       if (disposed) return;
-      if (cfg.dispatchMode === "on-accept" || !isBusySafe()) {
-        flush();
-      }
+      flush();
     });
   }
   function teardownSettledSub() {
@@ -374,6 +362,7 @@ function createDelivery(port, config) {
       if (e.onFailure === "retain") continue;
       callOnSettled(e.msg, "rejected");
     }
+    const ts = now();
     for (const e of batch) {
       if (!inRegistry(e)) continue;
       if (e.onFailure === "retain") {
@@ -384,6 +373,14 @@ function createDelivery(port, config) {
         warn(`entry retained after failure (id=${e.id}); re-dispatch waits for next settled edge or external flush`);
         continue;
       }
+      if (e.onFailure === "failed") {
+        e.state = "failed";
+        e.updatedAt = ts;
+        e.settledAt = ts;
+        changed = true;
+        warn(`entry kept as failed after rejection (id=${e.id}); awaiting user retry (resync) or cancel`);
+        continue;
+      }
       store?.discard(e.id);
       removeActive(e);
       changed = true;
@@ -430,17 +427,12 @@ function createDelivery(port, config) {
   function scheduleFlush() {
     if (disposed || !hasQueuedEntries()) return;
     if (inFlight) return;
-    if (cfg.dispatchMode !== "on-accept" && isBusySafe()) return;
     doSend();
   }
   const warnSink = resolveWarnSink(config);
   function warn(msg, err) {
     warnSink(msg, err);
   }
-  if (config?.dispatchMode === "on-accept" && (config.mergeWindowMs ?? 0) > 0 && !mergeIgnoredWarned) {
-    mergeIgnoredWarned = true;
-    warn("dispatchMode=on-accept ignores mergeWindowMs (batching moves to submit side)");
-  }
   function passDedupe(msg) {
     if (!dedupSet) return true;
     if (!msg.dedupeKey) {
@@ -511,13 +503,6 @@ function createDelivery(port, config) {
     if (!persistBeforeAccept(entry)) {
       return { kind: "rejected", reason: "persist-failed" };
     }
-    const useMerge = cfg.dispatchMode !== "on-accept" && (opts?.merge ?? (cfg.mergeWindowMs > 0 && cfg.mergeHoldActive != null && cfg.mergeHoldActive()));
-    if (useMerge) {
-      resetMergeTimer();
-      ensureSettledSub();
-      return { kind: "accepted", id: entry.id };
-    }
-    clearMergeTimer();
     ensureSettledSub();
     scheduleFlush();
     return { kind: "accepted", id: entry.id };
@@ -535,7 +520,7 @@ function createDelivery(port, config) {
     if (opts?.onFailure === "retain") {
       if (!checkedRetainWarned) {
         checkedRetainWarned = true;
-        warn("sendChecked ignores onFailure=retain (checked entries are always forget)");
+        warn("sendChecked ignores onFailure=retain (checked entries default to forget)");
       }
       opts = { ...opts, onFailure: "forget" };
     }
@@ -555,7 +540,6 @@ function createDelivery(port, config) {
   }
   function flush() {
     if (disposed) return;
-    clearMergeTimer();
     scheduleFlush();
   }
   function depth() {
@@ -585,8 +569,14 @@ function createDelivery(port, config) {
     }
     const e = activeIndex.get(id);
     if (!e) return false;
-    if (e.state !== "queued" && e.state !== "in-flight") return false;
-    finalizeEntry(e, "delivered");
+    if (e.state !== "queued" && e.state !== "in-flight" && e.state !== "failed") return false;
+    try {
+      finalizeEntry(e, "delivered");
+    } catch (err) {
+      if (!(err instanceof DeliveryAckPersistError)) throw err;
+      warn(`store.ack failed; terminal not registered, entry stays non-terminal (id=${id})`, err);
+      return false;
+    }
     if (!disposed) callOnSettled(e.msg, "delivered");
     return true;
   }
@@ -673,13 +663,25 @@ function createDelivery(port, config) {
         return { kind: "reclaim-requested", entry: snapshot(e) };
       }
       rejectWaitersOf(e, new DeliveryReclaimError("cancelled", id));
-      finalizeEntry(e, "cancelled");
+      cancelFinalize(e);
       return { kind: "cancelled", entry: snapshot(e) };
     }
     rejectWaitersOf(e, new DeliveryReclaimError("cancelled", id));
-    finalizeEntry(e, "cancelled");
+    cancelFinalize(e);
     return { kind: "cancelled", entry: snapshot(e) };
   }
+  function edit(id, payload) {
+    if (disposed) return false;
+    const e = activeIndex.get(id);
+    if (!e) return false;
+    if (e.state !== "queued" && e.state !== "in-flight" && e.state !== "failed") return false;
+    if (e.state === "queued" && inflightBatch.includes(e)) return false;
+    e.payload = payload;
+    e.msg.payload = payload;
+    e.updatedAt = now();
+    notifyChange();
+    return true;
+  }
   function failInFlight(reason) {
     if (disposed) return 0;
     const ts = now();
@@ -702,19 +704,29 @@ function createDelivery(port, config) {
   }
   function drain() {
     if (disposed) return [];
-    clearMergeTimer();
     const drained = active.slice();
-    active.length = 0;
-    activeIndex.clear();
+    const ts = now();
+    const result = [];
+    for (const e of drained) {
+      try {
+        ackStore(e.id, "cancelled");
+        const idx = active.indexOf(e);
+        if (idx !== -1) active.splice(idx, 1);
+        activeIndex.delete(e.id);
+        e.state = "cancelled";
+        e.updatedAt = ts;
+        e.settledAt = ts;
+        terminalIndex.add(e.id);
+        terminalRecords.set(e.id, { id: e.id, state: "cancelled", lane: e.lane, settledAt: ts });
+      } catch (err) {
+        if (!(err instanceof DeliveryAckPersistError)) throw err;
+        warn(`store.ack failed in drain; entry not terminalized, parked failed (id=${e.id})`, err);
+        parkAsFailed(e);
+      }
+      result.push({ id: e.id, payload: e.payload });
+    }
     inflightBatch = [];
     inFlight = false;
-    const ts = now();
-    const result = drained.map((e) => {
-      terminalIndex.add(e.id);
-      terminalRecords.set(e.id, { id: e.id, state: "cancelled", lane: e.lane, settledAt: ts });
-      ackStore(e.id);
-      return { id: e.id, payload: e.payload };
-    });
     for (const w of checkedPending) {
       w.reject(new DeliveryReclaimError("drained"));
     }
@@ -724,7 +736,6 @@ function createDelivery(port, config) {
   }
   function dispose() {
     disposed = true;
-    clearMergeTimer();
     teardownSettledSub();
     active.length = 0;
     activeIndex.clear();
@@ -740,7 +751,7 @@ function createDelivery(port, config) {
     checkedPending.length = 0;
     dedupSet?.clear();
   }
-  return { send, sendChecked, flush, depth, entriesFull, projection, onChange, confirmDelivered, confirmDeliveredByProof, confirmAccepted, requeue, cancel, failInFlight, drain, dispose };
+  return { send, sendChecked, flush, depth, entriesFull, projection, onChange, confirmDelivered, confirmDeliveredByProof, confirmAccepted, requeue, cancel, edit, failInFlight, drain, dispose };
 }
 
 // src/disk-store.ts
@@ -748,6 +759,15 @@ function serializeLine(line) {
   return `${JSON.stringify(line)}
 `;
 }
+var DiskStoreReadError = class extends Error {
+  /** outbox 文件路径（诊断定位）。 */
+  file;
+  constructor(file, cause) {
+    super(`disk delivery store read failed: ${file}`, { cause });
+    this.name = "DiskStoreReadError";
+    this.file = file;
+  }
+};
 function createDiskDeliveryStore(deps) {
   const { fs, dir, file } = deps;
   const log = deps.log ?? ((message, err) => {
@@ -780,15 +800,18 @@ function createDiskDeliveryStore(deps) {
   }
   function ensureLoaded() {
     if (loaded) return;
-    loaded = true;
-    if (!fs.existsSync(file)) return;
+    if (!fs.existsSync(file)) {
+      loaded = true;
+      return;
+    }
     let raw;
     try {
       raw = fs.readFileSync(file, "utf8");
     } catch (err) {
-      log(`[disk-delivery-store] read failed (treated as empty), file=${file}`, err);
-      return;
+      log(`[disk-delivery-store] read failed (propagating; not treated as empty), file=${file}`, err);
+      throw new DiskStoreReadError(file, err);
     }
+    loaded = true;
     let lineNumber = 0;
     for (const lineText of raw.split("\n")) {
       lineNumber += 1;
@@ -856,7 +879,9 @@ function createDiskDeliveryStore(deps) {
   };
 }
 export {
+  DeliveryAckPersistError,
   DeliveryReclaimError,
+  DiskStoreReadError,
   createDelivery,
   createDiskDeliveryStore
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zhushanwen/session-delivery",
-  "version": "2.0.0",
-  "description": "Session message delivery kernel: zero-pi-dependency strategy layer for queueing, batching, dedup, and gated flush of messages into pi sessions",
+  "version": "2.2.0",
+  "description": "Session message delivery kernel: zero-pi-dependency strategy layer for idempotent, accept-time dispatch of messages into pi sessions",
   "main": "dist/index.mjs",
   "module": "dist/index.mjs",
   "types": "dist/index.d.mts",
@@ -25,6 +25,6 @@
   "scripts": {
     "build": "tsup",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run"
+    "test": "vitest run --pool=threads"
   }
 }