@zhushanwen/session-delivery 0.11.0 → 1.1.0

package/README.md

@@ -5,7 +5,7 @@ Session 消息投递内核：零 pi 依赖的策略层，负责排队、合批
 ## 设计原则
 
 - **零 pi 依赖**：内核不 import pi 包任何符号。steer/followUp/triggerTurn/streamingBehavior 等 pi 词汇封闭在两侧适配器内。
-- **端口注入**：`DeliveryPort` 是内核与外部世界的唯一接口（isIdle / hasPendingMessages / send / subscribeSettled），调用方负责注入运行时能力。
+- **端口注入**：`DeliveryPort` 是内核与外部世界的唯一接口（supportedPayloads / isIdle / send / subscribeSettled），调用方负责注入运行时能力。busy 判定不经 port 询问：内核内查 active 表在途条目，非空即在途、gate 不放行。
 - **意图驱动**：调用方声明投递意图（`DeliveryIntent`），内核处理与目标 session 运行状态的冲突。intent → pi 参数的翻译在适配器内。
 
 ## 接口
@@ -36,7 +36,6 @@ handle.dispose()
 | 策略 | 默认值 | 说明 |
 |------|--------|------|
 | `intent` | `'interrupt-at-turn-boundary'` | turn 边界抢占（F1 教训内化） |
-| `busyPolicy` | `'retry-force'` | settled 边沿驱动 flush + watch-dog 30s 复核；无订阅装配退化退避 {100ms, 50}≈5s 后强制发送 |
 | `mergeWindowMs` | `0` | 关；显式设值启用滑动窗口合批 |
 | `backoff` | `{ ms: 100, max: 50 }` | 退避参数 |
 | `watchdogMs` | `30_000` | watch-dog 复核间隔 |

package/dist/index.d.mts

@@ -5,13 +5,28 @@
  * - 零 pi 依赖：不出现 steer/followUp/triggerTurn/streamingBehavior 等 pi 词汇
  * - 意图驱动：调用方声明 intent，内核处理与 session 运行状态的冲突
  * - 判别联合 payload：适配器声明 supportedPayloads 能力
+ *
+ * v2 增量（投递所有权内核，设计 .tmp/tech-design/delivery-ownership-kernel.md）：
+ * 条目状态机/lane/条目双形态（活跃条目 + tombstone）/entriesFull()+projection() 双视图；行为实现在
+ * 本包 src/delivery.ts。lane 字面量中的 'steer' 是投递车道语义名（设计 §1.1 术语表
+ * /D1），非 pi API 词汇——intent → 底层参数的翻译在适配器内部，本包只记录车道，
+ * 零依赖纪律对 lane 不破例。
  */
 /** 投递意图（D3）：turn 边界抢占 / run 结束后注入，均含 idle 唤醒语义。 */
 type DeliveryIntent = 'interrupt-at-turn-boundary' | 'after-run';
