Skip to content

Adopt spec #385 Phase 1: reframe provider-status citations, audit provider events - #342

Merged
EtaCassiopeia merged 2 commits into
mainfrom
fix/issue-332
Aug 5, 2026
Merged

Adopt spec #385 Phase 1: reframe provider-status citations, audit provider events#342
EtaCassiopeia merged 2 commits into
mainfrom
fix/issue-332

Conversation

@EtaCassiopeia

Copy link
Copy Markdown
Owner

Phase 1 of adopting OpenFeature spec v0.9.0's provider state ownership via events (spec#385). No runtime behaviour changes — comments, docs and tests only.

Why the citations were stale

v0.9.0 removed requirements 1.7.6 / 1.7.7, which said a client MUST short-circuit evaluation when the provider is NOT_READY/FATAL, and renumbered the equivalent gherkin scenarios to @spec-2.2.7 (+ @spec-1.4.10).

This library still short-circuits, and that is unchanged. What changes is the justification: it is now deliberate library policy, permitted rather than required. Removing the gate would alter the published 1.0.0 error contract (typed ProviderNotReady/ProviderFatal, with transaction overrides and cached evaluations deliberately bypassing it) for no spec gain, since the gherkin asserts the same observable outcomes either way. Evaluations in Error still proceed — a transient blip must not become an outage.

Every stale citation across core/, testkit/, extras/ and docs/ is reframed. Two references remain in the conformance README, deliberately: they record the pre-rename numbering so a future re-sync can trace it, and a note says so. CHANGELOG.md mentions are release history and stay as written.

Provider event audit

docs/providers.md gains a per-provider table of lifecycle-event emission, audited against the spec's appendix-e-migrations.md. The audit corrected three things the issue's own draft table got wrong:

  • CircuitBreakerProvider emits its own READY/STALE on breaker transitions, not just forwarding;
  • CachingReasonProvider extends EventProvider but never attaches, so it drops the delegate's events (same limitation as DeferredProvider) — the draft said it forwarded them;
  • HoconProvider, EnvVarProvider and IntegerWideningLongProvider were missing from the table entirely.

Why provider-side emission is deferred

No bundled provider emits init-time events, deliberately. Until the Java SDK ships the opt-in marker it keeps synthesizing them, so a provider emitting its own would duplicate. The spec calls such duplicates "expected legacy behavior" — but that concerns the SDK's derived status, and it does not hold here. Two new characterization tests in ProviderStatusBridgeSpec pin the asymmetry:

  • the status machine absorbs a duplicate READY (one transition);
  • the event hub delivers both to user handlers.

So emitting early would surface duplicate PROVIDER_READY in user code — a visible regression. If Phase 2 flips the second test to observe 1, that is the deliberate change, and the test makes it impossible to miss. Phase 2 is filed as #340 (blocked on java-sdk), and four watch-point comments in the code point at it.

Verification

scalafmtCheckAll, core 509 tests, testkit 199 tests, conformance/test 113/113, conformanceZioBdd/test 113/113, +mimaReportBinaryIssues — all green. A repo-wide grep for the removed requirement numbers returns only the intended survivors.

Closes #332

@EtaCassiopeia
EtaCassiopeia merged commit d438103 into main Aug 5, 2026
10 checks passed
@EtaCassiopeia
EtaCassiopeia deleted the fix/issue-332 branch August 18, 2026 19:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Adopt spec #385: provider state ownership via events

1 participant