@rei-standard/amsg-server 2.6.0-next.9 → 3.0.0

package/dist/adapters/d1.d.ts

@@ -0,0 +1,693 @@
+/**
+ * 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;
+    /** A complete management implementation needs real transactional batches. */
+    get cloudDataManagement(): boolean;
+    _cloudGuardPredicate(userId: any, guard: any): {
+        sql: string;
+        args: any[];
+    };
+    _cloudBatch(statements: any, userId: any, guards?: any[], metadata?: Map<any, any>): Promise<any[]>;
+    getCloudResourceMetadata(userId: any, resourceKey: any): Promise<any>;
+    listCloudResourceRows(userId: any): Promise<{
+        gaps: any[];
+    }>;
+    _cloudRecord(row: any): Promise<{
+        id: any;
+        userId: any;
+        kind: any;
+        data: any;
+        updatedAt: any;
+    }>;
+    putCloudDataRecord(userId: any, kind: any, id: any, data: any, { idempotencyKey, createOnly, leaseToken, work }?: {
+        idempotencyKey?: any;
+        createOnly?: boolean;
+    }): Promise<{
+        id: any;
+        userId: any;
+        kind: any;
+        data: any;
+        updatedAt: any;
+    }>;
+    getCloudDataRecord(userId: any, kind: any, id: any): Promise<{
+        id: any;
+        userId: any;
+        kind: any;
+        data: any;
+        updatedAt: any;
+    }>;
+    getCloudDataRecordByIdempotency(userId: any, kind: any, idempotencyKey: any): Promise<{
+        id: any;
+        userId: any;
+        kind: any;
+        data: any;
+        updatedAt: any;
+    }>;
+    _cloudRecordForList(row: any): Promise<{
+        id: any;
+        userId: any;
+        kind: any;
+        data: any;
+        updatedAt: any;
+    }>;
+    listCloudDataRecords(userId: any, kind: any): Promise<any[]>;
+    listCloudDataRecordsAcrossUsers(kind: any): Promise<any[]>;
+    claimCloudDataRecord(userId: any, kind: any, id: any, leaseMs: any, leaseToken?: any): Promise<boolean>;
+    releaseCloudDataRecord(userId: any, kind: any, id: any, leaseToken: any): Promise<void>;
+    renewCloudDataRecordLease(userId: any, kind: any, id: any, leaseMs: any, leaseToken: any): Promise<boolean>;
+    deleteCloudDataRecord(userId: any, kind: any, id: any): Promise<boolean>;
+    cleanupCloudDataRecords(kind: any, beforeMs: any): Promise<any>;
+    listDueCloudDataOperations(now?: number, limit?: number): Promise<any[]>;
+    cleanupExpiredCloudDataRecords(now?: number, limit?: number): Promise<any>;
+    getCloudMaintenanceBatch(name: any, table: any, limit?: number): Promise<{
+        rows: any[];
+        completed: boolean;
+        upperBound?: undefined;
+        cursor?: undefined;
+    } | {
+        rows: any;
+        upperBound: any;
+        cursor: any;
+        completed: boolean;
+    }>;
+    finishCloudMaintenanceBatch(name: any, cursor: any, completed: any): Promise<void>;
+    /**
+     * Index a whole repair batch in one statement. Never overwrites an existing schedule, and
+     * skips a record that was rewritten after the batch was read.
+     */
+    indexCloudDataRecordWorkBatch(entries: any): Promise<void>;
+    /** Move an indexed record's schedule, unless the record was rewritten since the caller read it. */
+    rescheduleCloudDataRecordWork(userId: any, kind: any, id: any, work: any, expectedWriteToken?: any): Promise<boolean>;
+    readCloudMaintenanceRecord(row: any): Promise<{
+        id: any;
+        userId: any;
+        kind: any;
+        data: any;
+        updatedAt: any;
+    }>;
+    repairCloudResourceMetadata(limit?: number): Promise<void>;
+    /** One explicit repair, or a bounded upgrade batch; never called as a recurring sweep. */
+    cleanupCloudResourceMetadata(userId?: any, range?: any): Promise<any>;
+    listCloudOwners(userId: any): Promise<any>;
+    getCloudOwner(userId: any, owner: any): Promise<{
+        active: boolean;
+        generation: any;
+        updatedAt: any;
+    }>;
+    setCloudOwnerActive(userId: any, owner: any, active: any, expectedGeneration: any): Promise<{
+        active: boolean;
+        generation: any;
+        updatedAt: any;
+    }>;
+    isCloudOwnerGuardValid(userId: any, guard: any): Promise<boolean>;
+    /** Delete only the exact physical snapshot; no untrusted SQL identifiers. */
+    deleteCloudResourceRows(userId: any, locators: any, { operationId, leaseToken }?: {}): Promise<{
+        deleted: number;
+        changed: number;
+    }>;
+    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[], triggers: string[] }>}
+     */
+    describeSchema(): Promise<{
+        tables: Record<string, string[]>;
+        indexes: string[];
+        triggers: string[];
+    }>;
+    dropSchema(): Promise<void>;
+    createTask(params: any, cloudGuard?: 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, cloudGuard?: any): 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, cloudGuard?: any): Promise<any>;
+    /**
+     * 按 uuid 改一条 pending 任务（PUT /update-message、fire hook 的 renewTask）。
+     *
+     * 改排期（extraFields 里带 next_send_at）时多一道租约门：这条任务正被一次投递
+     * 占着的话不改，返回 null。投递收尾会按自己领取时看到的排期推进下一次（一次性
+     * 任务干脆标成已发送），这期间写进去的新时刻随后就被盖掉，接口却已经回了成功
+     * ——用户以为改期生效了，实际什么都没留下。正文这类字段不受这道门约束：它们
+     * 只影响以后的触发，收尾那边本来就不会覆盖（见 run-tick 的收尾守卫）。
+     */
+    updateTaskByUuid(uuid: any, userId: any, encryptedPayload: any, extraFields: any, cloudGuard?: 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, cloudGuard?: any): Promise<boolean>;
+    /**
+     * 投递期间的租约续期（run-tick 的心跳用）。只在行仍是 pending 且确实持有
+     * 租约（lease_until 非空）时生效——收尾把租约放掉之后，迟到的心跳不会把
+     * 租约复活。
+     *
+     * @param {number} taskId
+     * @param {string|Date} leaseUntil - 新的租期末尾
+     * @returns {Promise<boolean>} true = 续上了
+     */
+    renewTaskLease(taskId: number, leaseUntil: string | Date, cloudGuard?: any): 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).
+     *
+     * 例外是「来自未来」的行：`updated_at` 晚于服务端当前时间的行一律放行覆盖。
+     * 比较值是客户端自己报的时间戳，设备时钟只要领先过真实时间（用户改过系统
+     * 时间、时区或日期误操作），那一刻同步上来的行就带着一个还没到的时刻；之后
+     * 这台设备发什么都比它「旧」，条件写全被无声跳过，云端那行要等真实时间追上
+     * 去才解得开——客户端删本地数据、重装都碰不到它。合法写入不可能来自未来，
+     * 所以这种行按脏数据处理：服务端的钟是可信的那一个，拿它当判据放行。一次
+     * 正常写入就把 `updated_at` 拉回现实，之后旧不盖新照常生效。
+     *
+     * `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]
+     * @param {number} [now] - 服务端当前时刻（epoch 毫秒），判定「这行来自未来」用的
+     *   就是它。调用方（lib/client-state-store.js）传下来，测试可以钉住一个假时钟；
+     *   自定义调用方不传时退回本机时钟。
+     * @returns {Promise<{ upserted: number, skipped: number, outcomes: boolean[], cleanupOutcomes?: Array<boolean|null> }>}
+     *   `outcomes[i]` 对应 entries[i] 是否真的写入（changes > 0）。
+     *   `cleanupOutcomes[i]` 对应 cleanups[i]（传了 cleanups 才有）：精确 key 形态
+     *   回 `true` = 这个 key 的行已经不在（删掉了，或本来就没有）、`false` = 行还在
+     *   （库里那行更新，删除被条件写拦下）；前缀形态不探测，回 `null`。
+     */
+    upsertClientState(userId: string, entries: Array<{
+        namespace: string;
+        key: string;
+        value: string;
+        updatedAt: number;
+    }>, cleanups?: Array<{
+        namespace: string;
+        key?: string;
+        keyPrefix?: string;
+        updatedAt: number;
+    }>, now?: number, cloudGuard?: any): Promise<{
+        upserted: number;
+        skipped: number;
+        outcomes: boolean[];
+        cleanupOutcomes?: Array<boolean | null>;
+    }>;
+    /**
+     * 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;
+    }>>;
+    /**
+     * 例行清理：把指定命名空间下太久没更新的条目删掉（run-tick 每跳顺手调，
+     * 宿主配了 `clientStateTtl` 才会调）。
+     *
+     * 不限用户——「这个命名空间只留最近 N 天」是命名空间级的约定，单用户部署
+     * 下也就是这一个用户的行。指令由 lib/client-state-store.js 的
+     * `planClientStateCleanup` 算好（含大值切片所在的保留命名空间），这里只负
+     * 责照着删。
+     *
+     * @param {Array<{ namespace: string, updatedBefore: number }>} targets
+     *   `updatedBefore` 是 epoch 毫秒，与 `updated_at` 列同一把尺子。
+     * @returns {Promise<number>} 删掉的行数
+     */
+    cleanupClientState(targets?: Array<{
+        namespace: string;
+        updatedBefore: number;
+    }>): Promise<number>;
+    /**
+     * Wipe every entry of this user.
+     *
+     * @param {string} userId
+     * @returns {Promise<number>} rows deleted
+     */
+    clearClientState(userId: string): Promise<number>;
+    /**
+     * 这个用户名下有哪些命名空间，各自几条、占多少字节、最后更新是什么时候
+     * （宿主对账「云端到底存了什么」用）。
+     *
+     * `foldPrefix` 传进来的是大值分块那个保留命名空间的前缀（见
+     * lib/state-chunks.js）：以它开头的行不单独成一个命名空间，而是折算进
+     * 去掉前缀之后的那个原命名空间——保留命名空间是库的存储实现细节，宿主眼里
+     * 那些切片行就是原命名空间占掉的地方。折算口径：
+     *   - `byte_size` / `updated_at` 算进去（存储确实占着、写入确实发生过）；
+     *   - `entry_count` 不算（切片是一个逻辑条目的几段，不是几个条目）。
+     * 不传 `foldPrefix` = 不折算，保留命名空间按普通命名空间原样列出来。
+     *
+     * 前缀由调用方传、不由适配器自己知道：分块是 lib 层的约定，适配器只照着折。
+     *
+     * 折算写在 SQL 里而不是取回来在 JS 里合，是因为有 `limit`：保留命名空间以
+     * \u001f 开头，BINARY 排序下排在所有正常命名空间前面，先取 limit 条再折算
+     * 的话额度会被切片命名空间吃光，正常命名空间一条都露不出来。
+     *
+     * `LENGTH(CAST(value AS BLOB))` 数的是字节不是字符——TEXT 上的 `LENGTH()`
+     * 按字符算，密文虽然是 ASCII 十六进制、两者相同，但换个存法就悄悄差一截。
+     *
+     * 这条语句要把该用户的 client_state 全扫一遍（GROUP BY 本来就得看每一行），
+     * 所以没为它单独加索引：它是宿主按需点开的对账口，不在 cron 路径上。别把它
+     * 塞进每分钟跑的东西里（理由见 adapters/schema.sqlite.js 的 CLIENT_STATE_INDEXES）。
+     *
+     * @param {string} userId
+     * @param {{ limit?: number, foldPrefix?: string|null }} [opts]
+     * @returns {Promise<Array<{ namespace: string, entry_count: number, byte_size: number, updated_at: number }>>}
+     *   按 namespace 升序，最多 `limit` 条。
+     */
+    listClientStateNamespaces(userId: string, { limit, foldPrefix }?: {
+        limit?: number;
+        foldPrefix?: string | null;
+    }): Promise<Array<{
+        namespace: string;
+        entry_count: number;
+        byte_size: number;
+        updated_at: number;
+    }>>;
+    /**
+     * 把这几个命名空间下这个用户的行一次删光（一次 batch = 一次事务）。
+     *
+     * 调用方传的是「原命名空间 + 它的切片保留命名空间」两个（见
+     * lib/state-chunks.js 的 chunkNamespaceFor）：只删前者的话，大值那几行切片
+     * 留在库里成孤儿——读不出来、也不会被别的路径清掉。哪些命名空间算一组由调
+     * 用方决定，适配器只负责它们在同一个事务里删完。
+     *
+     * 条件是 `user_id = ? AND namespace = ?`，吃的是主键
+     * (user_id, namespace, key) 的前两列，不扫表。
+     *
+     * @param {string} userId
+     * @param {string[]} namespaces
+     * @returns {Promise<number>} 删掉的行数合计（含切片行）
+     */
+    deleteClientStateNamespaces(userId: string, namespaces: 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;
+    }>, cloudGuard?: any): 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>;
+    /**
+     * 按 cred_id 前缀删这个用户的凭据（宿主按角色清理：`char:<charId>/` 一把清
+     * 掉该角色名下的 chat / instant / emotion 几行）。
+     *
+     * **不用 LIKE。** 两条 D1 的限制在这儿各埋一个雷：
+     *   - LIKE / GLOB 的 pattern 在 D1 上最长 50 字节（SQLite 默认 50000，官方文
+     *     档没写这一条）。`char:<uuid>/` 就是 42 字节，前缀里再多点东西、或者
+     *     cred_id 用上契约允许的 128 字符，pattern 当场超限，整条语句报
+     *     `LIKE or GLOB pattern too complex`——本地 better-sqlite3 上永远复现不
+     *     了，只有真实 D1 才炸。
+     *   - 退一步「先 SELECT 出匹配的 cred_id 再按 id 批量删」也不是好路：单条语
+     *     句最多 100 个绑定参数，得自己切批，还平白多一个来回和一个「查完到删完
+     *     之间又写进来一行」的窗口。
+     * 走字典序范围（`cred_id >= 前缀 AND cred_id < 上界`）两条都绕开了：没有长度
+     * 上限，前缀里的 `%` `_` `\` 只是普通字符，一条语句三个绑定参数，而且直接吃
+     * (user_id, cred_id) 主键索引。上界算法见本文件顶部的 prefixRangeEnd。
+     *
+     * 前缀没有字典序上界时（prefixRangeEnd 返回空串，实际用不到——见那个函数的
+     * 说明）范围条件一行都匹配不上，删 0 行。宁可少删，也不能把别人的行带走。
+     *
+     * @param {string} userId
+     * @param {string} credIdPrefix - 非空前缀，空串由上层拒掉（空前缀 = 删全部，
+     *   那是 `deleteLlmCredentials(userId, null)` 的活儿，不能从这个口误伤进来）
+     * @returns {Promise<number>} 删掉的行数
+     */
+    deleteLlmCredentialsByPrefix(userId: string, credIdPrefix: string): 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;
+    }>, cloudGuard?: any): 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>;
+    /**
+     * 把这一批还没发出去的行删掉（任务投递到一半被取消 / 顶替时用）。
+     *
+     * 只删 delivered_at 仍为 NULL 的行：已经推给设备的那几条撤不回来，行留着让
+     * 客户端照常 ack。已 ack 的行更不动。
+     *
+     * @param {string} userId
+     * @param {string[]} messageIds
+     * @returns {Promise<number>} 删掉的行数
+     */
+    discardOutboxMessages(userId: string, messageIds: string[]): Promise<number>;
+    /**
+     * 把某条任务名下还没发出去的行一次删掉（取消 / 顶替时的 outbox 清理）。
+     *
+     * 判据与 discardOutboxMessages 相同：只删 delivered_at 与 acked_at 均为
+     * NULL 的行——已经推给设备 / 已 ack 的照旧留着。按 task_uuid 直删是为了不
+     * 受未 ack 积压量的影响：靠翻页扫描挑行的话，积压一大这条任务的行就落在
+     * 扫描上限之外（见 lib/outbox-store.js 的 discardUndeliveredPushesForTask）。
+     *
+     * @param {string} userId
+     * @param {string} taskUuid
+     * @returns {Promise<number>} 删掉的行数
+     */
+    discardUndeliveredOutboxForTask(userId: string, taskUuid: string): Promise<number>;
+    /**
+     * 某条任务名下、某个时刻之后落的行，**不论投递 / ack 状态**（payload 仍是密文）。
+     *
+     * 给「生成成功之后推送失败、重试只补推送」那条路用（见 lib/outbox-store.js 的
+     * findCommittedBatch）：重试那一跳先来这里看这次触发的整批是不是已经落定了。
+     * 已 ack 的行也要读——客户端在两次重试之间把整批补收并 ack 了，同样说明这次
+     * 触发的内容已经生成过，不该再生成一份。
+     *
+     * `+user_id` 的一元加号是故意的：它让这一项不参与选索引，查询改走
+     * idx_outbox_created 按 created_at 收窄。否则 SQLite 会挑 (user_id, message_id)
+     * 的唯一约束索引，单用户部署下 user_id 对每一行都成立，等于把整个收件箱扫一遍
+     * （D1 按扫过的行数计费）。idx_outbox_created 不在时照样查得出来，只是退回扫表。
+     *
+     * @param {string} userId
+     * @param {string} taskUuid
+     * @param {{ sinceMs?: number, limit?: number }} [options] - sinceMs：只要
+     *   created_at ≥ 它的行（epoch 毫秒）；limit：最多读几行（默认 500）
+     * @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, acked_at: number|null }>>}
+     */
+    listOutboxForTask(userId: string, taskUuid: string, { sinceMs, limit }?: {
+        sinceMs?: 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;
+        acked_at: number | null;
+    }>>;
+    /**
+     * 未 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 的行：数组删指定那几条，传 null 删这个用户的全部。
+     *
+     * 跟 `discardOutboxMessages` 是两件事：那个只撤「还没发出去的」，是取消 / 顶
+     * 替时的收尾；这个不看 delivered_at / acked_at，是宿主的清理口（对完账之后
+     * 把某几条、或者整个收件箱清掉）。在此之前 message_outbox 只能等 cron 的
+     * TTL（已签收 7 天 / 任何行 28 天）自己老化。
+     *
+     * 数组形态走 `_runInClauseWrite`：D1 单条语句最多 100 个绑定参数，`user_id`
+     * 占掉 1 个，所以一批最多 99 个 id，多了自动切批、整组仍在一个事务里（切开
+     * 之后「只删掉前 99 个」那种中间态比原问题更难查）。
+     *
+     * @param {string} userId
+     * @param {string[]|null} messageIds - null = 这个用户的全部
+     * @returns {Promise<number>} 删掉的行数
+     */
+    deleteOutboxMessages(userId: string, messageIds?: string[] | null): 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>;
+}