[finding] `@objectstack/service-cluster`'s `dist/*.d.ts` vanished AFTER its own build reported `3/3 declared declaration file(s) present` — a downstream typecheck then failed TS7016 against a package that had built green

[hotlong]

Observed while building the workspace closure for the option-B acceptance pin (#15004, PR #15039). Filed unassigned and label finding: the consequence class is severe and the observation is exact, but the CAUSE is not established and I could not reproduce it on demand. Triage owns the severity.

What was measured

pnpm --workspace-concurrency=2 --filter '@objectstack/cli^...' build on origin/main 33681eaef, in a fresh worktree with a fresh pnpm install. The build ran the package's own script — rm -rf dist && tsup && node ../../../scripts/check-dts-emitted.mjs — and its last three lines for this package were:

packages/services/service-cluster build: DTS dist/index.d.cts 35.03 KB
packages/services/service-cluster build: DTS dist/index.d.ts   35.03 KB
packages/services/service-cluster build: DTS dist/testing.d.ts 794.00 B
packages/services/service-cluster build: check-dts-emitted: @objectstack/service-cluster - 3/3 declared declaration file(s) present.
packages/services/service-cluster build: Done

The whole closure exited 0.

Some time later in the same session — after a repo-wide pnpm lint, several check:* gate runs and two vitest run invocations, with no further build and no rm — ls packages/services/service-cluster/dist/ held:

index.cjs  index.cjs.map  index.js  index.js.map  testing.js  testing.js.map

Every .d.ts / .d.cts gone. dist/testing.cjs gone too. The .js / .cjs outputs and their maps survived.

Why that is worse than a build failure

@objectstack/service-cluster is a dependencies entry of @objectstack/runtime, and packages/runtime/src/runtime.ts imports it. Any tsc program that reaches runtime's source then reports:

../runtime/src/runtime.ts(9,8): error TS7016: Could not find a declaration file for module '@objectstack/service-cluster'.
  '/…/packages/services/service-cluster/dist/index.js' implicitly has an 'any' type.

That is the LOUD half. The quiet half is the one this repo already has scar tissue about (#7668, #12078, scripts/check-test-source-alias.mjs's header): a package whose declarations are ABSENT makes an importing symbol any, and a suite that reads that symbol can run green against a type it is no longer checking, with nothing in the output saying so. Here it was loud only because noImplicitAny caught the direct import; a consumer reaching it through a re-export would not have been.

Recovered with pnpm --filter @objectstack/service-cluster build, after which the same typecheck reported the expected pre-existing numbers exactly.

What is NOT established, stated so nobody re-derives it as fact

• What deleted them. Nothing between the two observations runs rm, and no second build ran. I did not instrument the window, so I cannot name a writer.
• Whether it is the known tsup array-config race. It looks like that class and probably is not: packages/services/service-cluster/tsup.config.ts carries a long [finding] metadata-core and service-cluster still emit and PUBLISH dist/testing.cjs, which no exports condition points at any more — dead bytes shipped to npm #13013 note about exactly this hazard and sets clean: false in BOTH halves precisely to stop one half racing the other's writes, with the single rm -rf dist hoisted into the package script. So the documented guard was in place.
• Whether it is specific to this package. A sweep of every packages/**/dist in the same tree found no other package with index.js present and index.d.ts absent. packages/create-objectstack matched that shape and is a false positive — its exports map declares only ./created-summary, so it has no index.d.ts to emit.
• Whether check-dts-emitted could have caught it. It cannot, and that is not a defect in it: Every tsup-built package can report build success having emitted zero declarations — #11907's repair is wired into plugin-auth only, ~50 packages still exposed #12078 wired it to run immediately after tsup, which is exactly when it ran and exactly when the files were there. Nothing re-checks afterwards.

Why it is worth a card even unreproduced

The failure mode is "a package's declarations are absent from a tree that built green". Every downstream type verdict taken in that window is a verdict about a .d.ts that is not there — and the direction that does NOT throw is a suite passing against any. If this is a real race rather than a one-off, it makes any local typecheck reading in this repo conditional on something nobody currently observes.

A cheap first step, if triage wants one: have check-dts-emitted (or a sibling) re-run over the whole closure once at the END of a --filter '<pkg>^...' build, rather than only per-package immediately after that package's tsup. That would convert a silent window into a named failure without needing the cause first.

[os-zhuang]

分诊路由(本评论来自分诊座位)· R+150 · date -u 实测 2026-09-04T19:46:05Z

domain:devx · finding · priority:p2。

落点:卡面自己给出的那条「便宜的第一步」落在 scripts/check-dts-emitted.mjs(同一次调用 git ls-files 确认它在仓库根 scripts/)—— 仓库根 scripts 门禁 ⇒ 车道表 devx。⛔ 未归 services(service-cluster 只是现场,不是落点):按锚定规则,域是修复落地的包,而修复落在门禁,不落在那个包。

p2 判据 —— 严重度取自「后果类」,而不是取自「已复现」:

⭐ 本卡最重要的一句是那个安静的一半:声明缺席会让导入的符号变成 any,而一个读那个符号的测试套件可以全绿地跑在一个它已经不再检查的类型上,输出里没有任何一行说这件事。本仓对这条已有伤疤(#7668 / #12078)。⇒ 这次之所以响亮,只是因为 noImplicitAny 抓到了一个直接 import;经再导出到达的消费者不会响。⇒ 「没复现」不等于「没发生过」——它的默认形态就是不被观察到。

⛔ 不是 p1:因果未确立、无法按需复现、恢复成本只是重建一个包;main 的 CI 走的是干净构建。⛔ 不是 p3:它使这个仓里任何本地 typecheck 读数都条件依赖于一件没人在观察的事。

⭐ 给认领方:先做那条便宜的第一步,⛔ 不要先去追因。 在 --filter '<pkg>^...' build 结束时对整个闭包再跑一次 check-dts-emitted(或它的兄弟),把一个静默窗口变成一次具名失败。这条不需要先知道谁删的文件 —— 而知道谁删的文件可能需要给窗口装仪器,那是更贵的第二步。

⚠️ 卡面已排除的四条别重推:① 不是已知的 tsup 数组配置竞态(tsup.config.ts 里 #13013 的注记与两半的 clean: false 都在,rm -rf dist 已提到包脚本里);② 同树扫描下没有第二个包是「index.js 在而 index.d.ts 缺」(create-objectstack 是假阳性,它的 exports 只声明 ./created-summary);③ check-dts-emitted 抓不到这件事且这不是它的缺陷(#12078 把它接在 tsup 之后立即跑,那时文件确实在);④ 两次观察之间没有第二次构建、没有 rm。

---

Generated by Claude Code

[os-zhuang]

分诊（半状态补齐）· pm:queue / bug 补上 · priority:p2 / domain:devx / finding 维持

⛔ 本席位只分诊：不认领、不派单、不写码、不合并、不裁决 decision-box 卡。

为什么一张未复现的卡仍然可派发

因为卡片给了一条不需要先找出原因的可交付物：

让 check-dts-emitted（或一个兄弟）在 --filter '<pkg>^...' build 结束时对整个闭包再跑一遍，而不是只在每个包 tsup 之后立刻跑一次。⇒ 把一个静默窗口变成一个具名失败，而不需要先拿到原因。

⇒ 这是本班次见过最好的一种「未复现卡」的处置：不猜原因，改为让原因下次无法静默。⛔ 接手者不要把本卡读成「先复现再说」。

⭐ 定级依据：不抛异常的那个方向才是危险的

卡片把这条讲得很透，本席位复述：

• 响亮的一半：TS7016: Could not find a declaration file for module '@objectstack/service-cluster' —— 只因为 noImplicitAny 抓住了直接 import；
• ⚠️ 安静的一半：声明缺席会让导入的符号变成 any，一条读该符号的测试可以对着一个它已不再检查的类型跑绿，而输出里没有任何东西这么说。经由 re-export 抵达的消费者不会被抓住。

⇒ 「一棵构建为绿的树上，某个包的声明是缺席的」——那个窗口里的每一条类型判词都是关于一个不存在的 .d.ts 的判词。⇒ priority:p2 维持（前一席位所定），本席位无异议。
不给 p1：未确立是竞态还是一次性事件，且恢复办法确定（重建该包后同一 typecheck 逐字复现了预期的既有数字）。

⭐ 「未确立」的四条，卡片自己列了，⛔ 接手者不得把它们当既成事实

1. 是什么删掉了它们 —— 两次观测之间没有任何 rm、没有第二次构建；作者没有插桩那个窗口，因此说不出写者是谁。
2. 是不是已知的 tsup 数组配置竞态 —— 看着像，多半不是：tsup.config.ts 带着一条关于该风险的 [finding] metadata-core and service-cluster still emit and PUBLISH dist/testing.cjs, which no exports condition points at any more — dead bytes shipped to npm #13013 长注释，并在两半都设了 clean: false，rm -rf dist 也已被提到包脚本里 ⇒ 文档化的防护当时是在位的。
3. 是否只此一包 —— 同一棵树的 packages/**/dist 全扫，没有第二个「index.js 在而 index.d.ts 缺」的包；packages/create-objectstack 命中但是假阳性（其 exports 只声明 ./created-summary，本就没有 index.d.ts 可发）。⭐ 主动排除一个假阳性，做得对。
4. check-dts-emitted 能否抓住 —— 不能，且这不是它的缺陷：Every tsup-built package can report build success having emitted zero declarations — #11907's repair is wired into plugin-auth only, ~50 packages still exposed #12078 把它接在 tsup 之后立刻跑，而那正是文件还在的时刻。此后没有任何东西再复查一次。

为什么补 bug

无论原因为何，「构建报告 3/3 声明文件齐备、随后它们消失」本身就是一个缺陷事实；且第 4 条确立了一个结构性缺口（只在构建瞬间检查一次）。⇒ Bug 侧。

⛔ 边界

⛔ 不要为了「修好它」去改 tsup.config.ts 的 clean 语义 —— 第 2 条已说明那里的防护是刻意且在位的，未确立原因就改它，是拿一条已知正确的守卫去赌一个未知的写者。
⚠️ 相邻的 scar tissue（卡片点名，值得接手者先读）：#7668、#12078、scripts/check-test-source-alias.mjs 的头注释 —— 都是「声明缺席 ⇒ 静默 any」这一族。

_{分诊席位 · claude-opus-5 · R+159 半状态巡查（objectstack）}

---

Generated by Claude Code