@rei-standard/amsg-server 2.6.0-next.2 → 2.6.0-next.21

package/dist/lib/errors.d.ts

@@ -0,0 +1,215 @@
+/**
+ * 这个错误是不是「重试也好不了」。认 NonRetryableError，也认任何自带
+ * `permanent: true` 的错误对象（跨包/跨版本安全）。
+ *
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+export function isNonRetryableError(error: unknown): boolean;
+/**
+ * 把一个已经构造好的错误标成确定性失败（就地改，原样返回），顺带补一个稳定
+ * 的 `code`（错误自己带了 code 就不覆盖）。
+ *
+ * 用在错误由别处构造、又想保住它原本类型的时候——比如契约校验抛的
+ * `TypeError`：宿主按 `instanceof TypeError` 分流的代码不该因为库多标了一个
+ * 字段就走岔。自己现造错误的地方直接用 {@link NonRetryableError} 更直白。
+ *
+ * @template T
+ * @param {T} error
+ * @param {string} [code]
+ * @returns {T}
+ */
+export function markPermanent<T>(error: T, code?: string): T;
+/**
+ * 这个错误是不是「投递期间任务被取消/顶替」。
+ *
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+export function isTaskCancelledError(error: unknown): boolean;
+/**
+ * 这次投递失败要不要判成永久性的（不再重试）。四个来源：
+ *   - 已知的永久性错误码（见 {@link PERMANENT_ERROR_CODES}）；
+ *   - hook 侧抛出的 NonRetryableError（`permanent`，见 {@link NonRetryableError}）——
+ *     fire_pack 缺失、解析失败这类重试必然同败的错，隔两分钟再试三次只是让用户
+ *     多白等十二分钟，还把情绪评估之类的计费重跑三遍；
+ *   - 推送服务判了这条订阅的死刑（见 {@link TERMINAL_PUSH_STATUSES}）；
+ *   - 推送服务说这条 payload 太大（见 {@link PUSH_PAYLOAD_TOO_LARGE_STATUS}）。
+ *
+ * @param {{ permanent?: unknown, errorCode?: unknown, pushStatus?: unknown }} failure
+ * @returns {boolean}
+ */
+export function isPermanentDeliveryFailure(failure: {
+    permanent?: unknown;
+    errorCode?: unknown;
+    pushStatus?: unknown;
+}): boolean;
+/**
+ * 发一条 push，失败时自动标上「这是发 push 那一步抛的」。
+ *
+ * 发 push 的地方一律走这里，别各自写 `try { send } catch { throw
+ * tagPushStatusCode(e) }`：漏标一处，那条路上的 410 就读不出状态码，一条早就
+ * 失效的订阅会被当成普通失败，在退避阶梯上把 LLM 重跑三轮。忘了标是没有任何
+ * 提示的。
+ *
+ * @param {{ sendNotification: (subscription: any, payload: string) => Promise<any> }} webpush
+ * @param {any} subscription
+ * @param {string} payloadJson
+ * @returns {Promise<any>}
+ */
+export function sendTaggedPush(webpush: {
+    sendNotification: (subscription: any, payload: string) => Promise<any>;
+}, subscription: any, payloadJson: string): Promise<any>;
+/**
+ * 读推送服务回的状态码。没被 {@link tagPushStatusCode} 标过 → null。
+ *
+ * @param {unknown} error
+ * @returns {number|null}
+ */
+export function readPushStatusCode(error: unknown): number | null;
+/**
+ * lastError 里的机读标注：`errorCode` 是底层错误的稳定 code（如
+ * `PUSH_PAYLOAD_TOO_LARGE`），`pushStatus` 是推送服务回的 HTTP 状态码。两个都
+ * 没有 → undefined，不往记录里塞空字段。
+ *
+ * reason 那句是给用户看的人话、措辞随时会变，判断「该让用户重建订阅还是裁短
+ * 内容」得读这两个字段。定时任务（run-tick）与 instant 任务
+ * （processMessagesByUuid）共用这一份，两条路记下来的形状一致。
+ *
+ * code 是标识符不是人话，不用脱敏，但也别让一个来路不明的超长 code 撑大明文
+ * 列——截到 64 字符，够放所有约定过的码。
+ *
+ * @param {string|null|undefined} errorCode
+ * @param {number|null|undefined} pushStatus
+ * @returns {{ errorCode?: string, pushStatus?: number }|undefined}
+ */
+export function buildErrorExtra(errorCode: string | null | undefined, pushStatus: number | null | undefined): {
+    errorCode?: string;
+    pushStatus?: number;
+} | undefined;
+/**
+ * 把错误原因脱敏成能明文落库（任务行 last_error 列）的摘要。
+ *
+ * 任务内容一律密文落库，last_error 是唯一一列明文的「为什么没发出去」——
+ * 错误消息偶尔会回显请求细节（上游 API 的报错带 URL、header 片段），所以
+ * 长得像凭据的 token 一律遮掉，再截断。
+ *
+ * 遮什么、怎么遮由 @rei-standard/amsg-shared 的 `redactCredentials` 说了算，
+ * 这里只负责压平空白和截断。
+ *
+ * @param {unknown} reason
+ * @returns {string}
+ */
+export function sanitizeErrorSummary(reason: unknown): string;
+/**
+ * @typedef {Object} ErrorCause
+ * @property {'config'|'request'|'tick'} stage - 在哪一段炸的
+ * @property {string} name - 错误类型（`error.name`，认不出来时是 'Error'）
+ * @property {string} [message] - 脱敏后的错误消息。降级 500（配置都没建起来那条
+ *   路）回给跨域调用方时不带这个字段——那条路的 CORS 头是回显来访 Origin 的，任
+ *   意第三方页面都能读，而构建期异常原文里常有 binding 名、内网域名、环境变量
+ *   名。同源 / 无 Origin 的请求照旧带全文，`wrangler tail` 里也一直有。
+ * @property {string} [code] - 错误自带的 `code` 字符串（有才带）
+ */
+/**
+ * 把一个异常整理成能随响应体一起回给调用方的机读原因。
+ *
+ * 500 只回一句「服务器内部错误」的话，真因（`D1_ERROR: no such table:
+ * message_outbox`、存储层写超时……）就只剩 console.error 里那一行，调用方拿不
+ * 到，用户看到的也只是「服务器内部错误」——不知道哪儿坏了，也不知道该点哪里。
+ * 这个函数把异常压成几个固定字段，让调用方能机读、能展示。
+ *
+ * 只带错误类型和消息文本。消息先过 `sanitizeErrorSummary`（遮掉长得像凭据的
+ * 串、截断到 500 字符）；密钥、用户数据、任务正文都不在 `error.message` 上，
+ * 也不往这里放。
+ *
+ * @param {unknown} error - 捕获到的异常，也收 `{ name, message }` 这样的普通对象
+ * @param {'config'|'request'|'tick'} stage - 'config' = 构建配置时抛的（少了
+ *   binding / 环境变量）；'request' = 路由或处理器抛的；'tick' = cron 那一跳抛的
+ * @returns {ErrorCause}
+ */
+export function summarizeErrorCause(error: unknown, stage: "config" | "request" | "tick"): ErrorCause;
+/**
+ * 确定性失败——重试必然同败，别再排退避阶梯。
+ *
+ * 典型场景全在 fire-time hook 里：onBeforeFire 发现 fire_pack 缺失、解析失
+ * 败、缺必要的段……这类错误不会因为过两分钟再跑一次就好，按普通投递失败重
+ * 试三轮只是让用户多白等十几分钟，还把 hook 里的计费调用（情绪评估之类）
+ * 重复烧三遍。hook 抛这个类（或任何带 `permanent: true` 的错误），run-tick
+ * 收到后跳过退避：一次性任务直接标 failed（原因进 last_error / payload 的
+ * lastError），循环任务直接作废本次 occurrence。
+ *
+ * `code`（可选）会透传到 processSingleMessage 的 errorCode，宿主想按错误类
+ * 别分流时用它。
+ *
+ * 用 `permanent` 属性而不是 instanceof 做判定：宿主的 worker 里可能打包了另
+ * 一份本库（版本错开、bundler 双实例），跨 realm 的 instanceof 靠不住。
+ */
+export class NonRetryableError extends Error {
+    /**
+     * @param {string} message
+     * @param {{ code?: string, cause?: unknown }} [options]
+     */
+    constructor(message: string, options?: {
+        code?: string;
+        cause?: unknown;
+    });
+    permanent: boolean;
+    code: string;
+}
+/**
+ * 部署级的配置 / 适配器能力错误——坏的不是这条任务，是这个部署。
+ *
+ * 典型场景：`hooks.onBeforeFire` 配了但 `onLLMOutput` 忘了配、`executeToolCalls`
+ * 没配、自定义适配器缺 `createTask` / `deleteTaskByUuid` / `upsertClientState`。
+ * 这类错误重试确实好不了，但**不能**判终态：同一个坏部署下每条到点的任务都会
+ * 撞同一个错，判终态就等于在那段时间里把每一条一次性任务都永久标 `failed`，
+ * 运维改好配置重新部署也捞不回来了（行已不在 pending，`PUT /update-message`
+ * 回 409）。所以留在退避阶梯上——配置一修好，还在阶梯上的任务下一跳就正常发
+ * 出去。这跟 VAPID 配错回的 400/401/403 是同一个道理，见
+ * {@link PUSH_PAYLOAD_TOO_LARGE_STATUS} 那段注释。
+ *
+ * 带 `code` 但不带 `permanent`：失败原因照旧进 last_error 的 `errorCode`，宿主
+ * 想分流照样读得到，只是不再跳过重试。
+ */
+export class DeploymentConfigError extends Error {
+    /**
+     * @param {string} message
+     * @param {{ code?: string, cause?: unknown }} [options]
+     */
+    constructor(message: string, options?: {
+        code?: string;
+        cause?: unknown;
+    });
+    code: string;
+}
+/**
+ * 投递期间发现「这条任务已经不归本次投递管了」时，推送侧抛的错误码：行被
+ * `DELETE /message` 取消、被 `supersedesUuid` 顶替，或被别的执行者收尾了。
+ *
+ * 发送方（message-processor 的正文投递、agentic-fire 的 hook 投递）靠它区分
+ * 「取消」和「发失败」——两者的收尾完全不同：取消要把这一批还没发出去的
+ * outbox 行撤掉，发失败则要把它们留着等补收。
+ */
+export const TASK_CANCELLED_CODE: "TASK_CANCELLED";
+export type ErrorCause = {
+    /**
+     * - 在哪一段炸的
+     */
+    stage: "config" | "request" | "tick";
+    /**
+     * - 错误类型（`error.name`，认不出来时是 'Error'）
+     */
+    name: string;
+    /**
+     * - 脱敏后的错误消息。降级 500（配置都没建起来那条
+     * 路）回给跨域调用方时不带这个字段——那条路的 CORS 头是回显来访 Origin 的，任
+     * 意第三方页面都能读，而构建期异常原文里常有 binding 名、内网域名、环境变量
+     * 名。同源 / 无 Origin 的请求照旧带全文，`wrangler tail` 里也一直有。
+     */
+    message?: string;
+    /**
+     * - 错误自带的 `code` 字符串（有才带）
+     */
+    code?: string;
+};

