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

package/dist/index.d.ts

@@ -10,27 +10,25 @@ import { HaiResult } from '@h-ai/core';
  */
 
 /**
- * Console Provider 配置（开发/测试用，将消息输出到日志）
+ * 开发/测试日志适配器配置；不证明外部投递，生产共享状态守卫拒绝console。
+ *
+ * @example
+ * ```ts
+ * import { ConsoleProviderConfigSchema } from '@h-ai/reach'
+ * const config = ConsoleProviderConfigSchema.parse({ name: 'dev-log', type: 'console' })
+ * ```
  */
 declare const ConsoleProviderConfigSchema: z.ZodObject<{
     name: z.ZodString;
     type: z.ZodLiteral<"console">;
 }, z.core.$strip>;
 /**
- * SMTP 邮件 Provider 配置
+ * SMTP配置，默认TLS/465；凭据来自私有环境，SMTP没有接收端持久幂等能力声明。
  *
  * @example
  * ```ts
- * {
- *   name: 'email',
- *   type: 'smtp',
- *   host: 'smtp.example.com',
- *   port: 465,
- *   secure: true,
- *   user: 'noreply@example.com',
- *   pass: 'password',
- *   from: 'noreply@example.com'
- * }
+ * import { SmtpProviderConfigSchema } from '@h-ai/reach'
+ * const config = SmtpProviderConfigSchema.parse({ name: 'email', type: 'smtp', host: 'smtp.example.com', from: 'noreply@example.com', user: process.env.HAI_REACH_PROVIDERS_0_USER, pass: process.env.HAI_REACH_PROVIDERS_0_PASS })
  * ```
  */
 declare const SmtpProviderConfigSchema: z.ZodObject<{
@@ -44,18 +42,12 @@ declare const SmtpProviderConfigSchema: z.ZodObject<{
     from: z.ZodString;
 }, z.core.$strip>;
 /**
- * 阿里云短信 Provider 配置（通过 HTTP API 调用，无需 SDK）
+ * 阿里云短信POP API配置；Secret只在服务端私有注入，发送需Provider模板编码等扩展参数。
  *
  * @example
  * ```ts
- * {
- *   name: 'sms',
- *   type: 'aliyun-sms',
- *   accessKeyId: 'LTAI...',
- *   accessKeySecret: '...',
- *   signName: '某某科技',
- *   endpoint: 'dysmsapi.aliyuncs.com'
- * }
+ * import { AliyunSmsProviderConfigSchema } from '@h-ai/reach'
+ * const config = AliyunSmsProviderConfigSchema.parse({ name: 'sms', type: 'aliyun-sms', accessKeyId: process.env.HAI_REACH_PROVIDERS_0_ACCESSKEYID, accessKeySecret: process.env.HAI_REACH_PROVIDERS_0_ACCESSKEYSECRET, signName: process.env.HAI_REACH_PROVIDERS_0_SIGNNAME })
  * ```
  */
 declare const AliyunSmsProviderConfigSchema: z.ZodObject<{
@@ -67,17 +59,13 @@ declare const AliyunSmsProviderConfigSchema: z.ZodObject<{
     endpoint: z.ZodDefault<z.ZodString>;
 }, z.core.$strip>;
 /**
- * API 回调 Provider 配置（通用 HTTP 回调）
+ * HTTP回调配置；idempotent默认false，只有接收端按稳定Idempotency-Key原子持久去重并覆盖旧请求迟到窗口才允许true。
+ * 写入该布尔值或发送请求头本身不证明接收端具备此能力。
  *
  * @example
  * ```ts
- * {
- *   name: 'webhook',
- *   type: 'api',
- *   url: 'https://api.example.com/notify',
- *   method: 'POST',
- *   headers: { 'Authorization': 'Bearer xxx' }
- * }
+ * import { ApiProviderConfigSchema } from '@h-ai/reach'
+ * const config = ApiProviderConfigSchema.parse({ name: 'webhook', type: 'api', url: 'https://notify.example.com/events', idempotent: false })
  * ```
  */
 declare const ApiProviderConfigSchema: z.ZodObject<{
@@ -90,9 +78,16 @@ declare const ApiProviderConfigSchema: z.ZodObject<{
     }>>;
     headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     timeout: z.ZodDefault<z.ZodNumber>;
+    idempotent: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
 /**
- * 单个 Provider 配置 Schema（判别联合体）
+ * 按type区分内置Provider配置，不把name当协议类型；name用于模板/消息路由。
+ *
+ * @example
+ * ```ts
+ * import { ProviderConfigSchema } from '@h-ai/reach'
+ * const config = ProviderConfigSchema.parse({ name: 'webhook', type: 'api', url: 'https://notify.example.com/events', idempotent: false })
+ * ```
  */
 declare const ProviderConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     name: z.ZodString;
@@ -123,34 +118,145 @@ declare const ProviderConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     }>>;
     headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     timeout: z.ZodDefault<z.ZodNumber>;
+    idempotent: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>], "type">;
-/** 单个 Provider 配置类型（parse 后） */
+/**
+ * 由ProviderConfigSchema解析后的配置类型，默认值已经填充；与输入类型区分，秘密字段不写日志。
+ *
+ * @example
+ * ```ts
+ * import { ProviderConfigSchema, type ProviderConfig } from '@h-ai/reach'
+ * const config: ProviderConfig = ProviderConfigSchema.parse({ name: 'webhook', type: 'api', url: 'https://notify.example.com/events', idempotent: false })
+ * ```
+ */
 type ProviderConfig = z.infer<typeof ProviderConfigSchema>;
-/** Console 配置类型 */
+/**
+ * 由ConsoleProviderConfigSchema解析后的配置类型，默认值已经填充；与输入类型区分，秘密字段不写日志。
+ *
+ * @example
+ * ```ts
+ * import { ConsoleProviderConfigSchema, type ConsoleProviderConfig } from '@h-ai/reach'
+ * const config: ConsoleProviderConfig = ConsoleProviderConfigSchema.parse({ name: 'dev-log', type: 'console' })
+ * ```
+ */
 type ConsoleProviderConfig = z.infer<typeof ConsoleProviderConfigSchema>;
-/** SMTP 配置类型 */
+/**
+ * 由SmtpProviderConfigSchema解析后的配置类型，默认值已经填充；与输入类型区分，秘密字段不写日志。
+ *
+ * @example
+ * ```ts
+ * import { SmtpProviderConfigSchema, type SmtpProviderConfig } from '@h-ai/reach'
+ * const config: SmtpProviderConfig = SmtpProviderConfigSchema.parse({ name: 'email', type: 'smtp', host: 'smtp.example.com', from: 'noreply@example.com', user: process.env.HAI_REACH_PROVIDERS_0_USER, pass: process.env.HAI_REACH_PROVIDERS_0_PASS })
+ * ```
+ */
 type SmtpProviderConfig = z.infer<typeof SmtpProviderConfigSchema>;
-/** 阿里云短信配置类型 */
+/**
+ * 由AliyunSmsProviderConfigSchema解析后的配置类型，默认值已经填充；与输入类型区分，秘密字段不写日志。
+ *
+ * @example
+ * ```ts
+ * import { AliyunSmsProviderConfigSchema, type AliyunSmsProviderConfig } from '@h-ai/reach'
+ * const config: AliyunSmsProviderConfig = AliyunSmsProviderConfigSchema.parse({ name: 'sms', type: 'aliyun-sms', accessKeyId: process.env.HAI_REACH_PROVIDERS_0_ACCESSKEYID, accessKeySecret: process.env.HAI_REACH_PROVIDERS_0_ACCESSKEYSECRET, signName: process.env.HAI_REACH_PROVIDERS_0_SIGNNAME })
+ * ```
+ */
 type AliyunSmsProviderConfig = z.infer<typeof AliyunSmsProviderConfigSchema>;
-/** API 回调配置类型 */
+/**
+ * 由ApiProviderConfigSchema解析后的配置类型，默认值已经填充；与输入类型区分，秘密字段不写日志。
+ *
+ * @example
+ * ```ts
+ * import { ApiProviderConfigSchema, type ApiProviderConfig } from '@h-ai/reach'
+ * const config: ApiProviderConfig = ApiProviderConfigSchema.parse({ name: 'webhook', type: 'api', url: 'https://notify.example.com/events', idempotent: false })
+ * ```
+ */
 type ApiProviderConfig = z.infer<typeof ApiProviderConfigSchema>;
 /**
- * 免打扰时间段配置
+ * 人工处置unknown的结构边界，仅sent/discarded，不提供重发；应用须先校验运维权限并隔离旧worker/核对外部效果。
  *
- * 在指定的时间段内，根据策略处理消息：
- * - `discard`：直接丢弃，返回 DND_BLOCKED 错误
- * - `delay`：暂存到数据库（状态为 pending），DND 结束后由定时任务集中发送
+ * @example
+ * ```ts
+ * import { ReachUnknownResolutionSchema } from '@h-ai/reach'
+ * const config = ReachUnknownResolutionSchema.parse({ status: 'discarded' })
+ * ```
+ */
+declare const ReachUnknownResolutionSchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        sent: "sent";
+        discarded: "discarded";
+    }>;
+    messageId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * 持久入队回执UUID格式；合法UUID不代表存在，也不授予队列运维权限。
  *
