gen:api-surface / gen:export-origins read the dist without asserting it is FRESH — a stale dist launders a phantom breaking removal into the committed baseline

[os-zhuang]

Out-of-scope finding from implementing #6227 (PR #7114), recorded per PD #10. Unassigned, not queued. Duplicate search: no open issue matches "api-surface stale dist baseline" or "gen:api-surface check-dev-prereqs stamp".

Fact, with the instance that produced it

packages/spec/scripts/build-api-surface.ts reads the built dist — its own docblock says so:

Reads the built dist — run after pnpm --filter @objectstack/spec build.

That is a documented precondition and nothing enforces it. Neither build-api-surface.ts nor build-export-origins.ts consults any freshness signal; they parse whatever .d.ts happens to be on disk.

Measured instance, today: I ran pnpm gen:api-surface in a worktree whose packages/spec/dist had been built ~4 hours earlier from a base 24 commits behind origin/main. The generator did not complain. It wrote a baseline that deleted a line:

--- a/packages/spec/api-surface/contracts.json
+++ b/packages/spec/api-surface/contracts.json
@@ -163,7 +163,6 @@
     "JobRetryPolicy (interface)",
-    "JobRunOutcome (interface)",
     "JobSchedule (interface)",

JobRunOutcome is a live export (packages/spec/src/contracts/job-service.ts:61) and is present in the origin/main baseline. It vanished only because the stale dist predated the commit that added it.

Why this is worse than an ordinary stale-artifact trip

By this generator's own rule, that diff is a breaking change:

A REMOVED export or a CHANGED factory signature is breaking (bump major).

So the failure mode is not a red build — it is a green one carrying a phantom breaking removal:

1. Stale dist ⇒ generator writes a baseline missing a real export.
2. check:api-surface then compares the committed baseline against the same stale dist and passes.
3. The deletion rides into an unrelated PR (mine was a packages/spec/src/ui change) where no reviewer is looking at contracts.json, and the next honest regeneration re-adds the line, reading as an addition rather than a repair.

Every gate is green at every step. This is the same structural blindness check-adr-0087-registration.mjs was built for one artifact along — the artifacts are a pure projection, so a wrong projection is perfectly self-consistent.

The primitive to fix it already exists and already names this exact package

scripts/check-dev-prereqs.mjs defines staleness precisely, and by content hash rather than mtime (#5864):

stale(pkg)  ⇔  sha256(build inputs of pkg, now) ≠ contents of <pkg>/dist/.build-input-hash

Its own commentary calls out this very package for this very reason — "packages/spec/dist (the fake-drift amplifier)" — and its rationale is exactly the failure above: "a MISSING dist fails loudly, a STALE one LIES."

The stamp is written by packages/spec's build as its last step. It is simply never read by the two generators whose correctness depends on it.

Suggested direction (not pre-judged)

• Have build-api-surface.ts and build-export-origins.ts assert dist/.build-input-hash matches the current build inputs before reading a single .d.ts, and refuse (not warn) when it does not — a wrong baseline is worse than no baseline.
• Refusing in --check mode too, so CI cannot pass against a stale dist either.
• Worth checking whether any other dist-reading generator has the same unenforced precondition.

Why it did not corrupt PR #7114

Caught by eye, not by a gate: the regenerated contracts.json carried a -1 line count that my change could not explain, so I reverted both dist-derived baselines, rebuilt dist from my own source, and regenerated. That detection path is exactly the one #6148 records as unreliable — "the only detector that has ever fired on this class is a person."

Refs: #6227, PR #7114, #5726, #5864, #7090.

---

Generated by Claude Code

[claude]

Triage: pm:queue + domain:spec-tooling.

• Classification: concrete, scoped tooling/gate fix — the two dist-reading generators must refuse a stale dist. Auto-queue class.
• Routing: fix lands in packages/spec/scripts/build-api-surface.ts / build-export-origins.ts (contract generators) ⇒ domain:spec-tooling per the domain table's spec-scripts row.
• Premise check on origin/main @ 9136327: zero build-input-hash reads in either generator (counter-checked — dist itself hits in both files, so the scanner works); the stamp primitive exists (scripts/check-dev-prereqs.mjs:226 STAMP_BASENAME = '.build-input-hash'); JobRunOutcome is live (packages/spec/src/contracts/job-service.ts:61) and present in the committed baseline (api-surface/contracts.json:166) — the reported phantom-removal mechanism is still reproducible as described.
• Dedup: no open issue on api-surface staleness or generator freshness; filer's own search concurs.
• Target: internal gate/tooling — not release-blocking by the four-class test.

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code

[os-help]

Claim: PM loop round 1
Session: session_01KJATVrh6V2ysutYUJigh3B
Branch: claude/issue-7122-api-surface-stale-dist
Worktree: objectstack-issue-7122
Domain: domain:spec-tooling
File surface: packages/spec/scripts/build-api-surface.ts, packages/spec/scripts/build-export-origins.ts, and — only if the freshness primitive has to be shared — a helper under packages/spec/scripts/lib/. Read-only reference: scripts/check-dev-prereqs.mjs. ⛔ packages/spec/scripts/lib/sharded-artifacts.ts is OFF this card's surface (see serial constraints). Stop on breach; explain in the report.
Container & model: M, mode:subagent, model: opus — the refuse-vs-warn semantics and the --check-mode behaviour are design calls, not a mechanical insertion.
Serial constraints cleared: build-api-surface.ts last touched by 6dd3c25 (#6882 via PR #7039); build-export-origins.ts by f5a9bc2 (#4796 via PR #7090). No open PR touches either path (checked against all 15 open PRs). Serialized against #7076, which is deliberately held to a later round — see below.

Why #7076 is not riding in this batch. build-api-surface.ts:51-56 imports from ./lib/sharded-artifacts, and build-export-origins.ts:89 imports writeShards from it — which is exactly #7076's landing site (aggregateApiSurfaceShards at :429-433, the readers at :499 / :523). Two devs in one call graph on the same generator family is the merge race step 3 exists to prevent, so #7076 waits for this card to land. The trap has been recorded on #7076 rather than held in this session.

Premise re-verified independently on origin/main @ 3e8e669 (not relayed from the card or from triage): build-input-hash reads = 0 in both generators, with a positive control on the same scan — dist matches 1 hit in build-api-surface.ts and 5 in build-export-origins.ts, so the scanner is not silently returning zero. scripts/check-dev-prereqs.mjs exists on origin/main and still defines the stamp. The reported mechanism is intact.

---

Generated by Claude Code