@h-ai/audit 1.0.0-beta.22 → 1.0.0-beta.24

package/README.en.md

@@ -181,7 +181,7 @@ New records include category (system/business), outcome (success/failure/denied)
 
 `retention: { enabled: true, minDays: 90 }` activates a shared database policy. Cleanup honors the actual minimum even with cleanup(0); triggers reject protected UPDATE, DELETE and conflicting replacement writes. An unconfigured fresh framework installation does not force retention protection: the default cleanup argument of 90 days alone is no immutability guarantee. Reinitialization without retention preserves the database policy; explicit trusted startup configuration can disable it. This covers ordinary row writes; database-owner DDL/privileges and stronger archive/storage protection belong to deployment management.
 
-Stop old writers and back up before upgrading. `migrateAudit({ dryRun: true })` previews without writes; audit.init applies repeatable migrations. Unknown historical fields remain null. Legacy joined usernames are display compatibility, rather than historical identity evidence. Failed writes return failure and emit correlated diagnostics. close drains started writes before RelDB can close.
+`audit.init()` prepares the current tables and retention policy and fails if their structure is incompatible. List results use the event-time actor snapshot for the username and return `null` when it is unavailable. Failed writes return an error and emit correlated diagnostics. Close audit before closing RelDB so started writes can finish.
 
 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.
 

package/README.ja.md

@@ -133,7 +133,7 @@ SQLite、PostgreSQL、MySQL で読み取り契約は共通です。`createdAt`
 
 - `audit.init(config)`：監査モジュールを初期化。
 - `audit.log(input)`：監査ログを記録。
-- `audit.list(options)`：`PaginatedResult<AuditLogWithUser>`（items/total/page/pageSize、ユーザー名 JOIN）を返します。core がページ入力を正規化し、既定 pageSize は 20 です。返されたメタデータを直接利用してください。
+- `audit.list(options)`：`PaginatedResult<AuditLogWithUser>`（items/total/page/pageSize、イベント時のユーザー名）を返します。core がページ入力を正規化し、既定 pageSize は 20 です。返されたメタデータを直接利用してください。
 - `audit.getUserRecent(userId, limit)`：ユーザーの最近の操作を取得。
 - `audit.cleanup(days)`：古いログを削除。
 - `audit.getStats(days)`：操作統計を取得。
@@ -165,7 +165,7 @@ SQLite、PostgreSQL、MySQL で読み取り契約は共通です。`createdAt`
 
 `retention: { enabled: true, minDays: 90 }` は共有DBの最低保持を有効にします。cleanup(0) も最低期間を守り、トリガーは保護対象の UPDATE・DELETE・衝突置換を拒否します。未設定の新規フレームワークは保持保護を強制せず、削除引数の既定90日だけでは不変保証になりません。retention を省略した再初期化はDB設定を継続し、信頼できる起動設定で明示的に無効化できます。通常の行書込を対象とし、DB所有者のDDL・権限や独立アーカイブなどは配備側で管理します。
 
-更新前に旧書込を停止してバックアップし、`migrateAudit({ dryRun: true })` で読み取り専用の事前確認ができます。audit.init は再実行可能な移行を行います。歴史上不明な分類・結果・身元は null のままです。旧記録のユーザー表JOINは表示互換であり、当時の身元の証拠にはしません。書込失敗は失敗結果と関連診断を返し、close は開始済み書込を待つため、その後に RelDB を閉じてください。
+`audit.init()` は現在のテーブル構造と保持ポリシーを準備し、構造が一致しない場合は失敗します。一覧のユーザー名はイベント時のスナップショットを使用し、名称がない場合は `null` です。書き込み失敗時はエラーと関連診断を返します。開始済みの書き込みを待つため、RelDB の前に audit を終了します。
 
 マスキングは項目全体に適用し、オブジェクト、配列、独自 JSON 変換の機密値も隠します。未初期化または close 後の capture は未初期化エラーを返し、初期化済みモジュールで capture を無効にした場合だけ自動イベントを省略します。
 
