@zhushanwen/session-delivery 2.1.0 → 2.2.0

package/dist/index.d.mts

@@ -202,7 +202,7 @@ interface DeliveryStoreRecord {
     meta?: DeliveryMeta;
 }
 /**
- * 持久化存储端口（v3，统一语言词条「持久化存储端口」）：内核与耐久面的唯一接口。
+ * 持久化存储端口（v3，统一语言词条「持久化存储端口」）：内核与耐久层的唯一接口。
  * 两个实现在两半区适配层（本包零 fs 零 pi 知识）：runtime 半区 = 磁盘 outbox 文件
  * （文本投递路径，波 4 接线）；port 半区 = session entry 读写（通知投递路径，波 2 接线）。
  *
@@ -210,8 +210,12 @@ interface DeliveryStoreRecord {
  * - persist：send 受理前调用（耐久承诺先于投递尝试，与账本 record 先于 deliver 同
  *   律）。persist 抛错 = 承诺未落 → 内核拒收该条目（send 返回 persist-failed /
  *   sendChecked 同步 throw），不进入投递流程。
- * - ack：终局 delivered / cancelled 后调用（写持久终局——已撤销消息的防复活凭据
- *   同样在持久终局记录里）。ack 抛错不回滚状态机（终局事实已发生），warn 留痕。
+ * - ack：终局 delivered / cancelled 时调用（写持久终局——已撤销消息的防复活凭据
+ *   同样在持久终局记录里）。磁盘权威（2026-10-30 用户裁决「内存终态必须以磁盘确认为
+ *   准」）：ack 先于内存终态登记，抛错 = 持久终局未写入 → 内核不登记内存终态（条目
+ *   留守活跃集非终态）并显式上报分型错误 DeliveryAckPersistError；外部送达事实不
+ *   回滚，恢复后可能重投（at-least-once 显式接受）。实现方须遵守同序：自身内存派生
+ *   数据只在落盘成功后登记。
  * - discard：forget 失败条目的记录无痕移除（无终局无判重语义——区别于 ack，不进
  *   终局记录，防重启后 loadUndelivered 把已弃条目当未投递复活）。
  * - loadUndelivered：供重启 / 重放时重入队（装配方启动时取回未终局记录重新提交）。
@@ -228,7 +232,7 @@ interface DeliveryStoreRecord {
 interface DeliveryStore {
     /** 受理前写入记录（耐久承诺先于投递尝试）。抛错 = 承诺未写入，内核拒收。 */
     persist(record: DeliveryStoreRecord): void;
-    /** 终局（delivered / cancelled）后写持久终局（从待投差集移除、进终局记录）。 */
+    /** 终局（delivered / cancelled）写持久终局（从待投差集移除、进终局记录）。抛错 = 持久终局未写入 → 内核不登记内存终态（磁盘权威，见上方契约）。 */
     ack(id: string): void;
     /** forget 失败条目的记录无痕移除（无终局形态，区别于 ack）。 */
     discard(id: string): void;
@@ -272,7 +276,7 @@ interface DeliveryConfig {
      */
     onSettled?: (msg: DeliveryMessage, outcome: 'delivered' | 'rejected') => void;
     /**
-     * 持久化存储端口（v3）。缺省 undefined = 无耐久面（v2 行为：纯内存条目集）——
+     * 持久化存储端口（v3）。缺省 undefined = 无耐久层（v2 行为：纯内存条目集）——
      * 既有 runtime 装配不传 = 逐字节不变（波 1 零行为变化锚）。提供时内核行为契约见
      * DeliveryStore（受理前 persist / 终局 ack / forget 失败 discard / 构造期
      * loadTerminalIds 播种判重索引）。
@@ -459,10 +463,12 @@ interface DeliveryEntriesProjection {
  * 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 拒收（承诺语义）。
+ *   回滚不入队不投递）；终局 delivered / cancelled 时 ack（finalizeEntry / drain）；
+ *   forget 失败条目 discard（无终局语义的记录无痕移除，防重启复活）。ack 先于内存
+ *   终态登记（磁盘权威，2026-10-30 用户裁决「内存终态必须以磁盘确认为准」）：写盘
+ *   失败 → 内存不登记终态（条目留守活跃集非终态）+ 分型错误 DeliveryAckPersistError
+ *   显式上报——外部送达事实不回滚，恢复后可能重投（at-least-once 显式接受）；判重
+ *   查询（hasTerminal）异常保守放行 + warn；persist 异常 fail-fast 拒收（承诺语义）。
  * - 送达凭据三档（receiptAnchor）：'details-id' 与 'marker' / 'acceptance' 并列
  *   （ADR-0074 词条扩展）。details-id 条目受理后维持 in-flight 等回执（同 marker）；
  *   判定逻辑以可注入凭据检查函数（config.proofCheck）承载，调用点 =
@@ -652,7 +658,10 @@ interface DeliveryHandleV2 extends DeliveryHandle {
      * msg.payload 同步替换引用（onSettled per-message 契约的消费方拿到替换后内容）。
      */
     edit(id: string, payload: DeliveryPayload): boolean;
-    /** 全量取回文本（forceQuit，D9③）：条目清空 + 全部记 cancelled tombstone。 */
+    /**
+     * 全量取回文本（forceQuit，D9③）：条目清空 + 全部记 cancelled tombstone（ack 写盘
+     * 失败的条目除外——文本照常返回，条目转 failed 留守，见 drain 实现的磁盘权威序注释）。
+     */
     drain(): DrainResult;
 }
 /** cancel(id) 结果（D-3 偏差：cancelled 形态携带条目快照含 payload 全文供草稿恢复）。 */
