@rei-standard/amsg-server 2.6.0-next.11 → 2.6.0-next.12

package/README.md

@@ -43,6 +43,7 @@ const rei = await createReiServer({
 // PUT  /api/v1/update-message       -> rei.handlers.updateMessage.PUT
 // DELETE /api/v1/cancel-message     -> rei.handlers.cancelMessage.DELETE
 // GET  /api/v1/messages             -> rei.handlers.messages.GET
+// GET  /api/v1/message?id={uuid}    -> rei.handlers.getMessage.GET
 // PUT  /api/v1/push-subscription    -> rei.handlers.pushSubscription.PUT
 // GET  /api/v1/push-subscription    -> rei.handlers.pushSubscription.GET
 // DELETE /api/v1/push-subscription  -> rei.handlers.pushSubscription.DELETE
@@ -159,6 +160,27 @@ const message = body.length <= remainingBytes ? body : body.slice(0, remainingBy
 
 装不下的内容（长文、附件详情）建议走旁路：正文存进 `client_state`，push 里只带一个引用键，客户端上线后用 `GET /client-state` 取回。单用户 Worker 的 fire-time hook 用 `ctx.writeState()` 写，见 [`examples/cloudflare-single-user/README.md`](https://github.com/Tosd0/ReiStandard/blob/main/packages/rei-standard-amsg/server/examples/cloudflare-single-user/README.md)。
 
+## 读一条任务：列表 vs 单条
+
+| 端点 | 给什么 |
+|---|---|
+| `GET /messages` | 任务列表。每条只带 `charId` / `clientTaskId` 两个 `metadata` 子字段 |
+| `GET /message?id=<uuid>` | 单条任务。同样的形状，外加**完整的 `metadata`** |
+
+什么时候需要单条：`PUT /update-message` 对 `metadata` 是**整体替换**（不深合并），所以「只改 metadata 里的一个键」必须先把完整的那份读回来，改完再整份传上去；只传一部分会把宿主存在里面的其余键（任务指令、锚点时间戳、过期策略之类）一起冲掉。列表不带整份 metadata，是因为一页最多 100 条，每条都驮着它会把响应撑得很大，而列表要的只是「有哪些任务」。
+
+`GET /message` 只读得到还没发出去的任务；已完成 / 已失败的返回 `409 TASK_ALREADY_COMPLETED`，不存在返回 `404 TASK_NOT_FOUND`（与 `PUT /update-message` 同一口径）。响应和列表一样是加密的，客户端侧对应 `client.getMessage(uuid)`。
+
+## 更新任务时能改哪些字段
+
+`PUT /update-message` 的可写字段：`contactName` / `avatarUrl` / `userMessage` / `completePrompt` / `messages` / `nextSendAt` / `recurrenceType` / `tzId` / `metadata` / `maxTokens` / `temperature` / `splitPattern`，以及凭据三件套 `apiUrl` / `apiKey` / `primaryModel`。
+
+- `contactName` 必须是非空字符串（口径与排程时一致），空串 / `null` / 非字符串一律 `400`。用户给角色改了名之后，之前排的任务推送出来的通知标题（「来自 <contactName>」）靠它跟着改。
+- `metadata` 是整体替换，不深合并——只改一个子字段的读-改-写流程见上一节。
+- `avatarUrl` 显式传 `null` 是「不改」而不是「清空」（§6.2 的软清空策略要求非法头像被摘掉时保留旧头像，「摘掉」和「传了个 null」在这一层是同一件事）。
+- 凭据三件套传 `null` 同样只是忽略：清掉任何一个，任务到点就发不出去。
+- `pushSubscription` 不收（`400 PUSH_SUBSCRIPTION_NOT_ACCEPTED`），它是用户级的一份，走 `PUT /push-subscription`。
+
 ## 推送自带任务身份
 
 每条从任务行发出去的 push（冻结 prompt 路径和 fire-time hook 路径都算）顶层带这四个字段：
@@ -203,12 +225,24 @@ hook 在 `pushPayloads` 里自己写了这几个字段的话会被库覆盖：
 | hook | 什么时候调 | 载荷 |
 |---|---|---|
 | `onAfterSend` | fire 的 pushPayloads 逐段发完，或中途发挂 | `{ task, sentCount, total, error, scratch, readState, writeState }` |
+| `onFireSettled` | 一次 fire 收尾——只要 `onBeforeFire` 被调用过，什么结局都调一次 | `{ task, status, skipReason, sentCount, total, iterations, error, scratch, readState, writeState }` |
 | `onStaleSkip` | 任务错过触发时刻超过 60 分钟、这一次（或这几次）不再补发 | `{ reason, action, metadata, recurrenceType, occurrenceMs, skippedCount, skippedOccurrences, skippedTruncated, nextSendAt, readState, writeState }` |
 
-两个 hook 都自带 `readState` / `writeState`，作用于当前用户的 `client_state`，语义与 fire 级那套一致。`onStaleSkip` 尤其需要：服务停摆恢复后的第一跳里可能一次 fire 都没跑过，而那正是它要留痕迹的时候。
+三个 hook 都自带 `readState` / `writeState`，作用于当前用户的 `client_state`，语义与 fire 级那套一致。`onStaleSkip` 尤其需要：服务停摆恢复后的第一跳里可能一次 fire 都没跑过，而那正是它要留痕迹的时候。
 
 `onAfterSend` 的 `scratch` 与本次 fire 的 `onBeforeFire` / `onLLMOutput` 是同一个引用——「这次生成了哪几段正文」之类的上下文直接从这里读，不用自建按任务分格的登记表。全部成功时 `error` 为 `null`；第 k 段失败时 `sentCount = k`、`error` 带原始错误，且在错误往上抛之前调用完。
 
+`onFireSettled` 是「这次 fire 结束了」这一个信号，`status` 说明结局：
+
+| status | 什么时候 |
+|---|---|
+| `sent` | pushPayloads 全部发完（`sentCount === total`） |
+| `skipped` | 这次不发。`skipReason` 区分是 `onBeforeFire` 直接 `{ skip: true }`（`'before-fire'`）还是模型跑完后判定不发（`'skip-push'`） |
+| `failed` | 链路抛错，`error` 带原始错误。发到第 k 段挂了也是这个：`sentCount = k`、`total` 是原本要发的段数 |
+| `not-handled` | `onBeforeFire` 返回 `null`，这条任务交还给排程时冻结的 prompt 老链路。那条链路不归 fire hook 管，它后面发没发出去不体现在这里 |
+
+跟 `onAfterSend` 的分工：`onAfterSend` 只走「有 push 要发」这条路，所以 hook 判断这次不用说话、或者链路中途抛错时它不会被调到——「开始时占点什么、结束时放掉」的写法要挂 `onFireSettled`（fire 里已经用 `ctx.scheduleTask` 建出来的任务，不记账就成了只活在数据库里的幽灵任务；fire 开头拿的锁，没有可靠释放点就只能等 TTL）。正常发完时两个都会调，`onAfterSend` 在前。`scratch` 是同一个引用。没配 hooks 的部署、以及不需要 LLM 的固定文本任务不走 fire 这条路径，两个都不会调。
+
 `onStaleSkip` 的 `action` 分两种：
 
 - `expired` —— 一次性任务，这一次永远不会补发了，行已标 `failed`。
@@ -275,7 +309,7 @@ const result = await ctx.scheduleTask({
 
 ## 端点鉴权
 
-- `get-user-key`、`schedule-message`、`update-message`、`cancel-message`、`messages`
+- `get-user-key`、`schedule-message`、`update-message`、`cancel-message`、`messages`、`message`
   - `Authorization: Bearer <tenantToken>`
 - `send-notifications`
   - `Authorization: Bearer <cronToken>` 或 `?token=<cronToken>`
@@ -315,7 +349,38 @@ await client.scheduleMessage({
 
 内置适配器都实现了占位。自定义适配器可以不实现 `claimTask`，跑得动，只是回到不占位的行为。
 
-`lease_until` 是这次新加的列。走 `POST /init-tenant`（或任何一次 `initSchema`）会自动给已有的表补上；手工建表的看 `examples/cloudflare-single-user/schema.sql`。
+投递失败的退避记在 `retry_after` 上，租约同时放掉。两件事分两列记：`lease_until` 只表示「这条正在跑」，`retry_after` 表示「这条没在跑，在等重试」。挤在一列的话，下面的分组串行会把一条正在退避、其实闲着的任务当成「这一组忙着」，同组别的任务白等一轮退避（最长 6 分钟）。
+
+## 同一分组的任务不并发（`serializeBy`）
+
+同一个角色可能有好几条定时任务。撞在一起并发跑的话，用户一口气收到两条互不知情的消息；宿主在 hook 里维护的「我刚才说过什么」台账通常是读进内存 → 改 → 整份写回，两条各改各的再写回，后写的必然盖掉前面那条。
+
+`runScheduledTick`（以及单用户 Worker 的 config）收一个可选的 `serializeBy`：
+
+```js
+await runScheduledTick({
+  // ...其余 ctx
+  serializeBy: (task) => task.metadata?.charId ?? null,
+});
+```
+
+- 参数是与 `onBeforeFire` 的 `ctx.task` 同一份的只读任务视图（凭据已剔除）。
+- 返回 `null` / 空串、或者不配这个函数 → 这条任务不参与串行，行为与以前完全一致。
+- 同一分组同时只放行一条，**跨跳也算**：上一跳的 fire 还拿着租约时，下一跳捞到同组的另一条也不放行。一次 fire 常常跑十几秒到几分钟，只挡同一跳是不够的。
+- 同一跳内同组放行的是**到点更早**的那条；跑完之后不补跑同组剩下的，留给下一跳。
+- 被拦下的任务是**推迟不是丢弃**：`next_send_at` / `status` / `retry_count` 一个字段都不会被动，下一跳原样再捞一次。条数记在 `details.serializeSkippedTasks`（同一跳内拦下的）和 `details.claimSkippedTasks`（跨跳拦下的）里。
+- `serializeBy` 自身抛错时这条任务这一跳不跑：分不清它属于哪一组，就不该冒着破坏台账的风险跑下去。
+- 正在等重试的任务不算「这一组忙着」（退避记在 `retry_after` 上，租约已经放掉）。
+
+判定和占位是同一条 `UPDATE`：先查「这一组忙不忙」再占位的话，两个 tick 的查询会双双在对方占位之前返回「不忙」。分组 key 不明文落库——库拿它和该用户的存储密钥做一次 HMAC，`serialize_group` 列存的是那个派生值。
+
+自定义适配器实现了 `claimTask` 但忽略第四个参数的，分组串行退化成只在同一跳内生效；完全没实现 `claimTask` 的同理。
+
+`createReiServer` 内置的 `/send-notifications` 处理器不透传 `serializeBy`（和 `claimLeaseMs` 一样），多租户部署要用就自己调 `runScheduledTick`。单用户 Worker 直接在 config 里写。
+
+## 任务表用到的三列
+
+`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` 一并建。
 
 ## 导出 API（Exports）
 

package/dist/adapters/d1.d.ts

@@ -69,12 +69,20 @@ export class D1Adapter {
      * 着非归一化写法的行（如 +08:00 结尾），归一化后反而对不上，那条任务会永
      * 远领不到。
      *
+     * 带 serializeGroup 时多一道分组门：同一分组里已经有别的行拿着未到期的租
+     * 约，这条就领不走（同一分组同时只跑一条）。判定和写租约在同一条 UPDATE
+     * 里完成，「先查再占」的空档天然不存在——两个 tick 同时来，只有一个改得动
+     * 行。分组门只看租约，不看 `retry_after`：等着重试的任务其实闲着，不该把
+     * 同分组的其他任务一起堵住。
+     *
      * @param {number} taskId
      * @param {string} expectedNextSendAt - 读这行时拿到的 next_send_at 原值
      * @param {string|Date} leaseUntil - 租期末尾
-     * @returns {Promise<boolean>} true = 领到了；false = 别人正拿着租约、排期被改过、或行已不是 pending
+     * @param {string|null} [serializeGroup] - 串行分组标识；空表示不参与分组串行
+     * @returns {Promise<boolean>} true = 领到了；false = 别人正拿着租约、同分组
+     *   有任务正在跑、排期被改过、或行已不是 pending
      */
-    claimTask(taskId: number, expectedNextSendAt: string, leaseUntil: string | Date): Promise<boolean>;
+    claimTask(taskId: number, expectedNextSendAt: string, leaseUntil: string | Date, serializeGroup?: string | null): Promise<boolean>;
     listTasks(userId: any, opts?: {}): Promise<{
         tasks: any;
         total: number;

package/dist/adapters/interface.d.ts

@@ -47,8 +47,9 @@ export type DbAdapter = {
     getTaskByUuidOnly: (uuid: string) => Promise<TaskRow | null>;
     /**
      *   Partially update a task row by its numeric id.
-     *   实现了 `claimTask` 的适配器还要认 `lease_until`（含写 null）：投递收尾
-     *   时 runScheduledTick 用它把租约放掉。
+     *   实现了 `claimTask` 的适配器还要认 `lease_until` 和 `retry_after`（含写
+     *   null）：投递收尾时 runScheduledTick 用前者把租约放掉，用后者写/清投递失败
+     *   的退避时刻。
      */
     updateTaskById: (taskId: number, updates: any) => Promise<TaskRow | null>;
     /**
@@ -65,7 +66,8 @@ export type DbAdapter = {
     deleteTaskByUuid: (uuid: string, userId: string) => Promise<boolean>;
     /**
      *   Fetch pending tasks whose next_send_at <= NOW(), ordered ASC.
-     *   跳过租约还没到期的行（`lease_until` 为空或已过期才算待发）。
+     *   跳过两种还不该动的行：租约没到期的（`lease_until`，有人正在跑）、退避没到
+     *   点的（`retry_after`，上次投递失败在等重试）。两列都是空或已过期才算待发。
      */
     getPendingTasks: (limit?: number) => Promise<TaskRow[]>;
     /**
@@ -75,10 +77,15 @@ export type DbAdapter = {
      * （没别人正在跑）；`next_send_at` 还等于 `expectedNextSendAt`（读这行时
      * 拿到的值，用户中途改了排期就不发了）。领到就把 `lease_until` 写成
      * `leaseUntil`，`next_send_at` 不动。
+     * 传了非空 `serializeGroup` 时还多一个条件：同一分组里没有别的行拿着未到期
+     * 的租约（同一分组同时只跑一条，`runScheduledTick` 的 `serializeBy` 用）。
+     * 领到时把这个值写进 `serialize_group` 列。判定和占位必须在同一条语句里，
+     * 「先查再占」中间的空档会让两个 tick 同时进同一个分组。
      * 自定义适配器可以不实现（runScheduledTick 会退回不占位的行为，代价是慢
-     * 任务可能被下一跳重复触发）。
+     * 任务可能被下一跳重复触发）；实现了但忽略第四个参数的，分组串行退化成只在
+     * 同一跳内生效。
      */
-    claimTask?: (taskId: number, expectedNextSendAt: string | Date, leaseUntil: string | Date) => Promise<boolean>;
+    claimTask?: (taskId: number, expectedNextSendAt: string | Date, leaseUntil: string | Date, serializeGroup?: string | null) => Promise<boolean>;
     /**
      *   List tasks for a user with optional filters and pagination.
      */

package/dist/adapters/neon.d.ts

@@ -60,12 +60,19 @@ export class NeonAdapter {
      * 比 next_send_at 时两边都截到毫秒：列是 timestamptz（微秒精度），驱动读
      * 出来是 JS Date（毫秒精度），原值送回去可能因为亚毫秒差对不上。
      *
+     * 带 serializeGroup 时多一道分组门：同一分组里已经有别的行拿着未到期的租
+     * 约，这条就领不走（同一分组同时只跑一条）。判定和写租约在同一条 UPDATE
+     * 里完成，「先查再占」的空档天然不存在。分组门只看租约，不看
+     * `retry_after`：等着重试的任务其实闲着，不该把同分组的其他任务一起堵住。
+     *
      * @param {number} taskId
      * @param {string|Date} expectedNextSendAt - 读这行时拿到的 next_send_at 原值
      * @param {string|Date} leaseUntil - 租期末尾
-     * @returns {Promise<boolean>} true = 领到了；false = 别人正拿着租约、排期被改过、或行已不是 pending
+     * @param {string|null} [serializeGroup] - 串行分组标识；空表示不参与分组串行
+     * @returns {Promise<boolean>} true = 领到了；false = 别人正拿着租约、同分组
+     *   有任务正在跑、排期被改过、或行已不是 pending
      */
-    claimTask(taskId: number, expectedNextSendAt: string | Date, leaseUntil: string | Date): Promise<boolean>;
+    claimTask(taskId: number, expectedNextSendAt: string | Date, leaseUntil: string | Date, serializeGroup?: string | null): Promise<boolean>;
     listTasks(userId: any, opts?: {}): Promise<{
         tasks: Record<string, any>[];
         total: number;

package/dist/adapters/pg.d.ts

@@ -62,12 +62,19 @@ export class PgAdapter {
      * 比 next_send_at 时两边都截到毫秒：列是 timestamptz（微秒精度），驱动读
      * 出来是 JS Date（毫秒精度），原值送回去可能因为亚毫秒差对不上。
      *
+     * 带 serializeGroup 时多一道分组门：同一分组里已经有别的行拿着未到期的租
+     * 约，这条就领不走（同一分组同时只跑一条）。判定和写租约在同一条 UPDATE
+     * 里完成，「先查再占」的空档天然不存在。分组门只看租约，不看
+     * `retry_after`：等着重试的任务其实闲着，不该把同分组的其他任务一起堵住。
+     *
      * @param {number} taskId
      * @param {string|Date} expectedNextSendAt - 读这行时拿到的 next_send_at 原值
      * @param {string|Date} leaseUntil - 租期末尾
-     * @returns {Promise<boolean>} true = 领到了；false = 已被别人领走或行已不是 pending
+     * @param {string|null} [serializeGroup] - 串行分组标识；空表示不参与分组串行
+     * @returns {Promise<boolean>} true = 领到了；false = 已被别人领走、同分组有
+     *   任务正在跑、或行已不是 pending
      */
-    claimTask(taskId: number, expectedNextSendAt: string | Date, leaseUntil: string | Date): Promise<boolean>;
+    claimTask(taskId: number, expectedNextSendAt: string | Date, leaseUntil: string | Date, serializeGroup?: string | null): Promise<boolean>;
     listTasks(userId: any, opts?: {}): Promise<{
         tasks: any[][];
         total: number;

package/dist/adapters/schema.d.ts

@@ -1,7 +1,18 @@
 /**
  * Shared SQL schema constants
+ *
+ * 定时触发用的三列各管一件事，别把它们混着读（见 lib/run-tick.js）：
+ *   - `lease_until`：**这条正在跑**。某个 tick 占位时写「归我管到什么时候」，
+ *     投递收尾时放掉。捞取待发任务时跳过租约未到期的行。
+ *   - `retry_after`：**这条没在跑，等着重试**。投递失败的退避时刻，到点之前
+ *     捞不到这行。跟租约分开写，是因为「正在跑」会挡住同分组的其他任务，而
+ *     一条正在等重试的任务其实闲着，不该连累别人。
+ *   - `serialize_group`：这条属于哪个串行分组（`runScheduledTick` 的
+ *     `serializeBy` 算出来的，占位时一起写）。同一分组同时只放行一条。存的是
+ *     派生值而不是宿主给的原始 key —— 原始 key 往往是角色 id 之类的宿主数据，
+ *     任务内容都是密文落库的，这一列不该成为它的明文出口。
  */
-export const TABLE_SQL: "\n  CREATE TABLE IF NOT EXISTS scheduled_messages (\n    id SERIAL PRIMARY KEY,\n    user_id VARCHAR(255) NOT NULL,\n    uuid VARCHAR(36),\n    encrypted_payload TEXT NOT NULL,\n    message_type VARCHAR(50) NOT NULL CHECK (message_type IN ('fixed', 'prompted', 'auto', 'instant')),\n    next_send_at TIMESTAMP WITH TIME ZONE NOT NULL,\n    lease_until TIMESTAMP WITH TIME ZONE,\n    status VARCHAR(50) NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'sent', 'failed')),\n    retry_count INTEGER DEFAULT 0,\n    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),\n    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()\n  )\n";
+export const TABLE_SQL: "\n  CREATE TABLE IF NOT EXISTS scheduled_messages (\n    id SERIAL PRIMARY KEY,\n    user_id VARCHAR(255) NOT NULL,\n    uuid VARCHAR(36),\n    encrypted_payload TEXT NOT NULL,\n    message_type VARCHAR(50) NOT NULL CHECK (message_type IN ('fixed', 'prompted', 'auto', 'instant')),\n    next_send_at TIMESTAMP WITH TIME ZONE NOT NULL,\n    lease_until TIMESTAMP WITH TIME ZONE,\n    retry_after TIMESTAMP WITH TIME ZONE,\n    serialize_group VARCHAR(64),\n    status VARCHAR(50) NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'sent', 'failed')),\n    retry_count INTEGER DEFAULT 0,\n    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),\n    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()\n  )\n";
 /**
  * 建表语句用的是 CREATE TABLE IF NOT EXISTS，已经存在的表不会被改动，所以
  * 后加的列要单独补。initSchema 每次都会跑一遍，Postgres 的 IF NOT EXISTS

package/dist/adapters/schema.sqlite.d.ts

@@ -1,6 +1,9 @@
 /**
  * SQLite (Cloudflare D1) dialect schema for scheduled_messages.
  *
+ * 定时触发用的 `lease_until` / `retry_after` / `serialize_group` 三列分别是什么
+ * 意思，写在 Postgres 那份 schema 的文件头（adapters/schema.js）。
+ *
  * Differences from the Postgres schema (adapters/schema.js):
  *   - id: INTEGER PRIMARY KEY AUTOINCREMENT (vs SERIAL)
  *   - timestamps stored as TEXT ISO8601 UTC (vs TIMESTAMP WITH TIME ZONE)
@@ -11,7 +14,7 @@
  * Index entries mirror the Postgres INDEXES shape ({ name, sql, description,
  * critical }) so both adapters' initSchema() return the same index metadata.
  */
-export const SQLITE_TABLE_SQL: "\n  CREATE TABLE IF NOT EXISTS scheduled_messages (\n    id INTEGER PRIMARY KEY AUTOINCREMENT,\n    user_id TEXT NOT NULL,\n    uuid TEXT,\n    encrypted_payload TEXT NOT NULL,\n    message_type TEXT NOT NULL CHECK (message_type IN ('fixed', 'prompted', 'auto', 'instant')),\n    next_send_at TEXT NOT NULL,\n    lease_until TEXT,\n    status TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'sent', 'failed')),\n    retry_count INTEGER NOT NULL DEFAULT 0,\n    created_at TEXT NOT NULL,\n    updated_at TEXT NOT NULL\n  )\n";
+export const SQLITE_TABLE_SQL: "\n  CREATE TABLE IF NOT EXISTS scheduled_messages (\n    id INTEGER PRIMARY KEY AUTOINCREMENT,\n    user_id TEXT NOT NULL,\n    uuid TEXT,\n    encrypted_payload TEXT NOT NULL,\n    message_type TEXT NOT NULL CHECK (message_type IN ('fixed', 'prompted', 'auto', 'instant')),\n    next_send_at TEXT NOT NULL,\n    lease_until TEXT,\n    retry_after TEXT,\n    serialize_group TEXT,\n    status TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'sent', 'failed')),\n    retry_count INTEGER NOT NULL DEFAULT 0,\n    created_at TEXT NOT NULL,\n    updated_at TEXT NOT NULL\n  )\n";
 /**
  * 建表语句用的是 CREATE TABLE IF NOT EXISTS，已经存在的表不会被改动，所以
  * 后加的列要单独补。initSchema 每次都会跑一遍，列已经在了就跳过。

package/dist/{chunk-WAFOSZL3.mjs → chunk-B2FDV7YK.mjs}

@@ -8,6 +8,8 @@ var TABLE_SQL = `
     message_type VARCHAR(50) NOT NULL CHECK (message_type IN ('fixed', 'prompted', 'auto', 'instant')),
     next_send_at TIMESTAMP WITH TIME ZONE NOT NULL,
     lease_until TIMESTAMP WITH TIME ZONE,
+    retry_after TIMESTAMP WITH TIME ZONE,
+    serialize_group VARCHAR(64),
     status VARCHAR(50) NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'sent', 'failed')),
     retry_count INTEGER DEFAULT 0,
     created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
@@ -19,6 +21,16 @@ var MIGRATIONS = [
     name: "add_lease_until",
     sql: "ALTER TABLE scheduled_messages ADD COLUMN IF NOT EXISTS lease_until TIMESTAMP WITH TIME ZONE",
     description: "Task claim lease (2.6.0)"
+  },
+  {
+    name: "add_retry_after",
+    sql: "ALTER TABLE scheduled_messages ADD COLUMN IF NOT EXISTS retry_after TIMESTAMP WITH TIME ZONE",
+    description: "Retry backoff, held apart from the claim lease (2.6.0)"
+  },
+  {
+    name: "add_serialize_group",
+    sql: "ALTER TABLE scheduled_messages ADD COLUMN IF NOT EXISTS serialize_group VARCHAR(64)",
+    description: "Serialization group for runScheduledTick serializeBy (2.6.0)"
   }
 ];
 var INDEXES = [
@@ -56,6 +68,13 @@ var INDEXES = [
           WHERE uuid IS NOT NULL`,
     description: "UUID uniqueness guard",
     critical: true
+  },
+  {
+    name: "idx_serialize_group_lease",
+    sql: `CREATE INDEX IF NOT EXISTS idx_serialize_group_lease
+          ON scheduled_messages (serialize_group, lease_until)
+          WHERE serialize_group IS NOT NULL AND status = 'pending'`,
+    description: "Serialization group busy-check index (claimTask)"
   }
 ];
 var PUSH_SUBSCRIPTION_TABLE_SQL = `
@@ -85,6 +104,8 @@ var UPDATABLE_COLUMNS = /* @__PURE__ */ new Set([
   "message_type",
   "next_send_at",
   "lease_until",
+  "retry_after",
+  "serialize_group",
   "status",
   "retry_count",
   "created_at",