@h-ai/reach 0.1.0-alpha.67 → 0.1.0-alpha.69

package/dist/index.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { core, err, ok } from '@h-ai/core';
+import process from 'process';
 import { reldb, BaseReldbCrudRepository } from '@h-ai/reldb';
 import { randomUUID, createHmac } from 'crypto';
 import { createRequire } from 'module';
@@ -20,7 +21,14 @@ var en_US_default = {
   reach_providerNotFound: "Provider not found: {provider}",
   reach_providerRequired: "No provider specified, set provider field in message or template",
   reach_dndBlocked: "Message discarded by Do Not Disturb period",
-  reach_dndDeferred: "Message deferred by Do Not Disturb period, will be sent after DND ends",
+  reach_dndPersistenceRequired: "DND delay requires an initialized database and a ready queue table",
+  reach_dndEnqueueFailed: "The message could not be reliably queued; try again later",
+  reach_sendRecordSaveFailed: "Failed to persist the reach send record",
+  reach_invalidStoredInteger: "Send record {field} is not a safe non-negative integer",
+  reach_claimLost: "The valid delivery lease was lost",
+  reach_unknownResolutionFailed: "Unknown delivery was not found or has already been resolved",
+  reach_queueInputInvalid: "Invalid queue receipt or manual resolution parameters",
+  reach_deliveryUnknown: "The external delivery outcome is unknown; manual review is required and automatic redelivery has stopped",
   reach_smsSendFailed: "SMS send failed: {error}",
   reach_emailSendFailed: "Email send failed: {error}",
   reach_apiSendFailed: "API callback send failed: {error}",
@@ -39,7 +47,55 @@ var en_US_default = {
   reach_config_providersRequired: "At least one provider is required",
   reach_templateDbInitFailed: "Template database initialization failed: {error}",
   reach_templateSaveFailed: "Template save failed: {error}",
-  reach_templateDeleteFailed: "Template delete failed: {error}"
+  reach_templateDeleteFailed: "Template delete failed: {error}",
+  reach_queueRetryInvalid: "maxRetryDelayMs must be at least retryDelayMs",
+  reach_deadRequeueFailed: "Dead message changed or does not exist; reload its state before restoring",
+  reach_productionProviderRequired: "Production requires a delivery provider; console is available only in development or explicit test mode"
+};
+
+// messages/ja-JP.json
+var ja_JP_default = {
+  $schema: "https://inlang.com/schema/inlang-message-format",
+  reach_notInitialized: "\u901A\u77E5\u30E2\u30B8\u30E5\u30FC\u30EB\u304C\u521D\u671F\u5316\u3055\u308C\u3066\u3044\u307E\u305B\u3093\u3002\u5148\u306Breach.init()\u3092\u547C\u3073\u51FA\u3057\u3066\u304F\u3060\u3055\u3044",
+  reach_initFailed: "\u901A\u77E5\u30E2\u30B8\u30E5\u30FC\u30EB\u306E\u521D\u671F\u5316\u306B\u5931\u6557\u3057\u307E\u3057\u305F: {error}",
+  reach_unsupportedType: "\u672A\u5BFE\u5FDC\u306E\u901A\u77E5\u306E\u7A2E\u985E\u3067\u3059: {type}",
+  reach_sendFailed: "\u9001\u4FE1\u306B\u5931\u6557\u3057\u307E\u3057\u305F: {error}",
+  reach_templateNotFound: "\u30C6\u30F3\u30D7\u30EC\u30FC\u30C8\u304C\u898B\u3064\u304B\u308A\u307E\u305B\u3093: {template}",
+  reach_templateRenderFailed: "\u30C6\u30F3\u30D7\u30EC\u30FC\u30C8\u306E\u63CF\u753B\u306B\u5931\u6557\u3057\u307E\u3057\u305F: {error}",
+  reach_invalidRecipient: "\u5B9B\u5148\u304C\u7121\u52B9\u3067\u3059: {recipient}",
+  reach_providerNotFound: "\u30D7\u30ED\u30D0\u30A4\u30C0\u30FC\u304C\u898B\u3064\u304B\u308A\u307E\u305B\u3093: {provider}",
+  reach_providerRequired: "\u30D7\u30ED\u30D0\u30A4\u30C0\u30FC\u304C\u6307\u5B9A\u3055\u308C\u3066\u3044\u307E\u305B\u3093\u3002\u30E1\u30C3\u30BB\u30FC\u30B8\u307E\u305F\u306F\u30C6\u30F3\u30D7\u30EC\u30FC\u30C8\u306Eprovider\u3092\u8A2D\u5B9A\u3057\u3066\u304F\u3060\u3055\u3044",
+  reach_dndBlocked: "\u901A\u77E5\u3092\u505C\u6B62\u3059\u308B\u6642\u9593\u5E2F\u306E\u305F\u3081\u3001\u30E1\u30C3\u30BB\u30FC\u30B8\u3092\u7834\u68C4\u3057\u307E\u3057\u305F",
+  reach_dndPersistenceRequired: "\u901A\u77E5\u5236\u9650\u6642\u9593\u5E2F\u306E\u914D\u4FE1\u5EF6\u671F\u306B\u306F\u521D\u671F\u5316\u6E08\u307F\u306E\u30C7\u30FC\u30BF\u30D9\u30FC\u30B9\u3068\u6E96\u5099\u6E08\u307F\u306E\u30AD\u30E5\u30FC\u30C6\u30FC\u30D6\u30EB\u304C\u5FC5\u8981\u3067\u3059",
+  reach_dndEnqueueFailed: "\u30E1\u30C3\u30BB\u30FC\u30B8\u3092\u78BA\u5B9F\u306B\u30AD\u30E5\u30FC\u3078\u767B\u9332\u3067\u304D\u307E\u305B\u3093\u3067\u3057\u305F\u3002\u3057\u3070\u3089\u304F\u3057\u3066\u304B\u3089\u518D\u8A66\u884C\u3057\u3066\u304F\u3060\u3055\u3044",
+  reach_sendRecordSaveFailed: "\u914D\u4FE1\u8A18\u9332\u306E\u6C38\u7D9A\u5316\u306B\u5931\u6557\u3057\u307E\u3057\u305F",
+  reach_invalidStoredInteger: "\u914D\u4FE1\u8A18\u9332\u306E {field} \u306F\u5B89\u5168\u306A\u975E\u8CA0\u6574\u6570\u3067\u306F\u3042\u308A\u307E\u305B\u3093",
+  reach_claimLost: "\u6709\u52B9\u306A\u914D\u4FE1\u30EA\u30FC\u30B9\u304C\u5931\u308F\u308C\u307E\u3057\u305F",
+  reach_unknownResolutionFailed: "\u7D50\u679C\u4E0D\u660E\u306E\u914D\u4FE1\u304C\u898B\u3064\u304B\u3089\u306A\u3044\u304B\u3001\u65E2\u306B\u89E3\u6C7A\u3055\u308C\u3066\u3044\u307E\u3059",
+  reach_queueInputInvalid: "\u30AD\u30E5\u30FC\u306E\u53D7\u9818\u8A18\u9332\u307E\u305F\u306F\u624B\u52D5\u89E3\u6C7A\u306E\u30D1\u30E9\u30E1\u30FC\u30BF\u30FC\u304C\u7121\u52B9\u3067\u3059",
+  reach_deliveryUnknown: "\u5916\u90E8\u3078\u306E\u914D\u4FE1\u7D50\u679C\u306F\u4E0D\u660E\u3067\u3059\u3002\u624B\u52D5\u78BA\u8A8D\u304C\u5FC5\u8981\u306A\u305F\u3081\u3001\u81EA\u52D5\u518D\u914D\u4FE1\u3092\u505C\u6B62\u3057\u307E\u3057\u305F",
+  reach_smsSendFailed: "SMS\u306E\u9001\u4FE1\u306B\u5931\u6557\u3057\u307E\u3057\u305F: {error}",
+  reach_emailSendFailed: "\u30E1\u30FC\u30EB\u306E\u9001\u4FE1\u306B\u5931\u6557\u3057\u307E\u3057\u305F: {error}",
+  reach_apiSendFailed: "API\u30B3\u30FC\u30EB\u30D0\u30C3\u30AF\u306E\u9001\u4FE1\u306B\u5931\u6557\u3057\u307E\u3057\u305F: {error}",
+  reach_configError: "\u901A\u77E5\u8A2D\u5B9A\u306E\u691C\u8A3C\u306B\u5931\u6557\u3057\u307E\u3057\u305F: {error}",
+  reach_config_nameRequired: "\u30D7\u30ED\u30D0\u30A4\u30C0\u30FC\u540D\u306F\u5FC5\u9808\u3067\u3059",
+  reach_config_hostRequired: "SMTP\u30DB\u30B9\u30C8\u306F\u5FC5\u9808\u3067\u3059",
+  reach_config_fromRequired: "\u9001\u4FE1\u8005\u30A2\u30C9\u30EC\u30B9\uFF08from\uFF09\u306F\u5FC5\u9808\u3067\u3059",
+  reach_config_accessKeyIdRequired: "AccessKey ID\u306F\u5FC5\u9808\u3067\u3059",
+  reach_config_accessKeySecretRequired: "AccessKey Secret\u306F\u5FC5\u9808\u3067\u3059",
+  reach_config_signNameRequired: "SMS\u7F72\u540D\u306F\u5FC5\u9808\u3067\u3059",
+  reach_config_urlRequired: "\u30B3\u30FC\u30EB\u30D0\u30C3\u30AFURL\u306F\u5FC5\u9808\u3067\u3059",
+  reach_config_dndTimeInvalid: "\u6642\u523B\u5F62\u5F0F\u304C\u7121\u52B9\u3067\u3059\u3002HH:mm\uFF0824\u6642\u9593\u5236\uFF09\u3067\u6307\u5B9A\u3057\u3066\u304F\u3060\u3055\u3044",
+  reach_config_templateNameRequired: "\u30C6\u30F3\u30D7\u30EC\u30FC\u30C8\u540D\u306F\u5FC5\u9808\u3067\u3059",
+  reach_config_templateProviderRequired: "\u30C6\u30F3\u30D7\u30EC\u30FC\u30C8\u306E\u30D7\u30ED\u30D0\u30A4\u30C0\u30FC\u306F\u5FC5\u9808\u3067\u3059",
+  reach_config_templateBodyRequired: "\u30C6\u30F3\u30D7\u30EC\u30FC\u30C8\u672C\u6587\u306F\u5FC5\u9808\u3067\u3059",
+  reach_config_providersRequired: "\u5C11\u306A\u304F\u3068\u30821\u3064\u306E\u30D7\u30ED\u30D0\u30A4\u30C0\u30FC\u304C\u5FC5\u8981\u3067\u3059",
+  reach_templateDbInitFailed: "\u30C6\u30F3\u30D7\u30EC\u30FC\u30C8\u30C7\u30FC\u30BF\u30D9\u30FC\u30B9\u306E\u521D\u671F\u5316\u306B\u5931\u6557\u3057\u307E\u3057\u305F: {error}",
+  reach_templateSaveFailed: "\u30C6\u30F3\u30D7\u30EC\u30FC\u30C8\u306E\u4FDD\u5B58\u306B\u5931\u6557\u3057\u307E\u3057\u305F: {error}",
+  reach_templateDeleteFailed: "\u30C6\u30F3\u30D7\u30EC\u30FC\u30C8\u306E\u524A\u9664\u306B\u5931\u6557\u3057\u307E\u3057\u305F: {error}",
+  reach_queueRetryInvalid: "maxRetryDelayMs \u306F retryDelayMs \u4EE5\u4E0A\u306B\u3057\u3066\u304F\u3060\u3055\u3044",
+  reach_deadRequeueFailed: "\u914D\u4FE1\u4E0D\u80FD\u30E1\u30C3\u30BB\u30FC\u30B8\u304C\u5909\u66F4\u3055\u308C\u305F\u304B\u3001\u5B58\u5728\u3057\u307E\u305B\u3093\u3002\u5FA9\u5143\u3059\u308B\u524D\u306B\u72B6\u614B\u3092\u518D\u8AAD\u307F\u8FBC\u307F\u3057\u3066\u304F\u3060\u3055\u3044",
+  reach_productionProviderRequired: "\u672C\u756A\u74B0\u5883\u306B\u306F\u914D\u4FE1\u30D7\u30ED\u30D0\u30A4\u30C0\u30FC\u304C\u5FC5\u8981\u3067\u3059\u3002console \u306F\u958B\u767A\u74B0\u5883\u307E\u305F\u306F\u660E\u793A\u7684\u306A\u30C6\u30B9\u30C8\u30E2\u30FC\u30C9\u3067\u306E\u307F\u4F7F\u7528\u3067\u304D\u307E\u3059"
 };
 
 // messages/zh-CN.json
@@ -55,7 +111,14 @@ var zh_CN_default = {
   reach_providerNotFound: "Provider \u672A\u627E\u5230: {provider}",
   reach_providerRequired: "\u672A\u6307\u5B9A Provider\uFF0C\u8BF7\u5728\u6D88\u606F\u6216\u6A21\u677F\u4E2D\u8BBE\u7F6E provider \u5B57\u6BB5",
   reach_dndBlocked: "\u5F53\u524D\u5904\u4E8E\u514D\u6253\u6270\u65F6\u6BB5\uFF0C\u6D88\u606F\u5DF2\u4E22\u5F03",
-  reach_dndDeferred: "\u5F53\u524D\u5904\u4E8E\u514D\u6253\u6270\u65F6\u6BB5\uFF0C\u6D88\u606F\u5DF2\u6682\u5B58\u5F85\u53D1\u9001",
+  reach_dndPersistenceRequired: "\u542F\u7528\u514D\u6253\u6270\u5EF6\u8FDF\u53D1\u9001\u9700\u8981\u5148\u521D\u59CB\u5316\u6570\u636E\u5E93\u5E76\u786E\u4FDD\u961F\u5217\u8868\u53EF\u7528",
+  reach_dndEnqueueFailed: "\u6D88\u606F\u672A\u80FD\u53EF\u9760\u4FDD\u5B58\u5230\u5EF6\u8FDF\u961F\u5217\uFF0C\u8BF7\u7A0D\u540E\u91CD\u8BD5",
+  reach_sendRecordSaveFailed: "\u4FDD\u5B58\u89E6\u8FBE\u53D1\u9001\u8BB0\u5F55\u5931\u8D25",
+  reach_invalidStoredInteger: "\u53D1\u9001\u8BB0\u5F55\u7684 {field} \u4E0D\u662F\u5B89\u5168\u7684\u975E\u8D1F\u6574\u6570",
+  reach_claimLost: "\u6D88\u606F\u7684\u6709\u6548\u6295\u9012\u79DF\u7EA6\u5DF2\u4E22\u5931",
+  reach_unknownResolutionFailed: "\u672A\u77E5\u6295\u9012\u7ED3\u679C\u4E0D\u5B58\u5728\u6216\u5DF2\u88AB\u5176\u5B83\u64CD\u4F5C\u88C1\u5B9A",
+  reach_queueInputInvalid: "\u961F\u5217\u56DE\u6267\u6216\u4EBA\u5DE5\u88C1\u5B9A\u53C2\u6570\u65E0\u6548",
+  reach_deliveryUnknown: "\u5916\u90E8\u6295\u9012\u7ED3\u679C\u672A\u77E5\uFF0C\u9700\u8981\u4EBA\u5DE5\u6838\u5BF9\uFF0C\u5DF2\u505C\u6B62\u81EA\u52A8\u91CD\u53D1",
   reach_smsSendFailed: "\u77ED\u4FE1\u53D1\u9001\u5931\u8D25: {error}",
   reach_emailSendFailed: "\u90AE\u4EF6\u53D1\u9001\u5931\u8D25: {error}",
   reach_apiSendFailed: "API \u56DE\u8C03\u53D1\u9001\u5931\u8D25: {error}",
@@ -74,13 +137,17 @@ var zh_CN_default = {
   reach_config_providersRequired: "\u81F3\u5C11\u9700\u8981\u914D\u7F6E\u4E00\u4E2A Provider",
   reach_templateDbInitFailed: "\u6A21\u677F\u6570\u636E\u5E93\u521D\u59CB\u5316\u5931\u8D25: {error}",
   reach_templateSaveFailed: "\u6A21\u677F\u4FDD\u5B58\u5931\u8D25: {error}",
-  reach_templateDeleteFailed: "\u6A21\u677F\u5220\u9664\u5931\u8D25: {error}"
+  reach_templateDeleteFailed: "\u6A21\u677F\u5220\u9664\u5931\u8D25: {error}",
+  reach_queueRetryInvalid: "maxRetryDelayMs \u4E0D\u80FD\u5C0F\u4E8E retryDelayMs",
+  reach_deadRequeueFailed: "\u6B7B\u4FE1\u5DF2\u53D8\u5316\u6216\u4E0D\u5B58\u5728\uFF0C\u8BF7\u91CD\u65B0\u67E5\u8BE2\u540E\u6062\u590D",
+  reach_productionProviderRequired: "\u751F\u4EA7\u73AF\u5883\u5FC5\u987B\u914D\u7F6E\u771F\u5B9E\u89E6\u8FBE\u670D\u52A1\uFF1Bconsole \u4EC5\u53EF\u7528\u4E8E\u5F00\u53D1\u6216\u663E\u5F0F\u6D4B\u8BD5\u6A21\u5F0F"
 };
 
 // src/reach-i18n.ts
 var reachM = core.i18n.createMessageGetter({
   "zh-CN": zh_CN_default,
-  "en-US": en_US_default
+  "en-US": en_US_default,
+  "ja-JP": ja_JP_default
 });
 
 // src/reach-config.ts
@@ -132,7 +199,9 @@ var ApiProviderConfigSchema = z.object({
   /** 自定义请求头 */
   headers: z.record(z.string(), z.string()).optional(),
   /** 请求超时毫秒数（默认 10000） */
-  timeout: z.number().int().min(0).default(1e4)
+  timeout: z.number().int().min(0).default(1e4),
+  /** 接收端按 Idempotency-Key 原子持久去重，且覆盖所有重试与旧节点迟到请求时才启用；默认 false。 */
+  idempotent: z.boolean().default(false)
 });
 var ProviderConfigSchema = z.discriminatedUnion("type", [
   ConsoleProviderConfigSchema,
@@ -140,10 +209,33 @@ var ProviderConfigSchema = z.discriminatedUnion("type", [
   AliyunSmsProviderConfigSchema,
   ApiProviderConfigSchema
 ]);
+var ReachUnknownResolutionSchema = z.object({
+  status: z.enum(["sent", "discarded"]),
+  messageId: z.string().max(255).optional()
+});
+var ReachQueueIdSchema = z.string().uuid();
+var ReachQueueConfigSchema = z.object({
+  /** 自动领取次数上限（含首次及崩溃恢复，默认 5，范围 1–100）。 */
+  maxAttempts: z.number().int().min(1).max(100).default(5),
+  /** 首次失败后的退避毫秒数（默认 60000，范围 1000–86400000）。 */
+  retryDelayMs: z.number().int().min(1e3).max(864e5).default(6e4),
+  /** 指数退避上限毫秒数，不得小于 retryDelayMs（默认 3600000）。 */
+  maxRetryDelayMs: z.number().int().min(1e3).max(864e5).default(36e5)
+}).refine((value) => value.maxRetryDelayMs >= value.retryDelayMs, {
+  message: reachM("reach_queueRetryInvalid")
+});
+var ReachQueueListSchema = z.object({
+  status: z.enum(["dead", "unknown"]),
+  limit: z.number().int().min(1).max(100).default(50),
+  offset: z.number().int().min(0).max(1e6).default(0)
+});
+var ReachDeadRequeueSchema = z.object({
+  expectedUpdatedAt: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER - 1)
+});
 var DndConfigSchema = z.object({
   /** 是否启用免打扰（默认 false） */
   enabled: z.boolean().default(false),
-  /** 免打扰策略：discard 丢弃 / delay 延时发送（默认 discard） */
+  /** discard 丢弃；delay 要求数据库队列就绪并确认入队（默认 discard）。 */
   strategy: z.enum(["discard", "delay"]).default("discard"),
   /** 免打扰开始时间（HH:mm 格式） */
   start: z.string().regex(/^([01]\d|2[0-3]):[0-5]\d$/, reachM("reach_config_dndTimeInvalid")).default("00:00"),
@@ -166,7 +258,9 @@ var ReachConfigSchema = z.object({
   /** 模板配置（通过配置文件注册） */
   templates: z.array(TemplateConfigSchema).optional(),
   /** 免打扰配置 */
-  dnd: DndConfigSchema.optional()
+  dnd: DndConfigSchema.optional(),
+  /** 可靠队列重试策略；每条消息入队时持久保存。 */
+  queue: ReachQueueConfigSchema.prefault({})
 });
 var ReachErrorInfo = {
   SEND_FAILED: "001:500",
@@ -175,10 +269,10 @@ var ReachErrorInfo = {
   INVALID_RECIPIENT: "004:400",
   PROVIDER_NOT_FOUND: "005:500",
   DND_BLOCKED: "006:403",
-  DND_DEFERRED: "007:202",
   NOT_INITIALIZED: "010:500",
   UNSUPPORTED_TYPE: "011:400",
-  CONFIG_ERROR: "012:500"
+  CONFIG_ERROR: "012:500",
+  DELIVERY_REJECTED: "020:422"
 };
 var HaiReachError = core.error.buildHaiErrorsDef("reach", ReachErrorInfo);
 
@@ -209,6 +303,7 @@ function createAliyunSmsProvider() {
   let smsConfig = null;
   return {
     name: "aliyun-sms",
+    supportsIdempotency: false,
     async connect(config) {
       if (config.type !== "aliyun-sms") {
         return err(
@@ -295,6 +390,9 @@ function createApiProvider() {
   let apiConfig = null;
   return {
     name: "api",
+    get supportsIdempotency() {
+      return apiConfig?.idempotent === true;
+    },
     async connect(config) {
       if (config.type !== "api") {
         return err(
@@ -328,24 +426,26 @@ function createApiProvider() {
           body: message.body,
           template: message.template,
           vars: message.vars,
-          extra: message.extra
+          extra: message.extra,
+          idempotencyKey: message.idempotencyKey
         };
         const controller = new AbortController();
         const timeoutId = setTimeout(() => controller.abort(), apiConfig.timeout);
         try {
+          const headers = new Headers({ "Content-Type": "application/json", ...apiConfig.headers });
+          if (message.idempotencyKey)
+            headers.set("Idempotency-Key", message.idempotencyKey);
           const response = await fetch(apiConfig.url, {
             method: apiConfig.method,
-            headers: {
-              "Content-Type": "application/json",
-              ...apiConfig.headers
-            },
+            headers,
             body: JSON.stringify(payload),
             signal: controller.signal
           });
           if (!response.ok) {
             logger2.warn("API callback returned non-OK status", { status: response.status });
+            const rejected = response.status >= 400 && response.status < 500 && ![408, 425, 429].includes(response.status);
             return err(
-              HaiReachError.SEND_FAILED,
+              rejected ? HaiReachError.DELIVERY_REJECTED : HaiReachError.SEND_FAILED,
               reachM("reach_apiSendFailed", { params: { error: `HTTP ${response.status}` } })
             );
           }
@@ -367,6 +467,7 @@ function createConsoleProvider() {
   let connected = false;
   return {
     name: "console",
+    supportsIdempotency: true,
     async connect(_config) {
       connected = true;
       logger3.info("Console provider connected");
@@ -408,6 +509,7 @@ function createSmtpProvider() {
   let smtpConfig = null;
   return {
     name: "smtp",
+    supportsIdempotency: false,
     async connect(config) {
       if (config.type !== "smtp") {
         return err(
@@ -468,7 +570,92 @@ function createSmtpProvider() {
     }
   };
 }
-var logger5 = core.logger.child({ module: "reach", scope: "send" });
+var logger5 = core.logger.child({ module: "reach", scope: "delivery" });
+var DEFAULT_LEASE_MS = 10 * 60 * 1e3;
+async function deliverClaimedMessage(row, owner, provider, repo, leaseMs = DEFAULT_LEASE_MS) {
+  const retrySafe = provider.supportsIdempotency;
+  if (!row.queueId || row.retrySafe && !retrySafe) {
+    await repo.markUnknown(row.id, owner);
+    return err(HaiReachError.SEND_FAILED, reachM("reach_deliveryUnknown"));
+  }
+  if (!provider.isConnected()) {
+    await repo.failClaim(row, owner, "provider_unavailable");
+    return err(HaiReachError.NOT_INITIALIZED, reachM("reach_notInitialized"));
+  }
+  let message;
+  try {
+    message = {
+      provider: row.provider,
+      to: row.toAddr,
+      subject: row.subject ?? void 0,
+      body: row.body ?? void 0,
+      template: row.template ?? void 0,
+      vars: row.varsJson ? JSON.parse(row.varsJson) : void 0,
+      extra: row.extraJson ? JSON.parse(row.extraJson) : void 0,
+      idempotencyKey: row.queueId
+    };
+  } catch (cause) {
+    await repo.failClaim(row, owner, "invalid_message", true);
+    return err(HaiReachError.SEND_FAILED, reachM("reach_sendRecordSaveFailed"), cause);
+  }
+  const started = await repo.beginDelivery(row.id, owner, retrySafe, leaseMs);
+  if (!started.success)
+    return started;
+  let stopped = false;
+  let lost = false;
+  let renewing;
+  let timer;
+  const renew = async () => {
+    try {
+      const result = await repo.renewClaim(row.id, owner, leaseMs);
+      lost = !result.success;
+    } catch {
+      lost = true;
+    }
+    if (!stopped && !lost) {
+      timer = setTimeout(() => {
+        renewing = renew();
+      }, Math.max(1, Math.floor(leaseMs / 3)));
+    }
+  };
+  timer = setTimeout(() => {
+    renewing = renew();
+  }, Math.max(1, Math.floor(leaseMs / 3)));
+  let outcome;
+  try {
+    outcome = await provider.send(message);
+  } catch (cause) {
+    outcome = err(HaiReachError.SEND_FAILED, reachM("reach_deliveryUnknown"), cause);
+  } finally {
+    stopped = true;
+    clearTimeout(timer);
+    await renewing;
+  }
+  if (lost) {
+    if (!retrySafe)
+      await repo.markUnknown(row.id, owner);
+    return err(HaiReachError.SEND_FAILED, reachM("reach_claimLost"));
+  }
+  if (outcome.success && outcome.data.success) {
+    const marked = await repo.markSent(row.id, owner, outcome.data.messageId);
+    if (!marked.success && !retrySafe)
+      await repo.markUnknown(row.id, owner);
+    return marked;
+  }
+  if (!retrySafe) {
+    await repo.markUnknown(row.id, owner);
+    logger5.warn("Delivery outcome is unknown; automatic redelivery stopped", { queueId: row.queueId, provider: row.provider });
+    return err(HaiReachError.SEND_FAILED, reachM("reach_deliveryUnknown"), outcome.success ? void 0 : outcome.error);
+  }
+  const permanent = !outcome.success && [HaiReachError.DELIVERY_REJECTED.code, HaiReachError.INVALID_RECIPIENT.code].includes(outcome.error.code);
+  const released = await repo.failClaim(row, owner, permanent ? "permanent_rejection" : "transient_failure", permanent);
+  if (!released.success)
+    return released;
+  return err(HaiReachError.SEND_FAILED, reachM("reach_deliveryUnknown"), outcome.success ? void 0 : outcome.error);
+}
+
+// src/reach-send.ts
+var logger6 = core.logger.child({ module: "reach", scope: "send" });
 var FLUSH_LOCK_KEY = "hai:reach:flush-pending";
 var FLUSH_LOCK_TTL = 300;
 var FLUSH_BATCH_SIZE = 100;
@@ -520,12 +707,10 @@ async function preprocessMessage(message, templateRegistry2) {
   };
   return ok(processed);
 }
-async function saveSendRecord(repo, message, status, provider, messageId) {
-  if (!repo) {
-    return;
-  }
+async function saveSendRecord(repo, message, status, provider, messageId, queueId, queueConfig) {
   try {
-    await repo.create({
+    const inserted = await repo.create({
+      queueId: queueId ?? null,
       provider,
       toAddr: message.to,
       subject: message.subject ?? null,
@@ -534,11 +719,17 @@ async function saveSendRecord(repo, message, status, provider, messageId) {
       varsJson: message.vars ? JSON.stringify(message.vars) : null,
       extraJson: message.extra ? JSON.stringify(message.extra) : null,
       status,
+      ...queueConfig,
       messageId: messageId ?? null,
       createdAt: Date.now()
     });
-  } catch {
-    logger5.debug("Send record not saved (db module unavailable)");
+    if (!inserted.success)
+      return inserted;
+    if (inserted.data.changes !== 1)
+      return err(HaiReachError.SEND_FAILED, reachM("reach_sendRecordSaveFailed"));
+    return ok(void 0);
+  } catch (cause) {
+    return err(HaiReachError.SEND_FAILED, reachM("reach_sendRecordSaveFailed"), cause);
   }
 }
 var dndTimer = null;
@@ -549,11 +740,14 @@ function startDndScheduler(dndConfig2, providers2, repo) {
     return;
   }
   schedulerContext = { dndConfig: dndConfig2, providers: providers2, repo };
+  const context = schedulerContext;
   if (!isDndBlocked(dndConfig2)) {
     flushPendingMessages(providers2, repo).catch((error) => {
-      logger5.warn("Failed to flush pending messages on init", { error });
+      logger6.warn("Failed to flush pending messages on init", { error });
+    }).finally(() => {
+      if (schedulerContext === context)
+        scheduleDndCheck();
     });
-    scheduleDndCheck();
     return;
   }
   scheduleFlushAtDndEnd();
@@ -561,30 +755,38 @@ function startDndScheduler(dndConfig2, providers2, repo) {
 function scheduleFlushAtDndEnd() {
   if (!schedulerContext)
     return;
-  const { dndConfig: dndConfig2, providers: providers2, repo } = schedulerContext;
+  const context = schedulerContext;
+  const { dndConfig: dndConfig2, providers: providers2, repo } = context;
   const delayMs = msUntilDndEnd(dndConfig2);
-  logger5.info("DND scheduler started", { delayMs, dndEnd: dndConfig2.end });
+  logger6.info("DND scheduler started", { delayMs, dndEnd: dndConfig2.end });
   dndTimer = setTimeout(() => {
-    logger5.info("DND period ended, flushing pending messages");
+    if (schedulerContext !== context)
+      return;
+    logger6.info("DND period ended, flushing pending messages");
     flushPendingMessages(providers2, repo).catch((error) => {
-      logger5.error("Failed to flush pending messages", { error });
+      logger6.error("Failed to flush pending messages", { error });
     }).finally(() => {
-      scheduleDndCheck();
+      if (schedulerContext === context)
+        scheduleDndCheck();
     });
   }, delayMs);
 }
 function scheduleDndCheck() {
   if (!schedulerContext)
     return;
-  const { dndConfig: dndConfig2 } = schedulerContext;
+  const context = schedulerContext;
+  const { dndConfig: dndConfig2, providers: providers2, repo } = context;
   const CHECK_INTERVAL = 60 * 1e3;
   dndTimer = setTimeout(() => {
-    if (!schedulerContext)
+    if (schedulerContext !== context)
       return;
     if (isDndBlocked(dndConfig2)) {
       scheduleFlushAtDndEnd();
     } else {
-      scheduleDndCheck();
+      flushPendingMessages(providers2, repo).catch((error) => logger6.warn("Failed to recover pending messages", { error })).finally(() => {
+        if (schedulerContext === context)
+          scheduleDndCheck();
+      });
     }
   }, CHECK_INTERVAL);
 }
@@ -602,94 +804,59 @@ async function flushPendingMessages(providers2, repo) {
   if (!repo) {
     return;
   }
-  let lockAcquired = false;
-  const flushOwner = `${reachNodeId}:${Date.now()}`;
+  let lockOwner = null;
+  const flushOwner = `${reachNodeId}:${crypto.randomUUID()}`;
   if (cache.isInitialized) {
-    const lockResult = await cache.lock.acquire(FLUSH_LOCK_KEY, { ttl: FLUSH_LOCK_TTL, owner: reachNodeId });
+    const lockResult = await cache.lock.acquire(FLUSH_LOCK_KEY, { ttl: FLUSH_LOCK_TTL });
     if (!lockResult.success) {
-      logger5.warn("Failed to acquire flush lock, continuing with row claims only", { error: lockResult.error.message });
+      logger6.warn("Failed to acquire flush lock, continuing with row claims only", { error: lockResult.error.message });
     } else if (!lockResult.data) {
-      logger5.info("Skipping flush, another node holds the lock");
+      logger6.info("Skipping flush, another node holds the lock");
       return;
     } else {
-      lockAcquired = true;
+      lockOwner = lockResult.data;
     }
   }
   try {
-    while (true) {
+    const eligibleBefore = Date.now();
+    for (let processed = 0; processed < FLUSH_BATCH_SIZE; processed += 1) {
       const claimResult = await repo.claimPendingBatch(flushOwner, {
-        limit: FLUSH_BATCH_SIZE,
-        lockMs: FLUSH_CLAIM_LOCK_MS
+        limit: 1,
+        lockMs: FLUSH_CLAIM_LOCK_MS,
+        eligibleBefore
       });
       if (!claimResult.success) {
-        logger5.warn("Failed to claim pending messages", { error: claimResult.error.message });
+        logger6.warn("Failed to claim pending messages", { error: claimResult.error.message });
         return;
       }
       if (claimResult.data.length === 0) {
         return;
       }
-      logger5.debug("Flushing pending messages", { count: claimResult.data.length });
+      logger6.debug("Flushing pending messages", { count: claimResult.data.length });
       for (const row of claimResult.data) {
         const provider = providers2.get(row.provider);
         if (!provider) {
-          logger5.warn("Provider not found for pending message, releasing claim", { provider: row.provider, id: row.id });
-          const releaseResult2 = await repo.releaseClaim(row.id, flushOwner);
-          if (!releaseResult2.success) {
-            logger5.warn("Failed to release pending message claim", { id: row.id, error: releaseResult2.error.message });
-          }
-          continue;
-        }
-        let vars;
-        let extra;
-        try {
-          vars = row.varsJson ? JSON.parse(row.varsJson) : void 0;
-          extra = row.extraJson ? JSON.parse(row.extraJson) : void 0;
-        } catch {
-          logger5.warn("Failed to parse pending message JSON, releasing claim", { id: row.id });
-          const releaseResult2 = await repo.releaseClaim(row.id, flushOwner);
-          if (!releaseResult2.success) {
-            logger5.warn("Failed to release pending message claim", { id: row.id, error: releaseResult2.error.message });
+          logger6.warn("Provider not found for pending message, releasing claim", { provider: row.provider, id: row.id });
+          const releaseResult = await repo.failClaim(row, flushOwner, "provider_unavailable");
+          if (!releaseResult.success) {
+            logger6.warn("Failed to release pending message claim", { id: row.id, error: releaseResult.error.message });
           }
           continue;
         }
-        const message = {
-          provider: row.provider,
-          to: row.toAddr,
-          subject: row.subject ?? void 0,
-          body: row.body ?? void 0,
-          template: row.template ?? void 0,
-          vars,
-          extra
-        };
-        const sendResult = await provider.send(message);
-        if (sendResult.success) {
-          const markResult = await repo.markSent(row.id, sendResult.data.messageId, void 0, flushOwner);
-          if (!markResult.success) {
-            logger5.warn("Failed to mark pending message as sent", { id: row.id, error: markResult.error.message });
-            continue;
-          }
-          logger5.debug("Pending message sent", { id: row.id, to: row.toAddr, provider: row.provider });
-          continue;
-        }
-        const releaseResult = await repo.releaseClaim(row.id, flushOwner);
-        if (!releaseResult.success) {
-          logger5.warn("Failed to release pending message claim after send failure", { id: row.id, error: releaseResult.error.message });
-        }
-        logger5.warn("Pending message send failed", { id: row.id, to: row.toAddr, error: sendResult.error.code });
-      }
-      if (claimResult.data.length < FLUSH_BATCH_SIZE) {
-        return;
+        const sent = await deliverClaimedMessage(row, flushOwner, provider, repo, FLUSH_CLAIM_LOCK_MS);
+        if (!sent.success)
+          logger6.warn("Pending message delivery did not commit", { id: row.id, code: sent.error.code });
       }
     }
   } finally {
-    if (lockAcquired) {
-      await cache.lock.release(FLUSH_LOCK_KEY, reachNodeId).catch((error) => {
-        logger5.warn("Failed to release flush lock", { error });
+    if (lockOwner) {
+      await cache.lock.release(FLUSH_LOCK_KEY, lockOwner).catch((error) => {
+        logger6.warn("Failed to release flush lock", { error });
       });
     }
   }
 }
-async function executeSend(message, providers2, templateRegistry2, dndConfig2, repo) {
+async function executeSend(message, providers2, templateRegistry2, dndConfig2, repo, queueConfig = ReachQueueConfigSchema.parse({})) {
   if (!message.to) {
     return err(
       HaiReachError.INVALID_RECIPIENT,
@@ -716,43 +883,48 @@ async function executeSend(message, providers2, templateRegistry2, dndConfig2, r
   if (isDndBlocked(dndConfig2)) {
     const strategy = dndConfig2?.strategy ?? "discard";
     if (strategy === "delay") {
-      logger5.info("Message deferred by DND (delay strategy)", { provider: providerName, to: message.to });
-      try {
-        await saveSendRecord(repo ?? null, preprocessed.data, "pending", providerName);
-      } catch (error) {
-        logger5.warn("Failed to save deferred message to DB", { provider: providerName, to: message.to, error });
+      if (!repo)
+        return err(HaiReachError.SEND_FAILED, reachM("reach_dndPersistenceRequired"));
+      const queueId = crypto.randomUUID();
+      const saved = await saveSendRecord(repo, preprocessed.data, "pending", providerName, void 0, queueId, queueConfig);
+      if (!saved.success) {
+        logger6.warn("Failed to persist deferred message", { provider: providerName, code: saved.error.code });
         return err(
           HaiReachError.SEND_FAILED,
-          reachM("reach_dndDeferred"),
-          error
+          reachM("reach_dndEnqueueFailed"),
+          saved.error
         );
       }
-      return ok({ success: true, deferred: true });
+      logger6.info("Message persisted for DND delivery", { provider: providerName, queueId });
+      return ok({ success: true, deferred: true, queueId });
     }
-    logger5.info("Message blocked by DND (discard strategy)", { provider: providerName, to: message.to });
+    logger6.info("Message blocked by DND (discard strategy)", { provider: providerName, to: message.to });
     return err(
       HaiReachError.DND_BLOCKED,
       reachM("reach_dndBlocked")
     );
   }
   const provider = providers2.get(providerName);
-  logger5.debug("Sending message", {
+  logger6.debug("Sending message", {
     provider: providerName,
     to: preprocessed.data.to,
     template: message.template
   });
   const result = await provider.send(preprocessed.data);
   if (!result.success) {
-    logger5.warn("Message send failed", {
+    logger6.warn("Message send failed", {
       provider: providerName,
       to: message.to,
       error: result.error.code
     });
     return result;
   }
-  saveSendRecord(repo ?? null, preprocessed.data, "sent", providerName, result.data.messageId).catch((error) => {
-    logger5.warn("Failed to save send record", { provider: providerName, to: message.to, error });
-  });
+  if (repo) {
+    void saveSendRecord(repo, preprocessed.data, "sent", providerName, result.data.messageId).then((saved) => {
+      if (!saved.success)
+        logger6.warn("Failed to persist sent message log", { provider: providerName, code: saved.error.code });
+    });
+  }
   return result;
 }
 function renderString(template, vars) {
@@ -850,7 +1022,10 @@ function createTemplateRegistry(repo) {
 var TABLE_NAME = "hai_reach_send_log";
 var DEFAULT_CLAIM_BATCH_SIZE = 100;
 var DEFAULT_CLAIM_LOCK_MS = 10 * 60 * 1e3;
-var CLAIMABLE_STATUS_WHERE = "(status = ? OR (status = ? AND (locked_until IS NULL OR locked_until < ?)))";
+var CLAIMABLE_STATUS_WHERE = "(attempt_count < max_attempts AND ((status = ? AND next_attempt_at <= ?) OR (status = ? AND updated_at < ? AND (locked_until IS NULL OR locked_until <= ?)) OR (status = ? AND updated_at < ? AND retry_safe = TRUE AND locked_until <= ?)))";
+function claimableParams(now, eligibleBefore = now) {
+  return ["pending", eligibleBefore, "processing", eligibleBefore, now, "sending", eligibleBefore, now];
+}
 function buildSendLogError(detail, cause) {
   return err(
     HaiReachError.SEND_FAILED,
@@ -858,7 +1033,69 @@ function buildSendLogError(detail, cause) {
     cause
   );
 }
+function normalizeSendLog(row) {
+  const normalized = { ...row };
+  for (const field of ["id", "createdAt", "updatedAt", "lockedUntil", "nextAttemptAt", "attemptCount", "maxAttempts", "retryDelayMs", "maxRetryDelayMs"]) {
+    const value = row[field];
+    if (value === void 0 && (field === "updatedAt" || field === "lockedUntil"))
+      continue;
+    const validType = typeof value === "number" || typeof value === "bigint" || typeof value === "string" && /^\d+$/.test(value);
+    const integer = validType ? Number(value) : Number.NaN;
+    if (!Number.isSafeInteger(integer) || integer < 0)
+      return buildSendLogError(reachM("reach_invalidStoredInteger", { params: { field } }));
+    Object.assign(normalized, { [field]: integer });
+  }
+  return ok(normalized);
+}
+function normalizeSendLogs(rows) {
+  const normalized = [];
+  for (const row of rows) {
+    const result = normalizeSendLog(row);
+    if (!result.success)
+      return result;
+    normalized.push(result.data);
+  }
+  return ok(normalized);
+}
 var SEND_LOG_FIELDS = [
+  ...[
+    { fieldName: "attemptCount", columnName: "attempt_count", value: 0 },
+    { fieldName: "maxAttempts", columnName: "max_attempts", value: 5 },
+    { fieldName: "retryDelayMs", columnName: "retry_delay_ms", value: 6e4 },
+    { fieldName: "maxRetryDelayMs", columnName: "max_retry_delay_ms", value: 36e5 },
+    { fieldName: "nextAttemptAt", columnName: "next_attempt_at", value: 0 }
+  ].map(({ fieldName, columnName, value }) => ({
+    fieldName,
+    columnName,
+    def: { type: "BIGINT", notNull: true, defaultValue: value },
+    select: true,
+    create: true,
+    update: true
+  })),
+  {
+    fieldName: "lastFailure",
+    columnName: "last_failure",
+    def: { type: "TEXT" },
+    select: true,
+    create: true,
+    update: true
+  },
+  {
+    fieldName: "retrySafe",
+    columnName: "retry_safe",
+    def: { type: "BOOLEAN", notNull: true, defaultValue: false },
+    select: true,
+    create: true,
+    update: true
+  },
+  {
+    fieldName: "queueId",
+    columnName: "queue_id",
+    def: { type: "TEXT", unique: true },
+    select: true,
+    create: true,
+    update: false
+  },
   {
     fieldName: "id",
     columnName: "id",
@@ -950,7 +1187,7 @@ var SEND_LOG_FIELDS = [
   {
     fieldName: "lockedUntil",
     columnName: "locked_until",
-    def: { type: "INTEGER" },
+    def: { type: "BIGINT" },
     select: true,
     create: true,
     update: true
@@ -958,7 +1195,7 @@ var SEND_LOG_FIELDS = [
   {
     fieldName: "createdAt",
     columnName: "created_at",
-    def: { type: "TIMESTAMP", notNull: true },
+    def: { type: "BIGINT", notNull: true },
     select: true,
     create: true,
     update: false
@@ -966,7 +1203,7 @@ var SEND_LOG_FIELDS = [
   {
     fieldName: "updatedAt",
     columnName: "updated_at",
-    def: { type: "INTEGER", notNull: true },
+    def: { type: "BIGINT", notNull: true },
     select: true,
     create: true,
     update: true
@@ -1004,6 +1241,31 @@ var DbSendLogRepository = class extends BaseReldbCrudRepository {
       createTableIfNotExists: true
     });
   }
+  /** 单条可空查询统一返回经过校验的毫秒 number。 */
+  async findById(id, tx) {
+    const result = await super.findById(id, tx);
+    if (!result.success || result.data === null)
+      return result;
+    return normalizeSendLog(result.data);
+  }
+  /** 单条必需查询统一返回经过校验的毫秒 number。 */
+  async getById(id, tx) {
+    const result = await super.getById(id, tx);
+    return result.success ? normalizeSendLog(result.data) : result;
+  }
+  /** 普通列表与 claim 回读共用同一 BIGINT 转换边界。 */
+  async findAll(options, tx) {
+    const result = await super.findAll(options, tx);
+    return result.success ? normalizeSendLogs(result.data) : result;
+  }
+  /** 分页结果同样拒绝不安全的时间值，不返回经过舍入的毫秒数。 */
+  async findPage(options, tx) {
+    const result = await super.findPage(options, tx);
+    if (!result.success)
+      return result;
+    const rows = normalizeSendLogs(result.data.items);
+    return rows.success ? ok({ ...result.data, items: rows.data }) : rows;
+  }
   /** 获取所有待发送记录 */
   async findPending(tx) {
     const result = await this.findAll({ where: "status = ?", params: ["pending"], orderBy: "created_at ASC" }, tx);
@@ -1020,7 +1282,7 @@ var DbSendLogRepository = class extends BaseReldbCrudRepository {
    * - 并发事务会直接跳过这些行，而不是重复命中同一批记录
    * - 在 commit 前不会暴露给其它节点重复 claim
    */
-  async claimPendingIdsWithRowLocks(tx, owner, now, lockedUntil, limit) {
+  async claimPendingIdsWithRowLocks(tx, owner, now, lockedUntil, limit, eligibleBefore) {
     const lockedRowsResult = await tx.query(
       `SELECT id
        FROM ${TABLE_NAME}
@@ -1028,14 +1290,14 @@ var DbSendLogRepository = class extends BaseReldbCrudRepository {
        ORDER BY created_at ASC
        LIMIT ?
        FOR UPDATE SKIP LOCKED`,
-      ["pending", "processing", now, limit]
+      [...claimableParams(now, eligibleBefore), limit]
     );
     if (!lockedRowsResult.success) {
       throw lockedRowsResult.error;
     }
     const claimedIds = lockedRowsResult.data.map((row) => {
       const id = typeof row.id === "number" ? row.id : Number(row.id);
-      if (!Number.isInteger(id)) {
+      if (!Number.isSafeInteger(id)) {
         throw new TypeError(`Invalid send log id returned when claiming pending batch: ${String(row.id)}`);
       }
       return id;
@@ -1046,7 +1308,7 @@ var DbSendLogRepository = class extends BaseReldbCrudRepository {
     const placeholders = claimedIds.map(() => "?").join(", ");
     const updateResult = await tx.execute(
       `UPDATE ${TABLE_NAME}
-       SET status = ?, processing_owner = ?, locked_until = ?, updated_at = ?
+       SET status = ?, processing_owner = ?, locked_until = ?, updated_at = ?, attempt_count = attempt_count + 1
        WHERE id IN (${placeholders})`,
       ["processing", owner, lockedUntil, now, ...claimedIds]
     );
@@ -1062,10 +1324,10 @@ var DbSendLogRepository = class extends BaseReldbCrudRepository {
    * 即使多个节点读到了同一候选，只有第一个满足条件的 UPDATE 会成功，
    * 从而避免同一行被两个节点同时 claim。
    */
-  async claimPendingIdsWithConditionalUpdates(tx, owner, now, lockedUntil, limit) {
+  async claimPendingIdsWithConditionalUpdates(tx, owner, now, lockedUntil, limit, eligibleBefore) {
     const candidatesResult = await this.findAll({
       where: CLAIMABLE_STATUS_WHERE,
-      params: ["pending", "processing", now],
+      params: claimableParams(now, eligibleBefore),
       orderBy: "created_at ASC",
       limit
     }, tx);
@@ -1076,9 +1338,9 @@ var DbSendLogRepository = class extends BaseReldbCrudRepository {
     for (const row of candidatesResult.data) {
       const updateResult = await tx.execute(
         `UPDATE ${TABLE_NAME}
-         SET status = ?, processing_owner = ?, locked_until = ?, updated_at = ?
+         SET status = ?, processing_owner = ?, locked_until = ?, updated_at = ?, attempt_count = attempt_count + 1
          WHERE id = ? AND ${CLAIMABLE_STATUS_WHERE}`,
-        ["processing", owner, lockedUntil, now, row.id, "pending", "processing", now]
+        ["processing", owner, lockedUntil, now, row.id, ...claimableParams(now, eligibleBefore)]
       );
       if (!updateResult.success) {
         throw updateResult.error;
@@ -1108,6 +1370,7 @@ var DbSendLogRepository = class extends BaseReldbCrudRepository {
     const limit = options?.limit ?? DEFAULT_CLAIM_BATCH_SIZE;
     const lockMs = options?.lockMs ?? DEFAULT_CLAIM_LOCK_MS;
     const lockedUntil = now + lockMs;
+    const eligibleBefore = Math.min(now, options?.eligibleBefore ?? now);
     const dbType = this.db.config?.type;
     const txResult = await this.db.tx.begin();
     if (!txResult.success) {
@@ -1115,7 +1378,24 @@ var DbSendLogRepository = class extends BaseReldbCrudRepository {
     }
     const tx = txResult.data;
     try {
-      const claimedIds = dbType === "postgresql" || dbType === "mysql" ? await this.claimPendingIdsWithRowLocks(tx, owner, now, lockedUntil, limit) : await this.claimPendingIdsWithConditionalUpdates(tx, owner, now, lockedUntil, limit);
+      const unknown = await tx.execute(
+        `UPDATE ${TABLE_NAME} SET status = ?, processing_owner = NULL, locked_until = NULL, next_attempt_at = 0, updated_at = ?
+         WHERE status = ? AND retry_safe = FALSE AND (locked_until IS NULL OR locked_until <= ?)`,
+        ["unknown", now, "sending", now]
+      );
+      if (!unknown.success)
+        throw unknown.error;
+      const exhausted = await tx.execute(
+        `UPDATE ${TABLE_NAME}
+         SET status = ?, last_failure = ?, processing_owner = NULL, locked_until = NULL, next_attempt_at = 0, updated_at = ?
+         WHERE attempt_count >= max_attempts
+           AND (status = ? OR (status = ? AND (locked_until IS NULL OR locked_until <= ?))
+             OR (status = ? AND retry_safe = TRUE AND locked_until <= ?))`,
+        ["dead", "attempts_exhausted", now, "pending", "processing", now, "sending", now]
+      );
+      if (!exhausted.success)
+        throw exhausted.error;
+      const claimedIds = dbType === "postgresql" || dbType === "mysql" ? await this.claimPendingIdsWithRowLocks(tx, owner, now, lockedUntil, limit, eligibleBefore) : await this.claimPendingIdsWithConditionalUpdates(tx, owner, now, lockedUntil, limit, eligibleBefore);
       if (claimedIds.length === 0) {
         const commitResult2 = await tx.commit();
         if (!commitResult2.success) {
@@ -1134,43 +1414,95 @@ var DbSendLogRepository = class extends BaseReldbCrudRepository {
       return buildSendLogError(error instanceof Error ? error.message : String(error), error);
     }
   }
-  /** 释放一条已 claim 的记录，供后续批次重新发送 */
+  /** 显式取消未完成的领取；仍按失败退避，避免调用方绕过自动重试预算。 */
   async releaseClaim(id, owner, tx) {
+    const row = await this.getById(id, tx);
+    if (!row.success)
+      return row;
+    return this.failClaim(row.data, owner, "transient_failure", false, tx);
+  }
+  /** 失败提交与 owner、次数和有效租约同时比较，旧 worker 不能更改新领取的退避策略。 */
+  async failClaim(row, owner, reason, permanent = false, tx) {
     const now = Date.now();
+    const dead = permanent || row.attemptCount >= row.maxAttempts;
+    const delay = Math.min(row.maxRetryDelayMs, row.retryDelayMs * 2 ** Math.min(row.attemptCount - 1, 30));
     const result = await this.sql(tx).execute(
       `UPDATE ${TABLE_NAME}
-       SET status = ?, processing_owner = NULL, locked_until = NULL, updated_at = ?
-       WHERE id = ? AND status = ? AND processing_owner = ?`,
-      ["pending", now, id, "processing", owner]
+       SET status = ?, last_failure = ?, next_attempt_at = ?, processing_owner = NULL, locked_until = NULL, updated_at = ?
+       WHERE id = ? AND processing_owner = ? AND locked_until > ? AND attempt_count = ?
+         AND (status = ? OR (status = ? AND retry_safe = TRUE))`,
+      [dead ? "dead" : "pending", reason, dead ? 0 : now + delay, now, row.id, owner, now, row.attemptCount, "processing", "sending"]
     );
     if (!result.success) {
       return buildSendLogError(result.error.message, result.error);
     }
     if (result.data.changes === 0) {
-      return buildSendLogError(`Send log ${id} claim is no longer owned by ${owner}`);
+      return buildSendLogError(reachM("reach_claimLost"));
     }
     return ok(void 0);
   }
-  /** 将记录标记为已发送 */
-  async markSent(id, messageId, tx, owner) {
+  /** 仅当前 dead 版本可以恢复；保留 queueId，迟到的幂等 API 请求仍使用同一键。 */
+  async requeueDead(queueId, expectedUpdatedAt) {
+    const now = Math.max(Date.now(), expectedUpdatedAt + 1);
+    const result = await this.sql().execute(
+      `UPDATE ${TABLE_NAME} SET status = ?, attempt_count = 0, next_attempt_at = ?, last_failure = NULL, updated_at = ?
+       WHERE queue_id = ? AND status = ? AND updated_at = ?`,
+      ["pending", now, now, queueId, "dead", expectedUpdatedAt]
+    );
+    return result.success && result.data.changes === 1 ? ok(void 0) : buildSendLogError(reachM("reach_deadRequeueFailed"));
+  }
+  /** 发送前持久化门闩；仅有效租约可从 processing 进入 sending。 */
+  async beginDelivery(id, owner, retrySafe, lockMs = DEFAULT_CLAIM_LOCK_MS) {
+    const now = Date.now();
+    const flag = this.db.config?.type === "postgresql" ? retrySafe : Number(retrySafe);
+    const result = await this.sql().execute(
+      `UPDATE ${TABLE_NAME} SET status = ?, retry_safe = ?, locked_until = ?, updated_at = ?
+       WHERE id = ? AND status = ? AND processing_owner = ? AND locked_until > ?`,
+      ["sending", flag, now + lockMs, now, id, "processing", owner, now]
+    );
+    return result.success && result.data.changes === 1 ? ok(void 0) : buildSendLogError(reachM("reach_claimLost"));
+  }
+  /** 续租不接受已经过期的 owner，防止暂停的旧进程恢复后重新取得发送权。 */
+  async renewClaim(id, owner, lockMs = DEFAULT_CLAIM_LOCK_MS) {
+    const now = Date.now();
+    const result = await this.sql().execute(
+      `UPDATE ${TABLE_NAME} SET locked_until = ?, updated_at = ?
+       WHERE id = ? AND processing_owner = ? AND status IN (?, ?) AND locked_until > ?`,
+      [now + lockMs, now, id, owner, "processing", "sending", now]
+    );
+    return result.success && result.data.changes === 1 ? ok(void 0) : buildSendLogError(reachM("reach_claimLost"));
+  }
+  /** 未知结果只能停止自动处理，不推断外部副作用已撤销。 */
+  async markUnknown(id, owner) {
+    const result = await this.sql().execute(
+      `UPDATE ${TABLE_NAME} SET status = ?, processing_owner = NULL, locked_until = NULL, next_attempt_at = 0, updated_at = ?
+       WHERE id = ? AND processing_owner = ? AND status IN (?, ?)`,
+      ["unknown", Date.now(), id, owner, "processing", "sending"]
+    );
+    return result.success && result.data.changes === 1 ? ok(void 0) : buildSendLogError(reachM("reach_claimLost"));
+  }
+  /** 人工裁定的条件提交，不提供重新排队或重新发送操作。 */
+  async resolveUnknown(queueId, resolution) {
+    const result = await this.sql().execute(
+      `UPDATE ${TABLE_NAME} SET status = ?, message_id = ?, next_attempt_at = 0, updated_at = ? WHERE queue_id = ? AND status = ?`,
+      [resolution.status, resolution.messageId ?? null, Date.now(), queueId, "unknown"]
+    );
+    return result.success && result.data.changes === 1 ? ok(void 0) : buildSendLogError(reachM("reach_unknownResolutionFailed"));
+  }
+  /** 只有仍持有 sending 有效租约的 owner 可以确认投递。 */
+  async markSent(id, owner, messageId, tx) {
     const now = Date.now();
-    const params = ["sent", messageId ?? null, now, id];
-    let whereClause = "id = ?";
-    if (owner) {
-      whereClause += " AND status = ? AND processing_owner = ?";
-      params.push("processing", owner);
-    }
     const result = await this.sql(tx).execute(
       `UPDATE ${TABLE_NAME}
-       SET status = ?, message_id = ?, processing_owner = NULL, locked_until = NULL, updated_at = ?
-       WHERE ${whereClause}`,
-      params
+       SET status = ?, message_id = ?, processing_owner = NULL, locked_until = NULL, next_attempt_at = 0, updated_at = ?
+       WHERE id = ? AND status = ? AND processing_owner = ? AND locked_until > ?`,
+      ["sent", messageId ?? null, now, id, "sending", owner, now]
     );
     if (!result.success) {
       return buildSendLogError(result.error.message, result.error);
     }
-    if (owner && result.data.changes === 0) {
-      return buildSendLogError(`Send log ${id} claim is no longer owned by ${owner}`);
+    if (result.data.changes === 0) {
+      return buildSendLogError(reachM("reach_claimLost"));
     }
     return ok(void 0);
   }
@@ -1347,7 +1679,7 @@ var DbTemplateRepository = class extends BaseReldbCrudRepository {
 };
 
 // src/reach-main.ts
-var logger6 = core.logger.child({ module: "reach", scope: "main" });
+var logger7 = core.logger.child({ module: "reach", scope: "main" });
 var providers = /* @__PURE__ */ new Map();
 var currentConfig = null;
 var dndConfig;
@@ -1378,12 +1710,12 @@ async function tryInitSendLogRepo() {
     }
     const result = await createSendLogRepository(db);
     if (!result.success) {
-      logger6.debug("Send log repository not initialized", { error: result.error.message });
+      logger7.debug("Send log repository not initialized", { error: result.error.message });
       return null;
     }
     return result.data;
   } catch (error) {
-    logger6.debug("Send log repository not initialized", { error: error instanceof Error ? error.message : String(error) });
+    logger7.debug("Send log repository not initialized", { error: error instanceof Error ? error.message : String(error) });
     return null;
   }
 }
@@ -1395,12 +1727,12 @@ async function tryInitTemplateRepo() {
     }
     const result = await createTemplateRepository(db);
     if (!result.success) {
-      logger6.debug("Template repository not initialized", { error: result.error.message });
+      logger7.debug("Template repository not initialized", { error: result.error.message });
       return null;
     }
     return result.data;
   } catch (error) {
-    logger6.debug("Template repository not initialized", { error: error instanceof Error ? error.message : String(error) });
+    logger7.debug("Template repository not initialized", { error: error instanceof Error ? error.message : String(error) });
     return null;
   }
 }
@@ -1410,15 +1742,15 @@ var notInitialized = core.module.createNotInitializedKit(
 );
 async function doClose() {
   if (providers.size === 0 && currentConfig === null) {
-    logger6.info("Reach module already closed, skipping");
+    logger7.info("Reach module already closed, skipping");
     return;
   }
-  logger6.info("Closing reach module");
+  logger7.info("Closing reach module");
   for (const [name, provider] of providers.entries()) {
     try {
       await provider.close();
     } catch (error) {
-      logger6.error("Provider close failed", { name, error });
+      logger7.error("Provider close failed", { name, error });
     }
   }
   providers = /* @__PURE__ */ new Map();
@@ -1430,17 +1762,17 @@ async function doClose() {
   resetSendLogRepoSingleton();
   resetTemplateRepoSingleton();
   resetSendState();
-  logger6.info("Reach module closed");
+  logger7.info("Reach module closed");
 }
 async function doInit(config) {
   if (providers.size > 0) {
-    logger6.warn("Reach module is already initialized, reinitializing");
+    logger7.warn("Reach module is already initialized, reinitializing");
     await doClose();
   }
-  logger6.info("Initializing reach module");
+  logger7.info("Initializing reach module");
   const parseResult = ReachConfigSchema.safeParse(config);
   if (!parseResult.success) {
-    logger6.error("Reach config validation failed", { error: parseResult.error.message });
+    logger7.error("Reach config validation failed", { error: parseResult.error.message });
     return err(
       HaiReachError.CONFIG_ERROR,
       reachM("reach_configError", { params: { error: parseResult.error.message } }),
@@ -1448,24 +1780,35 @@ async function doInit(config) {
     );
   }
   const parsed = parseResult.data;
+  if (core.module.requiresSharedState(process.env) && parsed.providers.some((provider) => provider.type === "console"))
+    return err(HaiReachError.CONFIG_ERROR, reachM("reach_productionProviderRequired"));
   try {
+    let requiredQueue = null;
+    if (parsed.dnd?.enabled && parsed.dnd.strategy === "delay") {
+      if (!reldb.isInitialized)
+        return err(HaiReachError.CONFIG_ERROR, reachM("reach_dndPersistenceRequired"));
+      const queue = await createSendLogRepository(reldb);
+      if (!queue.success)
+        return err(HaiReachError.CONFIG_ERROR, reachM("reach_dndPersistenceRequired"), queue.error);
+      requiredQueue = queue.data;
+    }
     const newProviders = /* @__PURE__ */ new Map();
     for (const providerConfig of parsed.providers) {
       const provider = createProvider(providerConfig);
       const connectResult = await provider.connect(providerConfig);
       if (!connectResult.success) {
-        logger6.error("Provider initialization failed", {
+        logger7.error("Provider initialization failed", {
           name: providerConfig.name,
           type: providerConfig.type,
           code: connectResult.error.code,
           message: connectResult.error.message
         });
-        logger6.info("Rolling back connected providers", { count: newProviders.size });
+        logger7.info("Rolling back connected providers", { count: newProviders.size });
         for (const [name, p] of newProviders.entries()) {
           try {
             await p.close();
           } catch (rollbackError) {
-            logger6.error("Provider rollback close failed", { name, error: rollbackError });
+            logger7.error("Provider rollback close failed", { name, error: rollbackError });
           }
         }
         return connectResult;
@@ -1480,18 +1823,18 @@ async function doInit(config) {
     if (parsed.templates && templateRepo) {
       const saveResult = await templateRegistry.saveBatch(parsed.templates);
       if (!saveResult.success) {
-        logger6.warn("Failed to save config templates to database", { error: saveResult.error.message });
+        logger7.warn("Failed to save config templates to database", { error: saveResult.error.message });
       }
     }
-    sendLogRepo = await tryInitSendLogRepo();
+    sendLogRepo = requiredQueue ?? await tryInitSendLogRepo();
     if (dndConfig) {
       startDndScheduler(dndConfig, providers, sendLogRepo);
     }
     const providerNames = parsed.providers.map((p) => p.name);
-    logger6.info("Reach module initialized", { providers: providerNames });
+    logger7.info("Reach module initialized", { providers: providerNames });
     return ok(void 0);
   } catch (error) {
-    logger6.error("Reach module initialization failed", { error });
+    logger7.error("Reach module initialization failed", { error });
     return err(
       HaiReachError.CONFIG_ERROR,
       reachM("reach_initFailed", {
@@ -1501,10 +1844,75 @@ async function doInit(config) {
     );
   }
 }
+function queueEntry(row) {
+  return {
+    queueId: row.queueId,
+    provider: row.provider,
+    status: row.status,
+    updatedAt: row.updatedAt,
+    messageId: row.messageId ?? void 0,
+    attemptCount: row.attemptCount,
+    maxAttempts: row.maxAttempts,
+    nextAttemptAt: row.nextAttemptAt,
+    lastFailure: row.lastFailure ?? void 0
+  };
+}
 var reach = {
+  queue: {
+    async get(queueId) {
+      if (providers.size === 0)
+        return notInitialized.result();
+      if (!sendLogRepo)
+        return err(HaiReachError.CONFIG_ERROR, reachM("reach_dndPersistenceRequired"));
+      if (!ReachQueueIdSchema.safeParse(queueId).success)
+        return err(HaiReachError.CONFIG_ERROR, reachM("reach_queueInputInvalid"));
+      const rows = await sendLogRepo.findAll({ where: "queue_id = ?", params: [queueId], limit: 1 });
+      if (!rows.success)
+        return rows;
+      const row = rows.data[0];
+      return ok(row ? queueEntry(row) : null);
+    },
+    async list(options) {
+      if (providers.size === 0)
+        return notInitialized.result();
+      if (!sendLogRepo)
+        return err(HaiReachError.CONFIG_ERROR, reachM("reach_dndPersistenceRequired"));
+      const parsed = ReachQueueListSchema.safeParse(options);
+      if (!parsed.success)
+        return err(HaiReachError.CONFIG_ERROR, reachM("reach_queueInputInvalid"));
+      const rows = await sendLogRepo.findAll({
+        where: "status = ? AND queue_id IS NOT NULL",
+        params: [parsed.data.status],
+        orderBy: "created_at ASC, id ASC",
+        limit: parsed.data.limit,
+        offset: parsed.data.offset
+      });
+      return rows.success ? ok(rows.data.map(queueEntry)) : rows;
+    },
+    async requeueDead(queueId, options) {
+      if (providers.size === 0)
+        return notInitialized.result();
+      if (!sendLogRepo)
+        return err(HaiReachError.CONFIG_ERROR, reachM("reach_dndPersistenceRequired"));
+      const parsed = ReachDeadRequeueSchema.safeParse(options);
+      if (!ReachQueueIdSchema.safeParse(queueId).success || !parsed.success)
+        return err(HaiReachError.CONFIG_ERROR, reachM("reach_queueInputInvalid"));
+      return sendLogRepo.requeueDead(queueId, parsed.data.expectedUpdatedAt);
+    },
+    async resolveUnknown(queueId, resolution) {
+      if (providers.size === 0)
+        return notInitialized.result();
+      if (!sendLogRepo)
+        return err(HaiReachError.CONFIG_ERROR, reachM("reach_dndPersistenceRequired"));
+      const parsed = ReachUnknownResolutionSchema.safeParse(resolution);
+      if (!ReachQueueIdSchema.safeParse(queueId).success || !parsed.success)
+        return err(HaiReachError.CONFIG_ERROR, reachM("reach_queueInputInvalid"));
+      return sendLogRepo.resolveUnknown(queueId, parsed.data);
+    }
+  },
   async init(config) {
     if (initInProgress) {
-      logger6.warn("Reach module init already in progress, skipping");
+      logger7.warn("Reach module init already in progress, skipping");
       return err(
         HaiReachError.CONFIG_ERROR,
         reachM("reach_configError", { params: { error: "init already in progress" } })
@@ -1521,7 +1929,7 @@ var reach = {
     if (providers.size === 0) {
       return notInitialized.result();
     }
-    return executeSend(message, providers, templateRegistry, dndConfig, sendLogRepo);
+    return executeSend(message, providers, templateRegistry, dndConfig, sendLogRepo, currentConfig.queue);
   },
   get template() {
     return templateRegistry;
@@ -1537,6 +1945,6 @@ var reach = {
   }
 };
 
-export { AliyunSmsProviderConfigSchema, ApiProviderConfigSchema, ConsoleProviderConfigSchema, DndConfigSchema, HaiReachError, ProviderConfigSchema, ReachConfigSchema, SmtpProviderConfigSchema, TemplateConfigSchema, reach };
+export { AliyunSmsProviderConfigSchema, ApiProviderConfigSchema, ConsoleProviderConfigSchema, DndConfigSchema, HaiReachError, ProviderConfigSchema, ReachConfigSchema, ReachDeadRequeueSchema, ReachQueueConfigSchema, ReachQueueIdSchema, ReachQueueListSchema, ReachUnknownResolutionSchema, SmtpProviderConfigSchema, TemplateConfigSchema, reach };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map