@rei-standard/amsg-server 2.6.0-next.13 → 2.6.0-next.16

package/README.md

@@ -382,6 +382,108 @@ await runScheduledTick({
 
 `lease_until` / `retry_after` / `serialize_group`（都可空）。走 `POST /init-tenant`（或任何一次 `initSchema`）会自动给已有的表补上，跑几次都没事；手工维护表结构的看 `examples/cloudflare-single-user/schema.sql`，Postgres 侧对应三句 `ALTER TABLE scheduled_messages ADD COLUMN IF NOT EXISTS …`。分组串行还多一个索引 `idx_serialize_group_lease`，`initSchema` 一并建。
 
+## 表结构自查（`getSchemaVersion` / `ensureSchema`）
+
+建表语句是 `CREATE TABLE IF NOT EXISTS`，已经存在的表不会被改动，后加的列靠 `initSchema()` 里的 ALTER 补。升级到新版之后没人再跑一次建表的话，这个部署的表就停在旧形状上——cron 每分钟挂在缺的那一列上，任务一条都不发，而前端界面一切正常。
+
+这两个函数把「我需要什么 / 现在是什么 / 帮我补齐」露出来：
+
+```js
+import { getSchemaVersion, ensureSchema } from '@rei-standard/amsg-server/cloudflare';
+
+const state = await getSchemaVersion(db);
+// → { current: '2.6.0' | null, required: '2.6.0', ok: true | false, missing: [] }
+
+if (!state.ok) {
+  const fixed = await ensureSchema(db); // 建表 + 补列 + 建索引，重复调没事
+  // → { current, required, ok, missing, migrated: true, schema }
+}
+```
+
+| 字段 | 是什么 |
+|---|---|
+| `required` | 这一版代码需要的表结构版本（导出常量 `SCHEMA_VERSION`）。表结构自己的版本号，只在表 / 列 / 关键索引变化时抬，与包版本各走各的 |
+| `current` | 活库当前满足的版本：够用就是 `required` 那个值，缺东西就是 `null`（只知道不够用，不知道它停在哪一版） |
+| `ok` | 需要的表 / 列 / 关键索引是不是都在 |
+| `missing` | 缺什么，形如 `table:message_outbox` / `column:scheduled_messages.last_error` / `index:uidx_uuid`。整张表缺席时只报这一张表，不逐列展开 |
+| `migrated`（只有 `ensureSchema` 有） | 这次有没有真的跑 `initSchema()`。本来就够用 → `false`，`schema` 也是 `null` |
+
+「需要什么」是从建表语句里解析出来的，不是另抄一份清单：抄的那份漏掉新列的话，自查会对着一个缺列的库回「一切正常」。
+
+什么时候调、缺了怎么提示用户，由宿主决定——库不会在每次请求里偷偷迁移。`POST /init-tenant` 的行为一点没变（它内部做的就是 `initSchema()`）。
+
+单用户 Worker 上有走 `env` 的同名方法：`worker.getSchemaVersion(env)` / `worker.ensureSchema(env)`，省得自己再造一次适配器。
+
+自查要求适配器实现 `describeSchema()`（活库里现在有哪些表 / 列 / 索引，只读）。内置适配器里目前只有 D1 实现了；别的适配器调这两个函数会抛错，而不是假装一切正常。
+
+## 只跑指定那一条任务（`runTask`）
+
+`scheduled()` 的语义是「扫一遍所有到期任务」。刚落库的任务想立刻跑起来时，触发一次全量扫描是能达到目的，但那样多个执行者会去扫同一批任务，宿主只能退回单实例串行才不重复发。
+
+`runTask` 只跑指定那一条，走的是 cron 完全同一条投递链（占位、租约心跳、过期守卫、失败重试 / 终态、hook 全套）：
+
+```js
+// 单用户 Worker：从 env 拿库和配置
+const result = await worker.runTask(uuid, env);
+
+// 自己攒 ctx 的宿主（和 runScheduledTick 同一份 ctx）
+import { runTask } from '@rei-standard/amsg-server/cloudflare';
+const result = await runTask(ctx, uuid);
+```
+
+跑起来了是 `{ ran: true, summary }`（`summary` 与 `runScheduledTick` 的返回同构，`totalTasks` 恒为 1）。不跑的几种情形分开回报，宿主不用猜：
+
+| `reason` | 什么意思 | 附带 |
+|---|---|---|
+| `not_found` | 没有这条 uuid。一次性任务发完即删，所以「已经发完了」的那条也落在这里 | — |
+| `already_settled` | 行还在，但已经是终态 | `status`（`sent` / `failed`） |
+| `not_due` | 还没到触发时刻 | `nextSendAt` |
+| `retry_pending` | 上次投递失败，还在退避窗口里 | `retryAfter` |
+| `not_configured` | VAPID / webpush 没配齐，跑了也只是白扣这条任务一次重试（只有 `worker.runTask` 有这一种） | — |
+
+这个入口只是换了个触发器，不是绕过排期的后门：没到点、在退避窗口里的都不跑。`already_settled` 要求适配器实现 `getTaskStatusByUuidOnly(uuid)`（D1 / pg / neon 都实现了）；不实现的自定义适配器把这种情况并进 `not_found`。
+
+## 出错时的真实原因
+
+`fetch()` 兜底的 500 一直是 `{ success: false, error: { code: 'INTERNAL_ERROR', message: '服务器内部错误' } }`。这两个字段一个没动，真因加在 `error.cause` 上：
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "INTERNAL_ERROR",
+    "message": "服务器内部错误",
+    "cause": {
+      "stage": "request",
+      "name": "Error",
+      "message": "D1_ERROR: no such table: message_outbox"
+    }
+  }
+}
+```
+
+| 字段 | 是什么 |
+|---|---|
+| `stage` | 在哪一段炸的：`config` = 构建配置时（少了 binding、环境变量丢了），`request` = 路由或处理器抛错 |
+| `name` | 错误类型（`error.name`，认不出来时是 `Error`） |
+| `message` | 错误消息，长得像凭据的串已遮掉、超长截断到 500 字符 |
+| `code` | 错误自带的 `code` 字符串，有才带 |
+
+只带错误类型和消息文本：密钥、用户数据、任务正文都不在 `error.message` 上，也不往这里放。
+
+cron 那条路上没有调用方能读到响应，所以另开两个出口：
+
+```js
+export default createSingleUserCloudflareWorker(buildConfig, {
+  onError({ stage, error, cause, path }) {
+    // fetch / cron 任何一段出错都会调一次（best-effort，自身抛错只记日志）
+  },
+});
+```
+
+- `onError` 放在工厂的第二个参数上，而不是 `buildConfig` 的返回值里：`buildConfig` 自己抛错时配置里的东西一个都读不到，而那恰恰是最需要被看见的一种故障。`stage` 在 cron 路径上是 `config`（配置构建失败 / VAPID 没配齐）或 `tick`（那一跳抛错）。VAPID 没配齐这一支没有异常对象，`error` 为 `null`、`cause.name` 是 `VapidNotConfigured`。
+- `scheduled()` 现在有返回值：`{ ok: true, summary }` 或 `{ ok: false, cause }`。Cloudflare 不看它，是给「自己包一层再转调 `scheduled`」的宿主和测试用的。
+
 ## 导出 API（Exports）
 
 包根（`@rei-standard/amsg-server`）：
@@ -391,6 +493,10 @@ await runScheduledTick({
 - `createSingleUserCloudflareWorker` — 单用户 Cloudflare Worker 一键装配（`fetch` + `scheduled` 两个入口）
 - `createAdapter` / `createD1Adapter` — pg·neon / Cloudflare D1 数据库适配器
 - `runScheduledTick` — 手动触发一轮到期任务投递（自定义 cron 宿主、要调 `claimLeaseMs` 时用）
+- `runTask` — 只跑指定那一条任务（与 cron 同一条投递链）
+- `getSchemaVersion` / `ensureSchema` / `SCHEMA_VERSION` — 表结构自查与补齐
+- `summarizeErrorCause` — 把异常压成响应体里 `error.cause` 那个形状（自己包一层路由、想回同样形状时用同一份）
+- `NonRetryableError` / `isNonRetryableError` — hook 侧标注「重试也好不了」的失败
 - `createWebCryptoWebPush` — 纯 Web Crypto 的 Web Push 发送器（不依赖 `web-push` 包）
 - `createTenantToken` / `verifyTenantToken`
 - `deriveUserEncryptionKey` / `decryptPayload` / `encryptForStorage` / `decryptFromStorage`
@@ -401,7 +507,9 @@ await runScheduledTick({
 
 `@rei-standard/amsg-server/cloudflare` 子路径 —— 只含「单用户 + D1 + Web Crypto 推送」这条子图，不引用多租户装配线和 pg / neon / `web-push`，所以 D1-only 安装（不装可选数据库 peer）也能干净打包，Worker 不需要 `nodejs_compat` 兼容 flag：
 
-- `createSingleUserCloudflareWorker` / `createSingleUserServer` / `createD1Adapter` / `runScheduledTick`
+- `createSingleUserCloudflareWorker` / `createSingleUserServer` / `createD1Adapter` / `runScheduledTick` / `runTask`
+- `getSchemaVersion` / `ensureSchema` / `SCHEMA_VERSION`
+- `summarizeErrorCause` / `NonRetryableError` / `isNonRetryableError`
 - `createWebCryptoWebPush` / `measurePushPayload` / `MAX_PUSH_PAYLOAD_BYTES` / `WEB_PUSH_MAX_BODY_BYTES` / `WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES`
 - `deriveUserEncryptionKey` / `decryptPayload` / `encryptForStorage` / `decryptFromStorage`
 

package/dist/adapters/d1.d.ts

@@ -36,10 +36,47 @@ export class D1Adapter {
             error: any;
         })[];
     }>;
+    /**
+     * 活库里现在实际有哪些表 / 列 / 索引。
+     *
+     * 只读不写，纯粹如实回报：拿它跟这一版需要的清单对照的活儿在
+     * lib/schema-version.js（`getSchemaVersion` / `ensureSchema`）。库升级后表结
+     * 构变了而老部署没跑过 initSchema 时，cron 会每分钟静默挂在缺的那一列上，
+     * 界面上一切正常——这个方法就是让宿主查得出来。
+     *
+     * @returns {Promise<{ tables: Record<string, string[]>, indexes: string[] }>}
+     */
+    describeSchema(): Promise<{
+        tables: Record<string, string[]>;
+        indexes: string[];
+    }>;
     dropSchema(): Promise<void>;
     createTask(params: any): Promise<any>;
+    /**
+     * 建新任务的同时取消旧的那条（`POST /schedule-message` 的 supersedesUuid）。
+     *
+     * 两条语句走一次 batch（D1 的隐式事务 + 单次网络往返）：不会出现「旧的删了、
+     * 新的没建成」的中间态——INSERT 撞 uuid 唯一索引时整个 batch 回滚，旧行原样
+     * 留着，调用方按既有的 409 冲突路径处理。
+     *
+     * @param {import('./interface.js').InsertTaskParams} params
+     * @param {string} supersedesUuid - 要取消的旧任务 uuid（同一 user_id 下）
+     * @returns {Promise<Object>} createTask 的返回行 + `superseded`（旧行是否
+     *   真的被删掉；false = 旧行本就不存在）
+     */
+    createTaskSuperseding(params: import("./interface.js").InsertTaskParams, supersedesUuid: string): Promise<any>;
     getTaskByUuid(uuid: any, userId: any): Promise<any>;
     getTaskByUuidOnly(uuid: any): Promise<any>;
+    /**
+     * 这条 uuid 现在是什么状态——不限用户，也不限状态（getTaskByUuidOnly 只看
+     * pending 行）。`runTask` 用它把「这条已经跑完了」和「压根没这条」分开回报。
+     *
+     * @param {string} uuid
+     * @returns {Promise<{ status: string }|null>}
+     */
+    getTaskStatusByUuidOnly(uuid: string): Promise<{
+        status: string;
+    } | null>;
     updateTaskById(taskId: any, updates: any): Promise<any>;
     updateTaskByUuid(uuid: any, userId: any, encryptedPayload: any, extraFields: any): Promise<{
         uuid: any;
@@ -83,12 +120,34 @@ export class D1Adapter {
      *   有任务正在跑、排期被改过、或行已不是 pending
      */
     claimTask(taskId: number, expectedNextSendAt: string, leaseUntil: string | Date, serializeGroup?: string | null): Promise<boolean>;
+    /**
+     * 投递期间的租约续期（run-tick 的心跳用）。只在行仍是 pending 且确实持有
+     * 租约（lease_until 非空）时生效——收尾把租约放掉之后，迟到的心跳不会把
+     * 租约复活。
+     *
+     * @param {number} taskId
+     * @param {string|Date} leaseUntil - 新的租期末尾
+     * @returns {Promise<boolean>} true = 续上了
+     */
+    renewTaskLease(taskId: number, leaseUntil: string | Date): Promise<boolean>;
     listTasks(userId: any, opts?: {}): Promise<{
         tasks: any;
         total: number;
     }>;
     cleanupOldTasks(days?: number): Promise<any>;
     getTaskStatus(uuid: any, userId: any): Promise<any>;
+    /**
+     * 状态 + 失败摘要（GET /message 用它把「为什么失败」透给已失败的行——那些
+     * 行 getTaskByUuid 读不到，payload 里的 lastError 也就够不着了）。
+     *
+     * @param {string} uuid
+     * @param {string} userId
+     * @returns {Promise<{ status: string, last_error: string|null }|null>}
+     */
+    getTaskStatusInfo(uuid: string, userId: string): Promise<{
+        status: string;
+        last_error: string | null;
+    } | null>;
     /**
      * Batch upsert. Last-write-wins per (namespace, key): an entry older
      * than the stored row (updatedAt strictly lower) is skipped; equal or
@@ -178,4 +237,75 @@ export class D1Adapter {
      * @returns {Promise<boolean>} true = 确实删掉了一行
      */
     deletePushSubscription(userId: string): Promise<boolean>;
+    /**
+     * 发送前把这一批 push 落进 outbox（一次 batch）。(user_id, message_id)
+     * 唯一：重试同一 occurrence 带着同一批 messageId 再来时更新 payload、不加
+     * 第二行；客户端已经 ack 过的行不动（ack 是终态，重试不该把它拉回未读）。
+     *
+     * @param {string} userId
+     * @param {Array<{ message_id: string, task_uuid?: string|null, session_id?: string|null,
+     *   message_index?: number|null, total_messages?: number|null, payload: string, created_at: number }>} rows
+     *   `payload` 是整条 push JSON 的 encryptForStorage 密文。
+     * @returns {Promise<number>} 实际写入/更新的行数
+     */
+    appendOutboxMessages(userId: string, rows: Array<{
+        message_id: string;
+        task_uuid?: string | null;
+        session_id?: string | null;
+        message_index?: number | null;
+        total_messages?: number | null;
+        payload: string;
+        created_at: number;
+    }>): Promise<number>;
+    /**
+     * 把这一批标记为「Web Push 已发出」。发送失败的段不标——delivered_at 为
+     * null 的行正是客户端最需要拉的那部分。
+     *
+     * @param {string} userId
+     * @param {string[]} messageIds
+     * @param {number} deliveredAt - epoch 毫秒
+     * @returns {Promise<number>}
+     */
+    markOutboxDelivered(userId: string, messageIds: string[], deliveredAt: number): Promise<number>;
+    /**
+     * 未 ack 的行（id 升序，游标翻页）。payload 仍是密文，解密在 handler。
+     *
+     * @param {string} userId
+     * @param {number} sinceId - 上一页游标（0 = 从头）
+     * @param {number} limit
+     * @returns {Promise<Array<{ id: number, message_id: string, task_uuid: string|null,
+     *   session_id: string|null, message_index: number|null, total_messages: number|null,
+     *   payload: string, created_at: number, delivered_at: number|null }>>}
+     */
+    listUnackedOutbox(userId: string, sinceId?: number, limit?: number): Promise<Array<{
+        id: number;
+        message_id: string;
+        task_uuid: string | null;
+        session_id: string | null;
+        message_index: number | null;
+        total_messages: number | null;
+        payload: string;
+        created_at: number;
+        delivered_at: number | null;
+    }>>;
+    /**
+     * 客户端确认收到这一批（幂等：已 ack 的行再 ack 不动）。
+     *
+     * @param {string} userId
+     * @param {string[]} messageIds
+     * @param {number} ackedAt - epoch 毫秒
+     * @returns {Promise<number>} 本次真正被 ack 的行数
+     */
+    ackOutboxMessages(userId: string, messageIds: string[], ackedAt: number): Promise<number>;
+    /**
+     * outbox 的例行清理（run-tick 每跳顺手调）：已 ack 的行留短一些，未 ack 的
+     * 也不无限留（Web Push TTL 上限四周，比它更老的推送谁也收不到了）。
+     *
+     * @param {{ ackedBeforeMs?: number, allBeforeMs?: number }} opts - epoch 毫秒阈值
+     * @returns {Promise<number>} 删掉的行数
+     */
+    cleanupOutbox({ ackedBeforeMs, allBeforeMs }?: {
+        ackedBeforeMs?: number;
+        allBeforeMs?: number;
+    }): Promise<number>;
 }

package/dist/adapters/interface.d.ts

@@ -29,6 +29,15 @@ export type DbAdapter = {
      *   Create the scheduled_messages table and all indexes.
      */
     initSchema: () => Promise<InitSchemaResult>;
+    /**
+     * （可选）活库里现在实际有哪些表 / 列 / 索引，只读不写。
+     * `getSchemaVersion` / `ensureSchema`（lib/schema-version.js）拿它跟这一版
+     * 需要的清单对照；不实现的适配器调那两个函数会抛错。内置只有 D1 实现。
+     */
+    describeSchema?: () => Promise<{
+        tables: Record<string, string[]>;
+        indexes: string[];
+    }>;
     /**
      *   Drop the scheduled_messages table (CASCADE).
      */
@@ -45,6 +54,14 @@ export type DbAdapter = {
      *   Fetch a single pending task by uuid only (used by instant processing).
      */
     getTaskByUuidOnly: (uuid: string) => Promise<TaskRow | null>;
+    /**
+     * （可选）这条 uuid 现在是什么状态——不限用户，也不限状态。`runTask` 用它
+     * 把「这条已经跑完进终态了」和「压根没这条」分开回报；不实现时两种都归
+     * `not_found`。
+     */
+    getTaskStatusByUuidOnly?: (uuid: string) => Promise<{
+        status: string;
+    } | null>;
     /**
      *   Partially update a task row by its numeric id.
      *   实现了 `claimTask` 的适配器还要认 `lease_until` 和 `retry_after`（含写
@@ -162,4 +179,54 @@ export type DbAdapter = {
      * （建了也永远发不出去）。内置的 D1 / pg / neon 适配器都实现了。
      */
     deletePushSubscription?: (userId: string) => Promise<boolean>;
+    /**
+     * （可选）投递期间的租约续期（runScheduledTick 的心跳）。只在行仍是
+     * pending 且 lease_until 非空时生效——收尾放掉租约之后，迟到的心跳不会把
+     * 它复活。不实现 → 心跳自动关闭，退回一次性长租约（claimLeaseMs）。
+     */
+    renewTaskLease?: (taskId: number, leaseUntil: string | Date) => Promise<boolean>;
+    /**
+     * （可选）状态 + last_error 列（脱敏失败摘要的 JSON 串）。GET /message 用
+     * 它把「为什么失败」透给已失败的行；不实现时退回 getTaskStatus（409 里就
+     * 没有 lastError）。
+     */
+    getTaskStatusInfo?: (uuid: string, userId: string) => Promise<{
+        status: string;
+        last_error: string | null;
+    } | null>;
+    /**
+     * （可选）建新任务的同一事务里取消旧的那条（POST /schedule-message 的
+     * supersedesUuid）。不实现时 handler 退回「先删再建」两步（失去原子性）。
+     */
+    createTaskSuperseding?: (params: InsertTaskParams, supersedesUuid: string) => Promise<TaskRow & {
+        superseded: boolean;
+    }>;
+    /**
+     * （可选；单用户/D1）push 发送前把整批落进 message_outbox（密文 payload），
+     * (user_id, message_id) 冲突时更新未 ack 的行、不动已 ack 的。
+     */
+    appendOutboxMessages?: (userId: string, rows: Array<any>) => Promise<number>;
+    /**
+     * （可选；单用户/D1）把发出去的段标 delivered_at。
+     */
+    markOutboxDelivered?: (userId: string, messageIds: string[], deliveredAt: number) => Promise<number>;
+    /**
+     * （可选；单用户/D1）未 ack 的行，id 升序游标翻页（GET /outbox）。
+     */
+    listUnackedOutbox?: (userId: string, sinceId: number, limit: number) => Promise<Array<any>>;
+    /**
+     * （可选；单用户/D1）客户端确认收到（POST /outbox/ack，幂等）。
+     */
+    ackOutboxMessages?: (userId: string, messageIds: string[], ackedAt: number) => Promise<number>;
+    /**
+     * （可选；单用户/D1）outbox 例行清理（runScheduledTick 每跳顺手调）。
+     *
+     * outbox 五个方法要么都实现、要么都不实现：缺写入侧的（append / mark），
+     * 发送链路静默跳过落行；缺读取侧的（list / ack），`GET /outbox` 与
+     * `POST /outbox/ack` 返回 501。内置只有 D1 实现（与 client_state 同待遇）。
+     */
+    cleanupOutbox?: (opts: {
+        ackedBeforeMs?: number;
+        allBeforeMs?: number;
+    }) => Promise<number>;
 };

package/dist/adapters/neon.d.ts

@@ -35,75 +35,37 @@ export class NeonAdapter {
     createTask(params: any): Promise<Record<string, any>>;
     getTaskByUuid(uuid: any, userId: any): Promise<Record<string, any>>;
     getTaskByUuidOnly(uuid: any): Promise<Record<string, any>>;
+    /**
+     * 这条 uuid 现在是什么状态——不限用户，也不限状态（上面那个只看 pending
+     * 行）。`runTask` 用它把「这条已经跑完了」和「压根没这条」分开回报。
+     *
+     * @param {string} uuid
+     * @returns {Promise<{ status: string }|null>}
+     */
+    getTaskStatusByUuidOnly(uuid: string): Promise<{
+        status: string;
+    } | null>;
     updateTaskById(taskId: any, updates: any): Promise<Record<string, any>>;
     updateTaskByUuid(uuid: any, userId: any, encryptedPayload: any, extraFields: any): Promise<Record<string, any>>;
     deleteTaskById(taskId: any): Promise<boolean>;
     deleteTaskByUuid(uuid: any, userId: any): Promise<boolean>;
     getPendingTasks(limit?: number): Promise<Record<string, any>[]>;
-    /**
-     * 领取一条到点的任务：在 lease_until 上写下「这条归我管到什么时候」，
-     * 本次投递期间别的 tick 领不走它。
-     *
-     * 租约写在自己的列上，next_send_at 全程不动——那一列是用户设的触发时刻，
-     * 任务列表要读它、循环任务推进下一次也要拿它当基准。
-     *
-     * 两个 tick 抢同一行时只有一个改得动，另一个拿不到 RETURNING 行，据此跳
-     * 过。WHERE 里的两个条件各管一件事：
-     *   - lease_until 为空或已过期：没人正在跑这条。领了任务的 tick 中途没了
-     *     也不会把行焊死，租约到期后自然可以被接手。
-     *   - next_send_at 等于读这行时看到的值：读出来之后用户又改了排期的话，
-     *     这一跳就不该再按旧时刻发。
-     *
-     * 不加一个 'sending' 状态来表达「正在跑」：status 上有 CHECK 约束，加值
-     * 要改表。
-     *
-     * 比 next_send_at 时两边都截到毫秒：列是 timestamptz（微秒精度），驱动读
-     * 出来是 JS Date（毫秒精度），原值送回去可能因为亚毫秒差对不上。
-     *
-     * 带 serializeGroup 时多一道分组门：同一分组里已经有别的行拿着未到期的租
-     * 约，这条就领不走（同一分组同时只跑一条）。判定和写租约在同一条 UPDATE
-     * 里完成，「先查再占」的空档天然不存在。分组门只看租约，不看
-     * `retry_after`：等着重试的任务其实闲着，不该把同分组的其他任务一起堵住。
-     *
-     * @param {number} taskId
-     * @param {string|Date} expectedNextSendAt - 读这行时拿到的 next_send_at 原值
-     * @param {string|Date} leaseUntil - 租期末尾
-     * @param {string|null} [serializeGroup] - 串行分组标识；空表示不参与分组串行
-     * @returns {Promise<boolean>} true = 领到了；false = 别人正拿着租约、同分组
-     *   有任务正在跑、排期被改过、或行已不是 pending
-     */
-    claimTask(taskId: number, expectedNextSendAt: string | Date, leaseUntil: string | Date, serializeGroup?: string | null): Promise<boolean>;
+    claimTask(taskId: any, expectedNextSendAt: any, leaseUntil: any, serializeGroup?: any): Promise<boolean>;
+    renewTaskLease(taskId: any, leaseUntil: any): Promise<boolean>;
     listTasks(userId: any, opts?: {}): Promise<{
         tasks: Record<string, any>[];
         total: number;
     }>;
     cleanupOldTasks(days?: number): Promise<number>;
     getTaskStatus(uuid: any, userId: any): Promise<any>;
-    /**
-     * 这个用户当前登记的推送订阅（密文原样返回，解密在上层）。
-     *
-     * @param {string} userId
-     * @returns {Promise<{ subscription: string, updated_at: number }|null>}
-     */
-    getPushSubscription(userId: string): Promise<{
+    getTaskStatusInfo(uuid: any, userId: any): Promise<{
+        status: string;
+        last_error: string | null;
+    }>;
+    getPushSubscription(userId: any): Promise<{
         subscription: string;
         updated_at: number;
-    } | null>;
-    /**
-     * 覆盖写这个用户的订阅。一个用户一行，没有 last-write-wins 之类的比较——
-     * 客户端拿到的新订阅永远比旧的有效，旧的那份只会 410。
-     *
-     * @param {string} userId
-     * @param {string} encryptedSubscription
-     * @param {number} updatedAt - epoch 毫秒
-     * @returns {Promise<boolean>}
-     */
-    upsertPushSubscription(userId: string, encryptedSubscription: string, updatedAt: number): Promise<boolean>;
-    /**
-     * 删掉这个用户的订阅（设置页「停止接收推送」）。
-     *
-     * @param {string} userId
-     * @returns {Promise<boolean>} true = 确实删掉了一行
-     */
-    deletePushSubscription(userId: string): Promise<boolean>;
+    }>;
+    upsertPushSubscription(userId: any, encryptedSubscription: any, updatedAt: any): Promise<boolean>;
+    deletePushSubscription(userId: any): Promise<boolean>;
 }

package/dist/adapters/pg-shared.d.ts

@@ -0,0 +1,114 @@
+/**
+ * pg / neon 共用的 Postgres 查询实现。
+ *
+ * 两个适配器只在「怎么把 SQL 发出去」上不同（pg 的连接池 vs neon 的 HTTP
+ * 驱动），SQL 与并发语义必须逐字一致——各自复制一份的话，修一边漏一边就会让
+ * 两种 Postgres 部署的串行化行为静默分歧，而各自的测试还都是绿的。所以这里
+ * 按执行器参数化：适配器只递一个 `query(text, params) → rows`。
+ *
+ * D1（SQLite 方言、单写者、ISO TEXT 时间戳）不走这份实现。
+ *
+ * @typedef {(text: string, params?: any[]) => Promise<any[]>} PgQuery
+ */
+/**
+ * 领取一条到点的任务：在 lease_until 上写下「这条归我管到什么时候」，
+ * 本次投递期间别的 tick 领不走它。
+ *
+ * 租约写在自己的列上，next_send_at 全程不动——那一列是用户设的触发时刻，
+ * 任务列表要读它、循环任务推进下一次也要拿它当基准。
+ *
+ * 两个 tick 抢同一行时只有一个改得动，另一个拿不到 RETURNING 行，据此跳
+ * 过。WHERE 里的两个条件各管一件事：
+ *   - lease_until 为空或已过期：没人正在跑这条。领了任务的 tick 中途没了
+ *     也不会把行焊死，租约到期后自然可以被接手。
+ *   - next_send_at 等于读这行时看到的值：读出来之后用户又改了排期的话，
+ *     这一跳就不该再按旧时刻发。
+ *
+ * 不加一个 'sending' 状态来表达「正在跑」：status 上有 CHECK 约束，加值
+ * 要改表。
+ *
+ * 比 next_send_at 时两边都截到毫秒：列是 timestamptz（微秒精度），驱动读
+ * 出来是 JS Date（毫秒精度），原值送回去可能因为亚毫秒差对不上。
+ *
+ * 带 serializeGroup 时多一道分组门：同一分组里已经有别的行拿着未到期的租
+ * 约，这条就领不走（同一分组同时只跑一条）。判定和写租约在同一条 UPDATE
+ * 里完成——但那只对「抢同一行」成立；READ COMMITTED 下两个并发 tick 各领
+ * 同组的**不同**行时，各自的 NOT EXISTS 子查询都看不到对方尚未提交的租约，
+ * 也没有行锁冲突逼它重查（写偏斜）。所以占位成功后再回头查一次：真撞上了
+ * 就把自己刚写的租约放掉、这一跳不跑——两边都让也没事，行保持 pending，
+ * 下一跳重试。分组门只看租约，不看 `retry_after`：等着重试的任务其实闲着，
+ * 不该把同分组的其他任务一起堵住。
+ *
+ * @param {PgQuery} query
+ * @param {number} taskId
+ * @param {string|Date} expectedNextSendAt - 读这行时拿到的 next_send_at 原值
+ * @param {string|Date} leaseUntil - 租期末尾
+ * @param {string|null} [serializeGroup] - 串行分组标识；空表示不参与分组串行
+ * @returns {Promise<boolean>} true = 领到了；false = 已被别人领走、同分组有
+ *   任务正在跑、排期被改过、或行已不是 pending
+ */
+export function claimTask(query: PgQuery, taskId: number, expectedNextSendAt: string | Date, leaseUntil: string | Date, serializeGroup?: string | null): Promise<boolean>;
+/**
+ * 投递期间的租约续期（run-tick 的心跳用）。只在行仍是 pending 且确实持有
+ * 租约（lease_until 非空）时生效——收尾把租约放掉之后，迟到的心跳不会把
+ * 租约复活。
+ *
+ * @param {PgQuery} query
+ * @param {number} taskId
+ * @param {string|Date} leaseUntil - 新的租期末尾
+ * @returns {Promise<boolean>} true = 续上了
+ */
+export function renewTaskLease(query: PgQuery, taskId: number, leaseUntil: string | Date): Promise<boolean>;
+/**
+ * 状态 + 失败摘要（GET /message 用它把「为什么失败」透给已失败的行）。
+ *
+ * @param {PgQuery} query
+ * @param {string} uuid
+ * @param {string} userId
+ * @returns {Promise<{ status: string, last_error: string|null }|null>}
+ */
+export function getTaskStatusInfo(query: PgQuery, uuid: string, userId: string): Promise<{
+    status: string;
+    last_error: string | null;
+} | null>;
+/**
+ * 这个用户当前登记的推送订阅（密文原样返回，解密在上层）。
+ *
+ * @param {PgQuery} query
+ * @param {string} userId
+ * @returns {Promise<{ subscription: string, updated_at: number }|null>}
+ */
+export function getPushSubscription(query: PgQuery, userId: string): Promise<{
+    subscription: string;
+    updated_at: number;
+} | null>;
+/**
+ * 覆盖写这个用户的订阅。一个用户一行，没有 last-write-wins 之类的比较——
+ * 客户端拿到的新订阅永远比旧的有效，旧的那份只会 410。
+ *
+ * @param {PgQuery} query
+ * @param {string} userId
+ * @param {string} encryptedSubscription
+ * @param {number} updatedAt - epoch 毫秒
+ * @returns {Promise<boolean>}
+ */
+export function upsertPushSubscription(query: PgQuery, userId: string, encryptedSubscription: string, updatedAt: number): Promise<boolean>;
+/**
+ * 删掉这个用户的订阅（设置页「停止接收推送」）。
+ *
+ * @param {PgQuery} query
+ * @param {string} userId
+ * @returns {Promise<boolean>} true = 确实删掉了一行
+ */
+export function deletePushSubscription(query: PgQuery, userId: string): Promise<boolean>;
+/**
+ * pg / neon 共用的 Postgres 查询实现。
+ *
+ * 两个适配器只在「怎么把 SQL 发出去」上不同（pg 的连接池 vs neon 的 HTTP
+ * 驱动），SQL 与并发语义必须逐字一致——各自复制一份的话，修一边漏一边就会让
+ * 两种 Postgres 部署的串行化行为静默分歧，而各自的测试还都是绿的。所以这里
+ * 按执行器参数化：适配器只递一个 `query(text, params) → rows`。
+ *
+ * D1（SQLite 方言、单写者、ISO TEXT 时间戳）不走这份实现。
+ */
+export type PgQuery = (text: string, params?: any[]) => Promise<any[]>;