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

package/README.en.md

@@ -4,30 +4,24 @@
 
 [Framework home](../../README.en.md) · Related modules: [@h-ai/cache](../cache/README.en.md) · [@h-ai/core](../core/README.en.md) · [@h-ai/reldb](../reldb/README.en.md)
 
-A scheduled task module with a unified task model, cron scheduling, JS function strings / HTTP API execution, persistence, execution log queries, and global task lifecycle hooks.
-
-With the database enabled, nodes refresh persisted definitions every `tickInterval` (default 1000 ms); `tasks` is the latest successful snapshot. Registration, updates, deletion, manual triggers, and each attempt after acquiring a scheduling lock reread definitions. Deleted, disabled, or rescheduled old tasks stop executing; read failures abort the attempt. Already-started business side effects are not rolled back by remote changes. `init({ tasks })` remains node-local; use persisted `register()` for dynamic tasks across nodes. Cross-node deduplication requires shared Redis; memory cache is single-process only.
-
-Call `await scheduler.refreshTasks()` to refresh without execution; concurrent refreshes of the same snapshot share one read. Registration, updates, and deletion change memory only after successful persistence. Invalid full updates leave cron unchanged. Pass `retry: null` or `handler: null` to clear retries or built-in handlers.
-
-Hook business errors are recorded as `failed` and apply `retry`; missing handlers, cancellation, or host-thrown `SchedulerTaskSkippedError` are `interrupted`. `event.context.occurrenceId` identifies an occurrence: the same scheduled minute shares it across nodes, each manual trigger is independent, and retries reuse the original. Hosts can persist idempotency receipts with this ID; long tasks spanning periods still need a host-maintained lease for mutual exclusion. `deleteAfterRun` deletes only after success. Definitions are checked before retry and successful cleanup; one database DELETE atomically matches the executed definition, preserving concurrent updates.
-
-Multi-node regression tests build current source and start two real Node processes sharing SQLite and Testcontainers Redis, validating definition convergence and same-minute lock contention. A working Docker/Podman service is required before `pnpm --filter @h-ai/scheduler test`.
+## Introduction
 
-`await scheduler.close()` stops task intake, cancels HTTP, JS workers, and retry waits, then awaits execution chain exit before clearing state. Reinitialization waits for closure. All lifecycle events expose `signal`; hooks must observe cancellation and stop external side effects. The framework cannot terminate business code on the same thread; do not block the event loop in hooks. Cancelled old executions no longer retry, delete tasks, or call new-instance hooks. Keep the database and cache available until scheduler closure completes, then close dependencies.
+A scheduled task module with a unified task model, cron scheduling, JS function strings / HTTP API execution, persistence, execution log queries, and global task lifecycle hooks.
 
-Each JS string runs in its own worker; `timeout` defaults to 30000 ms including startup. On timeout, terminate the thread and await exit before logging failure or retrying. Synchronous infinite loops cannot block the main event loop. Context and results must support structured cloning. A worker's `vm` is still not a security sandbox; code must come from trusted server-side sources.
+## Core features
 
-API task `timeout` (default 30000 ms) covers the request and full response body read. `ApiTaskConfig.maxResponseBytes` limits received body bytes (positive safe integer; default 1048576, or 1 MiB). `maxResponseBytes: 10 * 1024 * 1024` allows 10 MiB. Invalid values fail before the request. Timeouts, size limits, and non-success HTTP statuses are logged as failures and apply task retries.
+- Run tasks on a cron schedule or trigger them from application code.
+- Execute HTTP requests, trusted JavaScript and application hooks, with retry and cancellation.
+- Optionally persist tasks and logs; use shared cache for scheduling locks across nodes.
 
-`init()` succeeds only after loading all tasks. Empty or duplicate IDs (including persisted duplicates), invalid cron, database read failures, and persisted-task parse failures return failure and clear initialization state. Correct configuration or data before retrying. Do not redeclare existing database tasks in `tasks`.
+## Getting started
 
-## Dependencies
+### Dependencies
 
 - `@h-ai/reldb`: task and execution log persistence; initialize first when `enableDb: true`.
 - `@h-ai/cache`: optional distributed locks; automatically participates in scheduled lock acquisition when initialized.
 