package/dist/lib/llm-credentials-store.d.ts

@@ -0,0 +1,147 @@
+/** 适配器支不支持用户级凭据存储。 */
+export function supportsLlmCredentialsStore(db: any): boolean;
+/**
+ * 一个字符串是不是合法 cred_id：非空、≤128 字符、不含控制字符。
+ *
+ * @param {unknown} credId
+ * @returns {boolean}
+ */
+export function isValidCredId(credId: unknown): boolean;
+/**
+ * 一份凭据 value 的形状：{ apiUrl, apiKey, primaryModel } 三字段全必填。
+ * 校验口径对齐 update-message 的凭据刷新：只查 truthy（+ 长度上限），不做
+ * 格式校验。
+ *
+ * @param {unknown} value
+ * @returns {string|null} 错误描述，合法时 null
+ */
+export function validateCredValue(value: unknown): string | null;
+/**
+ * 任务 payload 里 credRefs 字段的形状校验（schedule-message 与 update-message
+ * 共用一份口径）。
+ *
+ * @param {unknown} credRefs
+ * @returns {string|null} 错误描述，合法时 null
+ */
+export function validateCredRefs(credRefs: unknown): string | null;
+/**
+ * payload 带没带可用的 chat 凭据引用（`credRefs.chat`）。fire 侧的
+ * taskNeedsLlm 和校验共用这一个判据。
+ *
+ * @param {Object|null|undefined} payload
+ * @returns {boolean}
+ */
+export function hasChatCredRef(payload: any | null | undefined): boolean;
+/**
+ * payload 带没带非空的 credRefs 映射（不管里面是什么 purpose）。自排继承要在
+ * 「有 chat 引用」和「只有非 chat 引用」之间分支，这是后者用的那半个判据。
+ *
+ * @param {Object|null|undefined} payload
+ * @returns {boolean}
+ */
+export function hasCredRefs(payload: any | null | undefined): boolean;
+/**
+ * 批量写入（覆盖）这个用户的凭据。value 在这里加密。
+ *
+ * @param {Object} args
+ * @param {import('../adapters/interface.js').DbAdapter} args.db
+ * @param {string} args.userId
+ * @param {string} args.userKey
+ * @param {Array<{ credId: string, value: Object }>} args.credentials
+ * @returns {Promise<{ upserted: number }>}
+ */
+export function saveLlmCredentials({ db, userId, userKey, credentials }: {
+    db: import("../adapters/interface.js").DbAdapter;
+    userId: string;
+    userKey: string;
+    credentials: Array<{
+        credId: string;
+        value: any;
+    }>;
+}): Promise<{
+    upserted: number;
+}>;
+/**
+ * 排程 / 更新时的存在性检查：credRefs 里引用的 credId 有哪些还不在表里。
+ * 空缺不是这里的错误——回给调用方点名，由它组 4xx。
+ *
+ * @param {Object} args
+ * @param {import('../adapters/interface.js').DbAdapter} args.db
+ * @param {string} args.userId
+ * @param {Object} args.credRefs
+ * @returns {Promise<string[]>} 缺失的 credId（去重）
+ */
+export function findMissingCredIds({ db, userId, credRefs }: {
+    db: import("../adapters/interface.js").DbAdapter;
+    userId: string;
+    credRefs: any;
+}): Promise<string[]>;
+/**
+ * 按 cred_id 解出一份明文凭据。每次调用返回**新对象**；没有这行 / 解不开
+ * （换过 masterKey）→ null。
+ *
+ * 结果只该被「拿到就用」：合进发给 LLM 的请求对象、或在 hook 里当场发请求。
+ * 不要写回 payload / ctx / metadata——那些对象会流向 hook 和 push，凭据跟着
+ * 走就把 CREDENTIAL_PAYLOAD_KEYS 那道防线绕空了。
+ *
+ * @param {Object} args
+ * @param {import('../adapters/interface.js').DbAdapter} args.db
+ * @param {string} args.userId
+ * @param {string} args.userKey
+ * @param {string} args.credId
+ * @returns {Promise<{ apiUrl: string, apiKey: string, primaryModel: string }|null>}
+ */
+export function resolveLlmCredential({ db, userId, userKey, credId }: {
+    db: import("../adapters/interface.js").DbAdapter;
+    userId: string;
+    userKey: string;
+    credId: string;
+}): Promise<{
+    apiUrl: string;
+    apiKey: string;
+    primaryModel: string;
+} | null>;
+/**
+ * fire 时的 chat 凭据解析（message-processor 的两条老路径和 agentic 循环共用）。
+ *
+ * 解析顺序：
+ *   1. payload 没带 `credRefs.chat` → 返回 null，调用方按内联三件套的老行为走
+ *      （存量任务的零开销路径，不多打一次库）。
+ *   2. 带了 → 查表取值，查到就用表里那份（表是用户最近一次登记的，比冻结在
+ *      行里的新）。
+ *   3. 查不到行（被删 / 换过 masterKey / 适配器不支持）→ 退回内联三件套兜底
+ *      （update-message 给存量任务补 credRefs 时内联还留着，正是给这里用的）。
+ *   4. 都没有 → 抛 `code: 'CREDENTIAL_MISSING'`，走任务的常规失败/重试——用户
+ *      补传凭据后下一轮自愈。
+ *
+ * 返回的对象只许合进**发给 LLM 的请求对象**，见 resolveLlmCredential 的红线。
+ *
+ * @param {Object} args
+ * @param {import('../adapters/interface.js').DbAdapter} args.db
+ * @param {string} args.userId
+ * @param {string} args.userKey
+ * @param {Object} args.decryptedPayload
+ * @returns {Promise<{ apiUrl: string, apiKey: string, primaryModel: string }|null>}
+ */
+export function resolveFireCredentials({ db, userId, userKey, decryptedPayload }: {
+    db: import("../adapters/interface.js").DbAdapter;
+    userId: string;
+    userKey: string;
+    decryptedPayload: any;
+}): Promise<{
+    apiUrl: string;
+    apiKey: string;
+    primaryModel: string;
+} | null>;
+/** cred_id 的长度上限。 */
+export const CRED_ID_MAX_LENGTH: 128;
+/** value 单字段（apiUrl / apiKey / primaryModel）的长度上限。 */
+export const CRED_VALUE_FIELD_MAX_LENGTH: 2048;
+/** PUT 单批最多几条。 */
+export const CRED_PUT_BATCH_MAX: 100;
+/** 单用户最多存几行凭据。 */
+export const CRED_ROWS_PER_USER_MAX: 500;
+/** credRefs 最多几个 purpose 条目。 */
+export const CRED_REFS_MAX_ENTRIES: 16;
+/** credRefs 的 purpose 键长度上限。 */
+export const CRED_REFS_KEY_MAX_LENGTH: 64;

