@h-ai/audit 0.1.0-alpha9 → 1.0.0-beta.10

package/dist/index.d.ts

@@ -1,6 +1,11 @@
+import { ReachFunctions } from '@h-ai/reach';
+import { StorageFunctions } from '@h-ai/storage';
 import { z } from 'zod';
 import * as _h_ai_core from '@h-ai/core';
-import { HaiResult } from '@h-ai/core';
+import { HaiResult, PaginationOptionsInput, PaginatedResult } from '@h-ai/core';
+import * as _h_ai_reldb from '@h-ai/reldb';
+import { DmlWithTxOperations } from '@h-ai/reldb';
+import { SchedulerInitInput } from '@h-ai/scheduler';
 
 /**
  * @h-ai/audit — 错误码与配置
@@ -13,32 +18,111 @@ import { HaiResult } from '@h-ai/core';
  * 审计模块初始化配置 Schema（Zod）
  *
  * 所有字段均有默认值，可直接调用 `audit.init()` 无需传参。
- *
  * @example
  * ```ts
- * import { audit } from '@h-ai/audit'
- * import { reldb } from '@h-ai/reldb'
- *
- * await audit.init()
- *
- * // 自定义用户表映射
- * await audit.init({
- *   userTable: 'sys_users',
- *   userIdColumn: 'user_id',
- *   userNameColumn: 'name',
- * })
+ * import { AuditInitConfigSchema } from '@h-ai/audit'
+ * const config = AuditInitConfigSchema.parse({ userTable: 'app_users' })
+ * // 这里只校验字段映射；实际初始化前必须已有可用的 RelDB。
  * ```
  */
 declare const AuditInitConfigSchema: z.ZodObject<{
+    alerts: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        maxNotificationsPerCheck: z.ZodDefault<z.ZodNumber>;
+        rules: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            actions: z.ZodArray<z.ZodString>;
+            resource: z.ZodOptional<z.ZodString>;
+            outcomes: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+                success: "success";
+                failure: "failure";
+                denied: "denied";
+            }>>>;
+            minimumSeverity: z.ZodDefault<z.ZodEnum<{
+                error: "error";
+                info: "info";
+                warning: "warning";
+                critical: "critical";
+            }>>;
+            severity: z.ZodDefault<z.ZodEnum<{
+                error: "error";
+                warning: "warning";
+                critical: "critical";
+            }>>;
+            threshold: z.ZodDefault<z.ZodNumber>;
+            windowSeconds: z.ZodDefault<z.ZodNumber>;
+            targets: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                provider: z.ZodString;
+                to: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>>;
+        schedule: z.ZodDefault<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            cron: z.ZodDefault<z.ZodString>;
+            timezone: z.ZodDefault<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    backup: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        batchSize: z.ZodDefault<z.ZodNumber>;
+        maxRecordBytes: z.ZodDefault<z.ZodNumber>;
+        schedule: z.ZodDefault<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            cron: z.ZodDefault<z.ZodString>;
+            timezone: z.ZodDefault<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    capture: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        includeReads: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    retention: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        minDays: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    privacy: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        fields: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
     userTable: z.ZodDefault<z.ZodString>;
     userIdColumn: z.ZodDefault<z.ZodString>;
     userNameColumn: z.ZodDefault<z.ZodString>;
 }, z.core.$strip>;
-/** 审计模块初始化配置（解析后） */
+/**
+ * 审计模块初始化配置（解析后）
+ * @example
+ * ```ts
+ * import { AuditInitConfigSchema, type AuditInitConfig } from '@h-ai/audit'
+ * const config: AuditInitConfig = AuditInitConfigSchema.parse({ userTable: 'app_users' })
+ * ```
+ */
 type AuditInitConfig = z.output<typeof AuditInitConfigSchema>;
-/** 审计模块初始化配置（传入参数） */
-type AuditInitConfigInput = z.input<typeof AuditInitConfigSchema>;
+/**
+ * 审计模块初始化配置（传入参数）
+ * @example
+ * ```ts
+ * import type { AuditInitConfigInput } from '@h-ai/audit'
+ * const record: AuditInitConfigInput = { userTable: 'app_users', userIdColumn: 'id', userNameColumn: 'username' }
+ * ```
+ */
+type AuditInitConfigInput = z.input<typeof AuditInitConfigSchema> & {
+    /** 开启备份时注入已初始化且私有访问的存储；audit 不拥有它的生命周期。 */
+    storage?: StorageFunctions;
+    /** 开启告警时注入已初始化的 Reach；通知人员/目标仍由应用配置。 */
+    reach?: ReachFunctions;
+};
 
