docs: add ADR 0009 for static-context cache-first local persistence

[jonathannorris]

Summary

• add ADR 0009 proposing local persistence with local-cache-first initialization for static-context OFREP providers
• on startup, providers load cached evaluations immediately so initial flag evaluations never return defaults, then refresh from the network in parallel
• define local-cache-first and cache-miss initialization paths mapped to the OpenFeature provider lifecycle (PROVIDER_READY, PROVIDER_CONFIGURATION_CHANGED)
• introduce a cacheMode option with local-cache-first (default), network-first, and disabled values so applications can opt into blocking-on-fresh-evaluation when appropriate (e.g., SPAs)
• cache key uses hash(targetingKey), or hash(cacheKeyPrefix + ":" + targetingKey) when a cacheKeyPrefix is configured for multi-provider deployments

Motivation

Every major vendor SDK (LaunchDarkly, Statsig, DevCycle, Eppo) uses local-cache-first initialization by default. Current OFREP static-context providers keep their cache in memory only, losing all state on restart. See vendor mobile SDK caching research for a detailed comparison.

Some applications (most notably SPAs that already block rendering behind a splash screen) prefer to wait for a fresh evaluation rather than risk cached values shifting under the user. The cacheMode: "network-first" option supports that pattern while still using cached values as a fallback when the network is unavailable.

Notes

This PR replaces #64 which was closed due to a branch rename. All review feedback from #64 has been addressed.

Related

• Closes OFREP Static-Context Provider Local Persistence #65
• Replaces docs: add ADR 0009 for static-context cache-first local persistence #64

Test plan

• not applicable; documentation-only change

[gemini-code-assist]

Code Review

This pull request introduces ADR 0009, which proposes that OFREP static-context providers persist their last successful bulk evaluation in local storage by default to enable cache-first initialization. This change aims to eliminate the 'flash-of-defaults' problem and improve offline resilience for web and mobile applications. The review feedback suggests including a version field in the storage schema for better maintainability, recommending the use of platform-specific secure storage to mitigate security risks, and establishing a default TTL for persisted entries to prevent the use of excessively stale data.

[Copilot]

Pull request overview

Adds a new Architecture Decision Record (ADR-0009) describing cache-first startup with local persistence for OFREP static-context providers, to preserve last-known flag evaluations across restarts/offline startup and align provider lifecycle events with OpenFeature expectations.

Changes:

• Introduces ADR 0009 defining persisted cache contents (payload, ETag, cache-key hash, write time).
• Documents cache-hit vs cache-miss initialization flows, including background refresh and provider lifecycle/event mapping.
• Adds implementation notes and open questions (multi-context caching, TTL).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[toddbaert]

I approved #64 previously. Reviewed the diff between the two; the key changes I see:

• cacheKeyPrefix is now folded into the hash itself 👍
• Auth/config errors (401/403/400) no longer clear the persisted cache; TTL handles eventual expiry instead
• TTL is promoted from an open question to a recommendation
• storage write failure stuff (log and continue)

All of these seem like improvements to me. LGTM.

The flickering concern is still a notable tradeoff. cc @beeme1mr

[lukas-reining]

Looks good to me! Left some minor questions.

[beeme1mr]

Overall, I like the proposal. I just kept thinking about how I'd prefer it if the Provider evaluated the flags before falling back to the cached values. It would be nice if that were at least a configuration option. The reason I think this may be important is that some apps may not respond to flag changes and therefore continue using the old values for the duration of the session. Even ones that do react run the risk of the screen jitting when flag values change shortly after page load.

[jonathannorris]

Pushed some updates after a discussion with @beeme1mr on the network-first use case.

Summary of changes

For mobile and most web apps, local-cache-first is clearly the right default (eliminates the flash-of-defaults problem, matches vendor SDK behavior). But for some web use cases, particularly SPAs that already block rendering behind a splash screen, it makes more sense to block initialization on a fresh evaluation rather than flash cached values that might shift under the user.

To support both patterns, the ADR now defines a single cacheMode option with three values:

• local-cache-first (default): the original described behavior of the ADR, load from cache immediately and refresh in the background
• network-first: Simiar to the existing behaviour with a local-cache backup. initialize() awaits the network response using the existing timeoutMs. On success, fresh values only. On network failure, 5xx, or timeout, fall back to the persisted cache if one exists. Auth/config errors (401/403/400) emit PROVIDER_ERROR fatal without falling back to cache
• disabled: no persistence at all, in-memory cache only, initialize() blocks on the network

The earlier disableLocalCache boolean is replaced by cacheMode: \"disabled\". Since nothing has implemented the ADR yet (still Proposed), the rename is non-breaking.

Other tweaks

• Added `Alternatives Considered` entries documenting why we chose a single enum over two booleans, and why we didn't go with platform-specific defaults
• Added guidance that apps using `network-first` should consider lowering `timeoutMs` from the default so users aren't stuck on a loading state when the network is unavailable
• Clarified fallback semantics in the cache matching section: `network-first` only falls back to cache on network errors, never on auth errors

cc @lukas-reining @guidobrei @toddbaert @beeme1mr @erka

[lukas-reining]

Looks good to me!