fix(providers): point each export condition's types at its own declaration

[sroussey]

The real count: 25 branches, 9 manifests

Not ~24 ./ai entries in providers — 25 condition branches across 9 workspace manifests, and they are not all in providers/*:

where	branches
providers/* (8 packages × ./ai + ./ai-runtime, minus cactus's already-correct ./ai)	15
packages/workglow (9 provider re-export shims + ./worker)	10

Affected providers: openai, ollama, xai, deepseek, openrouter, llamacpp-server, stable-diffusion-server, cactus.

Shape in providers/*: the "browser" block loads ./dist/ai.browser.js but types it with ./dist/ai.d.ts. packages/workglow's nine shims are the same shape; its ./worker is the inverse — the default branch loads worker-node.js but types it with worker-browser.d.ts.

providers/anthropic, google-gemini, huggingface-inference, huggingface-transformers, mlx, node-llama-cpp have no browser condition at all and are unaffected. tf-mediapipe, chrome-ai, cloudflare have a browser block that points at the same files as the default — redundant, but internally consistent, so untouched.

Phase 1 classification — do the surfaces actually differ?

I compared the resolved export surface (not the text) of each emitted X.d.ts against X.browser.d.ts using the TypeScript checker — the emitted files are one-line export * from … stubs, so a textual diff is meaningless.

Type-surface difference (live bug) — 7 branches:

branch	node-only symbols
openai/ai	_testOnly, registerOpenAiImageValidator, OpenAI_ModelSearch_Stream
ollama/ai	_testOnly
ollama/ai-runtime	createOllamaTextGenerationStream, createOllamaStructuredGenerationStream
xai/ai	_testOnly, Xai_ModelSearch_Stream
deepseek/ai	assertNotTruncatedByReasoning, resolveMaxTokens, DEEPSEEK_DEFAULT_REASONING_ALLOWANCE, DeepSeekToolChoiceNotHonoredError, assertToolChoiceHonored, isForcingToolChoice, _testOnly, DeepSeek_ModelSearch_Stream
openrouter/ai	10 symbols (_testOnly, OPENROUTER_RUN_FN_SPECS, fetchOpenRouterModels, mapOpenRouterModels, OpenRouterRawModel, OPENROUTER_FALLBACK_MODELS, …)
cactus/ai-runtime	same names, different signature for getCactusModelCacheInfo

Same surface (wrong pointer, currently harmless) — 18 branches: openai/ai-runtime, xai/ai-runtime, deepseek/ai-runtime, openrouter/ai-runtime, both llamacpp-server entries, both stable-diffusion-server entries (their ai.ts and ai.browser.ts are byte-identical), and all 10 packages/workglow branches (its shims are byte-identical pass-throughs — the browser/node split really happens one layer down, in the provider's own exports map). No branch is browser-only or has a browser-superset surface: node ⊇ browser everywhere.

The difference is real at runtime, not just in the declarations. Importing both openai bundles and diffing Object.keys:

node-only runtime exports: [ "OpenAI_ModelSearch_Stream", "_testOnly", "registerOpenAiImageValidator" ]
browser-only runtime exports: []

Phase 1 — build and consumers

Per-condition declarations are already emitted; no build change is needed. Each package's tsconfig.json uses include: ["src/**/*"] with emitDeclarationOnly, so tsgo produces a .d.ts for every source file — dist/ai.browser.d.ts and dist/worker-node.d.ts all exist after a clean build. The browser .js bundles come from an existing per-package build-browser script (wired into build-js / build-package), which I initially missed by reading only build-code. Verified by listing dist/ after bun run build:packages: all eight providers and packages/workglow emit both .js and .d.ts for both targets. This is a manifest-only fix.

Nothing in-repo depends on the mismatch. customConditions: ["browser"] appears in exactly one place, examples/web/tsconfig.json, and that app does not reference any affected provider. Everything else (root tsconfig.json, tsconfig.typecheck.json, vitest) resolves under the default conditions, which are unchanged. packages/test imports _testOnly from these providers under the default condition — unaffected.

