downstream-contract's OTHER half — its typecheck — still resolves @objectstack/spec types through dist, so a narrowed export type reads green (measured)

[hotlong]

Filing unassigned; found while implementing #7991, and deliberately not fixed there (that card's scope is the vitest resolution path, and its ruling is to report adjacent exposure rather than widen).

Context

packages/qa/downstream-contract is the repo's backward-compatibility gate for @objectstack/spec. Its README states the gate has two halves:

• pnpm --filter @objectstack/downstream-contract typecheck — the fixtures are typed with real spec author-state types (Action, Report, Page, ...). A removed or narrowed export fails here (the fix(examples): typecheck example apps clean + gate in CI #2023 class of break).
• pnpm --filter @objectstack/downstream-contract test — runs each bare-literal fixture through its schema's .parse() ...

#7991 fixed the second half: it shipped no vitest.config.*, so the suite resolved @objectstack/spec through exports to dist/ and reported 14/14 green against a source-only break of its own fixture. The first half has the same exposure and is untouched by that fix.

Measured

packages/qa/downstream-contract/tsconfig.json sets moduleResolution: NodeNext and declares no paths, so tsc resolves @objectstack/spec through the workspace link and the exports map — i.e. dist/index.d.mts, a build artifact.

Injected into source only, no rebuild (packages/spec/src/integration/connector.zod.ts), a narrowing that the frozen DcConnector fixture cannot satisfy:

- label: z.string().describe('Display label'),
+ label: z.number().describe('TEMPORARY TYPE PROBE — was z.string()'),

DcConnector is declared const DcConnector: Connector and assigns label: 'DC HubSpot', so with source types this is a type error. Result:

> @objectstack/downstream-contract@0.0.38-rc.5 typecheck
> tsc --noEmit
(clean, exit 0)

Green — the exact shape of #7991, one layer over: the verdict is about the last pnpm build, not about the spec in the checkout. (Probe reverted; the source file was verified byte-identical afterwards.)

Ordering does not reach it, same as #7991

turbo.json orders typecheck after ^build, so CI's pnpm typecheck measures a fresh dist and is not the failing path. What breaks is every path turbo does not mediate: pnpm --filter ... typecheck in the package, an editor's TS server, or an agent in a tree built at an older commit — the paths this gate is re-read on while someone is changing the spec.

The judgment this needs (why it is a card, not a one-liner)

A paths mapping to ../../spec/src fixes the resolution, but it changes what the fixture type-checks against: generated .d.ts versus source types are not always identical, and a real third party does consume the published types. That argument was already weighed and rejected for the runtime half — the fixture's purpose is to answer "would the spec in this checkout break a published-spec consumer" — so consistency points the same way here, but it is a deliberate decision about the gate's meaning, plus whatever type errors the switch surfaces on first run.

Prior art (searched before filing)

• 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 #7991 — the runtime half; this is the same defect on the sibling command.
• 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 measure the runtime half repo-wide. Type resolution is outside their scope: check:test-source-alias reads vitest.config.*, not tsconfig.json.
• Three more dist-reading spec gates carry the same unenforced freshness precondition as gen:api-surface #7181 (closed) — three dist-reading spec gates with unenforced freshness preconditions; same family, different surfaces.
• check:dev-prereqs 只判 dist 存在性,#5726 的「陈旧 dist」那半边仍无门禁 —— 而绿灯现在会提供反向保证 #5864 (closed) — check:dev-prereqs checks dist existence only.

Nothing open covers the type half of this package.

---

Generated by Claude Code

[hotlong]

Triage: lands in packages/qa/downstream-contract (tsconfig type-resolution path) → domain:cli (packages/qa); queued pm:queue.

Ruling inheritance (same family, no new decision opened): the gate's meaning was already weighed and ruled for the runtime half under #7991 — the fixture answers "would the spec in this checkout break a published-spec consumer". Consistency extends the same ruling and its reasoning to the type half. If the switch surfaces a genuinely branch-specific fact (generated .d.ts vs source types producing errors that change the gate's meaning rather than just its verdicts), report it on-card instead of absorbing it — that is the one condition under which this stops being an inherited ruling.

Serial constraint: #7991 is in flight in the same package — hard-serialize behind it; do not co-batch. Re-price after #7991 merges (its PR may reshape the config surface this card edits).

---

Generated by Claude Code

[hotlong]

Serial block cleared — claimed and dispatched. domain:cli PM seat (#6024), session session_01B3Kurx8qufrDzNjk4rag7V, branch claude/issue-8021-downstream-contract-typecheck-source.

PR #8129 (#7991) has merged, so this package's other half is done and the file is free. #7991 fixed the runtime resolution (vitest.config.ts aliasing @objectstack/spec to source); this card is the typecheck half, which still resolves spec types through dist/*.d.ts — so a narrowed export type reads green exactly the way a narrowed export value used to.

Carrying forward what #7991 established, because it is directly reusable and was measured rather than assumed:

• ⛔ Anchored regex / array form only, never the object form. The object form matches by prefix, so a bare @objectstack/spec entry swallows @objectstack/spec/ui into spec/src/index.ts/ui (ENOTDIR). Prefer one subpath rule covering every namespace over enumerating them, so it cannot go stale as fixtures reach new subpaths. test(qa): make the spec backward-compatibility gate read spec source, not spec dist #8129's packages/qa/downstream-contract/vitest.config.ts is the shape to follow.
• ⛔ The demonstration must be executable, not historical. 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 #7991's deliverable was the flip proven with one variable moved: same checkout, same stale dist, only the alias added, 14/14 green → 1 failed/13 passed naming the injected field. This card needs the type-level equivalent — inject a narrowing into a spec export type in source only, no rebuild, and show typecheck passing before and failing after. If that flip cannot be shown, the alias is not on the resolution path and the card is not done.
• ⛔ If it goes red on a genuine narrowing already in spec — report and STOP. Do not fix the narrowing here, and do not weaken the fixture or re-freeze it to get green; that converts the gate back into the no-op this family of cards exists to remove. Coming back red with a precise diagnosis is a success outcome.
• Dual-instance / circular-import problems the dist boundary was hiding are findings, not obstacles. 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 #7991 found one (defineConnector was two different objects across two entry points through dist, filed as @objectstack/spec ships 18 self-contained entry bundles with no shared chunks, so a consumer mixing entry points gets different ConnectorSchema / defineConnector objects (measured) #8133) — ⛔ do not widen any registry to make one go away.

---

Generated by Claude Code