-## Quick start
+### Quick start
 
 ```ts
 import { cache } from '@h-ai/cache'
@@ -89,7 +83,7 @@ scheduler.stop()
 await scheduler.close()
 ```
 
-## Unified task model
+### Unified task model
 
 ```ts
 interface TaskDefinition {
@@ -132,7 +126,7 @@ Notes:
 
 > ⚠️ **Security warning**: `kind: 'js'` is only for trusted server-side code. Node.js `vm` provides convenient execution and **is not a security sandbox**. Never accept arbitrary JS strings from users, tenants, or admin inputs. Prefer `kind: 'api'` or `hooks.onTaskExecute` for configurable tasks.
 
-## Task lifecycle hooks
+### Task lifecycle hooks
 
 Provide hooks at initialization or set them at runtime with `setHooks()`:
 
@@ -156,7 +150,7 @@ await scheduler.init({
 })
 ```
 
-## Execution logs
+### Execution logs
 
 Filter logs by trigger source:
 
@@ -176,7 +170,7 @@ Execution logs support automatic cleanup policies configured at initialization:
 - `maxLogs`: retain at most N logs.
 - `retentionDays`: retain at most the last N days.
 
-## API overview
+### API overview
 
 - `init(config?)`
 - `register(task)`
@@ -190,7 +184,7 @@ Execution logs support automatic cleanup policies configured at initialization:
 - `tasks` / `hooks` / `config` / `isInitialized` / `isRunning`
 - `close()`
 
-## Error handling
+### Error handling
 
 All public APIs except `close()` return `HaiResult<T>`.
 
@@ -214,7 +208,29 @@ Common error codes:
 | `HaiSchedulerError.JS_COMPILE_FAILED`     | `hai:scheduler:030` | JS compilation failed   |
 | `HaiSchedulerError.HOOK_EXECUTION_FAILED` | `hai:scheduler:031` | Hook execution failed   |
 