package/dist/lib/llm.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/message-processor.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @typedef {Object} ProcessorContext
+ * @property {Object}  webpush           - The web-push module instance (already VAPID-configured).
+ * @property {Object}  vapid             - { email, publicKey, privateKey }
+ * @property {import('../adapters/interface.js').DbAdapter} db
+ * @property {{ maxChunkBytes?: number, maxChunks?: number, maxTotalBytes?: number, ttlMs?: number }} [multipart]
+ *   分片传输的限额，宿主传给 `installReiSW` 的那一份原样传过来即可（见
+ *   resolveMultipartOptions）。不传 = 两边都用默认值。
+ */
+/**
+ * Process a single database task row: decrypt → generate content → push.
+ *
+ * @param {import('../adapters/interface.js').TaskRow} task
+ * @param {ProcessorContext} ctx
+ * @param {string} [providedMasterKey]
+ * @param {{ userKey: string, payload: Object } | null} [predecrypted] - 调用方
+ *   （run-tick 的预扫描）已经解好的 payload；传了就不再解第二遍。
+ * @returns {Promise<{ success: boolean, messagesSent: number, error?: string, errorCode?: string|null, pushStatusCode?: number|null, permanent?: boolean }>}
+ *   失败时 `pushStatusCode` 是推送服务回的 HTTP 状态码（不是推送阶段炸的 → null）。
+ */
+export function processSingleMessage(task: import("../adapters/interface.js").TaskRow, ctx: ProcessorContext, providedMasterKey?: string, predecrypted?: {
+    userKey: string;
+    payload: any;
+} | null): Promise<{
+    success: boolean;
+    messagesSent: number;
+    error?: string;
+    errorCode?: string | null;
+    pushStatusCode?: number | null;
+    permanent?: boolean;
+}>;
+/**
+ * Process a single message identified by UUID (used for instant type).
+ *
+ * @param {string} uuid
+ * @param {ProcessorContext} ctx
+ * @param {number} [maxRetries=2]
+ * @param {string} [userId]
+ * @param {string} [providedMasterKey]
+ * @returns {Promise<{ success: boolean, messagesSent?: number, retriesUsed?: number, reasoningError?: string, error?: Object }>}
+ *   `reasoningError` 只在正文都发出去了、思考过程那一条没发成时出现（思考过程是
+ *   附赠内容，它发不出去不算这条消息失败）。调用方拿它提示用户这次没有思考过程，
+ *   不带这个字段就是整轮都送到了。
+ */
+export function processMessagesByUuid(uuid: string, ctx: ProcessorContext, maxRetries?: number, userId?: string, providedMasterKey?: string): Promise<{
+    success: boolean;
+    messagesSent?: number;
+    retriesUsed?: number;
+    reasoningError?: string;
+    error?: any;
+}>;
+export { normalizeAiApiUrl } from "./llm.js";
+export type ProcessorContext = {
+    /**
+     * - The web-push module instance (already VAPID-configured).
+     */
+    webpush: any;
+    /**
+     * - { email, publicKey, privateKey }
+     */
+    vapid: any;
+    db: import("../adapters/interface.js").DbAdapter;
+    /**
+     * 分片传输的限额，宿主传给 `installReiSW` 的那一份原样传过来即可（见
+     * resolveMultipartOptions）。不传 = 两边都用默认值。
+     */
+    multipart?: {
+        maxChunkBytes?: number;
+        maxChunks?: number;
+        maxTotalBytes?: number;
+        ttlMs?: number;
+    };
+};

