@h-ai/audit 1.0.0-beta.2 → 1.0.0-beta.20

package/README.en.md

@@ -4,33 +4,14 @@
 
 [Framework home](../../README.en.md) · Related modules: [@h-ai/core](../core/README.en.md) · [@h-ai/reldb](../reldb/README.en.md)
 
-## Introduction
-
 A unified audit logging module. The `audit` object records, queries, cleans up, and aggregates audit logs, with persistence provided by `@h-ai/reldb`.
 
-SQLite, PostgreSQL and MySQL share the same read contract: `createdAt` is a `Date`, `details` is a JSON string or `null`, and absent nullable fields return `null`. Date filters use the same driver conversion as writes. Counts are safe integers; out-of-range counts return `STATS_FAILED`.
-
-## Core features
-
-- Record user actions and security events; filter by user, date and action.
-- Query paginated logs and statistics, and clean up by retention period.
-- Persist through the relational database and redact credential fields before writing.
-
-## Getting started
+## Quick Start
 
 ### Dependencies
 
 - `@h-ai/reldb`: database for audit log persistence; **initialize it before audit.init()**.
 
-### Use cases
-
-- User activity auditing (login, logout, registration, password reset, etc.)
-- CRUD auditing (resource creation, reads, updates, and deletion)
-- Security event tracking and compliance auditing
-- Operational statistics (operation frequency, active users, etc.)
-
-### Quick start
-
 ```ts
 import { audit } from '@h-ai/audit'
 import { reldb } from '@h-ai/reldb'
@@ -54,7 +35,13 @@ await audit.log({
 
 // 4. 使用便捷方法
 await audit.helper.login('user_1', '127.0.0.1')
-await audit.helper.crud({ userId: 'user_1', action: 'create', resource: 'users', resourceId: 'user_2', details: { name: '张三' } })
+await audit.helper.crud({
+  userId: 'user_1',
+  action: 'create',
+  resource: 'users',
+  resourceId: 'user_2',
+  details: { name: '张三' }
+})
 
 // 5. 查询日志
 const logs = await audit.list({ pageSize: 20, action: 'login' })
@@ -72,6 +59,76 @@ if (!closeResult.success) {
 }
 ```
 