@@ -686,7 +695,7 @@ declare function createDelivery(port: DeliveryPort, config?: DeliveryConfigWithW
  *
  * 判别形态依据（设计 §3.3 D4 尾注）：本包与消费方（runtime registry）是进程内同包
  * 调用边界——编译期类型可得，instanceof 是最简判别且免词表；与跨进程 WS 边界的
- * 分类码形态（CompactErrorCode）不构成双轨。
+ * error envelope 分类码形态不构成双轨。
  */
 /**
  * 「用户主动回收」对挂起 sendChecked waiter 的 reject 错误类。
@@ -708,6 +717,28 @@ declare class DeliveryReclaimError extends Error {
     readonly entryId: string | undefined;
     constructor(kind: 'cancelled' | 'drained', entryId?: string);
 }
+/**
+ * 「终局事实已发生，但持久终局（store.ack）写入失败」的分型错误（2026-10-30 用户裁决
+ * 「磁盘为准」：内存终态必须以磁盘确认为准）。
+ *
+ * 产生点（delivery.ts ackStore）：confirmDelivered / cancel / drain 终局化时先写持久
+ * 终局，store.ack 抛错即包装为本类——内核不登记内存终态（条目留守活跃集非终态，判重
+ * 与恢复以磁盘为唯一权威），由各终局入口捕获留痕并显式上报。
+ *
+ * 语义边界：外部送达事实不可回滚（消息已实际发出）——写盘失败期间该条不视为已终态，
+ * 恢复（重启重放 / 下一回执边沿重驱动）后可能重投，at-least-once 语义被显式接受
+ * （宁可可能重投，不做内存单方终态）。
+ *
+ * 结构化字段：
+ * - entryId：终局写入失败的条目 id。
+ * - state：本应落定的终态（'delivered' | 'cancelled'）——文案按它分叉：delivered 强调
+ *   送达事实已成立；cancelled 强调本地撤销意图已发生但持久撤销凭据未落。
+ */
+declare class DeliveryAckPersistError extends Error {
+    readonly entryId: string;
+    readonly state: 'delivered' | 'cancelled';
+    constructor(entryId: string, state: 'delivered' | 'cancelled', cause?: unknown);
+}
 
 /**
  * 磁盘 outbox —— DeliveryStore 的 runtime 半区实现（统一消息投递设计 §3.5.1 / §3.8
@@ -731,6 +762,8 @@ declare class DeliveryReclaimError extends Error {
  * 设计 §3.5.1「两个实现在两半区适配层」）；目录与文件路径由装配方（runtime 侧）动态
  * 推导后以字符串传入。崩溃写入的中途半行由读取容错覆盖（JSON.parse 失败 warn 跳过）
  * ——最坏丢一行 = 最坏多投一次，与「必达优先于去重」语义一致，不需要原子替换协议。
+ * 读失败（文件存在但不可读）显式分型上抛 DiskStoreReadError，不折叠成空结果（见
+ * ensureLoaded 注释）；文件不存在 = 合法空态。
  */
 
 /** fs 窄接口（注入点；生产 = node:fs 适配，测试 = 内存替身）。 */
@@ -762,6 +795,16 @@ interface DiskDeliveryStore extends DeliveryStore {
      */
     attachSegments(id: string, segments: readonly unknown[]): void;
 }
+/**
+ * outbox 读失败错误（显式分型：读失败 ≠ 空文件）。文件存在但不可读（权限 / 瞬时 fs
+ * 故障）时由 ensureLoaded 抛出——判别形态与 DeliveryReclaimError 同理（进程内同包
+ * 调用边界，instanceof 最简判别）。
+ */
+declare class DiskStoreReadError extends Error {
+    /** outbox 文件路径（诊断定位）。 */
+    readonly file: string;
+    constructor(file: string, cause?: unknown);
+}
 declare function createDiskDeliveryStore(deps: DiskDeliveryStoreDeps): DiskDeliveryStore;
 
-export { type CustomPayload, type DeliveryCancelResult, type DeliveryConfig, type DeliveryConfigWithWarn, type DeliveryDeferReason, type DeliveryEntriesFull, type DeliveryEntriesProjection, type DeliveryEntry, type DeliveryEntryState, type DeliveryFailurePolicy, type DeliveryHandle, type DeliveryHandleV2, type DeliveryIntent, type DeliveryLane, type DeliveryMessage, type DeliveryMeta, type DeliveryPayload, type DeliveryPort, type DeliveryProofCheck, type DeliveryReceiptAnchor, DeliveryReclaimError, type DeliverySendResult, type DeliveryStore, type DeliveryStoreRecord, type DeliverySubmitOptions, type DeliveryTerminalRecord, type DeliveryWarnSink, type DiskDeliveryStore, type DiskDeliveryStoreDeps, type DiskStoreFs, type DrainResult, type SendReceipt, type TextPayload, createDelivery, createDiskDeliveryStore };
+export { type CustomPayload, DeliveryAckPersistError, type DeliveryCancelResult, type DeliveryConfig, type DeliveryConfigWithWarn, type DeliveryDeferReason, type DeliveryEntriesFull, type DeliveryEntriesProjection, type DeliveryEntry, type DeliveryEntryState, type DeliveryFailurePolicy, type DeliveryHandle, type DeliveryHandleV2, type DeliveryIntent, type DeliveryLane, type DeliveryMessage, type DeliveryMeta, type DeliveryPayload, type DeliveryPort, type DeliveryProofCheck, type DeliveryReceiptAnchor, DeliveryReclaimError, type DeliverySendResult, type DeliveryStore, type DeliveryStoreRecord, type DeliverySubmitOptions, type DeliveryTerminalRecord, type DeliveryWarnSink, type DiskDeliveryStore, type DiskDeliveryStoreDeps, type DiskStoreFs, DiskStoreReadError, type DrainResult, type SendReceipt, type TextPayload, createDelivery, createDiskDeliveryStore };

package/dist/index.mjs

@@ -9,6 +9,19 @@ var DeliveryReclaimError = class extends Error {
     this.entryId = entryId;
   }
 };
