e2e-smoke asserts the .d.ts exists but never type-checks it — sdk-server.d.ts now references an optional peer dep

[yakimoto]

Follow-up to #76 (closed #75), filed against my own gate.

#76 turned on declaration emission and added a check that every declared types target is present in the tarball. That check asserts the file exists. It does not assert the file resolves — which is the only thing a consumer experiences.

A peer caught the consequence in d2f8b96: src/sdk-server.ts:12 does

import type { McpSdkServerConfigWithInstance } from "@anthropic-ai/claude-agent-sdk";

and that package is an optional peer dependency:

"peerDependencies":     { "@anthropic-ai/claude-agent-sdk": ">=0.3.0" },
"peerDependenciesMeta": { "@anthropic-ai/claude-agent-sdk": { "optional": true } }

While dts: false meant nothing was emitted, that type reference never reached anyone. Now that sdk-server.d.ts is real, a consumer who installs @wave-av/mcp-server without the optional peer and type-checks @wave-av/mcp-server/sdk-server will fail to resolve McpSdkServerConfigWithInstance.

This is a general point about the change, not a regression: turning a dormant code path on is a behaviour change, and everything inside it becomes reachable for the first time.

What the gate should do instead

Add a smoke arm that type-checks the installed tarball from the consumer's side, without optional peers present — which is exactly the install shape the existing smoke already creates:

1. In the throwaway project the smoke already builds, write a tiny .ts that imports both the root and ./sdk-server.
2. Run tsc --noEmit against it with a minimal tsconfig.
3. Fail on unresolved types.

That converts existsSync into a real assertion. It would have caught this before merge.

Open question worth deciding first

Which behaviour do we actually want?

• (a) Accept it — the ./sdk-server subpath is documented as requiring the peer, so failing to type-check without it is correct. Then the smoke arm should install the peer before checking that subpath, and check the root without it.
• (b) Make the types self-contained — inline or re-declare the config type so sdk-server.d.ts has no hard reference to an optional package. Costs a duplicated type, buys a package that type-checks standalone.

I lean (a): the peer is genuinely required to use that entry point, so requiring it to type-check that entry point is honest. But it should be a decision, not an accident, and the CHANGELOG note from d2f8b96 should say which one we chose.

Related: #75, #76.

[yakimoto]

Resolved by #78 — went with (a).

The gate now asserts the root entry type-checks without the optional peer and ./sdk-server type-checks with it, by installing the real packed tarball into two separate throwaway projects and running tsc --noEmit against each. It deliberately does not assert that ./sdk-server fails without the peer, so switching to (b) later would not break the gate.

Proven with negative controls before pushing — in both, the old types ok line prints green immediately above the new failure, which is the whole finding:

NC1  peer leaked into a root-reachable declaration  -> root arm FAILS   (types ok: green)
NC2  subpath declaration points at a missing module -> sdk arm FAILS    (types ok: green)
NC3  arm with no compiler installed                 -> fails loudly, no vacuous pass
happy path on unmodified HEAD                       -> both arms green

CHANGELOG now records which option was chosen and why, as this issue asked.