@zhushanwen/session-delivery 1.1.0 → 2.0.0

package/dist/index.d.mts

@@ -6,11 +6,30 @@
  * - 意图驱动：调用方声明 intent，内核处理与 session 运行状态的冲突
  * - 判别联合 payload：适配器声明 supportedPayloads 能力
  *
- * v2 增量（投递所有权内核，设计 .tmp/tech-design/delivery-ownership-kernel.md）：
- * 条目状态机/lane/条目双形态（活跃条目 + tombstone）/entriesFull()+projection() 双视图；行为实现在
+ * 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，波 1
+ * 纯增量零行为变化——装配不传新参数 = v2 行为逐字节不变）：
+ * - 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 承载。
+ * - 受理即出站模式（DeliveryDispatchMode）：'on-accept' 旁路忙闲门禁与合批窗口；
+ *   缺省 'queue-hold' = v2 队列持有行为不变。
  */
 /** 投递意图（D3）：turn 边界抢占 / run 结束后注入，均含 idle 唤醒语义。 */
 type DeliveryIntent = 'interrupt-at-turn-boundary' | 'after-run';
@@ -64,18 +83,38 @@ 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）。 */
@@ -96,6 +135,102 @@ interface DeliveryPort {
     /** agent_settled 边沿订阅（D8）。缺省时 busy 条目留守至外部 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'：首败即停 + 显式上报后从内核移除（runtime 文本车道现状；重试决策归
+ *   消费方——人看页面通知可重发）。store 已 persist 的记录同步 discard（失败条目
+ *   无判重语义，防重启后被 loadUndelivered 复活成死条目）。
+ * - 'retain'：失败条目留守——内存态转回 queued 等下一 settled 边沿 / 外部 flush
+ *   重入队（事件驱动，无定时器）；store 记录保留（不 ack 不 discard），重启后经
+ *   loadUndelivered 重入队（通知车道无人值守语义，与账本现状同构）。
+ *
+ * 缺省按载荷类型：custom = 'retain' / text = 'forget'（§3.4 提交选项缺省值表：
+ * 交互在席 vs 无人值守），提交方可显式覆写。sendChecked 挂起条目恒 'forget'（同步
+ * 失败回执契约与 retain 重投矛盾——调用方已收到失败，重投会产生「失败但送达」的
+ * 矛盾观测；显式申报 retain 时按 forget 处置并一次性 warn）。
+ */
+type DeliveryFailurePolicy = 'forget' | 'retain';
+/**
+ * 送达凭据检查函数（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）。 */
@@ -133,6 +268,30 @@ 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;
+    /**
+     * 出站运行模式（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 {
@@ -151,7 +310,7 @@ interface DeliveryHandle {
 }
 /**
  * 投递车道（D1）。lane 在条目创建时由 runtime 内核适配层判定（读权威 occupancy
- * 投影 + 内核自身队列态，单一判定源）后记录，此后不变。三档为投递车道语义名
+ * 派生视图 + 内核自身队列态，单一判定源）后记录，此后不变。三档为投递车道语义名
  * （设计 §1.1 术语表），非底层通道 API 词汇。
  */
 type DeliveryLane = 'direct' | 'steer' | 'queued';
@@ -164,7 +323,7 @@ type DeliveryLane = 'direct' | 'steer' | 'queued';
  * - in-flight → failed：断连事件驱动的未确认终局（failInFlight，ADR-0122——pi 连接
  *   断开时结果未知，显式失败交用户处置）
  * - failed → queued：用户重试（resync 单条重报）；failed → cancelled：用户移除
- * 帧投影四态差异：cancelled 不进 session.delivery 帧（D5③），协议侧帧 state 无此值。
+ * 帧派生视图四态差异：cancelled 不进 session.delivery 帧（D5③），协议侧帧 state 无此值。
  */
 type DeliveryEntryState = 'queued' | 'in-flight' | 'delivered' | 'failed' | 'cancelled';
 /**
@@ -188,39 +347,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 {
@@ -231,8 +395,8 @@ 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
+ * 驱动）之上升级为条目制所有权内核（v2 设计批次 D9①②③⑤ / D5②③ / D3，单元 u1——
+ * 设计文档未入 git，裁决随本仓 commit 历史可溯）。零 pi 依赖不变：确认/回收由适配器（runtime
  * registry）调 handle 方法驱动。
  *
  * 五态状态机（D9①，types.ts 迁移表）+ 本文件登记的两处实施扩展：
@@ -253,11 +417,13 @@ 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') 逐条显式上报 + 从内核移除。重试决策归消费方
+ * port.send 失败（含 accepted:false）一次即收尾——checked 条目 reject + 从内核移除；
+ * 非 checked 条目 onSettled('rejected') 逐条显式上报 + 从内核移除。唯一例外：拒绝
+ * 回执为 deferred 形态（设计内等待，DeliveryDeferReason——如 port 合批提交窗 hold）
+ * 不计首败，条目留守等投递端下一边沿重提（onSendDeferred）。重试决策归消费方
  * （人看页面通知、agent 收失败回执），内核只做忠实投递与事实上报。
  *
  * onSettled 记账口径（D9⑤ 升级）：
@@ -276,19 +442,50 @@ 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 增量（波 1 纯增量零行为变化——装配不传新参数 = v2 行为逐字节不变）：
+ * - DeliveryStore 端口（config.store）：send/sendChecked 受理前先 persist（耐久承诺
+ *   先于投递尝试；persist 抛错 = 承诺未落 → 拒收 rejected('persist-failed')，条目
+ *   回滚不入队不投递）；终局 delivered / cancelled 后 ack（finalizeEntry / drain）；
+ *   forget 失败条目 discard（无终局语义的记录无痕移除，防重启复活）。ack / 判重
+ *   查询的 store 异常降级 warn 留痕、状态机照常（终局事实已发生 / 探测降级同
+ *   safeIsIdle 型）；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 /
+ *   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）。
  *
- * 其余 v1 机制逐条保持：busy gate（isIdle + 内核在途内查双条件——hasPendingMessages
+ * 其余 v1/v2 机制逐条保持：busy gate（isIdle + 内核在途内查双条件——hasPendingMessages
  * 自镜像四件套已按 msg-pipeline-debloat D2 拆除，busy 判定内查 active 表）、合批窗口、
- * settled 边沿驱动、dedupe LRU、dispose 语义（丢弃不触发 onSettled、checked 挂账
+ * settled 边沿驱动、dedupe LRU、dispose 语义（丢弃不触发 onSettled、checked 挂起
  * reject）。[ADR-0122 退役登记] backoff 自动重试链、port.send settle 挂死兜底
  * （60s）、watchdog 30s 定时复核、无订阅装配 busy 退避轮询——时间平抑/补偿类机制
  * 全部删除，busy 等待归 settled 边沿与外部触发。depth() 口径保持 v1 = 尚未受理的
@@ -320,19 +517,36 @@ interface DeliverySubmitOptions {
     /** 投递车道（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' 的代价
      * = 静默丢送达确认语义（更隐蔽）。两害取可见者。新增无标记投递来源必须显式申报
-     * 'acceptance' 并登记来源清单（ADR-0074 词条）。
+     * 'acceptance' 或 'details-id' 并登记来源清单（ADR-0074 词条）。
      */
-    receiptAnchor?: 'marker' | 'acceptance';
+    receiptAnchor?: DeliveryReceiptAnchor;
+    /**
+     * 失败保留策略（v3）：port.send 首败时本条目的处置（ADR-0122 无内核自动重试不变
+     * ——retain 不是重试机制，是失败条目的留存策略）。
+     * - 'forget' = 首败即停 + 显式上报后移除（runtime 文本车道现状；store 已 persist
+     *   的记录同步 discard）。
+     * - 'retain' = 失败条目留守：内存态转回 queued 等下一 settled 边沿 / 外部 flush
+     *   重入队；store 记录保留（重启经 loadUndelivered 重入队）。
+     * 缺省按载荷类型：custom = 'retain' / text = 'forget'（§3.4 缺省值表：交互在席 vs
+     * 无人值守）。sendChecked 挂起条目恒 forget（同步失败回执契约与 retain 重投矛盾；
+     * 显式申报 retain 时按 forget 处置 + 一次性 warn）。
+     */
+    onFailure?: DeliveryFailurePolicy;
     /**
      * 无标记条目标志（pi1-disposition-chat-flow D14⑥ 起源；技能/芯片通路并入后为
      * 「出站不注标条目」统一标志——命令 / 手打 skill 与 prompt 模板 / `<taiji-skill>`
@@ -348,13 +562,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 +583,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 +592,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 +605,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 视为未送达，同 safeIsIdle 型）时
+     * 一律返回 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 终态化条数。
@@ -428,7 +654,7 @@ type DeliveryCancelResult = {
     entry: DeliveryEntry;
 } | {
     kind: 'already-final';
-    tombstone: DeliveryTombstone;
+    tombstone: DeliveryTerminalRecord;
 } | {
     kind: 'not-found';
 };
@@ -458,7 +684,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 +699,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

@@ -123,7 +123,10 @@ 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;
+  let mergeIgnoredWarned = false;
   const deliveredLog = [];
   const checkedPending = [];
   let inflightBatch = [];
@@ -136,6 +139,40 @@ function createDelivery(port, config) {
   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();
   }
@@ -200,7 +237,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);
@@ -250,7 +289,7 @@ function createDelivery(port, config) {
     if (settledUnsub || !port.subscribeSettled) return;
     settledUnsub = port.subscribeSettled(() => {
       if (disposed) return;
-      if (!isBusySafe()) {
+      if (cfg.dispatchMode === "on-accept" || !isBusySafe()) {
         flush();
       }
     });
@@ -289,6 +328,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 +367,38 @@ 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");
     }
     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;
+      }
+      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,13 +430,17 @@ function createDelivery(port, config) {
   function scheduleFlush() {
     if (disposed || !hasQueuedEntries()) return;
     if (inFlight) return;
-    if (isBusySafe()) 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) {
@@ -389,7 +456,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 +485,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,7 +508,10 @@ 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 (!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();
@@ -446,7 +532,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 are always 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 });
@@ -470,7 +566,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() {
@@ -494,6 +590,28 @@ function createDelivery(port, config) {
     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 +661,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" };
     }
@@ -592,7 +710,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) {
@@ -608,7 +728,8 @@ function createDelivery(port, config) {
     teardownSettledSub();
     active.length = 0;
     activeIndex.clear();
-    tombstones.clear();
+    terminalIndex.clear();
+    terminalRecords.clear();
     deliveredLog.length = 0;
     inflightBatch = [];
     inFlight = false;
@@ -619,9 +740,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, 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,6 +1,6 @@
 {
   "name": "@zhushanwen/session-delivery",
-  "version": "1.1.0",
+  "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",
   "main": "dist/index.mjs",
   "module": "dist/index.mjs",