package/dist/lib/outbox-store.d.ts

@@ -0,0 +1,95 @@
+/** 适配器支持 outbox 吗（写入侧要用的两个方法都在才算）。 */
+export function supportsOutbox(db: any): boolean;
+/**
+ * 发送前把这一批 push 落进 outbox。push 对象须已定稿（messageId / sessionId /
+ * messageIndex / totalMessages / 任务身份都已补齐）——落进去的密文就是客户端
+ * 补收时拿到的那一份。
+ *
+ * @param {Object} args
+ * @param {Object} args.db
+ * @param {string} args.userId
+ * @param {CryptoKey|string} args.userKey - per-user 存储密钥
+ * @param {Object[]} args.pushes - 定稿后的 push 对象
+ * @returns {Promise<boolean>} 是否真的落了行（适配器不支持 / 落行失败 → false）
+ */
+export function appendPushesToOutbox({ db, userId, userKey, pushes }: {
+    db: any;
+    userId: string;
+    userKey: CryptoKey | string;
+    pushes: any[];
+}): Promise<boolean>;
+/**
+ * 把 push 对象转成 message_outbox 的行（payload 加密）。
+ *
+ * 抽出来是给 `ctx.emitResult()` 用的：它落的行要跟推送链路落的完全同构——
+ * 列一样、加密方式一样、身份字段的取法一样，客户端补收时才不用区分是谁写的。
+ *
+ * @param {Object[]} pushes - 定稿后的 push 对象
+ * @param {CryptoKey|string} userKey
+ * @param {number} createdAt - epoch 毫秒
+ * @returns {Promise<Object[]>}
+ */
+export function toOutboxRows(pushes: any[], userKey: CryptoKey | string, createdAt: number): Promise<any[]>;
+/**
+ * 把发出去的那部分标成 delivered（发送半途失败时只标已发出的段）。
+ *
+ * @param {Object} args
+ * @param {Object} args.db
+ * @param {string} args.userId
+ * @param {string[]} args.messageIds
+ */
+export function markPushesDelivered({ db, userId, messageIds }: {
+    db: any;
+    userId: string;
+    messageIds: string[];
+}): Promise<void>;
+/**
+ * 把这一批 push 里「没发出去的那些」从 outbox 撤掉。
+ *
+ * 取消撞上投递时用：整批 push 在开发之前就落进了 outbox，取消只拦住了 Web
+ * Push 这一路，剩下的行不撤掉，客户端下一次 GET /outbox 会照样把它们拉回去
+ * ——用户看到的就是「取消接口回了成功，消息还是来了」。
+ *
+ * 「哪些算没发出去」这条判据收在这里：投递侧只要把整批 push 和已发出的
+ * messageId 交过来就行。
+ *
+ * @param {Object} args
+ * @param {Object} args.db
+ * @param {string} args.userId
+ * @param {Array<{ messageId: string }>} args.pushes - 落进 outbox 的整批 push
+ * @param {string[]} args.sentIds - 已经发出去的 messageId
+ */
+export function discardUndeliveredPushes({ db, userId, pushes, sentIds }: {
+    db: any;
+    userId: string;
+    pushes: Array<{
+        messageId: string;
+    }>;
+    sentIds: string[];
+}): Promise<void>;
+/**
+ * 把某条任务名下「还没发出去的」行从 outbox 撤掉。
+ *
+ * 用在取消 / 顶替只碰了任务行的那两条路上（`DELETE /message` 与
+ * `supersedesUuid`）：任务此前投递到一半失败过的话，没发出去的那几段还躺在
+ * outbox 里等重试，任务行删掉它们也不会跟着走。不撤的话客户端下一次
+ * `GET /outbox` 照样把它们补收回去——用户看到的就是「取消接口回了成功，消息还
+ * 是来了」。
+ *
+ * 判据与 discardUndeliveredPushes 一致：只撤 delivered_at 为 null 的行。已经推
+ * 给设备的那几条撤不回来，行留着让客户端照常 ack——取消的意思是「别再发后面
+ * 的」，不是「把已经收到的从收件箱里抹掉」。
+ *
+ * 同样是 best-effort：适配器缺读/删任一侧就静默跳过，出错只记日志。取消 / 顶
+ * 替本身已经生效了，不该因为账本没清干净被翻成失败。
+ *
+ * @param {Object} args
+ * @param {Object} args.db
+ * @param {string} args.userId
+ * @param {string} args.taskUuid - 被取消 / 被顶替的任务 uuid
+ */
+export function discardUndeliveredPushesForTask({ db, userId, taskUuid }: {
+    db: any;
+    userId: string;
+    taskUuid: string;
+}): Promise<void>;

