@zhushanwen/session-delivery 1.1.0 → 2.1.0

package/dist/index.d.mts

@@ -6,11 +6,29 @@
  * - 意图驱动：调用方声明 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 → 底层参数的翻译在适配器内部，本包只记录车道，
+ * v2 增量（投递所有权内核，v2 设计批次——设计文档未入 git，裁决随本仓 commit
+ * 历史可溯）：
+ * 条目状态机/lane/条目双形态（活跃条目 + 终局记录）/entriesFull()+projection() 双视图；行为实现在
+ * 本包 src/delivery.ts。lane 字面量中的 'steer' 是投递路径语义名（设计 §1.1 术语表
+ * /D1），非 pi API 词汇——intent → 底层参数的翻译在适配器内部，本包只记录投递路径，
  * 零依赖纪律对 lane 不破例。
+ *
+ * v3 增量（统一消息投递内核，设计 .tmp/tech-design/unified-delivery.md §3.5）：
+ * - DeliveryStore 持久化存储端口（persist / ack / discard / loadUndelivered /
+ *   loadTerminalIds / hasTerminal）：耐久承诺先于投递尝试；终局写持久终局；判重
+ *   第三级查持久记录。两个实现在两半区适配层（runtime 半区磁盘 outbox / port 半区
+ *   session entries），本包零 fs 零 pi 知识。
+ * - 送达凭据三档（DeliveryReceiptAnchor）：'marker' / 'acceptance' / 'details-id'
+ *   （ADR-0074 词条扩展）；details-id 的判定逻辑以可注入的凭据检查函数
+ *   （DeliveryProofCheck）形态承载在本内核。
+ * - 失败保留策略（DeliveryFailurePolicy）：'forget' 首败即停 / 'retain' 留账重投，
+ *   缺省按载荷类型 custom=retain / text=forget。
+ * - 判重统一：v2 的 DeliveryTombstone 独立机制与类型退役，判重 = 在途条目 → 内存
+ *   已完结 id 索引（loadTerminalIds 播种 + 终局即时登记）→ 持久记录（store.hasTerminal）。
+ *   entriesFull() 的 tombstones 视图字段与结构保持（双视图消费方零改动），元素类型
+ *   由 DeliveryTerminalRecord 承载。
+ * - 受理即出站（唯一出站形态，v2 队列持有分支已删）：受理后立即 port.send，无
+ *   忙闲门禁、无合批窗口（合批归 port 提交侧承载）。
  */
 /** 投递意图（D3）：turn 边界抢占 / run 结束后注入，均含 idle 唤醒语义。 */
 type DeliveryIntent = 'interrupt-at-turn-boundary' | 'after-run';
@@ -64,23 +82,43 @@ interface DeliveryMessage {
     meta?: DeliveryMeta;
 }
 /**
- * port.send 的受理回执（U2 回执口径扩展位）。
+ * 设计内等待原因（F1-13）：port 半区投递端的「注入门禁 hold」——这些拒绝不是失败
+ * （host.sendMessage 未调用，条目从未被注入），内核不计首败，条目留守等投递端下一
+ * 边沿重新提交。两端唯一契约点：内核消费（onSendReceipt 的 deferred 分流）与 port
+ * 产单（`{ accepted: false, deferred }`）共用本词表——新增成员属内核行为变更，不是
+ * 端口私货。
+ * - 'merge-commit-hold'：port 合批提交窗的注入门禁（窗口结束 kernel.flush 重提）。
+ * - 'compaction-wait'：port compaction 提交侧等待的第二道防线（覆盖提交同步链与
+ *   compaction 边沿交叠的残余窗口；compaction 终态边沿复位唤醒重提）。
+ */
+type DeliveryDeferReason = 'merge-commit-hold' | 'compaction-wait';
+/**
+ * port.send 显式受理回执（U2 回执口径扩展位）。
  *
  * 受理 = 底层通道接受了消息（进入投递路径），**不等于送达事实**——送达判定由
  * 调用方按自身回执锚点确认（如扩展侧扫描 custom_message entry）。旧 port 实现
  * 返回 void 不受影响（void = 受理未知，按成功处理，与既有内核语义一致）。
+ *
+ * 拒绝分支为判别联合（deferred 与 reason 互斥，MF-1-4）：
+ * - `{ accepted: false, deferred }` = 设计内等待（见 DeliveryDeferReason）——内核
+ *   不计首败，条目留守（onSendDeferred）；
+ * - `{ accepted: false, reason }` = 显式拒绝（消息未进入任何通道，走错误重试路径，
+ *   reason 进 warn 日志与 reject 链）。
  */
