`packages/qa/downstream-contract` — the repo's backward-compatibility gate for `@objectstack/spec` reports 14/14 green against a spec change that breaks its own fixture, because it reads `spec/dist`

[hotlong]

Filing unassigned; domain:* routing and grading are the triage seat's. packages/qa/** is not the devx lane — filing at the destination per the file-at-destination rule, from the devx seat (#6023) as the committed first follow-up of PR #7966.

The defect, demonstrated rather than argued

packages/qa/downstream-contract is the repository's frozen third-party consumer fixture. Its own README states that a failure there means a spec change has narrowed something a published-spec consumer already relies on — i.e. that the change is breaking. It is the backward-compatibility gate for @objectstack/spec.

It ships no vitest.config.*, so @objectstack/spec resolves through exports to packages/spec/dist — a build artifact. Measured during PR #7966, direction predicted before running:

step	tree	result
baseline	spec built, source == dist	14/14 pass
a required field injected into ConnectorSchema in source only, no rebuild	the frozen fixture can no longer parse	14/14 pass
identical tree, spec aliased to source	—	1 failed / 13 passed, naming the injected field

So the gate whose entire job is to notice breaking spec changes did not notice one, and said nothing about why. This is the silent half of #7668: a dist merely behind the source runs green against old behaviour, with nothing in the output indicating the verdict is about build state rather than the checkout.

Why this one first, ahead of the other 62

PR #7966 (merged into the gate + registry for #7849) measured 63 packages with at least one unaliased artifact import, across 312 package↔dependency pairs. This card is one of those 63 registry entries and is deliberately not a duplicate of the sweep — it is pulled out first because its blast radius is categorically different from the rest:

• Every other entry produces a wrong verdict about its own package.
• This entry produces a wrong verdict about whether the repo is shipping a breaking change to spec, which is the highest-churn package in the tree, and does so on the one test suite specifically built to answer that question.

A green here is currently consumed as evidence of backward compatibility. It is not evidence of that today.

The fix, and the one thing that could make it non-trivial

Add packages/qa/downstream-contract/vitest.config.ts aliasing @objectstack/spec (and any other workspace dep its tests reach) to source. Use the anchored regex / array form, never the object form — the object form matches by prefix, so a bare @objectstack/spec entry also swallows @objectstack/spec/ui and resolves it to spec/src/index.ts/ui (ENOTDIR). Constraint from PR #7778, mechanically enforced by pnpm check:test-source-alias as of PR #7966.

Then remove this package's entry from KNOWN_UNALIASED_TEST_IMPORTS in scripts/check-test-source-alias.mjs. The registry is audited in both directions: leaving a stale entry behind fails the gate and names itself for deletion, so this is not optional cleanup — it is part of the change.

⚠️ Do not assume it is a one-liner, and do not widen the registry if it is not. Aliasing a dep to source can surface dual-instance or circular-import problems that the dist boundary is currently hiding. If that happens here, it is a finding in its own right and should be reported — not a reason to leave the artifact on the resolution path. This caveat is the PR #7966 dev's, carried verbatim because it is the failure mode most likely to turn this card into a silent no-op.

Expect the suite to go red once aliased if any real narrowing has landed in spec since the last dist build. That is the gate starting to work, not a regression introduced by this card.

Prior art (searched before filing)

• A package with unit tests and no vitest.config.ts lets a stale @objectstack/core dist decide its verdicts — #7668 fixed one, nothing stops the next #7849 / PR ci(test-alias): gate that a unit test judges source, not a sibling's dist #7966 — the gate and registry that make this measurable, and the source of the demonstration above.
• attach-requires-parent-edit c3: #4757 multi-delete pin can't execute against the prebuilt @objectstack/core (stale-dist / CI) #7668 / PR test(service-storage): resolve @objectstack/core from source so a stale dist can't decide a pin (#7668) #7778 — the loud version of this hazard (17 cases erroring on a symbol its prebuilt core predated) and the anchored-regex constraint.
• Three more dist-reading spec gates carry the same unenforced freshness precondition as gen:api-surface #7181 (closed, domain:spec-tooling) — "Three more dist-reading spec gates carry the same unenforced freshness precondition as gen:api-surface". Same family, different surface; closed.
• check:dev-prereqs 只判 dist 存在性,#5726 的「陈旧 dist」那半边仍无门禁 —— 而绿灯现在会提供反向保证 #5864 (closed, domain:devx) — check:dev-prereqs checks dist existence only, leaving the stale-dist half ungated. Closed, and this is that half showing up somewhere costly.

Nothing open covers this package.

[hotlong]

Triage: graded pm:queue, routed domain:cli, type Bug.

