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

package/dist/index.d.ts

@@ -16,25 +16,106 @@ import { PaginationOptionsInput, HaiResult, PaginatedResult } from '@h-ai/core';
  *
  * @example
  * ```ts
- * const config = SchedulerConfigSchema.parse({
- *   enableDb: true,
- *   tickInterval: 1000,
- * })
+ * import { SchedulerConfigSchema } from '@h-ai/scheduler'
+ *
+ * const parsed = SchedulerConfigSchema.safeParse({ enableDb: true, tickInterval: 1000, leaseMs: 300000 })
+ * if (parsed.success) {
+ *   const renewalPeriod = Math.floor(parsed.data.leaseMs / 3)
+ * }
  * ```
  */
 declare const SchedulerConfigSchema: z.ZodObject<{
-    enableDb: z.ZodDefault<z.ZodBoolean>;
+    enableDb: z.ZodDefault<z.ZodLiteral<true>>;
     tickInterval: z.ZodDefault<z.ZodNumber>;
-    lockExpireMs: z.ZodDefault<z.ZodNumber>;
+    leaseMs: z.ZodDefault<z.ZodNumber>;
     nodeId: z.ZodOptional<z.ZodString>;
     maxLogs: z.ZodOptional<z.ZodNumber>;
     retentionDays: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
-/** 调度器配置类型 */
+/**
+ * 手动触发边界，重复使用同一幂等键会命中同一个执行记录。
+ *
+ * @example
+ * ```ts
+ * import { TriggerTaskSchema } from '@h-ai/scheduler'
+ *
+ * const parsed = TriggerTaskSchema.safeParse({ source: 'billing-console', idempotencyKey: 'billing-2026-10' })
+ * if (parsed.success) {
+ *   const sameOccurrenceKey = parsed.data.idempotencyKey
+ * }
+ * ```
+ */
+declare const TriggerTaskSchema: z.ZodObject<{
+    source: z.ZodOptional<z.ZodString>;
+    idempotencyKey: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * 可信服务端人工核对结果；必须先停止旧 runner，不能将未知执行直接重排。
+ *
+ * @example
+ * ```ts
+ * import { ExecutionResolutionSchema, scheduler } from '@h-ai/scheduler'
+ *
+ * // 可信运维流程已停止旧 runner 并核对实际外部结果。
+ * const pending = await scheduler.execution.listUnknown({ limit: 10 })
+ * if (!pending.success) throw new Error(pending.error.message)
+ * const entry = pending.data[0]
+ * if (entry) {
+ *   const resolution = ExecutionResolutionSchema.parse({ status: 'discarded', expectedUpdatedAt: entry.updatedAt })
+ *   const resolved = await scheduler.execution.resolveUnknown(entry.occurrenceId, resolution)
+ *   if (!resolved.success) throw new Error(resolved.error.message)
+ * }
+ * ```
+ */
+declare const ExecutionResolutionSchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        success: "success";
+        discarded: "discarded";
+    }>;
+    expectedUpdatedAt: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * 调度器配置类型
+ *
+ * @example
+ * ```ts
+ * import type { SchedulerConfig } from '@h-ai/scheduler'
+ * import { SchedulerConfigSchema } from '@h-ai/scheduler'
+ *
+ * const config: SchedulerConfig = SchedulerConfigSchema.parse({ leaseMs: 60000 })
+ * const renewalInterval = config.leaseMs / 3
+ * ```
+ */
 type SchedulerConfig = z.infer<typeof SchedulerConfigSchema>;
-/** 调度器配置输入类型 */
+/**
+ * 调度器配置输入类型
+ *
+ * @example
+ * ```ts
+ * import type { SchedulerConfigInput } from '@h-ai/scheduler'
+ * import { scheduler } from '@h-ai/scheduler'
+ *
+ * // 宿主已成功初始化共享 reldb。
+ * const config: SchedulerConfigInput = { leaseMs: 60000, retentionDays: 30 }
+ * const initialized = await scheduler.init(config)
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * ```
+ */
 type SchedulerConfigInput = z.input<typeof SchedulerConfigSchema>;
 
+/**
+ * Scheduler 领域错误定义；业务调用先判断 success 再按错误码分支。
+ *
+ * @example
+ * ```ts
+ * import { HaiSchedulerError, scheduler } from '@h-ai/scheduler'
+ *
+ * const result = await scheduler.trigger('missing-task')
+ * if (!result.success && result.error.code === HaiSchedulerError.TASK_NOT_FOUND.code) {
+ *   const missingTask = true
+ * }
+ * ```
+ */
 declare const HaiSchedulerError: {
     readonly NOT_INITIALIZED: _h_ai_core.HaiErrorDef;
     readonly INIT_FAILED: _h_ai_core.HaiErrorDef;
@@ -48,27 +129,85 @@ declare const HaiSchedulerError: {
     readonly DB_SAVE_FAILED: _h_ai_core.HaiErrorDef;
     readonly ALREADY_RUNNING: _h_ai_core.HaiErrorDef;
     readonly NOT_RUNNING: _h_ai_core.HaiErrorDef;
-    readonly LOCK_ACQUIRE_FAILED: _h_ai_core.HaiErrorDef;
     readonly JS_COMPILE_FAILED: _h_ai_core.HaiErrorDef;
     readonly HOOK_EXECUTION_FAILED: _h_ai_core.HaiErrorDef;
+    readonly LOG_PERSIST_FAILED: _h_ai_core.HaiErrorDef;
 };
-/** 任务参数字典（键值对） */
+/**
+ * 任务参数字典（键值对）
+ *
+ * @example
+ * ```ts
+ * import type { TaskParams } from '@h-ai/scheduler'
+ *
+ * const params: TaskParams = { month: '2026-10', dryRun: true }
+ * const month = params.month
+ * ```
+ */
 type TaskParams = Record<string, unknown>;
-/** 任务触发类型 */
+/**
+ * 任务触发类型
+ *
+ * @example
+ * ```ts
+ * import type { TaskTriggerType } from '@h-ai/scheduler'
+ *
+ * const triggerType: TaskTriggerType = 'manual'
+ * const isManual = triggerType === 'manual'
+ * ```
+ */
 type TaskTriggerType = 'scheduled' | 'manual';
-/** 任务处理器类型 */
+/**
+ * 任务处理器类型
+ *
+ * @example
+ * ```ts
+ * import type { TaskHandlerKind } from '@h-ai/scheduler'
+ *
+ * const kind: TaskHandlerKind = 'api'
+ * const needsNetwork = kind === 'api'
+ * ```
+ */
 type TaskHandlerKind = 'api' | 'js';
-/** 失败重试策略 */
+/**
+ * 失败重试策略
+ *
+ * @example
+ * ```ts
+ * import type { TaskRetryPolicy } from '@h-ai/scheduler'
+ *
+ * const retry: TaskRetryPolicy = { maxAttempts: 3, backoffMs: [1000, 5000] }
+ * // 只有外部副作用确实按 occurrenceId 持久去重时，任务才能声明 idempotent。
+ * ```
+ */
 interface TaskRetryPolicy {
-    /** 最大尝试次数（包含首次执行，最小 1） */
+    /** 最大尝试次数（含首次及崩溃恢复，范围 1–100，默认 1）。 */
     maxAttempts: number;
     /** 每次重试前的退避时间（毫秒）；按顺序对应第 2、3... 次尝试 */
     backoffMs?: number[];
 }
-/** 任务执行目标类型 */
+/**
+ * 任务执行目标类型
+ *
+ * @example
+ * ```ts
+ * import type { TaskExecutionTargetType } from '@h-ai/scheduler'
+ *
+ * const target: TaskExecutionTargetType = 'hook'
+ * const usesHostCallback = target === 'hook'
+ * ```
+ */
 type TaskExecutionTargetType = TaskHandlerKind | 'hook';
 /**
  * API 任务配置
+ *
+ * @example
+ * ```ts
+ * import type { ApiTaskConfig } from '@h-ai/scheduler'
+ *
+ * const handler: ApiTaskConfig = { kind: 'api', url: 'https://example.com/health', method: 'GET', timeout: 5000, maxResponseBytes: 4096 }
+ * // API 接收端若支持重试，须持久处理 Idempotency-Key 与 fencing 元数据。
+ * ```
  */
 interface ApiTaskConfig {
     /** 处理器类型 */
@@ -95,6 +234,14 @@ interface ApiTaskConfig {
  *
  * `code` 为 JS 函数字符串，例如：
  * `(context) => ({ taskId: context.task.id, params: context.params })`
+ *
+ * @example
+ * ```ts
+ * import type { JsTaskConfig } from '@h-ai/scheduler'
+ *
+ * const handler: JsTaskConfig = { kind: 'js', code: '(context) => ({ taskId: context.taskId })', timeout: 1000 }
+ * // 仅装载受信任的服务端源码；工作线程不是不可信代码沙箱。
+ * ```
  */
 interface JsTaskConfig {
     /** 处理器类型 */
@@ -104,34 +251,30 @@ interface JsTaskConfig {
     /** 独立线程执行期限，单位毫秒（默认 30000，含线程启动）；超时终止线程后才允许重试 */
     timeout?: number;
 }
-/** 统一任务处理器配置 */
+/**
+ * 统一任务处理器配置
+ *
+ * @example
+ * ```ts
+ * import type { TaskHandlerConfig } from '@h-ai/scheduler'
+ *
+ * const handler: TaskHandlerConfig = { kind: 'api', url: 'https://example.com/health' }
+ * const timeout = handler.timeout ?? 30000
+ * ```
+ */
 type TaskHandlerConfig = ApiTaskConfig | JsTaskConfig;
 /**
  * 任务定义
  *
  * @example
  * ```ts
- * const jsTask: TaskDefinition = {
- *   id: 'cleanup',
- *   name: '清理过期数据',
- *   cron: '0 2 * * *',
- *   params: { channel: 'nightly' },
- *   handler: {
- *     kind: 'js',
- *     code: '(context) => ({ taskId: context.task.id, params: context.params })',
- *   },
- * }
+ * import type { TaskDefinition } from '@h-ai/scheduler'
+ * import { scheduler } from '@h-ai/scheduler'
  *
- * const apiTask: TaskDefinition = {
- *   id: 'health-check',
- *   name: '健康检查',
- *   cron: '&#42;/5 * * * *',
- *   handler: {
- *     kind: 'api',
- *     url: 'https://api.example.com/health',
- *     method: 'GET',
- *   },
- * }
+ * // 宿主已成功初始化共享 reldb 与 scheduler。
+ * const definition: TaskDefinition = { ...{ id: 'daily-report', name: '每日报表', cron: '0 2 * * *', timezone: 'UTC' }, handler: { kind: 'api', url: 'https://example.com/health', maxResponseBytes: 4096 } }
+ * const registered = await scheduler.register(definition)
+ * if (!registered.success) throw new Error(registered.error.message)
  * ```
  */
 interface TaskDefinition {
@@ -143,7 +286,7 @@ interface TaskDefinition {
     description?: string;
     /** cron 表达式（标准 5 字段：分 时 日 月 周） */
     cron: string;
-    /** IANA 时区，用于解释 cron 墙上时间；省略时使用运行环境默认时区 */
+    /** IANA 时区，用于解释 cron 墙上时间；省略或清空时统一使用 UTC，不读取节点 TZ。 */
     timezone?: string;
     /** 是否启用（默认 true） */
     enabled?: boolean;
@@ -151,6 +294,8 @@ interface TaskDefinition {
     deleteAfterRun?: boolean;
     /** 失败重试策略 */
     retry?: TaskRetryPolicy;
+    /** 全部副作用按 context.occurrenceId 原子持久去重时才为 true；默认 false，未知结果禁止自动重跑。 */
+    idempotent?: boolean;
     /** 通用参数 */
     params?: TaskParams;
     /** 任务处理器；为空时可由全局事件回调统一处理 */
@@ -158,6 +303,14 @@ interface TaskDefinition {
 }
 /**
  * 任务触发信息
+ *
+ * @example
+ * ```ts
+ * import type { TaskTriggerInfo } from '@h-ai/scheduler'
+ *
+ * const trigger: TaskTriggerInfo = { type: 'manual', source: 'billing-console' }
+ * const source = trigger.source ?? 'cron'
+ * ```
  */
 interface TaskTriggerInfo {
     /** 触发类型 */
@@ -167,10 +320,27 @@ interface TaskTriggerInfo {
 }
 /**
  * 任务执行上下文
+ *
+ * @example
+ * ```ts
+ * import type { SchedulerTaskContext } from '@h-ai/scheduler'
+ *
+ * function safeReceipt(context: SchedulerTaskContext): string {
+ *   if (!context.occurrenceId || !context.executionToken) throw new Error('Shared execution identity required')
+ *   return context.occurrenceId
+ * }
+ * // 接收端将稳定 receipt 原子持久去重；executionToken 不写入用户可见日志。
+ * ```
  */
 interface SchedulerTaskContext {
     /** 一次调度发生的稳定标识；所有重试共享，供宿主构造业务幂等键。 */
     occurrenceId?: string;
+    /** 当前领取独有的凭据，用于宿主条件提交；续租失败后不能继续产生副作用。 */
+    executionToken?: string;
+    /** 数据库执行序号；与 attempt 组成接收端可比较的 fencing 版本。 */
+    sequence?: number;
+    /** 同一 occurrence 中持久化的尝试次数。 */
+    attempt?: number;
     /** 当前任务 */
     task: TaskDefinition;
     /** 任务 ID */
@@ -180,10 +350,35 @@ interface SchedulerTaskContext {
     /** 触发信息 */
     trigger: TaskTriggerInfo;
 }
-/** 编译后的 JS 任务函数 */
+/**
+ * 编译后的 JS 任务函数
+ *
+ * @example
+ * ```ts
+ * import type { JsTaskHandler } from '@h-ai/scheduler'
+ *
+ * const handler: JsTaskHandler = (context, signal) => {
+ *   signal?.throwIfAborted()
+ *   return { taskId: context.taskId, batch: context.params.batch }
+ * }
+ * ```
+ */
 type JsTaskHandler = (context: SchedulerTaskContext, signal?: AbortSignal) => unknown | Promise<unknown>;
-/** 任务开始事件 */
+/**
+ * 任务开始事件
+ *
+ * @example
+ * ```ts
+ * import type { SchedulerTaskStartEvent } from '@h-ai/scheduler'
+ *
+ * function summarizeStart(event: SchedulerTaskStartEvent) {
+ *   return { taskId: event.task.id, occurrenceId: event.context?.occurrenceId, observedAt: event.startedAt }
+ * }
+ * ```
+ */
 interface SchedulerTaskStartEvent {
+    /** 已领取执行的持久身份，观测回调也可据此标记或幂等处理；竞争中断时不存在。 */
+    context?: SchedulerTaskContext;
     /** 关闭调度器时取消；回调必须停止后续副作用并释放资源 */
     signal: AbortSignal;
     /** 当前任务 */
@@ -193,19 +388,55 @@ interface SchedulerTaskStartEvent {
     /** 开始时间（Unix 时间戳，毫秒） */
     startedAt: number;
 }
-/** 任务执行事件 */
+/**
+ * 任务执行事件
+ *
+ * @example
+ * ```ts
+ * import type { SchedulerTaskExecuteEvent } from '@h-ai/scheduler'
+ *
+ * function execute(event: SchedulerTaskExecuteEvent) {
+ *   event.signal.throwIfAborted()
+ *   return { taskId: event.context.taskId, params: event.context.params }
+ * }
+ * ```
+ */
 interface SchedulerTaskExecuteEvent extends SchedulerTaskStartEvent {
     /** 执行上下文 */
     context: SchedulerTaskContext;
 }
-/** 任务中断事件 */
+/**
+ * 任务中断事件
+ *
+ * @example
+ * ```ts
+ * import type { SchedulerTaskInterruptedEvent } from '@h-ai/scheduler'
+ *
+ * function summarizeInterruption(event: SchedulerTaskInterruptedEvent) {
+ *   return { taskId: event.task.id, reason: event.reason, observedAt: event.interruptedAt }
+ * }
+ * // 中断观测不能证明外部副作用不存在。
+ * ```
+ */
 interface SchedulerTaskInterruptedEvent extends SchedulerTaskStartEvent {
     /** 中断时间（Unix 时间戳，毫秒） */
     interruptedAt: number;
     /** 中断原因 */
     reason: string;
 }
-/** 任务结束事件 */
+/**
+ * 任务结束事件
+ *
+ * @example
+ * ```ts
+ * import type { SchedulerTaskFinishEvent } from '@h-ai/scheduler'
+ *
+ * function needsLogRepair(event: SchedulerTaskFinishEvent): boolean {
+ *   return event.log.persistence.status === 'pending'
+ * }
+ * // 结束回调是观测；业务是否已提交以 journal 为准。
+ * ```
+ */
 interface SchedulerTaskFinishEvent extends SchedulerTaskStartEvent {
     /** 结束时间（Unix 时间戳，毫秒） */
     finishedAt: number;
@@ -217,6 +448,19 @@ interface SchedulerTaskFinishEvent extends SchedulerTaskStartEvent {
  *
  * - `onTaskExecute` 可用于统一处理无内置 handler 的任务
  * - `onTaskStart` / `onTaskInterrupted` / `onTaskFinish` 用于观测生命周期
+ *
+ * @example
+ * ```ts
+ * import type { SchedulerTaskHooks } from '@h-ai/scheduler'
+ *
+ * const hooks: SchedulerTaskHooks = {
+ *   onTaskExecute: ({ context, signal }) => {
+ *     signal.throwIfAborted()
+ *     return { taskId: context.taskId }
+ *   },
+ * }
+ * // 有副作用的宿主需使用 context.occurrenceId 和持久条件写入。
+ * ```
  */
 interface SchedulerTaskHooks {
     /** 任务开始前触发 */
@@ -228,14 +472,60 @@ interface SchedulerTaskHooks {
     /** 任务结束时触发 */
     onTaskFinish?: (event: SchedulerTaskFinishEvent) => void | Promise<void>;
 }
-/** 执行状态 */
-type ExecutionStatus = 'success' | 'failed' | 'interrupted';
+/**
+ * 执行状态
+ *
+ * @example
+ * ```ts
+ * import type { ExecutionStatus } from '@h-ai/scheduler'
+ *
+ * function needsReconciliation(status: ExecutionStatus): boolean {
+ *   return status === 'unknown'
+ * }
+ * // unknown 先隔离旧执行并核对外部效果，不换键重试。
+ * ```
+ */
+type ExecutionStatus = 'success' | 'failed' | 'interrupted' | 'unknown';
+/**
+ * 日志投影状态，与业务 status 独立；unconfirmed 表示没有可补写的已确认终态。
+ *
+ * @example
+ * ```ts
+ * import type { TaskLogPersistence } from '@h-ai/scheduler'
+ *
+ * const persistence: TaskLogPersistence = { status: 'pending', error: { code: 'hai:scheduler:032', message: 'Log projection pending' } }
+ * const needsRepair = persistence.status === 'pending'
+ * ```
+ */
+interface TaskLogPersistence {
+    /** pending 可由已发布 journal 补写；persisted 已确认日志和回执；unconfirmed 不能推断业务结果。 */
+    status: 'pending' | 'persisted' | 'unconfirmed';
+    /** 安全的公开错误，不包含 SQL、驱动 cause 或连接参数。 */
+    error?: {
+        code: string;
+        message: string;
+    };
+}
 /**
  * 任务执行日志
+ *
+ * @example
+ * ```ts
+ * import type { TaskExecutionLog } from '@h-ai/scheduler'
+ *
+ * function summarize(log: TaskExecutionLog) {
+ *   return { businessStatus: log.status, logStatus: log.persistence.status, occurrenceId: log.occurrenceId }
+ * }
+ * // pending 的成功业务只补写日志，不重跑处理器。
+ * ```
  */
 interface TaskExecutionLog {
-    /** 日志 ID */
-    id: number;
+    /** 持久执行回执；相同定时 occurrence 或手动幂等键共用。 */
+    occurrenceId?: string;
+    /** 每次尝试固定的 UUID 主键；未知写入回执或并发补写均复用。 */
+    id: string;
+    /** 独立持久化状态；业务成功不等于日志保存成功。 */
+    persistence: TaskLogPersistence;
     /** 任务 ID */
     taskId: string;
     /** 任务名称 */
@@ -248,7 +538,7 @@ interface TaskExecutionLog {
     triggerSource: string | null;
     /** 执行状态 */
     status: ExecutionStatus;
-    /** 执行结果（JSON 字符串） */
+    /** 序列化 JS/Hook 结果或 API 响应正文；无结果为 null */
     result: string | null;
     /** 错误或中断信息 */
     error: string | null;
@@ -261,6 +551,17 @@ interface TaskExecutionLog {
 }
 /**
  * 执行日志查询选项
+ *
+ * @example
+ * ```ts
+ * import type { LogQueryOptions } from '@h-ai/scheduler'
+ * import { scheduler } from '@h-ai/scheduler'
+ *
+ * const options: LogQueryOptions = { taskId: 'daily-report', status: 'success', pagination: { page: 1, pageSize: 20 } }
+ * const logs = await scheduler.getLogs(options)
+ * if (!logs.success) throw new Error(logs.error.message)
+ * const page = logs.data.items
+ * ```
  */
 interface LogQueryOptions {
     /** 按任务 ID 过滤 */
@@ -278,7 +579,17 @@ interface LogQueryOptions {
     /** 分页参数（page 从 1 开始，pageSize 默认 20） */
     pagination?: PaginationOptionsInput;
 }
-/** 日志清理策略 */
+/**
+ * 日志清理策略
+ *
+ * @example
+ * ```ts
+ * import type { SchedulerLogCleanupPolicy } from '@h-ai/scheduler'
+ *
+ * const policy: SchedulerLogCleanupPolicy = { maxLogs: 1000, retentionDays: 30 }
+ * // 仅清理日志投影，不撤销或重排共享 execution journal。
+ * ```
+ */
 interface SchedulerLogCleanupPolicy {
     /** 最多保留日志条数 */
     maxLogs?: number;
@@ -290,15 +601,28 @@ interface SchedulerLogCleanupPolicy {
  *
  * 可更新的字段包括：名称、cron 表达式、启用状态、参数、处理器。
  * 任务 ID 不可更新。
+ *
+ * @example
+ * ```ts
+ * import type { TaskUpdateInput } from '@h-ai/scheduler'
+ * import { scheduler } from '@h-ai/scheduler'
+ *
+ * const updates: TaskUpdateInput = { enabled: false, timezone: null }
+ * const changed = await scheduler.updateTask('daily-report', updates)
+ * if (!changed.success) throw new Error(changed.error.message)
+ * // null 时区恢复 UTC，任务 ID 不能修改。
+ * ```
  */
 interface TaskUpdateInput {
+    /** 全部副作用的持久去重能力声明。 */
+    idempotent?: boolean;
     /** 任务名称 */
     name?: string;
     /** 任务描述 */
     description?: string;
     /** cron 表达式 */
     cron?: string;
-    /** IANA 时区；传 null 表示清空任务时区 */
+    /** IANA 时区；传 null 表示清空并恢复 UTC，不读取节点 TZ。 */
     timezone?: string | null;
     /** 是否启用 */
     enabled?: boolean;
@@ -311,15 +635,122 @@ interface TaskUpdateInput {
     /** 任务处理器；传 null 表示清空内置处理器 */
     handler?: TaskHandlerConfig | null;
 }
-/** 手工触发输入 */
+/**
+ * 手工触发输入
+ *
+ * @example
+ * ```ts
+ * import type { TriggerTaskInput } from '@h-ai/scheduler'
+ * import { scheduler } from '@h-ai/scheduler'
+ *
+ * const options: TriggerTaskInput = { source: 'billing-console', idempotencyKey: 'billing-2026-10' }
+ * const result = await scheduler.trigger('daily-report', options)
+ * if (!result.success) throw new Error(result.error.message)
+ * const status = result.data.status
+ * ```
+ */
 interface TriggerTaskInput {
     /** 手工触发来源（例如 admin-console / api / cli） */
     source?: string;
+    /** 稳定业务触发键（1–128 字符）；同任务重复使用会命中同一持久执行。 */
+    idempotencyKey?: string;
+}
+/**
+ * 可信运维可见的执行状态；unknown 继续占用任务串行槽。
+ *
+ * @example
+ * ```ts
+ * import type { SchedulerExecutionState } from '@h-ai/scheduler'
+ *
+ * function occupiesUncertainSlot(state: SchedulerExecutionState): boolean {
+ *   return state === 'unknown'
+ * }
+ * ```
+ */
+type SchedulerExecutionState = 'claimed' | 'running' | ExecutionStatus | 'discarded';
+/**
+ * 不包含代码、参数、URL 或 owner 凭据的共享执行记录。
+ *
+ * @example
+ * ```ts
+ * import type { SchedulerExecutionEntry } from '@h-ai/scheduler'
+ *
+ * function publicAudit(entry: SchedulerExecutionEntry) {
+ *   return { occurrenceId: entry.occurrenceId, status: entry.status, revision: entry.updatedAt }
+ * }
+ * // 安全投影不包含 owner token 和业务载荷。
+ * ```
+ */
+interface SchedulerExecutionEntry {
+    /** 稳定执行回执。 */
+    occurrenceId: string;
+    /** 任务标识。 */
+    taskId: string;
+    /** 共享状态。 */
+    status: SchedulerExecutionState;
+    /** 数据库序号，配合 attempt 用于外部 fencing。 */
+    sequence: number;
+    /** 已开始的尝试次数。 */
+    attemptCount: number;
+    /** 最近状态版本（Unix 毫秒），用于人工裁定条件。 */
+    updatedAt: number;
+    /** 日志投影独立状态；pending 不会重新排队业务。 */
+    logPersistence: TaskLogPersistence['status'];
+}
+/**
+ * 可信服务端的执行查询与人工核对入口。
+ *
+ * @example
+ * ```ts
+ * import type { SchedulerExecutionOperations } from '@h-ai/scheduler'
+ *
+ * async function repairPending(execution: SchedulerExecutionOperations) {
+ *   const pending = await execution.listLogFailures({ limit: 20 })
+ *   if (!pending.success) return pending
+ *   for (const entry of pending.data) {
+ *     const repaired = await execution.repairLog(entry.occurrenceId)
+ *     if (!repaired.success) return repaired
+ *   }
+ * }
+ * // 此链路不会调用业务 handler。
+ * ```
+ */
+interface SchedulerExecutionOperations {
+    /** 按回执查询安全元数据。@example await scheduler.execution.get(occurrenceId) */
+    get: (occurrenceId: string) => Promise<HaiResult<SchedulerExecutionEntry | null>>;
+    /** 有界查询待核对的 unknown；每页 1–100 条。@example await scheduler.execution.listUnknown({ limit: 50, offset: 0 }) */
+    listUnknown: (options?: {
+        limit?: number;
+        offset?: number;
+    }) => Promise<HaiResult<SchedulerExecutionEntry[]>>;
+    /** 分页查询已有终态但日志尚待补写的回执，不含业务载荷。@example await scheduler.execution.listLogFailures({ limit: 50 }) */
+    listLogFailures: (options?: {
+        limit?: number;
+        offset?: number;
+    }) => Promise<HaiResult<SchedulerExecutionEntry[]>>;
+    /** 只从已发布 journal 幂等补写日志，不执行业务；并发调用安全。@example await scheduler.execution.repairLog(occurrenceId) */
+    repairLog: (occurrenceId: string) => Promise<HaiResult<void>>;
+    /** 先终止旧 runner 并核对外部结果，再条件裁定；不能重新排队。@example await scheduler.execution.resolveUnknown(id, { status: 'discarded', expectedUpdatedAt: entry.updatedAt }) */
+    resolveUnknown: (occurrenceId: string, resolution: {
+        status: 'success' | 'discarded';
+        expectedUpdatedAt: number;
+    }) => Promise<HaiResult<void>>;
 }
 /**
  * 调度器初始化输入
  *
  * 包含调度器配置、可选的预定义任务列表，以及可选的全局生命周期回调。
+ *
+ * @example
+ * ```ts
+ * import type { SchedulerInitInput } from '@h-ai/scheduler'
+ * import { scheduler } from '@h-ai/scheduler'
+ *
+ * // 宿主已成功初始化共享 reldb。
+ * const input: SchedulerInitInput = { leaseMs: 60000, tasks: [{ id: 'daily-report', name: '每日报表', cron: '0 2 * * *', timezone: 'UTC' }], hooks: { onTaskExecute: ({ context }) => ({ taskId: context.taskId }) } }
+ * const initialized = await scheduler.init(input)
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * ```
  */
 interface SchedulerInitInput extends SchedulerConfigInput {
     /** 预定义任务列表（从配置中加载，初始化时自动注册） */
@@ -329,8 +760,22 @@ interface SchedulerInitInput extends SchedulerConfigInput {
 }
 /**
  * 调度器函数接口
+ *
+ * @example
+ * ```ts
+ * import type { SchedulerFunctions } from '@h-ai/scheduler'
+ *
+ * async function stopScheduler(instance: SchedulerFunctions) {
+ *   const stopped = instance.stop()
+ *   if (!stopped.success) return stopped
+ *   await instance.close()
+ * }
+ * // close 返回 Promise<void>，宿主随后关闭自己拥有的共享数据库。
+ * ```
  */
 interface SchedulerFunctions {
+    /** 共享执行状态、未知结果查询与可信人工裁定。 */
+    readonly execution: SchedulerExecutionOperations;
     /** 刷新共享数据库中的任务定义，用于跨实例配置读取。 */
     refreshTasks: () => Promise<HaiResult<void>>;
     /** 初始化调度器 */
@@ -375,6 +820,38 @@ interface SchedulerFunctions {
  * @module scheduler-main
  */
 
+/**
+ * 定时任务公共入口；先初始化共享 RelDB，再注册/触发/启动；关闭会排空任务和日志修复，宿主最后关闭数据库。
+ *
+ * @example
+ * ```ts
+ * import { core } from '@h-ai/core'
+ * import { reldb } from '@h-ai/reldb'
+ * import { scheduler } from '@h-ai/scheduler'
+ *
+ * // 本地开发示例；生产使用所有节点共同连接的 PostgreSQL/MySQL。
+ * const database = await reldb.init({ type: 'sqlite', database: ':memory:' })
+ * if (!database.success) throw new Error(database.error.message)
+ * try {
+ *   const initialized = await scheduler.init({ hooks: { onTaskExecute: ({ context }) => ({ taskId: context.taskId }) } })
+ *   if (!initialized.success) throw new Error(initialized.error.message)
+ *   const registered = await scheduler.register({ id: 'daily-report', name: '每日报表', cron: '0 2 * * *', timezone: 'UTC' })
+ *   if (!registered.success) throw new Error(registered.error.message)
+ *   const executed = await scheduler.trigger('daily-report', { idempotencyKey: 'report-2026-10-23' })
+ *   if (!executed.success) throw new Error(executed.error.message)
+ *   // 业务 status 与 persistence 分开判断；pending 只补日志，不重跑业务。
+ *   const status = executed.data.status
+ *   const persistence = executed.data.persistence.status
+ * } finally {
+ *   await scheduler.close()
+ *   const closed = await reldb.close()
+ *   if (!closed.success) {
+ *     core.logger.error('Database cleanup failed', { errorCode: closed.error.code })
+ *     process.exitCode = 1
+ *   }
+ * }
+ * ```
+ */
 declare const scheduler: SchedulerFunctions;
 
-export { type ApiTaskConfig, type ExecutionStatus, HaiSchedulerError, type JsTaskConfig, type JsTaskHandler, type LogQueryOptions, type SchedulerConfig, type SchedulerConfigInput, SchedulerConfigSchema, type SchedulerFunctions, type SchedulerInitInput, type SchedulerLogCleanupPolicy, type SchedulerTaskContext, type SchedulerTaskExecuteEvent, type SchedulerTaskFinishEvent, type SchedulerTaskHooks, type SchedulerTaskInterruptedEvent, type SchedulerTaskStartEvent, type TaskDefinition, type TaskExecutionLog, type TaskExecutionTargetType, type TaskHandlerConfig, type TaskHandlerKind, type TaskParams, type TaskRetryPolicy, type TaskTriggerInfo, type TaskTriggerType, type TaskUpdateInput, type TriggerTaskInput, scheduler };
+export { type ApiTaskConfig, ExecutionResolutionSchema, type ExecutionStatus, HaiSchedulerError, type JsTaskConfig, type JsTaskHandler, type LogQueryOptions, type SchedulerConfig, type SchedulerConfigInput, SchedulerConfigSchema, type SchedulerExecutionEntry, type SchedulerExecutionOperations, type SchedulerExecutionState, type SchedulerFunctions, type SchedulerInitInput, type SchedulerLogCleanupPolicy, type SchedulerTaskContext, type SchedulerTaskExecuteEvent, type SchedulerTaskFinishEvent, type SchedulerTaskHooks, type SchedulerTaskInterruptedEvent, type SchedulerTaskStartEvent, type TaskDefinition, type TaskExecutionLog, type TaskExecutionTargetType, type TaskHandlerConfig, type TaskHandlerKind, type TaskLogPersistence, type TaskParams, type TaskRetryPolicy, type TaskTriggerInfo, type TaskTriggerType, type TaskUpdateInput, type TriggerTaskInput, TriggerTaskSchema, scheduler };