feat: add provider-side event emission helper

[mtonko-flx]

Stacked on #260 (→ #259 → #258). Base is main because the branch lives in a fork and GitHub requires a base branch in the upstream repository, so the diff shown here includes the parents' commits. Review only the last commit, feat: add provider-side event emission helper.

Intent

Now that a provider can own its lifecycle events by implementing StateManagingProvider, doing so by hand is more work than it looks: hold an event flow, pick a replay policy that does not lose a readiness report emitted before the SDK has finished subscribing, keep emissions ordered under concurrency, and coalesce context reconciliations that overlap so an intermediate one does not surface as a spurious update. This adds ProviderEventEmitter so provider authors do not each reimplement it.

Motivation

Appendix E's migration guidance asks providers to emit readiness, failure and reconciliation events themselves, and spells out the coalescing rule as prose. Every provider author hitting that will write the same flow plumbing, and the failure modes are quiet ones — a lost readiness report leaves the SDK waiting, and an uncoalesced reconciliation publishes updates the application should never have seen.

This is the helper referred to in the migration path; it does not satisfy any requirement by itself.

Spec Requirements

Requirement	Relationship
2.8.1–2.8.4	Enables provider conformance — ordered emission around the lifecycle methods
5.3.4.1–5.3.4.3	Enables provider conformance — reconciliation events, coalesced per Appendix E
5.1.4, 5.1.5	Enables — error reports carry message and error code

Changes

Implementation

• observe() — the stream to return from StateManagingProvider.observe(), replaying its most recent event so a readiness report is not lost to a subscription still in progress.
• emit(event) — ordered reporting for transitions that arise on their own, such as going stale or recovering.
• initializing { … } — reports ready on success, error on failure, then rethrows.
• reconciling { … } — reports that reconciliation began, then its outcome, coalescing overlapping invocations so only the first announces and only the last reports. Where every invocation was cancelled it re-reports the transition that preceded reconciliation, rather than leaving the SDK reconciling with nothing further coming.

It holds no status. The provider owns its events and the SDK derives the status from them, which is the distinction #385 chose over #380, so there is deliberately nothing here to read or set.

Usage Examples

class MyProvider : StateManagingProvider {
    private val emitter = ProviderEventEmitter()

    override fun observe(): Flow<OpenFeatureProviderEvents> = emitter.observe()

    override suspend fun initialize(initialContext: EvaluationContext?) =
        emitter.initializing { client.connect(initialContext) }

    override suspend fun onContextSet(oldContext: EvaluationContext?, newContext: EvaluationContext) =
        emitter.reconciling { client.refresh(newContext) }

    fun onConnectionLost() = emitter.emit(OpenFeatureProviderEvents.ProviderStale())
}

Testing

• Ready on success; error reported before the exception propagates, carrying the originating error code.
• A readiness report survives a subscriber that attaches afterwards.
• Reconciliation brackets its outcome; overlapping reconciliations announce once and report once, at the last completion.
• A failed reconciliation reports the error and rethrows.
• Cancelling every reconciliation in flight re-reports the preceding transition — and a stateless event such as PROVIDER_CONFIGURATION_CHANGED is not what gets re-reported.
• Spontaneous reports keep their order.
• 260 tests, ktlintCheck and apiCheck green, apiDump regenerated.

Breaking Changes

None — new public type, nothing existing changes. Using it is optional; a provider can implement StateManagingProvider with its own flow.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

_{Comment @coderabbitai help to get the list of available commands.}

[mtonko-flx]

Superseded by #262, which delivers this work as a single change. Closing the stack.