fix(plugin-audit): 审计行写失败升为 error 并只报一次 (#5226 之二);#5226 主缺陷前提被证伪

[os-zhuang]

Refs #5226

ℹ️ PM 复核已把 Fixes 改为 Refs(2026-08-05)。 本 PR 只落地 #5226 的第二个缺陷(日志级别)。issue 陈述的主缺陷「表没建」已被本 PR 的 dev 证伪(表在 dev.telemetry.db 里,50 行),真实根因是跨数据源 ambient 事务泄漏,落点在 engine 车道,已另立单。#5226 不随本 PR 关闭。

前提证伪:表是建了的

issue 断言「表在这个全新数据库里根本没被创建」。在 origin/main(1792384)上跑真实复现,这一条不成立。

pnpm dev:showcase -- --fresh -p 39726 --seed-admin --log-level debug

boot 日志里 provisioning 明确成功:

AuditPlugin: system tables provisioned — sys_audit_log→telemetry, sys_activity→telemetry,
                                         sys_comment→com.objectstack.driver.sql

直接查两个 SQLite 文件:

文件	是否有 sys_audit_log	行数
dev.db(主库)	否	—
dev.telemetry.db	是	50

sys_audit_log 的 lifecycle.class: 'audit' 被 ADR-0057 §3.6 路由到专用 telemetry 数据源,os dev 默认以兄弟文件形式提供一个。表建好了,50 行审计也确实落盘了。#4887 早就记录过这个「在另一个 store 里」的误诊形状。

真实根因:ambient 事务跨数据源泄漏

同一次 boot 的完整计数(登录后做一次 PUT /api/v1/meta/api/issue5226probe):

• sys_audit_log insert 尝试 52 次
• 成功 50 次
• 失败 2 次 —— 且这 2 次的堆栈全部带 knex 的 trxClient.query / execution/transaction.js 帧

失败的两条正是 issue 贴出的那两条(sys_metadata、sys_metadata_history)。机制:

1. protocol.saveMetaItem 在主数据源上开启事务;
2. 事务内写 sys_metadata 触发 afterInsert 钩子 → 审计写;
3. getDriver('sys_audit_log') 正确解析到 telemetry 驱动;
4. 但 buildDriverOptions(packages/objectql/src/engine.ts:1609)把 txStore 里的 ambient 事务句柄无条件塞进 driver options —— 那个句柄属于主库连接;
5. knex 的 .transacting(trx) 于是把语句发到主库执行,而主库没有这张表 → no such table: sys_audit_log。

即 ADR-0067 D2「加入已开启的 ambient 事务」被应用时没有校验该事务是否属于同一个 driver。

影响面比 issue 描述的宽

不限于元数据写。用 POST /api/v1/batch + transaction: true 写一条普通业务记录 showcase_category,同样丢审计行:

Audit write failed {"object":"showcase_category"}
Audit write failed {"object":"sys_metadata"}
Audit write failed {"object":"sys_metadata_history"}

结论:凡是在事务中执行的被审计写入,其合规审计行都会丢失 —— 只要该部署启用了 lifecycle 数据源分流(os dev 默认开;生产上设了 OS_TELEMETRY_DB 亦然)。这不是 plugin-audit 的问题,也不是「plugin 声明的对象没进 schema sync」:所有 plugin 声明对象都正常建表,sys_comment 因为没有 lifecycle class 留在主库、从不失败。受影响的是每一个 lifecycle class 为 audit/telemetry/event 的对象。

本 PR 做了什么(只有第二个缺陷)

真实修复点在 packages/objectql/src/engine.ts 的事务管道 —— 属 engine 车道,在本单声明的文件面之外,且涉及一个 issue 未给出结论的架构取舍(跨数据源写入在外层事务回滚时应当:一起回滚?自动提交并接受孤儿审计行?还是直接拒绝?)。按借道声明与「不猜测公共契约」的规矩,此处停手并上报 needs_decision,不在本 PR 里动它。

本 PR 只落地 issue 的第二个论点 —— 日志级别,这一条完全在本单车道内且判据明确:

按 AGENTS.md「Degradation log levels」的那一个问题:降级之后系统从外面看是否仍然正常,而它声称已持久化的东西没落地?被审计的那次写入本身成功、数据在盘上、接口 200,只有记录「谁做的」的审计行没了,且无人重试 —— 是 durability/data-consistency 类,应为 error。

• WARN Audit write failed → error,并在第一行同时给出后果(合规轨迹已不完整、系统会继续显得健康)与修复方向(表被 ADR-0057 分流到 telemetry;"no such table" 通常意味着写入执行在了与建表处不同的数据源上;OS_TELEMETRY_DB=0 可收回分流)。
• 全进程只报一次。审计写发生在每一次数据变更上,系统性原因会每写一次报一条 —— 那正是当初让 [automation/approvals] 进程重启后审批决策静默失效:挂起 flow run 仍只存内存(#1518 标记 COMPLETED 但 17.0.0-rc.1 未生效),approve 落库却永不推进且零报错 #4420 的 warn 无人阅读的反射。后续失败降 debug,细节仍可取回。
• 写入点提取为具名 persistAuditTrailRow,登记进 DURABILITY_CRITICAL_CALLEES,由 pnpm check:durability-log-level 把级别焊死。

验证

pnpm --filter @objectstack/plugin-audit test       → 7 files, 112 tests passed
pnpm --filter @objectstack/plugin-audit typecheck  → clean
node scripts/check-durability-degradation-log-level.mjs
  → 24 durability-critical catch seam(s), all loud or rethrowing

反向验证(方向为事前预测的 before-red / after-green):

• 把 reportAuditWriteFailure 改回 warn → 门禁按预期变红,精确点名 audit-writers.ts:729 guards persistAuditTrailRow()。
• 把 catch 体还原成改动前的那行 logger.warn('Audit write failed', …) → 新增 4 个用例中的 3 个变红(Tests 3 failed | 109 passed)。

诚实地说明第 4 个:never lets a logging failure break the audited write 改动前后都绿 —— 旧代码同样把日志调用包在 try 里。它固化的是一条本来就成立的性质,不是本次改动带来的新覆盖,保留是为了防止将来重构时丢掉。

遗留

主缺陷(跨数据源 ambient 事务)未修,#5226 需重新分诊并转派 engine 车道。

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01FTszibd6C8sUCCZnM4VcrL

---

Generated by Claude Code

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 5, 2026 12:19am

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/plugin-audit.

4 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/deployment/cli.mdx (via @objectstack/plugin-audit)
• content/docs/deployment/production-readiness.mdx (via @objectstack/plugin-audit)
• content/docs/plugins/packages.mdx (via @objectstack/plugin-audit)
• content/docs/releases/implementation-status.mdx (via @objectstack/plugin-audit)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.