ambient 事务句柄跨数据源泄漏:凡在事务中执行的被审计写入,合规审计行全部静默丢失(#5226 的真实根因)

[os-zhuang]

从 #5226 的实施中证伪原前提后定位到的真实缺陷,严重度高于原单。由 PR #5350 的 dev 实测发现,落点在 engine 车道、超出该单声明文件面,故独立立单。未认领。

先说 #5226 的前提被证伪了

#5226 断言「dev --fresh 上 sys_audit_log 表根本没建」。实测(origin/main 1792384)不成立:

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

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

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

原单列出的两个待查方向双双被排除:AuditPlugin 确实通过 manifest 注册进 schema sync;dev 组合也没有缺任何 service/对象包。

真实缺陷

同一次 boot 的完整计数:sys_audit_log insert 尝试 52 次、成功 50 次、失败 2 次,且失败的两次堆栈全部带 knex 的 trxClient.query 帧,成功的没有一次带。

机制:

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。origin/main 上该处注释自陈「Explicit wins; ambient is the safety net」—— 漏的正是这张网:

const tx = execCtx?.transaction !== undefined
  ? execCtx.transaction
  : this.txStore.getStore()?.transaction;   // ← 不问这个 tx 属于哪个数据源

影响面(比 #5226 描述的宽得多)

不限于元数据写。 用 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 亦然)。业务写本身成功、接口 200、数据在盘上,只有「谁做的」那一行没了,且无人重试。

受影响的是每一个 lifecycle class 为 audit / telemetry / event 的对象,不止审计。判别式是数据源分流,不是 plugin 作者身份;反证:sys_comment 没有 lifecycle class、留在主库,从不失败。

⚠️ 需要维护者拍板的语义问题(已挂 needs-user-decision)

问题:当 ambient 事务内的一次写入解析到与开启该事务的数据源不同的数据源时,引擎应当怎么做?今天它静默地把外来事务句柄穿过去、在错误的连接上执行 —— 那就是本缺陷。任何修法都必须选定语义,而这个选择改变的是 ADR-0067 对所有多数据源部署的事务契约,不只是审计。

以下四选项与推荐由 PR #5350 的 dev 给出。PM 原先在本单写过一版三选项分析,已被这一版取代 —— 它多出选项 D,并指出 C 在当前 driver 契约下不可交付,比 PM 那版准确。

• A —— 同源校验后自动提交:buildDriverOptions 仅在解析到的 driver 就是该事务的属主时才穿入 ambient trx(需要 txStore 记录属主 driver,对引擎事务核心是一处小增补)。跨数据源写入在事务之外执行。代价:外层事务回滚时审计行仍然留下 —— 一条描述「从未发生的写入」的孤儿账目。
• B —— 同源校验后拒绝:跨数据源写入抛具名错误,强制调用方显式选择。代价:把今天的静默丢数据换成硬失败,而这些路径在单数据源部署上是好的;每一个被审计的事务写入都会中断,直到逐个调用点更新。
• C —— 按数据源开嵌套事务:在第二个 driver 上开伴随事务,一起提交/回滚。代价:需要 driver 并不具备的两阶段提交语义;提交中途失败会让两个存储互相矛盾 —— 用一个新的持久性风险替换当前这个。
• D —— 取消分流:让带 lifecycle class 的对象留在主数据源(dev 里 OS_TELEMETRY_DB 默认关)。代价:放弃 ADR-0057 §3.6 的增长隔离目标;是掩盖而非修复引擎缺陷,任何把某个对象路由到第二数据源的部署照样会被咬。

推荐:A,并把孤儿行的后果写进代码 + 修订 ADR。

项目长远合理性:A 在生产者处修复 —— 引擎的事务路由,错误假设就住在那里 —— 而不是教审计插件绕开它;消费端的绕行正是 PD#12 禁止的 ?? 回退形态,而且会把其它所有跨数据源写入继续留在坏状态。它也保住了 ADR-0057 §3.6 的增长隔离,而 D 把它丢掉。B 与 C 在原子性上更纯粹,但在当前 driver 契约下都不可交付:C 需要 driver 没有的两阶段提交,B 把静默丢失变成一批今天健康的路径集体启动即失败。对一个只追加的合规账本,多记(A 的孤儿行)是正确的失败方向 —— 一条对应已回滚写入的审计行是可对账的麻烦,而一条已提交写入却缺失的审计行是不可恢复的合规空洞,那正是今天在发的版本。

防 AI 写元数据犯错:A 是唯一让该不变量结构化且可检查的选项 —— 引擎拒绝把不属于某 driver 的事务句柄交给它,于是任何插件作者(人或 AI)都无法靠写一个普通钩子重现这个缺陷,也不需要知道数据源分流的存在才能写对。随后必须把孤儿行语义写进 ADR-0067 并按 PD#13 锚定,好让下一个读者知道自己站在哪条裁决上。

由于 A 仍然改变了一条已记录 ADR 的事务语义,需要维护者拍板 + ADR 修订。

与其它单的关系

• objectstack dev --fresh 上 sys_audit_log 表不存在 —— 每次元数据写入都以 ERROR + 「Audit write failed」告终,审计轨迹静默丢失 #5226:原单的第二个缺陷(日志级别应为 error 而非 WARN)已由 PR fix(plugin-audit): 审计行写失败升为 error 并只报一次 (#5226 之二);#5226 主缺陷前提被证伪 #5350 落地(PM 已把该 PR 的 Fixes 改为 Refs,不会误关)。原单主缺陷即本单。
• plugin-audit never provisions sys_audit_log / sys_activity — Setup "System Overview" audit widgets silently render zeros #4887:同形状的「在另一个 store 里」误诊先例。
• [automation/approvals] 进程重启后审批决策静默失效:挂起 flow run 仍只存内存(#1518 标记 COMPLETED 但 17.0.0-rc.1 未生效),approve 落库却永不推进且零报错 #4420:同类「写入落空只留没人读的日志」。
• ADR-0057 §3.6(lifecycle 分流)、ADR-0067 D2(ambient 事务)。

验收建议

• 回归测试:在主库事务内写一个被审计对象,断言审计行确实落在 telemetry 数据源上(⛔ 不要断言「没有报错」—— 当前缺陷下不报错的路径也是错的)。
• 反证测试:sys_comment(无 lifecycle class)路径行为不变。
• 覆盖普通业务对象 + POST /api/v1/batch transaction: true,不只元数据写。

顺带(留给接手 engine 的人)

os dev 一次 boot 打印了两次 Schema sync complete {synced:94, skipped:2, total:96} —— 对 96 个对象跑了两遍完整同步(ObjectQLPlugin.start Phase 1 与 Phase 3)。非用户可见,本单不处理,记在这里只因为它正好在引擎修复要读的那条代码路径上。

[os-zhuang]

来自 #4619 engine 半边(PR #5724)的实测复证 —— 本单前提成立,并且本单推荐的方案 A 所需的那处前置已经在 #5724 里落地了。

一、独立复证:句柄确实跨数据源穿了过去

#5724 给跨数据源事务写了新测试,写用例时撞上同一现象。我原本按契约 TSDoc 的说法(「路由到别处的对象在事务外写入」)断言收到的是 undefined,实测转红:

AssertionError: expected { __trx: 'primary' } to be undefined

复现最小面(纯 in-memory driver 双数据源,不依赖 lifecycle 分流、不依赖 sqlite):

• primary 为默认驱动;setDatasourceMapping 把 ledger 路由到 ledger_db
• 在 engine.transaction() 内 insert('ledger', …)
• ledger_db 的 driver 收到的 options.transaction 是 primary 的句柄

即本单第 4 步与判别式(数据源分流,不是 plugin 作者身份)在普通业务对象上同样成立,与审计、与 lifecycle class 都无关 —— 只要有任何一条 mapping 规则把对象路由走。这是本单「影响面比 #5226 描述的宽得多」那节的一个独立佐证。

顺带修正一处措辞:契约 TSDoc 说这类写入「在事务外执行」,实测比这更糟 —— 它是带着另一个连接的事务对象执行的。in-memory double 对此无感,真 SQL driver 的 .transacting(trx) 会把语句发到错误的库,也就是本单实测到的 no such table。

二、方案 A 的前置已就绪

本单推荐方案 A 时写道:

buildDriverOptions 仅在解析到的 driver 就是该事务的属主时才穿入 ambient trx(需要 txStore 记录属主 driver,对引擎事务核心是一处小增补)。

#5724 已经加了这处增补 —— txStore 条目上的 TransactionScope 记录了开启该事务的 driver 实例(按实例身份比对,不是按名字,因为 registerDriver 存在同名不同实例的碰撞分支)。所以 A 落地时不必再动这块地基,buildDriverOptions 里读 this.txStore.getStore()?.scope?.driver 与解析到的 driver 比一下即可。

⚠️ 边界两条,免得接手的人踩:

1. scope 是可选的。沙箱的离散 beginTransaction/commit/rollback 三件套跨 setImmediate 显式穿句柄、根本不走 txStore,那条路径上 scope 为 undefined;execCtx.transaction 显式传入的那一支同理。A 的同源校验要想覆盖它们,得另想办法(或明确接受不覆盖)。
2. fix(objectql): make transaction() 的两条既声明 caveat 可被观测 (#4619) #5724 只报告不拦截 —— 它在事务内写入路由到非属主 driver 时打一条 error(每事务每数据源一次),句柄照旧穿过去。这是刻意的:拦截会改掉 ADR-0119 D1 已声明的语义,正是本单挂 needs-user-decision 的那个裁决,fix(objectql): make transaction() 的两条既声明 caveat 可被观测 (#4619) #5724 不预判它。

所以两单不冲突:#5724 让缺陷有声音,本单决定行为怎么改。本单落地后,#5724 那条 error 大概率要跟着调整语义(A 之下它会变成「已按同源校验放到事务外执行」的提示,而不是「静默穿错连接」的警报),届时可一并改。

三、已钉住的现状测试

packages/objectql/src/engine-transaction-observability.test.ts 里把当前行为如实钉成 toEqual({ __trx: 'primary' }),并注明是「观测到,非认可、非本 PR 引入」。这样本单动手时那条断言会转红,把改动引到看这条测试的人面前 —— 而不是让它在一个当初只是猜测的 toBeUndefined() 底下悄悄变过去。

本单未认领,我没有改它的 assignee。

---

Generated by Claude Code

[claude]

裁决(2026-08-06):方案 (i)——引擎级同源校验 carve-out。

buildDriverOptions 做事务属主比对(#5724 的 TransactionScope 属主记录已就绪):lifecycle 路由的系统写(审计/telemetry/event)目标数据源 ≠ ambient 事务属主时,自动放到事务外执行——审计行真正落盘,插件作者零负担;孤儿行语义(业务回滚后审计行保留)写进 ADR-0067/0119 修订——对只追加的合规账本,「多记孤儿行」优于「少记已提交写入」。业务写维持 #5696 已批的「跨驱动响亮拒绝」通用契约,两者在同一份 ADR 修订里调和。

⚠️ 硬约束:与 #5696 同批同 PR 序实施(同一条 buildDriverOptions/transaction() 缝)——单独先落 #5696 会「响亮化但不修复」(审计 hook 的 try/catch 把拒绝吃成日志,合规行照丢);派发 #5696 时把本裁决带进派发令。#5724 dev 提示的那条 error 语义同步调整。量级 M。

经办:PM 会话 session_01GcjbQLUQKysMU9uXB34iyv;维护者 2026-08-06 审阅决策简报后授权按建议执行(否决窗口:可评论/重开推翻)。

---

Generated by Claude Code