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

package/dist/index.mjs

@@ -1,6 +1,17 @@
 import {
+  CORS_ALLOW_HEADERS,
+  CORS_ALLOW_METHODS,
+  DEFAULT_CLAIM_LEASE_MS,
+  DEFAULT_HEARTBEAT_LEASE_TTL_MS,
+  DEFAULT_LEASE_HEARTBEAT_MS,
+  DEFAULT_MAX_SCHEDULED_TASKS_PER_FIRE,
+  DEFAULT_MAX_TOOL_ITERATIONS,
+  DEFAULT_TOTAL_TIMEOUT_MS,
   MAX_PUSH_PAYLOAD_BYTES,
+  MIN_SCHEDULE_LEAD_MS,
+  NonRetryableError,
   PUSH_ENVELOPE_RESERVED_BYTES,
+  SCHEMA_VERSION,
   WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES,
   WEB_PUSH_MAX_BODY_BYTES,
   advanceOccurrence,
@@ -21,7 +32,10 @@ import {
   decryptPayload,
   deriveUserEncryptionKey,
   encryptForStorage,
+  ensureSchema,
   getHeader,
+  getSchemaVersion,
+  isNonRetryableError,
   isValidISO8601,
   isValidTimeZoneId,
   isValidUUID,
@@ -32,6 +46,9 @@ import {
   parseJsonBody,
   planNextOccurrence,
   runScheduledTick,
+  runTask,
+  sanitizeErrorSummary,
+  summarizeErrorCause,
   timingSafeEqualBytes,
   utf8,
   utf8Decode,
@@ -39,7 +56,8 @@ import {
   validateLlmMessagesArray,
   validateScheduleMessagePayload,
   validateSplitPattern
-} from "./chunk-TV7N3RTH.mjs";
+} from "./chunk-KVHR3RCU.mjs";
+import "./chunk-34I2YSWE.mjs";
 
 // src/server/adapters/factory.js
 async function createAdapter(config) {
@@ -55,11 +73,11 @@ async function createAdapter(config) {
   }
   switch (config.driver) {
     case "neon": {
-      const { NeonAdapter } = await import("./neon-CUIGAB2T.mjs");
+      const { NeonAdapter } = await import("./neon-GBUF4G76.mjs");
       return new NeonAdapter(config.connectionString);
     }
     case "pg": {
-      const { PgAdapter } = await import("./pg-KMJPL6QV.mjs");
+      const { PgAdapter } = await import("./pg-MRXP5MHJ.mjs");
       return new PgAdapter(config.connectionString);
     }
     default:
@@ -228,14 +246,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) {
@@ -249,16 +259,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");
@@ -446,8 +456,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);
   }
@@ -595,8 +614,19 @@ async function createReiServer(config) {
   };
 }
 export {
+  CORS_ALLOW_HEADERS,
+  CORS_ALLOW_METHODS,
+  DEFAULT_CLAIM_LEASE_MS,
+  DEFAULT_HEARTBEAT_LEASE_TTL_MS,
+  DEFAULT_LEASE_HEARTBEAT_MS,
+  DEFAULT_MAX_SCHEDULED_TASKS_PER_FIRE,
+  DEFAULT_MAX_TOOL_ITERATIONS,
+  DEFAULT_TOTAL_TIMEOUT_MS,
   MAX_PUSH_PAYLOAD_BYTES,
+  MIN_SCHEDULE_LEAD_MS,
+  NonRetryableError,
   PUSH_ENVELOPE_RESERVED_BYTES,
+  SCHEMA_VERSION,
   WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES,
   WEB_PUSH_MAX_BODY_BYTES,
   advanceOccurrence,
@@ -611,6 +641,9 @@ export {
   decryptPayload,
   deriveUserEncryptionKey,
   encryptForStorage,
+  ensureSchema,
+  getSchemaVersion,
+  isNonRetryableError,
   isValidISO8601,
   isValidTimeZoneId,
   isValidUUID,
@@ -620,6 +653,9 @@ export {
   nextFutureOccurrence,
   planNextOccurrence,
   runScheduledTick,
+  runTask,
+  sanitizeErrorSummary,
+  summarizeErrorCause,
   validateAvatarUrl,
   validateLlmMessagesArray,
   validateScheduleMessagePayload,

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

@@ -12,6 +12,13 @@ export function stateValueBytes(value: any): number;
  * 两者都受同一套 last-write-wins 约束：`updatedAt` 比库里已有值旧的写入
  * （或删除）不生效，陈旧批次盖不掉新数据。
  *
+ * 条件写护栏：条目可带可选的 `version`（毫秒时间戳或单调递增整数）。带了它，
+ * 比较用的就是这个值而不是 `updatedAt`——同一个 key 有多个写入方时（例如
+ * fire_pack 由常规 flush 和 instant-chat 两条路径写），谁的**内容**新谁赢，
+ * 而不是谁的请求后到谁赢：慢网下晚到的旧包带着旧 `version`，盖不掉先到的新
+ * 包。护栏值落在行的 updated_at 列上（client_state 的比较列本来就是它），
+ * 没带 `version` 的写入照旧按 `updatedAt` 比。
+ *
  * 条目本身的合法性（namespace / key 字符、value 大小）由调用方先校验好：
  * HTTP handler 逐条拒绝并把原因回给客户端，`writeState()` 直接抛错给 hook。
  *
@@ -19,10 +26,13 @@ export function stateValueBytes(value: any): number;
  * @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 }>} args.entries
- * @returns {Promise<{ upserted: number, skipped: number, deleted: number }>}
+ * @param {Array<{ namespace: string, key: string, value: string|null, updatedAt: number, version?: number }>} args.entries
+ *   `version`（可选）：条件写护栏值，见文件头。带了它，这条的 last-write-wins
+ *   比较用它（写进行的 updated_at 列）；没带照旧用 `updatedAt`。
+ * @returns {Promise<{ upserted: number, skipped: number, deleted: number, skippedEntries: Array<{ namespace: string, key: string }> }>}
  *   `upserted` / `skipped` 按逻辑条目计（切片行不计）；`deleted` 是请求删除的
- *   key 数，不代表这些 key 原本一定存在。
+ *   key 数，不代表这些 key 原本一定存在。`skippedEntries` 逐条列出被
+ *   last-write-wins 拦下的 key（适配器不回 outcomes 时为空数组——分不清是哪条）。
  */
 export function writeClientStateEntries({ db, userId, userKey, entries }: {
     db: {
@@ -35,11 +45,16 @@ export function writeClientStateEntries({ db, userId, userKey, entries }: {
         key: string;
         value: string | null;
         updatedAt: number;
+        version?: 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;

package/dist/lib/errors.d.ts

@@ -0,0 +1,93 @@
+/**
+ * 这个错误是不是「重试也好不了」。认 NonRetryableError，也认任何自带
+ * `permanent: true` 的错误对象（跨包/跨版本安全）。
+ *
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+export function isNonRetryableError(error: unknown): boolean;
+/**
+ * 把错误原因脱敏成能明文落库（任务行 last_error 列）的摘要。
+ *
+ * 任务内容一律密文落库，last_error 是唯一一列明文的「为什么没发出去」——
+ * 错误消息偶尔会回显请求细节（上游 API 的报错带 URL、header 片段），所以
+ * 长得像凭据的 token 一律遮掉，再截断到 500 字符。
+ *
+ * @param {unknown} reason
+ * @returns {string}
+ */
+export function sanitizeErrorSummary(reason: unknown): string;
+/**
+ * @typedef {Object} ErrorCause
+ * @property {'config'|'request'|'tick'} stage - 在哪一段炸的
+ * @property {string} name - 错误类型（`error.name`，认不出来时是 'Error'）
+ * @property {string} message - 脱敏后的错误消息
+ * @property {string} [code] - 错误自带的 `code` 字符串（有才带）
+ */
+/**
+ * 把一个异常整理成能随响应体一起回给调用方的机读原因。
+ *
+ * 500 只回一句「服务器内部错误」的话，真因（`D1_ERROR: no such table:
+ * message_outbox`、存储层写超时……）就只剩 console.error 里那一行，调用方拿不
+ * 到，用户看到的也只是「服务器内部错误」——不知道哪儿坏了，也不知道该点哪里。
+ * 这个函数把异常压成几个固定字段，让调用方能机读、能展示。
+ *
+ * 只带错误类型和消息文本。消息先过 `sanitizeErrorSummary`（遮掉长得像凭据的
+ * 串、截断到 500 字符）；密钥、用户数据、任务正文都不在 `error.message` 上，
+ * 也不往这里放。
+ *
+ * @param {unknown} error - 捕获到的异常，也收 `{ name, message }` 这样的普通对象
+ * @param {'config'|'request'|'tick'} stage - 'config' = 构建配置时抛的（少了
+ *   binding / 环境变量）；'request' = 路由或处理器抛的；'tick' = cron 那一跳抛的
+ * @returns {ErrorCause}
+ */
+export function summarizeErrorCause(error: unknown, stage: "config" | "request" | "tick"): ErrorCause;
+/**
+ * 错误类型：宿主 hook 与库内部共用的失败语义标注。
+ */
+/**
+ * 确定性失败——重试必然同败，别再排退避阶梯。
+ *
+ * 典型场景全在 fire-time hook 里：onBeforeFire 发现 fire_pack 缺失、解析失
+ * 败、缺必要的段……这类错误不会因为过两分钟再跑一次就好，按普通投递失败重
+ * 试三轮只是让用户多白等十几分钟，还把 hook 里的计费调用（情绪评估之类）
+ * 重复烧三遍。hook 抛这个类（或任何带 `permanent: true` 的错误），run-tick
+ * 收到后跳过退避：一次性任务直接标 failed（原因进 last_error / payload 的
+ * lastError），循环任务直接作废本次 occurrence。
+ *
+ * `code`（可选）会透传到 processSingleMessage 的 errorCode，宿主想按错误类
+ * 别分流时用它。
+ *
+ * 用 `permanent` 属性而不是 instanceof 做判定：宿主的 worker 里可能打包了另
+ * 一份本库（版本错开、bundler 双实例），跨 realm 的 instanceof 靠不住。
+ */
+export class NonRetryableError extends Error {
+    /**
+     * @param {string} message
+     * @param {{ code?: string, cause?: unknown }} [options]
+     */
+    constructor(message: string, options?: {
+        code?: string;
+        cause?: unknown;
+    });
+    permanent: boolean;
+    code: string;
+}
+export type ErrorCause = {
+    /**
+     * - 在哪一段炸的
+     */
+    stage: "config" | "request" | "tick";
+    /**
+     * - 错误类型（`error.name`，认不出来时是 'Error'）
+     */
+    name: string;
+    /**
+     * - 脱敏后的错误消息
+     */
+    message: string;
+    /**
+     * - 错误自带的 `code` 字符串（有才带）
+     */
+    code?: string;
+};

package/dist/lib/message-processor.d.ts

@@ -10,12 +10,18 @@
  * @param {import('../adapters/interface.js').TaskRow} task
  * @param {ProcessorContext} ctx
  * @param {string} [providedMasterKey]
- * @returns {Promise<{ success: boolean, messagesSent: number, error?: string }>}
+ * @param {{ userKey: string, payload: Object } | null} [predecrypted] - 调用方
+ *   （run-tick 的预扫描）已经解好的 payload；传了就不再解第二遍。
+ * @returns {Promise<{ success: boolean, messagesSent: number, error?: string, errorCode?: string|null }>}
  */
-export function processSingleMessage(task: import("../adapters/interface.js").TaskRow, ctx: ProcessorContext, providedMasterKey?: string): Promise<{
+export function processSingleMessage(task: import("../adapters/interface.js").TaskRow, ctx: ProcessorContext, providedMasterKey?: string, predecrypted?: {
+    userKey: string;
+    payload: any;
+} | null): Promise<{
     success: boolean;
     messagesSent: number;
     error?: string;
+    errorCode?: string | null;
 }>;
 /**
  * Process a single message identified by UUID (used for instant type).

package/dist/lib/outbox-store.d.ts

@@ -0,0 +1,33 @@
+/** 适配器支持 outbox 吗（写入侧要用的两个方法都在才算）。 */
+export function supportsOutbox(db: any): boolean;
+/**
+ * 发送前把这一批 push 落进 outbox。push 对象须已定稿（messageId / sessionId /
+ * messageIndex / totalMessages / 任务身份都已补齐）——落进去的密文就是客户端
+ * 补收时拿到的那一份。
+ *
+ * @param {Object} args
+ * @param {Object} args.db
+ * @param {string} args.userId
+ * @param {CryptoKey|string} args.userKey - per-user 存储密钥
+ * @param {Object[]} args.pushes - 定稿后的 push 对象
+ * @returns {Promise<boolean>} 是否真的落了行（适配器不支持 / 落行失败 → false）
+ */
+export function appendPushesToOutbox({ db, userId, userKey, pushes }: {
+    db: any;
+    userId: string;
+    userKey: CryptoKey | string;
+    pushes: any[];
+}): Promise<boolean>;
+/**
+ * 把发出去的那部分标成 delivered（发送半途失败时只标已发出的段）。
+ *
+ * @param {Object} args
+ * @param {Object} args.db
+ * @param {string} args.userId
+ * @param {string[]} args.messageIds
+ */
+export function markPushesDelivered({ db, userId, messageIds }: {
+    db: any;
+    userId: string;
+    messageIds: string[];
+}): Promise<void>;

package/dist/lib/push-subscription-store.d.ts

@@ -48,16 +48,24 @@ export function loadPushSubscription({ db, userId, userKey }: {
 /**
  * 投递前取订阅。取不到就抛——静默不发会让任务「成功」地什么都没做，用户
  * 只看到消息凭空消失。抛出去走既有的重试 / 标记逻辑，原因也会记进 payload
- * 的 lastError，`GET /messages` 上看得见。
+ * 的 lastError，`GET /messages` 上看得见。抛出的错误带稳定的 `code` 属性
+ * （'PUSH_SUBSCRIPTION_MISSING' / 'PUSH_SUBSCRIPTION_STORE_UNSUPPORTED'），
+ * 按类别分支请用它，别匹配 message 文案。
+ *
+ * `legacyFallback`：用户级存储里没有订阅时的兜底（升级前创建的任务把订阅
+ * 冻结在自己的 payload 里，这份订阅仍然有效）。存储里有订阅时永远用存储的
+ * 那份——它是用户最近一次登记的。
  *
  * @param {Object} args
  * @param {import('../adapters/interface.js').DbAdapter} args.db
  * @param {string} args.userId
  * @param {string} args.userKey
+ * @param {unknown} [args.legacyFallback] - 旧任务 payload 里内嵌的订阅（可选）
  * @returns {Promise<Object>} 明文订阅对象
  */
-export function resolvePushSubscription({ db, userId, userKey }: {
+export function resolvePushSubscription({ db, userId, userKey, legacyFallback }: {
     db: import("../adapters/interface.js").DbAdapter;
     userId: string;
     userKey: string;
+    legacyFallback?: unknown;
 }): Promise<any>;

package/dist/lib/request.d.ts

@@ -56,6 +56,42 @@ export function isEncryptedEnvelope(payload: unknown): payload is {
  * @returns {ParseBodyResult}
  */
 export function parseEncryptedBody(body: unknown): ParseBodyResult;
+/**
+ * 标准错误信封：{ status, body: { success: false, error: { code, message, details? } } }。
+ *
+ * @param {number} status
+ * @param {string} code
+ * @param {string} message
+ * @param {Object} [details]
+ */
+export function errorResponse(status: number, code: string, message: string, details?: any): {
+    status: number;
+    body: {
+        success: boolean;
+        error: {
+            code: string;
+            message: string;
+            details?: undefined;
+        } | {
+            code: string;
+            message: string;
+            details: any;
+        };
+    };
+};
+/**
+ * X-User-Id 门禁。所有按用户读写的端点共用这一份：规则（必填 + UUID v4）和
+ * 文案只此一处，改口径不用挨个 handler 找复制粘贴的副本。
+ *
+ * @param {Record<string, any>} headers
+ * @returns {{ userId: string, error?: undefined } | { error: ReturnType<typeof errorResponse> }}
+ */
+export function requireUserId(headers: Record<string, any>): {
+    userId: string;
+    error?: undefined;
+} | {
+    error: ReturnType<typeof errorResponse>;
+};
 /**
  * Read a header value case-insensitively.
  *

package/dist/lib/run-tick.d.ts

@@ -27,8 +27,45 @@ export function runScheduledTick(ctx: any): Promise<{
         failedTasks: any[];
     };
 }>;
+/**
+ * 只跑一条任务的官方入口，给「fetch 里只来得及 enqueue、真正的 fire 交给
+ * CF Queue 消费者（15 分钟预算）跑」这类宿主用——不用再依赖 cron 恰好捞到。
+ *
+ * 与 cron tick 走完全同一条投递链：占位（含心跳续租）、过期守卫、分组串行
+ * （单任务场景下退化为占位时的跨 tick 分组门）、失败重试/终态、hook 全套。
+ * 行没到点（next_send_at 在未来）或正处在退避窗口（retry_after 未到点）时不
+ * 跑——这个入口只是换了个触发器，不是绕过排期的后门。
+ *
+ * 四种不跑的情形分开回报，调用方不用猜：
+ *   - `not_found`：没有这条 uuid。一次性任务发完即删，所以「发完了」的那条也
+ *     落在这里；行还在但已经是终态的走下面那条。
+ *   - `already_settled`：行还在，但已经是 sent / failed（`status` 带上是哪
+ *     个）。适配器没实现 `getTaskStatusByUuidOnly` 时这种情况并进 `not_found`。
+ *   - `not_due`：还没到 `next_send_at`（`nextSendAt` 带上是什么时候）。
+ *   - `retry_pending`：上次投递失败，还在退避窗口里（`retryAfter` 带上什么时
+ *     候到点）。
+ *
+ * @param {Object} ctx - 与 runScheduledTick 同一份 ctx
+ * @param {string} uuid - 任务 uuid（pending 行）
+ * @returns {Promise<{ ran: false, reason: 'not_found'|'already_settled'|'not_due'|'retry_pending', status?: string, nextSendAt?: string, retryAfter?: string }
+ *   | { ran: true, summary: Object }>} summary 与 runScheduledTick 的返回同构
+ *   （totalTasks 恒为 1）；任务被别的执行者占着时体现在 summary.details.claimSkippedTasks。
+ */
+export function runTask(ctx: any, uuid: string): Promise<{
+    ran: false;
+    reason: "not_found" | "already_settled" | "not_due" | "retry_pending";
+    status?: string;
+    nextSendAt?: string;
+    retryAfter?: string;
+} | {
+    ran: true;
+    summary: any;
+}>;
 export const DEFAULT_CLAIM_LEASE_MS: number;
+export const DEFAULT_LEASE_HEARTBEAT_MS: number;
+export const DEFAULT_HEARTBEAT_LEASE_TTL_MS: number;
 export const STALE_AFTER_MS: number;
+export { sanitizeErrorSummary };
 export type StaleSkipInfo = {
     reason: "stale";
     /**
@@ -66,3 +103,4 @@ export type StaleSkipInfo = {
     readState: (namespace: string) => Promise<any[]>;
     writeState: (namespace: string, entries: any[]) => Promise<any>;
 };
+import { sanitizeErrorSummary } from './errors.js';

package/dist/lib/schema-version.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 活库的表结构够不够这一版代码用。只读，不改任何东西。
+ *
+ * @param {import('../adapters/interface.js').DbAdapter} db - 数据库适配器
+ *   （要实现 `describeSchema()`；内置的 D1 适配器实现了）
+ * @returns {Promise<SchemaVersionResult>}
+ */
+export function getSchemaVersion(db: import("../adapters/interface.js").DbAdapter): Promise<SchemaVersionResult>;
+/**
+ * 缺什么补什么：自查一遍，不够用就跑一次 `initSchema()`（建表 + 补列 + 建索
+ * 引，重复跑没事），再自查一遍把结果回报出去。
+ *
+ * 本来就够用时不跑——`initSchema()` 是好几个来回，能省则省。
+ *
+ * @param {import('../adapters/interface.js').DbAdapter} db - 数据库适配器
+ * @returns {Promise<EnsureSchemaResult>} 补齐之后的自查结果；`migrated` 说明这
+ *   次有没有真的动手。补完仍然 `ok: false`（例如 ALTER 被库拒了）时 `missing`
+ *   里还留着没补上的那几项
+ */
+export function ensureSchema(db: import("../adapters/interface.js").DbAdapter): Promise<EnsureSchemaResult>;
+/**
+ * 表结构自己的版本号，只在表 / 列 / 关键索引变化时抬，与包版本各走各的。
+ * 数值取自引入当前这套表结构的那条发布线。
+ */
+export const SCHEMA_VERSION: "2.6.0";
+export type SchemaVersionResult = {
+    /**
+     * - 活库当前满足的版本：够用就是 `SCHEMA_VERSION`，
+     * 缺东西就是 `null`（只知道不够用，不知道它停在哪一版）
+     */
+    current: string | null;
+    /**
+     * - 这一版代码需要的表结构版本
+     */
+    required: string;
+    /**
+     * - 需要的表 / 列 / 关键索引是不是都在
+     */
+    ok: boolean;
+    /**
+     * - 缺什么，形如 `'table:message_outbox'` /
+     * `'column:scheduled_messages.last_error'` / `'index:uidx_uuid'`。整张表缺席
+     * 时只报这一张表，不再逐列展开。`ok` 为 true 时是空数组
+     */
+    missing: string[];
+};
+export type EnsureSchemaResult = SchemaVersionResult & {
+    migrated: boolean;
+    schema: any | null;
+};

package/dist/lib/validation.d.ts

@@ -4,12 +4,6 @@
  * @returns {boolean}
  */
 export function isValidISO8601(dateString: string): boolean;
-/**
- * Validate URL format.
- * @param {string} urlString
- * @returns {boolean}
- */
-export function isValidUrl(urlString: string): boolean;
 /**
  * Validate UUID format.
  * @param {string} uuid
@@ -65,4 +59,4 @@ export function validateScheduleMessagePayload(payload: any): {
     details?: any;
 };
 import { isValidTimeZoneId } from './recurrence.js';
-export { isValidTimeZoneId, validateAvatarUrl };
+export { isValidTimeZoneId, isValidUrl, validateAvatarUrl };