flaky: `spec/src/cloud/tenant.test.ts` 的 #4739 导出面用例贴着 5s 超时 —— 今晚已两次把不相干的 PR 踢出合并队列

[os-zhuang]

现象

packages/spec/src/cloud/tenant.test.ts 这条用例非确定性超时:

FAIL src/cloud/tenant.test.ts > [#4739] `TenantPlan(Schema)` resolves to the ./cloud declaration
  everywhere > resolves the export surface: only ./cloud declares `TenantPlan(Schema)`; …
Error: Test timed out in 5000ms.

Test Files  1 failed | 292 passed (293)
     Tests  1 failed | 7350 passed (7351)

7350 条过,唯一一条红,而且是超时不是断言失败。

它是 flaky 的硬证据(不是回归)

同一份 spec 代码,14 分钟内一过一红:

时刻	上下文	结果
06:33–06:36	PR #4788 的 PR 分支,Test Core (1/2) (2/2)	✅ 全绿
06:47	同一个 PR 变基进合并队列(gh-readonly-queue/main/pr-4788-941dec4c…)	❌ 本条超时

PR #4788 只改 packages/plugins/plugin-auth 和 docs/adr/0069,碰不到 packages/spec 的任何文件。中间也没有任何 spec 侧改动进入 —— 后来排队的 #4783(base 更新)CI 是绿的,main 没坏。

为什么这不是「重跑一次就行」

今晚这是第二次了,两次都打在不相干的 PR 上:

1. 第 1 次:PR fix(security): permission-set 投影只写 spec 认的键;失败的 backfill 变响亮 (#4669) #4755(permission-set backfill (ADR-0094 D4) 现在 100% 失败：行里的 active 存储列喂进了 #4001 之后严格化的 permission spec #4669,permission-set backfill,改 packages/metadata-protocol)—— Test Core 红。我当时误判为 DTS 构建 OOM,是 dev 深挖才定位到本条测试贴着 5s 超时,归属 spec 双源清账 C16:TenantPlan(./cloud ≠ ./system)—— 路线 B:删 system 侧 provisioning 家族,2 条 #4739 / feat(spec)!: 删除 ./system 的 declared-only tenant-provisioning 家族 —— C16 双源清账,基线 12 → 10 (#4739) #4752 车道。
2. 第 2 次:PR fix(plugin-auth): 限流计数器惰性解析 kernel cache —— 误报的告警，与它掩盖的共享限流功能洞 #4788(bug(plugin-auth): [auth] no cache service registered 在 CacheServicePlugin 注册前 21ms 就喊了 —— 误报，且把人引向「你需要 Redis」 #4772,改 plugin-auth)—— 直接被踢出合并队列(CI_FAILURE),需要人工重新入队。

代价不是「多等一轮」,而是:

• 它让每个作者去诊断一个自己没碰过的包的失败。 我第一次就诊断错了方向,烧掉的是真实的排查时间。合并队列的失败信息不挂在 PR head 上,还得去翻 gh-readonly-queue/* 分支的 run,门槛更高。
• 它训练人「红了就重跑」。 一条稳定误报的检查,和 bug(service-automation): flow 节点类型校验跑在插件贡献的执行器注册之前 —— 每个 ADR-0019 approval flow 都被误报「will fail at execution time」 #4771 / bug(plugin-auth): [auth] no cache service registered 在 CacheServicePlugin 注册前 21ms 就喊了 —— 误报，且把人引向「你需要 Redis」 #4772 修的那类误报是同一种病:信号无法区分真假,于是所有人开始忽略它。区别只是这条更贵——它卡的是合并队列。
• 按今晚约 18 次合并/天的节奏,一条随机命中的 flaky 会持续抽税。

建议方向

这条用例叫 resolves the export surface,做的是导出面解析(很可能是逐个动态 import / 模块解析),天然比普通断言慢,5s 是个偏紧的默认值。两条路:

1. 给这条(或整个文件)一个符合其真实工作量的 timeout —— 最省事,但要先量一下它正常耗时多少,确认 5s 是"偏紧"而不是"刚好"。如果正常就要 4.5s,那放宽到 10s 只是把下次踩雷推后。
2. 让它别在测试里做重解析 —— 把导出面解析的结果做成构建期产物(spec 已经有 authorable-surface.json 一类的生成物基线),测试只比对,不现场解析。这条更符合仓内既有做法,也顺带让这个检查变快、变确定。

倾向 2,但先测量再决定 —— 不要在不知道它正常耗时的情况下直接调大数字。

车道归属

⚠️ 落点在 packages/spec/**,按 #4604 登记表归 spec 车道(session_0176qgxgCXTJCUv4YFLtusP9),本会话(主 backlog PM)不派发。

但它影响的是所有车道的合并队列,所以优先级建议高于普通 spec 清账单 —— 它每命中一次,成本就落在一个完全无关的 PR 作者头上。这条 issue 由主 backlog PM 代为立单,正是因为受害者在我这一侧。

关联

• spec 双源清账 C16:TenantPlan(./cloud ≠ ./system)—— 路线 B:删 system 侧 provisioning 家族,2 条 #4739 / feat(spec)!: 删除 ./system 的 declared-only tenant-provisioning 家族 —— C16 双源清账,基线 12 → 10 (#4739) #4752 —— 引入本用例的双源清账车道
• PR fix(security): permission-set 投影只写 spec 认的键;失败的 backfill 变响亮 (#4669) #4755(第 1 次命中)、PR fix(plugin-auth): 限流计数器惰性解析 kernel cache —— 误报的告警，与它掩盖的共享限流功能洞 #4788(第 2 次命中,被踢出合并队列)
• CI: Test Core stalls mid-suite with frozen log output — three occurrences in one day, each costing a manual diagnosis + rerun #4250 —— Test Core 中途卡死的既有 issue(现象不同:那条是卡住无输出,本条是单用例超时;但同属"Test Core 的稳定性在抽税"这一类,建议一并看)

[os-zhuang]

第 3 次命中,并且修正一处诊断:这不是一条用例,是一整类

第 3 次命中:PR #4823(#4728,只改 packages/metadata)在合并队列被踢出(CI_FAILURE),同样碰不到 packages/spec 任何文件。今晚累计 3 次:#4755 → #4788 → #4823,受害者分别在 metadata-protocol / plugin-auth / metadata 三个互不相干的包。

需要修正标题与正文里「cloud/tenant.test.ts 这条用例」的说法。 这次红的不是它:

文件	用例	形态
src/api/rest-server.test.ts	resolves the export surface	解析整个导出面
src/data/driver.test.ts	(tsc 通道用例)	起 tsc 子进程

cloud/tenant.test.ts 只是第 1、2 次抽到的那一张牌。共同点不是"某个文件",而是"做重活的用例跑在 vitest 5s 默认超时下" —— 逐个动态 import 解析导出面、或起一个 tsc 子进程,这类工作量本来就在秒级,5s 默认值对它们全体都是偏紧的。谁被抽中取决于当次 runner 的负载,所以只给 cloud/tenant.test.ts 加 timeout 不会让抽税停止,只会换一张牌。

一条已有的旁证:PR #4506 曾给 #4491 的同族用例显式加过 60s timeout —— 也就是说这个"重活用例贴着 5s"的问题已经被局部修过一次,只是当时只覆盖了当时红的那几条。今晚红的这批,正是那次没修到的余量。这把"建议方向"里的选项 1 从"最省事"降级为"已经试过、且已证明会漏"——逐条加 timeout 是在打地鼠。

因此建议收敛到:先把这一类用例识别出来(在 packages/spec 里 grep 出所有解析导出面 / 起子进程的用例),要么整体给一个符合真实工作量的 testTimeout(文件级或 vitest 配置级),要么按原正文的方向 2 把导出面解析做成构建期产物。选哪条仍由 spec 车道定,但作用域必须是"这一类",不是"这一条"。 原正文"先测量再决定"的要求不变 —— 但测量对象是这一类用例的耗时分布,不是单条。

车道归属不变:packages/spec/**,归 spec 车道(session_0176qgxgCXTJCUv4YFLtusP9),本会话仍不派发,只记录。优先级建议再提一档 —— 一晚 3 次,每次的成本都落在一个完全无关的 PR 作者头上,而现在我们还知道了它的靶面比原以为的更大。

---

Generated by Claude Code

[os-zhuang]

第 4 次命中 —— 这一条把靶子从「一类用例」缩小到一个共用模板,请按这个改

我上一条说「不再追记」,这次破例,因为拿到的不是又一次重复,是能直接决定修法的信息。

第 4 次:PR #4822(#4708,只改 packages/services/service-analytics)在合并队列被踢出。日志:

FAIL src/automation/state-machine.test.ts > [#4658] `EventSchema` is not exported
  from ./automation > resolves the export surface: no entry but ./kernel declares `EventSchema`
Error: Test timed out in 5000ms.
Test Files  1 failed | 293 passed (294)

四次命中的文件全不相同,但用例名是同一个

#	PR	受害包	红的文件	用例名	挂的单
1	#4755	metadata-protocol	cloud/tenant.test.ts	resolves the export surface	#4739
2	#4788	plugin-auth	cloud/tenant.test.ts	resolves the export surface	#4739
3	#4823	metadata	api/rest-server.test.ts	resolves the export surface	—
4	#4822	service-analytics	automation/state-machine.test.ts	resolves the export surface	#4658

四个不同文件、挂在不同的清账单(#4739 / #4658)下,用例名逐字相同:resolves the export surface。 这不是巧合——这些是双源清账车道按同一个模板批量生成的 pin 测试,每条都现场解析一遍整个导出面,然后跑在 vitest 5s 默认超时下。

这把修法从「打地鼠」变成「改一处」

我上一条建议「grep 出这一类用例、整体给 timeout」。有了用例名之后可以更准:

1. 先定位这些 pin 测试的共用模板 / helper(按 resolves the export surface 全仓搜 packages/spec/**)。四次命中都指向它,大概率是一个被复用的断言函数或生成脚本。
2. 改法二选一,都只需动那一处:
   • 给这个模板产出的用例统一一个符合真实工作量的 testTimeout(它们做的是逐个动态 import,秒级是常态,5s 是紧的);
   • 或按原正文方向 2,把导出面解析提成构建期产物,模板只比对——这条更彻底,因为它同时消掉了每条 pin 测试重复解析同一份导出面的浪费。

PR #4506 给 #4491 同族用例加 60s timeout 的那次,就是在模板下游逐条打补丁——所以只覆盖了当时红的那几条,#4739 / #4658 后来新增的照样漏。动模板才收得干净。

成本已经不是「多等一轮」

一晚 4 次,受害者是 metadata-protocol / plugin-auth / metadata / service-analytics 四个完全无关的包。#4823 是原样重投后一次通过的,#4822 我也已原样重投——每一次都在证明 PR 本身没问题,而这个证明过程要有人去翻 gh-readonly-queue/* 的 run 才做得出来。

车道归属不变:packages/spec/**,归 spec 车道(session_0176qgxgCXTJCUv4YFLtusP9),本会话仍不派发。但按目前频率,它已经是全仓合并吞吐上最贵的一条单。

---

Generated by Claude Code

[os-zhuang]

根因锁定 —— 是 packages/spec/vitest.config.ts 缺 testTimeout,修法是一行

第 5 次命中(PR #4822 连续第 2 次被踢)。这次日志给了决定性证据,根因不必再猜了。

一次红三个文件,用例名逐字相同

FAIL src/automation/state-machine.test.ts  > [#4658] … > resolves the export surface: …
FAIL src/cloud/tenant.test.ts              > [#4739] … > resolves the export surface: …
FAIL src/system/environment-artifact.test.ts > [#4740] … > resolves the export surface: …
Error: Test timed out in 5000ms.   (×3)
Test Files  3 failed | 291 passed (294)

三条挂在三个不同的清账单(#4658 / #4739 / #4740)下,同时超时。这排除了「某条用例自己慢」,只剩「一批用例共用一个过紧的超时」。

机制:这些用例在跑 TypeScript 编译器

state-machine.test.ts:150 起:

it('resolves the export surface: …', async () => {
  const ts = (await import('typescript')).default;
  …                       // 建 program、解析 symbol、unalias、追 originOf

它们每条都现场加载 typescript 并对整个导出面做一次类型解析。 这在正常机器上就是秒级工作,不是"偶尔慢"。

而 packages/spec/vitest.config.ts 没有设 testTimeout:

export default defineConfig({
  test: { globals: true, environment: 'node', include: [...], coverage: {...} },
});          // ← 无 testTimeout,吃 vitest 默认 5000ms

一批跑编译器的用例,配在 5 秒默认超时下。 合并队列的 runner 比 PR CI 更拥挤(同时跑多个 PR 的批次),所以命中率在队列里明显更高——今晚 5 次全在队列里,PR 分支上一次没红过。这也解释了为什么"重跑就过":它从来不是逻辑问题,是余量问题。

靶面:12 个文件,不是 1 个也不是 3 个

全仓扫 await import('typescript'):

api/rest-server · automation/state-machine · automation/sync-retirement · cloud/tenant
data/driver · integration/connector · kernel/package-dependency-dual-source
studio/action-location-retirement · system/environment-artifact · system/notification
ui/app · ui/view

12 个文件全部暴露在同一个 5s 默认值下,今晚只是随机抽到了其中 5 个。这也印证了 PR #4506 当初逐条加 60s timeout 为什么会漏——它在下游打补丁,而池子有 12 个。

建议修法(一行)

// packages/spec/vitest.config.ts
test: { globals: true, environment: 'node', testTimeout: 60_000, … }

与 PR #4506 给同族用例定的 60s 一致,只是提到配置层一次覆盖全部 12 个,不再随新增清账单漏。这是止血,不是终局 —— 原正文方向 2(把导出面解析提成构建期产物,测试只比对)仍然更好:它同时消掉 12 个文件各自启动一次 TS 编译器的浪费。但方向 2 是一次重构,止血应该先落。

车道与请求

packages/spec/** 归 spec 车道(session_0176qgxgCXTJCUv4YFLtusP9),本会话不派发、不改动,以上全部为只读取证。

但请求提级处理:今晚 5 次命中,受害者是 metadata-protocol / plugin-auth / metadata / service-analytics 四个无关包,#4822 已连续两次被踢、正在第三次重投。它现在实际卡的是全仓合并吞吐,而止血只需要改一行配置。

---

Generated by Claude Code

[os-zhuang]

跨车道登记:止血已拆为 #4850,本单保持打开

维护者批准主 backlog PM(session_015Br2xsJsczFsTR9bvbh2Ny)破例跨入 packages/spec/**,仅限止血那一行:

• 止血:packages/spec 的 vitest 缺 testTimeout —— 12 个跑 TS 编译器的用例配在 5s 默认值下 #4850 —— packages/spec/vitest.config.ts 加 testTimeout: 60_000 + changeset。范围写死,不碰 .zod.ts、不碰测试逻辑、不碰生成基线。已认领并派发。
• 本单(flaky: spec/src/cloud/tenant.test.ts 的 #4739 导出面用例贴着 5s 超时 —— 今晚已两次把不相干的 PR 踢出合并队列 #4796)不关闭、不被 止血:packages/spec 的 vitest 缺 testTimeout —— 12 个跑 TS 编译器的用例配在 5s 默认值下 #4850 的 PR 引用 Fixes。 方向 2(把导出面解析提成构建期产物,12 个文件不必各自启动一次 TS 编译器)仍归 spec 车道(session_0176qgxgCXTJCUv4YFLtusP9),那才是解。

破例的理由,记录在案:这条 flaky 卡的不是某个车道,是全仓合并吞吐——今晚 5 次全部命中队列,受害者是四个无关包,其中 #4822 连踢两次;而本次发版的关键项(#4775)还要走同一条队列。止血成本是一行配置,等待成本是每条 PR 进队列都在抽签。

留否决窗口:spec 车道若认为这一行该换个值、换个位置(比如放到 workspace 级配置、或只给这 12 个文件加 per-file timeout),直接在 #4850 说,本会话立刻让行、撤回 PR。这一行属于你们的车道,我只是在你们接手前先把血止住。

---

Generated by Claude Code