package/dist/lib/push-subscription-store.d.ts

@@ -0,0 +1,94 @@
+/** 适配器支不支持用户级订阅存储。 */
+export function supportsPushSubscriptionStore(db: any): boolean;
+/**
+ * 一个对象长得像不像 Web Push 订阅。只看投递必需的部分：没有 endpoint 就
+ * 谈不上往哪推。keys 缺失留给推送服务去拒，这里不替它判。
+ *
+ * @param {unknown} subscription
+ * @returns {boolean}
+ */
+export function isPushSubscriptionShape(subscription: unknown): boolean;
+/**
+ * 写入（覆盖）这个用户的订阅。
+ *
+ * @param {Object} args
+ * @param {import('../adapters/interface.js').DbAdapter} args.db
+ * @param {string} args.userId
+ * @param {string} args.userKey
+ * @param {Object} args.subscription - 明文订阅对象
+ * @param {number} [args.updatedAt] - epoch 毫秒，默认取当前时刻
+ * @returns {Promise<{ updatedAt: number }>}
+ */
+export function savePushSubscription({ db, userId, userKey, subscription, updatedAt }: {
+    db: import("../adapters/interface.js").DbAdapter;
+    userId: string;
+    userKey: string;
+    subscription: any;
+    updatedAt?: number;
+}): Promise<{
+    updatedAt: number;
+}>;
+/**
+ * 把一行 push_subscriptions 解成明文订阅。行不在、或订阅列是空的 → null；
+ * 密文解不开（换过 masterKey 之类）、解出来不是 JSON → 抛。
+ *
+ * 单独拎出来是为了让调用方分得开两类失败：`db.getPushSubscription()` 抛出来
+ * 的是基础设施问题（表没建、读超时），换个时候重试有救；这里抛出来的是这一
+ * 行的密文废了，重试多少次都一样。两者压在同一个 try 里就只能一起处理，读不
+ * 到库会被当成「这个用户没登记过」。
+ *
+ * @param {{ subscription?: unknown, updated_at?: unknown }|null|undefined} row - `getPushSubscription()` 读回的行
+ * @param {string} userKey
+ * @returns {Promise<{ subscription: Object, updatedAt: number|null }|null>}
+ */
+export function decodePushSubscriptionRow(row: {
+    subscription?: unknown;
+    updated_at?: unknown;
+} | null | undefined, userKey: string): Promise<{
+    subscription: any;
+    updatedAt: number | null;
+} | null>;
+/**
+ * 读回这个用户的订阅（解密后的明文对象）。没有登记过 → null。
+ *
+ * 读库失败和解密失败都原样抛出去：投递链路上这两种都得让任务失败，分不分得
+ * 开无所谓；要分开处理的调用方（GET /push-subscription）自己走上面两步。
+ *
+ * @param {Object} args
+ * @param {import('../adapters/interface.js').DbAdapter} args.db
+ * @param {string} args.userId
+ * @param {string} args.userKey
+ * @returns {Promise<{ subscription: Object, updatedAt: number|null }|null>}
+ */
+export function loadPushSubscription({ db, userId, userKey }: {
+    db: import("../adapters/interface.js").DbAdapter;
+    userId: string;
+    userKey: string;
+}): Promise<{
+    subscription: any;
+    updatedAt: number | null;
+} | null>;
+/**
+ * 投递前取订阅。取不到就抛——静默不发会让任务「成功」地什么都没做，用户
+ * 只看到消息凭空消失。抛出去走既有的重试 / 标记逻辑，原因也会记进 payload
+ * 的 lastError，`GET /messages` 上看得见。抛出的错误带稳定的 `code` 属性
+ * （'PUSH_SUBSCRIPTION_MISSING' / 'PUSH_SUBSCRIPTION_STORE_UNSUPPORTED'），
+ * 按类别分支请用它，别匹配 message 文案。
+ *
+ * `legacyFallback`：用户级存储里没有订阅时的兜底（升级前创建的任务把订阅
+ * 冻结在自己的 payload 里，这份订阅仍然有效）。存储里有订阅时永远用存储的
+ * 那份——它是用户最近一次登记的。
+ *
+ * @param {Object} args
+ * @param {import('../adapters/interface.js').DbAdapter} args.db
+ * @param {string} args.userId
+ * @param {string} args.userKey
+ * @param {unknown} [args.legacyFallback] - 旧任务 payload 里内嵌的订阅（可选）
+ * @returns {Promise<Object>} 明文订阅对象
+ */
+export function resolvePushSubscription({ db, userId, userKey, legacyFallback }: {
+    db: import("../adapters/interface.js").DbAdapter;
+    userId: string;
+    userKey: string;
+    legacyFallback?: unknown;
+}): Promise<any>;