- * 时间使用 HH:mm 格式（24 小时制），支持跨午夜（如 22:00-08:00）。
+ * @example
+ * ```ts
+ * import { ReachQueueIdSchema } from '@h-ai/reach'
+ * const config = ReachQueueIdSchema.parse('00000000-0000-4000-8000-000000000001')
+ * ```
+ */
+declare const ReachQueueIdSchema: z.ZodString;
+/**
+ * 可靠队列重试策略，入队时随消息持久保存；maxAttempts含首次与崩溃恢复，指数退避有上限。
  *
  * @example
  * ```ts
- * {
- *   enabled: true,
- *   strategy: 'delay',
- *   start: '22:00',
- *   end: '08:00'
- * }
+ * import { ReachQueueConfigSchema } from '@h-ai/reach'
+ * const config = ReachQueueConfigSchema.parse({ maxAttempts: 5, retryDelayMs: 60000, maxRetryDelayMs: 3600000 })
+ * ```
+ */
+declare const ReachQueueConfigSchema: z.ZodObject<{
+    maxAttempts: z.ZodDefault<z.ZodNumber>;
+    retryDelayMs: z.ZodDefault<z.ZodNumber>;
+    maxRetryDelayMs: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * 由ReachQueueConfigSchema解析后的配置类型，默认值已经填充；与输入类型区分，秘密字段不写日志。
+ *
+ * @example
+ * ```ts
+ * import { ReachQueueConfigSchema, type ReachQueueConfig } from '@h-ai/reach'
+ * const config: ReachQueueConfig = ReachQueueConfigSchema.parse({ maxAttempts: 5, retryDelayMs: 60000, maxRetryDelayMs: 3600000 })
+ * ```
+ */
+type ReachQueueConfig = z.infer<typeof ReachQueueConfigSchema>;
+/**
+ * 仅分页列出dead/unknown元数据，限制limit/offset；不返回正文/收件人，不替代服务端运维授权。
+ *
+ * @example
+ * ```ts
+ * import { ReachQueueListSchema } from '@h-ai/reach'
+ * const config = ReachQueueListSchema.parse({ status: 'dead', limit: 10, offset: 0 })
+ * ```
+ */
+declare const ReachQueueListSchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        unknown: "unknown";
+        dead: "dead";
+    }>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    offset: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * 恢复dead所需的最近updatedAt条件输入，阻止过时/并发恢复；unknown禁止此操作。
+ *
+ * @example
+ * ```ts
+ * import { ReachDeadRequeueSchema } from '@h-ai/reach'
+ * const config = ReachDeadRequeueSchema.parse({ expectedUpdatedAt: 1730000000000 })
+ * ```
+ */
+declare const ReachDeadRequeueSchema: z.ZodObject<{
+    expectedUpdatedAt: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * 本机时区的HH:mm免打扰配置，支持跨午夜；start=end表示不拦截。
+ * discard返回DND_BLOCKED；delay要求数据库队列就绪且pending写入成功才返回deferred回执。
+ *
+ * @example
+ * ```ts
+ * import { DndConfigSchema } from '@h-ai/reach'
+ * const config = DndConfigSchema.parse({ enabled: true, strategy: 'delay', start: '22:00', end: '08:00' })
  * ```
  */
 declare const DndConfigSchema: z.ZodObject<{
@@ -162,18 +268,23 @@ declare const DndConfigSchema: z.ZodObject<{
     start: z.ZodDefault<z.ZodString>;
     end: z.ZodDefault<z.ZodString>;
 }, z.core.$strip>;
-/** DND 配置类型 */
+/**
+ * 由DndConfigSchema解析后的配置类型，默认值已经填充；与输入类型区分，秘密字段不写日志。
+ *
+ * @example
+ * ```ts
+ * import { DndConfigSchema, type DndConfig } from '@h-ai/reach'
+ * const config: DndConfig = DndConfigSchema.parse({ enabled: true, strategy: 'delay', start: '22:00', end: '08:00' })
+ * ```
+ */
 type DndConfig = z.infer<typeof DndConfigSchema>;
 /**
- * 模板配置 Schema（通过配置文件定义模板）
+ * 绑定Provider名称的持久模板配置，{key}仅做文本替换；需要先初始化数据库，不提供HTML消毒。
  *
  * @example
- * ```yaml
- * templates:
- *   - name: verification_code
- *     provider: email
- *     subject: "验证码: {code}"
- *     body: "您的验证码是 {code}，有效期 {minutes} 分钟。"
+ * ```ts
+ * import { TemplateConfigSchema } from '@h-ai/reach'
+ * const config = TemplateConfigSchema.parse({ name: 'welcome', provider: 'webhook', subject: 'Welcome {userName}', body: 'Hello {userName}' })
  * ```
  */
 declare const TemplateConfigSchema: z.ZodObject<{
@@ -182,13 +293,24 @@ declare const TemplateConfigSchema: z.ZodObject<{
     subject: z.ZodOptional<z.ZodString>;
     body: z.ZodString;
 }, z.core.$strip>;
-/** 模板配置类型 */
+/**
+ * 由TemplateConfigSchema解析后的配置类型，默认值已经填充；与输入类型区分，秘密字段不写日志。
+ *
+ * @example
+ * ```ts
+ * import { TemplateConfigSchema, type TemplateConfig } from '@h-ai/reach'
+ * const config: TemplateConfig = TemplateConfigSchema.parse({ name: 'welcome', provider: 'webhook', subject: 'Welcome {userName}', body: 'Hello {userName}' })
+ * ```
+ */
 type TemplateConfig = z.infer<typeof TemplateConfigSchema>;
 /**
- * 触达模块配置 Schema
+ * 模块配置Schema，解析Provider/模板/DND及持久重试默认值；Schema校验不证明外部服务可用或接收端幂等。
  *
- * 接受一个 Provider 配置数组，支持同时注册多个 Provider。
- * 支持通过配置文件定义模板和免打扰时间段。
+ * @example
+ * ```ts
+ * import { ReachConfigSchema } from '@h-ai/reach'
+ * const config = ReachConfigSchema.parse({ providers: [{ name: 'webhook', type: 'api', url: 'https://notify.example.com/events', idempotent: false }], templates: [{ name: 'welcome', provider: 'webhook', subject: 'Welcome {userName}', body: 'Hello {userName}' }], dnd: { enabled: true, strategy: 'delay', start: '22:00', end: '08:00' } })
+ * ```
  */
 declare const ReachConfigSchema: z.ZodObject<{
     providers: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -220,6 +342,7 @@ declare const ReachConfigSchema: z.ZodObject<{
         }>>;
         headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         timeout: z.ZodDefault<z.ZodNumber>;
+        idempotent: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>], "type">>;
     templates: z.ZodOptional<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
@@ -236,14 +359,47 @@ declare const ReachConfigSchema: z.ZodObject<{
         start: z.ZodDefault<z.ZodString>;
         end: z.ZodDefault<z.ZodString>;
     }, z.core.$strip>>;
+    queue: z.ZodPrefault<z.ZodObject<{
+        maxAttempts: z.ZodDefault<z.ZodNumber>;
+        retryDelayMs: z.ZodDefault<z.ZodNumber>;
+        maxRetryDelayMs: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
-/** 触达模块配置类型（parse 后） */
+/**
+ * 由ReachConfigSchema解析后的配置类型，默认值已经填充；与输入类型区分，秘密字段不写日志。
+ *
+ * @example
+ * ```ts
+ * import { ReachConfigSchema, type ReachConfig } from '@h-ai/reach'
+ * const config: ReachConfig = ReachConfigSchema.parse({ providers: [{ name: 'webhook', type: 'api', url: 'https://notify.example.com/events', idempotent: false }], templates: [{ name: 'welcome', provider: 'webhook', subject: 'Welcome {userName}', body: 'Hello {userName}' }], dnd: { enabled: true, strategy: 'delay', start: '22:00', end: '08:00' } })
+ * ```
+ */
 type ReachConfig = z.infer<typeof ReachConfigSchema>;
 /**
- * 触达模块配置输入类型
+ * reach.init接收的配置输入，queue默认值可省略；生产选真实Provider、共享数据库，不能用console假定通知完成。
+ *
+ * @example
+ * ```ts
+ * import { ReachConfigSchema, type ReachConfigInput } from '@h-ai/reach'
+ * const input: ReachConfigInput = { providers: [{ name: 'webhook', type: 'api', url: 'https://notify.example.com/events', idempotent: false }], templates: [{ name: 'welcome', provider: 'webhook', subject: 'Welcome {userName}', body: 'Hello {userName}' }], dnd: { enabled: true, strategy: 'delay', start: '22:00', end: '08:00' } }
+ * const parsed = ReachConfigSchema.parse(input)
+ * ```
  */
 type ReachConfigInput = z.input<typeof ReachConfigSchema>;
 
+/**
+ * Reach标准错误集合；DND拒绝、发送失败与配置错误均通过HaiResult判断，不把失败当已入队。
+ *
+ * @example
+ * ```ts
+ * import { reach, HaiReachError } from '@h-ai/reach'
+ * const result = await reach.send({ provider: 'webhook', to: 'user@example.com', body: 'hello' })
+ * if (!result.success && result.error.code === HaiReachError.NOT_INITIALIZED.code) {
+ *   // 先执行依赖初始化，不能把未初始化失败当作触达成功。
+ *   const message = result.error.message
+ * }
+ * ```
+ */
 declare const HaiReachError: {
     readonly SEND_FAILED: _h_ai_core.HaiErrorDef;
     readonly TEMPLATE_NOT_FOUND: _h_ai_core.HaiErrorDef;
@@ -251,39 +407,29 @@ declare const HaiReachError: {
     readonly INVALID_RECIPIENT: _h_ai_core.HaiErrorDef;
     readonly PROVIDER_NOT_FOUND: _h_ai_core.HaiErrorDef;
     readonly DND_BLOCKED: _h_ai_core.HaiErrorDef;
-    readonly DND_DEFERRED: _h_ai_core.HaiErrorDef;
     readonly NOT_INITIALIZED: _h_ai_core.HaiErrorDef;
     readonly UNSUPPORTED_TYPE: _h_ai_core.HaiErrorDef;
     readonly CONFIG_ERROR: _h_ai_core.HaiErrorDef;
+    readonly DELIVERY_REJECTED: _h_ai_core.HaiErrorDef;
 };
 /**
- * 触达渠道类型
+ * 渠道语义标签email/sms/api；消息路由实际使用配置中的Provider名称。
  *
- * - `email` — 邮件
- * - `sms` — 短信
- * - `api` — API 回调
+ * @example
+ * ```ts
+ * import type { ReachChannel } from '@h-ai/reach'
+ * const channel: ReachChannel = 'api'
+ * ```
  */
 type ReachChannel = 'email' | 'sms' | 'api';
 /**
- * 触达消息（发送请求）
- *
- * 通过 `provider` 字段指定目标 Provider，通过 `template` 字段指定模板。
+ * 直接发送必须指定Provider名和内容；模板发送可由持久模板推导路由，vars做文本替换。
+ * 队列幂等键固定为持久queueId；直接调用的业务重试由应用提供稳定idempotencyKey并核验接收端契约。
  *
  * @example
  * ```ts
- * // 使用模板发送邮件
- * const msg: ReachMessage = {
- *   to: 'user@example.com',
- *   template: 'welcome',
- *   vars: { userName: '张三' },
- * }
- *
- * // 使用模板发送短信
- * const msg: ReachMessage = {
- *   to: '13800138000',
- *   template: 'verification_code',
- *   vars: { code: '123456' },
- * }
+ * import type { ReachMessage } from '@h-ai/reach'
+ * const message: ReachMessage = { provider: 'webhook', to: 'user@example.com', template: 'welcome', vars: { userName: 'Alice' } }
  * ```
  */
 interface ReachMessage {
@@ -301,30 +447,402 @@ interface ReachMessage {
     vars?: Record<string, string>;
     /** Provider 扩展参数（如短信 Provider 的模板编码、签名等） */
     extra?: Record<string, unknown>;
+    /** API 接收端幂等键；直接发送可指定，队列投递固定使用持久化 queueId。 */
+    idempotencyKey?: string;
 }
 /**
- * 发送结果
+ * 发送或可靠入队结果；deferred=true只证明持久pending写入成功，queueId用于后续查询，不代表已送达。
+ *
+ * @example
+ * ```ts
+ * import { reach, type SendResult } from '@h-ai/reach'
+ * const { reldb } = await import('@h-ai/reldb')
+ * const connected = await reldb.init({ type: 'postgresql', host: 'db', port: 5432, database: 'hai', user: 'postgres', password: process.env.HAI_DB_PASSWORD })
+ * if (!connected.success) throw new Error(connected.error.message)
+ * try {
+ *   const initialized = await reach.init({ providers: [{ name: 'webhook', type: 'api', url: 'https://notify.example.com/events', idempotent: false }], templates: [{ name: 'welcome', provider: 'webhook', subject: 'Welcome {userName}', body: 'Hello {userName}' }], dnd: { enabled: true, strategy: 'delay', start: '22:00', end: '08:00' } })
+ *   if (!initialized.success) throw new Error(initialized.error.message)
+ *   try {
+ *     const result = await reach.send({ provider: 'webhook', to: 'user@example.com', body: 'hello' })
+ *     if (!result.success) throw new Error(result.error.message)
+ *     const outcome: SendResult = result.data
+ *     if (outcome.deferred) {
+ *       const queued = await reach.queue.get(outcome.queueId)
+ *       if (!queued.success) throw new Error(queued.error.message)
+ *     }
+ *   }
+ *   finally { await reach.close() }
+ * }
+ * finally {
+ *   const closed = await reldb.close()
+ *   if (!closed.success) throw new Error(closed.error.message)
+ * }
+ * ```
  */
-interface SendResult {
-    /** 是否发送成功 */
+type SendResult = {
+    /** 是否已完成 Provider 发送或可靠入队；具体状态同时检查 deferred。 */
     success: boolean;
     /** Provider 返回的消息 ID（如有） */
     messageId?: string;
-    /** 是否被延时（DND delay 策略暂存，待 DND 结束后发送） */
-    deferred?: boolean;
+} & ({
+    /** 已可靠入队，尚未投递。 */
+    deferred: true;
+    /** 持久化回执 UUID，对应 hai_reach_send_log.queue_id。 */
+    queueId: string;
+} | {
+    /** Provider 即时发送结果，不含入队回执。 */
+    deferred?: false;
+    queueId?: never;
+});
+/**
+ * 持久队列状态；sending已开始外部效果，非幂等失败/失租约进unknown禁止自动重发；dead停止自动处理但可条件恢复。
+ *
+ * @example
+ * ```ts
+ * import type { ReachQueueStatus } from '@h-ai/reach'
+ * const status: ReachQueueStatus = 'unknown'
+ * ```
+ */
+type ReachQueueStatus = 'pending' | 'processing' | 'sending' | 'unknown' | 'sent' | 'discarded' | 'dead';
+/**
+ * 有界失败分类，不保存Provider响应正文、凭据或收件人；用于修复根因和处置死信。
+ *
+ * @example
+ * ```ts
+ * import type { ReachQueueFailure } from '@h-ai/reach'
+ * const failure: ReachQueueFailure = 'provider_unavailable'
+ * ```
+ */
+type ReachQueueFailure = 'provider_unavailable' | 'invalid_message' | 'permanent_rejection' | 'transient_failure' | 'attempts_exhausted';
+/**
+ * 不含消息正文/收件人的队列运维快照；时间为安全整数Unix毫秒，计数/策略来自持久消息。
+ *
+ * @example
+ * ```ts
+ * import { reach, type ReachQueueEntry } from '@h-ai/reach'
+ * const { reldb } = await import('@h-ai/reldb')
+ * const connected = await reldb.init({ type: 'postgresql', host: 'db', port: 5432, database: 'hai', user: 'postgres', password: process.env.HAI_DB_PASSWORD })
+ * if (!connected.success) throw new Error(connected.error.message)
+ * try {
+ *   const initialized = await reach.init({ providers: [{ name: 'webhook', type: 'api', url: 'https://notify.example.com/events', idempotent: false }], templates: [{ name: 'welcome', provider: 'webhook', subject: 'Welcome {userName}', body: 'Hello {userName}' }], dnd: { enabled: true, strategy: 'delay', start: '22:00', end: '08:00' } })
+ *   if (!initialized.success) throw new Error(initialized.error.message)
+ *   try {
+ *     const listed = await reach.queue.list({ status: 'dead', limit: 10 })
+ *     if (!listed.success) throw new Error(listed.error.message)
+ *     const entry: ReachQueueEntry | undefined = listed.data[0]
+ *     if (entry) { const attempts = entry.attemptCount }
+ *   }
+ *   finally { await reach.close() }
+ * }
+ * finally {
+ *   const closed = await reldb.close()
+ *   if (!closed.success) throw new Error(closed.error.message)
+ * }
+ * ```
+ */
+interface ReachQueueEntry {
+    /** 持久化入队回执。 */
+    queueId: string;
+    /** Provider 配置名称。 */
+    provider: string;
+    /** 当前处理状态。 */
+    status: ReachQueueStatus;
+    /** 最近更新时间（Unix 毫秒）。 */
+    updatedAt?: number;
+    /** 外部 Provider 确认的消息编号。 */
+    messageId?: string;
+    /** 已领取次数；节点崩溃后的重新领取也计数。 */
+    attemptCount: number;
+    /** 此条消息持久保存的自动领取上限。 */
+    maxAttempts: number;
+    /** 下次允许自动领取的 Unix 毫秒时间；终态为 0。 */
+    nextAttemptAt: number;
+    /** 最近失败分类，便于可信运维流程排查与修复。 */
+    lastFailure?: ReachQueueFailure;
+}
+/**
+ * 仅列出需人工处理的dead/unknown；分页有界，不提供凭据或替代运维权限。
+ *
+ * @example
+ * ```ts
+ * import { reach, type ReachQueueListOptions } from '@h-ai/reach'
+ * const { reldb } = await import('@h-ai/reldb')
+ * const connected = await reldb.init({ type: 'postgresql', host: 'db', port: 5432, database: 'hai', user: 'postgres', password: process.env.HAI_DB_PASSWORD })
+ * if (!connected.success) throw new Error(connected.error.message)
+ * try {
+ *   const initialized = await reach.init({ providers: [{ name: 'webhook', type: 'api', url: 'https://notify.example.com/events', idempotent: false }], templates: [{ name: 'welcome', provider: 'webhook', subject: 'Welcome {userName}', body: 'Hello {userName}' }], dnd: { enabled: true, strategy: 'delay', start: '22:00', end: '08:00' } })
+ *   if (!initialized.success) throw new Error(initialized.error.message)
+ *   try {
+ *     const options: ReachQueueListOptions = { status: 'unknown', limit: 10, offset: 0 }
+ *     const listed = await reach.queue.list(options)
+ *     if (!listed.success) throw new Error(listed.error.message)
+ *   }
+ *   finally { await reach.close() }
+ * }
+ * finally {
+ *   const closed = await reldb.close()
+ *   if (!closed.success) throw new Error(closed.error.message)
+ * }
+ * ```
+ */
+interface ReachQueueListOptions {
+    /** 需要人工处理的状态。 */
+    status: 'dead' | 'unknown';
+    /** 每页 1–100 条，默认 50。 */
+    limit?: number;
+    /** 跳过条数，默认 0，上限 1000000。 */
+    offset?: number;
+}
+/**
+ * dead条件恢复输入；expectedUpdatedAt必须来自最近快照，不能用本机当前时间冒充版本。
+ * 先修根因并确认旧执行与接收端幂等边界，unknown不能重排。
+ *
+ * @example
+ * ```ts
+ * import { reach, type ReachDeadRequeue } from '@h-ai/reach'
+ * const { reldb } = await import('@h-ai/reldb')
+ * const connected = await reldb.init({ type: 'postgresql', host: 'db', port: 5432, database: 'hai', user: 'postgres', password: process.env.HAI_DB_PASSWORD })
+ * if (!connected.success) throw new Error(connected.error.message)
+ * try {
+ *   const initialized = await reach.init({ providers: [{ name: 'webhook', type: 'api', url: 'https://notify.example.com/events', idempotent: false }], templates: [{ name: 'welcome', provider: 'webhook', subject: 'Welcome {userName}', body: 'Hello {userName}' }], dnd: { enabled: true, strategy: 'delay', start: '22:00', end: '08:00' } })
+ *   if (!initialized.success) throw new Error(initialized.error.message)
+ *   try {
+ *     const listed = await reach.queue.list({ status: 'dead', limit: 10 })
+ *     if (!listed.success) throw new Error(listed.error.message)
+ *     const entry = listed.data[0]
+ *     if (entry && entry.updatedAt !== undefined) {
+ *       const options: ReachDeadRequeue = { expectedUpdatedAt: entry.updatedAt }
+ *       // 此调用仅在受信运维流程核验完成后执行。
+ *       const restored = await reach.queue.requeueDead(entry.queueId, options)
+ *       if (!restored.success) throw new Error(restored.error.message)
+ *     }
+ *   }
+ *   finally { await reach.close() }
+ * }
+ * finally {
+ *   const closed = await reldb.close()
+ *   if (!closed.success) throw new Error(closed.error.message)
+ * }
+ * ```
+ */
+interface ReachDeadRequeue {
+    /** 必须等于最近查询的更新时间，阻止并发及过时请求。 */
+    expectedUpdatedAt: number;
 }
 /**
- * 触达模板定义
+ * unknown人工裁定，不提供自动重发；先校验运维权限、停止/隔离旧worker并核对Provider实际记录。
+ * discarded只终止后续处理，不能撤销已开始的外部请求或已发送消息。
  *
- * 每个模板绑定到一个 Provider，发送时按模板中的 `provider` 路由。
+ * @example
+ * ```ts
+ * import { reach, type ReachUnknownResolution } from '@h-ai/reach'
+ * const { reldb } = await import('@h-ai/reldb')
+ * const connected = await reldb.init({ type: 'postgresql', host: 'db', port: 5432, database: 'hai', user: 'postgres', password: process.env.HAI_DB_PASSWORD })
+ * if (!connected.success) throw new Error(connected.error.message)
+ * try {
+ *   const initialized = await reach.init({ providers: [{ name: 'webhook', type: 'api', url: 'https://notify.example.com/events', idempotent: false }], templates: [{ name: 'welcome', provider: 'webhook', subject: 'Welcome {userName}', body: 'Hello {userName}' }], dnd: { enabled: true, strategy: 'delay', start: '22:00', end: '08:00' } })
+ *   if (!initialized.success) throw new Error(initialized.error.message)
+ *   try {
+ *     const listed = await reach.queue.list({ status: 'unknown', limit: 10 })
+ *     if (!listed.success) throw new Error(listed.error.message)
+ *     const entry = listed.data[0]
+ *     if (entry) {
+ *       // 可信运维前置：旧worker已隔离且外部投递记录已核对。
+ *       const resolution: ReachUnknownResolution = { status: 'discarded' }
+ *       const resolved = await reach.queue.resolveUnknown(entry.queueId, resolution)
+ *       if (!resolved.success) throw new Error(resolved.error.message)
+ *     }
+ *   }
+ *   finally { await reach.close() }
+ * }
+ * finally {
+ *   const closed = await reldb.close()
+ *   if (!closed.success) throw new Error(closed.error.message)
+ * }
+ * ```
+ */
+interface ReachUnknownResolution {
+    /** 经外部核对确认已投递，或终止后续处理。discarded 不撤销已经开始的外部请求。 */
+    status: 'sent' | 'discarded';
+    /** 确认已投递时，可记录 Provider 消息编号，最多 255 个字符。 */
+    messageId?: string;
+}
+/**
+ * 受信服务端队列运维入口，需应用先授权；只查询安全元数据，恢复/裁定均由数据库条件提交。
+ *
+ * @example
+ * ```ts
+ * import { reach } from '@h-ai/reach'
+ * const { reldb } = await import('@h-ai/reldb')
+ * const connected = await reldb.init({ type: 'postgresql', host: 'db', port: 5432, database: 'hai', user: 'postgres', password: process.env.HAI_DB_PASSWORD })
+ * if (!connected.success) throw new Error(connected.error.message)
+ * try {
+ *   const initialized = await reach.init({ providers: [{ name: 'webhook', type: 'api', url: 'https://notify.example.com/events', idempotent: false }], templates: [{ name: 'welcome', provider: 'webhook', subject: 'Welcome {userName}', body: 'Hello {userName}' }], dnd: { enabled: true, strategy: 'delay', start: '22:00', end: '08:00' } })
+ *   if (!initialized.success) throw new Error(initialized.error.message)
+ *   try {
+ *     const listed = await reach.queue.list({ status: 'unknown', limit: 10 })
+ *     if (!listed.success) throw new Error(listed.error.message)
+ *     const count = listed.data.length
+ *   }
+ *   finally { await reach.close() }
+ * }
+ * finally {
+ *   const closed = await reldb.close()
+ *   if (!closed.success) throw new Error(closed.error.message)
+ * }
+ * ```
+ */
+interface ReachQueueOperations {
+    /**
+     * 按回执查询队列状态。
+     * @param queueId - 持久UUID回执，不代替运维权限。
+     * @returns HaiResult；先检查success，条件提交失败不能伪装成功。
+     *
+     * @example
+     * ```ts
+     * import { reach } from '@h-ai/reach'
+     * const { reldb } = await import('@h-ai/reldb')
+     * const connected = await reldb.init({ type: 'postgresql', host: 'db', port: 5432, database: 'hai', user: 'postgres', password: process.env.HAI_DB_PASSWORD })
+     * if (!connected.success) throw new Error(connected.error.message)
+     * try {
+     *   const initialized = await reach.init({ providers: [{ name: 'webhook', type: 'api', url: 'https://notify.example.com/events', idempotent: false }], templates: [{ name: 'welcome', provider: 'webhook', subject: 'Welcome {userName}', body: 'Hello {userName}' }], dnd: { enabled: true, strategy: 'delay', start: '22:00', end: '08:00' } })
+     *   if (!initialized.success) throw new Error(initialized.error.message)
+     *   try {
+     *     const result = await reach.queue.get('00000000-0000-4000-8000-000000000001')
+     *     if (!result.success) throw new Error(result.error.message)
+     *     if (result.data) { const status = result.data.status }
+     *   }
+     *   finally { await reach.close() }
+     * }
+     * finally {
+     *   const closed = await reldb.close()
+     *   if (!closed.success) throw new Error(closed.error.message)
+     * }
+     * ```
+     */
+    get: (queueId: string) => Promise<HaiResult<ReachQueueEntry | null>>;
+    /**
+     * 分页查询死信或未知结果，仅返回运维元数据。
+     * @param options - 实际操作输入，按本方法约束校验。
+     * @returns HaiResult；先检查success，条件提交失败不能伪装成功。
+     *
+     * @example
+     * ```ts
+     * import { reach } from '@h-ai/reach'
+     * const { reldb } = await import('@h-ai/reldb')
+     * const connected = await reldb.init({ type: 'postgresql', host: 'db', port: 5432, database: 'hai', user: 'postgres', password: process.env.HAI_DB_PASSWORD })
+     * if (!connected.success) throw new Error(connected.error.message)
+     * try {
+     *   const initialized = await reach.init({ providers: [{ name: 'webhook', type: 'api', url: 'https://notify.example.com/events', idempotent: false }], templates: [{ name: 'welcome', provider: 'webhook', subject: 'Welcome {userName}', body: 'Hello {userName}' }], dnd: { enabled: true, strategy: 'delay', start: '22:00', end: '08:00' } })
+     *   if (!initialized.success) throw new Error(initialized.error.message)
+     *   try {
+     *     const listed = await reach.queue.list({ status: 'unknown', limit: 10 })
+     *     if (!listed.success) throw new Error(listed.error.message)
+     *     const count = listed.data.length
+     *   }
+     *   finally { await reach.close() }
+     * }
+     * finally {
+     *   const closed = await reldb.close()
+     *   if (!closed.success) throw new Error(closed.error.message)
+     * }
+     * ```
+     */
+    list: (options: ReachQueueListOptions) => Promise<HaiResult<ReachQueueEntry[]>>;
+    /**
+     * 修复根因并确认接收端幂等契约后恢复 dead；重置计数，保留 queueId/策略。unknown 不能重排。
+     * @param queueId - 持久UUID回执，不代替运维权限。
+     * @param options - 实际操作输入，按本方法约束校验。
+     * @returns HaiResult；先检查success，条件提交失败不能伪装成功。
+     *
+     * @example
+     * ```ts
+     * import { reach, type ReachDeadRequeue } from '@h-ai/reach'
+     * const { reldb } = await import('@h-ai/reldb')
+     * const connected = await reldb.init({ type: 'postgresql', host: 'db', port: 5432, database: 'hai', user: 'postgres', password: process.env.HAI_DB_PASSWORD })
+     * if (!connected.success) throw new Error(connected.error.message)
+     * try {
+     *   const initialized = await reach.init({ providers: [{ name: 'webhook', type: 'api', url: 'https://notify.example.com/events', idempotent: false }], templates: [{ name: 'welcome', provider: 'webhook', subject: 'Welcome {userName}', body: 'Hello {userName}' }], dnd: { enabled: true, strategy: 'delay', start: '22:00', end: '08:00' } })
+     *   if (!initialized.success) throw new Error(initialized.error.message)
+     *   try {
+     *     const listed = await reach.queue.list({ status: 'dead', limit: 10 })
+     *     if (!listed.success) throw new Error(listed.error.message)
+     *     const entry = listed.data[0]
+     *     if (entry && entry.updatedAt !== undefined) {
+     *       const options: ReachDeadRequeue = { expectedUpdatedAt: entry.updatedAt }
+     *       // 此调用仅在受信运维流程核验完成后执行。
+     *       const restored = await reach.queue.requeueDead(entry.queueId, options)
+     *       if (!restored.success) throw new Error(restored.error.message)
+     *     }
+     *   }
+     *   finally { await reach.close() }
+     * }
+     * finally {
+     *   const closed = await reldb.close()
+     *   if (!closed.success) throw new Error(closed.error.message)
+     * }
+     * ```
+     */
+    requeueDead: (queueId: string, options: ReachDeadRequeue) => Promise<HaiResult<void>>;
+    /**
+     * 停止/隔离旧 worker 并核对外部投递记录后，裁定 unknown；不重新发送。
+     * @param queueId - 持久UUID回执，不代替运维权限。
+     * @param resolution - 实际操作输入，按本方法约束校验。
+     * @returns HaiResult；先检查success，条件提交失败不能伪装成功。
+     *
+     * @example
+     * ```ts
+     * import { reach, type ReachUnknownResolution } from '@h-ai/reach'
+     * const { reldb } = await import('@h-ai/reldb')
+     * const connected = await reldb.init({ type: 'postgresql', host: 'db', port: 5432, database: 'hai', user: 'postgres', password: process.env.HAI_DB_PASSWORD })
+     * if (!connected.success) throw new Error(connected.error.message)
+     * try {
+     *   const initialized = await reach.init({ providers: [{ name: 'webhook', type: 'api', url: 'https://notify.example.com/events', idempotent: false }], templates: [{ name: 'welcome', provider: 'webhook', subject: 'Welcome {userName}', body: 'Hello {userName}' }], dnd: { enabled: true, strategy: 'delay', start: '22:00', end: '08:00' } })
+     *   if (!initialized.success) throw new Error(initialized.error.message)
+     *   try {
+     *     const listed = await reach.queue.list({ status: 'unknown', limit: 10 })
+     *     if (!listed.success) throw new Error(listed.error.message)
+     *     const entry = listed.data[0]
+     *     if (entry) {
+     *       // 可信运维前置：旧worker已隔离且外部投递记录已核对。
+     *       const resolution: ReachUnknownResolution = { status: 'discarded' }
+     *       const resolved = await reach.queue.resolveUnknown(entry.queueId, resolution)
+     *       if (!resolved.success) throw new Error(resolved.error.message)
+     *     }
+     *   }
+     *   finally { await reach.close() }
+     * }
+     * finally {
+     *   const closed = await reldb.close()
+     *   if (!closed.success) throw new Error(closed.error.message)
+     * }
+     * ```
+     */
+    resolveUnknown: (queueId: string, resolution: ReachUnknownResolution) => Promise<HaiResult<void>>;
+}
+/**
+ * 持久文本模板，provider是配置名称，subject/body支持{key}替换；未提供的占位符保留原文。
+ * 不提供HTML转义或消毒，渲染结果的最终安全上下文由使用方处理。
  *
  * @example
  * ```ts
- * const template: ReachTemplate = {
- *   name: 'verification_code',
- *   provider: 'email',
- *   subject: '验证码: {code}',
- *   body: '您的验证码是 {code}，有效期 {minutes} 分钟。',
+ * import { reach, type ReachTemplate } from '@h-ai/reach'
+ * const { reldb } = await import('@h-ai/reldb')
+ * const connected = await reldb.init({ type: 'postgresql', host: 'db', port: 5432, database: 'hai', user: 'postgres', password: process.env.HAI_DB_PASSWORD })
+ * if (!connected.success) throw new Error(connected.error.message)
+ * try {
+ *   const initialized = await reach.init({ providers: [{ name: 'webhook', type: 'api', url: 'https://notify.example.com/events', idempotent: false }], templates: [{ name: 'welcome', provider: 'webhook', subject: 'Welcome {userName}', body: 'Hello {userName}' }], dnd: { enabled: true, strategy: 'delay', start: '22:00', end: '08:00' } })
+ *   if (!initialized.success) throw new Error(initialized.error.message)
+ *   try {
+ *     const template: ReachTemplate = { name: 'welcome', provider: 'webhook', subject: 'Welcome {userName}', body: 'Hello {userName}' }
+ *     const saved = await reach.template.save(template)
+ *     if (!saved.success) throw new Error(saved.error.message)
+ *   }
+ *   finally { await reach.close() }
+ * }
+ * finally {
+ *   const closed = await reldb.close()
+ *   if (!closed.success) throw new Error(closed.error.message)
  * }
  * ```
  */
@@ -339,7 +857,30 @@ interface ReachTemplate {
     body: string;
 }
 /**
- * 渲染后的模板
+ * 渲染后的主题/正文；文本替换不等于HTML安全，可选subject按原模板保留。
+ *
+ * @example
+ * ```ts
+ * import { reach, type RenderedTemplate } from '@h-ai/reach'
+ * const { reldb } = await import('@h-ai/reldb')
+ * const connected = await reldb.init({ type: 'postgresql', host: 'db', port: 5432, database: 'hai', user: 'postgres', password: process.env.HAI_DB_PASSWORD })
+ * if (!connected.success) throw new Error(connected.error.message)
+ * try {
+ *   const initialized = await reach.init({ providers: [{ name: 'webhook', type: 'api', url: 'https://notify.example.com/events', idempotent: false }], templates: [{ name: 'welcome', provider: 'webhook', subject: 'Welcome {userName}', body: 'Hello {userName}' }], dnd: { enabled: true, strategy: 'delay', start: '22:00', end: '08:00' } })
+ *   if (!initialized.success) throw new Error(initialized.error.message)
+ *   try {
+ *     const rendered = await reach.template.render('welcome', { userName: 'Alice' })
+ *     if (!rendered.success) throw new Error(rendered.error.message)
+ *     const value: RenderedTemplate = rendered.data
+ *     const body = value.body
+ *   }
+ *   finally { await reach.close() }
+ * }
+ * finally {
+ *   const closed = await reldb.close()
+ *   if (!closed.success) throw new Error(closed.error.message)
+ * }
+ * ```
  */
 interface RenderedTemplate {
     /** 渲染后的主题 */
@@ -348,7 +889,35 @@ interface RenderedTemplate {
     body: string;
 }
 /**
- * 发送操作接口
+ * 统一发送操作；失败HaiResult不表示已发送，成功结果仍检查内部success与deferred。
+ * 即时外部发送成功不因可选日志失败而转失败，防调用方重复发送；延迟入队必须确认持久写入。
+ *
+ * @example
+ * ```ts
+ * import { reach } from '@h-ai/reach'
+ * const { reldb } = await import('@h-ai/reldb')
+ * const connected = await reldb.init({ type: 'postgresql', host: 'db', port: 5432, database: 'hai', user: 'postgres', password: process.env.HAI_DB_PASSWORD })
+ * if (!connected.success) throw new Error(connected.error.message)
+ * try {
+ *   const initialized = await reach.init({ providers: [{ name: 'webhook', type: 'api', url: 'https://notify.example.com/events', idempotent: false }], templates: [{ name: 'welcome', provider: 'webhook', subject: 'Welcome {userName}', body: 'Hello {userName}' }], dnd: { enabled: true, strategy: 'delay', start: '22:00', end: '08:00' } })
+ *   if (!initialized.success) throw new Error(initialized.error.message)
+ *   try {
+ *     const result = await reach.send({ provider: 'webhook', to: 'user@example.com', template: 'welcome', vars: { userName: 'Alice' } })
+ *     if (!result.success) throw new Error(result.error.message)
+ *     if (!result.data.success) throw new Error('Delivery was not accepted')
+ *     if (result.data.deferred) {
+ *       const queueId = result.data.queueId
+ *       // 持久入队成功，尚未证明接收端已完成外部投递。
+ *     }
+ *     else { const providerMessageId = result.data.messageId }
+ *   }
+ *   finally { await reach.close() }
+ * }
+ * finally {
+ *   const closed = await reldb.close()
+ *   if (!closed.success) throw new Error(closed.error.message)
+ * }
+ * ```
  */
 interface SendOperations {
     /**
@@ -359,68 +928,296 @@ interface SendOperations {
      *
      * @example
      * ```ts
-     * const result = await reach.send({
-     *   provider: 'email',
-     *   to: 'user@example.com',
-     *   template: 'welcome',
-     *   vars: { userName: '张三' },
-     * })
+     * import { reach } from '@h-ai/reach'
+     * const { reldb } = await import('@h-ai/reldb')
+     * const connected = await reldb.init({ type: 'postgresql', host: 'db', port: 5432, database: 'hai', user: 'postgres', password: process.env.HAI_DB_PASSWORD })
+     * if (!connected.success) throw new Error(connected.error.message)
+     * try {
+     *   const initialized = await reach.init({ providers: [{ name: 'webhook', type: 'api', url: 'https://notify.example.com/events', idempotent: false }], templates: [{ name: 'welcome', provider: 'webhook', subject: 'Welcome {userName}', body: 'Hello {userName}' }], dnd: { enabled: true, strategy: 'delay', start: '22:00', end: '08:00' } })
+     *   if (!initialized.success) throw new Error(initialized.error.message)
+     *   try {
+     *     const result = await reach.send({ provider: 'webhook', to: 'user@example.com', template: 'welcome', vars: { userName: 'Alice' } })
+     *     if (!result.success) throw new Error(result.error.message)
+     *     if (!result.data.success) throw new Error('Delivery was not accepted')
+     *     if (result.data.deferred) {
+     *       const queueId = result.data.queueId
+     *       // 持久入队成功，尚未证明接收端已完成外部投递。
+     *     }
+     *     else { const providerMessageId = result.data.messageId }
+     *   }
+     *   finally { await reach.close() }
+     * }
+     * finally {
+     *   const closed = await reldb.close()
+     *   if (!closed.success) throw new Error(closed.error.message)
+     * }
      * ```
      */
     send: (message: ReachMessage) => Promise<HaiResult<SendResult>>;
 }
 /**
- * 模板注册表接口
+ * 数据库模板操作；无数据库时不回退进程模板缓存，resolve失败、list为空，保存/删除返回失败。
+ * saveBatch并发逐条upsert，失败时不承诺其它项回滚；需要原子业务批次时由受控事务流程实现。
  *
- * 所有模板通过数据库持久化存储，避免节点间状态不一致。
- * 配置文件中的模板在 init 时写入数据库。
+ * @example
+ * ```ts
+ * import { reach } from '@h-ai/reach'
+ * const { reldb } = await import('@h-ai/reldb')
+ * const connected = await reldb.init({ type: 'postgresql', host: 'db', port: 5432, database: 'hai', user: 'postgres', password: process.env.HAI_DB_PASSWORD })
+ * if (!connected.success) throw new Error(connected.error.message)
+ * try {
+ *   const initialized = await reach.init({ providers: [{ name: 'webhook', type: 'api', url: 'https://notify.example.com/events', idempotent: false }], templates: [{ name: 'welcome', provider: 'webhook', subject: 'Welcome {userName}', body: 'Hello {userName}' }], dnd: { enabled: true, strategy: 'delay', start: '22:00', end: '08:00' } })
+ *   if (!initialized.success) throw new Error(initialized.error.message)
+ *   try {
+ *     const saved = await reach.template.save({ name: 'welcome', provider: 'webhook', subject: 'Welcome {userName}', body: 'Hello {userName}' })
+ *     if (!saved.success) throw new Error(saved.error.message)
+ *     const rendered = await reach.template.render('welcome', { userName: 'Alice' })
+ *     if (!rendered.success) throw new Error(rendered.error.message)
+ *   }
+ *   finally { await reach.close() }
+ * }
+ * finally {
+ *   const closed = await reldb.close()
+ *   if (!closed.success) throw new Error(closed.error.message)
+ * }
+ * ```
  */
 interface ReachTemplateRegistry {
-    /** 按名称解析模板 */
+    /**
+     * 按名称解析模板
+     * @param name - 实际操作输入，按本方法约束校验。
+     * @returns HaiResult；先检查success，条件提交失败不能伪装成功。
+     *
+     * @example
+     * ```ts
+     * import { reach } from '@h-ai/reach'
+     * const { reldb } = await import('@h-ai/reldb')
+     * const connected = await reldb.init({ type: 'postgresql', host: 'db', port: 5432, database: 'hai', user: 'postgres', password: process.env.HAI_DB_PASSWORD })
+     * if (!connected.success) throw new Error(connected.error.message)
+     * try {
+     *   const initialized = await reach.init({ providers: [{ name: 'webhook', type: 'api', url: 'https://notify.example.com/events', idempotent: false }], templates: [{ name: 'welcome', provider: 'webhook', subject: 'Welcome {userName}', body: 'Hello {userName}' }], dnd: { enabled: true, strategy: 'delay', start: '22:00', end: '08:00' } })
+     *   if (!initialized.success) throw new Error(initialized.error.message)
+     *   try {
+     *     const result = await reach.template.resolve('welcome')
+     *     if (!result.success) throw new Error(result.error.message)
+     *     const providerName = result.data.provider
+     *   }
+     *   finally { await reach.close() }
+     * }
+     * finally {
+     *   const closed = await reldb.close()
+     *   if (!closed.success) throw new Error(closed.error.message)
+     * }
+     * ```
+     */
     resolve: (name: string) => Promise<HaiResult<ReachTemplate>>;
-    /** 保存模板到数据库（upsert） */
+    /**
+     * 保存模板到数据库（upsert）
+     * @param template - 实际操作输入，按本方法约束校验。
+     * @returns HaiResult；先检查success，条件提交失败不能伪装成功。
+     *
+     * @example
+     * ```ts
+     * import { reach, type ReachTemplate } from '@h-ai/reach'
+     * const { reldb } = await import('@h-ai/reldb')
+     * const connected = await reldb.init({ type: 'postgresql', host: 'db', port: 5432, database: 'hai', user: 'postgres', password: process.env.HAI_DB_PASSWORD })
+     * if (!connected.success) throw new Error(connected.error.message)
+     * try {
+     *   const initialized = await reach.init({ providers: [{ name: 'webhook', type: 'api', url: 'https://notify.example.com/events', idempotent: false }], templates: [{ name: 'welcome', provider: 'webhook', subject: 'Welcome {userName}', body: 'Hello {userName}' }], dnd: { enabled: true, strategy: 'delay', start: '22:00', end: '08:00' } })
+     *   if (!initialized.success) throw new Error(initialized.error.message)
+     *   try {
+     *     const template: ReachTemplate = { name: 'welcome', provider: 'webhook', subject: 'Welcome {userName}', body: 'Hello {userName}' }
+     *     const saved = await reach.template.save(template)
+     *     if (!saved.success) throw new Error(saved.error.message)
+     *   }
+     *   finally { await reach.close() }
+     * }
+     * finally {
+     *   const closed = await reldb.close()
+     *   if (!closed.success) throw new Error(closed.error.message)
+     * }
+     * ```
+     */
     save: (template: ReachTemplate) => Promise<HaiResult<void>>;
-    /** 批量保存模板到数据库 */
+    /**
+     * 批量保存模板到数据库
+     * @param templates - 实际操作输入，按本方法约束校验。
+     * @returns HaiResult；先检查success，条件提交失败不能伪装成功。
+     *
+     * @example
+     * ```ts
+     * import { reach } from '@h-ai/reach'
+     * const { reldb } = await import('@h-ai/reldb')
+     * const connected = await reldb.init({ type: 'postgresql', host: 'db', port: 5432, database: 'hai', user: 'postgres', password: process.env.HAI_DB_PASSWORD })
+     * if (!connected.success) throw new Error(connected.error.message)
+     * try {
+     *   const initialized = await reach.init({ providers: [{ name: 'webhook', type: 'api', url: 'https://notify.example.com/events', idempotent: false }], templates: [{ name: 'welcome', provider: 'webhook', subject: 'Welcome {userName}', body: 'Hello {userName}' }], dnd: { enabled: true, strategy: 'delay', start: '22:00', end: '08:00' } })
+     *   if (!initialized.success) throw new Error(initialized.error.message)
+     *   try {
+     *     const result = await reach.template.saveBatch([{ name: 'receipt', provider: 'webhook', body: 'Receipt {orderId}' }, { name: 'reminder', provider: 'webhook', body: 'Reminder {orderId}' }])
+     *     if (!result.success) throw new Error(result.error.message)
+     *     // 非原子批次；失败时应核对已保存条目，不假定整体回滚。
+     *   }
+     *   finally { await reach.close() }
+     * }
+     * finally {
+     *   const closed = await reldb.close()
+     *   if (!closed.success) throw new Error(closed.error.message)
+     * }
+     * ```
+     */
     saveBatch: (templates: ReachTemplate[]) => Promise<HaiResult<void>>;
-    /** 从数据库删除模板 */
+    /**
+     * 从数据库删除模板
+     * @param name - 实际操作输入，按本方法约束校验。
+     * @returns HaiResult；先检查success，条件提交失败不能伪装成功。
+     *
+     * @example
+     * ```ts
+     * import { reach } from '@h-ai/reach'
+     * const { reldb } = await import('@h-ai/reldb')
+     * const connected = await reldb.init({ type: 'postgresql', host: 'db', port: 5432, database: 'hai', user: 'postgres', password: process.env.HAI_DB_PASSWORD })
+     * if (!connected.success) throw new Error(connected.error.message)
+     * try {
+     *   const initialized = await reach.init({ providers: [{ name: 'webhook', type: 'api', url: 'https://notify.example.com/events', idempotent: false }], templates: [{ name: 'welcome', provider: 'webhook', subject: 'Welcome {userName}', body: 'Hello {userName}' }], dnd: { enabled: true, strategy: 'delay', start: '22:00', end: '08:00' } })
+     *   if (!initialized.success) throw new Error(initialized.error.message)
+     *   try {
+     *     const result = await reach.template.remove('welcome')
+     *     if (!result.success) throw new Error(result.error.message)
+     *   }
+     *   finally { await reach.close() }
+     * }
+     * finally {
+     *   const closed = await reldb.close()
+     *   if (!closed.success) throw new Error(closed.error.message)
+     * }
+     * ```
+     */
     remove: (name: string) => Promise<HaiResult<void>>;
-    /** 列出所有模板 */
+    /**
+     * 列出所有模板
+     * @returns HaiResult；先检查success，条件提交失败不能伪装成功。
+     *
+     * @example
+     * ```ts
+     * import { reach } from '@h-ai/reach'
+     * const { reldb } = await import('@h-ai/reldb')
+     * const connected = await reldb.init({ type: 'postgresql', host: 'db', port: 5432, database: 'hai', user: 'postgres', password: process.env.HAI_DB_PASSWORD })
+     * if (!connected.success) throw new Error(connected.error.message)
+     * try {
+     *   const initialized = await reach.init({ providers: [{ name: 'webhook', type: 'api', url: 'https://notify.example.com/events', idempotent: false }], templates: [{ name: 'welcome', provider: 'webhook', subject: 'Welcome {userName}', body: 'Hello {userName}' }], dnd: { enabled: true, strategy: 'delay', start: '22:00', end: '08:00' } })
+     *   if (!initialized.success) throw new Error(initialized.error.message)
+     *   try {
+     *     const result = await reach.template.list()
+     *     if (!result.success) throw new Error(result.error.message)
+     *     const count = result.data.length
+     *   }
+     *   finally { await reach.close() }
+     * }
+     * finally {
+     *   const closed = await reldb.close()
+     *   if (!closed.success) throw new Error(closed.error.message)
+     * }
+     * ```
+     */
     list: () => Promise<HaiResult<ReachTemplate[]>>;
-    /** 渲染模板（从数据库解析后渲染） */
+    /**
+     * 渲染模板（从数据库解析后渲染）
+     * @param name - 实际操作输入，按本方法约束校验。
+     * @param vars - 实际操作输入，按本方法约束校验。
+     * @returns HaiResult；先检查success，条件提交失败不能伪装成功。
+     *
+     * @example
+     * ```ts
+     * import { reach, type RenderedTemplate } from '@h-ai/reach'
+     * const { reldb } = await import('@h-ai/reldb')
+     * const connected = await reldb.init({ type: 'postgresql', host: 'db', port: 5432, database: 'hai', user: 'postgres', password: process.env.HAI_DB_PASSWORD })
+     * if (!connected.success) throw new Error(connected.error.message)
+     * try {
+     *   const initialized = await reach.init({ providers: [{ name: 'webhook', type: 'api', url: 'https://notify.example.com/events', idempotent: false }], templates: [{ name: 'welcome', provider: 'webhook', subject: 'Welcome {userName}', body: 'Hello {userName}' }], dnd: { enabled: true, strategy: 'delay', start: '22:00', end: '08:00' } })
+     *   if (!initialized.success) throw new Error(initialized.error.message)
+     *   try {
+     *     const rendered = await reach.template.render('welcome', { userName: 'Alice' })
+     *     if (!rendered.success) throw new Error(rendered.error.message)
+     *     const value: RenderedTemplate = rendered.data
+     *     const body = value.body
+     *   }
+     *   finally { await reach.close() }
+     * }
+     * finally {
+     *   const closed = await reldb.close()
+     *   if (!closed.success) throw new Error(closed.error.message)
+     * }
+     * ```
+     */
     render: (name: string, vars: Record<string, string>) => Promise<HaiResult<RenderedTemplate>>;
 }
 /**
- * 触达模块函数接口
+ * Reach生命周期、模板、发送及受信队列运维能力；先初始化数据库，再检查reach.init结果，反序close。
+ * API Provider init只建立适配器配置，不探测远端可用性；实际send结果才能判断本次投递。
  *
  * @example
  * ```ts
  * import { reach } from '@h-ai/reach'
- *
- * // 初始化（同时注册多个 Provider）
- * await reach.init({
- *   providers: [
- *     { name: 'email', type: 'smtp', host: 'smtp.example.com', from: 'no-reply@example.com' },
- *     { name: 'sms', type: 'aliyun-sms', accessKeyId: '...', accessKeySecret: '...', signName: '...' },
- *   ],
- * })
- *
- * // 保存模板（绑定到 Provider）
- * await reach.template.save({
- *   name: 'welcome',
- *   provider: 'email',
- *   subject: '欢迎 {userName}',
- *   body: '亲爱的 {userName}，欢迎使用我们的服务！',
- * })
- *
- * // 发送（指定 Provider）
- * await reach.send({ provider: 'email', to: 'user@example.com', template: 'welcome', vars: { userName: '张三' } })
- *
- * // 关闭
- * await reach.close()
+ * const { reldb } = await import('@h-ai/reldb')
+ * const connected = await reldb.init({ type: 'postgresql', host: 'db', port: 5432, database: 'hai', user: 'postgres', password: process.env.HAI_DB_PASSWORD })
+ * if (!connected.success) throw new Error(connected.error.message)
+ * try {
+ *   const initialized = await reach.init({ providers: [{ name: 'webhook', type: 'api', url: 'https://notify.example.com/events', idempotent: false }], templates: [{ name: 'welcome', provider: 'webhook', subject: 'Welcome {userName}', body: 'Hello {userName}' }], dnd: { enabled: true, strategy: 'delay', start: '22:00', end: '08:00' } })
+ *   if (!initialized.success) throw new Error(initialized.error.message)
+ *   try {
+ *     const result = await reach.send({ provider: 'webhook', to: 'user@example.com', template: 'welcome', vars: { userName: 'Alice' } })
+ *     if (!result.success) throw new Error(result.error.message)
+ *     if (!result.data.success) throw new Error('Delivery was not accepted')
+ *     if (result.data.deferred) {
+ *       const queueId = result.data.queueId
+ *       // 持久入队成功，尚未证明接收端已完成外部投递。
+ *     }
+ *     else { const providerMessageId = result.data.messageId }
+ *   }
+ *   finally { await reach.close() }
+ * }
+ * finally {
+ *   const closed = await reldb.close()
+ *   if (!closed.success) throw new Error(closed.error.message)
+ * }
  * ```
  */
 interface ReachFunctions extends SendOperations {
-    /** 初始化触达模块（注册多个 Provider） */
+    /** 持久化队列查询、死信恢复与未知结果人工裁定。 */
+    readonly queue: ReachQueueOperations;
+    /**
+     * 初始化触达模块（注册多个 Provider）
+     * @param config - 实际操作输入，按本方法约束校验。
+     * @returns HaiResult；先检查success，条件提交失败不能伪装成功。
+     *
+     * @example
+     * ```ts
+     * import { reach } from '@h-ai/reach'
+     * const { reldb } = await import('@h-ai/reldb')
+     * const connected = await reldb.init({ type: 'postgresql', host: 'db', port: 5432, database: 'hai', user: 'postgres', password: process.env.HAI_DB_PASSWORD })
+     * if (!connected.success) throw new Error(connected.error.message)
+     * try {
+     *   const initialized = await reach.init({ providers: [{ name: 'webhook', type: 'api', url: 'https://notify.example.com/events', idempotent: false }], templates: [{ name: 'welcome', provider: 'webhook', subject: 'Welcome {userName}', body: 'Hello {userName}' }], dnd: { enabled: true, strategy: 'delay', start: '22:00', end: '08:00' } })
+     *   if (!initialized.success) throw new Error(initialized.error.message)
+     *   try {
+     *     const result = await reach.send({ provider: 'webhook', to: 'user@example.com', template: 'welcome', vars: { userName: 'Alice' } })
+     *     if (!result.success) throw new Error(result.error.message)
+     *     if (!result.data.success) throw new Error('Delivery was not accepted')
+     *     if (result.data.deferred) {
+     *       const queueId = result.data.queueId
+     *       // 持久入队成功，尚未证明接收端已完成外部投递。
+     *     }
+     *     else { const providerMessageId = result.data.messageId }
+     *   }
+     *   finally { await reach.close() }
+     * }
+     * finally {
+     *   const closed = await reldb.close()
+     *   if (!closed.success) throw new Error(closed.error.message)
+     * }
+     * ```
+     */
     init: (config: ReachConfigInput) => Promise<HaiResult<void>>;
     /** 当前脱敏后的配置快照（未初始化时为 null） */
     readonly config: ReachConfig | null;
@@ -428,25 +1225,37 @@ interface ReachFunctions extends SendOperations {
     readonly isInitialized: boolean;
     /** 模板注册表 */
     readonly template: ReachTemplateRegistry;
-    /** 关闭连接并释放资源 */
-    close: () => Promise<void>;
-}
-/**
- * 触达 Provider 接口
- *
- * 由具体实现（console / smtp / aliyun-sms / api）提供。
- */
-interface ReachProvider {
-    /** Provider 名称 */
-    readonly name: string;
-    /** 连接/初始化 Provider */
-    connect: (config: ProviderConfig) => Promise<HaiResult<void>>;
-    /** 发送消息 */
-    send: (message: ReachMessage) => Promise<HaiResult<SendResult>>;
-    /** 关闭连接 */
+    /**
+     * 关闭连接并释放资源
+     *
+     * @example
+     * ```ts
+     * import { reach } from '@h-ai/reach'
+     * const { reldb } = await import('@h-ai/reldb')
+     * const connected = await reldb.init({ type: 'postgresql', host: 'db', port: 5432, database: 'hai', user: 'postgres', password: process.env.HAI_DB_PASSWORD })
+     * if (!connected.success) throw new Error(connected.error.message)
+     * try {
+     *   const initialized = await reach.init({ providers: [{ name: 'webhook', type: 'api', url: 'https://notify.example.com/events', idempotent: false }], templates: [{ name: 'welcome', provider: 'webhook', subject: 'Welcome {userName}', body: 'Hello {userName}' }], dnd: { enabled: true, strategy: 'delay', start: '22:00', end: '08:00' } })
+     *   if (!initialized.success) throw new Error(initialized.error.message)
+     *   try {
+     *     const result = await reach.send({ provider: 'webhook', to: 'user@example.com', template: 'welcome', vars: { userName: 'Alice' } })
+     *     if (!result.success) throw new Error(result.error.message)
+     *     if (!result.data.success) throw new Error('Delivery was not accepted')
+     *     if (result.data.deferred) {
+     *       const queueId = result.data.queueId
+     *       // 持久入队成功，尚未证明接收端已完成外部投递。
+     *     }
+     *     else { const providerMessageId = result.data.messageId }
+     *   }
+     *   finally { await reach.close() }
+     * }
+     * finally {
+     *   const closed = await reldb.close()
+     *   if (!closed.success) throw new Error(closed.error.message)
+     * }
+     * ```
+     */
     close: () => Promise<void>;
-    /** 是否已连接 */
-    isConnected: () => boolean;
 }
 
 /**
@@ -457,10 +1266,36 @@ interface ReachProvider {
  */
 
 /**
- * 触达服务对象
+ * 邮件/短信/API触达统一入口；先检查init与send的HaiResult，成功后还区分deferred和即时Provider结果。
+ * 模板与delay队列使用已初始化数据库，生产共享后端；close停止本地调度/关闭Provider，不撤销已发外部请求。
  *
- * 统一的用户触达入口，支持同时使用邮件、短信、API 回调等多种 Provider。
+ * @example
+ * ```ts
+ * import { reach } from '@h-ai/reach'
+ * const { reldb } = await import('@h-ai/reldb')
+ * const connected = await reldb.init({ type: 'postgresql', host: 'db', port: 5432, database: 'hai', user: 'postgres', password: process.env.HAI_DB_PASSWORD })
+ * if (!connected.success) throw new Error(connected.error.message)
+ * try {
+ *   const initialized = await reach.init({ providers: [{ name: 'webhook', type: 'api', url: 'https://notify.example.com/events', idempotent: false }], templates: [{ name: 'welcome', provider: 'webhook', subject: 'Welcome {userName}', body: 'Hello {userName}' }], dnd: { enabled: true, strategy: 'delay', start: '22:00', end: '08:00' } })
+ *   if (!initialized.success) throw new Error(initialized.error.message)
+ *   try {
+ *     const result = await reach.send({ provider: 'webhook', to: 'user@example.com', template: 'welcome', vars: { userName: 'Alice' } })
+ *     if (!result.success) throw new Error(result.error.message)
+ *     if (!result.data.success) throw new Error('Delivery was not accepted')
+ *     if (result.data.deferred) {
+ *       const queueId = result.data.queueId
+ *       // 持久入队成功，尚未证明接收端已完成外部投递。
+ *     }
+ *     else { const providerMessageId = result.data.messageId }
+ *   }
+ *   finally { await reach.close() }
+ * }
+ * finally {
+ *   const closed = await reldb.close()
+ *   if (!closed.success) throw new Error(closed.error.message)
+ * }
+ * ```
  */
 declare const reach: ReachFunctions;
 
-export { type AliyunSmsProviderConfig, AliyunSmsProviderConfigSchema, type ApiProviderConfig, ApiProviderConfigSchema, type ConsoleProviderConfig, ConsoleProviderConfigSchema, type DndConfig, DndConfigSchema, HaiReachError, type ProviderConfig, ProviderConfigSchema, type ReachChannel, type ReachConfig, type ReachConfigInput, ReachConfigSchema, type ReachFunctions, type ReachMessage, type ReachProvider, type ReachTemplate, type ReachTemplateRegistry, type RenderedTemplate, type SendOperations, type SendResult, type SmtpProviderConfig, SmtpProviderConfigSchema, type TemplateConfig, TemplateConfigSchema, reach };
+export { type AliyunSmsProviderConfig, AliyunSmsProviderConfigSchema, type ApiProviderConfig, ApiProviderConfigSchema, type ConsoleProviderConfig, ConsoleProviderConfigSchema, type DndConfig, DndConfigSchema, HaiReachError, type ProviderConfig, ProviderConfigSchema, type ReachChannel, type ReachConfig, type ReachConfigInput, ReachConfigSchema, type ReachDeadRequeue, ReachDeadRequeueSchema, type ReachFunctions, type ReachMessage, type ReachQueueConfig, ReachQueueConfigSchema, type ReachQueueEntry, type ReachQueueFailure, ReachQueueIdSchema, type ReachQueueListOptions, ReachQueueListSchema, type ReachQueueOperations, type ReachQueueStatus, type ReachTemplate, type ReachTemplateRegistry, type ReachUnknownResolution, ReachUnknownResolutionSchema, type RenderedTemplate, type SendOperations, type SendResult, type SmtpProviderConfig, SmtpProviderConfigSchema, type TemplateConfig, TemplateConfigSchema, reach };