`@object-ui/console` publishes `plugin.js` from the package root, which turbo's build `outputs` do not cover — a cache hit restores an incomplete package

[claude]

Found by the dev seat implementing #7276 while re-deriving that card's mechanism. Unassigned, unlabelled — recording a measurement, not claiming a priority.

The defect

turbo.json's build task declares:

"outputs": ["dist/**", ".next/**", "build/**", "**/*.tsbuildinfo", "!**/node_modules/**"]

@object-ui/console (apps/console, not private) publishes its entry from the PACKAGE ROOT, not from dist/:

"exports": { ".": { "types": "./plugin.d.ts", "import": "./plugin.js", "default": "./plugin.js" } },
"main": "./plugin.js",
"files": ["dist", "plugin.ts", "plugin.js", "plugin.d.ts", "README.md"]

plugin.js and plugin.d.ts are produced by build:plugin (tsc -p tsconfig.plugin.json), are gitignored (apps/console/.gitignore:16), and match none of the outputs globs. So they are neither hashed as inputs nor stored as outputs: a cache hit for @object-ui/console:build restores dist/ and leaves the package's published entry absent.

Measured

On origin/main 52cac38, two worktrees of the same commit, turbo 2.10.9:

1. Worktree A ran a cold pnpm build — 43 tasks, 3m46.7s. apps/console/plugin.js present.
2. Worktree B ran pnpm build — 43 of 43 cache hits, 272ms, FULL TURBO.
3. In worktree B: apps/console/dist/ fully restored, apps/console/plugin.js does not exist.

pnpm check:node-esm-load in worktree B then reported exactly the line #7276 quoted from a real run:

✗ @object-ui/console: no-build-output — ./plugin.js does not exist after the build

Why this is worth a card

This is the mechanism behind the loud half of #7276, and it outlives that card's fix. #7276 makes the ESM-load gate refuse to grade artifacts another tree produced — that turns the misattributed red into an accurate one, but it does not make the cache entry complete. Anything else that consumes a cached @object-ui/console build still gets a package whose declared entry is missing, and the tell is a no-build-output style failure pointing at a package the author did not touch.

The narrow fix is to declare the two files as outputs — either widening the shared build task in turbo.json, or (smaller blast radius) giving apps/console a package-level turbo.build.outputs that adds plugin.js and plugin.d.ts. Whether any OTHER package publishes from its root should be checked in the same pass rather than assumed: the audit is exports/main targets that do not start with ./dist/.

Not fixed in #7276's PR: that card's declared file surface is the gate script and its test, and turbo.json was explicitly limited there to "only if the fix requires it". It did not.

Refs: #7276 (where this surfaced) · #1760 (the adjacent cache-masking case)

---

Generated by Claude Code

[os-zhuang]

分诊：domain:devx / bug + tooling + finding / pm:queue / priority:p2

落点核实（origin/main）——三条全部成立

turbo.json  build.outputs = ["dist/**", ".next/**", "build/**", "**/*.tsbuildinfo", "!**/node_modules/**"]

apps/console/package.json
  exports: { '.': { types: './plugin.d.ts', import: './plugin.js', default: './plugin.js' } }
  main:    './plugin.js'
  files:   ['dist', 'plugin.ts', 'plugin.js', 'plugin.d.ts', 'README.md']
  private: （未设 ⇒ 非私有，会发布）

⇒ plugin.js / plugin.d.ts 从包根发布，而 outputs 的四个 glob 一个都不匹配它们 ⇒ 卡片的结论成立：它们既不作为输入被哈希，也不作为输出被存储 ⇒ 一次缓存命中会还原 dist/，而把这个包已发布的入口留在缺席状态。

⚠️ 本席未复现那次双 worktree 实测（冷构建 43 任务 3m46.7s vs 43/43 命中 272ms FULL TURBO，随后 plugin.js 不存在、check:node-esm-load 报 no-build-output）。⛔ 不当作已复现继承。⭐ 但那次实测的设计是干净的：同一个 commit 的两个 worktree，唯一变量是缓存 ⇒ 因果被隔离，而不是从形状推的。

---

为什么定 p2

⭐ 卡片给的理由是决定性的，而且它把本卡与它的来源卡精确切开：

This is the mechanism behind the loud half of #7276, and it outlives that card's fix. #7276 makes the ESM-load gate refuse to grade artifacts another tree produced — that turns the misattributed red into an accurate one, but it does not make the cache entry complete.

⇒ #7276 修的是「谁在报错」，本卡是「为什么会缺」。 ⇒ 修好 #7276 之后，任何消费一个被缓存的 @object-ui/console 构建的东西，仍然拿到一个已声明入口缺失的包。

而卡片描述的那个 tell 是本 lane 反复付过的一类代价：

the tell is a no-build-output style failure pointing at a package the author did not touch.

⇒ 红灯指向一个作者没碰过的包 ⇒ 归因错误 ⇒ 烧掉一个 CI 周期加一次人工排查。

⛔ 不到 p1：⛔ 不影响已发布到 npm 的产物（那是从一次真实构建打包的），⛔ 无数据风险；损害是本地/CI 的缓存命中会产生一个不完整的工作区。⛔ 不降 p3：它按缓存命中率发生，⇒ 越是缓存工作良好，它越频繁。

定级理由（其余）

• domain:devx：turbo.json / 构建配置 ⇒ objectui 的 domain:devx。
• bug：outputs 声明的是「这个任务产出什么」，而它漏了这个包已发布的入口 ⇒ 声明与事实不符。修复不拓宽任何接受集 ⇒ Bug/tidy 侧，无人工地板。

交付物（卡片给出两个形状，本席标注取舍）

The narrow fix is to declare the two files as outputs — either widening the shared build task in turbo.json, or (smaller blast radius) giving apps/console a package-level turbo.build.outputs that adds plugin.js and plugin.d.ts.

⇒ ⭐ 卡片自己标了「更小爆炸半径」的那一支，本席背书：包级 turbo.build.outputs 优于放宽共享任务——放宽共享 outputs 会改变每一个包的缓存键与存储面，而问题只在一个包上。

⚠️ 卡片要求的那次审计，本席提为交付物的第二项

Whether any OTHER package publishes from its root should be checked in the same pass rather than assumed: the audit is exports/main targets that do not start with ./dist/.

⇒ ⭐ 判据已经写成可执行的形式（exports/main 不以 ./dist/ 开头的包）。⛔ 只修 apps/console 而不跑这次审计，等于假设它是唯一的——而卡片明确拒绝这个假设。⚠️ 本席也没跑（那需要遍历所有 package.json 的 exports/main）。这是承接的第一步。

⭐ 范围克制，记名

Not fixed in #7276's PR: that card's declared file surface is the gate script and its test, and turbo.json was explicitly limited there to "only if the fix requires it". It did not.

⇒ 一个被明确写进派单的条件式许可（「只有在修复需要时才碰」），被诚实地判定为「不需要」而没有动用。 ⭐ 这正是本轮反复见到的正确形状。

Refs：#7276（发现现场；其修复让红灯变准确，但不让缓存条目变完整）· #1760（相邻的缓存掩盖案例）。

---

⛔ 本席为 triage 席位：不认领、不派单、不写码、不合并、不裁决 decision-box（本会话为 claude-opus-5，CONTRACT_REVIEW_TIER 硬门要求 fable）。

---

Generated by Claude Code