+## Features
+
+SQLite, PostgreSQL and MySQL share the same read contract: `createdAt` is a `Date`, `details` is a JSON string or `null`, and absent nullable fields return `null`. Date filters use the same driver conversion as writes. Counts are safe integers; out-of-range counts return `STATS_FAILED`.
+
+### Operations and results
+
+Use the complete initialization flow in this section first. The host validates and authorizes example business values; check success before reading data from asynchronous domain results. Here void means completion without data, null means absent; synchronous factories/tools return the listed type directly.
+
+#### audit
+
+Structured events: log takes event/optional tx and yields the record, capture yields void under read/write policy, withContext takes trusted correlation plus callback and returns its value.
+
+| Entry               | Input parameters   | Successful result | Call example                                                |
+| ------------------- | ------------------ | ----------------- | ----------------------------------------------------------- |
+| `audit.log`         | input, tx          | `AuditLog`        | `await audit.log(event)`                                    |
+| `audit.capture`     | input, options     | `void`            | `await audit.capture(event)`                                |
+| `audit.withContext` | context, operation | `T`               | `audit.withContext(trustedAuditContext, () => saveOrder())` |
+
+#### audit
+
+Query/retention: filters/page yield a page with users, user ID/limit recent events, days/filters statistics, cleanup retention days a deleted count.
+
+| Entry                 | Input parameters | Successful result                   | Call example                                  |
+| --------------------- | ---------------- | ----------------------------------- | --------------------------------------------- |
+| `audit.list`          | options          | `PaginatedResult<AuditLogWithUser>` | `await audit.list({ page: 1, pageSize: 20 })` |
+| `audit.getUserRecent` | userId, limit    | `AuditLog[]`                        | `await audit.getUserRecent(userId, 20)`       |
+| `audit.getStats`      | days, filters    | `AuditStatItem[]`                   | `await audit.getStats(7)`                     |
+| `audit.cleanup`       | olderThanDays    | `number`                            | `await audit.cleanup(90)`                     |
+
+#### audit.helper
+
+Common events accept user ID (email for reset request), optional IP/UA or a CRUD event and yield void HaiResult; privacy filtering still applies.
+
+| Entry                                | Input parameters | Successful result | Call example                                       |
+| ------------------------------------ | ---------------- | ----------------- | -------------------------------------------------- |
+| `audit.helper.login`                 | userId, ip, ua   | `void`            | `await audit.helper.login(userId)`                 |
+| `audit.helper.logout`                | userId, ip, ua   | `void`            | `await audit.helper.logout(userId)`                |
+| `audit.helper.register`              | userId, ip, ua   | `void`            | `await audit.helper.register(userId)`              |
+| `audit.helper.passwordResetRequest`  | email, ip, ua    | `void`            | `await audit.helper.passwordResetRequest(email)`   |
+| `audit.helper.passwordResetComplete` | userId, ip, ua   | `void`            | `await audit.helper.passwordResetComplete(userId)` |
+| `audit.helper.crud`                  | input            | `void`            | `await audit.helper.crud(crudEvent)`               |
+
+#### audit.backup
+
+Private archive: run takes filters/deadline/cancellation, verify an object key; both yield verified archive information without publishing objects.
+
+| Entry                 | Input parameters | Successful result | Call example                            |
+| --------------------- | ---------------- | ----------------- | --------------------------------------- |
+| `audit.backup.run`    | options          | `AuditBackupInfo` | `await audit.backup.run()`              |
+| `audit.backup.verify` | key, options     | `AuditBackupInfo` | `await audit.backup.verify(archiveKey)` |
+
+#### audit
+
+Scheduled anomaly check takes optional signal and yields matched rules/notification results; orchestrate via scheduler rather than assuming a worker started.
+
+| Entry               | Input parameters | Successful result  | Call example                |
+| ------------------- | ---------------- | ------------------ | --------------------------- |
+| `audit.checkAlerts` | options          | `AuditAlertReport` | `await audit.checkAlerts()` |
+
+- Record user actions and security events; filter by user, date and action.
+- Query paginated logs and statistics, and clean up by retention period.
+- Persist through the relational database and redact credential fields before writing.
+
+### Use cases
+
+- User activity auditing (login, logout, registration, password reset, etc.)
+- CRUD auditing (resource creation, reads, updates, and deletion)
+- Security event tracking and compliance auditing
+- Operational statistics (operation frequency, active users, etc.)
+
 ### Initialization options
 
 ```ts
@@ -110,31 +167,7 @@ Record common events through `audit.helper`, with the public `AuditHelper` type.
 - `audit.cleanup(days)`: `days`, if provided, must be a nonnegative integer.
 - `audit.getStats(days)`: `days`, if provided, must be a nonnegative integer.
 
-### Error codes
-
-Business data operations return `HaiResult<T>`. Common error codes:
-
-| Error code                       | code            | Description                          |
-| -------------------------------- | --------------- | ------------------------------------ |
-| `HaiAuditError.LOG_FAILED`       | `hai:audit:001` | Recording failed                     |
-| `HaiAuditError.QUERY_FAILED`     | `hai:audit:002` | Query failed                         |
-| `HaiAuditError.CLEANUP_FAILED`   | `hai:audit:003` | Cleanup failed                       |
-| `HaiAuditError.STATS_FAILED`     | `hai:audit:004` | Aggregation failed                   |
-| `HaiAuditError.INIT_IN_PROGRESS` | `hai:audit:005` | Initialization in progress           |
-| `HaiAuditError.NOT_INITIALIZED`  | `hai:audit:010` | Module not initialized               |
-| `HaiAuditError.CONFIG_ERROR`     | `hai:audit:012` | Invalid configuration                |
-| `HaiAuditError.BACKUP_DISABLED`  | `hai:audit:020` | Backup disabled                      |
-| `HaiAuditError.BACKUP_FAILED`    | `hai:audit:021` | Backup or verification failed        |
-| `HaiAuditError.BACKUP_INVALID`   | `hai:audit:022` | Invalid backup input                 |
-| `HaiAuditError.BACKUP_CONFLICT`  | `hai:audit:023` | Backup ID/export conditions conflict |
-| `HaiAuditError.ALERTS_DISABLED`  | `hai:audit:024` | Alerts disabled                      |
-| `HaiAuditError.ALERTS_FAILED`    | `hai:audit:025` | Alert check or notification failed   |
-
-> Note: `audit.close()` also returns `HaiResult<void>`. Email details in `audit.helper.passwordResetRequest()` are hidden by the default business privacy settings.
-
-`audit.init()` awaits automatic table creation and repository readiness before success. DDL failures leave `isInitialized=false`; correct the database and retry. Custom joins, statistics and cleanup share the same barrier. Closing during initialization invalidates late publication. Check the init HaiResult before recording or querying. Audit does not own the shared RelDB connection; close audit before the database.
-
-## Event context, privacy and retention
+### Event context, privacy and retention
 
 Audit createdAt, alert windows and archive cutoffs share the database clock rather than individual node clocks. Scheduled backup/alert tasks declare idempotency based on their persistent deduplication guarantees; failures do not incorrectly block subsequent schedules as non-idempotent unknown tasks.
 
@@ -152,7 +185,7 @@ Stop old writers and back up before upgrading. `migrateAudit({ dryRun: true })`
 
 Redaction matches whole fields, including objects, arrays and sensitive values produced by custom JSON projections. capture returns not-initialized failure before initialization or after close; only an initialized module with capture disabled skips automatic events.
 
-## Private backups and scheduled archives
+### Private backups and scheduled archives
 
 `backup.enabled` is off by default. Inject initialized `StorageFunctions` with `audit.init({ storage, backup: { enabled: true } })`; initialize RelDB first. `backup.batchSize` controls scan batches (default200), while `maxRecordBytes` bounds each UTF-8 record (default1 MiB). Oversized records fail the archive without truncating stored evidence.
 
@@ -165,7 +198,10 @@ Version1 contains a header, `{type:'entry',record}` lines and a footer. Entries
 ```ts
 const plan = audit.schedulerPlan
 if (plan) {
-  const initialized = await scheduler.init({ ...schedulerSettings, ...plan })
+  const initialized = await scheduler.init({
+    ...schedulerSettings,
+    ...plan
+  })
   if (!initialized.success)
     throw new Error(initialized.error.message)
   const started = scheduler.start()
@@ -176,7 +212,7 @@ if (plan) {
 
 The host imports audit/scheduler and supplies validated schedulerSettings, with Audit/Storage/RelDB initialized. Use private archive storage: enabling backups rejects an S3 publicUrl setting, and deployment must restrict bucket/CDN access. Public asset endpoints should expose designated resources only. The example/fullstack runtimes expose canonical avatar paths; archives require an authorized audit download endpoint. Disabling backups preserves the private boundary of existing files.
 
-## Graded anomaly alerts
+### Graded anomaly alerts
 
 `alerts.enabled` defaults to false. Inject initialized Reach when enabling it: `audit.init({ reach, alerts: { enabled: true, rules: [...] } })`. Each rule has a stable id, exact actions, optional resource, outcomes and minimumSeverity filters, threshold/windowSeconds, notification severity, and targets containing id/provider/to. Windows default to 300 seconds (60–86400); default outcomes are failure/denied, while an empty outcomes list matches all. Rule and target IDs must be unique; providers must exist in Reach. Business roles remain application choices.
 
@@ -186,7 +222,41 @@ Messages include only rule/target IDs, level, count and window, without event de
 
 alerts.schedule defaults to disabled, once per minute in UTC. audit.schedulerPlan composes enabled backup and alert tasks for explicit host Scheduler initialization; it is null without automatic tasks. Scheduler callbacks fail when checking fails or report.failed>0. Close Scheduler before Audit/Reach. Audit cancels further claims and drains in-flight sends within Reach provider timeouts without closing host Reach. Query/audit failures return a failed HaiResult; notification failures appear in a successful report.failed and must be checked by callers.
 
-## Development and testing
+## Configuration
+
+Lifecycle: init takes backend/business configuration; use the module only after success. Await close before releasing borrowed dependencies. Follow the quick-start example and public signatures for exact return values.
+
+The host loads and validates configuration before passing it to this module. Keep secrets in private server environment files. Select the backend, capacity, deadlines and logging for the actual use case; reinitialize and check the result after changes.
+
+[Per-option purpose, use cases and examples](../../docs/usage/configuration/operations.md).
+
+## Error Handling
+
+Check result.success for domain operations. Handle failures with the module error definitions and safe messages; retain codes, correlation IDs and sanitized causes in server logs. Synchronous tools, factories, stream iteration and lifecycle calls follow their own signatures. A completed Promise alone is not business success. See each feature for recovery limits.
+
+Business data operations return `HaiResult<T>`. Common error codes:
+
+| Error code                       | code            | Description                          |
+| -------------------------------- | --------------- | ------------------------------------ |
+| `HaiAuditError.LOG_FAILED`       | `hai:audit:001` | Recording failed                     |
+| `HaiAuditError.QUERY_FAILED`     | `hai:audit:002` | Query failed                         |
+| `HaiAuditError.CLEANUP_FAILED`   | `hai:audit:003` | Cleanup failed                       |
+| `HaiAuditError.STATS_FAILED`     | `hai:audit:004` | Aggregation failed                   |
+| `HaiAuditError.INIT_IN_PROGRESS` | `hai:audit:005` | Initialization in progress           |
+| `HaiAuditError.NOT_INITIALIZED`  | `hai:audit:010` | Module not initialized               |
+| `HaiAuditError.CONFIG_ERROR`     | `hai:audit:012` | Invalid configuration                |
+| `HaiAuditError.BACKUP_DISABLED`  | `hai:audit:020` | Backup disabled                      |
+| `HaiAuditError.BACKUP_FAILED`    | `hai:audit:021` | Backup or verification failed        |
+| `HaiAuditError.BACKUP_INVALID`   | `hai:audit:022` | Invalid backup input                 |
+| `HaiAuditError.BACKUP_CONFLICT`  | `hai:audit:023` | Backup ID/export conditions conflict |
+| `HaiAuditError.ALERTS_DISABLED`  | `hai:audit:024` | Alerts disabled                      |
+| `HaiAuditError.ALERTS_FAILED`    | `hai:audit:025` | Alert check or notification failed   |
+
+> Note: `audit.close()` also returns `HaiResult<void>`. Email details in `audit.helper.passwordResetRequest()` are hidden by the default business privacy settings.
+
+`audit.init()` awaits automatic table creation and repository readiness before success. DDL failures leave `isInitialized=false`; correct the database and retry. Custom joins, statistics and cleanup share the same barrier. Closing during initialization invalidates late publication. Check the init HaiResult before recording or querying. Audit does not own the shared RelDB connection; close audit before the database.
+
+## Development
 
 ```bash
 pnpm --filter @h-ai/audit test

package/README.ja.md

@@ -4,33 +4,14 @@
 
 [フレームワークのホーム](../../README.ja.md) · 関連モジュール：[@h-ai/core](../core/README.ja.md) · [@h-ai/reldb](../reldb/README.ja.md)
 
-## 概要
-
 統一された監査ログモジュールです。`audit` オブジェクトで記録、検索、削除、集計を行い、`@h-ai/reldb` で永続化します。
 
-SQLite、PostgreSQL、MySQL で読み取り契約は共通です。`createdAt` は `Date`、`details` は JSON 文字列または `null`、値のない nullable フィールドは `null` を返します。日時フィルターは書き込みと同じドライバー変換を使用します。件数は安全な整数とし、範囲外では `STATS_FAILED` を返します。
-
-## 主な機能
-
-- ユーザー操作やセキュリティイベントを記録し、ユーザー・日時・操作で検索。
-- ログのページ取得、統計、保存期間に応じた削除。
-- 関係データベースに保存し、認証情報を記録前にマスク。
-
-## 使い始める
+## クイックスタート
 
 ### 依存関係
 
 - `@h-ai/reldb`：監査ログを永続化するデータベース。**audit.init() より先に初期化してください**。
 
-### 用途
-
-- ユーザー操作の監査（ログイン、ログアウト、登録、パスワードリセットなど）
-- CRUD 操作の監査（リソースの作成、参照、更新、削除）
-- セキュリティイベントの追跡とコンプライアンス監査
-- 運用統計（操作頻度、アクティブユーザーなど）
-
-### クイックスタート
-
 ```ts
 import { audit } from '@h-ai/audit'
 import { reldb } from '@h-ai/reldb'
@@ -54,7 +35,13 @@ await audit.log({
 
 // 4. 使用便捷方法
 await audit.helper.login('user_1', '127.0.0.1')
-await audit.helper.crud({ userId: 'user_1', action: 'create', resource: 'users', resourceId: 'user_2', details: { name: '张三' } })
+await audit.helper.crud({
+  userId: 'user_1',
+  action: 'create',
+  resource: 'users',
+  resourceId: 'user_2',
+  details: { name: '张三' }
+})
 
 // 5. 查询日志
 const logs = await audit.list({ pageSize: 20, action: 'login' })
@@ -72,21 +59,75 @@ if (!closeResult.success) {
 }
 ```
 
-### 初期化設定
+## 機能
 
-```ts
-// 默认配置（无需传参）
-await audit.init()
+SQLite、PostgreSQL、MySQL で読み取り契約は共通です。`createdAt` は `Date`、`details` は JSON 文字列または `null`、値のない nullable フィールドは `null` を返します。日時フィルターは書き込みと同じドライバー変換を使用します。件数は安全な整数とし、範囲外では `STATS_FAILED` を返します。
 
-// 自定义用户表映射
-await audit.init({
-  userTable: 'hai_iam_users', // 用户表名（默认 'hai_iam_users'）
-  userIdColumn: 'id', // 用户表主键列名（默认 'id'）
-  userNameColumn: 'username', // 用户表用户名列名（默认 'username'）
-})
-```
+### 操作と入出力
 
-監査ログは固定の `hai_audit_logs` テーブルに保存され、初期化済みの `@h-ai/reldb` が必要です。
+本節の完全な初期化手順を先に実行します。例の業務値はホストが検証・認可し、非同期領域結果は success を確認してから data を読みます。void はデータなし完了、null は不存在、同期ファクトリー/ツールは表の型を直接返します。
+
+#### audit
+
+構造化イベント。log はイベント/任意 tx から記録、capture は読書方針に従い void、withContext は信頼する関連情報とコールバックからその値を直接返す。
+
+| 入口                | 入力引数           | 成功結果   | 呼出し例                                                    |
+| ------------------- | ------------------ | ---------- | ----------------------------------------------------------- |
+| `audit.log`         | input, tx          | `AuditLog` | `await audit.log(event)`                                    |
+| `audit.capture`     | input, options     | `void`     | `await audit.capture(event)`                                |
+| `audit.withContext` | context, operation | `T`        | `audit.withContext(trustedAuditContext, () => saveOrder())` |
+
+#### audit
+
+検索/保持。条件/ページから利用者付き一覧、ユーザー ID/limit から直近配列、days/filters から統計、cleanup は保持日数から削除数。
+
+| 入口                  | 入力引数      | 成功結果                            | 呼出し例                                      |
+| --------------------- | ------------- | ----------------------------------- | --------------------------------------------- |
+| `audit.list`          | options       | `PaginatedResult<AuditLogWithUser>` | `await audit.list({ page: 1, pageSize: 20 })` |
+| `audit.getUserRecent` | userId, limit | `AuditLog[]`                        | `await audit.getUserRecent(userId, 20)`       |
+| `audit.getStats`      | days, filters | `AuditStatItem[]`                   | `await audit.getStats(7)`                     |
+| `audit.cleanup`       | olderThanDays | `number`                            | `await audit.cleanup(90)`                     |
+
+#### audit.helper
+
+共通イベントはユーザー ID（リセット要求は email）・任意 IP/UA または CRUD 入力から void HaiResult。機密値は引き続き秘匿。
+
+| 入口                                 | 入力引数       | 成功結果 | 呼出し例                                           |
+| ------------------------------------ | -------------- | -------- | -------------------------------------------------- |
+| `audit.helper.login`                 | userId, ip, ua | `void`   | `await audit.helper.login(userId)`                 |
+| `audit.helper.logout`                | userId, ip, ua | `void`   | `await audit.helper.logout(userId)`                |
+| `audit.helper.register`              | userId, ip, ua | `void`   | `await audit.helper.register(userId)`              |
+| `audit.helper.passwordResetRequest`  | email, ip, ua  | `void`   | `await audit.helper.passwordResetRequest(email)`   |
+| `audit.helper.passwordResetComplete` | userId, ip, ua | `void`   | `await audit.helper.passwordResetComplete(userId)` |
+| `audit.helper.crud`                  | input          | `void`   | `await audit.helper.crud(crudEvent)`               |
+
+#### audit.backup
+
+非公開アーカイブ。run は条件/期限/取消、verify はオブジェクト key から完全性を確認した情報を返す。公開しない。
+
+| 入口                  | 入力引数     | 成功結果          | 呼出し例                                |
+| --------------------- | ------------ | ----------------- | --------------------------------------- |
+| `audit.backup.run`    | options      | `AuditBackupInfo` | `await audit.backup.run()`              |
+| `audit.backup.verify` | key, options | `AuditBackupInfo` | `await audit.backup.verify(archiveKey)` |
+
+#### audit
+
+異常検査は任意 signal から該当規則と通知結果。暗黙ワーカーを仮定せず scheduler で調整。
+
+| 入口                | 入力引数 | 成功結果           | 呼出し例                    |
+| ------------------- | -------- | ------------------ | --------------------------- |
+| `audit.checkAlerts` | options  | `AuditAlertReport` | `await audit.checkAlerts()` |
+
+- ユーザー操作やセキュリティイベントを記録し、ユーザー・日時・操作で検索。
+- ログのページ取得、統計、保存期間に応じた削除。
+- 関係データベースに保存し、認証情報を記録前にマスク。
+
+### 用途
+
+- ユーザー操作の監査（ログイン、ログアウト、登録、パスワードリセットなど）
+- CRUD 操作の監査（リソースの作成、参照、更新、削除）
+- セキュリティイベントの追跡とコンプライアンス監査
+- 運用統計（操作頻度、アクティブユーザーなど）
 
 ### API 一覧
 
@@ -110,31 +151,7 @@ await audit.init({
 - `audit.cleanup(days)`：`days` を指定する場合は 0 以上の整数。
 - `audit.getStats(days)`：`days` を指定する場合は 0 以上の整数。
 
-### エラーコード
-
-業務データ操作は `HaiResult<T>` を返します。主なエラーコード：
-
-| エラーコード                     | code            | 説明                       |
-| -------------------------------- | --------------- | -------------------------- |
-| `HaiAuditError.LOG_FAILED`       | `hai:audit:001` | 記録に失敗                 |
-| `HaiAuditError.QUERY_FAILED`     | `hai:audit:002` | 検索に失敗                 |
-| `HaiAuditError.CLEANUP_FAILED`   | `hai:audit:003` | 削除に失敗                 |
-| `HaiAuditError.STATS_FAILED`     | `hai:audit:004` | 集計に失敗                 |
-| `HaiAuditError.INIT_IN_PROGRESS` | `hai:audit:005` | 初期化中                   |
-| `HaiAuditError.NOT_INITIALIZED`  | `hai:audit:010` | モジュールが未初期化       |
-| `HaiAuditError.CONFIG_ERROR`     | `hai:audit:012` | 設定エラー                 |
-| `HaiAuditError.BACKUP_DISABLED`  | `hai:audit:020` | バックアップ無効           |
-| `HaiAuditError.BACKUP_FAILED`    | `hai:audit:021` | バックアップ/検証失敗      |
-| `HaiAuditError.BACKUP_INVALID`   | `hai:audit:022` | バックアップ入力が無効     |
-| `HaiAuditError.BACKUP_CONFLICT`  | `hai:audit:023` | IDとエクスポート条件が衝突 |
-| `HaiAuditError.ALERTS_DISABLED`  | `hai:audit:024` | アラート無効               |
-| `HaiAuditError.ALERTS_FAILED`    | `hai:audit:025` | アラート検査・通知失敗     |
-
-> 注：`audit.close()` も `HaiResult<void>` を返します。`audit.helper.passwordResetRequest()` のメール情報は既定の業務個人情報設定でマスクされます。
-
-`audit.init()` は自動建表とリポジトリーの準備完了を待って成功します。DDL 失敗時は `isInitialized=false` のままで、DB を修正後に再試行できます。独自 JOIN・統計・削除も同じ準備完了を待ちます。初期化中の close は遅れた公開を無効化します。init の HaiResult を確認後に記録・検索し、共有 DB の接続は所有しないため audit の終了後に DB を終了します。
-
-## イベント文脈、個人情報と保持
+### イベント文脈、個人情報と保持
 
 監査 createdAt、アラート窓、アーカイブ終了時刻はノード時刻ではなく DB 時刻を共用します。バックアップ/アラート定時タスクは永続的な重複排除の保証により冪等を宣言し、失敗を非冪等の不明タスクとして後続スケジュールを阻止しません。
 
@@ -152,7 +169,7 @@ await audit.init({
 
 マスキングは項目全体に適用し、オブジェクト、配列、独自 JSON 変換の機密値も隠します。未初期化または close 後の capture は未初期化エラーを返し、初期化済みモジュールで capture を無効にした場合だけ自動イベントを省略します。
 
-## 非公開バックアップと定時アーカイブ
+### 非公開バックアップと定時アーカイブ
 
 `backup.enabled` は既定で無効です。RelDB を先に初期化し、初期化済み StorageFunctions を `audit.init({ storage, backup: { enabled: true } })` に渡します。batchSize は走査件数（既定200）、maxRecordBytes は UTF-8 一行の上限（既定1 MiB）です。上限超過は失敗し、元の監査証拠は切り詰めません。
 
@@ -165,7 +182,10 @@ backup.schedule は enabled、5項目 cron（既定 `0 2 * * *`）、IANA timezo
 ```ts
 const plan = audit.schedulerPlan
 if (plan) {
-  const initialized = await scheduler.init({ ...schedulerSettings, ...plan })
+  const initialized = await scheduler.init({
+    ...schedulerSettings,
+    ...plan
+  })
   if (!initialized.success)
     throw new Error(initialized.error.message)
   const started = scheduler.start()
@@ -176,7 +196,7 @@ if (plan) {
 
 ホストが audit/scheduler と検証済み schedulerSettings を提供し、Audit/Storage/RelDB を初期化済みとします。非公開ストレージを使い、バックアップ有効時は S3 publicUrl 設定を拒否します。バケット/CDN のアクセス制限も必要です。公開ファイル入口は指定資源のみを許可し、example/fullstack は正規のアバターパスだけを公開します。アーカイブの取得には監査の認可入口を使い、無効化後も既存ファイルは非公開のままです。
 
-## 等級別の異常アラート
+### 等級別の異常アラート
 
 `alerts.enabled` は既定で false。有効化時は初期化済み Reach を `audit.init({ reach, alerts: { enabled: true, rules: [...] } })` に渡します。ルールは一意な id、完全一致の actions、任意の resource、outcomes、minimumSeverity、threshold/windowSeconds、通知 severity、id/provider/to を持つ targets で指定します。既定の窓は300秒（60–86400秒）、結果は failure/denied、空の outcomes は全結果です。通知 Provider は Reach に登録済みである必要があります。業務ロールはアプリ側で決定します。
 
@@ -186,6 +206,54 @@ if (plan) {
 
 alerts.schedule は独立して有効化でき、既定は毎分・UTC。audit.schedulerPlan は有効なバックアップ/アラートをまとめ、ホストが Scheduler に明示的に渡します。自動タスクがなければ null。検査失敗または report.failed>0 はタスク失敗です。Scheduler を先に停止し、次に Audit/Reach を閉じます。Audit は新規取得を取消し、Reach の Provider タイムアウト内で実行中通知を待機し、ホスト Reach は閉じません。DB/監査失敗は HaiResult の失敗、通知失敗は成功レポートの failed に現れるため、呼出側で確認します。
 
+## 設定
+
+ライフサイクル。init にバックエンド/業務設定を渡し成功後に使用します。借用依存先の解放前に close の完了を待ち、正確な戻り値は例と公開署名に従います。
+
+```ts
+// 默认配置（无需传参）
+await audit.init()
+
+// 自定义用户表映射
+await audit.init({
+  userTable: 'hai_iam_users', // 用户表名（默认 'hai_iam_users'）
+  userIdColumn: 'id', // 用户表主键列名（默认 'id'）
+  userNameColumn: 'username', // 用户表用户名列名（默认 'username'）
+})
+```
+
+監査ログは固定の `hai_audit_logs` テーブルに保存され、初期化済みの `@h-ai/reldb` が必要です。
+
+設定はホストが読込・検証してから渡します。秘密はサーバーの非公開環境に保存し、利用場面に応じてバックエンド・容量・期限・ログを選びます。変更後は再初期化の結果を確認してください。
+
+[項目別の用途・適用場面・例](../../docs/usage/configuration/operations.md).
+
+## エラー処理
+
+領域操作は result.success を確認し、失敗時はモジュールのエラー定義と安全な説明を使います。コード・関連 ID・秘匿した原因をサーバーログに残します。同期ツール・ファクトリー・ストリーム反復・ライフサイクルは各署名に従い、Promise 完了だけで成功と判断しません。回復条件は各機能を参照してください。
+
+業務データ操作は `HaiResult<T>` を返します。主なエラーコード：
+
+| エラーコード                     | code            | 説明                       |
+| -------------------------------- | --------------- | -------------------------- |
+| `HaiAuditError.LOG_FAILED`       | `hai:audit:001` | 記録に失敗                 |
+| `HaiAuditError.QUERY_FAILED`     | `hai:audit:002` | 検索に失敗                 |
+| `HaiAuditError.CLEANUP_FAILED`   | `hai:audit:003` | 削除に失敗                 |
+| `HaiAuditError.STATS_FAILED`     | `hai:audit:004` | 集計に失敗                 |
+| `HaiAuditError.INIT_IN_PROGRESS` | `hai:audit:005` | 初期化中                   |
+| `HaiAuditError.NOT_INITIALIZED`  | `hai:audit:010` | モジュールが未初期化       |
+| `HaiAuditError.CONFIG_ERROR`     | `hai:audit:012` | 設定エラー                 |
+| `HaiAuditError.BACKUP_DISABLED`  | `hai:audit:020` | バックアップ無効           |
+| `HaiAuditError.BACKUP_FAILED`    | `hai:audit:021` | バックアップ/検証失敗      |
+| `HaiAuditError.BACKUP_INVALID`   | `hai:audit:022` | バックアップ入力が無効     |
+| `HaiAuditError.BACKUP_CONFLICT`  | `hai:audit:023` | IDとエクスポート条件が衝突 |
+| `HaiAuditError.ALERTS_DISABLED`  | `hai:audit:024` | アラート無効               |
+| `HaiAuditError.ALERTS_FAILED`    | `hai:audit:025` | アラート検査・通知失敗     |
+
+> 注：`audit.close()` も `HaiResult<void>` を返します。`audit.helper.passwordResetRequest()` のメール情報は既定の業務個人情報設定でマスクされます。
+
+`audit.init()` は自動建表とリポジトリーの準備完了を待って成功します。DDL 失敗時は `isInitialized=false` のままで、DB を修正後に再試行できます。独自 JOIN・統計・削除も同じ準備完了を待ちます。初期化中の close は遅れた公開を無効化します。init の HaiResult を確認後に記録・検索し、共有 DB の接続は所有しないため audit の終了後に DB を終了します。
+
 ## 開発とテスト
 
 ```bash