@@ -252,7 +252,7 @@ await audit.init({
 
 > 注：`audit.close()` も `HaiResult<void>` を返します。`audit.helper.passwordResetRequest()` のメール情報は既定の業務個人情報設定でマスクされます。
 
-`audit.init()` は自動建表とリポジトリーの準備完了を待って成功します。DDL 失敗時は `isInitialized=false` のままで、DB を修正後に再試行できます。独自 JOIN・統計・削除も同じ準備完了を待ちます。初期化中の close は遅れた公開を無効化します。init の HaiResult を確認後に記録・検索し、共有 DB の接続は所有しないため audit の終了後に DB を終了します。
+`audit.init()` は自動建表とリポジトリーの準備完了を待って成功します。DDL 失敗時は `isInitialized=false` のままで、DB を修正後に再試行できます。一覧・統計・削除も同じ準備完了を待ちます。初期化中の close は遅れた公開を無効化します。init の HaiResult を確認後に記録・検索し、共有 DB の接続は所有しないため audit の終了後に DB を終了します。
 
 ## 開発とテスト
 

package/README.md

@@ -133,7 +133,7 @@ SQLite、PostgreSQL、MySQL 的读取结果保持同一契约：`createdAt` 为
 
 - `audit.init(config)` - 初始化审计模块
 - `audit.log(input)` - 记录审计日志
-- `audit.list(options)` - 返回统一 `PaginatedResult<AuditLogWithUser>`（items/total/page/pageSize，含用户名 JOIN）；页码/条数复用 core 分页规范化，默认 pageSize 为 20，调用方直接使用返回元数据。
+- `audit.list(options)` - 返回统一 `PaginatedResult<AuditLogWithUser>`（items/total/page/pageSize，含事件时的用户名）；页码/条数复用 core 分页规范化，默认 pageSize 为 20，调用方直接使用返回元数据。
 - `audit.getUserRecent(userId, limit)` - 获取用户最近活动
 - `audit.cleanup(days)` - 清理旧日志
 - `audit.getStats(days, filters)` - 获取按分类等条件筛选的操作统计
@@ -165,7 +165,7 @@ SQLite、PostgreSQL、MySQL 的读取结果保持同一契约：`createdAt` 为
 
 `retention: { enabled: true, minDays: 90 }` 开启最低保留。共享数据库保存策略，清理使用实际最低期限，`cleanup(0)` 不能绕过；数据库触发器拒绝保护期内的 UPDATE、DELETE 和冲突覆盖写。框架首次未配置时不强制保护，清理参数默认90天本身不构成不可变保证。未传 retention 的重初始化沿用既有策略，只有可信启动配置显式关闭才解除。该保护针对正常行级写入；数据库所有者的 DDL/权限、独立归档和更强存储保护需由部署管理。
 
-升级前先停旧写入并备份，`migrateAudit({ dryRun: true })` 只读预检；audit.init 自动执行可重入升级。历史未知分类、结果和身份快照保持 null，不补造历史身份。列表对无快照的历史记录保留旧的用户表关联展示，不能当作事件时身份。写入失败返回失败并输出关联诊断；close 等待已开始写入后再释放模块，随后才能关闭 RelDB。
+`audit.init()` 准备当前表结构和留存策略，结构不符时返回初始化失败。列表中的用户名来自事件时的身份快照，缺失时为 `null`。写入失败返回失败并输出关联诊断。`audit.close()` 等待已开始的写入，随后可关闭 RelDB。
 
 脱敏匹配整个字段：对象、数组以及自定义 JSON 投影内的敏感值同样隐藏。关闭或尚未初始化 Audit 时，capture 返回未初始化失败；只有已初始化模块的关闭采集配置才跳过自动事件。
 
@@ -252,7 +252,7 @@ await audit.init({
 
 > 说明：`audit.close()` 也返回 `HaiResult<void>`；`audit.helper.passwordResetRequest()` 的邮箱详情默认经过业务隐私脱敏。
 
-`audit.init()` 会等待自动建表和仓库就绪才返回成功；DDL 失败保持 `isInitialized=false`，修正数据库后可重试。自定义 JOIN、统计和清理也使用同一就绪屏障；初始化期间关闭会使迟到结果失效。先检查 init 的 HaiResult，再立即记录或查询；audit 不拥有共享 RelDB 的连接，关闭 audit 后再关闭数据库。
+`audit.init()` 会等待自动建表和仓库就绪才返回成功；DDL 失败保持 `isInitialized=false`，修正数据库后可重试。列表、统计和清理也使用同一就绪屏障；初始化期间关闭会使迟到结果失效。先检查 init 的 HaiResult，再立即记录或查询；audit 不拥有共享 RelDB 的连接，关闭 audit 后再关闭数据库。
 
 ## 开发测试
 

package/dist/index.d.ts

@@ -3,7 +3,6 @@ import { StorageFunctions } from '@h-ai/storage';
 import { z } from 'zod';
 import * as _h_ai_core 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';
 
@@ -219,7 +218,7 @@ interface AuditLog extends AuditEventFields {
 /**
  * 审计日志记录（含用户名）
  *
- * 新记录使用事件时身份快照；无快照的历史记录才保留旧的用户表关联展示。
+ * 用户名来自事件时的身份快照；无名称时为 null。
  * @example
  * ```ts
  * import type { AuditLogWithUser } from '@h-ai/audit'
@@ -227,7 +226,7 @@ interface AuditLog extends AuditEventFields {
  * ```
  */
 interface AuditLogWithUser extends AuditLog {
-    /** 操作用户的用户名；用户不存在或系统操作时为 null */
+    /** 事件时的用户名；未捕获到名称时为 null。 */
     username: string | null;
 }
 /**
@@ -476,7 +475,7 @@ interface AuditFunctions {
         tx?: DmlWithTxOperations;
     }) => Promise<HaiResult<void>>;
     /**
-     * 分页查询审计日志列表（含用户名 LEFT JOIN）
+     * 分页查询审计日志列表，用户名来自事件时的身份快照。
      *
      * @param options - 查询过滤与分页选项
      * @returns 成功时返回 PaginatedResult（items/total/page/pageSize）；失败时返回 QUERY_FAILED
@@ -633,17 +632,5 @@ interface AuditAlertReport {
  */
 declare const audit: AuditFunctions;
 
-/**
- * 只读预检或迁移审计字段、保留设置和写入保护；升级前停旧写入并备份。
- * @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, AuditInitConfigSchema, HaiAuditError, audit, migrateAudit };
+export { AUDIT_BACKUP_PREFIX, AuditInitConfigSchema, HaiAuditError, audit };
 export type { AuditActorSnapshot, AuditAlertReport, AuditBackupInfo, AuditBackupOperations, AuditBackupOptions, AuditContext, AuditEventFields, AuditFunctions, AuditHelper, AuditInitConfig, AuditInitConfigInput, AuditLog, AuditLogWithUser, AuditStatItem, CreateAuditLogInput, CrudAuditInput, ListAuditLogsOptions };

package/dist/index.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { core, ok, err } from '@h-ai/core';
-import { reldb, validateIdentifiers, BaseReldbCrudRepository } from '@h-ai/reldb';
+import { validateIdentifiers, BaseReldbCrudRepository, reldb } from '@h-ai/reldb';
 import { createHash } from 'crypto';
 import { AsyncLocalStorage } from 'async_hooks';
 import { Buffer } from 'buffer';
@@ -100,11 +100,11 @@ var AuditInitConfigSchema = z.object({
     /** 额外脱敏的详情字段名，不区分大小写；例如 customerPhone，不要将秘密放进 action/resourceId。 */
     fields: z.array(z.string().trim().min(1).max(256)).max(1e3).default([])
   }).default({ enabled: true, fields: [] }),
-  /** 用户表名，用于 list 查询时 LEFT JOIN 获取用户名 */
+  /** 事件写入时用于捕获用户名的用户表名。 */
   userTable: z.string().default("hai_iam_users"),
-  /** 用户表主键列名，用于 JOIN 条件 */
+  /** 用于查找事件操作者的用户表主键列名。 */
   userIdColumn: z.string().default("id"),
-  /** 用户表用户名列名，用于 SELECT 输出 */
+  /** 用于写入身份快照的用户名列名。 */
   userNameColumn: z.string().default("username")
 });
 var storage = new AsyncLocalStorage();
@@ -129,6 +129,7 @@ function withAuditContext(context, operation) {
 
 // messages/en-US.json
 var en_US_default = {
+  audit_timestampPrecisionRequired: "The audit event timestamp must support millisecond precision",
   audit_eventFieldsInvalid: "Invalid event fields",
   audit_identityMismatch: "Actor snapshot does not match the event identity",
   audit_queryInvalid: "Invalid filters or dates",
@@ -165,6 +166,7 @@ var en_US_default = {
 
 // messages/ja-JP.json
 var ja_JP_default = {
+  audit_timestampPrecisionRequired: "\u76E3\u67FB\u30A4\u30D9\u30F3\u30C8\u306E\u6642\u523B\u5217\u306B\u306F\u30DF\u30EA\u79D2\u7CBE\u5EA6\u304C\u5FC5\u8981\u3067\u3059",
   audit_eventFieldsInvalid: "\u30A4\u30D9\u30F3\u30C8\u9805\u76EE\u304C\u7121\u52B9\u3067\u3059",
   audit_identityMismatch: "\u8EAB\u5143\u30B9\u30CA\u30C3\u30D7\u30B7\u30E7\u30C3\u30C8\u3068\u64CD\u4F5C\u8005\u304C\u4E00\u81F4\u3057\u307E\u305B\u3093",
   audit_queryInvalid: "\u691C\u7D22\u6761\u4EF6\u307E\u305F\u306F\u65E5\u4ED8\u304C\u7121\u52B9\u3067\u3059",
@@ -201,6 +203,7 @@ var ja_JP_default = {
 
 // messages/zh-CN.json
 var zh_CN_default = {
+  audit_timestampPrecisionRequired: "\u5BA1\u8BA1\u4E8B\u4EF6\u65F6\u95F4\u5217\u5FC5\u987B\u652F\u6301\u6BEB\u79D2\u7CBE\u5EA6",
   audit_eventFieldsInvalid: "\u4E8B\u4EF6\u5B57\u6BB5\u65E0\u6548",
   audit_identityMismatch: "\u8EAB\u4EFD\u5FEB\u7167\u4E0E\u64CD\u4F5C\u8005\u4E0D\u4E00\u81F4",
   audit_queryInvalid: "\u7B5B\u9009\u6761\u4EF6\u6216\u65E5\u671F\u65E0\u6548",
@@ -1050,142 +1053,98 @@ function createHelper(logFn) {
     }
   };
 }
-var columns = {
-  category: "VARCHAR(16)",
-  outcome: "VARCHAR(16)",
-  severity: "VARCHAR(16)",
-  request_id: "TEXT",
-  trace_id: "TEXT",
-  scope_id: "TEXT",
-  actor_snapshot: "JSON"
-};
-var triggers = ["hai_audit_protect_update", "hai_audit_protect_delete", "hai_audit_protect_insert"];
-async function existingTriggers(sql) {
-  const result = reldb.config?.type === "sqlite" ? await sql.query("SELECT name FROM sqlite_master WHERE type='trigger' AND tbl_name='hai_audit_logs'") : await sql.query(`SELECT trigger_name AS name FROM information_schema.triggers WHERE trigger_schema=${reldb.config?.type === "mysql" ? "DATABASE()" : "current_schema()"} AND event_object_table='hai_audit_logs'`);
-  return result.success ? ok(result.data.map((row) => row.name)) : result;
+var mysqlLock = "SHA2(CONCAT(DATABASE(), ':hai_audit_policy'), 256)";
+var triggerOperations = [
+  ["hai_audit_protect_update", "UPDATE"],
+  ["hai_audit_protect_delete", "DELETE"],
+  ["hai_audit_protect_insert", "INSERT"]
+];
+async function installTriggers(sql) {
+  const type = reldb.config?.type;
+  const existing = type === "sqlite" ? await sql.query("SELECT name FROM sqlite_master WHERE type='trigger' AND tbl_name='hai_audit_logs'") : await sql.query(`SELECT trigger_name AS name FROM information_schema.triggers WHERE trigger_schema=${type === "mysql" ? "DATABASE()" : "current_schema()"} AND event_object_table='hai_audit_logs'`);
+  if (!existing.success)
+    return existing;
+  const names = new Set(existing.data.map((row) => row.name));
+  const missing = triggerOperations.filter(([name]) => !names.has(name));
+  if (!missing.length)
+    return ok(void 0);
+  const enabled = "COALESCE((SELECT enabled FROM hai_audit_policy WHERE id=1),1)=1";
+  const days = "COALESCE((SELECT min_days FROM hai_audit_policy WHERE id=1),90)";
+  const cutoff = type === "sqlite" ? `CAST((julianday('now')-2440587.5)*86400000 AS INTEGER) - ${days}*86400000` : type === "postgresql" ? `CURRENT_TIMESTAMP - (${days} * INTERVAL '1 day')` : `TIMESTAMPADD(DAY, -${days}, CURRENT_TIMESTAMP(3))`;
+  const existingProtected = `${enabled} AND EXISTS(SELECT 1 FROM hai_audit_logs a WHERE a.id=NEW.id AND a.created_at >= ${cutoff})`;
+  if (type === "postgresql") {
+    const fn = await sql.execute(`CREATE OR REPLACE FUNCTION hai_audit_protect() RETURNS trigger AS $$ BEGIN IF TG_OP='INSERT' THEN IF ${existingProtected} THEN RAISE EXCEPTION 'Audit record is protected by retention policy'; END IF; RETURN NEW; END IF; IF ${enabled} AND OLD.created_at >= ${cutoff} THEN RAISE EXCEPTION 'Audit record is protected by retention policy'; END IF; IF TG_OP='DELETE' THEN RETURN OLD; END IF; RETURN NEW; END; $$ LANGUAGE plpgsql`);
+    if (!fn.success)
+      return fn;
+  }
+  for (const [name, operation] of missing) {
+    const protectedRow = operation === "INSERT" ? existingProtected : `${enabled} AND OLD.created_at >= ${cutoff}`;
+    const prefix = `CREATE TRIGGER ${name} BEFORE ${operation} ON hai_audit_logs`;
+    const statement = type === "sqlite" ? `${prefix} WHEN ${protectedRow} BEGIN SELECT RAISE(ABORT, 'Audit record is protected by retention policy'); END` : type === "postgresql" ? `${prefix} FOR EACH ROW EXECUTE FUNCTION hai_audit_protect()` : `${prefix} FOR EACH ROW BEGIN IF ${protectedRow} THEN SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='Audit record is protected by retention policy'; END IF; END`;
+    const created = type === "mysql" ? await sql.query(statement) : await sql.execute(statement);
+    if (!created.success)
+      return created;
+  }
+  return ok(void 0);
 }
-var steps = [
-  {
-    version: 1,
-    name: "event-context-and-identity",
-    async needed(sql) {
-      const found = await reldb.schemaColumns("hai_audit_logs", sql);
-      return found.success ? ok(found.data.length > 0 && Object.keys(columns).some((name) => !found.data.includes(name))) : found;
-    },
-    async apply(sql) {
-      const found = await reldb.schemaColumns("hai_audit_logs", sql);
-      if (!found.success)
-        return found;
-      for (const [name, definition] of Object.entries(columns)) {
-        if (found.data.includes(name))
-          continue;
-        const added = await sql.execute(`ALTER TABLE hai_audit_logs ADD COLUMN ${name} ${definition}`);
-        if (!added.success)
-          return added;
-      }
-      return ok(void 0);
-    }
-  },
-  {
-    version: 2,
-    name: "persistent-retention-policy",
-    async needed(sql) {
-      const found = await reldb.schemaColumns("hai_audit_policy", sql);
-      if (!found.success || found.data.length === 0) {
-        return found.success ? ok(true) : found;
-      }
-      const row = await sql.get("SELECT id FROM hai_audit_policy WHERE id=1");
-      return row.success ? ok(!row.data) : row;
-    },
-    async apply(sql) {
-      const created = await sql.execute("CREATE TABLE IF NOT EXISTS hai_audit_policy (id INTEGER PRIMARY KEY, enabled INTEGER NOT NULL, min_days INTEGER NOT NULL)");
-      if (!created.success)
-        return created;
-      return sql.execute(reldb.config?.type === "mysql" ? "INSERT IGNORE INTO hai_audit_policy (id, enabled, min_days) VALUES (1, 0, 90)" : "INSERT INTO hai_audit_policy (id, enabled, min_days) VALUES (1, 0, 90) ON CONFLICT(id) DO NOTHING");
-    }
-  },
-  {
-    version: 3,
-    name: "retention-write-guards",
-    async needed(sql) {
-      const table2 = await reldb.schemaColumns("hai_audit_logs", sql);
-      if (!table2.success || !table2.data.length) {
-        return table2.success ? ok(false) : table2;
-      }
-      const found = await existingTriggers(sql);
-      return found.success ? ok(triggers.some((name) => !found.data.includes(name))) : found;
-    },
-    async apply(sql) {
-      const found = await existingTriggers(sql);
-      if (!found.success)
-        return found;
-      const enabled = "COALESCE((SELECT enabled FROM hai_audit_policy WHERE id=1),1)=1";
-      const days = "COALESCE((SELECT min_days FROM hai_audit_policy WHERE id=1),90)";
-      const cutoff = reldb.config?.type === "sqlite" ? `CAST((julianday('now')-2440587.5)*86400000 AS INTEGER) - ${days}*86400000` : reldb.config?.type === "postgresql" ? `CURRENT_TIMESTAMP - (${days} * INTERVAL '1 day')` : `TIMESTAMPADD(DAY, -${days}, CURRENT_TIMESTAMP(3))`;
-      const existingProtected = `${enabled} AND EXISTS(SELECT 1 FROM hai_audit_logs a WHERE a.id=NEW.id AND a.created_at >= ${cutoff})`;
-      if (reldb.config?.type === "postgresql") {
-        const fn = await sql.execute(`CREATE OR REPLACE FUNCTION hai_audit_protect() RETURNS trigger AS $$ BEGIN IF TG_OP='INSERT' THEN IF ${existingProtected} THEN RAISE EXCEPTION 'Audit record is protected by retention policy'; END IF; RETURN NEW; END IF; IF ${enabled} AND OLD.created_at >= ${cutoff} THEN RAISE EXCEPTION 'Audit record is protected by retention policy'; END IF; IF TG_OP='DELETE' THEN RETURN OLD; END IF; RETURN NEW; END; $$ LANGUAGE plpgsql`);
-        if (!fn.success)
-          return fn;
-      }
-      for (const [index, operation] of ["UPDATE", "DELETE", "INSERT"].entries()) {
-        const name = triggers[index];
-        if (found.data.includes(name))
-          continue;
-        const protectedRow = operation === "INSERT" ? existingProtected : `${enabled} AND OLD.created_at >= ${cutoff}`;
-        const statement = reldb.config?.type === "sqlite" ? `CREATE TRIGGER ${name} BEFORE ${operation} ON hai_audit_logs WHEN ${protectedRow} BEGIN SELECT RAISE(ABORT, 'Audit record is protected by retention policy'); END` : reldb.config?.type === "postgresql" ? `CREATE TRIGGER ${name} BEFORE ${operation} ON hai_audit_logs FOR EACH ROW EXECUTE FUNCTION hai_audit_protect()` : `CREATE TRIGGER ${name} BEFORE ${operation} ON hai_audit_logs FOR EACH ROW BEGIN IF ${protectedRow} THEN SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='Audit record is protected by retention policy'; END IF; END`;
-        const created = reldb.config?.type === "mysql" ? await sql.query(statement) : await sql.execute(statement);
-        if (!created.success)
-          return created;
-      }
-      return ok(void 0);
-    }
-  },
-  {
-    version: 4,
-    name: "millisecond-event-time",
-    async needed(sql) {
-      if (reldb.config?.type !== "mysql")
-        return ok(false);
-      const column = await sql.get("SELECT DATETIME_PRECISION AS fractional_digits FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name=? AND column_name=?", ["hai_audit_logs", "created_at"]);
-      return column.success ? ok(Boolean(column.data && Number(column.data.fractional_digits ?? 0) < 3)) : column;
-    },
-    async apply(sql) {
-      const changed = await sql.execute("ALTER TABLE hai_audit_logs MODIFY COLUMN created_at DATETIME(3)");
-      return changed.success ? ok(void 0) : changed;
+async function installTimeIndex(sql) {
+  if (reldb.config?.type !== "mysql")
+    return sql.execute("CREATE INDEX IF NOT EXISTS hai_audit_event_time_idx ON hai_audit_logs (created_at)");
+  const index = await sql.get("SELECT index_name FROM information_schema.statistics WHERE table_schema=DATABASE() AND table_name=? AND index_name=? LIMIT 1", ["hai_audit_logs", "hai_audit_event_time_idx"]);
+  if (!index.success)
+    return index;
+  return index.data ? ok(void 0) : sql.execute("CREATE INDEX hai_audit_event_time_idx ON hai_audit_logs (created_at)");
+}
+async function initializeAuditStorage() {
+  const policy = await reldb.sql.execute("CREATE TABLE IF NOT EXISTS hai_audit_policy (id INTEGER PRIMARY KEY, enabled INTEGER NOT NULL, min_days INTEGER NOT NULL)");
+  if (!policy.success)
+    return policy;
+  const claims = await reldb.sql.execute("CREATE TABLE IF NOT EXISTS hai_audit_alert_claims (id VARCHAR(64) PRIMARY KEY, rule_id VARCHAR(64) NOT NULL, target_id VARCHAR(64) NOT NULL, window_start BIGINT NOT NULL, status VARCHAR(16) NOT NULL, queue_id VARCHAR(64), error_code VARCHAR(128))");
+  if (!claims.success)
+    return claims;
+  const mysql = reldb.config?.type === "mysql";
+  const seeded = await reldb.sql.execute(mysql ? "INSERT INTO hai_audit_policy (id, enabled, min_days) VALUES (1, 0, 90) ON DUPLICATE KEY UPDATE id=id" : "INSERT INTO hai_audit_policy (id, enabled, min_days) VALUES (1, 0, 90) ON CONFLICT(id) DO NOTHING");
+  if (!seeded.success)
+    return seeded;
+  const started = await reldb.tx.begin();
+  if (!started.success)
+    return started;
+  const tx = started.data;
+  let namedLock = false;
+  try {
+    if (mysql) {
+      const lock = await tx.get(`SELECT GET_LOCK(${mysqlLock}, 30) AS acquired`);
+      if (!lock.success)
+        return lock;
+      if (Number(lock.data?.acquired) !== 1)
+        return err(HaiAuditError.CONFIG_ERROR, auditM("audit_retentionPolicyFailed"));
+      namedLock = true;
+    } else {
+      const lock = await tx.execute("UPDATE hai_audit_policy SET id=id WHERE id=1");
+      if (!lock.success)
+        return lock;
     }
-  },
-  {
-    version: 5,
-    name: "alert-notification-claims",
-    async needed(sql) {
-      const found = await reldb.schemaColumns("hai_audit_alert_claims", sql);
-      return found.success ? ok(found.data.length === 0) : found;
-    },
-    async apply(sql) {
-      const created = await sql.execute("CREATE TABLE IF NOT EXISTS hai_audit_alert_claims (id VARCHAR(64) PRIMARY KEY, rule_id VARCHAR(64) NOT NULL, target_id VARCHAR(64) NOT NULL, window_start BIGINT NOT NULL, status VARCHAR(16) NOT NULL, queue_id VARCHAR(64), error_code VARCHAR(128))");
-      return created.success ? ok(void 0) : created;
-    }
-  },
-  {
-    version: 6,
-    name: "event-time-index",
-    async needed(sql) {
-      const table2 = await reldb.schemaColumns("hai_audit_logs", sql);
-      if (!table2.success || !table2.data.length) {
-        return table2.success ? ok(false) : table2;
-      }
-      const found = reldb.config?.type === "sqlite" ? await sql.get("SELECT name FROM sqlite_master WHERE type='index' AND name='hai_audit_event_time_idx'") : reldb.config?.type === "postgresql" ? await sql.get("SELECT indexname FROM pg_indexes WHERE schemaname=current_schema() AND tablename='hai_audit_logs' AND indexname='hai_audit_event_time_idx'") : await sql.get("SELECT index_name FROM information_schema.statistics WHERE table_schema=DATABASE() AND table_name='hai_audit_logs' AND index_name='hai_audit_event_time_idx' LIMIT 1");
-      return found.success ? ok(!found.data) : found;
-    },
-    async apply(sql) {
-      const created = await sql.execute("CREATE INDEX hai_audit_event_time_idx ON hai_audit_logs (created_at)");
-      return created.success ? ok(void 0) : created;
+    const retained = await auditRetentionDays(tx);
+    if (!retained.success)
+      return retained;
+    const triggers = await installTriggers(tx);
+    if (!triggers.success)
+      return triggers;
+    const index = await installTimeIndex(tx);
+    if (!index.success)
+      return index;
+    if (namedLock) {
+      const released = await tx.get(`SELECT RELEASE_LOCK(${mysqlLock})`);
+      if (!released.success)
+        return released;
+      namedLock = false;
     }
+    return await tx.commit();
+  } finally {
+    if (namedLock)
+      await tx.get(`SELECT RELEASE_LOCK(${mysqlLock})`);
+    await tx.rollback();
   }
-];
-function migrateAudit(options = {}) {
-  return reldb.migrateSchema("audit", steps, options);
 }
 async function configureAuditRetention(policy) {
   if (!policy)
@@ -1196,12 +1155,14 @@ async function configureAuditRetention(policy) {
   ]);
   return result.success && result.data.changes === 1 ? ok(void 0) : err(HaiAuditError.CONFIG_ERROR, auditM("audit_retentionPolicyFailed"), result.success ? void 0 : result.error);
 }
-async function auditRetentionDays() {
-  const result = await reldb.sql.get("SELECT enabled, min_days FROM hai_audit_policy WHERE id=1");
+async function auditRetentionDays(sql = reldb.sql) {
+  const result = await sql.get("SELECT enabled, min_days FROM hai_audit_policy WHERE id=1");
   if (!result.success || !result.data || ![0, 1].includes(Number(result.data.enabled)) || !Number.isInteger(Number(result.data.min_days)) || Number(result.data.min_days) < 1)
-    return err(HaiAuditError.CLEANUP_FAILED, auditM("audit_retentionPolicyFailed"));
+    return err(HaiAuditError.CLEANUP_FAILED, auditM("audit_retentionPolicyFailed"), result.success ? void 0 : result.error);
   return ok(Number(result.data.enabled) === 1 ? Number(result.data.min_days) : 0);
 }
+
+// src/audit-repository-log.ts
 var logger4 = core.logger.child({ module: "audit", scope: "repository" });
 var AUDIT_TABLE = "hai_audit_logs";
 function normalizeAuditLog(row) {
@@ -1219,14 +1180,18 @@ function normalizeAuditLog(row) {
 var AuditLogRepository = class extends BaseReldbCrudRepository {
   repoConfig;
   isSqlite;
+  mysqlTable;
+  readiness;
   /**
    * @param config - 仓库配置（用户表映射）
    */
   constructor(config) {
+    const mysql = reldb.config?.type === "mysql";
     super(reldb, {
       table: AUDIT_TABLE,
       idColumn: "id",
       generateId: () => core.id.withPrefix("audit_"),
+      createTableIfNotExists: !mysql,
       fields: [
         {
           fieldName: "id",
@@ -1360,6 +1325,20 @@ var AuditLogRepository = class extends BaseReldbCrudRepository {
     });
     this.repoConfig = config;
     this.isSqlite = this.db.config?.type === "sqlite";
+    if (mysql) {
+      this.mysqlTable = this.db.ddl.raw(`CREATE TABLE IF NOT EXISTS ${AUDIT_TABLE} (
+        id VARCHAR(255) NOT NULL PRIMARY KEY, user_id VARCHAR(255), action VARCHAR(255) NOT NULL,
+        resource VARCHAR(255) NOT NULL, resource_id VARCHAR(255), details JSON, ip_address VARCHAR(255),
+        user_agent VARCHAR(255), category VARCHAR(255), outcome VARCHAR(255), severity VARCHAR(255),
+        request_id VARCHAR(255), trace_id VARCHAR(255), scope_id VARCHAR(255), actor_snapshot JSON,
+        created_at DATETIME(3)
+      )`);
+    }
+    this.readiness = this.validateSchema();
+  }
+  async ensureReady() {
+    const mysql = await this.mysqlTable;
+    return mysql ?? super.ensureReady();
   }
   /**
    * 等待基类完成建表及字段校验；init和自定义SQL共享此屏障，失败不发布仓库。
@@ -1367,7 +1346,16 @@ var AuditLogRepository = class extends BaseReldbCrudRepository {
    * @example const ready = await repository.ready(); if (!ready.success) return ready
    */
   ready() {
-    return this.ensureReady();
+    return this.readiness;
+  }
+  async validateSchema() {
+    const schema = await this.ensureSchema();
+    if (!schema.success || !this.mysqlTable)
+      return schema;
+    const column = await this.db.sql.get("SELECT DATETIME_PRECISION AS digits FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name=? AND column_name=?", [AUDIT_TABLE, "created_at"]);
+    if (!column.success)
+      return column;
+    return Number(column.data?.digits) >= 3 ? ok(void 0) : err(HaiAuditError.CONFIG_ERROR, auditM("audit_timestampPrecisionRequired"));
   }
   /**
    * 将 Date 转为适合当前数据库类型的 SQL 参数
@@ -1505,7 +1493,7 @@ var AuditLogRepository = class extends BaseReldbCrudRepository {
     }
   }
   /**
-   * 分页查询日志列表（含用户名 LEFT JOIN）
+   * 分页查询日志列表，用户名来自事件时的身份快照。
    *
    * @param options - 过滤条件与分页参数
    * @returns 成功时返回 PaginatedResult（items/total/page/pageSize）；失败时返回 QUERY_FAILED
@@ -1516,7 +1504,6 @@ var AuditLogRepository = class extends BaseReldbCrudRepository {
       return ready;
     logger4.debug("Querying audit logs", { userId: options.userId, action: options.action, resource: options.resource });
     const { conditions, params } = this.filters(options);
-    const { userTable, userIdColumn, userNameColumn } = this.repoConfig;
     const quote = this.db.config?.type === "mysql" ? "`" : '"';
     const identifier = (name) => `${quote}${name.replaceAll(quote, quote + quote)}${quote}`;
     const sortColumns = {
@@ -1543,9 +1530,8 @@ var AuditLogRepository = class extends BaseReldbCrudRepository {
         sql: `SELECT a.id, a.user_id AS ${identifier("userId")}, a.action, a.resource, a.resource_id AS ${identifier("resourceId")},
                 a.details, a.ip_address AS ${identifier("ipAddress")}, a.user_agent AS ${identifier("userAgent")},
                 a.created_at AS ${identifier("createdAt")}, a.category, a.outcome, a.severity,
-                a.request_id AS ${identifier("requestId")}, a.trace_id AS ${identifier("traceId")}, a.scope_id AS ${identifier("scopeId")}, a.actor_snapshot AS ${identifier("actorSnapshot")}, u.${identifier(userNameColumn)} AS username
+                a.request_id AS ${identifier("requestId")}, a.trace_id AS ${identifier("traceId")}, a.scope_id AS ${identifier("scopeId")}, a.actor_snapshot AS ${identifier("actorSnapshot")}
          FROM ${AUDIT_TABLE} a
-         LEFT JOIN ${identifier(userTable)} u ON a.user_id = u.${identifier(userIdColumn)}
          ${whereClause}
          ORDER BY a.${sortColumns[sortBy]} ${direction.toUpperCase()}, a.id ${direction.toUpperCase()}`,
         params,
@@ -1564,10 +1550,10 @@ var AuditLogRepository = class extends BaseReldbCrudRepository {
       }
       return ok({
         ...result.data,
-        items: result.data.items.map((row) => ({
-          ...normalizeAuditLog(row),
-          username: readAuditActor(row.actorSnapshot)?.username ?? (row.actorSnapshot == null ? row.username ?? null : null)
-        }))
+        items: result.data.items.map((row) => {
+          const record = normalizeAuditLog(row);
+          return { ...record, username: record.actorSnapshot?.username ?? null };
+        })
       });
     } catch (error) {
       logger4.error("Failed to query audit logs", { error });
@@ -1869,9 +1855,6 @@ var audit = {
           identifierResult.error
         );
       }
-      const migrated = await migrateAudit();
-      if (!migrated.success)
-        return migrated;
       const candidate = new AuditLogRepository({
         userTable: parsed.userTable,
         userIdColumn: parsed.userIdColumn,
@@ -1883,7 +1866,7 @@ var audit = {
           params: { error: ready.error.message }
         }), ready.error);
       }
-      const protection = await migrateAudit();
+      const protection = await initializeAuditStorage();
       if (!protection.success)
         return protection;
       const configured = await configureAuditRetention(parsed.retention);
@@ -1947,7 +1930,7 @@ var audit = {
     return written.success ? ok(void 0) : written;
   },
   /**
-   * 分页查询审计日志列表（含用户名 LEFT JOIN）
+   * 分页查询审计日志列表，用户名来自事件时的身份快照。
    *
    * @param options - 过滤条件与分页参数
    * @returns 成功时返回 PaginatedResult（items/total/page/pageSize）；未初始化时返回 NOT_INITIALIZED
@@ -2111,6 +2094,6 @@ var audit = {
   }
 };
 
-export { AUDIT_BACKUP_PREFIX, AuditInitConfigSchema, HaiAuditError, audit, migrateAudit };
+export { AUDIT_BACKUP_PREFIX, AuditInitConfigSchema, HaiAuditError, audit };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map