feat: Add the FDv2 cache initializer and per-context freshness to the client

[beekld]

Summary

Adds an FDv2 cache initializer so the client can begin evaluating from its local per-context cache before the network responds, and tracks how fresh each context's cached data is.

• A cache hit produces a full basis with no selector. The cached flags are applied so evaluation can begin, but the missing selector keeps them from becoming a delta basis, so initialization continues to a network source for verified data and a real selector. A miss produces a "none" result, and the next initializer runs.
• Cache-sourced data is marked so it is not written back to the cache it came from.
• The client records a freshness timestamp per context, keyed by a hash of the full context, updated when a payload arrives or a "none" intent confirms the current data, and persisted alongside the cached flags.

Design note: this client persists a per-context freshness timestamp keyed by a hash of the full context, matching Android. Flutter's FDv2 freshness is different -- an in-memory, per-synchronizer timestamp that is neither persisted nor keyed by context.

Internal only. Not user-selectable yet.

---

Note

Overview
Adds an FDv2 cache initializer that hydrates the flag store from per-context persistence before network init: a hit yields a full changeset without a selector (so cached data can be evaluated but not used as a delta basis), and a miss yields a none intent so the initializer chain continues. The factory marks itself via IsFromCache() for orchestration.

Flag persistence gains ReadCached / ReadFreshness, exposes the cache through FlagManager::Cache(), and tracks service-confirmed freshness in a separate ContextFreshness index keyed by a hash of the full context (not just the key). Network Apply paths record freshness on payloads and on none confirmations; from_cache applies still update the store but do not write back or record freshness. ReadFreshness is suppressed when flag data for the context is no longer cached, including after LRU eviction edge cases.

Docs/comments on IDataSourceUpdateSink::Apply clarify cache-sourced semantics. Tests cover the cache initializer and freshness/eviction behavior.

^{Reviewed by Cursor Bugbot for commit 60b04ea. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit fc7d735. Configure here.}

[cursor]

Freshness outlives overwritten flag data

Medium Severity

ReadFreshness treats any cached flags for the context's CanonicalKey as proof the stored timestamp still describes that data. Flag data is keyed only by that key, while freshness is keyed by a hash of the full context, so a later payload for the same key with different attributes overwrites the flags and leaves the earlier timestamp in place. ReadFreshness then reports the old time for the new data, which can make a poll wait on evaluations that were never confirmed for this attribute set.

Additional Locations (2)

• libs/client-sdk/src/flag_manager/flag_persistence.cpp#L117-L123
• libs/client-sdk/src/flag_manager/flag_persistence.cpp#L66-L71

 

^{Reviewed by Cursor Bugbot for commit fc7d735. Configure here.}