-## Tests
+### Runtime behavior and limits
+
+With the database enabled, nodes refresh persisted definitions every `tickInterval` (default 1000 ms); `tasks` is the latest successful snapshot. Registration, updates, deletion, manual triggers, and each attempt after acquiring a scheduling lock reread definitions. Deleted, disabled, or rescheduled old tasks stop executing; read failures abort the attempt. Already-started business side effects are not rolled back by remote changes. `init({ tasks })` remains node-local; use persisted `register()` for dynamic tasks across nodes. Cross-node deduplication requires shared Redis; memory cache is single-process only.
+
+Call `await scheduler.refreshTasks()` to refresh without execution; concurrent refreshes of the same snapshot share one read. Registration, updates, and deletion change memory only after successful persistence. Invalid full updates leave cron unchanged. Pass `retry: null` or `handler: null` to clear retries or built-in handlers.
+
+Hook business errors are recorded as `failed` and apply `retry`; missing handlers, cancellation, or host-thrown `SchedulerTaskSkippedError` are `interrupted`. `event.context.occurrenceId` identifies an occurrence: the same scheduled minute shares it across nodes, each manual trigger is independent, and retries reuse the original. Hosts can persist idempotency receipts with this ID; long tasks spanning periods still need a host-maintained lease for mutual exclusion. `deleteAfterRun` deletes only after success. Definitions are checked before retry and successful cleanup; one database DELETE atomically matches the executed definition, preserving concurrent updates.
+
+Multi-node regression tests build current source and start two real Node processes sharing SQLite and Testcontainers Redis, validating definition convergence and same-minute lock contention. A working Docker/Podman service is required before `pnpm --filter @h-ai/scheduler test`.
+
+`await scheduler.close()` stops task intake, cancels HTTP, JS workers, and retry waits, then awaits execution chain exit before clearing state. Reinitialization waits for closure. All lifecycle events expose `signal`; hooks must observe cancellation and stop external side effects. The framework cannot terminate business code on the same thread; do not block the event loop in hooks. Cancelled old executions no longer retry, delete tasks, or call new-instance hooks. Keep the database and cache available until scheduler closure completes, then close dependencies.
+
+Each JS string runs in its own worker; `timeout` defaults to 30000 ms including startup. On timeout, terminate the thread and await exit before logging failure or retrying. Synchronous infinite loops cannot block the main event loop. Context and results must support structured cloning. A worker's `vm` is still not a security sandbox; code must come from trusted server-side sources.
+
+API task `timeout` (default 30000 ms) covers the request and full response body read. `ApiTaskConfig.maxResponseBytes` limits received body bytes (positive safe integer; default 1048576, or 1 MiB). `maxResponseBytes: 10 * 1024 * 1024` allows 10 MiB. Invalid values fail before the request. Timeouts, size limits, and non-success HTTP statuses are logged as failures and apply task retries.
+
+`init()` succeeds only after loading all tasks. Empty or duplicate IDs (including persisted duplicates), invalid cron, database read failures, and persisted-task parse failures return failure and clear initialization state. Correct configuration or data before retrying. Do not redeclare existing database tasks in `tasks`.
+
+### Optional integrations
+
+Cron is matched by minute, and distributed lock keys use that same minute. Startup or ticks delayed beyond second zero still check the current minute; a running scheduler does not reschedule it on every tick.
+
+## Development and testing
 
 ```bash
 pnpm --filter @h-ai/scheduler test
@@ -223,5 +239,3 @@ pnpm --filter @h-ai/scheduler test
 ## License
 
 Apache-2.0
-
-Cron is matched by minute, and distributed lock keys use that same minute. Startup or ticks delayed beyond second zero still check the current minute; a running scheduler does not reschedule it on every tick.

package/README.ja.md

@@ -4,30 +4,24 @@
 
 [フレームワークのホーム](../../README.ja.md) · 関連モジュール：[@h-ai/cache](../cache/README.ja.md) · [@h-ai/core](../core/README.ja.md) · [@h-ai/reldb](../reldb/README.ja.md)
 
-共通のタスクモデル、cron スケジュール、JS 関数文字列・HTTP API の実行、永続化、実行ログ検索、全体のライフサイクル Hook を提供するスケジューラーモジュールです。
-
-DB を有効にすると、各ノードは `tickInterval`（既定 1000 ms）ごとに保存された定義を更新し、`tasks` は直近の成功したスナップショットになります。登録・更新・削除・手動実行、およびロック取得後の各試行で定義を再読します。削除・無効化・再スケジュールされた古いタスクは実行せず、読み取り失敗時は試行を中断します。開始済みの副作用は遠隔の変更で自動ロールバックしません。`init({ tasks })` はノード固有設定です。ノード間の動的タスクには永続化する `register()`、重複防止には共有 Redis を使います。メモリーキャッシュは単一プロセスのみです。
-
-`await scheduler.refreshTasks()` でタスクを実行せず定義を更新できます。同じスナップショットの並行更新は 1 回の読み取りを共有します。登録・更新・削除は永続化成功後にメモリーへ反映し、全体更新の検証失敗では cron を変更しません。再試行や組み込み handler の解除には `retry: null`、`handler: null` を渡します。
-
-Hook が投げる業務エラーは `failed` として記録し `retry` を適用します。handler の不足、キャンセル、ホストが投げる `SchedulerTaskSkippedError` は `interrupted` です。`event.context.occurrenceId` は 1 回の発生を識別し、同じスケジュール分ではノード間で共通、手動実行では毎回独立、再試行では元の ID を共有します。ホストはこの ID で冪等性の受領記録を保存できます。周期をまたぐ長時間タスクの排他制御にはホスト側の継続リースが必要です。`deleteAfterRun` は成功時のみ削除します。再試行前と成功後の削除前に現在の定義を確認し、DB の削除は 1 つの DELETE 内で実行定義をアトミックに照合して並行更新を保持します。
-
-複数ノードの回帰テストは現在のソースをビルドし、SQLite と Testcontainers Redis を共有する実際の Node プロセスを 2 つ起動して、定義の収束と同じ分のロック競合を検証します。`pnpm --filter @h-ai/scheduler test` の前に、利用可能な Docker/Podman サービスが必要です。
+## 概要
 
-`await scheduler.close()` は受付を止め、HTTP、JS Worker、再試行待機をキャンセルし、実行チェーンの終了後に状態を解放します。再初期化は終了完了を待ちます。すべてのイベントが `signal` を提供し、Hook はキャンセルを監視して外部への副作用を停止する必要があります。同じスレッドの業務コードは強制終了できないため、Hook でイベントループをブロックしないでください。キャンセルされた旧実行は再試行・自動削除・新インスタンスの Hook 呼び出しを行いません。scheduler の終了完了まで DB とキャッシュを維持し、その後に依存モジュールを終了します。
+共通のタスクモデル、cron スケジュール、JS 関数文字列・HTTP API の実行、永続化、実行ログ検索、全体のライフサイクル Hook を提供するスケジューラーモジュールです。
 
-JS 文字列は呼び出しごとの独立 Worker で実行します。`timeout` は起動を含めて既定 30000 ms です。時間超過時はスレッドを終了し、終了を待ってから失敗記録・再試行を行います。同期の無限ループでもメインイベントループをブロックしません。コンテキストと戻り値は構造化クローンに対応する必要があります。Worker 内の `vm` も安全なサンドボックスではなく、信頼できるサーバー側コードのみを使用します。
+## 主な機能
 
-API タスクの `timeout`（既定 30000 ms）はリクエストと応答本文全体の読み取りを含みます。`ApiTaskConfig.maxResponseBytes` は受信バイト上限で、正の安全な整数、既定は 1048576（1 MiB）です。`maxResponseBytes: 10 * 1024 * 1024` なら最大 10 MiB を許可し、不正値は送信前に失敗します。タイムアウト・上限超過・非成功 HTTP 応答は失敗として記録し、タスクの再試行方針を適用します。
+- cron による定期実行とアプリケーションからの手動実行。
+- HTTP、信頼できる JavaScript、アプリ Hook に対応し、再試行とキャンセルを提供。
+- タスク・ログの永続化と、共有キャッシュによるノード間の実行ロック。
 
-`init()` は全タスクの読み込み完了後にのみ成功します。空 ID、重複 ID（保存済みタスクとの重複を含む）、不正な cron、DB 読み取り失敗、保存タスクの解析失敗では失敗を返し、初期化状態を消去します。設定・データを修正してから再初期化し、既存の DB タスクを `tasks` に重複宣言しないでください。
+## 使い始める
 
-## 依存関係
+### 依存関係
 
 - `@h-ai/reldb`：タスク定義と実行ログの永続化。`enableDb: true` の場合は先に初期化。
 - `@h-ai/cache`：任意の分散ロック。初期化済みの場合、定時実行時のロック取得に自動参加。
 
-## クイックスタート
+### クイックスタート
 
 ```ts
 import { cache } from '@h-ai/cache'