-interface SendReceipt {
-    /** 受理结果。false = 底层显式拒绝（消息未进入任何通道，走错误重试路径）。 */
-    accepted: boolean;
-    /** 拒绝原因（accepted:false 时携带，进 warn 日志与 reject 链）。 */
+type SendReceipt = {
+    accepted: true;
+} | {
+    accepted: false;
+    deferred: DeliveryDeferReason;
+} | {
+    accepted: false;
     reason?: string;
-}
+};
 /** 内核与外部世界的唯一接口（D2 端口注入）。 */
 interface DeliveryPort {
     /** 本通路支持的 payload kind（D9 fail-fast）。 */
     supportedPayloads: readonly DeliveryPayload['kind'][];
-    /** 主 agent 是否空闲。 */
+    /** 主 agent 是否空闲（受理即出站下内核不读——port 契约与诊断面保留）。 */
     isIdle(): boolean;
     /**
      * 投递消息（intent → pi 参数的翻译在适配器内部）。
@@ -93,18 +131,118 @@ 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'：出站文本尾附裸标记、送达以回执命中为准（文本投递路径主通路）。
+ * - 'acceptance'：受理即送达——无回执锚点条目的「受理 = 送达」是唯一可判事实，
+ *   port.send 受理成功即落 delivered 终态（v1 记账口径 / D9⑤ 显式例外）。
+ * - 'details-id'（v3 新增）：通知条目送达判定 = 对话记录中出现 details 携带本条目
+ *   id 的通知条目（deliveryId 由注入端附加，业务字段保持原样）。判定逻辑不在内核
+ *   ——内核以可注入的凭据检查函数（DeliveryProofCheck）承载函数位与调用点
+ *   （handle.confirmDeliveredByProof），对话记录读取由装配方实现（零 pi 知识）。
+ *   申报 'details-id' 的条目受理后维持 in-flight 等回执（与 'marker' 同形态），
+ *   由装配方在回执证据到达时调 confirmDeliveredByProof 驱动终局。
+ */
+type DeliveryReceiptAnchor = 'marker' | 'acceptance' | 'details-id';
+/**
+ * 失败保留策略（v3）：port.send 失败（首败，ADR-0122 无内核自动重试）时条目的处置。
+ * - 'forget'：首败即停 + 显式上报后从内核移除（缺省 text 现状；重试决策归
+ *   消费方——人看页面通知可重发）。store 已 persist 的记录同步 discard（失败条目
+ *   无判重语义，防重启后被 loadUndelivered 复活成死条目）。
+ * - 'retain'：失败条目留守——内存态转回 queued 等下一 settled 边沿 / 外部 flush
+ *   重入队（事件驱动，无定时器）；store 记录保留（不 ack 不 discard），重启后经
+ *   loadUndelivered 重入队（通知投递路径无人值守语义，与账本现状同构）。
+ * - 'failed'（chat-flow-consistency 第 11 条）：受理失败条目转 **failed 终态留守**——
+ *   不自动重投（无 retain 的边沿重投，等用户处置：resync 重试 / cancel 撤销）、
+ *   不 store.discard（重启后经 loadUndelivered 重放，重放带 transcript 判重防线），
+ *   与断连 failInFlight 的 failed 同态同出路（队列区一行 + 重试入口双呈现）。
+ *
+ * 缺省按载荷类型：custom = 'retain' / text = 'forget'（§3.4 提交选项缺省值表：
+ * 交互在席 vs 无人值守），提交方可显式覆写。sendChecked 挂起条目缺省/显式 'retain'
+ * 按 'forget' 处置（同步失败回执契约与 retain 边沿重投矛盾——调用方已收到失败，
+ * 自动重投会产生「失败但送达」的矛盾观测；一次性 warn）；显式 'failed' 放行——
+ * waiter reject 是受理口径通知，failed 留守是条目状态，两者不矛盾（failed 不自动
+ * 重投，「失败但送达」观测不存在）。
+ */
+type DeliveryFailurePolicy = 'forget' | 'retain' | 'failed';
+/**
+ * 送达凭据检查函数（v3，'details-id' 凭据的判定承载形态）：判定「对话记录中是否已
+ * 存在 details 携带该 id 的通知条目」。由装配方注入实现（实现读对话记录——pi 半区
+ * 扫 session entries；内核零 pi 零 fs 知识，只持有函数位与调用点）。同步判定：
+ * 装配方内部缓存扫描结果时恒 O(1)；未注入时 details-id 条目无法确认送达（留守）。
+ */
+type DeliveryProofCheck = (id: string) => boolean;
+/**
+ * DeliveryStore 的持久记录（persist 的写入单元 / loadUndelivered 的读取单元）：
+ * 重建投递所需的最小信息快照。字段是内核条目的持久化派生数据——重启重入队时装配方经
+ * loadUndelivered 取回后按原 id / lane / receiptAnchor 重新提交（幂等判重锚不丢）。
+ */
+interface DeliveryStoreRecord {
+    /** 客户端幂等 id（= 条目 id）。 */
+    id: string;
+    /** 投递路径（重入队时按原路径重报）。 */
+    lane: DeliveryLane;
+    /** 载荷（原样）。 */
+    payload: DeliveryPayload;
+    /** 期望注入时机（persist 时按 msg.intent ?? config.intent 解析定型）。 */
+    intent: DeliveryIntent;
+    /** 记录写入时间（epoch ms）。 */
+    recordedAt: number;
+    /** 送达凭据申报（重入队时保真重报）。 */
+    receiptAnchor?: DeliveryReceiptAnchor;
+    /** 无标记出站条目标志（重入队时保真重报，组批隔离判定源）。 */
+    unmarked?: boolean;
+    /** additive meta（原样透传债权等消费方字段，重入队时保真重报）。 */
+    meta?: DeliveryMeta;
+}
+/**
+ * 持久化存储端口（v3，统一语言词条「持久化存储端口」）：内核与耐久面的唯一接口。
+ * 两个实现在两半区适配层（本包零 fs 零 pi 知识）：runtime 半区 = 磁盘 outbox 文件
+ * （文本投递路径，波 4 接线）；port 半区 = session entry 读写（通知投递路径，波 2 接线）。
+ *
+ * 内核行为契约（设计 §3.5.1）：
+ * - persist：send 受理前调用（耐久承诺先于投递尝试，与账本 record 先于 deliver 同
+ *   律）。persist 抛错 = 承诺未落 → 内核拒收该条目（send 返回 persist-failed /
+ *   sendChecked 同步 throw），不进入投递流程。
+ * - ack：终局 delivered / cancelled 后调用（写持久终局——已撤销消息的防复活凭据
+ *   同样在持久终局记录里）。ack 抛错不回滚状态机（终局事实已发生），warn 留痕。
+ * - discard：forget 失败条目的记录无痕移除（无终局无判重语义——区别于 ack，不进
+ *   终局记录，防重启后 loadUndelivered 把已弃条目当未投递复活）。
+ * - loadUndelivered：供重启 / 重放时重入队（装配方启动时取回未终局记录重新提交）。
+ * - loadTerminalIds：启动 / 重放时构建已完结 id 内存索引（判重第二级的播种源，
+ *   对齐账本 ackedIds 播种语义）。
+ * - hasTerminal：判重第三级「查持久记录」的按 id 查询（内存索引 miss 时的持久
+ *   兜底——宁可误吞不误重投）。实现方自负缓存（如读盘一次建 Set）。
+ *
+ * 同步签名纪律：persist / ack / discard / hasTerminal 在内核热路径上，同步语义使
+ * 「承诺先于尝试」构造性成立（调用返回 = 动作已落）；loadUndelivered / loadTerminalIds
+ * 在启动 / 重放路径，装配方在装配内核前同步加载即可。异步介质由实现方内部缓冲，
+ * 不进端口签名。
+ */
+interface DeliveryStore {
+    /** 受理前写入记录（耐久承诺先于投递尝试）。抛错 = 承诺未写入，内核拒收。 */
+    persist(record: DeliveryStoreRecord): void;
+    /** 终局（delivered / cancelled）后写持久终局（从待投差集移除、进终局记录）。 */
+    ack(id: string): void;
+    /** forget 失败条目的记录无痕移除（无终局形态，区别于 ack）。 */
+    discard(id: string): void;
+    /** 未终局记录全量（重启 / 重放重入队的读取源）。 */
+    loadUndelivered(): readonly DeliveryStoreRecord[];
+    /** 已完结 id 全量（启动 / 重放时构建内存索引的播种源）。 */
+    loadTerminalIds(): readonly string[];
+    /** 持久终局按 id 查询（判重第三级）。 */
+    hasTerminal(id: string): boolean;
+}
 /** 内核配置（D4 策略默认值）。 */
 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;
@@ -123,7 +261,7 @@ interface DeliveryConfig {
      * （受理 ≠ 送达——SendReceipt 注释口径的机制化落地）。**显式例外：sendChecked 的
      * 同步 settle 维持受理口径不变**——session_manager send 的「立即受理确认」契约
      * 锚定在受理时点，后移到送达会让 agent 工具调用阻塞至目标 session 当前 turn 结束
-     * （steer 类车道可达数十秒）。本注释即接口口径权威声明。
+     * （steer 类投递路径可达数十秒）。本注释即接口口径权威声明。
      *
      * outcome 'rejected' = 失败终局通知（ADR-0122 首败即停：send 失败一次即移除条目并
      * 逐条回调；断连事件 failInFlight 转 failed 终态同样逐条回调）。重试决策归消费方，
@@ -133,13 +271,23 @@ interface DeliveryConfig {
      * 其余条目的回调（回调异常 ≠ 投递失败，不进失败重试链）。
      */
     onSettled?: (msg: DeliveryMessage, outcome: 'delivered' | 'rejected') => void;
+    /**
+     * 持久化存储端口（v3）。缺省 undefined = 无耐久面（v2 行为：纯内存条目集）——
+     * 既有 runtime 装配不传 = 逐字节不变（波 1 零行为变化锚）。提供时内核行为契约见
+     * DeliveryStore（受理前 persist / 终局 ack / forget 失败 discard / 构造期
+     * loadTerminalIds 播种判重索引）。
+     */
+    store?: DeliveryStore;
+    /**
+     * 送达凭据检查函数（v3）：'details-id' 凭据条目的送达判定承载（见 DeliveryProofCheck）。
+     * 缺省 undefined = details-id 条目无法经 confirmDeliveredByProof 确认（留守 in-flight）。
+     */
+    proofCheck?: DeliveryProofCheck;
 }
 /** 投递句柄（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 边沿内部复用）。 */
@@ -150,8 +298,8 @@ interface DeliveryHandle {
     dispose(): void;
 }
 /**
- * 投递车道（D1）。lane 在条目创建时由 runtime 内核适配层判定（读权威 occupancy
- * 投影 + 内核自身队列态，单一判定源）后记录，此后不变。三档为投递车道语义名
+ * 投递路径（D1）。lane 在条目创建时由 runtime 内核适配层判定（读权威 occupancy
+ * 派生视图 + 内核自身队列态，单一判定源）后记录，此后不变。三档为投递路径语义名
  * （设计 §1.1 术语表），非底层通道 API 词汇。
  */
 type DeliveryLane = 'direct' | 'steer' | 'queued';
@@ -163,8 +311,13 @@ 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 无此值。
+ * 帧派生视图四态差异：cancelled 不进 session.delivery 帧（D5③），协议侧帧 state 无此值。
  */
 type DeliveryEntryState = 'queued' | 'in-flight' | 'delivered' | 'failed' | 'cancelled';
 /**
@@ -176,7 +329,7 @@ interface DeliveryEntry {
     /** 客户端幂等 id（= 协议层 clientUuid；裸标记身份源 D2，判重锚 D5②）。 */
     id: string;
     state: DeliveryEntryState;
-    /** 投递车道（创建时判定后记录，不变，D1）。 */
+    /** 投递路径（创建时判定后记录，不变，D1）。 */
     lane: DeliveryLane;
     /** 载荷（一期仅 text，DeliveryPayload 联合保留扩展位）。 */
     payload: DeliveryPayload;
@@ -188,39 +341,44 @@ interface DeliveryEntry {
     settledAt?: number;
 }
 /**
- * 终态判重记录 tombstone（D5②）：delivered 与 cancelled 的轻量元数据。runtime
- * 存活期内全量保留、**不设数量窗口**——断连前积压长队列的 resync 重报判重锚不丢；
- * cancelled tombstone 防「cancel 确认帧断连窗口丢失 → 已撤销消息被 resync 复活」。
- * 栖身 runtime 进程内存、不跨 runtime 重启；reattach 场景（判重表已清空）判重锚
- * 回落 transcript 全量标记扫描（D5②/§3.4）。
+ * 终局记录（v3）：delivered 与 cancelled 的轻量元数据——条目离开系统的事实的内存
+ * 派生数据。v2 的 DeliveryTombstone 独立判重机制与类型随 v3 退役（它像独立机制只因没有
+ * 持久存储）：判重统一为「在途条目 → 内存已完结 id 索引（store.loadTerminalIds 播种
+ * + 终局即时登记）→ 持久记录（store.hasTerminal）」三级（设计 §3.5.5），终态唯一
+ * 事实源 = 投递日志（DeliveryStore 终局记录）；本类型只承载条目视图面——
+ * entriesFull().tombstones 视图字段与结构保持不变（双视图消费方零改动，波 1 零行为
+ * 变化锚），cancel 的 already-final 结果同样由它承载。
  *
- * 语义边界（pi1-disposition-chat-flow D1②）：tombstone 语义从「送达事实」扩为
- * 「离开系统的事实」——handled 条目（pi 接管输入等受理即终局形态）复用送达确认
- * 原语写入本记录，终态固定为 delivered（复用既有送达终态，不新造终态形态；对账器
- * 见 tombstone 不重投，继承断线重连 resync 判重防线）。state 联合仅两值不变。
+ * 语义边界（pi1-disposition-chat-flow D1②）：终局语义 = 「离开系统的事实」——
+ * handled 条目（pi 接管输入等受理即终局形态）复用送达确认原语写入，终态固定为
+ * delivered。state 联合仅两值不变。
  */
-interface DeliveryTombstone {
+interface DeliveryTerminalRecord {
     id: string;
-    /** 仅两终态（活跃态不产 tombstone）。 */
+    /** 仅两终态（活跃态不产终局记录）。 */
     state: Extract<DeliveryEntryState, 'delivered' | 'cancelled'>;
     lane: DeliveryLane;
     /** 终态落定时间（epoch ms）。 */
     settledAt: number;
 }
 /**
- * 全量视图（D9②）：对账器与判重消费。活跃条目（完整字段）+ 全部 tombstone 元数据。
+ * 全量视图（D9②）：对账器与判重消费。活跃条目（完整字段）+ 全部终局记录。
  * 消费方：Reconciler 判别在途集（runtime registry 侧）、resync 判重、reattach 收养判定。
- * 访问入口 = handle.entriesFull()（MF-1-13 拆名：与投影视图分开命名，误用编译期可查）。
+ * 访问入口 = handle.entriesFull()（MF-1-13 拆名：与派生视图分开命名，误用编译期可查）。
+ *
+ * tombstones 字段口径（v3）：本 handle 生命周期内终局条目的完整记录（含 restart 前
+ * 条目的判重不依赖它——重启前的已完结 id 由 store.loadTerminalIds 播种进判重索引，
+ * 判重正确性不依赖本视图的全量性）。字段名与结构保持 v2 形态（双视图消费方零改动）。
  */
 interface DeliveryEntriesFull {
     active: readonly DeliveryEntry[];
-    tombstones: readonly DeliveryTombstone[];
+    tombstones: readonly DeliveryTerminalRecord[];
 }
 /**
- * 投影视图（D9②/D5③）：session.delivery 帧装配用。活跃条目（queued/in-flight/failed）
+ * 派生视图（D9②/D5③）：session.delivery 帧装配用。活跃条目（queued/in-flight/failed）
  * 全量 + delivered 最近 50 条完整条目；稳态体积有界 ≤ 50 + 活跃条目数。
  * 装配（帧 DTO 转换）归 runtime transport 侧（u3a），内核只产出本视图。
- * 访问入口 = handle.projection()；投影窗口恒为默认常量 50，无参数位（与全量视图
+ * 访问入口 = handle.projection()；派生视图窗口恒为默认常量 50，无参数位（与全量视图
  * entriesFull() 拆名为两个具名方法——双视图误用编译期即红，不靠注释纪律维持）。
  */
 interface DeliveryEntriesProjection {
@@ -230,22 +388,25 @@ interface DeliveryEntriesProjection {
 /**
  * 投递所有权内核实现：createDelivery（v2）。
  *
- * 在 v1 投递循环（入队 → dedupe → 合批窗口 → busy gate → port.send → settled 边沿
- * 驱动）之上升级为条目制所有权内核（设计 .tmp/tech-design/delivery-ownership-kernel.md
- * §3 D9①②③⑤ / D5②③ / D3，单元 u1）。零 pi 依赖不变：确认/回收由适配器（runtime
+ * 在 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。收回失败不再调 → 条目留守原态
@@ -253,12 +414,17 @@ interface DeliveryEntriesProjection {
  *   对已标记条目事实优先转 delivered（delivered 事实 > cancel 意图）。
  * - [扩展③] confirmAccepted 受理登记（分段 port 实现用，dmg-r1-4）：申报批内条目
  *   已由底层通道受理——queued → in-flight + 出批 + checked waiter 受理口径 resolve。
- *   合批分段中途失败时已登记段留守 in-flight（等回执/对账），仅未受理段走失败面。
+ *   合批分段中途失败时已登记段留守 in-flight（等回执/对账），仅未受理段按失败处理。
  *
  * 失败语义（ADR-0122 首败即停，2026-10-05 用户裁决，backoff 自动重试链退役）：
- * port.send 失败（含 accepted:false）一次即收口——checked 条目 reject + 从内核移除；
- * 非 checked 条目 onSettled('rejected') 逐条显式上报 + 从内核移除。重试决策归消费方
- * （人看页面通知、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，
@@ -276,22 +442,51 @@ interface DeliveryEntriesProjection {
  *   同步了结（resolveWaitersOf）——契约「受理成功即 resolve」对命令条目成立，
  *   waiter 不因 settle 时序倒挂滞留。
  *
- * 双视图（D9②/D5③）：entriesFull() = 全量视图（活跃条目 + 全量 tombstone，对账/
- * 判重消费）；projection() = 投影视图（活跃全量 + delivered 最近 50 条完整条目，
- * cancelled 不投影；窗口恒为默认常量）。delivered 完整条目留存上限
- * = 默认投影窗口 50（tombstone 全量保留不受限——判重正确性不依赖展示窗口）。
+ * 双视图（D9②/D5③）：entriesFull() = 全量视图（活跃条目 + 全量终局记录，对账/
+ * 判重消费）；projection() = 派生视图（活跃全量 + delivered 最近 50 条完整条目，
+ * cancelled 不进派生视图；窗口恒为默认常量）。delivered 完整条目留存上限
+ * = 默认派生视图窗口 50（终局记录全量保留不受限——判重正确性不依赖展示窗口）。
+ *
+ * 判重（v3 统一：在途条目 → 内存已完结 id 索引 → 持久记录，设计 unified-delivery
+ * §3.5.5）：resync 重报/重建以显式 id 查三级判重链去重（send/sendChecked 的 opts.id
+ * 命中即吞）。一级 = 活跃集（activeIndex，含 queued/in-flight/failed）；二级 = 内存
+ * 已完结 id 索引（terminalIndex：store.loadTerminalIds 启动播种 + 终局即时登记）；
+ * 三级 = 持久记录（store.hasTerminal，索引 miss 的持久兜底）。v2 的 tombstone 独立
+ * 判重机制与 DeliveryTombstone 类型退役；已撤销消息的防复活凭据 = 撤销时写持久
+ * 终局（store.ack）。条目 id = opts.id ?? 内部生成；未传 id 的消息不参与幂等判重
+ * （v1「无 dedupe 配置不去重」语义保持）。
  *
- * 判重 tombstone（D5②）：delivered 与 cancelled 都写 tombstone，runtime 存活期内
- * 全量保留、不设数量窗口；resync 重报/重建以显式 id 查活跃集与 tombstone 去重
- * （send/sendChecked 的 opts.id 命中即吞）。条目 id = opts.id ?? 内部生成；未传
- * id 的消息不参与幂等判重（v1「无 dedupe 配置不去重」语义保持）。
+ * 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 留痕、状态机照常（终局事实已发生 / 探测异常降级
+ *   保守放行）；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' | 'failed'，缺省 custom=retain /
+ *   text=forget）：retain 条目首败后内存态转回 queued 留守（下一 settled 边沿 /
+ *   外部 flush 重入队，事件驱动无定时器；失败轮不主动重投——防 idle 同步失败循环），
+ *   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 机制逐条保持：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() 全量视图消费）。
  */
 
@@ -307,32 +502,50 @@ 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 申报制）：提交方声明本条目的送达判定锚。
+     * 送达回执锚申报（msg-pipeline-debloat D1 申报制；v3 三档，ADR-0074 词条扩展）：
+     * 提交方声明本条目的送达判定锚。
      * - 'marker'（缺省）= 出站文本尾附裸标记、送达以 message_end 回执命中为准
      *   （用户消息主通路语义）；受理后维持 in-flight 等回执。
      * - 'acceptance' = 无回执锚点条目（agent 通路：完成回流 / session_manager send /
      *   notifier 通知——出站文本原样不改），port.send 受理成功即落 delivered 终态
      *   （「受理 = 送达」是唯一可判事实，v1 记账口径 / D9⑤ 显式例外）。
+     * - 'details-id'（v3）= 通知条目凭据（deliveryId 由注入端写入 details，业务字段
+     *   保持原样）：送达判定 = 对话记录中出现 details 携带本条目 id 的通知条目；受理
+     *   后维持 in-flight 等回执（同 'marker'），终局由装配方调 handle.confirmDeliveredByProof
+     *   驱动（判定逻辑经 config.proofCheck 注入，内核零 pi 知识）。
      *
-     * 缺省 'marker' 是刻意的保守取向：无标记提交点漏申报的代价 = 复发已知死锁形态
-     * （in-flight 永挂、gate 恒关，有全链诊断可查，可见）；误申报 'acceptance' 的代价
+   * 缺省 'marker' 是刻意的保守取向：无标记提交点漏申报的代价 = 复发已知死锁形态
+   * （in-flight 永挂——条目无人确认终态，有全链诊断可查，可见）；误申报 'acceptance' 的代价
      * = 静默丢送达确认语义（更隐蔽）。两害取可见者。新增无标记投递来源必须显式申报
-     * 'acceptance' 并登记来源清单（ADR-0074 词条）。
+     * 'acceptance' 或 'details-id' 并登记来源清单（ADR-0074 词条）。
+     */
+    receiptAnchor?: DeliveryReceiptAnchor;
+    /**
+     * 失败保留策略（v3）：port.send 首败时本条目的处置（ADR-0122 无内核自动重试不变
+     * ——retain 不是重试机制，是失败条目的留存策略）。
+     * - '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 挂起条目缺省/显式 retain 按 forget 处置（同步失败回执
+     * 契约与 retain 重投矛盾；一次性 warn）；显式 failed 放行——waiter reject 是受理
+     * 口径通知，failed 留守是条目状态，两者不矛盾（failed 不自动重投）。
      */
-    receiptAnchor?: 'marker' | 'acceptance';
+    onFailure?: DeliveryFailurePolicy;
     /**
      * 无标记条目标志（pi1-disposition-chat-flow D14⑥ 起源；技能/芯片通路并入后为
      * 「出站不注标条目」统一标志——命令 / 手打 skill 与 prompt 模板 / `<taiji-skill>`
@@ -348,13 +561,14 @@ interface DeliverySubmitOptions {
     unmarked?: boolean;
 }
 /**
- * send() 受理结果（b31-D6：失败双表面窄口收口）。调用方忽略返回值不受影响
+ * 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
+ *   不含该 payload kind；persist-failed = store 受理前写入记录失败——耐久承诺未写入，
+ *   v3 仅 config.store 装配时可达）——仅 warn 单表面 + 本返回值，无终态无 onSettled
  *
  * void 兼容口径（与 SendReceipt 的 U2 扩展位同构）：接口返回类型含 void——
  * v1 → v2 测试替身适配（runtime asHandleV2 直转发 v1 handle.send）返回 void =
@@ -368,7 +582,7 @@ type DeliverySendResult = {
     reason: 'already-seen' | 'duplicate-content';
 } | {
     kind: 'rejected';
-    reason: 'disposed' | 'unsupported-payload';
+    reason: 'disposed' | 'unsupported-payload' | 'persist-failed';
 };
 /** v2 句柄：v1 DeliveryHandle 的超集（结构兼容，既有消费者零改动）。 */
 interface DeliveryHandleV2 extends DeliveryHandle {
@@ -377,7 +591,7 @@ interface DeliveryHandleV2 extends DeliveryHandle {
     sendChecked(msg: DeliveryMessage, opts?: DeliverySubmitOptions): Promise<void>;
     /** 全量视图（D9②）：活跃条目（完整字段）+ 全部 tombstone。快照（防御性拷贝）。 */
     entriesFull(): DeliveryEntriesFull;
-    /** 投影视图（D9②/D5③）：活跃全量 + delivered 最近 50 条完整条目，cancelled 不投影。 */
+    /** 派生视图（D9②/D5③）：活跃全量 + delivered 最近 50 条完整条目，cancelled 不进派生视图。 */
     projection(): DeliveryEntriesProjection;
     /**
      * 变更订阅（state topic 装配用）：任何条目创建/迁移/终态触发。返回退订函数。
@@ -390,16 +604,27 @@ interface DeliveryHandleV2 extends DeliveryHandle {
      * @returns 是否发生了状态转移（诊断/测试用）。
      */
     confirmDelivered(id: string): boolean;
+    /**
+     * 凭据检查驱动的送达确认（v3，'details-id' 凭据调用点）：仅对申报 'details-id'
+     * 的条目生效——调 config.proofCheck(id)（对话记录中出现 details 携带本条目 id 的
+     * 通知条目的判定，由装配方注入实现），true → confirmDelivered（终局化 + onSettled
+     * 回调），false → 留守。非 details-id 条目（marker / acceptance 有各自判定通路）、
+     * 未注入 proofCheck、proofCheck 抛错（降级 warn 视为未送达，保守放行型降级）时
+     * 一律返回 false 不转移。装配方在回执证据到达（message_end 等）或重放扫描时对本
+     * 批候选条目调用，内核保证凭据档位分派（误确认在结构上不可达）。
+     * 幂等：未知/已终态 no-op。@returns 是否发生了状态转移。
+     */
+    confirmDeliveredByProof(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
+     * 断连事件驱动的显式失败终局（ADR-0122 命令终局事件化的断连路径）：把全部 in-flight
      * 条目批量转 failed 终态（留守活跃集等用户处置：resync 重试 / cancel 移除），
      * 逐条 onSettled('rejected') 显式上报。queued 条目不触碰（未触达底层通道，随队列
      * 存活，重连后照常投递）。幂等：无 in-flight 条目返回 0。@returns 终态化条数。
@@ -416,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;
 }
@@ -428,7 +664,7 @@ type DeliveryCancelResult = {
     entry: DeliveryEntry;
 } | {
     kind: 'already-final';
-    tombstone: DeliveryTombstone;
+    tombstone: DeliveryTerminalRecord;
 } | {
     kind: 'not-found';
 };
@@ -458,7 +694,7 @@ declare function createDelivery(port: DeliveryPort, config?: DeliveryConfigWithW
  * 产生点（delivery.ts）：cancel 终结条目（queued/failed 本地终结 + in-flight 收回确认）
  * 与 drain 全量回收时的 waiter reject。语义：文本已回草稿（V9/V11），条目已被内核
  * 终结——不是投递失败，消费方（registry dispose 错误分级）据 instanceof 判别后
- * 只记日志、不进用户可见错误面。
+ * 只记日志、不进用户可见错误范围。
  *
  * 结构化字段（原文案契约的语义信息转字段，文案漂移不再击穿判别）：
  * - kind：回收方式。'cancelled' = cancel(id) 单条回收；'drained' = drain() 全量回收。
@@ -473,4 +709,59 @@ declare class DeliveryReclaimError extends Error {
     constructor(kind: 'cancelled' | 'drained', entryId?: string);
 }
 
-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 };
+/**
+ * 磁盘 outbox —— DeliveryStore 的 runtime 半区实现（统一消息投递设计 §3.5.1 / §3.8
+ * 文本行，波 4；关闭 ADR-0074「outbox 不落盘」代价）。
+ *
+ * 形态：JSONL 追加文件，每行一个 JSON 对象（`t` 字段判别行型），单调累积——
+ * - `{"t":"record","r":<DeliveryStoreRecord>}`：受理前写入记录（耐久承诺先于投递尝试）；
+ * - `{"t":"ack","id":...}`：终局（delivered / cancelled 同形，判重只看 id）——终局行
+ *   保留是判重依据（已撤销消息的防复活凭据同样在此），**单调累积、不实现清理通道**；
+ * - `{"t":"discard","id":...}`：forget 失败条目的记录移除（无终局无判重语义，区别于
+ *   ack——loadUndelivered 跳过、hasTerminal 为假，防重启后被当未投递复活）；
+ * - `{"t":"meta","id":...,"segments":...}`：segments 快照补记（runtime 侧撤销编排的
+ *   回填通道——重启重放后撤销仍返回原始 segments）。
+ *
+ * 读取 = 全量行序重放（后行覆盖前行）：record 建记录 / ack 进终局集 / discard 进弃置
+ * 集 / meta 并入记录 meta。同 id 先 discard 后 record = 记录复活（新承诺覆盖弃置）；
+ * 同 id 先 ack 后 record = 判重保持（终局集不撤销——宁可误吞不误重投，与内核
+ * store.hasTerminal 注释口径一致）。
+ *
+ * 本文件零 node:fs 依赖：全部 fs 操作经 DiskStoreFs 窄接口注入（内核包零 fs 知识纪律，
+ * 设计 §3.5.1「两个实现在两半区适配层」）；目录与文件路径由装配方（runtime 侧）动态
+ * 推导后以字符串传入。崩溃写入的中途半行由读取容错覆盖（JSON.parse 失败 warn 跳过）
+ * ——最坏丢一行 = 最坏多投一次，与「必达优先于去重」语义一致，不需要原子替换协议。
+ */
+
+/** fs 窄接口（注入点；生产 = node:fs 适配，测试 = 内存替身）。 */
+interface DiskStoreFs {
+    existsSync(path: string): boolean;
+    mkdirSync(path: string, opts: {
+        recursive: true;
+    }): unknown;
+    readFileSync(path: string, encoding: 'utf8'): string;
+    appendFileSync(path: string, data: string): void;
+}
+interface DiskDeliveryStoreDeps {
+    /** fs 操作面（注入；内核零 node:fs import）。 */
+    fs: DiskStoreFs;
+    /** outbox 目录（绝对路径，装配方动态推导；首次写入前惰性创建）。 */
+    dir: string;
+    /** outbox 文件（`<dir>/<sessionId 编码>.jsonl`，装配方拼装）。 */
+    file: string;
+    /** 读取容错与写失败的留痕出口；缺省 console.warn。 */
+    log?: (message: string, err?: unknown) => void;
+}
+/** 磁盘 outbox store：DeliveryStore 契约 + segments 补记扩展（registry 撤销回填通道）。 */
+interface DiskDeliveryStore extends DeliveryStore {
+    /**
+     * segments 快照补记（实现侧扩展，**非 DeliveryStore 端口成员**——内核不感知）：
+     * 把提交侧 attachSegments 登记的原始快照追加为 meta 行，随记录跨重启存活；
+     * 重放侧经 loadUndelivered 的 record.meta.segments 取回。同 id 多次补记按行序
+     * 后写覆盖先写。
+     */
+    attachSegments(id: string, segments: readonly unknown[]): void;
+}
+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 };

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 ?? "");
@@ -123,19 +114,53 @@ function createDelivery(port, config) {
   };
   const active = [];
   const activeIndex = /* @__PURE__ */ new Map();
-  const tombstones = /* @__PURE__ */ new Map();
+  const terminalIndex = /* @__PURE__ */ new Set();
+  const terminalRecords = /* @__PURE__ */ new Map();
+  let checkedRetainWarned = 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();
+  const store = config?.store;
+  if (store) {
+    for (const id of store.loadTerminalIds()) terminalIndex.add(id);
+  }
+  function persistRecord(e) {
+    if (!store) return;
+    store.persist({
+      id: e.id,
+      lane: e.lane,
+      payload: e.payload,
+      intent: e.msg.intent ?? cfg.intent,
+      recordedAt: e.createdAt,
+      receiptAnchor: e.receiptAnchor,
+      unmarked: e.unmarked,
+      meta: e.msg.meta
+    });
+  }
+  function ackStore(id) {
+    if (!store) return;
+    try {
+      store.ack(id);
+    } catch (err) {
+      warn(`store.ack failed (terminal record not persisted; id=${id})`, err);
+    }
+  }
+  function safeHasTerminal(id) {
+    if (!store) return false;
+    try {
+      return store.hasTerminal(id);
+    } catch (err) {
+      warn(`store.hasTerminal threw; treating as not-terminal (id=${id})`, err);
+      return false;
+    }
+  }
   function now() {
     return Date.now();
   }
@@ -170,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;
   }
@@ -200,7 +212,9 @@ function createDelivery(port, config) {
     const ts = now();
     e.updatedAt = ts;
     e.settledAt = ts;
-    tombstones.set(e.id, { id: e.id, state, lane: e.lane, 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);
@@ -229,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 (!isBusySafe()) {
-        flush();
-      }
+      flush();
     });
   }
   function teardownSettledSub() {
@@ -289,6 +284,10 @@ function createDelivery(port, config) {
   }
   function onSendReceipt(receipt) {
     if (receipt !== void 0 && receipt.accepted === false) {
+      if ("deferred" in receipt) {
+        onSendDeferred(receipt.deferred);
+        return;
+      }
       onSendFail(new Error(receipt.reason ?? "port.send rejected (accepted:false)"));
       return;
     }
@@ -324,18 +323,47 @@ function createDelivery(port, config) {
     warn("port.send failed (first-failure stop, no kernel retry)", err);
     const rejected = settleChecked(batch, err, checkedPending);
     let changed = false;
+    let retained = false;
     for (const e of batch) {
       if (!inRegistry(e)) continue;
       if (rejected.has(e)) continue;
+      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") {
+        e.state = "queued";
+        e.updatedAt = now();
+        changed = true;
+        retained = true;
+        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;
     }
     if (changed) notifyChange();
-    pump();
+    if (!retained) pump();
+  }
+  function onSendDeferred(reason) {
+    if (disposed) return;
+    const batch = inflightBatch;
+    inFlight = false;
+    inflightBatch = [];
+    warn(
+      `port.send deferred (designed-in wait, reason=${reason}); ${batch.length} entry(ies) stay queued for next dispatch edge`
+    );
   }
   function pump() {
     if (disposed || inFlight) return;
@@ -367,7 +395,6 @@ function createDelivery(port, config) {
   function scheduleFlush() {
     if (disposed || !hasQueuedEntries()) return;
     if (inFlight) return;
-    if (isBusySafe()) return;
     doSend();
   }
   const warnSink = resolveWarnSink(config);
@@ -389,7 +416,22 @@ function createDelivery(port, config) {
   }
   function seenId(id) {
     if (id === void 0) return false;
-    return activeIndex.has(id) || tombstones.has(id);
+    if (activeIndex.has(id)) return true;
+    if (terminalIndex.has(id)) return true;
+    return safeHasTerminal(id);
+  }
+  function resolveOnFailure(msg, opts) {
+    return opts?.onFailure ?? (msg.payload.kind === "custom" ? "retain" : "forget");
+  }
+  function persistBeforeAccept(e) {
+    try {
+      persistRecord(e);
+      return true;
+    } catch (err) {
+      warn(`store.persist failed before accept; entry rejected (id=${e.id})`, err);
+      removeActive(e);
+      return false;
+    }
   }
   function createEntry(msg, opts) {
     const ts = now();
@@ -403,7 +445,8 @@ function createDelivery(port, config) {
       msg,
       cancelRequested: false,
       receiptAnchor: opts?.receiptAnchor ?? "marker",
-      unmarked: opts?.unmarked ?? false
+      unmarked: opts?.unmarked ?? false,
+      onFailure: resolveOnFailure(msg, opts)
     };
     active.push(entry);
     activeIndex.set(entry.id, entry);
@@ -425,13 +468,9 @@ function createDelivery(port, config) {
     }
     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 { kind: "accepted", id: entry.id };
+    if (!persistBeforeAccept(entry)) {
+      return { kind: "rejected", reason: "persist-failed" };
     }
-    clearMergeTimer();
     ensureSettledSub();
     scheduleFlush();
     return { kind: "accepted", id: entry.id };
@@ -446,7 +485,17 @@ function createDelivery(port, config) {
       return;
     }
     if (!passDedupe(msg)) return;
+    if (opts?.onFailure === "retain") {
+      if (!checkedRetainWarned) {
+        checkedRetainWarned = true;
+        warn("sendChecked ignores onFailure=retain (checked entries default to forget)");
+      }
+      opts = { ...opts, onFailure: "forget" };
+    }
     const entry = createEntry(msg, opts);
+    if (!persistBeforeAccept(entry)) {
+      throw new Error(`store.persist failed before accept (id=${entry.id})`);
+    }
     ensureSettledSub();
     return new Promise((resolve, reject) => {
       checkedPending.push({ entry, resolve, reject });
@@ -459,7 +508,6 @@ function createDelivery(port, config) {
   }
   function flush() {
     if (disposed) return;
-    clearMergeTimer();
     scheduleFlush();
   }
   function depth() {
@@ -470,7 +518,7 @@ function createDelivery(port, config) {
   function entriesFull() {
     return {
       active: active.map(snapshot),
-      tombstones: [...tombstones.values()].map((t) => ({ ...t }))
+      tombstones: [...terminalRecords.values()].map((t) => ({ ...t }))
     };
   }
   function projection() {
@@ -489,11 +537,33 @@ 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;
   }
+  function confirmDeliveredByProof(id) {
+    if (disposed) {
+      warn(`confirmDeliveredByProof ignored: delivery handle disposed (id=${id})`);
+      return false;
+    }
+    const e = activeIndex.get(id);
+    if (!e || e.receiptAnchor !== "details-id") return false;
+    if (e.state !== "queued" && e.state !== "in-flight") return false;
+    if (!cfg.proofCheck) {
+      warn(`details-id entry has no proofCheck injected; delivery unconfirmed (id=${id})`);
+      return false;
+    }
+    let proven;
+    try {
+      proven = cfg.proofCheck(id);
+    } catch (err) {
+      warn(`proofCheck threw; treating as not-delivered (id=${id})`, err);
+      return false;
+    }
+    if (!proven) return false;
+    return confirmDelivered(id);
+  }
   function confirmAccepted(id) {
     if (disposed) return false;
     const e = activeIndex.get(id);
@@ -543,7 +613,7 @@ function createDelivery(port, config) {
     }
     const e = activeIndex.get(id);
     if (!e) {
-      const tb = tombstones.get(id);
+      const tb = terminalRecords.get(id);
       if (tb) return { kind: "already-final", tombstone: { ...tb } };
       return { kind: "not-found" };
     }
@@ -562,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();
@@ -584,7 +666,6 @@ function createDelivery(port, config) {
   }
   function drain() {
     if (disposed) return [];
-    clearMergeTimer();
     const drained = active.slice();
     active.length = 0;
     activeIndex.clear();
@@ -592,7 +673,9 @@ function createDelivery(port, config) {
     inFlight = false;
     const ts = now();
     const result = drained.map((e) => {
-      tombstones.set(e.id, { id: e.id, state: "cancelled", lane: e.lane, settledAt: ts });
+      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) {
@@ -604,11 +687,11 @@ function createDelivery(port, config) {
   }
   function dispose() {
     disposed = true;
-    clearMergeTimer();
     teardownSettledSub();
     active.length = 0;
     activeIndex.clear();
-    tombstones.clear();
+    terminalIndex.clear();
+    terminalRecords.clear();
     deliveredLog.length = 0;
     inflightBatch = [];
     inFlight = false;
@@ -619,9 +702,123 @@ function createDelivery(port, config) {
     checkedPending.length = 0;
     dedupSet?.clear();
   }
-  return { send, sendChecked, flush, depth, entriesFull, projection, onChange, confirmDelivered, 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
+function serializeLine(line) {
+  return `${JSON.stringify(line)}
+`;
+}
+function createDiskDeliveryStore(deps) {
+  const { fs, dir, file } = deps;
+  const log = deps.log ?? ((message, err) => {
+    console.warn(message, err ?? "");
+  });
+  let loaded = false;
+  const records = /* @__PURE__ */ new Map();
+  const terminalIds = /* @__PURE__ */ new Set();
+  const discardedIds = /* @__PURE__ */ new Set();
+  let dirCreated = false;
+  function applyLine(line) {
+    if (line.t === "record") {
+      records.set(line.r.id, line.r);
+      discardedIds.delete(line.r.id);
+      return;
+    }
+    if (line.t === "ack") {
+      terminalIds.add(line.id);
+      return;
+    }
+    if (line.t === "discard") {
+      discardedIds.add(line.id);
+      records.delete(line.id);
+      return;
+    }
+    const record = records.get(line.id);
+    if (record) {
+      record.meta = { ...record.meta, segments: line.segments };
+    }
+  }
+  function ensureLoaded() {
+    if (loaded) return;
+    loaded = true;
+    if (!fs.existsSync(file)) return;
+    let raw;
+    try {
+      raw = fs.readFileSync(file, "utf8");
+    } catch (err) {
+      log(`[disk-delivery-store] read failed (treated as empty), file=${file}`, err);
+      return;
+    }
+    let lineNumber = 0;
+    for (const lineText of raw.split("\n")) {
+      lineNumber += 1;
+      const trimmed = lineText.trim();
+      if (trimmed === "") continue;
+      let line;
+      try {
+        line = JSON.parse(trimmed);
+      } catch {
+        log(`[disk-delivery-store] corrupted line skipped, file=${file}, line=${lineNumber}`);
+        continue;
+      }
+      if (!line || typeof line !== "object" || typeof line.t !== "string") {
+        log(`[disk-delivery-store] malformed line skipped, file=${file}, line=${lineNumber}`);
+        continue;
+      }
+      applyLine(line);
+    }
+  }
+  function appendLine(line) {
+    if (!dirCreated) {
+      fs.mkdirSync(dir, { recursive: true });
+      dirCreated = true;
+    }
+    fs.appendFileSync(file, serializeLine(line));
+  }
+  return {
+    persist(record) {
+      ensureLoaded();
+      appendLine({ t: "record", r: record });
+      applyLine({ t: "record", r: record });
+    },
+    ack(id) {
+      ensureLoaded();
+      appendLine({ t: "ack", id, at: Date.now() });
+      applyLine({ t: "ack", id, at: 0 });
+    },
+    discard(id) {
+      ensureLoaded();
+      appendLine({ t: "discard", id, at: Date.now() });
+      applyLine({ t: "discard", id, at: 0 });
+    },
+    loadUndelivered() {
+      ensureLoaded();
+      const out = [];
+      for (const record of records.values()) {
+        if (terminalIds.has(record.id) || discardedIds.has(record.id)) continue;
+        out.push(record);
+      }
+      return out;
+    },
+    loadTerminalIds() {
+      ensureLoaded();
+      return [...terminalIds];
+    },
+    hasTerminal(id) {
+      ensureLoaded();
+      return terminalIds.has(id);
+    },
+    attachSegments(id, segments) {
+      ensureLoaded();
+      appendLine({ t: "meta", id, segments: [...segments] });
+      applyLine({ t: "meta", id, segments: [...segments] });
+    }
+  };
 }
 export {
   DeliveryReclaimError,
-  createDelivery
+  createDelivery,
+  createDiskDeliveryStore
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zhushanwen/session-delivery",
-  "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",
+  "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",