@zhushanwen/session-delivery 2.0.0 → 2.1.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;
@@ -196,7 +204,7 @@ interface DeliveryStoreRecord {
 /**
  * 持久化存储端口（v3，统一语言词条「持久化存储端口」）：内核与耐久面的唯一接口。
  * 两个实现在两半区适配层（本包零 fs 零 pi 知识）：runtime 半区 = 磁盘 outbox 文件
- * （文本车道，波 4 接线）；port 半区 = session entry 读写（通知车道，波 2 接线）。
+ * （文本投递路径，波 4 接线）；port 半区 = session entry 读写（通知投递路径，波 2 接线）。
  *
  * 内核行为契约（设计 §3.5.1）：
  * - persist：send 受理前调用（耐久承诺先于投递尝试，与账本 record 先于 deliver 同
@@ -235,11 +243,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 +261,7 @@ interface DeliveryConfig {
      * （受理 ≠ 送达——SendReceipt 注释口径的机制化落地）。**显式例外：sendChecked 的
      * 同步 settle 维持受理口径不变**——session_manager send 的「立即受理确认」契约
      * 锚定在受理时点，后移到送达会让 agent 工具调用阻塞至目标 session 当前 turn 结束
-     * （steer 类车道可达数十秒）。本注释即接口口径权威声明。
+     * （steer 类投递路径可达数十秒）。本注释即接口口径权威声明。
      *
      * outcome 'rejected' = 失败终局通知（ADR-0122 首败即停：send 失败一次即移除条目并
      * 逐条回调；断连事件 failInFlight 转 failed 终态同样逐条回调）。重试决策归消费方，
@@ -280,25 +283,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 +298,8 @@ interface DeliveryHandle {
     dispose(): void;
 }
 /**
- * 投递车道（D1）。lane 在条目创建时由 runtime 内核适配层判定（读权威 occupancy
- * 派生视图 + 内核自身队列态，单一判定源）后记录，此后不变。三档为投递车道语义名
+ * 投递路径（D1）。lane 在条目创建时由 runtime 内核适配层判定（读权威 occupancy
+ * 派生视图 + 内核自身队列态，单一判定源）后记录，此后不变。三档为投递路径语义名
  * （设计 §1.1 术语表），非底层通道 API 词汇。
  */
 type DeliveryLane = 'direct' | 'steer' | 'queued';
@@ -322,6 +311,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 +329,7 @@ interface DeliveryEntry {
     /** 客户端幂等 id（= 协议层 clientUuid；裸标记身份源 D2，判重锚 D5②）。 */
     id: string;
     state: DeliveryEntryState;
-    /** 投递车道（创建时判定后记录，不变，D1）。 */
+    /** 投递路径（创建时判定后记录，不变，D1）。 */
     lane: DeliveryLane;
     /** 载荷（一期仅 text，DeliveryPayload 联合保留扩展位）。 */
     payload: DeliveryPayload;
@@ -394,22 +388,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 +417,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 +456,37 @@ 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 拒收（承诺语义）。
+ *   查询的 store 异常降级 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 +502,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 +525,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 +534,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 +609,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,6 +641,17 @@ interface DeliveryHandleV2 extends DeliveryHandle {
      * 待收回（扩展②两段式）；已终态幂等返回既有 tombstone。
      */
     cancel(id: string): DeliveryCancelResult;
+    /**
+     * 原位替换条目内容（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。 */
     drain(): DrainResult;
 }

package/dist/index.mjs

@@ -43,8 +43,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 +102,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 +117,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();
@@ -207,19 +195,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;
   }
@@ -268,30 +243,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 +330,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 +341,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 +395,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 +471,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 +488,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 +508,6 @@ function createDelivery(port, config) {
   }
   function flush() {
     if (disposed) return;
-    clearMergeTimer();
     scheduleFlush();
   }
   function depth() {
@@ -585,7 +537,7 @@ function createDelivery(port, config) {
     }
     const e = activeIndex.get(id);
     if (!e) return false;
-    if (e.state !== "queued" && e.state !== "in-flight") return false;
+    if (e.state !== "queued" && e.state !== "in-flight" && e.state !== "failed") return false;
     finalizeEntry(e, "delivered");
     if (!disposed) callOnSettled(e.msg, "delivered");
     return true;
@@ -680,6 +632,18 @@ function createDelivery(port, config) {
     finalizeEntry(e, "cancelled");
     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,7 +666,6 @@ function createDelivery(port, config) {
   }
   function drain() {
     if (disposed) return [];
-    clearMergeTimer();
     const drained = active.slice();
     active.length = 0;
     activeIndex.clear();
@@ -724,7 +687,6 @@ function createDelivery(port, config) {
   }
   function dispose() {
     disposed = true;
-    clearMergeTimer();
     teardownSettledSub();
     active.length = 0;
     activeIndex.clear();
@@ -740,7 +702,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

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.1.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",