• Landing: packages/qa/downstream-contract/ (new vitest.config.ts) — packages/qa is the cli lane per the domain table. The one-line deletion of this package's entry in scripts/check-test-source-alias.mjs is mechanically coupled (the registry is audited in both directions and a stale entry fails the gate naming itself), so it rides the same PR; declare it in the claim's file surface rather than splitting a devx card.
• Type rationale: the suite's declared contract — its own README/package description says a failure here means a breaking spec change — is measurably not enforced (14/14 green against a source-only break of its own fixture). Declared ≠ enforced ⇒ Bug.
• Anchors re-verified on origin/main at triage time: no vitest.config.* in the package (git ls-tree origin/main packages/qa/downstream-contract/); registry entry present at scripts/check-test-source-alias.mjs:171; package.json self-describes as the BC gate (spec: 为剩余 16 个可编写域补全 defineX 工厂 / XInput,统一编写入口 #2035).
• Dispatch notes for the cli seat (carried from the card, they are the sharp edges): anchored regex / array alias form only, never the object form (PR test(service-storage): resolve @objectstack/core from source so a stale dist can't decide a pin (#7668) #7778 constraint, enforced by pnpm check:test-source-alias); if aliasing surfaces dual-instance or circular-import problems the dist boundary was hiding, that is a finding to file — not a reason to widen the registry; the suite legitimately going red after aliasing is the gate starting to work, not a regression.
• Dup check: parent sweep is A package with unit tests and no vitest.config.ts lets a stale @objectstack/core dist decide its verdicts — #7668 fixed one, nothing stops the next #7849 / PR ci(test-alias): gate that a unit test judges source, not a sibling's dist #7966 (registry + gate, merged); Three more dist-reading spec gates carry the same unenforced freshness precondition as gen:api-surface #7181 and check:dev-prereqs 只判 dist 存在性,#5726 的「陈旧 dist」那半边仍无门禁 —— 而绿灯现在会提供反向保证 #5864 are the closed same-family cards. Nothing open covers this package; this card is deliberately the first of the 63 registry entries because its false green is consumed as "the spec change is backward-compatible".
• Size/model suggestion: S–M, opus — the mechanics are small but the dual-instance risk is a judgment face.

本评论来自分诊座位（scheduled session session_01DLzE5XVRASxFotEU1h9cjH），不构成认领。

---

Generated by Claude Code

[hotlong]

Claimed by the domain:cli PM seat (#6024, session session_01B3Kurx8qufrDzNjk4rag7V, GitHub identity hotlong).
Branch: claude/issue-7991-downstream-contract-source-alias · dispatch: mode:subagent, model: claude-opus-5.

The card is already a complete brief — it demonstrates the defect with a three-step measurement whose direction was predicted before running, names the fix, names the trap (anchored regex / array form; the object form matches by prefix and swallows @objectstack/spec/ui into spec/src/index.ts/ui), and states that removing the KNOWN_UNALIASED_TEST_IMPORTS entry is part of the change rather than cleanup. This seat adds nothing to any of that.

Taking the prioritisation argument as stated. Every other one of the 63 registry entries produces a wrong verdict about its own package; this one produces a wrong verdict about whether the repo is shipping a breaking change to spec — on the one suite built to answer that question. That is a different category, and it is why this jumps the sweep.

The one thing the card leaves open, ruled here

Expect the suite to go red once aliased if any real narrowing has landed in spec since the last dist build. That is the gate starting to work, not a regression introduced by this card.

Correct — and it leaves the executor with an operational question they are likely to hit. Ruling: if the aliased suite goes red, report and stop.

• ⛔ Do not fix the spec narrowing inside this card. A red here means the repo has been shipping a breaking change to its highest-churn package while the gate said otherwise. That is a maintainer-level finding with its own blast radius, not a rider on a tooling fix.
• ⛔ Do not weaken the fixture, loosen an assertion, or re-freeze it against current behaviour to get green. The fixture is frozen because it represents a published-spec consumer; re-freezing it converts the gate back into the no-op this card exists to remove — the same failure wearing a fresh commit.
• Report what the red says: which schema, which field, which direction it narrowed. I will decide whether it becomes a separate card this PR waits behind.

Coming back red with a precise diagnosis is a success outcome. This lane has closed three "green that checked nothing" cards today (#7685's probe, #7362's harness, #7848's zero-match glob); the discipline is identical here — a gate that cannot fail is worse than no gate, because it is consumed as evidence.

Same treatment for the dual-instance / circular-import caveat the card carries verbatim from PR #7966's dev: if aliasing surfaces a problem the dist boundary was hiding, that is a finding in its own right — report it, and ⛔ do not widen the registry to make it go away.

Pin

Whatever lands must make the demonstration in the card body executable: the injected-required-field scenario that passes 14/14 today has to fail once aliased. If you cannot show that flip, the alias is not on the resolution path you think it is.

---

Generated by Claude Code