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

package/dist/adapters/d1.d.ts

@@ -0,0 +1,388 @@
+/**
+ * Create a D1 adapter from a Cloudflare D1 binding (env.DB).
+ * @param {{ prepare: (sql: string) => any }} db
+ * @returns {import('./interface.js').DbAdapter}
+ */
+export function createD1Adapter(db: {
+    prepare: (sql: string) => any;
+}): import("./interface.js").DbAdapter;
+export class D1Adapter {
+    /** @param {{ prepare: (sql: string) => any }} db - Cloudflare D1 binding */
+    constructor(db: {
+        prepare: (sql: string) => any;
+    });
+    /** @private */
+    private _db;
+    /** @private */
+    private _now;
+    /** @private */
+    private _iso;
+    /**
+     * 组一组带 `IN (...)` 的语句：值多到一条塞不下时，按 D1 的绑定参数上限切成
+     * 几条（见 chunkForBoundParams）。
+     *
+     * 只有拿得到事务的绑定才切。没有 batch() 的绑定（测试 shim、自定义适配器，
+     * 都不是真实 D1）原样发一条不切的语句：切批是为 D1 那条上限服务的，这类绑
+     * 定不受它约束，切了反倒会因为没有事务而多出一个「写一半」的中间态。
+     *
+     * @private
+     * @param {(placeholders: string) => string} buildSql - 拿占位符串（`?, ?, ?`）组 SQL
+     * @param {unknown[]} leadingParams - IN 列表之前的固定参数，按出现顺序
+     * @param {unknown[]} values - IN 列表里的全部值
+     * @returns {any[]} 已经 bind 好的语句
+     */
+    private _prepareInClauseStatements;
+    /**
+     * 带 `IN (...)` 的批量写，切成几条也仍然是一次原子操作。
+     *
+     * 一条语句本来天然原子，拆开之后这份保证得自己补回来，否则就会多出「只删掉
+     * 前 99 个」「只 ack 了前 98 条」这类比原问题更难查的中间态。D1 的 batch()
+     * 是隐式事务——其中一条失败，整批回滚——正好接住这件事。
+     *
+     * 一条就够时照旧单发，跟切批以前走的是同一条路，常见调用（一次三五个 id）
+     * 的行为一个字节都没变。
+     *
+     * @private
+     * @param {(placeholders: string) => string} buildSql
+     * @param {unknown[]} leadingParams
+     * @param {unknown[]} values
+     * @returns {Promise<number>} 各批影响行数之和
+     */
+    private _runInClauseWrite;
+    initSchema(): Promise<{
+        columnsCreated: number;
+        indexesCreated: number;
+        indexesFailed: number;
+        columns: any[];
+        indexes: ({
+            name: string;
+            status: string;
+            description: string;
+            critical: boolean;
+            error?: undefined;
+        } | {
+            name: string;
+            status: string;
+            description: string;
+            critical: boolean;
+            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;
+        updated_at: string;
+    }>;
+    deleteTaskById(taskId: any): Promise<boolean>;
+    deleteTaskByUuid(uuid: any, userId: any): Promise<boolean>;
+    getPendingTasks(limit?: number): Promise<any>;
+    /**
+     * 领取一条到点的任务：在 lease_until 上写下「这条归我管到什么时候」，
+     * 本次投递期间别的 tick 领不走它。
+     *
+     * 租约写在自己的列上，next_send_at 全程不动——那一列是用户设的触发时刻，
+     * 任务列表要读它、循环任务推进下一次也要拿它当基准。
+     *
+     * 两个 tick 抢同一行时只有一个能改到行，另一个拿到 changes = 0，据此跳过。
+     * WHERE 里的两个条件各管一件事：
+     *   - lease_until 为空或已过期：没人正在跑这条。领了任务的 tick 中途没了
+     *     也不会把行焊死，租约到期后自然可以被接手。
+     *   - next_send_at 等于读这行时看到的值：读出来之后用户又改了排期的话，
+     *     这一跳就不该再按旧时刻发。
+     *
+     * 不加一个 'sending' 状态来表达「正在跑」：建表语句里 status 有
+     * CHECK (status IN ('pending','sent','failed'))，加值要重建表。
+     *
+     * expectedNextSendAt 按读到的原样比对，不做时区归一化——老部署里可能还留
+     * 着非归一化写法的行（如 +08:00 结尾），归一化后反而对不上，那条任务会永
+     * 远领不到。
+     *
+     * 带 serializeGroup 时多一道分组门：同一分组里已经有别的行拿着未到期的租
+     * 约，这条就领不走（同一分组同时只跑一条）。判定和写租约在同一条 UPDATE
+     * 里完成，「先查再占」的空档天然不存在——两个 tick 同时来，只有一个改得动
+     * 行。分组门只看租约，不看 `retry_after`：等着重试的任务其实闲着，不该把
+     * 同分组的其他任务一起堵住。
+     *
+     * @param {number} taskId
+     * @param {string} expectedNextSendAt - 读这行时拿到的 next_send_at 原值
+     * @param {string|Date} leaseUntil - 租期末尾
+     * @param {string|null} [serializeGroup] - 串行分组标识；空表示不参与分组串行
+     * @returns {Promise<boolean>} true = 领到了；false = 别人正拿着租约、同分组
+     *   有任务正在跑、排期被改过、或行已不是 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
+     * newer overwrites. Values arrive pre-encrypted (the handler encrypts).
+     *
+     * `cleanups` 是删除项：在同一 batch 里先于 upsert 执行，`updated_at <= ?`
+     * 条件保证陈旧批次删不动更新写入的行。两种形态——
+     *   - `{ namespace, keyPrefix, updatedAt }` 删 key 前缀下的所有行，用来清掉
+     *     大值旧写入留下的切片行（见 lib/state-chunks.js）；
+     *   - `{ namespace, key, updatedAt }` 删这一个 key，用来删整条状态（前缀会
+     *     连带删掉同前缀的兄弟 key，删单条必须走精确匹配）。
+     *
+     * 删掉一整条状态就是这两种各来一条（切片行走前缀、根行走精确 key），
+     * `entries` 传空数组即可——见 lib/client-state-store.js。
+     *
+     * Uses D1's batch() — one network round trip for the whole set (implicit
+     * transaction). The client calls this endpoint inside its few-seconds
+     * background window, so N sequential round trips could eat the whole
+     * window. Bindings without batch() (e.g. the sqlite test shim, custom
+     * adapters) fall back to a sequential loop.
+     *
+     * @param {string} userId
+     * @param {Array<{ namespace: string, key: string, value: string, updatedAt: number }>} entries
+     * @param {Array<{ namespace: string, key?: string, keyPrefix?: string, updatedAt: number }>} [cleanups]
+     * @returns {Promise<{ upserted: number, skipped: number, outcomes: boolean[] }>}
+     *   `outcomes[i]` 对应 entries[i] 是否真的写入（changes > 0）。
+     */
+    upsertClientState(userId: string, entries: Array<{
+        namespace: string;
+        key: string;
+        value: string;
+        updatedAt: number;
+    }>, cleanups?: Array<{
+        namespace: string;
+        key?: string;
+        keyPrefix?: string;
+        updatedAt: number;
+    }>): Promise<{
+        upserted: number;
+        skipped: number;
+        outcomes: boolean[];
+    }>;
+    /**
+     * All entries of one namespace (values still encrypted).
+     *
+     * @param {string} userId
+     * @param {string} namespace
+     * @returns {Promise<Array<{ namespace: string, key: string, value: string, updated_at: number }>>}
+     */
+    getClientState(userId: string, namespace: string): Promise<Array<{
+        namespace: string;
+        key: string;
+        value: string;
+        updated_at: number;
+    }>>;
+    /**
+     * Wipe every entry of this user.
+     *
+     * @param {string} userId
+     * @returns {Promise<number>} rows deleted
+     */
+    clearClientState(userId: string): Promise<number>;
+    /**
+     * 这个用户当前登记的推送订阅（密文原样返回，解密在上层）。
+     *
+     * @param {string} userId
+     * @returns {Promise<{ subscription: string, updated_at: number }|null>}
+     */
+    getPushSubscription(userId: string): 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>;
+    /**
+     * 批量 upsert 这个用户的凭据（value 已是密文，加密在上层）。已存在的行
+     * 覆盖 encrypted_value 并刷 updated_at，created_at 保留首次写入的时刻。
+     *
+     * @param {string} userId
+     * @param {Array<{ credId: string, encryptedValue: string }>} entries
+     * @returns {Promise<number>} 实际写入/覆盖的行数
+     */
+    upsertLlmCredentials(userId: string, entries: Array<{
+        credId: string;
+        encryptedValue: string;
+    }>): Promise<number>;
+    /**
+     * 按 cred_id 批量读这个用户的凭据行（`encrypted_value` 是密文，解密在上
+     * 层）。排程时的存在性检查和 fire 时的解析共用这一个口。
+     *
+     * @param {string} userId
+     * @param {string[]} credIds
+     * @returns {Promise<Array<{ cred_id: string, encrypted_value: string, updated_at: string }>>}
+     */
+    getLlmCredentials(userId: string, credIds: string[]): Promise<Array<{
+        cred_id: string;
+        encrypted_value: string;
+        updated_at: string;
+    }>>;
+    /**
+     * 这个用户名下所有凭据的对账清单（只有 cred_id 和 updated_at，密文不出
+     * 这个方法）。按 cred_id 排序，输出稳定。
+     *
+     * @param {string} userId
+     * @returns {Promise<Array<{ cred_id: string, updated_at: string }>>}
+     */
+    listLlmCredentials(userId: string): Promise<Array<{
+        cred_id: string;
+        updated_at: string;
+    }>>;
+    /**
+     * 删凭据。`credIds` 传数组删指定那几行；传 null 删这个用户的全部
+     * （「清空云端数据」用）。
+     *
+     * @param {string} userId
+     * @param {string[]|null} credIds
+     * @returns {Promise<number>} 删掉的行数
+     */
+    deleteLlmCredentials(userId: string, credIds?: string[] | null): Promise<number>;
+    /**
+     * 发送前把这一批 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/factory.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Adapter Factory
+ *
+ * Creates a database adapter instance based on the supplied configuration.
+ *
+ * @typedef {'neon'|'pg'} DriverName
+ *
+ * @typedef {Object} AdapterConfig
+ * @property {DriverName} driver  - Which database driver to use.
+ * @property {string}     connectionString - Database connection URL.
+ */
+/**
+ * Create a database adapter.
+ *
+ * @param {AdapterConfig} config
+ * @returns {Promise<import('./interface.js').DbAdapter>}
+ */
+export function createAdapter(config: AdapterConfig): Promise<import("./interface.js").DbAdapter>;
+/**
+ * Adapter Factory
+ *
+ * Creates a database adapter instance based on the supplied configuration.
+ */
+export type DriverName = "neon" | "pg";
+/**
+ * Adapter Factory
+ *
+ * Creates a database adapter instance based on the supplied configuration.
+ */
+export type AdapterConfig = {
+    /**
+     * - Which database driver to use.
+     */
+    driver: DriverName;
+    /**
+     * - Database connection URL.
+     */
+    connectionString: string;
+};

package/dist/adapters/interface.d.ts

@@ -0,0 +1,265 @@
+export type TaskRow = {
+    id: number;
+    user_id: string;
+    uuid: string;
+    encrypted_payload: string;
+    message_type: string;
+    next_send_at: string;
+    status: string;
+    retry_count: number;
+    created_at: string;
+    updated_at: string;
+};
+export type InsertTaskParams = {
+    user_id: string;
+    uuid: string;
+    encrypted_payload: string;
+    next_send_at: string;
+    message_type: string;
+};
+export type InitSchemaResult = {
+    columnsCreated: number;
+    indexesCreated: number;
+    indexesFailed: number;
+    columns: any[];
+    indexes: any[];
+};
+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).
+     */
+    dropSchema: () => Promise<void>;
+    /**
+     *   Insert a new task row and return the created record.
+     */
+    createTask: (params: InsertTaskParams) => Promise<TaskRow>;
+    /**
+     *   Fetch a single pending task by uuid + user_id.
+     */
+    getTaskByUuid: (uuid: string, userId: string) => Promise<TaskRow | null>;
+    /**
+     *   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`（含写
+     *   null）：投递收尾时 runScheduledTick 用前者把租约放掉，用后者写/清投递失败
+     *   的退避时刻。
+     */
+    updateTaskById: (taskId: number, updates: any) => Promise<TaskRow | null>;
+    /**
+     *   Update a pending task's encrypted_payload (and optional index fields) by uuid + user_id.
+     */
+    updateTaskByUuid: (uuid: string, userId: string, encryptedPayload: string, extraFields?: any) => Promise<TaskRow | null>;
+    /**
+     *   Delete a task by numeric id. Returns true if a row was affected.
+     */
+    deleteTaskById: (taskId: number) => Promise<boolean>;
+    /**
+     *   Delete a task by uuid + user_id. Returns true if a row was affected.
+     */
+    deleteTaskByUuid: (uuid: string, userId: string) => Promise<boolean>;
+    /**
+     *   Fetch pending tasks whose next_send_at <= NOW(), ordered ASC.
+     *   跳过两种还不该动的行：租约没到期的（`lease_until`，有人正在跑）、退避没到
+     *   点的（`retry_after`，上次投递失败在等重试）。两列都是空或已过期才算待发。
+     */
+    getPendingTasks: (limit?: number) => Promise<TaskRow[]>;
+    /**
+     * 领取一条到点的任务，返回是否领到。cron 每分钟一跳而一次投递可能跑几分
+     * 钟，runScheduledTick 靠它保证同一行同时只被一个 tick 跑。
+     * 三个条件同时成立才领得走：行仍是 pending；`lease_until` 为空或已过期
+     * （没别人正在跑）；`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, serializeGroup?: string | null) => Promise<boolean>;
+    /**
+     *   List tasks for a user with optional filters and pagination.
+     */
+    listTasks: (userId: string, opts: {
+        status?: string;
+        limit?: number;
+        offset?: number;
+    }) => Promise<{
+        tasks: TaskRow[];
+        total: number;
+    }>;
+    /**
+     *   Delete completed / failed tasks older than `days` (default 7).
+     */
+    cleanupOldTasks: (days?: number) => Promise<number>;
+    /**
+     *   Return the status string of a task (used to distinguish 404 from 409).
+     */
+    getTaskStatus: (uuid: string, userId: string) => Promise<string | null>;
+    /**
+     * (optional; single-user/D1 only) Batch upsert of client state, last-write-wins on updatedAt.
+     * `cleanups` 先于 upsert 在同一事务里删旧行，两种形态：带 `keyPrefix` 的按 key 前缀删（清理大值
+     * 旧写入留下的切片行，见 lib/state-chunks.js），带 `key` 的删这一个 key（删整条状态；前缀会连带
+     * 删掉同前缀的兄弟 key）。两种都只删 `updated_at <= updatedAt` 的行。自定义 adapter 忽略前缀形态
+     * 只损失存储卫生；忽略精确 key 形态则删不掉状态，`ctx.writeState()` 的删除会失效。
+     * `outcomes` 逐条报告 entries[i] 是否真的写入（缺席时调用方按物理行计数兜底）。
+     */
+    upsertClientState?: (userId: string, entries: Array<{
+        namespace: string;
+        key: string;
+        value: string;
+        updatedAt: number;
+    }>, cleanups?: Array<{
+        namespace: string;
+        key?: string;
+        keyPrefix?: string;
+        updatedAt: number;
+    }>) => Promise<{
+        upserted: number;
+        skipped: number;
+        outcomes?: boolean[];
+    }>;
+    /**
+     * (optional; single-user/D1 only) All entries of one namespace; values still encrypted.
+     */
+    getClientState?: (userId: string, namespace: string) => Promise<Array<{
+        namespace: string;
+        key: string;
+        value: string;
+        updated_at: number;
+    }>>;
+    /**
+     * (optional; single-user/D1 only) Delete every entry of this user; returns rows deleted.
+     */
+    clearClientState?: (userId: string) => Promise<number>;
+    /**
+     * 这个用户当前登记的 Web Push 订阅（`subscription` 是密文，解密在上层）。没有登记过 → null。
+     * 一个用户一份：任务行不携带订阅，到点投递时读这里。
+     */
+    getPushSubscription?: (userId: string) => Promise<{
+        subscription: string;
+        updated_at: number;
+    } | null>;
+    /**
+     * 覆盖写这个用户的订阅（`updatedAt` 是 epoch 毫秒）。没有 last-write-wins 比较——
+     * 客户端拿到的新订阅永远比旧的有效，旧的那份只会 410。
+     */
+    upsertPushSubscription?: (userId: string, encryptedSubscription: string, updatedAt: number) => Promise<boolean>;
+    /**
+     * 删掉这个用户的订阅；返回是否真的删掉了一行。
+     *
+     * 上面三个方法要么都实现、要么都不实现：缺任何一个，`PUT/GET/DELETE
+     * /push-subscription` 返回 501，`POST /schedule-message` 也会拒绝建任务
+     * （建了也永远发不出去）。内置的 D1 / pg / neon 适配器都实现了。
+     */
+    deletePushSubscription?: (userId: string) => Promise<boolean>;
+    /**
+     * 批量覆盖写这个用户的 LLM 凭据（`encryptedValue` 是密文，加密在上层）。
+     * 已存在的行覆盖 encrypted_value 并刷 updated_at。返回实际写入/覆盖的行数。
+     */
+    upsertLlmCredentials?: (userId: string, entries: Array<{
+        credId: string;
+        encryptedValue: string;
+    }>) => Promise<number>;
+    /**
+     * 按 cred_id 批量读凭据行（密文原样返回）。排程时的存在性检查和 fire 时的
+     * 解析共用这一个口。
+     */
+    getLlmCredentials?: (userId: string, credIds: string[]) => Promise<Array<{
+        cred_id: string;
+        encrypted_value: string;
+        updated_at: string;
+    }>>;
+    /**
+     * 这个用户名下所有凭据的对账清单（只有 cred_id 和 updated_at，密文不出这个
+     * 方法）。按 cred_id 排序。
+     */
+    listLlmCredentials?: (userId: string) => Promise<Array<{
+        cred_id: string;
+        updated_at: string;
+    }>>;
+    /**
+     * 删凭据：数组删指定那几行，null 删全部。返回删掉的行数。
+     *
+     * llm_credentials 四个方法要么都实现、要么都不实现：缺任何一个，
+     * `PUT/GET/DELETE /llm-credentials` 返回 501，带 `credRefs` 的
+     * `POST /schedule-message` 也会被拒。内置的 D1 / pg / neon 适配器都实现了。
+     */
+    deleteLlmCredentials?: (userId: string, credIds: string[] | null) => Promise<number>;
+    /**
+     * （可选）投递期间的租约续期（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>;
+};