package/dist/lib/recurrence.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 这个字符串能不能当 IANA 时区 id 用。建任务 / 改任务时校验，运行时不再猜。
+ *
+ * @param {unknown} tzId
+ * @returns {boolean}
+ */
+export function isValidTimeZoneId(tzId: unknown): boolean;
+/**
+ * 从名义触发时刻往后推 `periods` 个周期。
+ *
+ * @param {number} occurrenceMs - 名义触发时刻（epoch 毫秒）
+ * @param {'daily'|'weekly'} recurrenceType
+ * @param {number} periods - 推几个周期（≥ 1）
+ * @param {string|null} [tzId] - IANA 时区 id；缺省按 UTC 推进
+ * @returns {number} 推进之后的时刻（epoch 毫秒）
+ */
+export function advanceOccurrence(occurrenceMs: number, recurrenceType: "daily" | "weekly", periods: number, tzId?: string | null): number;
+/**
+ * 从名义触发时刻往后推，找到第一个在 `nowMs` 之后的 occurrence，并顺带
+ * 报出中间跳过了哪些。
+ *
+ * 推进基准永远是名义时刻本身（不是「现在」），所以停摆多久都不会漂到别的
+ * 钟点上。
+ *
+ * @param {number} occurrenceMs
+ * @param {'daily'|'weekly'} recurrenceType
+ * @param {number} nowMs
+ * @param {string|null} [tzId]
+ * @returns {{ nextMs: number, skippedCount: number, skippedOccurrences: number[], skippedTruncated: boolean }}
+ *   `skippedCount` 含传进来的这一次（它自己就是没发出去的那一次）。
+ *   `skippedOccurrences` 最多列 {@link MAX_LISTED_SKIPPED_OCCURRENCES} 个，
+ *   超了只给首末两个并把 `skippedTruncated` 置 true。
+ */
+export function planNextOccurrence(occurrenceMs: number, recurrenceType: "daily" | "weekly", nowMs: number, tzId?: string | null): {
+    nextMs: number;
+    skippedCount: number;
+    skippedOccurrences: number[];
+    skippedTruncated: boolean;
+};
+/**
+ * 下一次触发时刻的 ISO 字符串（写库用）。
+ *
+ * @param {number} occurrenceMs
+ * @param {'daily'|'weekly'} recurrenceType
+ * @param {number} nowMs
+ * @param {string|null} [tzId]
+ * @returns {string}
+ */
+export function nextFutureOccurrence(occurrenceMs: number, recurrenceType: "daily" | "weekly", nowMs: number, tzId?: string | null): string;
+/** 快进时最多逐条列出多少个被跳过的名义时刻，超了只给首末两个。 */
+export const MAX_LISTED_SKIPPED_OCCURRENCES: 32;