+/**
+ * 审计初始化、写入、查询和清理失败的稳定错误定义。
+ * @example
+ * ```ts
+ * import { HaiAuditError } from '@h-ai/audit'
+ * import { err } from '@h-ai/core'
+ * const failed = err(HaiAuditError.NOT_INITIALIZED, 'Audit is not initialized')
+ * if (!failed.success) failed.error.code
+ * ```
+ */
 declare const HaiAuditError: {
     readonly LOG_FAILED: _h_ai_core.HaiErrorDef;
     readonly QUERY_FAILED: _h_ai_core.HaiErrorDef;
@@ -47,13 +131,72 @@ declare const HaiAuditError: {
     readonly INIT_IN_PROGRESS: _h_ai_core.HaiErrorDef;
     readonly NOT_INITIALIZED: _h_ai_core.HaiErrorDef;
     readonly CONFIG_ERROR: _h_ai_core.HaiErrorDef;
+    readonly BACKUP_DISABLED: _h_ai_core.HaiErrorDef;
+    readonly BACKUP_FAILED: _h_ai_core.HaiErrorDef;
+    readonly BACKUP_INVALID: _h_ai_core.HaiErrorDef;
+    readonly BACKUP_CONFLICT: _h_ai_core.HaiErrorDef;
+    readonly ALERTS_DISABLED: _h_ai_core.HaiErrorDef;
+    readonly ALERTS_FAILED: _h_ai_core.HaiErrorDef;
 };
+/**
+ * 事件发生时的最小身份快照，不承载授权真值或凭据。
+ * @example
+ * ```ts
+ * import type { AuditActorSnapshot } from '@h-ai/audit'
+ * const actor: AuditActorSnapshot = { id: 'user-1', username: 'alice', roles: ['auditor'] }
+ * ```
+ */
+interface AuditActorSnapshot {
+    id: string;
+    username?: string;
+    displayName?: string;
+    roles?: string[];
+}
+/**
+ * 异步请求的审计上下文；不替代会话校验或权限守卫。
+ * @example
+ * ```ts
+ * import type { AuditContext } from '@h-ai/audit'
+ * const context: AuditContext = { requestId: 'request-1', actor: { id: 'user-1', username: 'alice' }, ipAddress: '192.0.2.8' }
+ * ```
+ */
+interface AuditContext {
+    actor?: AuditActorSnapshot | null;
+    category?: 'system' | 'business';
+    requestId?: string;
+    traceId?: string;
+    scopeId?: string;
+    ipAddress?: string;
+    userAgent?: string;
+}
+/**
+ * 分类、结果、等级及事件身份；旧记录升级前未知的值保持 null。
+ * @example
+ * ```ts
+ * import type { AuditEventFields } from '@h-ai/audit'
+ * const fields: AuditEventFields = { category: 'system', outcome: 'denied', severity: 'warning', requestId: 'request-1' }
+ * ```
+ */
+interface AuditEventFields {
+    category?: 'system' | 'business' | null;
+    outcome?: 'success' | 'failure' | 'denied' | null;
+    severity?: 'info' | 'warning' | 'error' | 'critical' | null;
+    requestId?: string | null;
+    traceId?: string | null;
+    scopeId?: string | null;
+    actorSnapshot?: AuditActorSnapshot | null;
+}
 /**
  * 审计日志记录
  *
  * 表示一条已持久化的审计日志条目。
+ * @example
+ * ```ts
+ * import type { AuditLog } from '@h-ai/audit'
+ * const record: AuditLog = { id: 'audit_example', userId: 'user_1', action: 'create', resource: 'orders', resourceId: 'order_1', details: null, ipAddress: null, userAgent: null, createdAt: new Date() }
+ * ```
  */
-interface AuditLog {
+interface AuditLog extends AuditEventFields {
     /** 审计日志 ID，格式为 `audit_` 前缀 + 随机串 */
     id: string;
     /** 操作用户 ID；系统操作时为 null */
@@ -76,7 +219,12 @@ interface AuditLog {
 /**
  * 审计日志记录（含用户名）
  *
- * 通过 LEFT JOIN 用户表获取 username 字段，用于列表展示。
+ * 新记录使用事件时身份快照；无快照的历史记录才保留旧的用户表关联展示。
+ * @example
+ * ```ts
+ * import type { AuditLogWithUser } from '@h-ai/audit'
+ * const record: AuditLogWithUser = { id: 'audit_example', userId: 'user_1', action: 'create', resource: 'orders', resourceId: 'order_1', details: null, ipAddress: null, userAgent: null, createdAt: new Date() , username: 'alice' }
+ * ```
  */
 interface AuditLogWithUser extends AuditLog {
     /** 操作用户的用户名；用户不存在或系统操作时为 null */
@@ -87,8 +235,13 @@ interface AuditLogWithUser extends AuditLog {
  *
  * 调用 {@link AuditFunctions.log} 时传入的参数。
  * 仅 `action` 和 `resource` 为必填。
+ * @example
+ * ```ts
+ * import type { CreateAuditLogInput } from '@h-ai/audit'
+ * const record: CreateAuditLogInput = { userId: 'user_1', action: 'create', resource: 'orders', resourceId: 'order_1', details: { status: 'pending' } }
+ * ```
  */
-interface CreateAuditLogInput {
+interface CreateAuditLogInput extends AuditEventFields {
     /** 操作用户 ID；系统操作可省略 */
     userId?: string | null;
     /** 操作类型（如 login / create / update / delete） */
@@ -97,7 +250,7 @@ interface CreateAuditLogInput {
     resource: string;
     /** 资源 ID；不涉及特定资源时可省略 */
     resourceId?: string | null;
-    /** 操作详情对象，会被 JSON 序列化存储 */
+    /** 操作详情对象；密码、token、secret 等凭证类字段会先自动脱敏，再 JSON 序列化存储 */
     details?: Record<string, unknown> | null;
     /** 客户端 IP 地址 */
     ipAddress?: string | null;
@@ -108,8 +261,22 @@ interface CreateAuditLogInput {
  * 审计日志列表查询选项
  *
  * 所有字段均为可选，不传则不过滤。
+ * @example
+ * ```ts
+ * import type { ListAuditLogsOptions } from '@h-ai/audit'
+ * const record: ListAuditLogsOptions = { action: 'create', resource: 'orders', page: 1, pageSize: 20 }
+ * ```
  */
-interface ListAuditLogsOptions {
+interface ListAuditLogsOptions extends PaginationOptionsInput {
+    /** 按可信入口生成或校验的请求/追踪编号定位关联事件。 */
+    requestId?: string;
+    traceId?: string;
+    category?: 'system' | 'business';
+    outcome?: 'success' | 'failure' | 'denied';
+    severity?: 'info' | 'warning' | 'error' | 'critical';
+    scopeId?: string;
+    sortBy?: 'createdAt' | 'action' | 'resource' | 'category' | 'outcome' | 'severity';
+    sortDirection?: 'asc' | 'desc';
     /** 按用户 ID 过滤 */
     userId?: string;
     /** 按操作类型过滤（精确匹配） */
@@ -120,19 +287,16 @@ interface ListAuditLogsOptions {
     startDate?: Date;
     /** 结束时间（含），只返回此时间之前的日志 */
     endDate?: Date;
-    /** 页码，从 1 开始 */
-    page?: number;
-    /**
-     * 每页条数
-     *
-     * @default 20
-     */
-    pageSize?: number;
 }
 /**
  * 审计统计结果项
  *
  * 按操作类型（action）分组的统计条目。
+ * @example
+ * ```ts
+ * import type { AuditStatItem } from '@h-ai/audit'
+ * const record: AuditStatItem = { action: 'create', count: 12 }
+ * ```
  */
 interface AuditStatItem {
     /** 操作类型 */
@@ -144,8 +308,13 @@ interface AuditStatItem {
  * CRUD 审计操作输入
  *
  * 调用 {@link AuditHelper.crud} 时传入的参数。
+ * @example
+ * ```ts
+ * import type { CrudAuditInput } from '@h-ai/audit'
+ * const record: CrudAuditInput = { userId: 'user_1', action: 'update', resource: 'orders', resourceId: 'order_1', details: { status: 'paid' } }
+ * ```
  */
-interface CrudAuditInput {
+interface CrudAuditInput extends AuditEventFields {
     /** 操作用户 ID（系统操作传 null） */
     userId?: string | null;
     /** 操作类型 */
@@ -166,11 +335,14 @@ interface CrudAuditInput {
  *
  * 封装常见审计场景（认证、CRUD），简化调用方代码。
  * 通过 {@link AuditFunctions.helper} 访问。
- *
  * @example
  * ```ts
- * await audit.helper.login('user_1', '127.0.0.1', 'Mozilla/5.0')
- * await audit.helper.crud({ userId: 'user_1', action: 'create', resource: 'users', resourceId: 'user_2' })
+ * import type { AuditHelper } from '@h-ai/audit'
+ * // helper 来自已初始化的 audit；数据库生命周期归调用方。
+ * async function recordLogin(helper: AuditHelper) {
+ *   const result = await helper.login('user_1', '127.0.0.1')
+ *   return result.success ? 'recorded' : result.error.message
+ * }
  * ```
  */
 interface AuditHelper {
@@ -230,21 +402,45 @@ interface AuditHelper {
  * 审计模块函数接口
  *
  * 统一的审计日志访问入口。
- *
  * @example
  * ```ts
  * import { audit } from '@h-ai/audit'
- * import { reldb } from '@h-ai/reldb'
- *
- * await reldb.init({ type: 'sqlite', database: './data.db' })
- * await audit.init()
- *
- * await audit.log({ userId: 'user_1', action: 'login', resource: 'auth' })
- * const logs = await audit.list({ pageSize: 10 })
- * await audit.close()
+ * import { core } from '@h-ai/core'
+ * import { reldb, type ReldbConfigInput } from '@h-ai/reldb'
+ * async function recordCreation(config: ReldbConfigInput) {
+ *   const database = await reldb.init(config)
+ *   if (!database.success) return database
+ *   try {
+ *     const initialized = await audit.init()
+ *     if (!initialized.success) return initialized
+ *     const logged = await audit.log({ action: 'create', resource: 'orders', resourceId: 'order_1' })
+ *     if (logged.success) core.logger.info('Audit recorded', { id: logged.data.id })
+ *     return logged
+ *   } finally {
+ *     const auditClosed = await audit.close()
+ *     if (!auditClosed.success) return auditClosed // 保留依赖连接，修复后重试关闭。
+ *     const databaseClosed = await reldb.close()
+ *     if (!databaseClosed.success) return databaseClosed
+ *   }
+ * }
  * ```
  */
 interface AuditFunctions {
+    /** 手动流式归档与完整性核对，关闭后返回未初始化。 */
+    readonly backup: AuditBackupOperations;
+    /** 宿主显式装配的备份/告警任务计划；没有启用自动任务时为 null。 */
+    readonly schedulerPlan: Required<Pick<SchedulerInitInput, 'tasks' | 'hooks'>> | null;
+    /** 检查已提交事件的本窗口和前一窗口；每个规则/目标/窗口只尝试一次外部通知。 */
+    checkAlerts: (options?: {
+        signal?: AbortSignal;
+    }) => Promise<HaiResult<AuditAlertReport>>;
+    /**
+     * 在异步隔离的审计上下文中执行操作；同步或异步结果原样返回，调用方异常原样传播。
+     * @param context - 可信宿主解析的关联字段与身份快照。
+     * @param operation - 业务操作，内部 audit.log 自动补齐未显式指定的字段。
+     * @returns 业务操作的原始返回值或 Promise。
+     */
+    withContext: <T>(context: AuditContext, operation: () => T) => T;
     /**
      * 初始化审计模块
      *
@@ -255,26 +451,37 @@ interface AuditFunctions {
     /**
      * 关闭审计模块，释放内部状态
      */
-    close: () => Promise<void>;
+    close: () => Promise<HaiResult<void>>;
     /** 当前是否已初始化 */
     readonly isInitialized: boolean;
     /**
      * 记录一条审计日志
      *
      * @param input - 日志内容（action 和 resource 为必填）
+     * @param tx - 可选的调用者事务；提交或回滚同时决定事件，不在此提交事务。
      * @returns 成功时返回创建的 AuditLog；失败时返回 LOG_FAILED
      */
-    log: (input: CreateAuditLogInput) => Promise<HaiResult<AuditLog>>;
+    log: (input: CreateAuditLogInput, tx?: DmlWithTxOperations) => Promise<HaiResult<AuditLog>>;
+    /**
+     * 框架入口自动记录。模块未初始化或关闭自动采集时跳过；默认跳过成功读取。
+     * 不改变原业务结果；调用方仍须检查记录失败，避免静默丢失审计。
+     * @param input - 仅包含安全的事件字段，不应复制请求体或凭据。
+     * @param options - 入口是否属于读取操作；失败和拒绝的读取始终采集。
+     * @param options.read - 读取标志；默认 false。
+     * @param options.tx - 可选的调用者事务；回滚不会留下成功变更事件。
+     * @returns 持久化成功或按配置跳过时成功，否则返回审计错误。
+     */
+    capture: (input: CreateAuditLogInput, options?: {
+        read?: boolean;
+        tx?: DmlWithTxOperations;
+    }) => Promise<HaiResult<void>>;
     /**
      * 分页查询审计日志列表（含用户名 LEFT JOIN）
      *
      * @param options - 查询过滤与分页选项
-     * @returns 成功时返回 { items, total }；失败时返回 QUERY_FAILED
+     * @returns 成功时返回 PaginatedResult（items/total/page/pageSize）；失败时返回 QUERY_FAILED
      */
-    list: (options?: ListAuditLogsOptions) => Promise<HaiResult<{
-        items: AuditLogWithUser[];
-        total: number;
-    }>>;
+    list: (options?: ListAuditLogsOptions) => Promise<HaiResult<PaginatedResult<AuditLogWithUser>>>;
     /**
      * 获取指定用户的最近活动记录
      *
@@ -296,7 +503,7 @@ interface AuditFunctions {
      * @param days - 统计天数，默认 7
      * @returns 成功时返回 AuditStatItem 数组；失败时返回 STATS_FAILED
      */
-    getStats: (days?: number) => Promise<HaiResult<AuditStatItem[]>>;
+    getStats: (days?: number, filters?: Pick<ListAuditLogsOptions, 'category' | 'outcome' | 'severity' | 'scopeId' | 'userId' | 'resource'>) => Promise<HaiResult<AuditStatItem[]>>;
     /**
      * 便捷记录器，封装常见审计场景
      *
@@ -304,24 +511,82 @@ interface AuditFunctions {
      */
     readonly helper: AuditHelper;
 }
-
 /**
- * @h-ai/audit — 审计便捷记录器
- *
- * 封装常见审计操作（登录、登出、注册、密码重置、CRUD），简化调用方代码。
- * @module audit-helper
+ * 私有归档键前缀；宿主公开文件入口须拒绝此命名空间，即使备份策略已关闭。
+ * @example
+ * ```ts
+ * import { AUDIT_BACKUP_PREFIX } from '@h-ai/audit'
+ * const key = `${AUDIT_BACKUP_PREFIX}daily-archive.jsonl`
+ * ```
  */
-
+declare const AUDIT_BACKUP_PREFIX = "hai-private/audit-backups/";
 /**
- * 创建便捷记录器
- *
- * 封装常见审计操作（登录、登出、注册、密码重置、CRUD），
- * 简化调用方代码。每个方法内部调用 logFn 并将 AuditLog 结果映射为 void。
- *
- * @param logFn - 底层日志记录函数（通常为 currentRepo.log）
- * @returns 便捷记录器接口
+ * 归档扫描条件。缺省截止时刻在开始时固定，过程中新增日志交给下一次归档。
+ * @example
+ * ```ts
+ * import type { AuditBackupOptions } from '@h-ai/audit'
+ * const options: AuditBackupOptions = { id: 'daily-archive', from: new Date('2026-01-01T00:00:00Z') }
+ * ```
  */
-declare function createHelper(logFn: (input: CreateAuditLogInput) => Promise<HaiResult<AuditLog>>): AuditHelper;
+interface AuditBackupOptions {
+    /** 同一业务执行使用稳定 ID；省略时生成随机 ID。已有 ID 仅核对并复用完整归档。 */
+    id?: string;
+    from?: Date;
+    to?: Date;
+    signal?: AbortSignal;
+}
+/**
+ * 完整归档回执；SHA-256 校验内容完整性，不能替代独立存储权限或真实性认证。
+ * @example
+ * ```ts
+ * import { audit, type AuditBackupInfo } from '@h-ai/audit'
+ * // 宿主已初始化 RelDB、私有 Storage 和 Audit。
+ * const result = await audit.backup.run()
+ * if (result.success) { const receipt: AuditBackupInfo = result.data; void receipt.sha256 }
+ * ```
+ */
+interface AuditBackupInfo {
+    id: string;
+    key: string;
+    recordCount: number;
+    sha256: string;
+    createdAt: Date;
+    cutoff: Date;
+}
+/**
+ * 备份不覆盖在线审计。JSONL 归档可核对后用于离线恢复/独立查询存储。
+ * @example
+ * ```ts
+ * import { audit, type AuditBackupOperations } from '@h-ai/audit'
+ * const operations: AuditBackupOperations = audit.backup
+ * const result = await operations.run({ id: 'daily-archive' })
+ * if (!result.success) result.error.code
+ * ```
+ */
+interface AuditBackupOperations {
+    /** 创建或核对并复用同一 ID 的完整归档；已有归档不覆盖，输入无效、取消或存储失败返回失败。 */
+    run: (options?: AuditBackupOptions) => Promise<HaiResult<AuditBackupInfo>>;
+    /** 有界流式核对规范、记录数和校验和；只允许读取私有归档命名空间。 */
+    verify: (key: string, options?: {
+        signal?: AbortSignal;
+    }) => Promise<HaiResult<AuditBackupInfo>>;
+}
+/**
+ * 本次检查的通知提交回执；submitted 不证明收件人已阅读，queued 仅表示 Reach 持久入队。
+ * @example
+ * ```ts
+ * import { audit, type AuditAlertReport } from '@h-ai/audit'
+ * const result = await audit.checkAlerts()
+ * if (result.success) { const report: AuditAlertReport = result.data; void report.failed }
+ * ```
+ */
+interface AuditAlertReport {
+    submitted: number;
+    queued: number;
+    failed: number;
+    /** 已达到单轮通知上限，后续检查继续领取未尝试目标。 */
+    more: boolean;
+}
 
 /**
  * @h-ai/audit — 审计日志服务主入口
@@ -343,23 +608,41 @@ declare function createHelper(logFn: (input: CreateAuditLogInput) => Promise<Hai
  * - `audit.getStats()` — 获取统计数据
  * - `audit.helper` — 便捷记录器
  * - `audit.isInitialized` — 初始化状态
- *
  * @example
  * ```ts
  * import { audit } from '@h-ai/audit'
- * import { reldb } from '@h-ai/reldb'
- *
- * await reldb.init({ type: 'sqlite', database: ':memory:' })
- * const result = await audit.init()
- * if (!result.success) {
- *   // 处理初始化错误
+ * import { core } from '@h-ai/core'
+ * import { reldb, type ReldbConfigInput } from '@h-ai/reldb'
+ * async function recordCreation(config: ReldbConfigInput) {
+ *   const database = await reldb.init(config)
+ *   if (!database.success) return database
+ *   try {
+ *     const initialized = await audit.init()
+ *     if (!initialized.success) return initialized
+ *     const logged = await audit.log({ action: 'create', resource: 'orders', resourceId: 'order_1' })
+ *     if (logged.success) core.logger.info('Audit recorded', { id: logged.data.id })
+ *     return logged
+ *   } finally {
+ *     const auditClosed = await audit.close()
+ *     if (!auditClosed.success) return auditClosed // 保留依赖连接，修复后重试关闭。
+ *     const databaseClosed = await reldb.close()
+ *     if (!databaseClosed.success) return databaseClosed
+ *   }
  * }
- *
- * await audit.helper.login('user_1', '127.0.0.1')
- * const logs = await audit.list({ pageSize: 10 })
- * await audit.close()
  * ```
  */
 declare const audit: AuditFunctions;
 
-export { type AuditFunctions, type AuditHelper, type AuditInitConfig, type AuditInitConfigInput, AuditInitConfigSchema, type AuditLog, type AuditLogWithUser, type AuditStatItem, type CreateAuditLogInput, type CrudAuditInput, HaiAuditError, type ListAuditLogsOptions, audit, createHelper };
+/**
+ * 只读预检或迁移审计字段、保留设置和写入保护；升级前停旧写入并备份。
+ * @example
+ * ```ts
+ * import { migrateAudit } from '@h-ai/audit'
+ * const plan = await migrateAudit({ dryRun: true }) // RelDB 已初始化；不改写记录。
+ * ```
+ */
+declare function migrateAudit(options?: {
+    dryRun?: boolean;
+}): Promise<HaiResult<_h_ai_reldb.SchemaMigrationPlan>>;
+
+export { AUDIT_BACKUP_PREFIX, type AuditActorSnapshot, type AuditAlertReport, type AuditBackupInfo, type AuditBackupOperations, type AuditBackupOptions, type AuditContext, type AuditEventFields, type AuditFunctions, type AuditHelper, type AuditInitConfig, type AuditInitConfigInput, AuditInitConfigSchema, type AuditLog, type AuditLogWithUser, type AuditStatItem, type CreateAuditLogInput, type CrudAuditInput, HaiAuditError, type ListAuditLogsOptions, audit, migrateAudit };