@@ -89,7 +83,7 @@ scheduler.stop()
 await scheduler.close()
 ```
 
-## 共通タスクモデル
+### 共通タスクモデル
 
 ```ts
 interface TaskDefinition {
@@ -132,7 +126,7 @@ interface JsTaskConfig {
 
 > ⚠️ **セキュリティ注意**：`kind: 'js'` は信頼できるサーバー側コード専用です。Node.js の `vm` による実行は**安全なサンドボックスではありません**。ユーザー、テナント、管理画面から任意の JS 文字列を直接受け付けないでください。設定可能なタスクには `kind: 'api'` または `hooks.onTaskExecute` を優先してください。
 
-## タスクのライフサイクル Hook
+### タスクのライフサイクル Hook
 
 初期化時に渡すか、実行時に `setHooks()` で設定します：
 
@@ -156,7 +150,7 @@ await scheduler.init({
 })
 ```
 
-## 実行ログ
+### 実行ログ
 
 実行元でログを絞り込めます：
 
@@ -176,7 +170,7 @@ const logs = await scheduler.getLogs({
 - `maxLogs`：最大 N 件を保持。
 - `retentionDays`：直近 N 日分のみを保持。
 
-## API 一覧
+### API 一覧
 
 - `init(config?)`
 - `register(task)`
@@ -190,7 +184,7 @@ const logs = await scheduler.getLogs({
 - `tasks` / `hooks` / `config` / `isInitialized` / `isRunning`
 - `close()`
 
-## エラー処理
+### エラー処理
 
 `close()` を除くすべての公開 API は `HaiResult<T>` を返します。
 
@@ -214,14 +208,34 @@ const logs = await scheduler.getLogs({
 | `HaiSchedulerError.JS_COMPILE_FAILED`     | `hai:scheduler:030` | JS コンパイルに失敗  |
 | `HaiSchedulerError.HOOK_EXECUTION_FAILED` | `hai:scheduler:031` | Hook 実行に失敗      |
 
-## テスト
+### 実行時の動作と制約
+
+DB を有効にすると、各ノードは `tickInterval`（既定 1000 ms）ごとに保存された定義を更新し、`tasks` は直近の成功したスナップショットになります。登録・更新・削除・手動実行、およびロック取得後の各試行で定義を再読します。削除・無効化・再スケジュールされた古いタスクは実行せず、読み取り失敗時は試行を中断します。開始済みの副作用は遠隔の変更で自動ロールバックしません。`init({ tasks })` はノード固有設定です。ノード間の動的タスクには永続化する `register()`、重複防止には共有 Redis を使います。メモリーキャッシュは単一プロセスのみです。
+
+`await scheduler.refreshTasks()` でタスクを実行せず定義を更新できます。同じスナップショットの並行更新は 1 回の読み取りを共有します。登録・更新・削除は永続化成功後にメモリーへ反映し、全体更新の検証失敗では cron を変更しません。再試行や組み込み handler の解除には `retry: null`、`handler: null` を渡します。
+
+Hook が投げる業務エラーは `failed` として記録し `retry` を適用します。handler の不足、キャンセル、ホストが投げる `SchedulerTaskSkippedError` は `interrupted` です。`event.context.occurrenceId` は 1 回の発生を識別し、同じスケジュール分ではノード間で共通、手動実行では毎回独立、再試行では元の ID を共有します。ホストはこの ID で冪等性の受領記録を保存できます。周期をまたぐ長時間タスクの排他制御にはホスト側の継続リースが必要です。`deleteAfterRun` は成功時のみ削除します。再試行前と成功後の削除前に現在の定義を確認し、DB の削除は 1 つの DELETE 内で実行定義をアトミックに照合して並行更新を保持します。
+
+複数ノードの回帰テストは現在のソースをビルドし、SQLite と Testcontainers Redis を共有する実際の Node プロセスを 2 つ起動して、定義の収束と同じ分のロック競合を検証します。`pnpm --filter @h-ai/scheduler test` の前に、利用可能な Docker/Podman サービスが必要です。
+
+`await scheduler.close()` は受付を止め、HTTP、JS Worker、再試行待機をキャンセルし、実行チェーンの終了後に状態を解放します。再初期化は終了完了を待ちます。すべてのイベントが `signal` を提供し、Hook はキャンセルを監視して外部への副作用を停止する必要があります。同じスレッドの業務コードは強制終了できないため、Hook でイベントループをブロックしないでください。キャンセルされた旧実行は再試行・自動削除・新インスタンスの Hook 呼び出しを行いません。scheduler の終了完了まで DB とキャッシュを維持し、その後に依存モジュールを終了します。
+
+JS 文字列は呼び出しごとの独立 Worker で実行します。`timeout` は起動を含めて既定 30000 ms です。時間超過時はスレッドを終了し、終了を待ってから失敗記録・再試行を行います。同期の無限ループでもメインイベントループをブロックしません。コンテキストと戻り値は構造化クローンに対応する必要があります。Worker 内の `vm` も安全なサンドボックスではなく、信頼できるサーバー側コードのみを使用します。
+
+API タスクの `timeout`（既定 30000 ms）はリクエストと応答本文全体の読み取りを含みます。`ApiTaskConfig.maxResponseBytes` は受信バイト上限で、正の安全な整数、既定は 1048576（1 MiB）です。`maxResponseBytes: 10 * 1024 * 1024` なら最大 10 MiB を許可し、不正値は送信前に失敗します。タイムアウト・上限超過・非成功 HTTP 応答は失敗として記録し、タスクの再試行方針を適用します。
+
+`init()` は全タスクの読み込み完了後にのみ成功します。空 ID、重複 ID（保存済みタスクとの重複を含む）、不正な cron、DB 読み取り失敗、保存タスクの解析失敗では失敗を返し、初期化状態を消去します。設定・データを修正してから再初期化し、既存の DB タスクを `tasks` に重複宣言しないでください。
+
+### 任意の連携
+
+スケジュールループは分単位で cron を照合し、同じ分から分散ロックのキーを生成します。起動や tick が 0 秒を過ぎても現在の分を確認し、同じ実行中に毎 tick 重複してスケジュールしません。
+
+## 開発とテスト
 
 ```bash
 pnpm --filter @h-ai/scheduler test
 ```
 
-## License
+## ライセンス
 
 Apache-2.0
-
-スケジュールループは分単位で cron を照合し、同じ分から分散ロックのキーを生成します。起動や tick が 0 秒を過ぎても現在の分を確認し、同じ実行中に毎 tick 重複してスケジュールしません。

package/README.md

@@ -4,30 +4,24 @@
 
 [框架首页](../../README.md) · 相关模块：[@h-ai/cache](../cache/README.md) · [@h-ai/core](../core/README.md) · [@h-ai/reldb](../reldb/README.md)
 
-定时任务调度模块，支持统一任务模型、cron 调度、JS 函数字符串 / HTTP API 执行、任务持久化、执行日志查询，以及全局任务生命周期回调。
-
-启用数据库时，运行中的节点每个 `tickInterval`（默认 1000 毫秒）刷新持久化定义；`tasks` 是最近一次成功刷新的快照。注册、修改、删除、手工触发和获得调度锁后的每次尝试均重新读取定义，删除/禁用/已改调度时间的旧任务不会继续执行，读取失败则中断本次尝试。已经开始的业务副作用不因远端定义变化自动回滚。`init({ tasks })` 仍是节点本地配置，跨节点动态任务请用持久化的 `register()` 管理；跨节点防重需要共享 Redis，内存缓存仅限单进程。
-
-可调用 `await scheduler.refreshTasks()` 主动刷新而不执行任务；同一快照的并发刷新共用一次读取。注册、更新与删除成功持久化后才更新内存投影，整份更新验证失败不改变 cron。清除重试或内置处理器时分别传 `retry: null`、`handler: null`。
-
-Hook 抛出的业务失败记录为 `failed` 并应用 `retry`；缺少处理器、取消或宿主抛出的 `SchedulerTaskSkippedError` 记录为 `interrupted`。`event.context.occurrenceId` 标识一次发生：同一调度分钟跨节点一致，手工触发每次独立，重试共享原标识。宿主可据此持久化业务幂等回执；跨周期的长任务互斥仍需宿主持续租约。`deleteAfterRun` 仅在成功后删除，失败任务保留；重试前与成功清理前核对当前定义，数据库清理在同一条 DELETE 内原子匹配执行定义，保留期间提交的并发更新。
-
-多节点回归测试会构建当前源码、启动两个真实 Node 进程共享 SQLite 和 Testcontainers Redis，验证定义收敛及同分钟锁竞争；运行 `pnpm --filter @h-ai/scheduler test` 前须有可用的 Docker/Podman 服务。
+## 简介
 
-`await scheduler.close()` 先停止接收任务，取消 HTTP、JS Worker 与重试等待，再等待执行链退出后清理状态。重新初始化等待关闭完成。所有生命周期事件提供 `signal`；Hook 必须监听取消并停止自己的外部副作用（框架无法强制终止同一线程中的业务代码），不要在 Hook 中阻塞事件循环。取消后的旧执行不再重试、不自动删除任务，也不会调用新实例的 Hook。关闭期间保持数据库和缓存可用，待 scheduler 关闭后再关闭依赖。
+定时任务调度模块，支持统一任务模型、cron 调度、JS 函数字符串 / HTTP API 执行、任务持久化、执行日志查询，以及全局任务生命周期回调。
 
-JS 字符串在每次调用的独立 Worker 中执行，`timeout` 默认 30000 毫秒（含启动）。到期后终止并等待线程退出，再记录失败或重试；同步死循环也不会阻塞主事件循环。上下文及返回值必须支持结构化克隆。Worker 中的 `vm` 仍不是安全沙箱，代码必须来自受信任的服务端来源。
+## 核心功能清单
 
-API 任务的 `timeout`（默认 30000 毫秒）覆盖请求和完整响应体读取。`ApiTaskConfig.maxResponseBytes` 指定响应体实际接收字节上限（正安全整数，默认 1048576 即 1 MiB）；例如 `maxResponseBytes: 10 * 1024 * 1024` 允许最大 10 MiB，非法值在请求前失败；超时、超限或非成功 HTTP 状态均记录失败并应用任务重试策略。
+- 按 cron 定时执行，也可从业务代码手动触发。
+- 支持 HTTP、受信任的 JavaScript 和应用 Hook，提供重试与取消。
+- 可持久化任务和执行日志；共享缓存用于多节点抢锁。
 
-`init()` 必须完整加载全部任务才返回成功。配置中的空 ID、重复 ID（含与持久化任务重复）、无效 cron，以及数据库读取或持久化任务解析失败，均返回失败并清空初始化状态；修正配置或数据后重新初始化。不要同时在 `tasks` 中重复声明已有的数据库任务。
+## 使用入门
 
-## 依赖
+### 依赖
 
 - `@h-ai/reldb` — 任务定义与执行日志持久化，`enableDb: true` 时需先初始化
 - `@h-ai/cache` — 分布式锁，可选；初始化后自动参与定时触发抢锁
 
-## 快速开始
+### 快速开始
 
 ```ts
 import { cache } from '@h-ai/cache'
@@ -89,7 +83,7 @@ scheduler.stop()
 await scheduler.close()
 ```
 
-## 统一任务模型
+### 统一任务模型
 
 ```ts
 interface TaskDefinition {
@@ -132,7 +126,7 @@ interface JsTaskConfig {
 
 > ⚠️ **安全警示**：`kind: 'js'` 仅适用于受信任的服务端代码。当前实现基于 Node.js `vm` 做便捷执行，**不是安全沙箱**；禁止直接接收用户、租户或后台任意输入的 JS 字符串。可配置任务优先使用 `kind: 'api'` 或 `hooks.onTaskExecute`。
 
-## 任务生命周期回调
+### 任务生命周期回调
 
 初始化时传入或运行时通过 `setHooks()` 设置：
 
@@ -156,7 +150,7 @@ await scheduler.init({
 })
 ```
 
-## 执行日志
+### 执行日志
 
 查询日志时可按触发来源过滤：
 
@@ -176,7 +170,7 @@ const logs = await scheduler.getLogs({
 - `maxLogs`：最多保留 N 条日志
 - `retentionDays`：最多保留最近 N 天日志
 
-## API 概览
+### API 概览
 
 - `init(config?)`
 - `register(task)`
@@ -190,7 +184,7 @@ const logs = await scheduler.getLogs({
 - `tasks` / `hooks` / `config` / `isInitialized` / `isRunning`
 - `close()`
 
-## 错误处理
+### 错误处理
 
 所有公共 API（除 `close()`）返回 `HaiResult<T>`。
 
@@ -214,14 +208,34 @@ const logs = await scheduler.getLogs({
 | `HaiSchedulerError.JS_COMPILE_FAILED`     | `hai:scheduler:030` | JS 编译失败     |
 | `HaiSchedulerError.HOOK_EXECUTION_FAILED` | `hai:scheduler:031` | Hook 执行失败   |
 
-## 测试
+### 运行行为与边界
+
+启用数据库时，运行中的节点每个 `tickInterval`（默认 1000 毫秒）刷新持久化定义；`tasks` 是最近一次成功刷新的快照。注册、修改、删除、手工触发和获得调度锁后的每次尝试均重新读取定义，删除/禁用/已改调度时间的旧任务不会继续执行，读取失败则中断本次尝试。已经开始的业务副作用不因远端定义变化自动回滚。`init({ tasks })` 仍是节点本地配置，跨节点动态任务请用持久化的 `register()` 管理；跨节点防重需要共享 Redis，内存缓存仅限单进程。
+
+可调用 `await scheduler.refreshTasks()` 主动刷新而不执行任务；同一快照的并发刷新共用一次读取。注册、更新与删除成功持久化后才更新内存投影，整份更新验证失败不改变 cron。清除重试或内置处理器时分别传 `retry: null`、`handler: null`。
+
+Hook 抛出的业务失败记录为 `failed` 并应用 `retry`；缺少处理器、取消或宿主抛出的 `SchedulerTaskSkippedError` 记录为 `interrupted`。`event.context.occurrenceId` 标识一次发生：同一调度分钟跨节点一致，手工触发每次独立，重试共享原标识。宿主可据此持久化业务幂等回执；跨周期的长任务互斥仍需宿主持续租约。`deleteAfterRun` 仅在成功后删除，失败任务保留；重试前与成功清理前核对当前定义，数据库清理在同一条 DELETE 内原子匹配执行定义，保留期间提交的并发更新。
+
+多节点回归测试会构建当前源码、启动两个真实 Node 进程共享 SQLite 和 Testcontainers Redis，验证定义收敛及同分钟锁竞争；运行 `pnpm --filter @h-ai/scheduler test` 前须有可用的 Docker/Podman 服务。
+
+`await scheduler.close()` 先停止接收任务，取消 HTTP、JS Worker 与重试等待，再等待执行链退出后清理状态。重新初始化等待关闭完成。所有生命周期事件提供 `signal`；Hook 必须监听取消并停止自己的外部副作用（框架无法强制终止同一线程中的业务代码），不要在 Hook 中阻塞事件循环。取消后的旧执行不再重试、不自动删除任务，也不会调用新实例的 Hook。关闭期间保持数据库和缓存可用，待 scheduler 关闭后再关闭依赖。
+
+JS 字符串在每次调用的独立 Worker 中执行，`timeout` 默认 30000 毫秒（含启动）。到期后终止并等待线程退出，再记录失败或重试；同步死循环也不会阻塞主事件循环。上下文及返回值必须支持结构化克隆。Worker 中的 `vm` 仍不是安全沙箱，代码必须来自受信任的服务端来源。
+
+API 任务的 `timeout`（默认 30000 毫秒）覆盖请求和完整响应体读取。`ApiTaskConfig.maxResponseBytes` 指定响应体实际接收字节上限（正安全整数，默认 1048576 即 1 MiB）；例如 `maxResponseBytes: 10 * 1024 * 1024` 允许最大 10 MiB，非法值在请求前失败；超时、超限或非成功 HTTP 状态均记录失败并应用任务重试策略。
+
+`init()` 必须完整加载全部任务才返回成功。配置中的空 ID、重复 ID（含与持久化任务重复）、无效 cron，以及数据库读取或持久化任务解析失败，均返回失败并清空初始化状态；修正配置或数据后重新初始化。不要同时在 `tasks` 中重复声明已有的数据库任务。
+
+### 可选集成
+
+调度循环按分钟时间点匹配 cron，并用同一分钟生成分布式锁键；启动或 tick 延迟至非零秒仍检查当前分钟，同一轮运行不会每个 tick 重复调度。
+
+## 开发测试
 
 ```bash
 pnpm --filter @h-ai/scheduler test
 ```
 
-## License
+## 许可证
 
 Apache-2.0
-
-调度循环按分钟时间点匹配 cron，并用同一分钟生成分布式锁键；启动或 tick 延迟至非零秒仍检查当前分钟，同一轮运行不会每个 tick 重复调度。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/scheduler",
   "type": "module",
-  "version": "0.1.0-alpha.65",
+  "version": "0.1.0-alpha.67",
   "description": "Hai Framework task scheduling module with cron, function, and API jobs.",
   "license": "Apache-2.0",
   "exports": {
@@ -24,9 +24,9 @@
     "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
   },
   "dependencies": {
-    "@h-ai/cache": "0.1.0-alpha.65",
-    "@h-ai/core": "0.1.0-alpha.65",
-    "@h-ai/reldb": "0.1.0-alpha.65",
+    "@h-ai/cache": "0.1.0-alpha.67",
+    "@h-ai/core": "0.1.0-alpha.67",
+    "@h-ai/reldb": "0.1.0-alpha.67",
     "croner": "^10.0.1",
     "zod": "^4.6.5"
   },