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

package/dist/index.mjs

@@ -1,11 +1,38 @@
 import {
+  CORS_ALLOW_HEADERS,
+  CORS_ALLOW_METHODS,
+  CRED_ID_MAX_LENGTH,
+  CRED_PUT_BATCH_MAX,
+  CRED_REFS_MAX_ENTRIES,
+  CRED_ROWS_PER_USER_MAX,
+  DEFAULT_CLAIM_LEASE_MS,
+  DEFAULT_HEARTBEAT_LEASE_TTL_MS,
+  DEFAULT_LEASE_HEARTBEAT_MS,
+  DEFAULT_MAX_DELIVERY_RETRIES,
+  DEFAULT_MAX_REQUEST_BODY_BYTES,
+  DEFAULT_MAX_SCHEDULED_TASKS_PER_FIRE,
+  DEFAULT_MAX_TOOL_ITERATIONS,
+  DEFAULT_TOTAL_TIMEOUT_MS,
+  DeploymentConfigError,
+  MAX_DEFER_AFTER_MS,
   MAX_PUSH_PAYLOAD_BYTES,
+  MAX_TASK_PAYLOAD_BYTES,
+  MIN_SCHEDULE_LEAD_MS,
+  NonRetryableError,
+  PUSH_ENVELOPE_RESERVED_BYTES,
+  SCHEMA_VERSION,
   WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES,
   WEB_PUSH_MAX_BODY_BYTES,
+  advanceOccurrence,
+  base64UrlToBytes,
+  bytesToBase64Url,
   createCancelMessageHandler,
   createD1Adapter,
+  createGetMessageHandler,
   createGetUserKeyHandler,
+  createLlmCredentialsHandler,
   createMessagesHandler,
+  createPushSubscriptionHandler,
   createScheduleMessageHandler,
   createSingleUserCloudflareWorker,
   createSingleUserServer,
@@ -15,19 +42,39 @@ import {
   decryptPayload,
   deriveUserEncryptionKey,
   encryptForStorage,
+  ensureSchema,
   getHeader,
+  getSchemaVersion,
+  hasChatCredRef,
+  isNonRetryableError,
+  isValidCredId,
   isValidISO8601,
+  isValidTimeZoneId,
   isValidUUID,
   isValidUUIDv4,
   isValidUrl,
   measurePushPayload,
+  nextFutureOccurrence,
   parseJsonBody,
+  planNextOccurrence,
+  readRequestBody,
+  resolveLlmCredential,
   runScheduledTick,
+  runTask,
+  sanitizeErrorSummary,
+  summarizeErrorCause,
+  supportsLlmCredentialsStore,
+  timingSafeEqualBytes,
+  utf8,
+  utf8Decode,
   validateAvatarUrl,
+  validateCredRefs,
+  validateCredValue,
   validateLlmMessagesArray,
   validateScheduleMessagePayload,
   validateSplitPattern
-} from "./chunk-S6O3MXQO.mjs";
+} from "./chunk-RL7V7VSS.mjs";
+import "./chunk-GN44PST5.mjs";
 
 // src/server/adapters/factory.js
 async function createAdapter(config) {
@@ -43,11 +90,11 @@ async function createAdapter(config) {
   }
   switch (config.driver) {
     case "neon": {
-      const { NeonAdapter } = await import("./neon-QJ7KYHEX.mjs");
+      const { NeonAdapter } = await import("./neon-GKLT4UY3.mjs");
       return new NeonAdapter(config.connectionString);
     }
     case "pg": {
-      const { PgAdapter } = await import("./pg-DFJSFOJQ.mjs");
+      const { PgAdapter } = await import("./pg-J4YXRQP5.mjs");
       return new PgAdapter(config.connectionString);
     }
     default:
@@ -216,14 +263,6 @@ function createSendNotificationsHandler(ctx) {
 // src/server/tenant/blob-store.js
 import { createCipheriv, createDecipheriv, createHash, randomBytes } from "crypto";
 var inMemoryNamespaces = /* @__PURE__ */ new Map();
-function base64UrlEncode(input) {
-  return Buffer.from(input).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
-}
-function base64UrlDecode(input) {
-  const normalized = input.replace(/-/g, "+").replace(/_/g, "/");
-  const padLength = (4 - normalized.length % 4) % 4;
-  return Buffer.from(normalized + "=".repeat(padLength), "base64");
-}
 function getKekBuffer(kek) {
   const value = String(kek || "").trim();
   if (!value) {
@@ -237,16 +276,16 @@ function encryptConfig(config, kekBuffer) {
   const plaintext = Buffer.from(JSON.stringify(config), "utf8");
   const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
   const authTag = cipher.getAuthTag();
-  return `v1.${base64UrlEncode(iv)}.${base64UrlEncode(authTag)}.${base64UrlEncode(ciphertext)}`;
+  return `v1.${bytesToBase64Url(iv)}.${bytesToBase64Url(authTag)}.${bytesToBase64Url(ciphertext)}`;
 }
 function decryptConfig(encrypted, kekBuffer) {
   const parts = String(encrypted || "").split(".");
   if (parts.length !== 4 || parts[0] !== "v1") {
     throw new Error("INVALID_TENANT_CONFIG");
   }
-  const iv = base64UrlDecode(parts[1]);
-  const authTag = base64UrlDecode(parts[2]);
-  const ciphertext = base64UrlDecode(parts[3]);
+  const iv = base64UrlToBytes(parts[1]);
+  const authTag = base64UrlToBytes(parts[2]);
+  const ciphertext = base64UrlToBytes(parts[3]);
   const decipher = createDecipheriv("aes-256-gcm", kekBuffer, iv);
   decipher.setAuthTag(authTag);
   const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8");
@@ -312,17 +351,9 @@ function createTenantBlobStore(options) {
 import { createHash as createHash2, randomBytes as randomBytes2, randomUUID } from "crypto";
 
 // src/server/tenant/token.js
-import { createHmac, timingSafeEqual } from "crypto";
-function base64UrlEncode2(input) {
-  return Buffer.from(input).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
-}
-function base64UrlDecode2(input) {
-  const normalized = input.replace(/-/g, "+").replace(/_/g, "/");
-  const padLength = (4 - normalized.length % 4) % 4;
-  return Buffer.from(normalized + "=".repeat(padLength), "base64");
-}
+import { createHmac } from "crypto";
 function sign(input, secret) {
-  return base64UrlEncode2(createHmac("sha256", secret).update(input).digest());
+  return bytesToBase64Url(createHmac("sha256", secret).update(input).digest());
 }
 function nowEpochSeconds() {
   return Math.floor(Date.now() / 1e3);
@@ -338,8 +369,8 @@ function createTenantToken(params, secret) {
     v: 1
   };
   const header = { alg: "HS256", typ: "JWT" };
-  const encodedHeader = base64UrlEncode2(JSON.stringify(header));
-  const encodedPayload = base64UrlEncode2(JSON.stringify(payload));
+  const encodedHeader = bytesToBase64Url(utf8(JSON.stringify(header)));
+  const encodedPayload = bytesToBase64Url(utf8(JSON.stringify(payload)));
   const signingInput = `${encodedHeader}.${encodedPayload}`;
   const signature = sign(signingInput, secret);
   return `${signingInput}.${signature}`;
@@ -355,20 +386,20 @@ function verifyTenantToken(token, secret, options = {}) {
   const [encodedHeader, encodedPayload, receivedSignature] = parts;
   const signingInput = `${encodedHeader}.${encodedPayload}`;
   const expectedSignature = sign(signingInput, secret);
-  let receivedBuffer;
-  let expectedBuffer;
+  let receivedBytes;
+  let expectedBytes;
   try {
-    receivedBuffer = base64UrlDecode2(receivedSignature);
-    expectedBuffer = base64UrlDecode2(expectedSignature);
+    receivedBytes = base64UrlToBytes(receivedSignature);
+    expectedBytes = base64UrlToBytes(expectedSignature);
   } catch {
     throw new Error("INVALID_TENANT_AUTH");
   }
-  if (receivedBuffer.length !== expectedBuffer.length || !timingSafeEqual(receivedBuffer, expectedBuffer)) {
+  if (!timingSafeEqualBytes(receivedBytes, expectedBytes)) {
     throw new Error("INVALID_TENANT_AUTH");
   }
   let payload;
   try {
-    payload = JSON.parse(base64UrlDecode2(encodedPayload).toString("utf8"));
+    payload = JSON.parse(utf8Decode(base64UrlToBytes(encodedPayload)));
   } catch {
     throw new Error("INVALID_TENANT_AUTH");
   }
@@ -442,8 +473,17 @@ function createTenantContextManager(options) {
   async function getOrCreateAdapter(dbConfig) {
     const cacheKey = `${dbConfig.driver}:${dbConfig.connectionString}`;
     if (!adapterCache.has(cacheKey)) {
-      const adapter = await adapterFactory(dbConfig);
-      adapterCache.set(cacheKey, adapter);
+      const created = (async () => {
+        const adapter = await adapterFactory(dbConfig);
+        if (typeof adapter.initSchema === "function") {
+          await adapter.initSchema();
+        }
+        return adapter;
+      })().catch((error) => {
+        adapterCache.delete(cacheKey);
+        throw error;
+      });
+      adapterCache.set(cacheKey, created);
     }
     return adapterCache.get(cacheKey);
   }
@@ -571,6 +611,14 @@ async function createReiServer(config) {
       privateKey: vapid.privateKey || ""
     },
     webpush: webpushModule,
+    // 分片传输的限额（与 installReiSW 的 multipart 同一份）。instant 消息在
+    // schedule-message 里就地投递、定时消息走 send-notifications 的 tick，两条路
+    // 都从这个 ctx 展开，所以配一次两边都认。
+    multipart: config.multipart || null,
+    // 定时任务投递失败后的重试次数上限（默认 3），send-notifications 展开 ctx
+    // 时带进 runScheduledTick。
+    maxGenerationRetries: config.maxGenerationRetries,
+    maxDeliveryRetries: config.maxDeliveryRetries,
     tenant: {
       initSecret
     },
@@ -584,14 +632,39 @@ async function createReiServer(config) {
       sendNotifications: createSendNotificationsHandler(ctx),
       updateMessage: createUpdateMessageHandler(ctx),
       cancelMessage: createCancelMessageHandler(ctx),
-      messages: createMessagesHandler(ctx)
+      messages: createMessagesHandler(ctx),
+      getMessage: createGetMessageHandler(ctx),
+      pushSubscription: createPushSubscriptionHandler(ctx),
+      llmCredentials: createLlmCredentialsHandler(ctx)
     }
   };
 }
 export {
+  CORS_ALLOW_HEADERS,
+  CORS_ALLOW_METHODS,
+  CRED_ID_MAX_LENGTH,
+  CRED_PUT_BATCH_MAX,
+  CRED_REFS_MAX_ENTRIES,
+  CRED_ROWS_PER_USER_MAX,
+  DEFAULT_CLAIM_LEASE_MS,
+  DEFAULT_HEARTBEAT_LEASE_TTL_MS,
+  DEFAULT_LEASE_HEARTBEAT_MS,
+  DEFAULT_MAX_DELIVERY_RETRIES,
+  DEFAULT_MAX_REQUEST_BODY_BYTES,
+  DEFAULT_MAX_SCHEDULED_TASKS_PER_FIRE,
+  DEFAULT_MAX_TOOL_ITERATIONS,
+  DEFAULT_TOTAL_TIMEOUT_MS,
+  DeploymentConfigError,
+  MAX_DEFER_AFTER_MS,
   MAX_PUSH_PAYLOAD_BYTES,
+  MAX_TASK_PAYLOAD_BYTES,
+  MIN_SCHEDULE_LEAD_MS,
+  NonRetryableError,
+  PUSH_ENVELOPE_RESERVED_BYTES,
+  SCHEMA_VERSION,
   WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES,
   WEB_PUSH_MAX_BODY_BYTES,
+  advanceOccurrence,
   createAdapter,
   createD1Adapter,
   createReiServer,
@@ -603,13 +676,29 @@ export {
   decryptPayload,
   deriveUserEncryptionKey,
   encryptForStorage,
+  ensureSchema,
+  getSchemaVersion,
+  hasChatCredRef,
+  isNonRetryableError,
+  isValidCredId,
   isValidISO8601,
+  isValidTimeZoneId,
   isValidUUID,
   isValidUUIDv4,
   isValidUrl,
   measurePushPayload,
+  nextFutureOccurrence,
+  planNextOccurrence,
+  readRequestBody,
+  resolveLlmCredential,
   runScheduledTick,
+  runTask,
+  sanitizeErrorSummary,
+  summarizeErrorCause,
+  supportsLlmCredentialsStore,
   validateAvatarUrl,
+  validateCredRefs,
+  validateCredValue,
   validateLlmMessagesArray,
   validateScheduleMessagePayload,
   validateSplitPattern,

package/dist/lib/agentic-fire.d.ts

@@ -0,0 +1,177 @@
+/**
+ * 默认 messageId / sessionId 里掺的名义触发时刻后缀（`@<epoch-ms>`）。
+ *
+ * 循环任务跨天复用同一条任务行，id 只用 task.id 的话，离线设备一次性收到
+ * 多天积压的推送（push TTL 有四周）时会在 service worker 端互相去重、在
+ * 收件箱按 messageId 覆盖，几天的消息只剩一条。掺入名义触发时刻后每个
+ * occurrence 一套 id；同一 occurrence 的重试仍是同一套——重投已送达的段
+ * 会被去重，这正是想要的。行上没有可解析的 next_send_at（比如直接喂进来
+ * 的内存任务对象）时返回 ''，等价于旧格式。
+ *
+ * @param {{ next_send_at?: string }} task
+ * @returns {string}
+ */
+export function occurrenceSuffix(task: {
+    next_send_at?: string;
+}): string;
+/**
+ * 本次触发的名义时刻（epoch 毫秒）。行上没有可解析的 next_send_at（比如直接
+ * 喂进来的内存任务对象）时返回 null。
+ *
+ * @param {{ next_send_at?: string }} task
+ * @returns {number|null}
+ */
+export function occurrenceMsOf(task: {
+    next_send_at?: string;
+}): number | null;
+/**
+ * Does this task need the LLM at fire time? Fixed text never does, so it
+ * always stays on the legacy path regardless of hooks.
+ *
+ * @param {Object} decryptedPayload
+ * @returns {boolean}
+ */
+export function taskNeedsLlm(decryptedPayload: any): boolean;
+/**
+ * Frozen, credential-free view of the task for hook authors.
+ *
+ * nextSendAt 是这条任务原本的触发时刻。run-tick 领取任务时写的是 lease_until，
+ * next_send_at 那一列不动，所以这里给出去的和库里的是同一个值——宿主拿它当
+ * 时间锚点（窗口判断、缓存键）时对得上。
+ *
+ * 导出给 run-tick 用：`serializeBy` 要从任务内容里取分组 key，拿到的就该是
+ * 这一份（凭据剔掉、和 onBeforeFire 的 ctx.task 同一个形状），宿主不用为了
+ * 分组再学第二套字段。
+ */
+export function buildHookTask(task: any, decryptedPayload: any): Readonly<{
+    id: any;
+    uuid: any;
+    nextSendAt: any;
+    retryCount: any;
+}>;
+/**
+ * Try the hook-driven fire path for one task.
+ *
+ * @param {Object} args
+ * @param {import('../adapters/interface.js').TaskRow} args.task
+ * @param {Object} args.decryptedPayload - decrypted task payload (has credentials; they stop here)
+ * @param {string} args.userKey - per-user storage key (for readState decryption)
+ * @param {Object} args.ctx - processor ctx ({ db, webpush, vapid, hooks, maxToolIterations, totalTimeoutMs, maxScheduledTasksPerFire })
+ * @returns {Promise<{ handled: false }
+ *   | { handled: true, result: { success: true, messagesSent: number, status: 'finished'|'skipped', iterations: number } }
+ *   | { handled: true, result: { success: false, deferred: true, retryAfter: string, messagesSent: 0, status: 'deferred', iterations: 0 } }>}
+ *   `handled: false` → caller falls back to the legacy frozen-prompt path
+ *   (onBeforeFire returned null).
+ *   `onBeforeFire` may also return `{ skip: true }` to complete the fire
+ *   before the first LLM call → `status: 'skipped', iterations: 0`, same
+ *   success handling as the post-LLM skip-push path.
+ *   `{ defer: { afterMs } }` → `status: 'deferred'`，`retryAfter` 是「什么时候
+ *   再来问」的 ISO 时刻。`success` 给 false 而不是 true：这次什么都没发，调用
+ *   方得看 `deferred` 走推迟的收尾；万一有调用方不认识这个字段，也只会把它当
+ *   成没发成，不会当成发完了把任务删掉。
+ *   Failures (timeout / loop exceeded / config errors) throw — the caller's
+ *   existing error handling turns them into task retry/failure.
+ *
+ *   收尾回执：onBeforeFire 一旦被调用，上面每一种结局（含抛错）都会调一次
+ *   `ctx.onFireSettled`，见 notifyFireSettled。
+ */
+export function runAgenticFire({ task, decryptedPayload, userKey, ctx }: {
+    task: import("../adapters/interface.js").TaskRow;
+    decryptedPayload: any;
+    userKey: string;
+    ctx: any;
+}): Promise<{
+    handled: false;
+} | {
+    handled: true;
+    result: {
+        success: true;
+        messagesSent: number;
+        status: "finished" | "skipped";
+        iterations: number;
+    };
+} | {
+    handled: true;
+    result: {
+        success: false;
+        deferred: true;
+        retryAfter: string;
+        messagesSent: 0;
+        status: "deferred";
+        iterations: 0;
+    };
+}>;
+/**
+ * 把这一轮的 usage 累加进整次 fire 的合计，返回新的合计（不改传入的对象）。
+ *
+ * 合计的形状固定是 `{ prompt_tokens, completion_tokens, total_tokens }`，每个字
+ * 段是「报过这一项的那几轮」相加的结果，一轮都没报过的那一项是 null。各家供应
+ * 商的 usage 形状不齐，能加的尽量加：
+ *   - prompt / completion 认 OpenAI 的 `prompt_tokens` / `completion_tokens`，
+ *     没有就认 Anthropic 风格的 `input_tokens` / `output_tokens`；
+ *   - 这一轮没报 `total_tokens`、但 prompt 和 completion 都有，就拿两者之和补上；
+ *   - 只收有限的非负数，别的一律当没报。
+ *
+ * 这一轮三项都拿不到（没有 usage，或者形状完全认不出）就原样返回之前的合计——
+ * 所有轮次都这样的话合计保持 null。
+ *
+ * @param {{ prompt_tokens: number|null, completion_tokens: number|null, total_tokens: number|null } | null} total
+ * @param {unknown} usage - 这一轮 LLM 响应的 usage
+ * @returns {{ prompt_tokens: number|null, completion_tokens: number|null, total_tokens: number|null } | null}
+ */
+export function accumulateUsage(total: {
+    prompt_tokens: number | null;
+    completion_tokens: number | null;
+    total_tokens: number | null;
+} | null, usage: unknown): {
+    prompt_tokens: number | null;
+    completion_tokens: number | null;
+    total_tokens: number | null;
+} | null;
+export const DEFAULT_MAX_TOOL_ITERATIONS: 5;
+export const DEFAULT_TOTAL_TIMEOUT_MS: 240000;
+export const DEFAULT_MAX_SCHEDULED_TASKS_PER_FIRE: 2;
+export const MIN_SCHEDULE_LEAD_MS: 60000;
+export const MAX_DEFER_AFTER_MS: number;
+/**
+ * - 消息数组 / `{ messages, ... }`：用这份 prompt 生成；
+ * - `{ skip: true }`：这次不发，按零推送的成功收场（一次性任务删行、循环任务
+ * 推进到下一次）；
+ * - `{ defer: { afterMs } }`：现在不合适，afterMs 毫秒后再来问。afterMs 必须
+ * 是有限正数，且不超过 MAX_DEFER_AFTER_MS（24 小时）；
+ * - `null` / `undefined`：交还给排程时冻结的 prompt 老链路。
+ */
+export type BeforeFireResult = Array<any> | {
+    messages: Array<any>;
+    maxToolIterations?: number;
+    totalTimeoutMs?: number;
+    tools?: Array<any>;
+    toolChoice?: any;
+} | {
+    skip: true;
+} | {
+    defer: {
+        afterMs: number;
+    };
+} | null | undefined;
+/**
+ * 收尾回执（onFireSettled）的 status。
+ */
+export type FireSettledStatus = "sent" | "skipped" | "deferred" | "failed" | "cancelled" | "not-handled";
+/**
+ * 把任务的调度身份投影进一条 push。
+ *
+ * 客户端收到推送时要知道「这是哪条任务、哪一次触发、它还会不会再来」——不然
+ * 角色在 fire 里自排的任务客户端从没见过，只能靠猜。这三个字段由库统一补，
+ * 宿主不用再往 metadata 里抄一遍（抄漏一个就够坏事了）。
+ *
+ * 放在 push 顶层，和 messageId / sessionId / timestamp / messageIndex /
+ * totalMessages 一样，不塞进 metadata：metadata 是宿主自己的地盘，库往里写
+ * 会和宿主的键打架。
+ *
+ * @param {Object} push - 待发送的 push（原地补字段）
+ * @param {Object} task - 数据库任务行
+ * @param {Object} decryptedPayload
+ * @param {number|null} occurrenceMs
+ */
+export function stampTaskIdentity(push: any, task: any, decryptedPayload: any, occurrenceMs: number | null): void;

package/dist/lib/client-state-store.d.ts

@@ -0,0 +1,88 @@
+/** value 的 UTF-8 字节数——各处限额判断用的都是这个口径。 */
+export function stateValueBytes(value: any): number;
+/**
+ * 把 `clientStateTtl` 配置（`{ 命名空间: 天数 }`）算成清理指令。
+ *
+ * 一个命名空间出两条：它自己，加上它的切片命名空间（大值分块存在那儿，见
+ * lib/state-chunks.js）。两边共用同一个截止时刻——同一次写入的根行和切片行
+ * `updated_at` 相同，所以要么一起留、要么一起走，不会留下半截数据。
+ *
+ * 天数不是正数的条目跳过并告警（每个键只说一次）：配错了就该看得见，但不能
+ * 让 cron 每分钟刷一条。
+ *
+ * @param {Record<string, number>|null|undefined} ttl - `{ 命名空间: 天数 }`；天数可带小数
+ * @param {number} now - 当前时刻（epoch 毫秒）
+ * @returns {Array<{ namespace: string, updatedBefore: number }>}
+ *   `updatedBefore` 是 epoch 毫秒：这个命名空间下 `updated_at` 早于它的条目该清掉。
+ */
+export function planClientStateCleanup(ttl: Record<string, number> | null | undefined, now: number): Array<{
+    namespace: string;
+    updatedBefore: number;
+}>;
+/**
+ * 把逻辑条目写进 client_state。条目要么是覆盖写（`value` 是字符串），要么是
+ * 删除（`value` 为 `null`）：
+ *
+ *   - 覆盖写：≤ 200KB 单行存；超过的切片跨行存（见 lib/state-chunks.js）。
+ *     同一批里先清掉这个 key 上次写入留下的切片行，所以覆盖成更小的值、或者
+ *     块数变少，都不会留下尾巴。
+ *   - 删除：根行按精确 key 删，切片行按 key 前缀删，一个 key 的数据清干净。
+ *
+ * 两者都受同一套 last-write-wins 约束：`updatedAt` 比库里已有值旧的写入
+ * （或删除）不生效，陈旧批次盖不掉新数据。唯一的例外是库里那行「来自未来」
+ * （`updated_at` 晚于服务端当前时刻）——那种行只可能出自跑偏的设备时钟，不当
+ * 比较基准，写入放行，详见 adapters/d1.js 的 `upsertClientState`。
+ *
+ * 条件写护栏：条目可带可选的 `version`（毫秒时间戳或单调递增整数）。带了它，
+ * 比较用的就是这个值而不是 `updatedAt`——同一个 key 有多个写入方时（例如
+ * fire_pack 由常规 flush 和 instant-chat 两条路径写），谁的**内容**新谁赢，
+ * 而不是谁的请求后到谁赢：慢网下晚到的旧包带着旧 `version`，盖不掉先到的新
+ * 包。护栏值落在行的 updated_at 列上（client_state 的比较列本来就是它），
+ * 没带 `version` 的写入照旧按 `updatedAt` 比。
+ *
+ * 条目本身的合法性（namespace / key 字符、value 大小）由调用方先校验好：
+ * HTTP handler 逐条拒绝并把原因回给客户端，`writeState()` 直接抛错给 hook。
+ *
+ * @param {Object} args
+ * @param {{ upsertClientState: Function }} args.db
+ * @param {string} args.userId
+ * @param {CryptoKey|string} args.userKey - 该用户的存储密钥（value 用它加密）
+ * @param {Array<{ namespace: string, key: string, value: string|null, updatedAt: number, version?: number }>} args.entries
+ *   `version`（可选）：条件写护栏值，见文件头。带了它，这条的 last-write-wins
+ *   比较用它（写进行的 updated_at 列）；没带照旧用 `updatedAt`。
+ * @param {() => number} [args.now] - 取服务端当前时刻（测试可注入假时钟）。适配器
+ *   拿它认出库里「来自未来」的脏行。
+ * @returns {Promise<{ upserted: number, skipped: number, deleted: number, skippedEntries: Array<{ namespace: string, key: string }> }>}
+ *   `upserted` / `skipped` / `deleted` 按逻辑条目计（切片行不计），三者之和等于
+ *   条目数。`deleted` 是删除之后 key 已不在库里的条数——删掉了、或本来就没有，
+ *   两种都算；被 last-write-wins 拦下的删除（库里那行更新）计入 `skipped`。
+ *   `skippedEntries` 逐条列出被拦下的 key，写入与删除都在里面（适配器不回
+ *   outcomes / cleanupOutcomes 时分不清是哪条：写入按物理行计数兜底，删除一律
+ *   按「已删」计）。
+ */
+export function writeClientStateEntries({ db, userId, userKey, entries, now }: {
+    db: {
+        upsertClientState: Function;
+    };
+    userId: string;
+    userKey: CryptoKey | string;
+    entries: Array<{
+        namespace: string;
+        key: string;
+        value: string | null;
+        updatedAt: number;
+        version?: number;
+    }>;
+    now?: () => number;
+}): Promise<{
+    upserted: number;
+    skipped: number;
+    deleted: number;
+    skippedEntries: Array<{
+        namespace: string;
+        key: string;
+    }>;
+}>;
+export const MAX_STATE_ENTRIES_PER_BATCH: 200;
+export const MAX_NAMESPACE_CHARS: 128;
+export const MAX_KEY_CHARS: 256;

package/dist/lib/cloud-data-cleanup.d.ts

@@ -0,0 +1,36 @@
+export function cloudError(code: any, message: any, status?: number): Error & {
+    code: any;
+    status: number;
+};
+export function validCloudOwner(owner: any): boolean;
+export function cloudInventory(ctx: any, db: any, userId: any, userKey: any): Promise<{
+    entries: any[];
+    complete: boolean;
+    gaps: any[];
+}>;
+export function readCloudRecord(db: any, userId: any, key: any, kind: any, id: any): Promise<any>;
+export function publicOperation(operation: any): any;
+export function makeCleanupPlan(ctx: any, db: any, userId: any, key: any, input: any): Promise<{
+    id: `${string}-${string}-${string}-${string}-${string}`;
+    mode: any;
+    ownerGeneration: any;
+    owner: {
+        type: any;
+        id: any;
+        label: any;
+    };
+    resources: any[];
+    count: number;
+    counts: {
+        type: string;
+        count: number;
+    }[];
+    expiresAt: number;
+    impacts: string[];
+    complete: boolean;
+    gaps: any[];
+}>;
+export function startCleanup(ctx: any, db: any, userId: any, key: any, input: any): Promise<any>;
+export function advanceCleanup(ctx: any, db: any, userId: any, key: any, operation: any): Promise<any>;
+export function resumeCloudDataCleanups(ctx: any): Promise<void>;
+export const CLOUD_RESOURCE_TYPES: string[];

package/dist/lib/cloud-data-guard.d.ts

@@ -0,0 +1,14 @@
+/** Check at task start and immediately before external delivery. Writes must
+ * also use the adapter's transactional guard; this read is not a write lock. */
+export function assertCloudGuard(db: any, userId: any, guard: any): Promise<void>;
+/** Capture persisted task identity once. Missing generations deliberately mean
+ * zero, never the current generation: restoring must not revive old requests. */
+export function captureCloudTaskGuard(db: any, userId: any, payload: any, resolveOwner: any, task: any): Promise<{
+    owner: any;
+    generation: any;
+}>;
+/** Add ownership and transactional guard arguments at the storage boundary.
+ * A task-scoped inherited guard always wins over caller-provided output fields. */
+export function createCloudGuardedAdapter(db: any, { masterKey, resolveOwner, guard: inheritedGuard, userId: scopedUserId }?: {
+    guard?: any;
+}): any;

package/dist/lib/cloud-data-inventory.d.ts

@@ -0,0 +1,15 @@
+export function cloudDataHash(value: any): Promise<string>;
+/**
+ * Internal entries retain exact encrypted snapshots for conditional deletion.
+ * Only `entry.resource` may cross the API response boundary.
+ */
+export function buildCloudDataInventory({ db, userId, userKey, resolveOwner }: {
+    db: any;
+    userId: any;
+    userKey: any;
+    resolveOwner: any;
+}): Promise<{
+    entries: any[];
+    complete: boolean;
+    gaps: any[];
+}>;

package/dist/lib/constant-time.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Portable constant-time string comparison.
+ *
+ * Runs identically on Node (tests) and Cloudflare Workers (prod). We avoid
+ * both node:crypto's timingSafeEqual (undefined on Workers historically) and
+ * crypto.subtle.timingSafeEqual (absent on Node). Instead we HMAC-SHA256 both
+ * inputs under one fresh random key, then compare the two digests. Because the
+ * key is random per call, an attacker can't precompute or replay a stable
+ * timing oracle; digests are a fixed 32 bytes, so the XOR-accumulate compare
+ * runs the same number of steps regardless of input length, with no early-out.
+ *
+ * globalThis.crypto (Web Crypto) is available on Node >= 20 and on Workers.
+ */
+export function constantTimeEqual(a: any, b: any): Promise<boolean>;

package/dist/lib/db-errors.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Database error helpers.
+ */
+/**
+ * Check whether an error is caused by a unique-constraint violation.
+ *
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+export function isUniqueViolation(error: unknown): boolean;