refactor(core): share the oauth state failure union and fold callback narrowing

[tyler-dane]

What and why

Technical-debt cleanup in the OAuth callback analytics added by #4588 and partly reworked by #4617. No behavior change for any outcome the mapper reports today.

A duplicated type that could only drift. #4588 added oauthCallbackFailureReason to packages/core with a hand-copied "malformed" | "invalidSignature" | "expired" | "stateMismatch" union mirroring OAuthStateFailure in packages/sync/src/oauth/oauth-state.ts. Core cannot import sync, so nothing tied the two together: adding a fifth state-verification failure in sync would leave the analytics mapper unable to accept it, and widening the inline copy by hand would let the two definitions disagree silently. This moves the union into connection.contracts beside the other consent-flow contracts, as a Zod enum like its ConnectionStateReason sibling, and has both the verifier and the analytics mapper read it from there. One definition, correct dependency direction.

state and code were each narrowed from unknown twice, with different idioms (typeof x === "string" ? x : null in the declined branch, typeof x === "string" && x.length > 0 in the error branch). Each callback value is now narrowed once up front through asNonEmptyString. This is behavior-preserving: oauthFailedReasonFromCallbackQuery already tests state and code falsily, so "" took the absent path under both idioms. The inconsistency was the kind that eventually becomes a bug, not one today.

isTokenExchangeFailure and providerErrorFromExchange repeated the same object guard and the same cast, and were only ever called together on the same input. They fold into one tokenExchangeFailure, whose result now routes through withProviderError like every other branch in the function. That also drops the one inconsistency with real effect: the token-exchange branch built its result literal by hand, so a ProviderAuthError carrying no reason sent an explicit provider_error: undefined to PostHog instead of omitting the property.

Added regression tests for the folded paths: a reasonless exchange failure, a non-ProviderAuthError on the exchange path, blank state/code, and the invalidSignature/expired mapping.

Verify

bun run verify --strict
Selected packages: core, sync
Checks run: test:core, test:sync:fast, type-check, lint, knip
Checks skipped: (none)
VERDICT: PASS

---

Generated by Claude Code

[github-actions]

Boot bundle: 509.8 KB gzip (+0.0 KB vs main)