@zhushanwen/session-delivery 0.10.1 → 0.11.0

package/dist/index.d.mts

@@ -23,6 +23,19 @@ interface CustomPayload {
 }
 /** 判别联合（D9）：envelope / payload 分离。 */
 type DeliveryPayload = TextPayload | CustomPayload;
+/**
+ * envelope additive meta（notify-once 设计 D2：notifyId 穿 envelope）。
+ *
+ * 内核对 meta 零读取零加工——只随消息对象本身流转；per-message 终态回调（onSettled，
+ * 见下方契约）收到的是**该条原始消息**，meta 因此原样到达回调（合批亦然：回调逐条
+ * 收各自原始消息，非 composed 合批消息）。消费方（runtime 债权桥接）在 delivered 回调
+ * 读 `msg.meta.notifyId` 完成 armed→injected 受理回执锚定。
+ */
+interface DeliveryMeta {
+    /** 通知债权幂等键（notify-once）：delivered 回执据此锚定受理事实。 */
+    notifyId?: string;
+    [key: string]: unknown;
+}
 /** 投递消息 envelope。 */
 interface DeliveryMessage {
     payload: DeliveryPayload;
@@ -32,6 +45,8 @@ interface DeliveryMessage {
     dedupeKey?: string;
     /** 持久性预留（一期仅 'in-memory'）。 */
     durability?: 'in-memory';
+    /** additive meta：不参与内核策略，per-message 原样透传 onSettled（见 DeliveryMeta）。 */
+    meta?: DeliveryMeta;
 }
 /**
  * port.send 的受理回执（U2 回执口径扩展位）。
@@ -87,7 +102,8 @@ interface DeliveryConfig {
     };
     /**
      * 投递终态信号（D4）。per-message 契约（ext-simplify-08 D1/B1）：批次内每条消息
-     * 各获一次终态回调，msg 为该条原始消息（非合批 composed 消息）；单消息批次行为
+     * 各获一次终态回调，msg 为该条原始消息（非合批 composed 消息）——additive meta
+     * （notifyId 等）随原消息一并到达回调；单消息批次行为
      * 不变。回调循环边界：回调内 dispose() 后本批剩余条目不再回调（与 dispose「丢弃
      * 队列不触发 onSettled」契约一致）；回调内再 send() 的新消息走标准 flush 管线
      * （空闲时可能在回调栈内立即投递）、不参与本批回调循环（契约完备性登记：当前
@@ -121,7 +137,8 @@ interface DeliveryHandle {
  * - watch-dog 低频复核（D8 兜底层①：settled 事件丢失的恢复路径）
  * - port.send 失败 → 消息留在途、按 backoff 有限重试，达上限 settle rejected（D4 错误重试）
  * - 终态上报 per-message（ext-simplify-08 D1/B1）：onSettled 对批次内每条消息各回调
- *   一次，msg 为该条原始消息（非 composed 合批消息）；单消息批次行为不变
+ *   一次，msg 为该条原始消息（非 composed 合批消息）——additive meta（notifyId 等）
+ *   随原消息引用原样透传到回调（内核不读不改）；单消息批次行为不变
  * - sendChecked() 统一经投递循环：resolve 挂钩 port.send 受理结果（busy 时经
  *   streaming 受理入 pi 队列即回，以此确认可达）；首次受理失败即 reject（入口即拦）
  * - in-flight 防重：单 handle 至多一个 port.send 在途

package/package.json

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