feat(analytics): add Source discriminated union with Fallback.Reason (SDK-79)

[tylerjroach]

Summary

• New Source discriminated union (com.mixpanel.mixpanelapi.featureflags.model.Source): Source.Local | Source.Remote | Source.Fallback(Reason). Abstract class + nested static finals — Java 8 source level so no sealed keyword.
• Source.Fallback.Reason enum: FLAG_NOT_FOUND | MISSING_CONTEXT_KEY | NO_ROLLOUT_MATCH | BACKEND_ERROR | NOT_READY. Constants align with mixpanel-php.
• SelectedVariant.getSource() replaces the prior variantSource string field. isFallback() now checks source instanceof Source.Fallback.
• LocalFlagsProvider and RemoteFlagsProvider tag every returned variant: matches with Source.local() / Source.remote(), fallbacks with Source.fallback(reason) carrying the specific reason.

Why

Three behaviorally distinct outcomes — flag-not-found, no-rollout-match, and missing-context-key — previously all returned the bare fallback. A future OpenFeature wrapper (in openfeature-provider/) can now dispatch on the reason and map each to the spec-correct error code instead of collapsing them all to FLAG_NOT_FOUND.

Discriminated union rather than two flat fields because the language is type-safe enough to model it that way; invalid states like "successful evaluation with a fallback reason" are unrepresentable.

Cross-SDK fix tracked at Linear SDK-79. Constant set matches mixpanel-php so callers across SDKs see the same vocabulary.

Follow-up PR

The openfeature-provider module needs a matching update to dispatch on Source.Fallback.Reason — that PR depends on this one shipping in a new mixpanel-java release first (the provider consumes the published Maven coordinate). It'll come right after release.

Test plan

• 172 tests pass (mvn test -Dgpg.skip=true)
• Existing LocalFlagsProviderTest (53) and RemoteFlagsProviderTest (8) continue passing — the isFallback() contract is preserved
• SelectedVariant.equals() updated to include source
• Wrapper PR pending base SDK release (Phase 2)

🤖 Generated with Claude Code

[linear-code]

SDK-79

[rahul-mixpanel]

Four recommendations left as inline comments — one high, one medium, two low priority.

[tylerjroach]

Thanks for the review — pushed a58a93d. Threads addressed:

1. HIGH — Source.Fallback equals/hashCode (line 82): Added. Two Source.fallback(REASON) instances now compare structurally so SelectedVariant.equals() works correctly. Local / Remote stay singleton, so reference equality is structural equality for them.
2. MEDIUM — isSuccess / isFallback semantic change (SelectedVariant.java:80): Kept the source-based check — the Source is the canonical source-of-truth for whether something is a fallback, and variantKey != null was a proxy that breaks if a caller hands a key-bearing object as the fallback. Added a Javadoc note explaining the intent.
3. LOW — NOT_READY unused (line 73): Removed entirely in 4e4d08c — the wrapper handles PROVIDER_NOT_READY via areFlagsReady() before invoking the provider, so no producer would construct it. Same cleanup landed across the other server SDKs (Python / Ruby / Node / Go).
4. LOW — Source.toString() (line 56): Added on all three subclasses. Now prints Local / Remote / Fallback(FLAG_NOT_FOUND) instead of Source$Fallback@1a2b3c.
5. LOW — Missing @param Javadoc (SelectedVariant.java:46): Restored on both the 5-arg and 6-arg constructors.

Mirrored on mixpanel-android (PR #981, commit 9f89b3c0) — same Java-class structure had the same equals/toString gap on Persistence and Fallback. Other SDKs aren't affected: Swift uses if case pattern matching (no Equatable needed); Python / Ruby / Node / Go use structural value types that already compare correctly.