-/** 文本 payload（runtime 通路一期唯一支持）。 */
+/**
+ * 文本 payload（runtime 通路一期唯一支持）。
+ * images（D9④）：可选图片附件（base64 data + mimeType，形态对齐协议层
+ * 'message.send'.images；底层通道支持图片附件的契约旁证 = 设计 F9）。内核不解析、
+ * 随出站投递透传，底层 wire 格式组装归 runtime 适配层——本包零依赖纪律不变。
+ */
 interface TextPayload {
     kind: 'text';
     content: string;
+    images?: Array<{
+        data: string;
+        mimeType: string;
+    }>;
 }
 /** custom message payload（extension 通路支持）。 */
 interface CustomPayload {
@@ -67,35 +82,29 @@ interface DeliveryPort {
     supportedPayloads: readonly DeliveryPayload['kind'][];
     /** 主 agent 是否空闲。 */
     isIdle(): boolean;
-    /** 是否有排队中的消息。 */
-    hasPendingMessages(): boolean;
     /**
      * 投递消息（intent → pi 参数的翻译在适配器内部）。
      * 返回受理回执（U2 扩展位）：显式 `{accepted:false}` = 受理失败（内核按发送失败
      * 处理）；void / `{accepted:true}` = 受理成功。旧实现返回 void 兼容。
+     *
+     * settle 契约：返回 promise 时实现必须 settle（resolve 或 reject）——悬挂的
+     * promise 会让内核 in-flight 防重永久占位、通路停摆。信任边界内不设防
+     * （ADR-0122 范围纪律）：本机操作无响应 = 底层已挂，内核不建墙钟兜底，
+     * 处置 = 用户显式失败 + 重启应用。
      */
     send(msg: DeliveryMessage, intent: DeliveryIntent): Promise<SendReceipt | void> | SendReceipt | void;
-    /** agent_settled 边沿订阅（D8）。缺省时内核退化退避轮询。返回退订函数。 */
+    /** agent_settled 边沿订阅（D8）。缺省时 busy 条目留守至外部 flush/send 触发。返回退订函数。 */
     subscribeSettled?(cb: () => void): () => void;
 }
 /** 内核配置（D4 策略默认值）。 */
 interface DeliveryConfig {
     /** 默认意图：'interrupt-at-turn-boundary'（D3）。 */
     intent?: DeliveryIntent;
-    /** busy 策略：'retry-force'（默认）/ 'park'。 */
-    busyPolicy?: 'retry-force' | 'park';
     /** 合批窗口（ms）：0 = 关；>0 = 滑动窗口合批。 */
     mergeWindowMs?: number;
     /** 合批依赖谓词（D4 must-fix #1）。true 时 send() 走合批窗口，false/缺省时立即投。
      *  禁止用 isIdle 代替。 */
     mergeHoldActive?: () => boolean;
-    /** 退避参数。 */
-    backoff?: {
-        ms: number;
-        max: number;
-    };
-    /** watch-dog 复核间隔（ms）。默认 30_000。 */
-    watchdogMs?: number;
     /** 去重配置（条数 LRU）。 */
     dedupe?: {
         maxKeys: number;
@@ -108,6 +117,20 @@ interface DeliveryConfig {
      * 队列不触发 onSettled」契约一致）；回调内再 send() 的新消息走标准 flush 管线
      * （空闲时可能在回调栈内立即投递）、不参与本批回调循环（契约完备性登记：当前
      * 消费方两种形态均零可达）。
+     *
+     * [D9⑤ 口径升级——送达口径] outcome 'delivered' 升级为**送达口径** = 已拿到送达回执
+     * （两阶段回执第二阶段：消息已写入 durable 存储；D2），而非仅 port.send 受理
+     * （受理 ≠ 送达——SendReceipt 注释口径的机制化落地）。**显式例外：sendChecked 的
+     * 同步 settle 维持受理口径不变**——session_manager send 的「立即受理确认」契约
+     * 锚定在受理时点，后移到送达会让 agent 工具调用阻塞至目标 session 当前 turn 结束
+     * （steer 类车道可达数十秒）。本注释即接口口径权威声明。
+     *
+     * outcome 'rejected' = 失败终局通知（ADR-0122 首败即停：send 失败一次即移除条目并
+     * 逐条回调；断连事件 failInFlight 转 failed 终态同样逐条回调）。重试决策归消费方，
+     * 内核不建自动重试。
+     *
+     * 异常契约：实现不应抛——回调异常由内核捕获并 warn 留痕，不影响条目状态机与
+     * 其余条目的回调（回调异常 ≠ 投递失败，不进失败重试链）。
      */
     onSettled?: (msg: DeliveryMessage, outcome: 'delivered' | 'rejected') => void;
 }
@@ -119,29 +142,157 @@ interface DeliveryHandle {
     }): void;
     /** 入队 + 可达性同步确认。reject = 入队失败。 */
     sendChecked(msg: DeliveryMessage): Promise<void>;
-    /** 强制投递尝试（shutdown / park 外部重触发 / settled 边沿内部复用）。 */
+    /** 强制投递尝试（shutdown flush / 外部重触发 / settled 边沿内部复用）。 */
     flush(): void;
     /** 队列深度（诊断/测试）。 */
     depth(): number;
     /** 销毁（清空队列 + 清 timer + 退订 settled）。 */
     dispose(): void;
 }
+/**
+ * 投递车道（D1）。lane 在条目创建时由 runtime 内核适配层判定（读权威 occupancy
+ * 投影 + 内核自身队列态，单一判定源）后记录，此后不变。三档为投递车道语义名
+ * （设计 §1.1 术语表），非底层通道 API 词汇。
+ */
+type DeliveryLane = 'direct' | 'steer' | 'queued';
+/**
+ * 条目状态机五态（D9①）。迁移规则（§3.4 错误规格表 / D3 / D10）：
+ * - queued → in-flight：出站投递被受理（两阶段回执第一阶段，D2）
+ * - in-flight → delivered：送达回执到达（message_end 标记命中 / 适配器确认，D2）
+ * - in-flight → queued：对账回收重投（滞留收回，D3；cancel 部分收回的其余条目同路径）
+ * - in-flight/queued → cancelled：用户撤销（delivery.cancel）
+ * - in-flight → failed：断连事件驱动的未确认终局（failInFlight，ADR-0122——pi 连接
+ *   断开时结果未知，显式失败交用户处置）
+ * - failed → queued：用户重试（resync 单条重报）；failed → cancelled：用户移除
+ * 帧投影四态差异：cancelled 不进 session.delivery 帧（D5③），协议侧帧 state 无此值。
+ */
+type DeliveryEntryState = 'queued' | 'in-flight' | 'delivered' | 'failed' | 'cancelled';
+/**
+ * 活跃条目（D5①）：queued/in-flight/failed 三态全量保留完整字段（failed 至用户
+ * 处置：重试/移除）。id 即客户端幂等 id（协议层 clientUuid，出站裸标记按它构造，D2），
+ * 是 resync 判重与 reattach 收养判重的锚（D5②）。
+ */
+interface DeliveryEntry {
+    /** 客户端幂等 id（= 协议层 clientUuid；裸标记身份源 D2，判重锚 D5②）。 */
+    id: string;
+    state: DeliveryEntryState;
+    /** 投递车道（创建时判定后记录，不变，D1）。 */
+    lane: DeliveryLane;
+    /** 载荷（一期仅 text，DeliveryPayload 联合保留扩展位）。 */
+    payload: DeliveryPayload;
+    /** 入队时间（epoch ms）。 */
+    createdAt: number;
+    /** 最近一次状态迁移时间（epoch ms）。 */
+    updatedAt: number;
+    /** 终态落定时间（epoch ms；delivered/failed/cancelled 时有值，tombstone 提取源）。 */
+    settledAt?: number;
+}
+/**
+ * 终态判重记录 tombstone（D5②）：delivered 与 cancelled 的轻量元数据。runtime
+ * 存活期内全量保留、**不设数量窗口**——断连前积压长队列的 resync 重报判重锚不丢；
+ * cancelled tombstone 防「cancel 确认帧断连窗口丢失 → 已撤销消息被 resync 复活」。
+ * 栖身 runtime 进程内存、不跨 runtime 重启；reattach 场景（判重表已清空）判重锚
+ * 回落 transcript 全量标记扫描（D5②/§3.4）。
+ *
+ * 语义边界（pi1-disposition-chat-flow D1②）：tombstone 语义从「送达事实」扩为
+ * 「离开系统的事实」——handled 条目（pi 接管输入等受理即终局形态）复用送达确认
+ * 原语写入本记录，终态固定为 delivered（复用既有送达终态，不新造终态形态；对账器
+ * 见 tombstone 不重投，继承断线重连 resync 判重防线）。state 联合仅两值不变。
+ */
+interface DeliveryTombstone {
+    id: string;
+    /** 仅两终态（活跃态不产 tombstone）。 */
+    state: Extract<DeliveryEntryState, 'delivered' | 'cancelled'>;
+    lane: DeliveryLane;
+    /** 终态落定时间（epoch ms）。 */
+    settledAt: number;
+}
+/**
+ * 全量视图（D9②）：对账器与判重消费。活跃条目（完整字段）+ 全部 tombstone 元数据。
+ * 消费方：Reconciler 判别在途集（runtime registry 侧）、resync 判重、reattach 收养判定。
+ * 访问入口 = handle.entriesFull()（MF-1-13 拆名：与投影视图分开命名，误用编译期可查）。
+ */
+interface DeliveryEntriesFull {
+    active: readonly DeliveryEntry[];
+    tombstones: readonly DeliveryTombstone[];
+}
+/**
+ * 投影视图（D9②/D5③）：session.delivery 帧装配用。活跃条目（queued/in-flight/failed）
+ * 全量 + delivered 最近 50 条完整条目；稳态体积有界 ≤ 50 + 活跃条目数。
+ * 装配（帧 DTO 转换）归 runtime transport 侧（u3a），内核只产出本视图。
+ * 访问入口 = handle.projection()；投影窗口恒为默认常量 50，无参数位（与全量视图
+ * entriesFull() 拆名为两个具名方法——双视图误用编译期即红，不靠注释纪律维持）。
+ */
+interface DeliveryEntriesProjection {
+    entries: readonly DeliveryEntry[];
+}
 
 /**
- * 投递内核实现：createDelivery。
- *
- * 核心行为（design.md §3.3 D4/D8）：
- * - send() 入队 → dedupe → 合批窗口判定 → 立即投或窗口到期投
- * - flush() → busy gate（isIdle + hasPendingMessages 双条件，G4）→ port.send
- * - settled 边沿 → busy 复核通过 → flush；有订阅装配下 busy 只依赖边沿 + watch-dog（不退避强发）
- * - watch-dog 低频复核（D8 兜底层①：settled 事件丢失的恢复路径）
- * - port.send 失败 → 消息留在途、按 backoff 有限重试，达上限 settle rejected（D4 错误重试）
- * - 终态上报 per-message（ext-simplify-08 D1/B1）：onSettled 对批次内每条消息各回调
- *   一次，msg 为该条原始消息（非 composed 合批消息）——additive meta（notifyId 等）
- *   随原消息引用原样透传到回调（内核不读不改）；单消息批次行为不变
- * - sendChecked() 统一经投递循环：resolve 挂钩 port.send 受理结果（busy 时经
- *   streaming 受理入 pi 队列即回，以此确认可达）；首次受理失败即 reject（入口即拦）
- * - in-flight 防重：单 handle 至多一个 port.send 在途
+ * 投递所有权内核实现：createDelivery（v2）。
+ *
+ * 在 v1 投递循环（入队 → dedupe → 合批窗口 → busy gate → port.send → settled 边沿
+ * 驱动）之上升级为条目制所有权内核（设计 .tmp/tech-design/delivery-ownership-kernel.md
+ * §3 D9①②③⑤ / D5②③ / D3，单元 u1）。零 pi 依赖不变：确认/回收由适配器（runtime
+ * registry）调 handle 方法驱动。
+ *
+ * 五态状态机（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）
+ * - failed → queued：requeue（用户重试/resync 单条重报）
+ * - [扩展①] queued → delivered：confirmDelivered 也接受 queued 态——服务 reattach
+ *   场景 rebuild 直确认重建（D3②：适配器扫描 transcript 判 delivered 后 send 重建
+ *   + confirmDelivered 一步落终态），以及出站批次在途时送达回执先于受理回执到达
+ *   的竞态形态（message_end 比 RPC resolve 快，事实优先）。
+ * - [扩展②] cancel 对 in-flight 两段式：首次调用只标记待收回（条目留守 in-flight，
+ *   返回 reclaim-requested，适配器驱动 clear_queue 收回）；适配器收回确认后再次
+ *   cancel(id) 终结为 cancelled + tombstone。收回失败不再调 → 条目留守原态
+ *   （§3.4「目标条目留守原态」）；若文本实际进了 transcript，confirmDelivered
+ *   对已标记条目事实优先转 delivered（delivered 事实 > cancel 意图）。
+ * - [扩展③] confirmAccepted 受理登记（分段 port 实现用，dmg-r1-4）：申报批内条目
+ *   已由底层通道受理——queued → in-flight + 出批 + checked waiter 受理口径 resolve。
+ *   合批分段中途失败时已登记段留守 in-flight（等回执/对账），仅未受理段走失败面。
+ *
+ * 失败语义（ADR-0122 首败即停，2026-10-05 用户裁决，backoff 自动重试链退役）：
+ * port.send 失败（含 accepted:false）一次即收口——checked 条目 reject + 从内核移除；
+ * 非 checked 条目 onSettled('rejected') 逐条显式上报 + 从内核移除。重试决策归消费方
+ * （人看页面通知、agent 收失败回执），内核只做忠实投递与事实上报。
+ *
+ * onSettled 记账口径（D9⑤ 升级）：
+ * - 'delivered' = 送达口径：仅 confirmDelivered 驱动回调（受理只转 in-flight，
+ *   不回调——受理 ≠ 送达的机制化落地）；per-message 契约（ext-simplify-08）在
+ *   confirmDelivered 路径同样成立——对每条消息各回调一次，msg 为该条原始消息
+ *   （非 composed 合批消息），additive meta（notifyId 等）随原消息引用原样
+ *   透传到回调，内核不读不改。
+ * - 'rejected' = 失败终局通知（send 首败移除 / failInFlight 断连未确认，仅通知）。
+ * - 显式例外：sendChecked 的同步 settle 维持受理口径不变——promise 在 port.send
+ *   受理成功时点 resolve（session_manager send 的 {queued:true} 契约锚，D9⑤ 锁定），
+ *   与 onSettled 送达口径正交。补充受理口径的第二 settle 路径（F1-11）：条目在
+ *   port.send promise settle 之前已终局 delivered 时（handled 终局路径——适配器在
+ *   port.send 实现内部先 confirmDelivered 再让 promise settle，finalizeEntry 同步
+ *   摘批后 onSendOk 的 settleChecked 只 settle 当前批成员），受理确认随 confirmDelivered
+ *   同步了结（resolveWaitersOf）——契约「受理成功即 resolve」对命令条目成立，
+ *   waiter 不因 settle 时序倒挂滞留。
+ *
+ * 双视图（D9②/D5③）：entriesFull() = 全量视图（活跃条目 + 全量 tombstone，对账/
+ * 判重消费）；projection() = 投影视图（活跃全量 + delivered 最近 50 条完整条目，
+ * cancelled 不投影；窗口恒为默认常量）。delivered 完整条目留存上限
+ * = 默认投影窗口 50（tombstone 全量保留不受限——判重正确性不依赖展示窗口）。
+ *
+ * 判重 tombstone（D5②）：delivered 与 cancelled 都写 tombstone，runtime 存活期内
+ * 全量保留、不设数量窗口；resync 重报/重建以显式 id 查活跃集与 tombstone 去重
+ * （send/sendChecked 的 opts.id 命中即吞）。条目 id = opts.id ?? 内部生成；未传
+ * id 的消息不参与幂等判重（v1「无 dedupe 配置不去重」语义保持）。
+ *
+ * 其余 v1 机制逐条保持：busy gate（isIdle + 内核在途内查双条件——hasPendingMessages
+ * 自镜像四件套已按 msg-pipeline-debloat D2 拆除，busy 判定内查 active 表）、合批窗口、
+ * settled 边沿驱动、dedupe LRU、dispose 语义（丢弃不触发 onSettled、checked 挂账
+ * reject）。[ADR-0122 退役登记] backoff 自动重试链、port.send settle 挂死兜底
+ * （60s）、watchdog 30s 定时复核、无订阅装配 busy 退避轮询——时间平抑/补偿类机制
+ * 全部删除，busy 等待归 settled 边沿与外部触发。depth() 口径保持 v1 = 尚未受理的
+ * 消息数（受理转 in-flight 后不计；「在途未确认」数经 entriesFull() 全量视图消费）。
  */
 
 /**
@@ -156,12 +307,170 @@ interface DeliveryWarnSink {
 }
 /** createDelivery 配置（DeliveryConfig + warn 出口注入）。 */
 type DeliveryConfigWithWarn = DeliveryConfig & DeliveryWarnSink;
+/** send/sendChecked 提交选项（v1 `{ merge? }` 的超集，向后兼容）。 */
+interface DeliverySubmitOptions {
+    /** 合批窗口判定覆盖（v1 既有）。 */
+    merge?: boolean;
+    /**
+     * 客户端幂等 id（= 条目 id = 协议层 clientUuid，D2 裸标记身份源/D5② 判重锚）。
+     * 显式提供时参与幂等判重：命中活跃条目或 tombstone 即吞（resync 重报/重放去重）。
+     * 缺省内部生成、不参与判重。
+     */
+    id?: string;
+    /** 投递车道（D1）：适配器判定后传入记录；缺省 'direct'（既有调用方语义）。 */
+    lane?: DeliveryLane;
+    /**
+     * 送达回执锚申报（msg-pipeline-debloat D1 申报制）：提交方声明本条目的送达判定锚。
+     * - 'marker'（缺省）= 出站文本尾附裸标记、送达以 message_end 回执命中为准
+     *   （用户消息主通路语义）；受理后维持 in-flight 等回执。
+     * - 'acceptance' = 无回执锚点条目（agent 通路：完成回流 / session_manager send /
+     *   notifier 通知——出站文本原样不改），port.send 受理成功即落 delivered 终态
+     *   （「受理 = 送达」是唯一可判事实，v1 记账口径 / D9⑤ 显式例外）。
+     *
+     * 缺省 'marker' 是刻意的保守取向：无标记提交点漏申报的代价 = 复发已知死锁形态
+     * （in-flight 永挂、gate 恒关，有全链诊断可查，可见）；误申报 'acceptance' 的代价
+     * = 静默丢送达确认语义（更隐蔽）。两害取可见者。新增无标记投递来源必须显式申报
+     * 'acceptance' 并登记来源清单（ADR-0074 词条）。
+     */
+    receiptAnchor?: 'marker' | 'acceptance';
+    /**
+     * 无标记条目标志（pi1-disposition-chat-flow D14⑥ 起源；技能/芯片通路并入后为
+     * 「出站不注标条目」统一标志——命令 / 手打 skill 与 prompt 模板 / `<taiji-skill>`
+     * 芯片注入文本）。true = 条目出站文本不带投递标记、终局凭据不走 message_end
+     * 标记回执（pi disposition 响应 / 断连事件驱动，适配器职责）。内核两处行为：
+     * - 组批隔离：与普通条目合批会被 buildBatchPayload 以 BATCH_SEP 拼接，pi 命令解析
+     *   与适配器全文身份匹配对拼接文本必然失效——批内含无标记条目时只取队首一条单独
+     *   成批（isolateUnmarkedEntry）。
+     * - 首败即停（ADR-0122 统一语义后不再差异化，全条目同形态）。
+     * 'acceptance' 锚条目（agent 通路）出站同样无标记但走合批、以受理即终态，不置
+     * 本标志。
+     */
+    unmarked?: boolean;
+}
+/**
+ * send() 受理结果（b31-D6：失败双表面窄口收口）。调用方忽略返回值不受影响
+ * （v1 句柄面 send 仍声明 void，结构兼容）。三分口径：
+ * - accepted：已入队并进入投递流程（id = 条目 id，供调用方对账/判重锚定）
+ * - swallowed：幂等吞（already-seen = 显式 id 命中活跃集/tombstone；duplicate-content
+ *   = dedupeKey 内容级去重命中）——设计内去重，非失败
+ * - rejected：拒收未入队（disposed = 句柄已销毁；unsupported-payload = 通路能力
+ *   不含该 payload kind）——仅 warn 单表面 + 本返回值，无终态无 onSettled
+ *
+ * void 兼容口径（与 SendReceipt 的 U2 扩展位同构）：接口返回类型含 void——
+ * v1 → v2 测试替身适配（runtime asHandleV2 直转发 v1 handle.send）返回 void =
+ * 受理未知；内核本体实现恒返回具体结果，void 分支仅为替身/旧实现预留。
+ */
+type DeliverySendResult = {
+    kind: 'accepted';
+    id: string;
+} | {
+    kind: 'swallowed';
+    reason: 'already-seen' | 'duplicate-content';
+} | {
+    kind: 'rejected';
+    reason: 'disposed' | 'unsupported-payload';
+};
+/** v2 句柄：v1 DeliveryHandle 的超集（结构兼容，既有消费者零改动）。 */
+interface DeliveryHandleV2 extends DeliveryHandle {
+    /** 唯一常规入口（D4 入口收敛）；返回受理/吞/拒收口径（void = 受理未知，替身兼容）。 */
+    send(msg: DeliveryMessage, opts?: DeliverySubmitOptions): DeliverySendResult | void;
+    sendChecked(msg: DeliveryMessage, opts?: DeliverySubmitOptions): Promise<void>;
+    /** 全量视图（D9②）：活跃条目（完整字段）+ 全部 tombstone。快照（防御性拷贝）。 */
+    entriesFull(): DeliveryEntriesFull;
+    /** 投影视图（D9②/D5③）：活跃全量 + delivered 最近 50 条完整条目，cancelled 不投影。 */
+    projection(): DeliveryEntriesProjection;
+    /**
+     * 变更订阅（state topic 装配用）：任何条目创建/迁移/终态触发。返回退订函数。
+     * 回调实现不应抛——异常由内核捕获并 warn，不影响其余订阅者与状态机。
+     */
+    onChange(cb: () => void): () => void;
+    /**
+     * 送达回执驱动转 delivered（D9③）。接受 in-flight（正规送达路径）与 queued
+     * （扩展①：rebuild 直确认 / 出站中回执先到）。幂等：未知/已终态 no-op。
+     * @returns 是否发生了状态转移（诊断/测试用）。
+     */
+    confirmDelivered(id: string): boolean;
+    /**
+     * 受理登记（[扩展③]，dmg-r1-4）：分段 port 实现申报「本条目已由底层通道受理」。
+     * 只接受当前出站批内的 queued 条目（受理事实锚定于在途投递）；生效即 queued →
+     * in-flight 转移 + 出批 + checked waiter 按受理口径 resolve（D9⑤）。幂等：非批内/
+     * 已转移/未知 id 返回 false。合批分段中途失败时已登记段留守 in-flight（等回执/对账），
+     * 仅未受理段走失败面——已进底层通道的文本不再误报「投递失败」。
+     */
+    confirmAccepted(id: string): boolean;
+    /**
+     * 断连事件驱动的显式失败终局（ADR-0122 命令终局事件化的断连腿）：把全部 in-flight
+     * 条目批量转 failed 终态（留守活跃集等用户处置：resync 重试 / cancel 移除），
+     * 逐条 onSettled('rejected') 显式上报。queued 条目不触碰（未触达底层通道，随队列
+     * 存活，重连后照常投递）。幂等：无 in-flight 条目返回 0。@returns 终态化条数。
+     */
+    failInFlight(reason: string): number;
+    /**
+     * 回收重置 queued 至队首（保持 ids 相对序，D3 own 处置/failed 重试）。
+     * 只接受 in-flight/failed；queued 幂等跳过（已在队列）；cancelled/delivered
+     * 拒绝（防复活纪律）。@returns 实际重排条数。
+     */
+    requeue(ids: readonly string[]): number;
+    /**
+     * 撤销（D9③/§3.1 场景 D）：queued/failed 本地移除 + tombstone；in-flight 标记
+     * 待收回（扩展②两段式）；已终态幂等返回既有 tombstone。
+     */
+    cancel(id: string): DeliveryCancelResult;
+    /** 全量取回文本（forceQuit，D9③）：条目清空 + 全部记 cancelled tombstone。 */
+    drain(): DrainResult;
+}
+/** cancel(id) 结果（D-3 偏差：cancelled 形态携带条目快照含 payload 全文供草稿恢复）。 */
+type DeliveryCancelResult = {
+    kind: 'cancelled';
+    entry: DeliveryEntry;
+} | {
+    kind: 'reclaim-requested';
+    entry: DeliveryEntry;
+} | {
+    kind: 'already-final';
+    tombstone: DeliveryTombstone;
+} | {
+    kind: 'not-found';
+};
+/** drain() 返回：全部未终态条目的文本取回（Segment[] 快照切分归上层，ADR-0043）。 */
+type DrainResult = ReadonlyArray<{
+    id: string;
+    payload: DeliveryPayload;
+}>;
 /**
  * 创建投递句柄。
  *
  * 约束：同 session 必须单例 handle（多 handle 并发投递竞态无保护）。
  * subscribeSettled 的退订语义由适配器负责兑现。
  */
-declare function createDelivery(port: DeliveryPort, config?: DeliveryConfigWithWarn): DeliveryHandle;
+declare function createDelivery(port: DeliveryPort, config?: DeliveryConfigWithWarn): DeliveryHandleV2;
+
+/**
+ * 内核错误类（msg-pipeline-debloat D4-1，审计候选 16）。
+ *
+ * 判别形态依据（设计 §3.3 D4 尾注）：本包与消费方（runtime registry）是进程内同包
+ * 调用边界——编译期类型可得，instanceof 是最简判别且免词表；与跨进程 WS 边界的
+ * 分类码形态（CompactErrorCode）不构成双轨。
+ */
+/**
+ * 「用户主动回收」对挂起 sendChecked waiter 的 reject 错误类。
+ *
+ * 产生点（delivery.ts）：cancel 终结条目（queued/failed 本地终结 + in-flight 收回确认）
+ * 与 drain 全量回收时的 waiter reject。语义：文本已回草稿（V9/V11），条目已被内核
+ * 终结——不是投递失败，消费方（registry dispose 错误分级）据 instanceof 判别后
+ * 只记日志、不进用户可见错误面。
+ *
+ * 结构化字段（原文案契约的语义信息转字段，文案漂移不再击穿判别）：
+ * - kind：回收方式。'cancelled' = cancel(id) 单条回收；'drained' = drain() 全量回收。
+ * - entryId：被回收条目 id（drain 全量回收无单条目指向，undefined）。
+ *
+ * message 保持历史文案形态（`delivery cancelled: <id>` / `delivery drained`）：
+ * 日志与诊断输出字节级不变，判别不再依赖它。
+ */
+declare class DeliveryReclaimError extends Error {
+    readonly kind: 'cancelled' | 'drained';
+    readonly entryId: string | undefined;
+    constructor(kind: 'cancelled' | 'drained', entryId?: string);
+}
 
-export { type CustomPayload, type DeliveryConfig, type DeliveryHandle, type DeliveryIntent, type DeliveryMessage, type DeliveryPayload, type DeliveryPort, type SendReceipt, type TextPayload, createDelivery };
+export { type CustomPayload, type DeliveryCancelResult, type DeliveryConfig, type DeliveryConfigWithWarn, type DeliveryEntriesFull, type DeliveryEntriesProjection, type DeliveryEntry, type DeliveryEntryState, type DeliveryHandle, type DeliveryHandleV2, type DeliveryIntent, type DeliveryLane, type DeliveryMessage, type DeliveryPayload, type DeliveryPort, DeliveryReclaimError, type DeliverySendResult, type DeliverySubmitOptions, type DeliveryTombstone, type DeliveryWarnSink, type DrainResult, type SendReceipt, type TextPayload, createDelivery };

package/dist/index.mjs

@@ -1,3 +1,15 @@
+// src/errors.ts
+var DeliveryReclaimError = class extends Error {
+  kind;
+  entryId;
+  constructor(kind, entryId) {
+    super(kind === "cancelled" ? `delivery cancelled: ${entryId ?? ""}` : "delivery drained");
+    this.name = "DeliveryReclaimError";
+    this.kind = kind;
+    this.entryId = entryId;
+  }
+};
+
 // src/lru.ts
 var LruSet = class {
   constructor(maxKeys) {
@@ -32,11 +44,9 @@ var LruSet = class {
 // src/delivery.ts
 var DEFAULT_CONFIG = {
   intent: "interrupt-at-turn-boundary",
-  busyPolicy: "retry-force",
-  mergeWindowMs: 0,
-  backoff: { ms: 100, max: 50 },
-  watchdogMs: 3e4
+  mergeWindowMs: 0
 };
+var DEFAULT_DELIVERED_WINDOW = 50;
 function isThenable(v) {
   return !!v && typeof v.then === "function";
 }
@@ -62,18 +72,23 @@ function buildBatchPayload(messages) {
       }
     };
   }
+  const images = messages.flatMap((m) => m.payload.kind === "text" ? m.payload.images ?? [] : []);
   return {
     ...first,
-    payload: { kind: "text", content }
+    payload: images.length > 0 ? { kind: "text", content, images } : { kind: "text", content }
   };
 }
+function isolateUnmarkedEntry(batch) {
+  const firstUnmarked = batch.find((e) => e.unmarked);
+  return firstUnmarked !== void 0 ? [firstUnmarked] : batch;
+}
 function settleChecked(batch, err, checkedPending) {
   const rejected = /* @__PURE__ */ new Set();
   if (checkedPending.length === 0) return rejected;
   const batchSet = new Set(batch);
   const kept = [];
   for (const w of checkedPending) {
-    if (!batchSet.has(w.msg)) {
+    if (!batchSet.has(w.entry)) {
       kept.push(w);
       continue;
     }
@@ -81,28 +96,21 @@ function settleChecked(batch, err, checkedPending) {
       w.resolve();
     } else {
       w.reject(err);
-      rejected.add(w.msg);
+      rejected.add(w.entry);
     }
   }
   checkedPending.length = 0;
   checkedPending.push(...kept);
   return rejected;
 }
-function safeIsIdle(port) {
+function safeIsIdle(port, onFault) {
   try {
     return port.isIdle();
-  } catch {
+  } catch (err) {
+    onFault?.(err);
     return false;
   }
 }
-function isBusy(port) {
-  if (!safeIsIdle(port)) return true;
-  try {
-    return port.hasPendingMessages();
-  } catch {
-    return true;
-  }
-}
 function resolveWarnSink(config) {
   return config?.warn ?? ((msg, err) => {
     console.warn(`[session-delivery] ${msg}`, err ?? "");
@@ -111,21 +119,116 @@ function resolveWarnSink(config) {
 function createDelivery(port, config) {
   const cfg = {
     ...DEFAULT_CONFIG,
-    ...config,
-    backoff: config?.backoff ?? DEFAULT_CONFIG.backoff
+    ...config
   };
-  const queue = [];
+  const active = [];
+  const activeIndex = /* @__PURE__ */ new Map();
+  const tombstones = /* @__PURE__ */ new Map();
+  const deliveredLog = [];
   const checkedPending = [];
   let inflightBatch = [];
   let inFlight = false;
-  let sendAttempts = 0;
   let mergeTimer;
-  let backoffTimer;
-  let watchdogTimer;
   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();
+  function now() {
+    return Date.now();
+  }
+  function genId() {
+    idSeq += 1;
+    return `d-${idSeq}`;
+  }
+  function snapshot(e) {
+    return {
+      id: e.id,
+      state: e.state,
+      lane: e.lane,
+      payload: e.payload,
+      createdAt: e.createdAt,
+      updatedAt: e.updatedAt,
+      ...e.settledAt !== void 0 ? { settledAt: e.settledAt } : {}
+    };
+  }
+  function notifyChange() {
+    for (const cb of changeSubs) {
+      try {
+        cb();
+      } catch (err) {
+        warn("onChange callback threw; isolated to keep notifying remaining subscribers", err);
+      }
+    }
+  }
+  function callOnSettled(msg, outcome) {
+    try {
+      cfg.onSettled?.(msg, outcome);
+    } catch (err) {
+      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;
+  }
+  function hasQueuedEntries() {
+    for (const e of active) if (e.state === "queued") return true;
+    return false;
+  }
+  function finalizeEntry(e, state) {
+    const batchIdx = inflightBatch.indexOf(e);
+    if (batchIdx !== -1) inflightBatch.splice(batchIdx, 1);
+    const idx = active.indexOf(e);
+    if (idx !== -1) active.splice(idx, 1);
+    activeIndex.delete(e.id);
+    e.state = state;
+    const ts = now();
+    e.updatedAt = ts;
+    e.settledAt = ts;
+    tombstones.set(e.id, { id: e.id, state, lane: e.lane, settledAt: ts });
+    if (state === "delivered") {
+      resolveWaitersOf(e);
+      deliveredLog.push(e);
+      if (deliveredLog.length > DEFAULT_DELIVERED_WINDOW) deliveredLog.shift();
+    }
+    notifyChange();
+  }
+  function removeActive(e) {
+    const idx = active.indexOf(e);
+    if (idx !== -1) active.splice(idx, 1);
+    activeIndex.delete(e.id);
+  }
+  function rejectWaitersOf(e, err) {
+    for (let i = checkedPending.length - 1; i >= 0; i--) {
+      if (checkedPending[i].entry === e) {
+        checkedPending[i].reject(err);
+        checkedPending.splice(i, 1);
+      }
+    }
+  }
+  function resolveWaitersOf(e) {
+    for (let i = checkedPending.length - 1; i >= 0; i--) {
+      if (checkedPending[i].entry === e) {
+        checkedPending[i].resolve();
+        checkedPending.splice(i, 1);
+      }
+    }
+  }
   function clearMergeTimer() {
     if (mergeTimer !== void 0) {
       clearTimeout(mergeTimer);
@@ -147,7 +250,7 @@ function createDelivery(port, config) {
     if (settledUnsub || !port.subscribeSettled) return;
     settledUnsub = port.subscribeSettled(() => {
       if (disposed) return;
-      if (!isBusy(port)) {
+      if (!isBusySafe()) {
         flush();
       }
     });
@@ -158,26 +261,17 @@ function createDelivery(port, config) {
       settledUnsub = void 0;
     }
   }
-  function startWatchdog() {
-    if (watchdogTimer !== void 0) return;
-    if (!port.subscribeSettled) return;
-    watchdogTimer = setInterval(() => {
-      if (disposed || inFlight) return;
-      if (queue.length === 0) return;
-      if (!isBusy(port)) {
-        flush();
-      }
-    }, cfg.watchdogMs);
-  }
-  function stopWatchdog() {
-    if (watchdogTimer !== void 0) {
-      clearInterval(watchdogTimer);
-      watchdogTimer = void 0;
-    }
-  }
   function attemptSend() {
+    if (inflightBatch.some((e) => !inRegistry(e))) {
+      inflightBatch = inflightBatch.filter((e) => inRegistry(e));
+    }
+    if (inflightBatch.length === 0) {
+      inFlight = false;
+      pump();
+      return;
+    }
     const batch = inflightBatch;
-    const composed = buildBatchPayload(batch);
+    const composed = buildBatchPayload(batch.map((e) => e.msg));
     const intent = composed.intent ?? cfg.intent;
     try {
       const result = port.send(composed, intent);
@@ -202,103 +296,78 @@ function createDelivery(port, config) {
   }
   function onSendOk() {
     if (disposed) return;
-    const delivered = inflightBatch;
+    const batch = inflightBatch;
     inFlight = false;
     inflightBatch = [];
-    sendAttempts = 0;
-    settleChecked(delivered, void 0, checkedPending);
-    for (const m of delivered) {
+    settleChecked(batch, void 0, checkedPending);
+    let changed = false;
+    for (const e of batch) {
+      if (disposed) break;
+      if (!inRegistry(e)) continue;
+      if (e.state !== "queued") continue;
+      e.state = "in-flight";
+      e.updatedAt = now();
+      changed = true;
+    }
+    if (changed) notifyChange();
+    for (const e of batch) {
       if (disposed) break;
-      cfg.onSettled?.(m, "delivered");
+      if (e.receiptAnchor === "acceptance") confirmDelivered(e.id);
     }
     pump();
   }
   function onSendFail(err) {
     if (disposed) return;
-    sendAttempts++;
-    const rejected = settleChecked(inflightBatch, err, checkedPending);
-    if (rejected.size > 0) {
-      inflightBatch = inflightBatch.filter((m) => !rejected.has(m));
-    }
-    if (inflightBatch.length === 0) {
-      inFlight = false;
-      inflightBatch = [];
-      sendAttempts = 0;
-      warn("port.send failed", err);
-      pump();
-      return;
+    const batch = inflightBatch;
+    inFlight = false;
+    inflightBatch = [];
+    warn("port.send failed (first-failure stop, no kernel retry)", err);
+    const rejected = settleChecked(batch, err, checkedPending);
+    let changed = false;
+    for (const e of batch) {
+      if (!inRegistry(e)) continue;
+      if (rejected.has(e)) continue;
+      callOnSettled(e.msg, "rejected");
     }
-    if (sendAttempts > cfg.backoff.max) {
-      const rejectedBatch = inflightBatch;
-      inFlight = false;
-      inflightBatch = [];
-      sendAttempts = 0;
-      warn("port.send failed after max retries", err);
-      for (const m of rejectedBatch) {
-        if (disposed) break;
-        cfg.onSettled?.(m, "rejected");
-      }
-      pump();
-      return;
+    for (const e of batch) {
+      if (!inRegistry(e)) continue;
+      removeActive(e);
+      changed = true;
     }
-    if (sendAttempts === 1) warn("port.send failed, retrying with backoff", err);
-    backoffTimer = setTimeout(() => {
-      backoffTimer = void 0;
-      if (disposed || !inFlight) return;
-      attemptSend();
-    }, cfg.backoff.ms);
+    if (changed) notifyChange();
+    pump();
   }
   function pump() {
     if (disposed || inFlight) return;
     if (checkedPending.length > 0) {
-      const msgs = [];
+      const batch = [];
       for (const w of checkedPending) {
-        const idx = queue.indexOf(w.msg);
-        if (idx !== -1) {
-          queue.splice(idx, 1);
-          msgs.push(w.msg);
-        }
+        if (inRegistry(w.entry) && w.entry.state === "queued") batch.push(w.entry);
       }
-      if (msgs.length > 0) {
-        inflightBatch = msgs;
+      if (batch.length > 0) {
+        inflightBatch = isolateUnmarkedEntry(batch);
         inFlight = true;
-        sendAttempts = 0;
         attemptSend();
         return;
       }
     }
-    if (queue.length > 0) {
-      scheduleFlush(0);
+    if (hasQueuedEntries()) {
+      scheduleFlush();
       return;
     }
-    if (checkedPending.length === 0) stopWatchdog();
   }
   function doSend() {
-    if (disposed || queue.length === 0 || inFlight) return;
+    if (disposed || inFlight) return;
+    const batch = isolateUnmarkedEntry(active.filter((e) => e.state === "queued"));
+    if (batch.length === 0) return;
     inFlight = true;
-    inflightBatch = queue.splice(0);
-    sendAttempts = 0;
+    inflightBatch = batch;
     attemptSend();
   }
-  function scheduleFlush(attempt) {
-    if (disposed || queue.length === 0) return;
+  function scheduleFlush() {
+    if (disposed || !hasQueuedEntries()) return;
     if (inFlight) return;
-    if (cfg.busyPolicy === "park" && attempt > 0) return;
-    if (backoffTimer !== void 0) {
-      clearTimeout(backoffTimer);
-      backoffTimer = void 0;
-    }
-    if (isBusy(port) && attempt < cfg.backoff.max) {
-      if (port.subscribeSettled) {
-        startWatchdog();
-        return;
-      }
-      backoffTimer = setTimeout(() => {
-        backoffTimer = void 0;
-        scheduleFlush(attempt + 1);
-      }, cfg.backoff.ms);
-      return;
-    }
+    if (isBusySafe()) return;
     doSend();
   }
   const warnSink = resolveWarnSink(config);
@@ -318,78 +387,241 @@ function createDelivery(port, config) {
     dedupSet.add(msg.dedupeKey);
     return true;
   }
+  function seenId(id) {
+    if (id === void 0) return false;
+    return activeIndex.has(id) || tombstones.has(id);
+  }
+  function createEntry(msg, opts) {
+    const ts = now();
+    const entry = {
+      id: opts?.id ?? genId(),
+      state: "queued",
+      lane: opts?.lane ?? "direct",
+      payload: msg.payload,
+      createdAt: ts,
+      updatedAt: ts,
+      msg,
+      cancelRequested: false,
+      receiptAnchor: opts?.receiptAnchor ?? "marker",
+      unmarked: opts?.unmarked ?? false
+    };
+    active.push(entry);
+    activeIndex.set(entry.id, entry);
+    notifyChange();
+    return entry;
+  }
   function send(msg, opts) {
-    if (disposed) return;
+    if (disposed) {
+      warn("send ignored: delivery handle disposed (caller should re-create the handle)");
+      return { kind: "rejected", reason: "disposed" };
+    }
     if (!port.supportedPayloads.includes(msg.payload.kind)) {
       warn(`unsupported payload kind: ${msg.payload.kind}`);
-      return;
+      return { kind: "rejected", reason: "unsupported-payload" };
     }
-    if (!passDedupe(msg)) return;
-    queue.push(msg);
+    if (seenId(opts?.id)) {
+      warn(`send swallowed by idempotency dedupe: id already seen (id=${opts?.id})`);
+      return { kind: "swallowed", reason: "already-seen" };
+    }
+    if (!passDedupe(msg)) return { kind: "swallowed", reason: "duplicate-content" };
+    const entry = createEntry(msg, opts);
     const useMerge = opts?.merge ?? (cfg.mergeWindowMs > 0 && cfg.mergeHoldActive != null && cfg.mergeHoldActive());
     if (useMerge) {
       resetMergeTimer();
       ensureSettledSub();
-      return;
+      return { kind: "accepted", id: entry.id };
     }
     clearMergeTimer();
     ensureSettledSub();
-    scheduleFlush(0);
+    scheduleFlush();
+    return { kind: "accepted", id: entry.id };
   }
-  async function sendChecked(msg) {
+  async function sendChecked(msg, opts) {
     if (disposed) throw new Error("delivery handle disposed");
     if (!port.supportedPayloads.includes(msg.payload.kind)) {
       throw new Error(`unsupported payload kind: ${msg.payload.kind}`);
     }
+    if (seenId(opts?.id)) {
+      warn(`sendChecked swallowed by idempotency dedupe: id already seen (id=${opts?.id})`);
+      return;
+    }
     if (!passDedupe(msg)) return;
-    queue.push(msg);
+    const entry = createEntry(msg, opts);
     ensureSettledSub();
     return new Promise((resolve, reject) => {
-      checkedPending.push({ msg, resolve, reject });
+      checkedPending.push({ entry, resolve, reject });
       if (!inFlight) {
-        const idx = queue.indexOf(msg);
-        if (idx !== -1) queue.splice(idx, 1);
-        inflightBatch = [msg];
+        inflightBatch = [entry];
         inFlight = true;
-        sendAttempts = 0;
         attemptSend();
       }
     });
   }
   function flush() {
     if (disposed) return;
-    if (mergeTimer !== void 0) {
-      clearTimeout(mergeTimer);
-      mergeTimer = void 0;
-    }
-    scheduleFlush(0);
+    clearMergeTimer();
+    scheduleFlush();
   }
   function depth() {
-    return queue.length + inflightBatch.length;
+    let n = 0;
+    for (const e of active) if (e.state === "queued") n++;
+    return n;
   }
-  function dispose() {
-    disposed = true;
-    if (mergeTimer !== void 0) {
-      clearTimeout(mergeTimer);
-      mergeTimer = void 0;
+  function entriesFull() {
+    return {
+      active: active.map(snapshot),
+      tombstones: [...tombstones.values()].map((t) => ({ ...t }))
+    };
+  }
+  function projection() {
+    return { entries: [...active.map(snapshot), ...deliveredLog.map(snapshot)] };
+  }
+  function onChange(cb) {
+    changeSubs.add(cb);
+    return () => {
+      changeSubs.delete(cb);
+    };
+  }
+  function confirmDelivered(id) {
+    if (disposed) {
+      warn(`confirmDelivered ignored: delivery handle disposed (id=${id})`);
+      return false;
+    }
+    const e = activeIndex.get(id);
+    if (!e) return false;
+    if (e.state !== "queued" && e.state !== "in-flight") return false;
+    finalizeEntry(e, "delivered");
+    if (!disposed) callOnSettled(e.msg, "delivered");
+    return true;
+  }
+  function confirmAccepted(id) {
+    if (disposed) return false;
+    const e = activeIndex.get(id);
+    if (!e || e.state !== "queued") return false;
+    if (!inflightBatch.includes(e)) return false;
+    inflightBatch.splice(inflightBatch.indexOf(e), 1);
+    e.state = "in-flight";
+    e.updatedAt = now();
+    settleChecked([e], void 0, checkedPending);
+    notifyChange();
+    return true;
+  }
+  function requeue(ids) {
+    if (disposed) {
+      warn("requeue ignored: delivery handle disposed");
+      return 0;
+    }
+    if (ids.length === 0) return 0;
+    const found = [];
+    const seen = /* @__PURE__ */ new Set();
+    for (const id of ids) {
+      if (seen.has(id)) continue;
+      seen.add(id);
+      const e = activeIndex.get(id);
+      if (!e) continue;
+      if (e.state !== "in-flight" && e.state !== "failed") continue;
+      if (e.cancelRequested) continue;
+      found.push(e);
+    }
+    if (found.length === 0) return 0;
+    for (const e of found) {
+      const idx = active.indexOf(e);
+      if (idx !== -1) active.splice(idx, 1);
+      e.state = "queued";
+      e.updatedAt = now();
+      e.settledAt = void 0;
+    }
+    active.unshift(...found);
+    notifyChange();
+    scheduleFlush();
+    return found.length;
+  }
+  function cancel(id) {
+    if (disposed) {
+      warn(`cancel ignored: delivery handle disposed (id=${id}, reported as not-found)`);
+      return { kind: "not-found" };
+    }
+    const e = activeIndex.get(id);
+    if (!e) {
+      const tb = tombstones.get(id);
+      if (tb) return { kind: "already-final", tombstone: { ...tb } };
+      return { kind: "not-found" };
+    }
+    if (e.state === "in-flight") {
+      if (!e.cancelRequested) {
+        e.cancelRequested = true;
+        e.updatedAt = now();
+        notifyChange();
+        return { kind: "reclaim-requested", entry: snapshot(e) };
+      }
+      rejectWaitersOf(e, new DeliveryReclaimError("cancelled", id));
+      finalizeEntry(e, "cancelled");
+      return { kind: "cancelled", entry: snapshot(e) };
+    }
+    rejectWaitersOf(e, new DeliveryReclaimError("cancelled", id));
+    finalizeEntry(e, "cancelled");
+    return { kind: "cancelled", entry: snapshot(e) };
+  }
+  function failInFlight(reason) {
+    if (disposed) return 0;
+    const ts = now();
+    let count = 0;
+    for (const e of active) {
+      if (e.state !== "in-flight") continue;
+      const batchIdx = inflightBatch.indexOf(e);
+      if (batchIdx !== -1) inflightBatch.splice(batchIdx, 1);
+      e.state = "failed";
+      e.updatedAt = ts;
+      e.settledAt = ts;
+      count++;
+      callOnSettled(e.msg, "rejected");
     }
-    if (backoffTimer !== void 0) {
-      clearTimeout(backoffTimer);
-      backoffTimer = void 0;
+    if (count > 0) {
+      warn(`failInFlight: ${count} in-flight entry(ies) marked failed (${reason})`);
+      notifyChange();
     }
-    stopWatchdog();
+    return count;
+  }
+  function drain() {
+    if (disposed) return [];
+    clearMergeTimer();
+    const drained = active.slice();
+    active.length = 0;
+    activeIndex.clear();
+    inflightBatch = [];
+    inFlight = false;
+    const ts = now();
+    const result = drained.map((e) => {
+      tombstones.set(e.id, { id: e.id, state: "cancelled", lane: e.lane, settledAt: ts });
+      return { id: e.id, payload: e.payload };
+    });
+    for (const w of checkedPending) {
+      w.reject(new DeliveryReclaimError("drained"));
+    }
+    checkedPending.length = 0;
+    if (drained.length > 0) notifyChange();
+    return result;
+  }
+  function dispose() {
+    disposed = true;
+    clearMergeTimer();
     teardownSettledSub();
-    queue.length = 0;
+    active.length = 0;
+    activeIndex.clear();
+    tombstones.clear();
+    deliveredLog.length = 0;
     inflightBatch = [];
     inFlight = false;
+    changeSubs.clear();
     for (const w of checkedPending) {
       w.reject(new Error("delivery handle disposed"));
     }
     checkedPending.length = 0;
     dedupSet?.clear();
   }
-  return { send, sendChecked, flush, depth, dispose };
+  return { send, sendChecked, flush, depth, entriesFull, projection, onChange, confirmDelivered, confirmAccepted, requeue, cancel, failInFlight, drain, dispose };
 }
 export {
+  DeliveryReclaimError,
   createDelivery
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/session-delivery",
-  "version": "0.11.0",
+  "version": "1.1.0",
   "description": "Session message delivery kernel: zero-pi-dependency strategy layer for queueing, batching, dedup, and gated flush of messages into pi sessions",
   "main": "dist/index.mjs",
   "module": "dist/index.mjs",