+var DeliveryAckPersistError = class extends Error {
+  entryId;
+  state;
+  constructor(entryId, state, cause) {
+    super(
+      state === "delivered" ? `delivery delivered but terminal record not persisted; recovery may redeliver (id=${entryId})` : `entry cancelled locally but terminal record not persisted; recovery may redeliver (id=${entryId})`,
+      { cause }
+    );
+    this.name = "DeliveryAckPersistError";
+    this.entryId = entryId;
+    this.state = state;
+  }
+};
 
 // src/lru.ts
 var LruSet = class {
@@ -144,12 +157,12 @@ function createDelivery(port, config) {
       meta: e.msg.meta
     });
   }
-  function ackStore(id) {
+  function ackStore(id, state) {
     if (!store) return;
     try {
       store.ack(id);
     } catch (err) {
-      warn(`store.ack failed (terminal record not persisted; id=${id})`, err);
+      throw new DeliveryAckPersistError(id, state, err);
     }
   }
   function safeHasTerminal(id) {
@@ -203,6 +216,7 @@ function createDelivery(port, config) {
     return false;
   }
   function finalizeEntry(e, state) {
+    ackStore(e.id, state);
     const batchIdx = inflightBatch.indexOf(e);
     if (batchIdx !== -1) inflightBatch.splice(batchIdx, 1);
     const idx = active.indexOf(e);
@@ -214,7 +228,6 @@ function createDelivery(port, config) {
     e.settledAt = ts;
     terminalIndex.add(e.id);
     terminalRecords.set(e.id, { id: e.id, state, lane: e.lane, settledAt: ts });
-    ackStore(e.id);
     if (state === "delivered") {
       resolveWaitersOf(e);
       deliveredLog.push(e);
@@ -222,6 +235,25 @@ function createDelivery(port, config) {
     }
     notifyChange();
   }
+  function parkAsFailed(e) {
+    const batchIdx = inflightBatch.indexOf(e);
+    if (batchIdx !== -1) inflightBatch.splice(batchIdx, 1);
+    const ts = now();
+    e.state = "failed";
+    e.updatedAt = ts;
+    e.settledAt = ts;
+    notifyChange();
+  }
+  function cancelFinalize(e) {
+    try {
+      finalizeEntry(e, "cancelled");
+    } catch (err) {
+      if (!(err instanceof DeliveryAckPersistError)) throw err;
+      warn(`store.ack failed; cancel not terminalized, entry parked failed (id=${e.id})`, err);
+      parkAsFailed(e);
+      throw err;
+    }
+  }
   function removeActive(e) {
     const idx = active.indexOf(e);
     if (idx !== -1) active.splice(idx, 1);
@@ -538,7 +570,13 @@ function createDelivery(port, config) {
     const e = activeIndex.get(id);
     if (!e) return false;
     if (e.state !== "queued" && e.state !== "in-flight" && e.state !== "failed") return false;
-    finalizeEntry(e, "delivered");
+    try {
+      finalizeEntry(e, "delivered");
+    } catch (err) {
+      if (!(err instanceof DeliveryAckPersistError)) throw err;
+      warn(`store.ack failed; terminal not registered, entry stays non-terminal (id=${id})`, err);
+      return false;
+    }
     if (!disposed) callOnSettled(e.msg, "delivered");
     return true;
   }
@@ -625,11 +663,11 @@ function createDelivery(port, config) {
         return { kind: "reclaim-requested", entry: snapshot(e) };
       }
       rejectWaitersOf(e, new DeliveryReclaimError("cancelled", id));
-      finalizeEntry(e, "cancelled");
+      cancelFinalize(e);
       return { kind: "cancelled", entry: snapshot(e) };
     }
     rejectWaitersOf(e, new DeliveryReclaimError("cancelled", id));
-    finalizeEntry(e, "cancelled");
+    cancelFinalize(e);
     return { kind: "cancelled", entry: snapshot(e) };
   }
   function edit(id, payload) {
@@ -667,17 +705,28 @@ function createDelivery(port, config) {
   function drain() {
     if (disposed) return [];
     const drained = active.slice();
-    active.length = 0;
-    activeIndex.clear();
+    const ts = now();
+    const result = [];
+    for (const e of drained) {
+      try {
+        ackStore(e.id, "cancelled");
+        const idx = active.indexOf(e);
+        if (idx !== -1) active.splice(idx, 1);
+        activeIndex.delete(e.id);
+        e.state = "cancelled";
+        e.updatedAt = ts;
+        e.settledAt = ts;
+        terminalIndex.add(e.id);
+        terminalRecords.set(e.id, { id: e.id, state: "cancelled", lane: e.lane, settledAt: ts });
+      } catch (err) {
+        if (!(err instanceof DeliveryAckPersistError)) throw err;
+        warn(`store.ack failed in drain; entry not terminalized, parked failed (id=${e.id})`, err);
+        parkAsFailed(e);
+      }
+      result.push({ id: e.id, payload: e.payload });
+    }
     inflightBatch = [];
     inFlight = false;
-    const ts = now();
-    const result = drained.map((e) => {
-      terminalIndex.add(e.id);
-      terminalRecords.set(e.id, { id: e.id, state: "cancelled", lane: e.lane, settledAt: ts });
-      ackStore(e.id);
-      return { id: e.id, payload: e.payload };
-    });
     for (const w of checkedPending) {
       w.reject(new DeliveryReclaimError("drained"));
     }
@@ -710,6 +759,15 @@ function serializeLine(line) {
   return `${JSON.stringify(line)}
 `;
 }
+var DiskStoreReadError = class extends Error {
+  /** outbox 文件路径（诊断定位）。 */
+  file;
+  constructor(file, cause) {
+    super(`disk delivery store read failed: ${file}`, { cause });
+    this.name = "DiskStoreReadError";
+    this.file = file;
+  }
+};
 function createDiskDeliveryStore(deps) {
   const { fs, dir, file } = deps;
   const log = deps.log ?? ((message, err) => {
@@ -742,15 +800,18 @@ function createDiskDeliveryStore(deps) {
   }
   function ensureLoaded() {
     if (loaded) return;
-    loaded = true;
-    if (!fs.existsSync(file)) return;
+    if (!fs.existsSync(file)) {
+      loaded = true;
+      return;
+    }
     let raw;
     try {
       raw = fs.readFileSync(file, "utf8");
     } catch (err) {
-      log(`[disk-delivery-store] read failed (treated as empty), file=${file}`, err);
-      return;
+      log(`[disk-delivery-store] read failed (propagating; not treated as empty), file=${file}`, err);
+      throw new DiskStoreReadError(file, err);
     }
+    loaded = true;
     let lineNumber = 0;
     for (const lineText of raw.split("\n")) {
       lineNumber += 1;
@@ -818,7 +879,9 @@ function createDiskDeliveryStore(deps) {
   };
 }
 export {
+  DeliveryAckPersistError,
   DeliveryReclaimError,
+  DiskStoreReadError,
   createDelivery,
   createDiskDeliveryStore
 };

package/package.json

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