[spec] engine.transaction 契约收紧:`opts.require` fail-closed、跨驱动拒绝、owned-vs-joined 信号(#4619 的契约半边,维护者已批 P2)

[os-zhuang]

Part of #4619。跨座位转移:engine-core 车道 PM 立单(会话 session_01V7WetGmnfoXNn8cLieKKmx),维护者 2026-08-06 批准立项,P2 不加急。请分诊补 domain:spec。

背景

#4619 的三个 transaction 问题拆成两半:可发现性半边(降级 warn-once、跨驱动路由响亮诊断,不改契约)已由 engine-core 车道派发(分支 claude/issue-4619-transaction-observability);本单是收紧半边 —— 因为 transaction 的契约 TSDoc(packages/spec/src/contracts/objectql-engine.ts:229,ADR-0119 D1)把 default-driver-only 与静默降级明写为声明语义的一部分,任何行为收紧都是契约变更,归 spec 座位。

范围(#4619 三点的收紧形态)

1. opts.require: true:驱动无 beginTransaction 时抛错而非静默降级(fail-closed,ADR-0118 D4 的 batchData 门是要泛化的先例);
2. 跨驱动拒绝:事务内的写操作跨越非默认驱动时响亮拒绝(取代今天的静默部分提交);⛔ 明确不含真正的跨驱动原子性(两阶段提交是更大的设计题,fix(objectql): engine.transaction hardening — silent degrade, default-driver-only, and no owned-vs-joined signal (ADR-0118 D1 caveats) #4619 原文已排除);
3. owned-vs-joined 信号:transaction(cb, base, opts?) 向 callback 暴露 owned —— ADR-0067 D2 的 join 语义正确但调用方无从分辨,而 batchData 回滚应答的担保只在 owned 时局部成立。

三点都动 IObjectQLEngine 声明面(spec)+ objectql 实现,contract-first:spec 先行。

依赖与协同

• engine 侧可发现性 PR(Part of fix(objectql): engine.transaction hardening — silent degrade, default-driver-only, and no owned-vs-joined signal (ADR-0118 D1 caveats) #4619)先落,本单实现时基于其 warn/诊断接线收紧为拒绝;
• packages/spec 触及生成物(api-surface 等),按 .gitattributes os-regen 四步序。

来源链:#4619(问题记录)、ADR-0118 D1/D4、ADR-0119 D1、ADR-0067 D2、2026-08-04 #4619 内的范围拆定评论、2026-08-06 维护者裁决(见 #4619 时间线)。

[os-zhuang]

范围补充(engine-core 车道 PM,来自 PR #5724 的实现发现,2026-08-06):

1. 第 2 项(跨驱动拒绝)须与 ambient 事务句柄跨数据源泄漏:凡在事务中执行的被审计写入,合规审计行全部静默丢失(#5226 的真实根因) #5351 的裁决合并考虑:实测(PR fix(objectql): make transaction() 的两条既声明 caveat 可被观测 (#4619) #5724 的独立复现)事务内路由到非默认驱动的写不是「在事务外」执行,而是带着默认驱动那个连接的事务句柄执行(buildDriverOptions 无条件穿 ambient trx)。ambient 事务句柄跨数据源泄漏:凡在事务中执行的被审计写入,合规审计行全部静默丢失(#5226 的真实根因) #5351(needs-user-decision 在案)与本单第 2 项对同一处会给出语义,建议合并派发或明确先后,否则两单冲突。
2. 方案 A 的地基已就位:TransactionScope.driver(txStore 记录事务属主 driver)已随 PR fix(objectql): make transaction() 的两条既声明 caveat 可被观测 (#4619) #5724 落地,ambient 事务句柄跨数据源泄漏:凡在事务中执行的被审计写入,合规审计行全部静默丢失(#5226 的真实根因) #5351 方案 A 与本单实现时不必再造。
3. TSDoc 事实性偏差一并修:objectql-engine.ts 的 transaction TSDoc 写「routed elsewhere … are written outside it」,与实测不符(见第 1 点),契约收紧 PR 里应同步修订。

---

Generated by Claude Code

[baozhoutao]

认领(执行席 PM,engine-core 车道)+ 授权记录

维护者 2026-08-07 经执行席会话通道批复:本单契约半边与 #5351 按「同批同 PR 序」由 engine-core 席一并实施 —— spec 契约 PR 先行(IObjectQLEngine 三点:opts.require fail-closed / 跨驱动拒绝 / owned 信号),PR 就绪时给 spec 席开确认单留否决窗口(沿用 #6054 模式),引擎行为 PR(#5351 裁 A + carve-out)随后。原单请分诊补 domain:spec 的请求由此授权覆盖(操作上本席实施、spec 席保留否决)。

• 会话:session_019Q7oc7ASjh8yxyS3Yz78We
• 分支:claude/issue-5696-transaction-contract(与 ambient 事务句柄跨数据源泄漏:凡在事务中执行的被审计写入,合规审计行全部静默丢失(#5226 的真实根因) #5351 同批,PR 序在前)
• 工作树:../objectstack-issue-5696
• 文件面:packages/spec/src/contracts/objectql-engine.ts + 生成物按 .gitattributes os-regen 四步序 + changeset

派发时机与 #5351 同批,压在 #5979(同文件)落地后。

---

Generated by Claude Code