Optional shared cache contract for local feature flag definitions.

Configure a provider as {module, provider_state} using :flag_definition_cache_provider. The definition loader bounds and isolates every callback. Cached values must be maps containing flags, group_type_mapping, and cohorts (string or atom keys are accepted). Preserve the complete envelope, including property_matching_version, with the definitions. Only version 2 selects explicit property matching; older cached envelopes omitting the version use released service legacy matching.

With a project :api_key and local evaluation enabled, a provider can supply definitions without a :secret_key. These cache-only readers read the provider on each refresh without invoking the fetch decision or publishing definitions. Instances with a secret key consult the fetch decision: true fetches and publishes fresh definitions, while false reads the cache. An empty or failed cache preserves loaded definitions; a keyed instance without definitions can recover by fetching directly. Provider-backed instances use the same startup, polling, and refresh lifecycle.

A minimal provider can coordinate fetching and keep the complete envelope in an application-owned cache:

defmodule MyApp.PostHogDefinitionCache do
  @behaviour PostHog.FeatureFlags.FlagDefinitionCacheProvider

  def should_fetch_flag_definitions(state), do: state.fetch_owner?.()
  def get_flag_definitions(state), do: state.read.()
  def on_flag_definitions_received(state, definitions), do: state.write.(definitions)
  def shutdown(_state), do: :ok
end

config :posthog,
  api_key: System.fetch_env!("POSTHOG_PROJECT_TOKEN"),
  flag_definition_cache_provider: {MyApp.PostHogDefinitionCache, provider_state}