Phase 2 — decision

Point each condition's types at its own emitted declaration. The evidence rules out the cheaper options: 7 branches have genuinely different export surfaces, so "browser and node share a type surface" is factually false and documenting it would be wrong; and they should differ (the browser entries deliberately omit node-only test hooks and model-search code), so collapsing them onto one shared surface would be a product regression, not a de-drift. The fix costs nothing to build because the per-target declarations are already emitted, and I applied it uniformly to all 25 branches — including the 18 that agree today — because "identical right now" is exactly the state the seven divergent ones were in before they drifted. No package needed different treatment.

Phase 3 — the guard

packages/test/src/test/util/ExportTypesPairing.test.ts walks every condition branch (recursively, so nested conditions are covered) of every {packages,providers,examples}/*/package.json and asserts each types equals its sibling import/require/default with .js → .d.ts. Three assertions: the pairing invariant; a non-vacuity check (>50 branches found, so a broken scan can't pass silently); and a staleness check on the allowlist. ALLOWED_MISMATCHES is empty and documented as such — no legitimate exception exists today.

A short paragraph was added to docs/technical/19-build-system.md's "Conditional Exports" section stating the invariant and naming the guard.

Consumer-visible type surface change — yes

For the 7 divergent branches, browser builds now see the browser type surface. Downstream code importing a node-only symbol under the browser condition will start failing to compile. That is the point of the fix: those symbols were already undefined at runtime in a browser bundle, so the old behavior was a silent runtime failure dressed up as a clean compile. The other 18 branches are a no-op for consumers.

Verified

Everything below was run in this worktree and observed to pass:

• bun install — clean.
• bun run build:types — 41/41 tasks successful.
• bun run build:packages — 81/81 tasks successful.
• npx vitest run packages/test/src/test/util/ExportTypesPairing.test.ts — 3/3 passed.
• Negative check on the guard: reverted providers/openai's ./ai browser types back to ./dist/ai.d.ts → the test failed with the exact branch named (providers/openai/package.json exports["./ai"] [browser]: types="./dist/ai.d.ts" but implementation is "./dist/ai.browser.js"); restored, test passes again.
• Targeted typecheck proving corrected resolution: a probe importing { OPENAI, _testOnly } from "@workglow/openai/ai", compiled twice with moduleResolution: bundler. After the fix — under customConditions: ["browser"]: TS2305: Module '"@workglow/openai/ai"' has no exported member '_testOnly'; under default conditions: exit 0. Before the fix, the browser-condition compile exited 0 — i.e. it silently accepted a symbol that does not exist in the browser bundle.
• npx vitest run packages/test/src/test/util/ — 45 files, 669 passed / 6 skipped.
• Provider tests that consume _testOnly at runtime (OpenAI_ReasoningTemperature, ProviderUsageNormalization, CrossProviderRefusals) — 50/50 passed, confirming runtime resolution is untouched (types is a TypeScript-only condition).
• npx eslint on the new test — clean. prettier --check on the new test and all changed manifests — clean; docs/technical/19-build-system.md reports a pre-existing prettier warning that is present on main before my edit (unrelated table/JSON formatting), so I left it rather than adding reformatting churn.
• git status checked after every command; no stray manifest rewrites (bun run use-source was never invoked).

Not verified: I did not run the full repo test suite (only the util section plus the three provider tests above), and I did not build a downstream browser app against the corrected types — the compile-condition probe is the evidence for that path.

---

🤖 Generated with Claude Code

---

Generated by Claude Code

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	59.8%	37385 / 62509
🔵	Statements	59.32%	39228 / 66127
🔵	Functions	60.71%	7245 / 11933
🔵	Branches	48.07%	19038 / 39599

File Coverage

No changed files found.

Generated in workflow #3092 for commit d53f0ba by the Vitest Coverage Report Action