feat: supply the bound domain to provider initialization

[jonathannorris]

Amends provider initialization so the domain a provider is bound to is supplied to its initialize function, letting providers scope domain-specific behavior (such as partitioning a persistent cache) to that domain.

Motivation

Provider-level persistent caches (e.g. the OFREP web provider's local persistence) currently have no way to know which domain they're bound to, so two providers on the same storage partition can collide on cache entries even though OpenFeature's domain model is supposed to keep them isolated. See slack thread, open-feature/js-sdk-contrib#1566, and ADR 0009.

A follow-up OFREP ADR will add the domain to the cache key.

Changes

Two parts, both kept language-agnostic so implementations can use overloads, optional arguments, etc.:

Supply the bound domain to init (folded into the existing init requirements, per earlier review feedback):

• 2.4.1 (provider): the initialize function accepts the global evaluation context and the bound domain (if any).
• 1.1.2.2 (API): the provider mutator MUST supply the bound domain (if any) when invoking initialize.

Let a provider declare it's domain-scoped, enforced by the API (new requirements):

• 2.4.3 (provider): a provider MAY declare itself domain-scoped when it holds per-domain state such as a persistent cache.
• 1.1.8 (condition) / 1.1.8.1 (API): when a provider is domain-scoped, the provider mutator MUST NOT bind it to more than one domain, and rejects any attempt to do so.

Resolved

The earlier open question (a provider bound to multiple domains is initialized once and receives only its first binding's domain) is now addressed for stateful providers: declaring domain-scoped restricts the instance to a single domain, so the domain it keys on is unambiguous. Stateless providers are unaffected and can still back multiple domains.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The specification is extended to add domain parameter passing to provider initialization, define domain-scoped provider semantics, and constrain domain-scoped providers to single-domain binding. The provider initialize function now accepts both the evaluation context and nullable bound domain. The provider mutator requirement is updated to invoke initialize with the bound domain when registering a new provider. A new domain-scoped provider declaration and corresponding binding constraints are introduced to prevent the same domain-scoped provider instance from being bound to multiple domains. Both Markdown source files and specification.json are updated.

Changes

Domain scoping for provider initialization and binding

Layer / File(s)	Summary
Provider initialize signature update specification/sections/02-providers.md, specification.json	Requirement 2.4.1 and its JSON counterpart are updated so initialize accepts a nullable domain argument alongside initialContext, with documentation on one-time initialization semantics for multi-domain binding and default-provider behavior when unbound.
Provider mutator domain-passing requirement specification/sections/01-flag-evaluation.md, specification.json	Requirement 1.1.2.2 and its JSON counterpart are updated to require that the provider mutator calls initialize with the bound domain before using a newly registered provider to resolve flag values.
Domain-scoped provider declaration specification/sections/02-providers.md, specification.json	Requirements 2.4.3 and 2.4.4 are added defining the optional domain-scoped declaration for providers maintaining domain-specific state, specifying that such providers must accept the bound domain during initialization and bind to at most one domain for unambiguous state isolation.
Domain-scoped provider binding constraints specification/sections/01-flag-evaluation.md, specification.json	Conditional Requirement 1.1.8.1 is added specifying that domain-scoped provider instances cannot bind to multiple domains, that per-domain state is keyed to the domain passed into initialize, and that additional-binding attempts must be rejected. Requirement 1.8.4 is updated to clarify that only non-domain-scoped providers may be registered to multiple domains within a single API instance.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: amending provider initialization to supply the bound domain parameter.
Description check	✅ Passed	The description comprehensively explains the motivation, changes, and resolution, directly relating to the specification updates documented in the changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

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

[MattIPv4]

Thank you :) this looks good to me

[lukas-reining]

Looks good to me!

[jonathannorris]

Pushed an update adding a domain-scoped provider declaration, based on the #openfeature-js thread.

The point that a provider isn't 1:1 with a domain is fair, so rather than relying on providers to use the bound domain correctly, this makes it an enforced contract:

• 2.4.3: a provider MAY declare itself domain-scoped when it holds per-domain state (like a persistent cache).
• 1.1.8 / 1.1.8.1: when declared, the API MUST NOT bind that instance to more than one domain.

Stateless providers are unaffected and can still back multiple domains; only opt-in providers are constrained. This also resolves the open question about a shared instance only seeing its first domain.

OFREP cache key construction lives in the follow-up ADR: open-feature/protocol#80.

[jonathannorris]

Added 2.4.4: a domain-scoped provider MUST accept the bound domain at initialization. The domain-scoped declaration is only meaningful if the provider actually consumes the domain to scope its state, so this makes that an explicit contract rather than leaving it implied.

I kept it as a provider-side MUST rather than an API-enforced check, since whether the API can detect a violation varies and we can't rely on surfacing it as an error consistently.

[toddbaert]

I made one very small change to fix some wording that was a bit redundant, nothing substantive.