Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

153 KB
Raw Blame
use crate::api::errors::FlagError;
use crate::api::types::{FlagDetails, FlagValue, FlagsResponse, FromFeatureAndMatch};
use crate::cohorts::cohort_cache_manager::CohortCacheManager;
use crate::cohorts::cohort_models::{Cohort, CohortId, CohortMembership, MembershipStampPolicy};
use crate::cohorts::cohort_operations::{
    apply_cohort_membership_logic, evaluate_dynamic_cohorts, record_stamp_policy_divergence,
};
use crate::cohorts::membership::{CohortMembershipProvider, NoOpCohortMembershipProvider};
use crate::database::{pool_names, PostgresRouter};
use crate::flags::config_v2::{Config, NonV1Config};
use crate::flags::evaluate_v2::{
    Evaluation, EvaluationContext, EvaluationDetail, Evaluator, PersonProperties,
};
use crate::flags::flag_group_type_mapping::{
    GroupTypeCacheManager, GroupTypeIndex, GroupTypeMapping,
};
use crate::flags::flag_match_reason::FeatureFlagMatchReason;
use crate::flags::flag_matching_utils::{
    calculate_hash, db_operations, failed_flag_dependency,
    fetch_and_locally_cache_all_relevant_properties, get_feature_flag_hash_key_overrides,
    match_flag_value_to_flag_filter, populate_missing_initial_properties, populate_os_aliases,
    set_feature_flag_hash_key_overrides, should_write_hash_key_override, track_unretried_db_error,
};
use crate::flags::flag_models::{
    default_has_experiment, FeatureFlag, FeatureFlagId, FeatureFlagList, FlagFilters,
    FlagPropertyGroup,
};
use crate::flags::flag_operations::flags_require_db_preparation;
use crate::handler::canonical_log::{install_rayon_canonical_log, take_rayon_canonical_log};
use crate::handler::with_canonical_log;
use crate::metrics::consts::{
    DB_PERSON_AND_GROUP_PROPERTIES_READS_COUNTER, FLAG_BATCH_EVALUATION_COUNTER,
    FLAG_BATCH_EVALUATION_TIME, FLAG_BATCH_SIZE, FLAG_COHORT_SOURCE_COUNTER,
    FLAG_CONDITION_SKIPPED_COUNTER, FLAG_DB_PROPERTIES_FETCH_TIME,
    FLAG_EVALUATE_ALL_CONDITIONS_TIME, FLAG_EVALUATION_ERROR_COUNTER, FLAG_EVALUATION_TIME,
    FLAG_EXPERIENCE_CONTINUITY_OPTIMIZED, FLAG_EXPERIENCE_CONTINUITY_REQUESTS_COUNTER,
    FLAG_GET_MATCH_TIME, FLAG_GROUP_CACHE_FETCH_TIME, FLAG_GROUP_DB_FETCH_TIME,
    FLAG_HASH_KEY_PROCESSING_TIME, FLAG_HASH_KEY_WRITES_COUNTER,
    FLAG_REALTIME_COHORT_QUERY_ERROR_COUNTER, FLAG_REALTIME_COHORT_QUERY_TIME,
    PROPERTY_CACHE_HITS_COUNTER, PROPERTY_CACHE_MISSES_COUNTER,
};
use crate::properties::property_matching::{match_property, PropertyMatchingContext};
use crate::properties::property_models::{PropertyFilter, PropertyType};
use crate::rayon_dispatcher::RayonDispatcher;
use crate::utils::deadline::before_deadline;
use crate::utils::graph_utils::PrecomputedDependencyGraph;
use anyhow::Result;
use chrono::{DateTime, Utc};
use chrono_tz::Tz;
use common_metrics::{histogram, inc, timing_guard, timing_guard_high_precision};
use common_types::collections::HashMapExt;
use common_types::{PersonId, TeamId};
use rayon::prelude::*;
use serde_json::Value;
use std::collections::{HashMap, HashSet};
use std::future::Future;
use std::sync::Arc;
use tokio::time::Instant;
use tracing::{debug, error, instrument, warn};
use uuid::Uuid;

const DEFAULT_PARALLEL_EVAL_THRESHOLD: usize = 100;

/// Parameters for feature flag evaluation with various override options
#[derive(Debug, Default)]
pub struct FlagEvaluationOverrides {
    pub person_property_overrides: Option<HashMap<String, Value>>,
    pub group_property_overrides: Option<HashMap<String, HashMap<String, Value>>>,
    pub hash_key_overrides: Option<HashMap<String, String>>,
    pub hash_key_override_error: bool,
    /// The request's anon_distinct_id, used as a fallback for EEC flags when no DB override exists
    pub request_hash_key_override: Option<String>,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum EvaluationType {
    Sequential,
    Parallel,
}

impl EvaluationType {
    pub const fn as_str(self) -> &'static str {
        match self {
            EvaluationType::Sequential => "sequential",
            EvaluationType::Parallel => "parallel",
        }
    }

    /// Promote evaluation type across dependency levels:
    /// None → Sequential, None → Parallel, Sequential → Parallel.
    /// Parallel is sticky — once set, it never demotes back to Sequential.
    pub fn promote(current: Option<Self>, level_type: Self) -> Option<Self> {
        match (current, level_type) {
            (_, Self::Parallel) => Some(Self::Parallel),
            (None, Self::Sequential) => Some(Self::Sequential),
            (current, Self::Sequential) => current,
        }
    }
}

impl std::fmt::Display for EvaluationType {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.as_str())
    }
}

#[derive(Debug, PartialEq, Eq, Clone)]
pub struct FeatureFlagMatch {
    pub matches: bool,
    pub variant: Option<String>,
    pub reason: FeatureFlagMatchReason,
    pub condition_index: Option<usize>,
    pub payload: Option<Value>,
    /// Set only by `get_match_v2`; the v4 record is built from it.
    pub evaluation_v2: Option<EvaluationDetail>,
}

impl FeatureFlagMatch {
    pub fn get_flag_value(&self) -> FlagValue {
        match (self.matches, &self.variant) {
            (true, Some(variant)) => FlagValue::String(variant.clone()),
            (true, None) => FlagValue::Boolean(true),
            (false, _) => FlagValue::Boolean(false),
        }
    }

    /// Creates a match result for flags with missing dependencies.
    /// These flags evaluate to `false` (fail closed) with the `MissingDependency` reason.
    pub fn missing_dependency() -> Self {
        Self {
            matches: false,
            variant: None,
            reason: FeatureFlagMatchReason::MissingDependency,
            condition_index: None,
            payload: None,
            evaluation_v2: None,
        }
    }
}

/// Tracks person property state through the evaluation lifecycle.
///
/// Combines fetch status with property data so that impossible states (e.g. "fetched"
/// but no properties) are unrepresentable. When request overrides cover all needed keys,
/// DB prep is skipped and this stays `Skipped`. When DB prep runs, properties are stored
/// directly in the `Fetched` variant.
#[derive(Clone, Debug, Default)]
pub(crate) enum PersonPropertyState {
    /// DB prep has not yet run (initial state)
    #[default]
    Pending,
    /// DB prep was skipped because request overrides covered all needed property keys
    Skipped,
    /// DB prep ran and populated person properties
    Fetched(HashMap<String, Value>),
}

/// Outcome of the group type mapping lookup for a request.
///
/// The mapping resolves a group type index to the name the request keys its `groups` by, so
/// without it there is no way to tell "the caller sent no group of this type" from "the lookup
/// failed". Keeping the failure in the same value as the mapping stops those two from being
/// answered independently — see `FeatureFlagMatcher::filter_needs_partial_props`.
#[derive(Clone, Debug, Default)]
enum GroupTypeMappingState {
    /// The lookup has not run for this request (initial state)
    #[default]
    Uninitialized,
    /// The lookup ran and returned a mapping, which may be empty for a team with no group types
    Loaded(GroupTypeMapping),
    /// The lookup ran and failed
    Failed(Arc<FlagError>),
}

impl GroupTypeMappingState {
    fn mapping(&self) -> Option<&GroupTypeMapping> {
        match self {
            Self::Loaded(mapping) => Some(mapping),
            _ => None,
        }
    }
}

/// This struct maintains evaluation state by caching database-sourced data during feature flag evaluation.
/// It stores person IDs, properties, group properties, and cohort matches that are fetched from the database,
/// allowing them to be reused across multiple flag evaluations within the same request without additional DB lookups.
///
/// The cache is scoped to a single evaluation session and is cleared between different requests.
#[derive(Clone, Default, Debug)]
pub struct FlagEvaluationState {
    /// The person ID associated with the distinct_id being evaluated
    person_id: Option<PersonId>,
    /// The person UUID, needed for realtime cohort membership lookups
    person_uuid: Option<Uuid>,
    /// Person property fetch state: pending, skipped, or fetched (with property data)
    person_property_state: PersonPropertyState,
    /// Properties for each group type whose properties DB prep ran for this evaluation.
    ///
    /// The key set carries the group-level analogue of `PersonPropertyState`: a missing index
    /// means the fetch never ran, so nothing about that group type's properties is known. A
    /// present index means the fetch ran and its map is authoritative, so an empty map means
    /// the group genuinely has no properties (no `posthog_group` row).
    group_properties: HashMap<GroupTypeIndex, HashMap<String, Value>>,
    /// Cohorts for the current request, shared via `Arc` either from the
    /// preloaded hypercache slice or wrapped from a `CohortCacheManager`
    /// fetch.
    cohorts: Option<Arc<[Cohort]>>,
    /// Cache of cohort membership results (both static and realtime) to avoid repeated lookups.
    /// Static results come from `posthog_cohortpeople`, realtime results from `cohort_membership`.
    /// The two sources produce disjoint key sets partitioned by `CohortType`.
    cohort_matches: Option<HashMap<CohortId, bool>>,
    /// Cache of flag evaluation results to avoid repeated DB lookups
    flag_evaluation_results: HashMap<FeatureFlagId, FlagValue>,
    failed_flag_ids: HashSet<FeatureFlagId>,
}

impl FlagEvaluationState {
    pub fn get_person_id(&self) -> Option<PersonId> {
        self.person_id
    }

    pub fn get_person_properties(&self) -> Option<&HashMap<String, Value>> {
        match &self.person_property_state {
            PersonPropertyState::Fetched(props) => Some(props),
            _ => None,
        }
    }

    /// True when person-property DB prep never ran (neither fetched nor deliberately
    /// skipped in favor of overrides). Distinct from `Skipped`, where overrides are
    /// known to cover every property the batch needs — see `PersonPropertyState`.
    pub(crate) fn person_properties_pending(&self) -> bool {
        matches!(self.person_property_state, PersonPropertyState::Pending)
    }

    pub fn get_group_properties(&self) -> &HashMap<GroupTypeIndex, HashMap<String, Value>> {
        &self.group_properties
    }

    pub fn get_cohort_matches(&self) -> Option<&HashMap<CohortId, bool>> {
        self.cohort_matches.as_ref()
    }

    pub fn get_person_uuid(&self) -> Option<Uuid> {
        self.person_uuid
    }

    pub fn set_person_id(&mut self, id: PersonId) {
        self.person_id = Some(id);
    }

    pub fn set_person_uuid(&mut self, uuid: Uuid) {
        self.person_uuid = Some(uuid);
    }

    pub fn set_person_properties(&mut self, properties: HashMap<String, Value>) {
        self.person_property_state = PersonPropertyState::Fetched(properties);
    }

    pub fn skip_person_properties(&mut self) {
        self.person_property_state = PersonPropertyState::Skipped;
    }

    pub fn set_cohorts(&mut self, cohorts: Arc<[Cohort]>) {
        self.cohorts = Some(cohorts);
    }

    pub fn set_group_properties(
        &mut self,
        group_type_index: GroupTypeIndex,
        properties: HashMap<String, Value>,
    ) {
        self.group_properties.insert(group_type_index, properties);
    }

    /// Record that group-property DB prep ran for this group type, without disturbing
    /// properties already stored for it. Must be called for every requested index once the
    /// fetch succeeds, including indexes the query returned no row for — an empty map there
    /// is an authoritative "this group has no properties", not a missing fetch.
    pub fn mark_group_properties_fetched(&mut self, group_type_index: GroupTypeIndex) {
        self.group_properties.entry(group_type_index).or_default();
    }

    /// True when group-property DB prep never ran for this group type, so an absent
    /// key in the resolved property map carries no information — see `group_properties`.
    pub(crate) fn group_properties_pending(&self, group_type_index: GroupTypeIndex) -> bool {
        !self.group_properties.contains_key(&group_type_index)
    }

    pub fn set_cohort_matches(&mut self, matches: HashMap<CohortId, bool>) {
        self.cohort_matches = Some(matches);
    }

    /// Merge additional cohort membership results into the existing map.
    /// Used to add realtime cohort results after static results are already set.
    pub fn merge_cohort_matches(&mut self, additional: HashMap<CohortId, bool>) {
        match &mut self.cohort_matches {
            Some(existing) => existing.extend(additional),
            None => self.cohort_matches = Some(additional),
        }
    }

    pub fn add_flag_evaluation_result(&mut self, flag_id: FeatureFlagId, flag_value: FlagValue) {
        self.flag_evaluation_results.insert(flag_id, flag_value);
    }

    fn failed_dependency(&self, filter: &PropertyFilter) -> Option<FeatureFlagId> {
        failed_flag_dependency(filter, &self.flag_evaluation_results, &self.failed_flag_ids)
    }

    /// Returns true when no single value of some failed flag satisfies all of the filters on that
    /// flag, for example `true` together with `false`, or two different variants.
    /// `is_condition_match` passes each filter on a failed flag on its own. This check finds the
    /// conflict that those separate passes miss.
    fn failed_dependency_filters_conflict(&self, filters: &[PropertyFilter]) -> bool {
        let mut filters_by_flag: HashMap<FeatureFlagId, Vec<&PropertyFilter>> = HashMap::new();
        for filter in filters {
            if let Some(flag_id) = self.failed_dependency(filter) {
                filters_by_flag.entry(flag_id).or_default().push(filter);
            }
        }
        filters_by_flag
            .into_iter()
            .any(|(flag_id, filters_on_flag)| {
                if filters_on_flag.len() < 2 {
                    return false;
                }
                let variants = filters_on_flag
                    .iter()
                    .filter_map(|filter| match &filter.value {
                        Some(Value::String(variant)) => Some(FlagValue::String(variant.clone())),
                        _ => None,
                    });
                // A variant that no filter names passes the same filters as `true`.
                let can_match = [FlagValue::Boolean(false), FlagValue::Boolean(true)]
                    .into_iter()
                    .chain(variants)
                    .any(|value| {
                        let results = HashMap::from([(flag_id, value)]);
                        filters_on_flag
                            .iter()
                            .all(|filter| match_flag_value_to_flag_filter(filter, &results))
                    });
                !can_match
            })
    }
}

#[derive(Debug, PartialEq)]
enum ConditionAnswer {
    Match(Option<String>),
    NoMatch,
}

impl ConditionAnswer {
    fn is_match(&self) -> bool {
        matches!(self, ConditionAnswer::Match(_))
    }
}

struct AnswerIfDependencyMatched {
    failed_dependency: FeatureFlagId,
    answer: ConditionAnswer,
}

static EMPTY_PROPERTY_MAP: std::sync::LazyLock<HashMap<String, Value>> =
    std::sync::LazyLock::new(HashMap::new);

/// Bundles references to the property maps and aggregation mode needed during
/// condition matching. A condition may reference both person and group properties
/// (mixed targeting), so this struct carries both sources and routes each filter
/// to the correct one.
pub(crate) struct PropertyContext<'a> {
    pub person_properties: Option<&'a HashMap<String, Value>>,
    pub group_properties: &'a HashMap<GroupTypeIndex, HashMap<String, Value>>,
    pub aggregation: Option<GroupTypeIndex>,
    pub request_has_group_context: bool,
}

impl PropertyContext<'_> {
    /// Resolves the correct property map for a filter based on its type. Person filters
    /// use person properties, group filters use the group properties for the filter's
    /// `group_type_index`. Falls back to aggregation mode for legacy filters without
    /// an explicit type distinction.
    pub fn resolve_for_filter(&self, filter: &PropertyFilter) -> &HashMap<String, Value> {
        match filter.prop_type {
            // PersonMetadata fields (e.g. created_at) are injected into the same map as
            // regular person properties; see the `result.person` block in
            // `apply_person_cohort_to_state` (flag_matching_utils.rs).
            PropertyType::Person | PropertyType::PersonMetadata => {
                self.person_properties.unwrap_or(&*EMPTY_PROPERTY_MAP)
            }
            PropertyType::Group => filter
                .group_filter_index(self.aggregation)
                .and_then(|idx| self.group_properties.get(&idx))
                .unwrap_or(&*EMPTY_PROPERTY_MAP),
            PropertyType::Cohort | PropertyType::Flag => match self.aggregation {
                Some(gti) => self
                    .group_properties
                    .get(&gti)
                    .unwrap_or(&*EMPTY_PROPERTY_MAP),
                None => self.person_properties.unwrap_or(&*EMPTY_PROPERTY_MAP),
            },
        }
    }
}

/// Evaluates feature flags for a specific user/group context.
///
/// This struct maintains the state and logic needed to evaluate feature flags, including:
/// - User identification (distinct_id, team_id)
/// - Database connections for fetching data
/// - Caches for properties, cohorts, and group mappings to optimize performance
/// - Evaluation state that persists across multiple flag evaluations in a request
///
/// The matcher is typically created once per request and can evaluate multiple flags
/// efficiently by reusing cached data and DB connections.
#[derive(Clone)]
pub struct FeatureFlagMatcher {
    /// Unique identifier for the user/entity being evaluated
    pub distinct_id: String,
    /// Optional device identifier for device-level bucketing
    pub device_id: Option<String>,
    /// Team ID for scoping flag evaluations
    pub team_id: TeamId,
    /// Router for database connections across persons/non-persons pools
    pub router: PostgresRouter,
    /// Cache manager for cohort definitions and memberships
    pub cohort_cache: Arc<CohortCacheManager>,
    /// Shared in-process cache for group type mappings
    group_type_cache: Arc<GroupTypeCacheManager>,
    /// Outcome of the group type mapping lookup for the current team, fetched once per
    /// request via `group_type_cache`.
    group_type_mapping: GroupTypeMappingState,
    /// State maintained during flag evaluation, including cached DB lookups
    pub(crate) flag_evaluation_state: FlagEvaluationState,
    /// Group key mappings for group-based flag evaluation
    /// Maps group type name to the group key (identifier customer supplies for the group)
    /// ex. "project" → "123"
    ///     "organization" → "456"
    ///     "instance" → "789"
    ///     "customer" → "101"
    ///     "team" → "112"
    groups: HashMap<String, Value>,
    /// Flag count threshold for switching from sequential to parallel evaluation.
    /// Configured via PARALLEL_EVAL_THRESHOLD env var in production.
    parallel_eval_threshold: usize,
    /// Dispatcher for bounded-concurrency Rayon batch evaluation.
    /// `None` in tests that don't exercise the parallel path.
    rayon_dispatcher: Option<RayonDispatcher>,
    /// When true, skip all writes to PostgreSQL and Redis.
    skip_writes: bool,
    /// Keys of flags whose variant neither the caller nor any evaluated flag reads. A failed
    /// dependency fails one of these flags only when it could change whether the flag matches.
    /// Every other flag keeps the variant comparison.
    enabled_only_flag_keys: HashSet<String>,
    /// Flag IDs that should be skipped during evaluation.
    /// Populated once per request from `FeatureFlagList::filtered_out_flag_ids`.
    pub(crate) filtered_out_flag_ids: HashSet<i32>,
    /// Provider for realtime/behavioral cohort membership lookups.
    /// Queries the behavioral cohorts database for cohorts with CohortType::Realtime or Behavioral.
    cohort_membership_provider: Arc<dyn CohortMembershipProvider>,
    /// Whether to enable realtime cohort evaluation.
    /// When false, realtime cohorts are treated as non-members.
    enable_realtime_cohort_evaluation: bool,
    use_explicit_exact_matching: bool,
    membership_stamp_policy: MembershipStampPolicy,
    /// Cohort definitions preloaded from the flags hypercache.
    /// When present, scoped to only the cohorts referenced by flags (including transitive deps),
    /// so the matcher skips the CohortCacheManager PG query entirely.
    /// `None` means no preloaded data (PG fallback or old cache) — use CohortCacheManager.
    preloaded_cohorts: Option<Arc<[Cohort]>>,
    /// Whether to include detailed condition analysis in flag evaluation results.
    detailed_analysis: bool,
    /// Whether to only use person properties from request payload, ignoring database properties.
    only_use_override_person_properties: bool,
    /// Team timezone used to interpret naive datetime filter values (IS_DATE_* and
    /// relative dates), so flag evaluation matches HogQL/ClickHouse cohort behavior.
    /// Parsed once per request and reused across every property comparison.
    timezone: Tz,
    /// Request evaluation time. Only v2 relative-date predicates read it; tests pin it.
    now: DateTime<Utc>,
    /// Every persons DB call in this evaluation fails once this instant passes. `None` leaves
    /// each call bounded only by the pool acquire timeout and statement_timeout.
    persons_db_deadline: Option<Instant>,
}

/// Lightweight snapshot of a flag's identity fields, saved before moving
/// flags into the Rayon pool. Used to reconstruct per-flag error results
/// if the rayon task panics.
struct FlagSnapshot {
    key: String,
    id: FeatureFlagId,
    version: Option<i32>,
    /// Keeps a v2 flag's error record labelled v2.
    non_v1: Option<Arc<NonV1Config>>,
}

impl FlagSnapshot {
    pub fn from_flag(flag: &FeatureFlag) -> Self {
        FlagSnapshot {
            key: flag.key.clone(),
            id: flag.id,
            version: flag.version,
            non_v1: flag.filters.non_v1.clone(),
        }
    }
}

/// Mirrors Python's `add_local_person_and_group_properties` so flag conditions
/// matching on `distinct_id` evaluate without a DB lookup. Always injects the
/// request `distinct_id` (including `""`) unless an explicit
/// `person_property_overrides["distinct_id"]` is already present, in which case
/// the explicit override wins.
fn merge_distinct_id_into_person_properties(
    distinct_id: &str,
    overrides: Option<HashMap<String, Value>>,
) -> HashMap<String, Value> {
    let mut overrides = overrides.unwrap_or_default();
    overrides
        .entry("distinct_id".to_string())
        .or_insert_with(|| Value::String(distinct_id.to_string()));
    overrides
}

fn ids_of_failed_flags<'a>(
    details: impl Iterator<Item = &'a FlagDetails> + 'a,
) -> impl Iterator<Item = FeatureFlagId> + 'a {
    details
        .filter(|details| details.failed)
        .map(|details| details.metadata.id)
}

fn is_usable_group_key(group_key: &Value) -> bool {
    match group_key {
        Value::String(s) => !s.is_empty(),
        Value::Number(_) => true,
        _ => false,
    }
}

// This is a plain fn rather than an `async fn` so that it boxes `call` before any async state
// captures it. An `async fn` would store `call` in its own state. The `before_deadline` and
// `timeout_at` futures store it again. In debug builds those copies grow the /flags handler
// future enough to overflow a 2 MiB thread stack.
fn before_persons_db_deadline<T>(
    deadline: Option<Instant>,
    operation: &'static str,
    call: impl Future<Output = Result<T, FlagError>>,
) -> impl Future<Output = Result<T, FlagError>> {
    let call = Box::pin(call);
    async move {
        let result = before_deadline(deadline, call, FlagError::persons_db_deadline).await;
        record_persons_db_deadline_exceeded(operation, &result);
        result
    }
}

fn record_persons_db_deadline_exceeded<T>(operation: &'static str, result: &Result<T, FlagError>) {
    let Err(e) = result else {
        return;
    };
    if !e.is_persons_db_deadline() {
        return;
    }
    track_unretried_db_error(e, operation);
    with_canonical_log(|log| {
        log.persons_db_deadline_exceeded.get_or_insert(operation);
    });
}

/// The one place a failed flag is built, so the request outcome sees every failure.
fn failed_flag_details(flag: &FeatureFlag, error: &FlagError) -> FlagDetails {
    with_canonical_log(|log| log.outcome_marks.mark_flag_failed(error));
    FlagDetails::create_error(flag, error, None)
}

impl FeatureFlagMatcher {
    #[allow(clippy::too_many_arguments)]
    pub fn new(
        distinct_id: String,
        device_id: Option<String>,
        team_id: TeamId,
        router: PostgresRouter,
        cohort_cache: Arc<CohortCacheManager>,
        group_type_cache: Arc<GroupTypeCacheManager>,
        groups: Option<HashMap<String, Value>>,
    ) -> Self {
        FeatureFlagMatcher {
            distinct_id,
            device_id,
            team_id,
            router,
            cohort_cache,
            group_type_cache,
            group_type_mapping: GroupTypeMappingState::default(),
            groups: groups.unwrap_or_default(),
            flag_evaluation_state: FlagEvaluationState::default(),
            cohort_membership_provider: Arc::new(NoOpCohortMembershipProvider),
            parallel_eval_threshold: DEFAULT_PARALLEL_EVAL_THRESHOLD,
            rayon_dispatcher: None,
            skip_writes: false,
            enabled_only_flag_keys: HashSet::new(),
            filtered_out_flag_ids: HashSet::new(),
            enable_realtime_cohort_evaluation: false,
            use_explicit_exact_matching: false,
            membership_stamp_policy: MembershipStampPolicy::default(),
            preloaded_cohorts: None,
            detailed_analysis: false,
            only_use_override_person_properties: false,
            timezone: Tz::UTC,
            now: Utc::now(),
            persons_db_deadline: None,
        }
    }

    pub fn with_now(mut self, now: DateTime<Utc>) -> Self {
        self.now = now;
        self
    }

    /// Sets the team timezone used to interpret naive datetime filter values.
    /// Defaults to UTC; production must thread the team's timezone through so flag
    /// evaluation agrees with HogQL/ClickHouse cohort membership near day boundaries.
    pub fn with_timezone(mut self, timezone: Tz) -> Self {
        self.timezone = timezone;
        self
    }

    pub fn with_parallel_eval_threshold(mut self, threshold: usize) -> Self {
        self.parallel_eval_threshold = threshold;
        self
    }

    pub fn with_rayon_dispatcher(mut self, dispatcher: RayonDispatcher) -> Self {
        self.rayon_dispatcher = Some(dispatcher);
        self
    }

    pub fn with_skip_writes(mut self, skip_writes: bool) -> Self {
        self.skip_writes = skip_writes;
        self
    }

    pub fn with_enabled_only_flag_keys(mut self, flag_keys: HashSet<String>) -> Self {
        self.enabled_only_flag_keys = flag_keys;
        self
    }

    pub fn with_cohort_membership_provider(
        mut self,
        provider: Arc<dyn CohortMembershipProvider>,
    ) -> Self {
        self.cohort_membership_provider = provider;
        self
    }

    pub fn with_realtime_cohort_evaluation(mut self, enable: bool) -> Self {
        self.enable_realtime_cohort_evaluation = enable;
        self
    }

    pub fn with_explicit_exact_matching(mut self, enable: bool) -> Self {
        self.use_explicit_exact_matching = enable;
        self
    }

    pub fn with_membership_stamp_policy(mut self, policy: MembershipStampPolicy) -> Self {
        self.membership_stamp_policy = policy;
        self
    }

    pub fn with_detailed_analysis(mut self, detailed_analysis: bool) -> Self {
        self.detailed_analysis = detailed_analysis;
        self
    }

    pub fn with_only_use_override_person_properties(mut self, only_use_override: bool) -> Self {
        self.only_use_override_person_properties = only_use_override;
        self
    }

    /// Gives all persons DB work in this evaluation one shared deadline.
    pub fn with_persons_db_deadline(mut self, deadline: Option<Instant>) -> Self {
        self.persons_db_deadline = deadline;
        self
    }

    /// Evaluates all feature flags for the current matcher context.
    ///
    /// ## Arguments
    ///
    /// * `feature_flags` - The list of feature flags to evaluate.
    /// * `person_property_overrides` - Any overrides for person properties.
    /// * `group_property_overrides` - Any overrides for group properties.
    /// * `hash_key_override` - Optional hash key overrides for experience continuity.
    /// * `optimize_experience_continuity_lookups` - When true, skip lookups for flags that don't need them.
    ///
    /// ## Returns
    ///
    /// * `FlagsResponse` - The result containing flag evaluations and any errors.
    #[instrument(skip_all, fields(team_id = %self.team_id, distinct_id = %self.distinct_id, flags_len = feature_flags.flags.len()))]
    #[allow(clippy::too_many_arguments)]
    pub async fn evaluate_all_feature_flags(
        &mut self,
        feature_flags: FeatureFlagList,
        person_property_overrides: Option<HashMap<String, Value>>,
        group_property_overrides: Option<HashMap<String, HashMap<String, Value>>>,
        hash_key_override: Option<String>, // Aka $anon_distinct_id
        request_id: Uuid,
        flag_keys: Option<Vec<String>>,
        optimize_experience_continuity_lookups: bool,
    ) -> Result<FlagsResponse, FlagError> {
        let eval_timer = common_metrics::timing_guard(FLAG_EVALUATION_TIME, &[]);

        let person_property_overrides = Some(merge_distinct_id_into_person_properties(
            &self.distinct_id,
            person_property_overrides,
        ));

        let precomputed = PrecomputedDependencyGraph::build(&feature_flags, flag_keys.as_deref());

        self.filtered_out_flag_ids = feature_flags.filtered_out_flag_ids;
        self.preloaded_cohorts = feature_flags.cohorts;

        let PrecomputedDependencyGraph {
            error_count,
            has_cycle_errors,
            evaluation_stages,
            flags_with_missing_deps,
        } = precomputed;

        if error_count > 0 {
            with_canonical_log(|log| log.dependency_graph_errors = error_count);
        }

        // Compute experience continuity stats from the filtered graph.
        // This considers all flags that will actually be evaluated (including dependencies).
        let (experience_continuity_count, any_flag_needs_override) = {
            let mut continuity_count = 0;
            let mut needs_override = false;

            for flag in evaluation_stages.iter().flatten() {
                if !self.filtered_out_flag_ids.contains(&flag.id)
                    && flag.has_experience_continuity()
                {
                    continuity_count += 1;
                    if !needs_override && flag.needs_hash_key_override() {
                        needs_override = true;
                    }
                }
            }

            (continuity_count, needs_override)
        };

        // Log the experience continuity count from the filtered graph
        with_canonical_log(|log| log.flags_experience_continuity = experience_continuity_count);

        let has_experience_continuity = experience_continuity_count > 0;

        // Determine if we need to do the hash key override lookup.
        // In legacy mode (optimization disabled), we always do the lookup if any flag has continuity.
        // In optimized mode, we only do it if any flag actually needs it.
        let do_hash_key_lookup = if optimize_experience_continuity_lookups {
            any_flag_needs_override
        } else {
            has_experience_continuity
        };

        // A request is optimizable when it has experience continuity flags but none require the lookup
        let request_is_optimizable = has_experience_continuity && !any_flag_needs_override;

        // Track optimization metric: status="skipped" when we skip, "eligible" when we could have
        if request_is_optimizable {
            let status = if optimize_experience_continuity_lookups {
                "skipped"
            } else {
                "eligible"
            };

            inc(
                FLAG_EXPERIENCE_CONTINUITY_OPTIMIZED,
                &[
                    ("status".to_string(), status.to_string()),
                    ("team_id".to_string(), self.team_id.to_string()),
                ],
                1,
            );
        }

        // Record when the optimization actually skips the lookup
        if request_is_optimizable && optimize_experience_continuity_lookups {
            with_canonical_log(|log| log.hash_key_override_status = Some("skipped"));
        }

        // Clone the request's hash_key_override before passing it to process_hash_key_override_if_needed
        // since we also need it for the FlagEvaluationOverrides struct
        let request_hash_key_override = hash_key_override.clone();

        // Process any hash key overrides
        let (hash_key_overrides, flag_hash_key_override_error) = self
            .process_hash_key_override_if_needed(do_hash_key_lookup, hash_key_override)
            .await;

        let overrides = FlagEvaluationOverrides {
            person_property_overrides,
            group_property_overrides,
            hash_key_overrides,
            hash_key_override_error: flag_hash_key_override_error,
            request_hash_key_override,
        };

        let flags_response = self
            .evaluate_flags_with_overrides(
                overrides,
                request_id,
                evaluation_stages,
                flags_with_missing_deps,
            )
            .await?;

        let has_errors = flag_hash_key_override_error
            || flags_response.errors_while_computing_flags
            || has_cycle_errors;

        eval_timer
            .label("outcome", if has_errors { "error" } else { "success" })
            .fin();

        Ok(FlagsResponse::new(
            has_errors,
            flags_response.flags,
            None,
            request_id,
        ))
    }

    /// Processes hash key overrides for feature flags with experience continuity enabled.
    ///
    /// This method handles the logic for managing hash key overrides, which are used to ensure
    /// consistent feature flag experiences across different distinct IDs (e.g., when a user logs in).
    /// It performs the following steps:
    ///
    /// 1. Checks if a hash key override needs to be written by comparing the current distinct ID
    ///    with the provided hash key
    /// 2. If needed, writes the hash key override to the database using the writer connection
    /// 3. Increments metrics to track successful/failed hash key override writes
    /// 4. Retrieves and returns the current hash key overrides for the target distinct IDs
    ///
    /// Returns a tuple containing:
    /// - Option<HashMap<String, String>>: The hash key overrides if successfully retrieved, None if there was an error
    /// - bool: Whether there was an error during processing (true = error occurred)
    #[instrument(skip_all, fields(team_id = %self.team_id, distinct_id = %self.distinct_id))]
    async fn process_hash_key_override(
        &self,
        hash_key: String,
        target_distinct_ids: Vec<String>,
    ) -> (Option<HashMap<String, String>>, bool) {
        let should_write = match before_persons_db_deadline(
            self.persons_db_deadline,
            db_operations::SHOULD_WRITE_HASH_KEY_OVERRIDE,
            should_write_hash_key_override(
                &self.router,
                self.team_id,
                self.distinct_id.clone(),
                hash_key.clone(),
            ),
        )
        .await
        {
            Ok(should_write) => should_write,
            Err(e) => {
                error!(
                    "Failed to check if hash key override should be written for team {} distinct_id {}: {:?}",
                    self.team_id, self.distinct_id, e
                );
                inc(
                    FLAG_EVALUATION_ERROR_COUNTER,
                    &[("reason".to_string(), e.evaluation_error_code())],
                    1,
                );
                return (None, true);
            }
        };

        let mut writing_hash_key_override = false;

        if should_write {
            if self.skip_writes {
                tracing::debug!(
                    team_id = self.team_id,
                    distinct_id = %self.distinct_id,
                    "SKIP_WRITES: skipping hash key override write to PostgreSQL"
                );
            } else {
                // NB: this is the only method that writes to the database
                if let Err(e) = before_persons_db_deadline(
                    self.persons_db_deadline,
                    db_operations::SET_HASH_KEY_OVERRIDES,
                    set_feature_flag_hash_key_overrides(
                        &self.router,
                        self.team_id,
                        target_distinct_ids.clone(),
                        hash_key.clone(),
                    ),
                )
                .await
                {
                    error!("Failed to set feature flag hash key overrides for team {} distinct_id {} hash_key {}: {:?}", self.team_id, self.distinct_id, hash_key, e);
                    inc(
                        FLAG_EVALUATION_ERROR_COUNTER,
                        &[("reason".to_string(), e.evaluation_error_code())],
                        1,
                    );
                    return (None, true);
                }
                writing_hash_key_override = true;
            }
        }

        inc(
            FLAG_HASH_KEY_WRITES_COUNTER,
            &[(
                "successful_write".to_string(),
                writing_hash_key_override.to_string(),
            )],
            1,
        );

        // When we're writing a hash_key_override, we query the main database (writer), not the replica (reader)
        // This is because we need to make sure the write is successful before we read it back
        // to avoid read-after-write consistency issues with database replication lag
        let (database_for_reading, pool_name) = if writing_hash_key_override {
            (
                self.router.get_persons_writer().clone(),
                pool_names::PERSONS_WRITER,
            )
        } else {
            (
                self.router.get_persons_reader().clone(),
                pool_names::PERSONS_READER,
            )
        };

        match before_persons_db_deadline(
            self.persons_db_deadline,
            db_operations::GET_HASH_KEY_OVERRIDES,
            get_feature_flag_hash_key_overrides(
                database_for_reading,
                pool_name,
                self.router.get_persons_writer().clone(),
                self.team_id,
                target_distinct_ids,
            ),
        )
        .await
        {
            Ok(overrides) => (Some(overrides), false),
            Err(e) => {
                error!("Failed to get feature flag hash key overrides for team {} distinct_id {}: {:?}", self.team_id, self.distinct_id, e);
                inc(
                    FLAG_EVALUATION_ERROR_COUNTER,
                    &[("reason".to_string(), e.evaluation_error_code())],
                    1,
                );
                (None, true)
            }
        }
    }

    /// Evaluates cohort filters using cached membership results (both static and realtime)
    /// and evaluates dynamic cohorts based on the provided properties.
    pub fn evaluate_cohort_filters(
        &self,
        cohort_property_filters: &[&PropertyFilter],
        target_properties: &HashMap<String, Value>,
        cohorts: Arc<[Cohort]>,
    ) -> Result<bool, FlagError> {
        // Track cohort evaluations in canonical log
        with_canonical_log(|log| log.eval.cohorts_evaluated += cohort_property_filters.len());

        let (cohort_matches, errors) =
            self.resolve_cohort_matches(cohort_property_filters, target_properties, &cohorts);

        if let Some(error) = errors.into_iter().next() {
            return Err(error);
        }

        // Apply cohort membership logic (IN|NOT_IN) to the cohort match results
        apply_cohort_membership_logic(cohort_property_filters, &cohort_matches)
    }

    /// Resolves every cohort the given filters reference to a membership boolean, starting from
    /// the memberships cached during `prepare_flag_evaluation_state` (static and realtime).
    fn resolve_cohort_matches(
        &self,
        cohort_property_filters: &[&PropertyFilter],
        target_properties: &HashMap<String, Value>,
        cohorts: &[Cohort],
    ) -> (HashMap<CohortId, bool>, Vec<FlagError>) {
        // Get cached cohort results (static + realtime, merged during prepare_flag_evaluation_state)
        let cached_matches = match self.flag_evaluation_state.get_cohort_matches() {
            Some(matches) => matches.clone(),
            None => HashMap::new(), // Happens when targeting an anonymous user with no person record
        };

        Self::resolve_cohort_matches_from_cache(
            cohort_property_filters,
            target_properties,
            cohorts,
            cached_matches,
            PropertyMatchingContext::new(self.timezone, self.use_explicit_exact_matching),
        )
    }

    /// Evaluates any dynamic cohort the filters reference that the cache does not already cover.
    ///
    /// Resolution continues past a cohort that fails, and the failures come back alongside the
    /// memberships that did resolve. A caller that must agree with the whole filter set fails on
    /// the first error; condition analysis keeps what resolved, because a cohort left out of the
    /// map reads as unknown rather than as a non-match. Both paths share this loop so a change to
    /// cohort resolution cannot reach one and miss the other.
    fn resolve_cohort_matches_from_cache(
        cohort_property_filters: &[&PropertyFilter],
        target_properties: &HashMap<String, Value>,
        cohorts: &[Cohort],
        cached_matches: HashMap<CohortId, bool>,
        matching_context: PropertyMatchingContext,
    ) -> (HashMap<CohortId, bool>, Vec<FlagError>) {
        let mut cohort_matches = cached_matches;
        let mut errors = Vec::new();

        // For any cohorts not yet evaluated (i.e., dynamic ones), evaluate them
        for filter in cohort_property_filters {
            let Some(cohort_id) = filter.get_cohort_id() else {
                errors.push(FlagError::CohortFiltersParsingError);
                continue;
            };

            if !cohort_matches.contains_key(&cohort_id) {
                let current_matches = cohort_matches.clone();
                match evaluate_dynamic_cohorts(
                    cohort_id,
                    target_properties,
                    cohorts,
                    &current_matches,
                    matching_context,
                ) {
                    Ok(match_result) => {
                        cohort_matches.insert(cohort_id, match_result);
                    }
                    Err(error) => errors.push(error),
                }
            }
        }

        (cohort_matches, errors)
    }

    /// Resolves cohort memberships for every cohort filter on the flag, for detailed condition
    /// analysis.
    ///
    /// The evaluation state caches static and realtime memberships only, because
    /// `evaluate_cohort_filters` discards the dynamic ones it resolves. Reading that cache alone
    /// would report every dynamic cohort as a non-match.
    fn cohort_matches_for_analysis(
        &self,
        flag: &FeatureFlag,
        person_properties: Option<&HashMap<String, Value>>,
    ) -> HashMap<CohortId, CohortMembership> {
        let cohort_filters: Vec<&PropertyFilter> = flag
            .filters
            .groups
            .iter()
            .filter_map(|group| group.properties.as_ref())
            .flatten()
            .filter(|filter| filter.is_cohort())
            .collect();

        if cohort_filters.is_empty() {
            return HashMap::new();
        }

        let Some(cohorts) = self.flag_evaluation_state.cohorts.clone() else {
            return HashMap::new();
        };

        let target_properties = person_properties.unwrap_or(&EMPTY_PROPERTY_MAP);

        // A condition can name a cohort the flags payload no longer carries, because Django omits
        // deleted and cross-team cohorts but keeps the filters that name them. Those failures stay
        // out of the map, so the analysis reports them as unknown instead of as a non-match.
        let (cohort_matches, errors) =
            self.resolve_cohort_matches(&cohort_filters, target_properties, &cohorts);

        for error in errors {
            warn!("Cohort left unresolved for condition analysis: {error:?}");
        }

        // A non-match on a behavioral or lifecycle cohort is the dynamic path's default, not a
        // checked answer, which is why the matcher reports it as `cohort_not_evaluated`.
        cohort_matches
            .into_iter()
            .map(|(cohort_id, is_member)| {
                let membership = if is_member {
                    CohortMembership::Member
                } else if cohorts
                    .iter()
                    .any(|cohort| cohort.id == cohort_id && cohort.has_behavioral_condition())
                {
                    CohortMembership::UnverifiedNonMember
                } else {
                    CohortMembership::NonMember
                };
                (cohort_id, membership)
            })
            .collect()
    }

    /// Evaluates feature flags with property and hash key overrides.
    ///
    /// Takes pre-computed evaluation stages which should already be filtered by flag_keys if needed.
    /// The stages determine which flags are evaluated and in what order.
    pub async fn evaluate_flags_with_overrides(
        &mut self,
        overrides: FlagEvaluationOverrides,
        request_id: Uuid,
        evaluation_stages: Vec<Vec<FeatureFlag>>,
        flags_with_missing_deps: HashSet<i32>,
    ) -> Result<FlagsResponse, FlagError> {
        let mut errors_while_computing_flags = overrides.hash_key_override_error;
        let mut evaluated_flags_map = HashMap::new();

        // Joining `filtered_out_flag_ids` pre-seeds the flag false below, like an inactive
        // flag, so a dependent's `flag_evaluates_to: false` condition still resolves.
        let mut unsupported_flag_ids: Vec<FeatureFlagId> = Vec::new();
        for flag in evaluation_stages.iter().flatten() {
            if self.filtered_out_flag_ids.contains(&flag.id) {
                continue;
            }
            if let Err(error) = flag.filters.require_supported() {
                evaluated_flags_map.insert(flag.key.clone(), failed_flag_details(flag, &error));
                unsupported_flag_ids.push(flag.id);
            }
        }
        if !unsupported_flag_ids.is_empty() {
            errors_while_computing_flags = true;
            self.filtered_out_flag_ids.extend(unsupported_flag_ids);
        }

        // Collect flags from evaluation stages for preparation steps
        let flags: Vec<&FeatureFlag> = evaluation_stages
            .iter()
            .flatten()
            .filter(|flag| flag.filters.is_supported())
            .collect();

        // Handle hash key override errors by creating error responses for flags that need experience continuity
        if overrides.hash_key_override_error && overrides.hash_key_overrides.is_none() {
            let hash_key_error = FlagError::HashKeyOverrideError;
            for flag in flags.iter().filter(|flag| {
                !self.filtered_out_flag_ids.contains(&flag.id)
                    && flag.filters.is_v1()
                    && flag.ensure_experience_continuity.unwrap_or(false)
            }) {
                evaluated_flags_map
                    .insert(flag.key.clone(), failed_flag_details(flag, &hash_key_error));
            }
        }

        // Step 1: Initialize group type mappings if needed
        errors_while_computing_flags |= self.initialize_group_type_mappings_if_needed(&flags).await;

        // Step 2: Prepare evaluation state for flags requiring DB properties
        let db_prep_errors = self
            .prepare_evaluation_state_if_needed(
                &flags,
                &overrides.person_property_overrides,
                &overrides.group_property_overrides,
                &mut evaluated_flags_map,
            )
            .await;
        errors_while_computing_flags |= db_prep_errors;

        // Pre-seed filtered-out flags as false so dependency conditions like
        // `flag_evaluates_to=false` can match against them.
        for &flag_id in &self.filtered_out_flag_ids {
            self.flag_evaluation_state
                .add_flag_evaluation_result(flag_id, FlagValue::Boolean(false));
        }

        // Step 3: Evaluate flags stage by stage in dependency order
        self.flag_evaluation_state.failed_flag_ids =
            ids_of_failed_flags(evaluated_flags_map.values()).collect();
        for stage in evaluation_stages {
            let (level_evaluated_flags_map, level_errors) = self
                .evaluate_flags_in_level(
                    stage,
                    &mut evaluated_flags_map,
                    &overrides.person_property_overrides,
                    &overrides.group_property_overrides,
                    &overrides.hash_key_overrides,
                    &overrides.request_hash_key_override,
                    &flags_with_missing_deps,
                )
                .await?;
            errors_while_computing_flags |= level_errors;
            if level_errors {
                self.flag_evaluation_state
                    .failed_flag_ids
                    .extend(ids_of_failed_flags(level_evaluated_flags_map.values()));
            }
            evaluated_flags_map.extend(level_evaluated_flags_map);
        }

        Ok(FlagsResponse::new(
            errors_while_computing_flags,
            evaluated_flags_map,
            None,
            request_id,
        ))
    }

    /// Prepares evaluation state for flags that require database properties.
    /// Returns true if there were errors during preparation.
    #[instrument(skip_all, fields(team_id = %self.team_id, distinct_id = %self.distinct_id))]
    async fn prepare_evaluation_state_if_needed(
        &mut self,
        flags: &[&FeatureFlag],
        person_property_overrides: &Option<HashMap<String, Value>>,
        group_property_overrides: &Option<HashMap<String, HashMap<String, Value>>>,
        evaluated_flags_map: &mut HashMap<String, FlagDetails>,
    ) -> bool {
        let flags_requiring_db_preparation = flags_require_db_preparation(
            flags,
            person_property_overrides
                .as_ref()
                .unwrap_or(&HashMap::new()),
            &self.filtered_out_flag_ids,
            &|filter, effective_aggregation| {
                self.group_filter_needs_db_prep(
                    filter,
                    effective_aggregation,
                    group_property_overrides.as_ref(),
                )
            },
        );

        if flags_requiring_db_preparation.is_empty() || self.only_use_override_person_properties {
            self.flag_evaluation_state.skip_person_properties();
            return false;
        }
        with_canonical_log(|log| log.outcome_marks.mark_needs_persons());

        match self
            .prepare_flag_evaluation_state(flags_requiring_db_preparation.as_slice())
            .await
        {
            Ok(_) => false,
            Err(e) => {
                self.handle_db_preparation_error(
                    &flags_requiring_db_preparation,
                    &e,
                    evaluated_flags_map,
                );
                true
            }
        }
    }

    /// Handles errors during database preparation by creating error responses for affected flags.
    fn handle_db_preparation_error(
        &self,
        flags_requiring_db_preparation: &[&FeatureFlag],
        error: &FlagError,
        evaluated_flags_map: &mut HashMap<String, FlagDetails>,
    ) {
        evaluated_flags_map.extend(
            flags_requiring_db_preparation
                .iter()
                .map(|flag| (flag.key.clone(), failed_flag_details(flag, error))),
        );

        error!(
            "Error preparing flag evaluation state for team {} distinct_id {}: {:?}",
            self.team_id, self.distinct_id, error
        );

        let reason = error.evaluation_error_code();
        inc(
            FLAG_EVALUATION_ERROR_COUNTER,
            &[("reason".to_string(), reason)],
            1,
        );
    }

    /// Evaluates a set of flags with a combination of property overrides and DB properties
    ///
    /// This function is designed to be used as part of a level-based evaluation strategy
    /// (e.g., Kahn's algorithm) for handling flag dependencies.
    ///
    /// Dispatches between sequential and parallel evaluation based on flag count.
    /// Sequential: borrows flags by reference (zero-copy).
    /// Parallel: moves owned flags into a rayon task via oneshot channel.
    #[allow(clippy::too_many_arguments)]
    #[instrument(skip_all, fields(team_id = %self.team_id, distinct_id = %self.distinct_id))]
    async fn evaluate_flags_in_level(
        &mut self,
        flags: Vec<FeatureFlag>,
        evaluated_flags_map: &mut HashMap<String, FlagDetails>,
        person_property_overrides: &Option<HashMap<String, Value>>,
        group_property_overrides: &Option<HashMap<String, HashMap<String, Value>>>,
        hash_key_overrides: &Option<HashMap<String, String>>,
        request_hash_key_override: &Option<String>,
        flags_with_missing_deps: &HashSet<i32>,
    ) -> Result<(HashMap<String, FlagDetails>, bool), FlagError> {
        let mut errors_while_computing_flags = false;
        let mut level_evaluated_flags_map = HashMap::new();

        let flags_to_evaluate: Vec<FeatureFlag> = flags
            .into_iter()
            .filter(|flag| {
                !flag.deleted
                    && flag.active
                    && !self.filtered_out_flag_ids.contains(&flag.id)
                    && !evaluated_flags_map.contains_key(&flag.key)
            })
            .collect();

        let eval_type = if flags_to_evaluate.len() >= self.parallel_eval_threshold {
            EvaluationType::Parallel
        } else {
            EvaluationType::Sequential
        };

        // Record evaluation type in canonical log for E2E latency metrics.
        // Skip if no flags to evaluate (all deleted, filtered out, or already evaluated) — lets the
        // metric label stay None → "none" rather than incorrectly reporting Sequential.
        if !flags_to_evaluate.is_empty() {
            with_canonical_log(|log| {
                log.evaluation_type = EvaluationType::promote(log.evaluation_type, eval_type);
            });
        }

        let labels = [("evaluation_type".to_string(), eval_type.to_string())];
        histogram(FLAG_BATCH_SIZE, &labels, flags_to_evaluate.len() as f64);
        inc(FLAG_BATCH_EVALUATION_COUNTER, &labels, 1);
        let _batch_timer = timing_guard(FLAG_BATCH_EVALUATION_TIME, &labels);

        let flag_get_match_timer = timing_guard(FLAG_GET_MATCH_TIME, &[]);

        match eval_type {
            EvaluationType::Sequential => {
                flags_to_evaluate.iter().for_each(|flag| {
                    let result = self.evaluate_single_flag(
                        flag,
                        person_property_overrides,
                        group_property_overrides,
                        flags_with_missing_deps,
                        hash_key_overrides,
                        request_hash_key_override,
                    );
                    self.process_flag_result(
                        flag,
                        &result,
                        &mut level_evaluated_flags_map,
                        &mut errors_while_computing_flags,
                        person_property_overrides,
                        group_property_overrides,
                    );
                });
            }
            EvaluationType::Parallel => {
                let results = self
                    .evaluate_batch_parallel(
                        flags_to_evaluate,
                        person_property_overrides,
                        group_property_overrides,
                        flags_with_missing_deps,
                        hash_key_overrides,
                        request_hash_key_override,
                    )
                    .await?;

                for (flag, result) in &results {
                    self.process_flag_result(
                        flag,
                        result,
                        &mut level_evaluated_flags_map,
                        &mut errors_while_computing_flags,
                        person_property_overrides,
                        group_property_overrides,
                    );
                }
            }
        }

        flag_get_match_timer
            .label(
                "outcome",
                if errors_while_computing_flags {
                    "error"
                } else {
                    "success"
                },
            )
            .fin();

        Ok((level_evaluated_flags_map, errors_while_computing_flags))
    }

    /// Process a single flag evaluation result: update evaluation state, record metrics, and
    /// insert into the level map.
    fn process_flag_result(
        &mut self,
        flag: &FeatureFlag,
        result: &Result<FeatureFlagMatch, FlagError>,
        level_evaluated_flags_map: &mut HashMap<String, FlagDetails>,
        errors_while_computing_flags: &mut bool,
        person_property_overrides: &Option<HashMap<String, Value>>,
        group_property_overrides: &Option<HashMap<String, HashMap<String, Value>>>,
    ) {
        match result {
            Ok(flag_match) => {
                self.flag_evaluation_state
                    .add_flag_evaluation_result(flag.id, flag_match.get_flag_value());
                let flag_details = if self.detailed_analysis {
                    // Use merged person properties (DB + overrides) for condition analysis
                    let merged_person_props = self
                        .get_person_properties(person_property_overrides.as_ref())
                        .ok();
                    // Merged group properties (DB + overrides, including the injected
                    // `$group_key`) keyed by group type index, so group-typed condition
                    // filters resolve against the group rather than the person.
                    let merged_group_props =
                        self.merged_group_properties_for_flag(flag, group_property_overrides);
                    let cohort_matches =
                        self.cohort_matches_for_analysis(flag, merged_person_props.as_ref());
                    FlagDetails::create_with_analysis(
                        flag,
                        flag_match,
                        true,
                        merged_person_props.as_ref(),
                        Some(&merged_group_props),
                        Some(&self.flag_evaluation_state.flag_evaluation_results),
                        Some(&self.flag_evaluation_state.failed_flag_ids),
                        Some(&cohort_matches),
                        PropertyMatchingContext::new(
                            self.timezone,
                            self.use_explicit_exact_matching,
                        ),
                    )
                } else {
                    FlagDetails::create(flag, flag_match)
                };
                level_evaluated_flags_map.insert(flag.key.clone(), flag_details);
            }
            Err(e) => {
                *errors_while_computing_flags = true;
                with_canonical_log(|log| log.flags_errored += 1);

                match e {
                    FlagError::DependencyNotFound(dependency_type, dependency_id) => warn!(
                        "Feature flag '{}' targeting deleted {} with id {} for distinct_id '{}': {:?}",
                        flag.key, dependency_type, dependency_id, self.distinct_id, e
                    ),
                    // The failed dependency already logged its own error.
                    FlagError::DependencyFailed(dependency_id) => debug!(
                        "Feature flag '{}' failed because dependency {} failed",
                        flag.key, dependency_id
                    ),
                    // The group type lookup already logged or counted its own failure.
                    FlagError::GroupTypeLookupFailed(cause) => debug!(
                        "Feature flag '{}' failed because the group type lookup failed: {:?}",
                        flag.key, cause
                    ),
                    _ => error!(
                        "Error evaluating feature flag '{}' for distinct_id '{}': {:?}",
                        flag.key, self.distinct_id, e
                    ),
                }

                let reason = e.evaluation_error_code();
                inc(
                    FLAG_EVALUATION_ERROR_COUNTER,
                    &[("reason".to_string(), reason)],
                    1,
                );
                level_evaluated_flags_map.insert(flag.key.clone(), failed_flag_details(flag, e));
            }
        }
    }

    /// Resolves group property overrides for a specific group type index by mapping
    /// the index to the group type name and looking up the corresponding overrides.
    fn resolve_group_overrides<'a>(
        &self,
        group_type_index: GroupTypeIndex,
        group_property_overrides: Option<&'a HashMap<String, HashMap<String, Value>>>,
    ) -> Option<&'a HashMap<String, Value>> {
        let mapping = self.group_type_mapping.mapping()?;
        let index_to_type_map = mapping.group_indexes_to_types();
        let group_type = index_to_type_map.get(&group_type_index)?;
        let group_overrides = group_property_overrides?;
        group_overrides.get(group_type)
    }

    /// Builds merged group properties (DB + overrides) keyed by group type index for
    /// every group type the flag's conditions reference. Used by detailed condition
    /// analysis so group-typed filters resolve against the group's properties (and the
    /// `$group_key` injected into overrides) rather than the person's. Every referenced
    /// group type index is included, backed by an empty map if no properties were found.
    pub(crate) fn merged_group_properties_for_flag(
        &self,
        flag: &FeatureFlag,
        group_property_overrides: &Option<HashMap<String, HashMap<String, Value>>>,
    ) -> HashMap<GroupTypeIndex, HashMap<String, Value>> {
        let referenced_indexes: HashSet<GroupTypeIndex> = flag
            .filters
            .requirements()
            .group_property_type_indexes
            .into_iter()
            .collect();

        let mut merged = HashMap::new();
        for gti in referenced_indexes {
            let overrides = self.resolve_group_overrides(gti, group_property_overrides.as_ref());
            merged.insert(
                gti,
                self.get_group_properties(gti, overrides)
                    .unwrap_or_default(),
            );
        }
        merged
    }

    /// Pushes CPU-bound flag evaluation onto the Rayon pool via [`RayonDispatcher`],
    /// so the calling Tokio worker thread is free to serve other requests while
    /// evaluation runs. The dispatcher bounds how many batches can be in-flight
    /// simultaneously, preventing unbounded queue growth and preserving per-batch
    /// work-stealing parallelism.
    async fn evaluate_batch_parallel(
        &self,
        flags_to_evaluate: Vec<FeatureFlag>,
        person_property_overrides: &Option<HashMap<String, Value>>,
        group_property_overrides: &Option<HashMap<String, HashMap<String, Value>>>,
        flags_with_missing_deps: &HashSet<i32>,
        hash_key_overrides: &Option<HashMap<String, String>>,
        request_hash_key_override: &Option<String>,
    ) -> Result<Vec<(FeatureFlag, Result<FeatureFlagMatch, FlagError>)>, FlagError> {
        let matcher = self.clone();
        let missing_deps = flags_with_missing_deps.clone();
        let person_overrides = person_property_overrides.clone();
        let group_overrides = group_property_overrides.clone();
        let hash_overrides = hash_key_overrides.clone();
        let req_hash_override = request_hash_key_override.clone();

        // Save lightweight snapshots before moving flags into rayon.
        // If the rayon task panics, we use these to construct per-flag error results
        // instead of silently dropping flags from the response.
        let team_id = self.team_id;
        let flag_snapshots: Vec<_> = flags_to_evaluate
            .iter()
            .map(FlagSnapshot::from_flag)
            .collect();

        // Each rayon thread accumulates evaluation counters in a thread-local
        // FlagsCanonicalLogLine. After evaluation, the per-flag deltas are
        // returned alongside each flag result and merged into the request's
        // tokio task-local canonical log.
        let work = move || {
            flags_to_evaluate
                .into_par_iter()
                .map(|flag| {
                    let _guard = install_rayon_canonical_log();
                    let result = matcher.evaluate_single_flag(
                        &flag,
                        &person_overrides,
                        &group_overrides,
                        &missing_deps,
                        &hash_overrides,
                        &req_hash_override,
                    );
                    let delta = take_rayon_canonical_log();
                    (flag, result, delta)
                })
                .collect::<Vec<_>>()
        };

        let result = match &self.rayon_dispatcher {
            Some(dispatcher) => dispatcher
                .try_spawn(work)
                .await
                .map_err(|t| FlagError::RayonSemaphoreTimeout(t.waited.as_millis() as u64))?,
            None => {
                // Fallback for tests: unbounded dispatch (no semaphore).
                let (tx, rx) = tokio::sync::oneshot::channel();
                rayon::spawn(move || {
                    if let Ok(value) = std::panic::catch_unwind(std::panic::AssertUnwindSafe(work))
                    {
                        drop(tx.send(value));
                    }
                });
                rx.await.ok()
            }
        };

        let results_with_deltas = result.unwrap_or_else(|| {
            error!("Rayon parallel evaluation task was dropped (likely panicked)");
            Self::build_panic_fallback(flag_snapshots, team_id)
                .into_iter()
                .map(|(flag, result)| (flag, result, None))
                .collect()
        });

        Ok(results_with_deltas
            .into_iter()
            .map(|(flag, result, delta)| {
                if let Some(delta) = delta {
                    with_canonical_log(|log| log.merge_rayon_delta(&delta));
                }
                (flag, result)
            })
            .collect())
    }

    /// Constructs per-flag error results from lightweight snapshots when the
    /// rayon task panics and drops the oneshot sender.
    fn build_panic_fallback(
        snapshots: Vec<FlagSnapshot>,
        team_id: TeamId,
    ) -> Vec<(FeatureFlag, Result<FeatureFlagMatch, FlagError>)> {
        snapshots
            .into_iter()
            .map(|snapshot| {
                let stub = FeatureFlag {
                    id: snapshot.id,
                    key: snapshot.key,
                    // Panic fallback can't compute experiment linkage; use the shared default.
                    has_experiment: default_has_experiment(),
                    active: true,
                    version: snapshot.version,
                    filters: FlagFilters {
                        non_v1: snapshot.non_v1,
                        ..FlagFilters::default()
                    },
                    team_id,
                    name: None,
                    deleted: false,
                    ensure_experience_continuity: None,
                    evaluation_runtime: None,
                    evaluation_tags: None,
                    bucketing_identifier: None,
                };
                (stub, Err(FlagError::batch_evaluation_panicked()))
            })
            .collect()
    }

    fn evaluate_single_flag(
        &self,
        flag: &FeatureFlag,
        person_property_overrides: &Option<HashMap<String, Value>>,
        group_property_overrides: &Option<HashMap<String, HashMap<String, Value>>>,
        flags_with_missing_deps: &HashSet<i32>,
        hash_key_overrides: &Option<HashMap<String, String>>,
        request_hash_key_override: &Option<String>,
    ) -> Result<FeatureFlagMatch, FlagError> {
        if flags_with_missing_deps.contains(&flag.id) {
            return Ok(FeatureFlagMatch::missing_dependency());
        }

        self.get_match(
            flag,
            person_property_overrides.as_ref(),
            group_property_overrides.as_ref(),
            hash_key_overrides.as_ref(),
            request_hash_key_override,
        )
    }

    /// Determines if a feature flag matches for the current context.
    ///
    /// This method evaluates the conditions of a feature flag to determine if it should be enabled,
    /// and if so, which variant (if any) should be applied. It follows these steps:
    ///
    /// 1. Check if there's a valid hashed identifier for the flag.
    /// 2. Evaluate any super conditions that might override normal conditions.
    /// 3. Sort and evaluate each condition, prioritizing those with variant overrides.
    /// 4. For each matching condition, determine the appropriate variant and payload.
    /// 5. Return the result of the evaluation, including match status, variant, reason, and payload.
    ///
    /// The method also keeps track of the highest priority match reason and index,
    /// which are used even if no conditions ultimately match.
    pub fn get_match(
        &self,
        flag: &FeatureFlag,
        person_property_overrides: Option<&HashMap<String, Value>>,
        group_property_overrides: Option<&HashMap<String, HashMap<String, Value>>>,
        hash_key_overrides: Option<&HashMap<String, String>>,
        request_hash_key_override: &Option<String>,
    ) -> Result<FeatureFlagMatch, FlagError> {
        if let Some(config) = flag.filters.supported_v2() {
            return self.get_match_v2(config, person_property_overrides);
        }
        flag.filters.require_v1()?;
        // Seed with the lowest-priority "could not evaluate" reason so any real evaluation
        // result outranks it via `get_highest_priority_match_evaluation`. NoGroupType is
        // the floor: a pure-group flag whose only condition is skipped for missing context
        // still surfaces NoGroupType, while a person condition that runs and reports
        // NoConditionMatch or OutOfRolloutBound takes precedence in mixed-targeting flags.
        let mut highest_match = FeatureFlagMatchReason::NoGroupType;
        let mut highest_index = None;
        let mut had_skipped_group_conditions = false;
        let mut had_unevaluable_cohort_conditions = false;

        // Lazily compute properties per aggregation type. Person and group properties are
        // cached separately so conditions with different aggregation modes can share them.
        let mut cached_person_properties: Option<HashMap<String, Value>> = None;
        let mut cached_group_properties: HashMap<i32, HashMap<String, Value>> = HashMap::new();

        // Evaluate feature enrollment (early access features) first.
        // Enrollment is a person-level concept — always uses person properties, even for
        // group-based flags.
        if flag.filters.feature_enrollment == Some(true) {
            let enrollment_key = FlagFilters::enrollment_key(&flag.key);
            let person_properties = self.get_person_properties(person_property_overrides)?;

            if let Some(v) = person_properties.get(&enrollment_key) {
                let is_match = FlagFilters::is_enrolled(v);
                let payload = self.get_matching_payload(None, flag);
                return Ok(FeatureFlagMatch {
                    matches: is_match,
                    variant: None,
                    reason: FeatureFlagMatchReason::SuperConditionValue,
                    condition_index: Some(0),
                    payload,
                    evaluation_v2: None,
                });
            }
        }

        // Match for holdout condition
        // TODO: Validate holdout variant should have 0% default rollout %?
        // TODO: All this validation we need to do suggests the modelling is imperfect here. Carrying forward for now, we'll only enable
        // in beta, and potentially rework representation before rolling out to everyone. Probably the problem is holdout groups are an
        // experiment level concept that applies across experiments, and we are creating a feature flag level primitive to handle it.
        // Validating things like the variant name is the same across all flags, rolled out to 0%, has the same correct conditions is a bit of
        // a pain here. But I'm not sure if feature flags should indeed know all this info. It's fine for them to just work with what they're given.
        if flag.filters.holdout.is_some() {
            let (is_match, holdout_value, evaluation_reason) =
                self.is_holdout_condition_match(flag, request_hash_key_override)?;
            if is_match {
                let payload = self.get_matching_payload(holdout_value.as_deref(), flag);
                return Ok(FeatureFlagMatch {
                    matches: true,
                    variant: holdout_value,
                    reason: evaluation_reason,
                    condition_index: None,
                    payload,
                    evaluation_v2: None,
                });
            }
        }
        let conditions: Vec<(usize, &FlagPropertyGroup)> =
            flag.get_conditions().iter().enumerate().collect();

        let early_exit_enabled = flag.filters.early_exit.unwrap_or(false);
        // A condition on a failed flag cannot settle the answer. Each such condition records the
        // answer the flag would give if the failed flag matched it. The flag fails only when one
        // of those answers differs from the answer from its other conditions. Server SDKs read
        // `failed: true` as false. Failing every dependent would therefore turn a settled `true`
        // into false.
        let mut answers_if_dependency_matched: Vec<AnswerIfDependencyMatched> = Vec::new();
        // A later condition that matches still settles the flag. The skipped condition could
        // have picked a different variant. With early exit, a skipped condition below 100%
        // rollout could instead stop evaluation with no match, so a later match cannot settle
        // the flag.
        let mut group_lookup_error: Option<Arc<FlagError>> = None;
        let mut group_lookup_skip_can_exit_early = false;
        // The handler copies every request group key into the overrides as `$group_key`, also an
        // unusable one. An override map with only an unusable `$group_key` therefore names no group.
        let request_has_group_context = self.request_has_usable_group_key()
            || group_property_overrides.is_some_and(|overrides| {
                overrides
                    .values()
                    .flatten()
                    .any(|(key, value)| key != "$group_key" || is_usable_group_key(value))
            });
        let condition_timer = common_metrics::timing_guard(FLAG_EVALUATE_ALL_CONDITIONS_TIME, &[]);
        for (index, condition) in conditions {
            // Each condition resolves its own aggregation, falling back to the flag-level
            // value for backwards compatibility with flags that predate per-condition aggregation.
            let aggregation = condition.effective_aggregation(flag.get_group_type_index());

            // Device_id bucketing only applies to person-aggregated conditions. For mixed
            // flags, group-aggregated conditions can still match even without a device_id.
            if aggregation.is_none() {
                use crate::flags::flag_models::BucketingIdentifier;

                let buckets_on_device_id =
                    flag.get_bucketing_identifier() == BucketingIdentifier::DeviceId;
                let has_device_id = self
                    .device_id
                    .as_ref()
                    .is_some_and(|device_id| !device_id.is_empty());

                // Without a device_id there is nothing to bucket on, so the condition is
                // withheld rather than bucketed on the wrong identifier. Withholding a
                // condition whose outcome the hash cannot change would instead disable the
                // flag for everyone it targets, so the guard asks whether it can.
                if buckets_on_device_id
                    && !has_device_id
                    && flag.condition_needs_bucketing_hash(condition)
                {
                    inc(
                        FLAG_CONDITION_SKIPPED_COUNTER,
                        &[("reason".to_string(), "missing_device_id".to_string())],
                        1,
                    );
                    with_canonical_log(|log| {
                        tracing::debug!(
                            flag_key = %flag.key,
                            team_id = %flag.team_id,
                            condition_index = %index,
                            lib = log.lib.as_deref(),
                            lib_version = log.lib_version.as_deref(),
                            "Person condition uses device_id bucketing but no device_id provided, skipping"
                        );
                    });
                    let (new_highest_match, new_highest_index) = self
                        .get_highest_priority_match_evaluation(
                            highest_match.clone(),
                            highest_index,
                            FeatureFlagMatchReason::OutOfRolloutBound,
                            Some(index),
                        );
                    highest_match = new_highest_match;
                    highest_index = new_highest_index;
                    continue;
                }
                if buckets_on_device_id && has_device_id {
                    with_canonical_log(|log| log.eval.flags_device_id_bucketing += 1);
                }
            }

            if let Some(error) =
                self.group_lookup_error_for(condition, aggregation, request_has_group_context)
            {
                inc(
                    FLAG_CONDITION_SKIPPED_COUNTER,
                    &[("reason".to_string(), "group_type_lookup_failed".to_string())],
                    1,
                );
                group_lookup_skip_can_exit_early |=
                    early_exit_enabled && condition.rollout_percentage_unwrapped() < 100.0;
                group_lookup_error = Some(error);
                continue;
            }

            // For group-aggregated conditions, verify we have the group key. If not, this
            // condition can't match — log a warning and continue to the next condition.
            // This checks the group key directly rather than calling hashed_identifier,
            // which will be called again later in check_rollout/get_matching_variant.
            if let Some(group_type_index) = aggregation {
                if !self.has_group_key(group_type_index) {
                    inc(
                        FLAG_CONDITION_SKIPPED_COUNTER,
                        &[("reason".to_string(), "missing_group_type".to_string())],
                        1,
                    );
                    debug!(
                        flag_key = %flag.key,
                        team_id = %flag.team_id,
                        condition_index = %index,
                        "Condition uses group aggregation but group type not provided in evaluation context, skipping"
                    );
                    // Record this as a NoGroupType reason but continue to next condition.
                    // Track that we skipped a group condition so the final result can
                    // surface a richer description when person conditions also didn't match.
                    had_skipped_group_conditions = true;
                    let (new_highest_match, new_highest_index) = self
                        .get_highest_priority_match_evaluation(
                            highest_match.clone(),
                            highest_index,
                            FeatureFlagMatchReason::NoGroupType,
                            Some(index),
                        );
                    highest_match = new_highest_match;
                    highest_index = new_highest_index;
                    continue;
                }
            }

            // Lazily compute properties based on what the condition's filters reference.
            // A condition may have person filters, group filters, or both (mixed targeting).
            // Properties are cached per type so conditions sharing a property source reuse them.
            if Self::condition_needs_properties(condition) {
                let (needs_person, needed_group_types) =
                    Self::condition_property_type_needs(condition, aggregation);

                if needs_person && cached_person_properties.is_none() {
                    cached_person_properties =
                        Some(self.get_person_properties(person_property_overrides)?);
                }

                for &gti in &needed_group_types {
                    if let std::collections::hash_map::Entry::Vacant(e) =
                        cached_group_properties.entry(gti)
                    {
                        let group_overrides =
                            self.resolve_group_overrides(gti, group_property_overrides);
                        let group_props = self.get_group_properties(gti, group_overrides)?;
                        e.insert(group_props);
                    }
                }
            }

            let property_context = PropertyContext {
                person_properties: cached_person_properties.as_ref(),
                group_properties: &cached_group_properties,
                aggregation,
                request_has_group_context,
            };

            let (is_match, reason) = self.is_condition_match(
                flag,
                condition,
                &property_context,
                hash_key_overrides,
                request_hash_key_override,
            )?;

            if reason == FeatureFlagMatchReason::NoConditionMatchCohortNotEvaluated {
                had_unevaluable_cohort_conditions = true;
            }

            let failed_dependency = condition
                .properties
                .iter()
                .flatten()
                .find_map(|filter| self.flag_evaluation_state.failed_dependency(filter));

            // OutOfRolloutBound means the condition's property filters (if any) already
            // matched and only the rollout check failed, so re-evaluating later groups
            // can't change the outcome.
            if early_exit_enabled
                && !is_match
                && reason == FeatureFlagMatchReason::OutOfRolloutBound
            {
                // If the failed flag matched, the flag would stop here with no match.
                // Otherwise the later conditions decide.
                if let Some(failed_dependency) = failed_dependency {
                    answers_if_dependency_matched.push(AnswerIfDependencyMatched {
                        failed_dependency,
                        answer: ConditionAnswer::NoMatch,
                    });
                } else {
                    if let Some(error) = self.no_match_error(
                        flag,
                        &answers_if_dependency_matched,
                        group_lookup_error,
                    ) {
                        return Err(error);
                    }
                    return Ok(FeatureFlagMatch {
                        matches: false,
                        variant: None,
                        reason: FeatureFlagMatchReason::OutOfRolloutBound,
                        condition_index: Some(index),
                        payload: None,
                        evaluation_v2: None,
                    });
                }
            }

            if is_match {
                if let Some(failed_dependency) = failed_dependency {
                    let variant = self.condition_variant(
                        flag,
                        condition,
                        aggregation,
                        hash_key_overrides,
                        request_hash_key_override,
                    )?;
                    answers_if_dependency_matched.push(AnswerIfDependencyMatched {
                        failed_dependency,
                        answer: ConditionAnswer::Match(variant),
                    });
                    continue;
                }
            }

            // Update highest_match and highest_index
            let (new_highest_match, new_highest_index) = self
                .get_highest_priority_match_evaluation(
                    highest_match.clone(),
                    highest_index,
                    reason.clone(),
                    Some(index),
                );
            highest_match = new_highest_match;
            highest_index = new_highest_index;

            if is_match {
                let variant = self.condition_variant(
                    flag,
                    condition,
                    aggregation,
                    hash_key_overrides,
                    request_hash_key_override,
                )?;
                if !answers_if_dependency_matched.is_empty() {
                    if let Some(dependency) = self.dependency_that_changes_answer(
                        flag,
                        &answers_if_dependency_matched,
                        &ConditionAnswer::Match(variant.clone()),
                    ) {
                        return Err(FlagError::DependencyFailed(dependency.into()));
                    }
                }
                if let Some(error) = group_lookup_error.filter(|_| group_lookup_skip_can_exit_early)
                {
                    return Err(FlagError::GroupTypeLookupFailed(error));
                }
                let payload = self.get_matching_payload(variant.as_deref(), flag);

                return Ok(FeatureFlagMatch {
                    matches: true,
                    variant,
                    reason: highest_match,
                    condition_index: highest_index,
                    payload,
                    evaluation_v2: None,
                });
            }
        }

        if let Some(error) =
            self.no_match_error(flag, &answers_if_dependency_matched, group_lookup_error)
        {
            return Err(error);
        }

        condition_timer.label("outcome", "success").fin();

        // When person conditions were evaluated (and didn't match) but group conditions
        // were skipped because the caller didn't provide the required group type, upgrade
        // the reason to carry a richer description. The API code still serializes as
        // "no_condition_match" for backward compatibility, but the description tells the
        // caller about the skipped group conditions.
        // A cohort that can't be fully evaluated takes precedence over a skipped group
        // condition, because it reaches real flag traffic.
        if highest_match == FeatureFlagMatchReason::NoConditionMatch {
            if had_unevaluable_cohort_conditions {
                highest_match = FeatureFlagMatchReason::NoConditionMatchCohortNotEvaluated;
            } else if had_skipped_group_conditions {
                highest_match = FeatureFlagMatchReason::NoConditionMatchGroupsNotEvaluated;
            }
        }

        // Return with the highest_match reason and index even if no conditions matched
        Ok(FeatureFlagMatch {
            matches: false,
            variant: None,
            reason: highest_match,
            condition_index: highest_index,
            payload: None,
            evaluation_v2: None,
        })
    }

    /// Projects a v2 outcome onto the v1 match shape: a null value is disabled, a boolean is
    /// `enabled`, a string is the variant, and a number or object is an enabled flag whose value
    /// travels as a JSON-encoded payload, like a v1 payload. The subject is the request distinct ID.
    fn get_match_v2(
        &self,
        config: &Config,
        person_property_overrides: Option<&HashMap<String, Value>>,
    ) -> Result<FeatureFlagMatch, FlagError> {
        // A config without predicates never reads properties, so skip the merge.
        let merged = if config.rules.iter().any(|rule| !rule.targeting.is_empty()) {
            Some(self.get_person_properties(person_property_overrides)?)
        } else {
            None
        };
        // An overrides-only request treats its map as authoritative, as v1 does.
        let properties = match &merged {
            Some(map)
                if self.only_use_override_person_properties
                    || self.flag_evaluation_state.get_person_properties().is_some() =>
            {
                PersonProperties::Complete(map)
            }
            Some(map) if person_property_overrides.is_some() => PersonProperties::Partial(map),
            _ => PersonProperties::Unavailable,
        };
        let evaluation = Evaluator::new(config).evaluate(&EvaluationContext {
            person_identifier: &self.distinct_id,
            properties,
            timezone: self.timezone,
            use_explicit_exact_matching: self.use_explicit_exact_matching,
            now: self.now,
        })?;
        // `/flags?v=2` reports these v1 reasons; `/flags?v=4` reports the evaluator's own code.
        let reason = match evaluation {
            Evaluation::TargetingMatch { .. } | Evaluation::ExperimentSplit { .. } => {
                FeatureFlagMatchReason::ConditionMatch
            }
            Evaluation::RolloutMiss { .. } => FeatureFlagMatchReason::OutOfRolloutBound,
            Evaluation::Holdout { .. } => FeatureFlagMatchReason::HoldoutConditionValue,
            Evaluation::ExperimentPaused { .. } | Evaluation::NoRuleMatch { .. } => {
                FeatureFlagMatchReason::NoConditionMatch
            }
        };
        let condition_index = evaluation.rule().map(|rule| rule.index);
        let (matches, variant, payload) = match evaluation.value() {
            None => (false, None, None),
            Some(Value::Bool(value)) => (*value, None, None),
            Some(Value::String(value)) => (true, Some(value.clone()), None),
            Some(value) => (true, None, Some(Value::String(value.to_string()))),
        };
        Ok(FeatureFlagMatch {
            matches,
            variant,
            reason,
            condition_index,
            payload,
            evaluation_v2: Some(evaluation.into()),
        })
    }

    fn dependency_that_changes_answer(
        &self,
        flag: &FeatureFlag,
        answers_if_dependency_matched: &[AnswerIfDependencyMatched],
        answer: &ConditionAnswer,
    ) -> Option<FeatureFlagId> {
        let compare_variants = !self.enabled_only_flag_keys.contains(&flag.key);
        answers_if_dependency_matched
            .iter()
            .find(|candidate| {
                if compare_variants {
                    candidate.answer != *answer
                } else {
                    candidate.answer.is_match() != answer.is_match()
                }
            })
            .map(|candidate| candidate.failed_dependency)
    }

    fn no_match_error(
        &self,
        flag: &FeatureFlag,
        answers_if_dependency_matched: &[AnswerIfDependencyMatched],
        group_lookup_error: Option<Arc<FlagError>>,
    ) -> Option<FlagError> {
        self.dependency_that_changes_answer(
            flag,
            answers_if_dependency_matched,
            &ConditionAnswer::NoMatch,
        )
        .map(|dependency| FlagError::DependencyFailed(dependency.into()))
        .or_else(|| group_lookup_error.map(FlagError::GroupTypeLookupFailed))
    }

    /// This function determines the highest priority match evaluation for feature flag conditions.
    /// It compares the current match reason with a new match reason and returns the higher priority one.
    /// The priority is determined by the ordering of FeatureFlagMatchReason variants.
    /// It's used to keep track of the most significant reason why a flag matched or didn't match,
    /// especially useful when multiple conditions are evaluated.
    fn get_highest_priority_match_evaluation(
        &self,
        current_match: FeatureFlagMatchReason,
        current_index: Option<usize>,
        new_match: FeatureFlagMatchReason,
        new_index: Option<usize>,
    ) -> (FeatureFlagMatchReason, Option<usize>) {
        if current_match <= new_match {
            (new_match, new_index)
        } else {
            (current_match, current_index)
        }
    }

    /// Check if a condition matches for a feature flag.
    ///
    /// Evaluates a specific condition to determine if it should be enabled.
    /// If the condition has no property filters, performs a rollout check only.
    /// Otherwise, checks if the provided properties satisfy the condition's filters.
    ///
    /// Each filter is matched against the correct property source based on its type:
    /// person filters use person properties, group filters use the group properties
    /// for that filter's `group_type_index`. This enables mixed targeting where a
    /// single condition combines person and group filters with independent rollout.
    pub(crate) fn is_condition_match(
        &self,
        feature_flag: &FeatureFlag,
        condition: &FlagPropertyGroup,
        property_context: &PropertyContext,
        hash_key_overrides: Option<&HashMap<String, String>>,
        request_hash_key_override: &Option<String>,
    ) -> Result<(bool, FeatureFlagMatchReason), FlagError> {
        let rollout_percentage = condition.rollout_percentage.unwrap_or(100.0);

        if let Some(flag_property_filters) = &condition.properties {
            if flag_property_filters.is_empty() {
                return self.check_rollout(
                    feature_flag,
                    rollout_percentage,
                    property_context.aggregation,
                    hash_key_overrides,
                    request_hash_key_override,
                );
            }

            if self
                .flag_evaluation_state
                .failed_dependency_filters_conflict(flag_property_filters)
            {
                return Ok((false, FeatureFlagMatchReason::NoConditionMatch));
            }

            // Single-pass evaluation: flag-value and property filters are evaluated in Vec order
            // and short-circuit immediately on mismatch. Cohort filters (the most expensive)
            // are deferred and batch-evaluated after the loop to avoid unnecessary work.
            let mut cohort_filters: Vec<&PropertyFilter> = Vec::new();
            for filter in flag_property_filters {
                if filter.depends_on_feature_flag() {
                    // A filter on a flag that failed earlier in this request passes here, so the
                    // other filters and the rollout still decide whether the condition can
                    // match. `get_match` uses such a match only as the answer the flag would give
                    // if the failed flag matched.
                    if self
                        .flag_evaluation_state
                        .failed_dependency(filter)
                        .is_some()
                    {
                        continue;
                    }
                    if !match_flag_value_to_flag_filter(
                        filter,
                        &self.flag_evaluation_state.flag_evaluation_results,
                    ) {
                        return Ok((false, FeatureFlagMatchReason::NoConditionMatch));
                    }
                } else if filter.is_cohort() {
                    cohort_filters.push(filter);
                } else {
                    let props = property_context.resolve_for_filter(filter);
                    // Person properties that were never fetched (DB prep didn't run for this
                    // evaluation) must not be treated as "person has no properties", because
                    // an absent key would then make negative operators (is_not, not_icontains,
                    // ...) and is_not_set match by accident. partial_props makes match_property
                    // error on a missing key instead of matching it; the unwrap_or(false) below
                    // turns that error into no-match, so the condition fails closed. Only
                    // Pending gets this: Skipped and Fetched property maps are authoritative,
                    // so an absent key there genuinely means the person lacks the property.
                    // This is defense in depth: in the batch flow a prep failure errors those
                    // flags out before evaluation, so the guard protects any path that reaches
                    // evaluation with the state still Pending. Cohort filters get the same
                    // treatment below, refusing to evaluate outright since cohort membership
                    // is unknowable under Pending. Group filters get the equivalent guard
                    // keyed on their own group type — see `filter_needs_partial_props`.
                    let partial_props = self.filter_needs_partial_props(filter, property_context);
                    if !match_property(
                        filter,
                        props,
                        partial_props,
                        PropertyMatchingContext::new(
                            self.timezone,
                            self.use_explicit_exact_matching,
                        ),
                    )
                    .unwrap_or(false)
                    {
                        return Ok((false, FeatureFlagMatchReason::NoConditionMatch));
                    }
                }
            }

            // Evaluate cohort filters using person properties (cohorts are person-level).
            if !cohort_filters.is_empty() {
                // Cohort evaluation reads the same person-property map as direct filters, and
                // both the property-level `negation` inside a cohort definition and cohort-level
                // NOT_IN would turn a missing key into a match. Membership is unknowable under
                // Pending either way, so refuse to evaluate rather than guess. Today no prep path
                // loads cohorts without fetching person properties, so this should be unreachable
                // — hence the error log, which flags a broken invariant rather than normal traffic.
                if self.flag_evaluation_state.person_properties_pending() {
                    inc(
                        PROPERTY_CACHE_MISSES_COUNTER,
                        &[
                            ("type".to_string(), "cohort_filters".to_string()),
                            ("reason".to_string(), "db_prep_never_ran".to_string()),
                        ],
                        1,
                    );
                    with_canonical_log(|log| {
                        log.eval.property_cache_misses += 1;
                        log.eval.person_properties_not_cached = true;
                    });
                    tracing::error!(
                        "Cohort filters not evaluated — DB prep never ran, so the condition fails closed"
                    );
                    return Ok((false, FeatureFlagMatchReason::NoConditionMatch));
                }

                let cohorts = match &self.flag_evaluation_state.cohorts {
                    Some(cohorts) => cohorts.clone(),
                    None => return Ok((false, FeatureFlagMatchReason::NoConditionMatch)),
                };
                let cohort_props = property_context
                    .person_properties
                    .unwrap_or(&*EMPTY_PROPERTY_MAP);
                if !self.evaluate_cohort_filters(&cohort_filters, cohort_props, cohorts.clone())? {
                    // A non-match isn't trustworthy when a targeted cohort has a behavioral or
                    // lifecycle leaf the dynamic path can't resolve, so flag it with a distinct reason.
                    // An operator the matcher does not honor fails the condition whatever the
                    // membership is, so the caveat does not hold for one of those.
                    let cohort_membership_unresolved = cohort_filters
                        .iter()
                        .all(|filter| filter.cohort_operator_is_supported())
                        && cohort_filters.iter().any(|filter| {
                            filter.get_cohort_id().is_some_and(|cohort_id| {
                                cohorts
                                    .iter()
                                    .any(|c| c.id == cohort_id && c.has_behavioral_condition())
                            })
                        });
                    let reason = if cohort_membership_unresolved {
                        FeatureFlagMatchReason::NoConditionMatchCohortNotEvaluated
                    } else {
                        FeatureFlagMatchReason::NoConditionMatch
                    };
                    return Ok((false, reason));
                }
            }
        }
        self.check_rollout(
            feature_flag,
            rollout_percentage,
            property_context.aggregation,
            hash_key_overrides,
            request_hash_key_override,
        )
    }

    /// Seeds the mapping that `initialize_group_type_mappings_if_needed` loads in production,
    /// for tests that exercise matching without running DB prep.
    #[cfg(test)]
    pub(crate) fn set_group_type_mapping_for_test(&mut self, mapping: GroupTypeMapping) {
        self.group_type_mapping = GroupTypeMappingState::Loaded(mapping);
    }

    #[cfg(test)]
    pub(crate) fn set_group_type_mapping_failed_for_test(&mut self, error: FlagError) {
        self.group_type_mapping = GroupTypeMappingState::Failed(Arc::new(error));
    }

    /// Whether the request supplied a usable group key for this group type name. Without one
    /// there is no group to load properties for, so group filters on that type have no
    /// context at all — distinct from having a key whose properties weren't fetched.
    fn has_usable_group_key(&self, group_type: &str) -> bool {
        self.groups.get(group_type).is_some_and(is_usable_group_key)
    }

    /// `has_usable_group_key` by group type index. False both when the request omitted the
    /// group and when the mapping can't resolve the index, so callers that must tell those
    /// apart resolve the name themselves — see `filter_needs_partial_props`.
    fn has_group_key(&self, group_type_index: GroupTypeIndex) -> bool {
        self.group_type_mapping
            .mapping()
            .and_then(|m| m.group_indexes_to_types().get(&group_type_index))
            .is_some_and(|group_type| self.has_usable_group_key(group_type))
    }

    fn request_has_usable_group_key(&self) -> bool {
        self.groups.values().any(is_usable_group_key)
    }

    /// A condition names its group type by index. Only the mapping tells which group key or
    /// group property override in the request has that index. A request without them gets
    /// the same answer under any mapping, so its conditions evaluate as usual.
    fn group_lookup_error_for(
        &self,
        condition: &FlagPropertyGroup,
        aggregation: Option<GroupTypeIndex>,
        request_has_group_context: bool,
    ) -> Option<Arc<FlagError>> {
        let GroupTypeMappingState::Failed(error) = &self.group_type_mapping else {
            return None;
        };
        // A group-aggregated condition hashes the group key, so a request without a usable
        // key gets no match from it under any mapping, even when it sends property overrides.
        let outcome_unknown = if aggregation.is_some() {
            self.request_has_usable_group_key()
        } else {
            request_has_group_context
                && condition
                    .properties
                    .iter()
                    .flatten()
                    .any(|filter| filter.group_filter_index(None).is_some())
        };
        outcome_unknown.then(|| Arc::clone(error))
    }

    /// Whether DB preparation would load anything this group filter can use. Selecting a
    /// filter pulls its whole flag into preparation, and with it the person-property query,
    /// so a filter only counts when the fetch can serve it: the mapping resolves its index,
    /// the request carries a usable key for that group type, and no group property override
    /// already supplies the filtered key. In every other state the fetch would load nothing
    /// for the filter, and matching handles those states itself — see
    /// `filter_needs_partial_props`.
    fn group_filter_needs_db_prep(
        &self,
        filter: &PropertyFilter,
        effective_aggregation: Option<GroupTypeIndex>,
        group_property_overrides: Option<&HashMap<String, HashMap<String, Value>>>,
    ) -> bool {
        let Some(gti) = filter.group_filter_index(effective_aggregation) else {
            return false;
        };
        let Some(group_type) = self
            .group_type_mapping
            .mapping()
            .and_then(|m| m.group_indexes_to_types().get(&gti))
        else {
            return false;
        };
        if !self.has_usable_group_key(group_type) {
            return false;
        }
        !group_property_overrides
            .and_then(|overrides| overrides.get(group_type))
            .is_some_and(|group_overrides| group_overrides.contains_key(&filter.key))
    }

    /// Whether a filter must be matched with `partial_props`, i.e. treat an absent key as
    /// "unknown" (an error, which the caller turns into no-match) rather than as
    /// "the property is not set" (which would make negative operators match by accident).
    ///
    /// This is only true when the relevant property source was never fetched. Fetched and
    /// deliberately-skipped property maps are authoritative, so an absent key there
    /// genuinely means the property is unset.
    fn filter_needs_partial_props(
        &self,
        filter: &PropertyFilter,
        property_context: &PropertyContext,
    ) -> bool {
        if filter.prop_type != PropertyType::Group {
            return self.flag_evaluation_state.person_properties_pending();
        }

        // A group filter with no resolvable group type index can't be routed to a group
        // property map at all, so there is nothing to fail closed on.
        let Some(gti) = filter.group_filter_index(property_context.aggregation) else {
            return false;
        };

        // This check comes before the name lookup, so a failed or stale mapping does not change
        // the answer for a request without group context.
        if !property_context.request_has_group_context {
            return false;
        }

        // Without a resolved name for the index, nothing is known about the group: the
        // lookup failed, or a loaded mapping predates the group type (a stale cache entry).
        // The request may carry this very group under the name that can't be resolved, so
        // this must not read as "no group context" — fail closed.
        let Some(group_type) = self
            .group_type_mapping
            .mapping()
            .and_then(|m| m.group_indexes_to_types().get(&gti))
        else {
            return true;
        };

        // No group key means no group context whatsoever — the request never claimed to be
        // in a group of this type. Failing closed there would silently stop matching for
        // every caller that doesn't send `groups`, which is a much broader behavior change
        // than the fetch-miss this guard is for, so keep the existing semantics.
        if !self.has_usable_group_key(group_type) {
            return false;
        }

        self.flag_evaluation_state.group_properties_pending(gti)
    }

    /// Checks if a condition requires person/group properties to evaluate.
    /// Returns false for rollout-only conditions or conditions with only flag-value filters.
    fn condition_needs_properties(condition: &FlagPropertyGroup) -> bool {
        condition.properties.as_ref().is_some_and(|props| {
            // Check if there are any non-flag-value property filters
            props.iter().any(|prop| !prop.depends_on_feature_flag())
        })
    }

    /// Determines which property sources a condition's filters reference.
    /// Returns (needs_person_properties, set_of_group_type_indexes_needed).
    fn condition_property_type_needs(
        condition: &FlagPropertyGroup,
        effective_aggregation: Option<GroupTypeIndex>,
    ) -> (bool, HashSet<i32>) {
        let mut needs_person = false;
        let mut group_types = HashSet::new();

        if let Some(props) = &condition.properties {
            for prop in props {
                if prop.depends_on_feature_flag() || prop.is_cohort() {
                    // Cohort filters are evaluated against person properties, so the
                    // caller must load them before constructing the PropertyContext.
                    // Flag filters don't need any properties.
                    if prop.is_cohort() {
                        needs_person = true;
                    }
                    continue;
                }
                match prop.prop_type {
                    PropertyType::Person | PropertyType::PersonMetadata => needs_person = true,
                    PropertyType::Group => {
                        if let Some(gti) = prop.group_filter_index(effective_aggregation) {
                            group_types.insert(gti);
                        }
                    }
                    // Cohort and Flag filters are handled by the guard above, but
                    // listing them explicitly ensures a compile error if a new
                    // PropertyType variant is added.
                    PropertyType::Cohort | PropertyType::Flag => {}
                }
            }
        }

        // For legacy flags where all filters lack explicit types but the condition
        // is group-aggregated, ensure the aggregation index is included. Similarly,
        // person-aggregated legacy conditions need person properties loaded.
        if group_types.is_empty() && !needs_person {
            match effective_aggregation {
                Some(gti) => {
                    group_types.insert(gti);
                }
                None => needs_person = true,
            }
        }

        (needs_person, group_types)
    }

    /// Gets group properties by merging DB properties with overrides (overrides take precedence).
    fn get_group_properties(
        &self,
        group_type_index: GroupTypeIndex,
        property_overrides: Option<&HashMap<String, Value>>,
    ) -> Result<HashMap<String, Value>, FlagError> {
        // Start with DB properties
        let mut merged_properties =
            self.get_group_properties_from_evaluation_state(group_type_index)?;

        // Merge in overrides (overrides take precedence)
        if let Some(overrides) = property_overrides {
            merged_properties.extend(overrides.iter_owned());
        }

        // Return all merged properties
        Ok(merged_properties)
    }

    /// Gets person properties by merging DB properties with overrides (overrides take precedence).
    fn get_person_properties(
        &self,
        property_overrides: Option<&HashMap<String, Value>>,
    ) -> Result<HashMap<String, Value>, FlagError> {
        let mut merged_properties = if self.only_use_override_person_properties {
            // When only_use_override_person_properties is true, ignore DB properties entirely
            HashMap::new()
        } else {
            // Start with DB properties (clone only when we need a mutable copy)
            self.get_person_properties_from_evaluation_state()
                .cloned()
                .unwrap_or_default()
        };

        // Merge in overrides (overrides take precedence).
        //
        // PersonMetadata fields are stored under sentinel-prefixed keys (see
        // `lookup_key_for` in property_matching.rs). A caller could override the canonical
        // persons-table value by setting that sentinel key in `person_property_overrides`.
        // That's intentional for testing — no SDK has any reason to set such a key in
        // production, and overrides are caller-trusted by design. If we ever need to lock
        // metadata fields to the DB value, filter the prefixed keys out here.
        if let Some(overrides) = property_overrides {
            merged_properties.extend(overrides.iter_owned());
        }

        // Mirror $os <-> $os_name so a condition keyed on either matches when the
        // person row carries only one of them (web reports $os, mobile $os_name).
        // Runs before initial-property population so an aliased $os can backfill $initial_os.
        populate_os_aliases(&mut merged_properties);

        // Populate missing $initial_ properties from their non-initial counterparts.
        // DB $initial_ values are preserved; this only fills in missing ones from
        // the merged properties (which may come from DB or request overrides).
        populate_missing_initial_properties(&mut merged_properties);

        Ok(merged_properties)
    }

    fn is_holdout_condition_match(
        &self,
        flag: &FeatureFlag,
        request_hash_key_override: &Option<String>,
    ) -> Result<(bool, Option<String>, FeatureFlagMatchReason), FlagError> {
        if let Some(holdout) = &flag.filters.holdout {
            let percentage = holdout.exclusion_percentage_clamped();

            if !crate::flags::v1_bucketing::is_in_rollout(percentage, || {
                self.get_holdout_hash(flag, None, request_hash_key_override)
            })? {
                // User's hash is above the exclusion threshold — not in holdout
                return Ok((false, None, FeatureFlagMatchReason::OutOfRolloutBound));
            }

            // User is in holdout — variant name is derived from the holdout id
            return Ok((
                true,
                Some(format!("holdout-{}", holdout.id)),
                FeatureFlagMatchReason::HoldoutConditionValue,
            ));
        }
        Ok((false, None, FeatureFlagMatchReason::NoConditionMatch))
    }

    /// Get hashed identifier for flag evaluation.
    ///
    /// Resolves the identifier used for hashing (rollout and variant assignment) based on
    /// the provided aggregation group type index. For group-based aggregation, uses the
    /// group key; for person-based aggregation, uses the distinct_id (with experience
    /// continuity and device_id bucketing fallbacks).
    ///
    /// For person-based flags with ensure_experience_continuity enabled, the identifier priority is:
    /// 1. DB-stored hash_key_override (for consistency across sessions)
    /// 2. Request's hash_key_override (anon_distinct_id) for first-time evaluations
    /// 3. distinct_id (final fallback)
    fn hashed_identifier(
        &self,
        feature_flag: &FeatureFlag,
        aggregation_group_type_index: Option<i32>,
        hash_key_overrides: Option<&HashMap<String, String>>,
        request_hash_key_override: &Option<String>,
    ) -> Result<String, FlagError> {
        if let Some(group_type_index) = aggregation_group_type_index {
            // Group-based flag
            let group_key = match self.group_type_mapping.mapping().and_then(|m| {
                m.group_indexes_to_types()
                    .get(&group_type_index)
                    .and_then(|group_type_name| self.groups.get(group_type_name))
            }) {
                Some(Value::String(s)) => s.clone(),
                Some(Value::Number(n)) => n.to_string(),
                Some(_) => {
                    // For any other JSON type (bool, array, object, null), use empty string
                    // NB: we currently use empty string ("") as the hashed identifier for group flags without a group key,
                    // and I don't want to break parity with the old service since I don't want the hash values to change
                    "".to_string()
                }
                None => "".to_string(),
            };

            Ok(group_key)
        } else {
            // Person-based flag
            use crate::flags::flag_models::BucketingIdentifier;

            // Check if flag is configured for device_id bucketing
            if feature_flag.get_bucketing_identifier() == BucketingIdentifier::DeviceId {
                if let Some(device_id) = &self.device_id {
                    if !device_id.is_empty() {
                        return Ok(device_id.clone());
                    }
                }
            }

            // Use hash key overrides for experience continuity. Only consult overrides
            // when the flag *currently* has continuity enabled — a stored override row
            // is never deleted when continuity is turned off, so a stale row must not
            // steer a flag whose continuity is now off (which would keep every distinct_id
            // of the person bucketing on the old key).
            // Priority: DB override > request's anon_distinct_id > distinct_id
            if feature_flag.has_experience_continuity() {
                if let Some(hash_key_override) = hash_key_overrides
                    .as_ref()
                    .and_then(|h| h.get(&feature_flag.key))
                {
                    Ok(hash_key_override.clone())
                } else if let Some(request_override) = request_hash_key_override {
                    // Use the request's anon_distinct_id as fallback when no DB override exists
                    Ok(request_override.clone())
                } else {
                    Ok(self.distinct_id.clone())
                }
            } else {
                Ok(self.distinct_id.clone())
            }
        }
    }

    /// This function takes a identifier and a feature flag key and returns a float between 0 and 1.
    /// Given the same identifier and key, it'll always return the same float. These floats are
    /// uniformly distributed between 0 and 1, so if we want to show this feature to 20% of traffic
    /// we can do _hash(key, identifier) < 0.2
    fn get_hash(
        &self,
        feature_flag: &FeatureFlag,
        salt: &str,
        aggregation_group_type_index: Option<i32>,
        hash_key_overrides: Option<&HashMap<String, String>>,
        request_hash_key_override: &Option<String>,
    ) -> Result<f64, FlagError> {
        let hashed_identifier = self.hashed_identifier(
            feature_flag,
            aggregation_group_type_index,
            hash_key_overrides,
            request_hash_key_override,
        )?;
        if hashed_identifier.is_empty() {
            // Nothing to hash. `check_rollout` compares `hash <= percentage / 100.0`, so a
            // 0.0 hash matches every rollout threshold, including 0.
            return Ok(0.0);
        }

        calculate_hash(&format!("{}.", feature_flag.key), &hashed_identifier, salt)
    }

    fn get_holdout_hash(
        &self,
        feature_flag: &FeatureFlag,
        salt: Option<&str>,
        request_hash_key_override: &Option<String>,
    ) -> Result<f64, FlagError> {
        // Holdouts use the flag-level aggregation for hashing
        let hashed_identifier = self.hashed_identifier(
            feature_flag,
            feature_flag.get_group_type_index(),
            None,
            request_hash_key_override,
        )?;
        let hash = calculate_hash("holdout-", &hashed_identifier, salt.unwrap_or(""))?;
        Ok(hash)
    }

    /// Check if a feature flag should be shown based on its rollout percentage.
    ///
    /// Calculates a hash of the identifier (determined by `aggregation_group_type_index`)
    /// and compares it to the rollout percentage. Returns whether the flag matched and why.
    fn check_rollout(
        &self,
        feature_flag: &FeatureFlag,
        rollout_percentage: f64,
        aggregation_group_type_index: Option<i32>,
        hash_key_overrides: Option<&HashMap<String, String>>,
        request_hash_key_override: &Option<String>,
    ) -> Result<(bool, FeatureFlagMatchReason), FlagError> {
        let included = crate::flags::v1_bucketing::is_in_rollout(rollout_percentage, || {
            self.get_hash(
                feature_flag,
                "",
                aggregation_group_type_index,
                hash_key_overrides,
                request_hash_key_override,
            )
        })?;
        if included {
            Ok((true, FeatureFlagMatchReason::ConditionMatch))
        } else {
            Ok((false, FeatureFlagMatchReason::OutOfRolloutBound))
        }
    }

    fn condition_variant(
        &self,
        flag: &FeatureFlag,
        condition: &FlagPropertyGroup,
        aggregation: Option<i32>,
        hash_key_overrides: Option<&HashMap<String, String>>,
        request_hash_key_override: &Option<String>,
    ) -> Result<Option<String>, FlagError> {
        match flag.pinned_variant(condition) {
            Some(pinned) => Ok(Some(pinned.to_string())),
            None => self.get_matching_variant(
                flag,
                aggregation,
                hash_key_overrides,
                request_hash_key_override,
            ),
        }
    }

    /// Returns the variant key for this flag based on the hashed identifier.
    /// The aggregation determines which identifier is hashed (group key vs distinct_id).
    pub(crate) fn get_matching_variant(
        &self,
        feature_flag: &FeatureFlag,
        aggregation_group_type_index: Option<i32>,
        hash_key_overrides: Option<&HashMap<String, String>>,
        request_hash_key_override: &Option<String>,
    ) -> Result<Option<String>, FlagError> {
        let hash = self.get_hash(
            feature_flag,
            "variant",
            aggregation_group_type_index,
            hash_key_overrides,
            request_hash_key_override,
        )?;
        Ok(
            crate::flags::v1_bucketing::select_variant(hash, feature_flag.get_variants())
                .map(str::to_owned),
        )
    }

    /// Get matching payload for a feature flag.
    ///
    /// This function retrieves the payload associated with a matching variant of a feature flag.
    /// It takes the matched variant key and the feature flag itself as inputs and returns the payload.
    fn get_matching_payload(
        &self,
        match_variant: Option<&str>,
        feature_flag: &FeatureFlag,
    ) -> Option<serde_json::Value> {
        let variant = match_variant.unwrap_or("true");
        feature_flag.get_payload(variant)
    }

    /// Prepares all database-sourced data needed for flag evaluation.
    /// This includes:
    /// - Static cohort memberships
    /// - Realtime cohort memberships (via behavioral cohorts database)
    /// - Group type mappings
    /// - Person and group properties
    ///
    /// The data is cached in FlagEvaluationState to avoid repeated DB lookups
    /// during subsequent flag evaluations.
    pub async fn prepare_flag_evaluation_state(
        &mut self,
        flags: &[&FeatureFlag],
    ) -> Result<(), FlagError> {
        // Use preloaded cohorts from the flags cache when available (already scoped
        // to only referenced cohorts). Fall back to CohortCacheManager which fetches
        // ALL cohorts for the team.
        let cohorts: Arc<[Cohort]> = match self.preloaded_cohorts.take() {
            Some(preloaded) => {
                inc(
                    FLAG_COHORT_SOURCE_COUNTER,
                    &[("source".to_string(), "preloaded".to_string())],
                    1,
                );
                preloaded
            }
            None => {
                inc(
                    FLAG_COHORT_SOURCE_COUNTER,
                    &[("source".to_string(), "cache_manager".to_string())],
                    1,
                );
                Arc::from(self.cohort_cache.get_cohorts(self.team_id).await?)
            }
        };
        self.flag_evaluation_state.set_cohorts(Arc::clone(&cohorts));

        // Get static cohort IDs
        // NOTE: relies on `is_static` and `uses_realtime_membership()` being mutually exclusive
        // (a cohort with is_static=true should never have CohortType::Realtime/Behavioral).
        debug_assert!(
            !cohorts
                .iter()
                .any(|c| c.is_static && self.membership_stamp_policy.uses_realtime_membership(c)),
            "Cohort cannot be both static and realtime"
        );
        let static_cohort_ids: Vec<CohortId> = cohorts
            .iter()
            .filter(|c| c.is_static)
            .map(|c| c.id)
            .collect();

        // Load group type mappings if needed. Errors are intentionally not propagated here:
        // in the batch path (evaluate_flags_with_overrides), a group type mapping failure
        // should not poison person-based flags in the same batch. prepare_group_data
        // gracefully returns an empty map when the mapping was never loaded, so
        // group-based flags will fail individually rather than taking down the whole batch.
        if self.initialize_group_type_mappings_if_needed(flags).await {
            tracing::warn!("Failed to init group type mappings");
        }

        // Then prepare group mappings and properties
        // This should be _wicked_ fast since it's async and is just pulling from a cache that's already in memory
        let group_timer = common_metrics::timing_guard(FLAG_GROUP_CACHE_FETCH_TIME, &[]);
        let group_data = self.prepare_group_data(flags)?;
        group_timer.fin();

        // Single DB operation for properties and cohorts
        let db_fetch_timer = common_metrics::timing_guard(FLAG_DB_PROPERTIES_FETCH_TIME, &[]);
        match before_persons_db_deadline(
            self.persons_db_deadline,
            db_operations::FETCH_PROPERTIES,
            fetch_and_locally_cache_all_relevant_properties(
                &mut self.flag_evaluation_state,
                self.router.get_persons_reader().clone(),
                self.distinct_id.clone(),
                self.team_id,
                &group_data,
                static_cohort_ids,
            ),
        )
        .await
        {
            Ok(_) => {
                inc(DB_PERSON_AND_GROUP_PROPERTIES_READS_COUNTER, &[], 1);
                db_fetch_timer.label("outcome", "success").fin();
            }
            Err(e) => {
                error!(
                    "Error fetching properties for team {} distinct_id {}: {:?}",
                    self.team_id, self.distinct_id, e
                );
                db_fetch_timer.label("outcome", "error").fin();
                return Err(e);
            }
        }

        // Fetch realtime cohort memberships for Realtime/Behavioral cohorts.
        // This is a separate DB call to the behavioral cohorts database, isolated from
        // the static cohort path above which uses the persons_reader pool.
        let realtime_cohort_ids: Vec<CohortId> = if self.enable_realtime_cohort_evaluation {
            cohorts
                .iter()
                .inspect(|c| record_stamp_policy_divergence(c, self.membership_stamp_policy))
                .filter(|c| self.membership_stamp_policy.uses_realtime_membership(c))
                .map(|c| c.id)
                .collect()
        } else {
            Vec::new()
        };

        if !realtime_cohort_ids.is_empty() {
            with_canonical_log(|log| {
                log.realtime_cohorts_evaluated += realtime_cohort_ids.len();
            });

            let all_non_member = || -> HashMap<CohortId, bool> {
                realtime_cohort_ids.iter().map(|id| (*id, false)).collect()
            };

            let realtime_memberships = if let Some(person_uuid) =
                self.flag_evaluation_state.get_person_uuid()
            {
                let query_labels = [("team_id".to_string(), self.team_id.to_string())];
                // High precision: cache hits complete in microseconds, and plain
                // timing_guard truncates to integer ms, collapsing them all to 0.
                let realtime_timer =
                    timing_guard_high_precision(FLAG_REALTIME_COHORT_QUERY_TIME, &query_labels);
                let realtime_start = std::time::Instant::now();

                let result = self
                    .cohort_membership_provider
                    .check_memberships(self.team_id, person_uuid, &realtime_cohort_ids)
                    .await;

                let duration = realtime_start.elapsed();
                realtime_timer.fin();
                with_canonical_log(|log| {
                    log.realtime_cohort_queries += 1;
                    log.realtime_cohort_query_time_ms += duration.as_millis() as u64;
                });

                match result {
                    Ok(memberships) => memberships,
                    Err(e) => {
                        inc(FLAG_REALTIME_COHORT_QUERY_ERROR_COUNTER, &query_labels, 1);
                        warn!(
                            team_id = self.team_id,
                            person_uuid = %person_uuid,
                            realtime_cohort_count = realtime_cohort_ids.len(),
                            error = %e,
                            "Realtime cohort membership lookup failed, treating all as non-members"
                        );
                        // Graceful degradation: treat all realtime cohorts as non-members
                        all_non_member()
                    }
                }
            } else {
                // No person UUID available (anonymous user). Realtime cohorts return false.
                all_non_member()
            };

            self.flag_evaluation_state
                .merge_cohort_matches(realtime_memberships);
        }

        Ok(())
    }

    /// Every group type index a flag can read during evaluation: flag-level aggregation,
    /// per-condition aggregation, and the explicit `group_type_index` on individual group
    /// property filters. Indexes may repeat, so collect into a set where uniqueness matters.
    ///
    /// The filter-level indexes matter for mixed targeting, where a person-aggregated
    /// condition still carries a group filter with its own index.
    /// `PropertyContext::resolve_for_filter` resolves such a filter against exactly that
    /// index, so omitting it from the fetch would silently resolve the filter against an
    /// empty map instead of the group's real properties.
    pub(crate) fn referenced_group_type_indexes(
        flag: &FeatureFlag,
    ) -> impl Iterator<Item = GroupTypeIndex> + '_ {
        let requirements = flag.filters.requirements();
        requirements
            .aggregation_group_type_indexes
            .into_iter()
            .chain(requirements.group_property_type_indexes)
    }

    /// Builds a paired mapping from group type index to group key for flag
    /// evaluation, filtered to only the group types required by the given flags.
    fn prepare_group_data(
        &mut self,
        flags: &[&FeatureFlag],
    ) -> Result<HashMap<GroupTypeIndex, String>, FlagError> {
        let required_type_indexes: HashSet<GroupTypeIndex> = flags
            .iter()
            .flat_map(|flag| Self::referenced_group_type_indexes(flag))
            .collect();

        if required_type_indexes.is_empty() {
            return Ok(HashMap::new());
        }

        let Some(mapping) = self.group_type_mapping.mapping() else {
            return Ok(HashMap::new());
        };
        let types_to_indexes = mapping.group_types_to_indexes();

        let group_type_to_key: HashMap<GroupTypeIndex, String> = self
            .groups
            .iter()
            .filter_map(|(group_type, group_key_value)| {
                let group_key = match group_key_value {
                    Value::String(s) => s.clone(),
                    Value::Number(n) => n.to_string(),
                    _ => return None,
                };
                types_to_indexes
                    .get(group_type)
                    .cloned()
                    .filter(|idx| required_type_indexes.contains(idx))
                    .map(|group_type_index| (group_type_index, group_key))
            })
            .collect();

        Ok(group_type_to_key)
    }

    /// Get person properties from the `FlagEvaluationState` only, returning a reference.
    fn get_person_properties_from_evaluation_state(
        &self,
    ) -> Result<&HashMap<String, Value>, FlagError> {
        match &self.flag_evaluation_state.person_property_state {
            PersonPropertyState::Fetched(properties) => {
                inc(
                    PROPERTY_CACHE_HITS_COUNTER,
                    &[("type".to_string(), "person_properties".to_string())],
                    1,
                );
                with_canonical_log(|log| log.eval.property_cache_hits += 1);
                Ok(properties)
            }
            PersonPropertyState::Skipped => {
                tracing::debug!(
                    "Person properties not in cache — DB prep was skipped (overrides cover all needed keys)"
                );
                Err(FlagError::person_not_found())
            }
            PersonPropertyState::Pending => {
                inc(
                    PROPERTY_CACHE_MISSES_COUNTER,
                    &[
                        ("type".to_string(), "person_properties".to_string()),
                        ("reason".to_string(), "db_prep_never_ran".to_string()),
                    ],
                    1,
                );
                with_canonical_log(|log| {
                    log.eval.property_cache_misses += 1;
                    log.eval.person_properties_not_cached = true;
                });
                tracing::error!("Person properties not found — DB prep never ran");
                Err(FlagError::person_not_found())
            }
        }
    }

    /// Get group properties for the given group type index from the `FlagEvaluationState` only. Returns empty HashMap if not found.
    fn get_group_properties_from_evaluation_state(
        &self,
        group_type_index: GroupTypeIndex,
    ) -> Result<HashMap<String, Value>, FlagError> {
        let group_properties = self.flag_evaluation_state.get_group_properties();
        if let Some(properties) = group_properties.get(&group_type_index) {
            inc(
                PROPERTY_CACHE_HITS_COUNTER,
                &[("type".to_string(), "group_properties".to_string())],
                1,
            );
            with_canonical_log(|log| log.eval.property_cache_hits += 1);
            let mut result = HashMap::new();
            result.clone_from(properties);
            Ok(result)
        } else {
            inc(
                PROPERTY_CACHE_MISSES_COUNTER,
                &[("type".to_string(), "group_properties".to_string())],
                1,
            );
            with_canonical_log(|log| {
                log.eval.property_cache_misses += 1;
                log.eval.group_properties_not_cached = true;
            });
            // Return an empty HashMap instead of an error: a group with no `posthog_group`
            // row genuinely has no properties. Whether the fetch actually ran is tracked
            // separately by `FlagEvaluationState::group_properties_pending`, which
            // `is_condition_match` consults so a fetch miss can't be read as "unset".
            Ok(HashMap::new())
        }
    }

    /// If experience continuity is enabled, we need to process the hash key override.
    /// See [`FeatureFlagMatcher::process_hash_key_override`] for more details.
    async fn process_hash_key_override_if_needed(
        &self,
        flags_have_experience_continuity_enabled: bool,
        hash_key_override: Option<String>,
    ) -> (Option<HashMap<String, String>>, bool) {
        let hash_key_timer = common_metrics::timing_guard(FLAG_HASH_KEY_PROCESSING_TIME, &[]);
        let (hash_key_overrides, flag_hash_key_override_error) =
            if flags_have_experience_continuity_enabled {
                common_metrics::inc(FLAG_EXPERIENCE_CONTINUITY_REQUESTS_COUNTER, &[], 1);
                with_canonical_log(|log| log.outcome_marks.mark_needs_persons());
                match hash_key_override {
                    Some(hash_key) => {
                        let target_distinct_ids = vec![self.distinct_id.clone(), hash_key.clone()];
                        self.process_hash_key_override(hash_key, target_distinct_ids)
                            .await
                    }
                    // If no hash key override is provided, we need to look up existing overrides.
                    // Most of the time this is fine because our client side sdks usually include $anon_distinct_id in their requests,
                    // but if a customer is using hash key overrides across a client sdk and a server sdk then the experience
                    // will be inconsistent because server sdks won't include $anon_distinct_id in their requests.
                    // In addition, this behavior is consistent with /decide.
                    None => {
                        match before_persons_db_deadline(
                            self.persons_db_deadline,
                            db_operations::GET_HASH_KEY_OVERRIDES,
                            get_feature_flag_hash_key_overrides(
                                self.router.get_persons_reader().clone(),
                                pool_names::PERSONS_READER,
                                self.router.get_persons_writer().clone(),
                                self.team_id,
                                vec![self.distinct_id.clone()],
                            ),
                        )
                        .await
                        {
                            Ok(overrides) => (Some(overrides), false),
                            Err(e) => {
                                error!(
                                    "Failed to get feature flag hash key overrides for team {} distinct_id {}: {:?}",
                                    self.team_id, self.distinct_id, e
                                );
                                (None, true)
                            }
                        }
                    }
                }
            } else {
                // if experience continuity is not enabled, we don't need to worry about hash key overrides
                (None, false)
            };

        // If there was an error in processing hash key overrides, increment the error counter
        if flag_hash_key_override_error {
            let reason = "hash_key_override_error";
            common_metrics::inc(
                FLAG_EVALUATION_ERROR_COUNTER,
                &[("reason".to_string(), reason.to_string())],
                1,
            );
        }

        hash_key_timer
            .label(
                "outcome",
                if flag_hash_key_override_error {
                    "error"
                } else {
                    "success"
                },
            )
            .fin();

        // Track hash key override status in canonical log
        if flag_hash_key_override_error {
            with_canonical_log(|log| log.hash_key_override_status = Some("error"));
        } else if let Some(ref overrides) = hash_key_overrides {
            let status = if overrides.is_empty() {
                "empty"
            } else {
                "found"
            };
            with_canonical_log(|log| log.hash_key_override_status = Some(status));
        }

        (hash_key_overrides, flag_hash_key_override_error)
    }

    /// Initializes the group type mapping cache if needed.
    ///
    /// This function checks if any of the feature flags have group type indices and initializes the group type mapping cache if needed.
    /// It returns a boolean indicating if there were any errors while initializing the group type mapping cache.
    async fn initialize_group_type_mappings_if_needed(&mut self, flags: &[&FeatureFlag]) -> bool {
        // The lookup is request-scoped, and the batch path runs it before
        // `prepare_flag_evaluation_state` runs it again. `GroupTypeCacheManager` does not cache
        // failures, so without reusing the recorded outcome a single outage costs every affected
        // request two waits on two failed queries.
        match self.group_type_mapping {
            GroupTypeMappingState::Loaded(_) => return false,
            GroupTypeMappingState::Failed(_) => return true,
            GroupTypeMappingState::Uninitialized => {}
        }

        // Check if we need to fetch group type mappings — any flag references a group type,
        // whether through aggregation or through an individual group property filter. The
        // filter case must be included: without the mapping, `prepare_group_data` returns
        // an empty map and those filters evaluate against no properties at all.
        let has_type_indexes = flags.iter().any(|flag| {
            !self.filtered_out_flag_ids.contains(&flag.id)
                && Self::referenced_group_type_indexes(flag).next().is_some()
        });

        if !has_type_indexes {
            return false;
        }
        with_canonical_log(|log| log.outcome_marks.mark_needs_persons());

        let group_type_mapping_timer = common_metrics::timing_guard(FLAG_GROUP_DB_FETCH_TIME, &[]);
        let mut errors_while_computing_flags = false;

        // The cache applies the deadline itself, so that this request's deadline cannot cancel
        // the fetch that other requests for the team wait on.
        let mappings = self
            .group_type_cache
            .get_mappings(self.team_id, self.persons_db_deadline)
            .await;
        record_persons_db_deadline_exceeded(db_operations::FETCH_GROUP_TYPE_MAPPING, &mappings);
        match mappings {
            Ok(mapping) => {
                if mapping.is_empty() {
                    // Empty mappings are not an error — the team simply has no group types
                    // configured. Group-based flags won't match, but person flags in the same
                    // batch should succeed without surfacing errorsWhileComputingFlags to the
                    // client.
                    tracing::warn!("No group type mappings found for team {}", self.team_id);
                }
                self.group_type_mapping = GroupTypeMappingState::Loaded(mapping);
            }
            Err(e) => {
                errors_while_computing_flags = true;
                self.group_type_mapping = GroupTypeMappingState::Failed(Arc::new(e));
            }
        }

        group_type_mapping_timer
            .label(
                "outcome",
                if errors_while_computing_flags {
                    "error"
                } else {
                    "success"
                },
            )
            .fin();

        errors_while_computing_flags
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_promote_evaluation_type_none_to_sequential() {
        assert_eq!(
            EvaluationType::promote(None, EvaluationType::Sequential),
            Some(EvaluationType::Sequential)
        );
    }

    #[test]
    fn test_promote_evaluation_type_none_to_parallel() {
        assert_eq!(
            EvaluationType::promote(None, EvaluationType::Parallel),
            Some(EvaluationType::Parallel)
        );
    }

    #[test]
    fn test_promote_evaluation_type_sequential_to_parallel() {
        assert_eq!(
            EvaluationType::promote(Some(EvaluationType::Sequential), EvaluationType::Parallel),
            Some(EvaluationType::Parallel)
        );
    }

    #[test]
    fn test_promote_evaluation_type_parallel_stays_sticky() {
        assert_eq!(
            EvaluationType::promote(Some(EvaluationType::Parallel), EvaluationType::Sequential),
            Some(EvaluationType::Parallel)
        );
    }

    #[test]
    fn test_promote_evaluation_type_sequential_stays_sequential() {
        assert_eq!(
            EvaluationType::promote(Some(EvaluationType::Sequential), EvaluationType::Sequential),
            Some(EvaluationType::Sequential)
        );
    }

    #[test]
    fn test_panic_fallback_preserves_flag_identity() {
        let team_id = 42;
        let snapshots = vec![
            FlagSnapshot {
                key: "flag_a".to_string(),
                id: 10,
                version: Some(3),
                non_v1: None,
            },
            FlagSnapshot {
                key: "flag_b".to_string(),
                id: 20,
                version: None,
                non_v1: Some(Arc::new(NonV1Config {
                    parsed_v2: None,
                    document: serde_json::value::RawValue::from_string("{}".to_string()).unwrap(),
                })),
            },
            FlagSnapshot {
                key: "flag_c".to_string(),
                id: 30,
                version: Some(1),
                non_v1: None,
            },
        ];

        let results = FeatureFlagMatcher::build_panic_fallback(snapshots, team_id);

        assert_eq!(results.len(), 3);

        let (stub_a, err_a) = &results[0];
        assert_eq!(stub_a.key, "flag_a");
        assert_eq!(stub_a.id, 10);
        assert_eq!(stub_a.version, Some(3));
        assert!(matches!(
            err_a,
            Err(FlagError::InternalError {
                code: "batch_evaluation_panicked",
                ..
            })
        ));

        let (stub_b, err_b) = &results[1];
        assert_eq!(stub_b.key, "flag_b");
        assert_eq!(stub_b.id, 20);
        assert_eq!(stub_b.version, None);
        assert!(!stub_b.filters.is_v1());
        assert!(stub_a.filters.is_v1());
        assert!(matches!(
            err_b,
            Err(FlagError::InternalError {
                code: "batch_evaluation_panicked",
                ..
            })
        ));

        let (stub_c, err_c) = &results[2];
        assert_eq!(stub_c.key, "flag_c");
        assert_eq!(stub_c.id, 30);
        assert_eq!(stub_c.version, Some(1));
        assert!(matches!(
            err_c,
            Err(FlagError::InternalError {
                code: "batch_evaluation_panicked",
                ..
            })
        ));

        for (stub, _) in &results {
            assert_eq!(stub.team_id, team_id);
            assert!(stub.active);
            assert_eq!(stub.name, None);
            assert!(!stub.deleted);
            assert!(stub.filters.groups.is_empty());
        }
    }

    /// A stored hash-key override must only steer bucketing while the flag *currently*
    /// has experience continuity enabled. When continuity is turned off, the row written
    /// back while it was on is never deleted — so the matcher must fall back to the raw
    /// distinct_id and ignore the stale override, otherwise every distinct_id of the
    /// person keeps bucketing on the old key and resolves to the same stale value.
    #[rstest::rstest]
    #[case::continuity_off_ignores_stale_override(Some(false), None, "logged-in-username")]
    #[case::continuity_unset_ignores_stale_override(None, None, "logged-in-username")]
    #[case::continuity_on_applies_override(Some(true), None, "stale-anon-id")]
    #[case::continuity_on_stored_override_beats_request_override(
        Some(true),
        Some("request-anon-id"),
        "stale-anon-id"
    )]
    #[tokio::test]
    async fn test_hashed_identifier_respects_current_continuity_for_stored_override(
        #[case] ensure_experience_continuity: Option<bool>,
        #[case] request_hash_key_override: Option<&str>,
        #[case] expected_identifier: &str,
    ) {
        use crate::utils::test_utils::{mock_group_type_cache, TestContext};

        let context = TestContext::new(None).await;
        let cohort_cache = Arc::new(CohortCacheManager::new(
            context.non_persons_reader.clone(),
            None,
            None,
        ));
        let matcher = FeatureFlagMatcher::new(
            "logged-in-username".to_string(),
            None, // device_id
            1,
            context.create_postgres_router(),
            cohort_cache,
            mock_group_type_cache(HashMap::new()),
            None,
        );

        // Override left behind from when this flag still had continuity enabled.
        let overrides = HashMap::from([("my_flag".to_string(), "stale-anon-id".to_string())]);
        let flag = FeatureFlag {
            key: "my_flag".to_string(),
            ensure_experience_continuity,
            ..Default::default()
        };

        let request_override = request_hash_key_override.map(str::to_string);
        let identifier = matcher
            .hashed_identifier(&flag, None, Some(&overrides), &request_override)
            .unwrap();

        assert_eq!(identifier, expected_identifier);
    }

    #[rstest::rstest]
    #[case::injects_when_overrides_absent("user_42", None, "user_42", vec![])]
    #[case::injects_when_overrides_lack_distinct_id(
        "user_42",
        Some(vec![("email", "[email protected]")]),
        "user_42",
        vec![("email", "[email protected]")],
    )]
    #[case::explicit_override_wins(
        "user_42",
        Some(vec![("distinct_id", "explicit")]),
        "explicit",
        vec![],
    )]
    #[case::injects_empty_string_when_overrides_absent("", None, "", vec![])]
    #[case::injects_empty_string_when_overrides_lack_distinct_id(
        "",
        Some(vec![("foo", "bar")]),
        "",
        vec![("foo", "bar")],
    )]
    #[case::explicit_override_wins_over_empty_request_distinct_id(
        "",
        Some(vec![("distinct_id", "explicit")]),
        "explicit",
        vec![],
    )]
    fn test_merge_distinct_id_into_person_properties(
        #[case] request_distinct_id: &str,
        #[case] overrides: Option<Vec<(&str, &str)>>,
        #[case] expected_distinct_id: &str,
        #[case] expected_extras: Vec<(&str, &str)>,
    ) {
        let overrides = overrides.map(|kvs| {
            kvs.into_iter()
                .map(|(k, v)| (k.to_string(), Value::String(v.to_string())))
                .collect::<HashMap<_, _>>()
        });
        let result = merge_distinct_id_into_person_properties(request_distinct_id, overrides);
        assert_eq!(
            result.get("distinct_id"),
            Some(&Value::String(expected_distinct_id.to_string())),
        );
        for (k, v) in &expected_extras {
            assert_eq!(result.get(*k), Some(&Value::String((*v).to_string())));
        }
        assert_eq!(result.len(), 1 + expected_extras.len());
    }

    #[test]
    fn test_cohort_analysis_keeps_resolved_memberships_when_another_cohort_fails() {
        // A flag can name a cohort the flags payload no longer carries, because Django omits
        // deleted and cross-team cohorts but keeps the filters that name them. Resolving the set as
        // a unit drops the memberships that did resolve along with it.
        let cohort: Cohort = serde_json::from_value(serde_json::json!({
            "id": 1,
            "team_id": 1,
            "deleted": false,
            "is_calculating": false,
            "is_static": false,
            "errors_calculating": 0,
            "groups": [],
            "filters": {
                "properties": {
                    "type": "OR",
                    "values": [{
                        "type": "OR",
                        "values": [{
                            "key": "plan",
                            "type": "person",
                            "value": "enterprise",
                            "operator": "exact"
                        }]
                    }]
                }
            }
        }))
        .unwrap();

        // Cohort 999 comes first, so a resolver that stopped on the first failure would lose
        // cohort 1 instead of reporting it.
        let filters: Vec<PropertyFilter> = [999, 1]
            .into_iter()
            .map(|id| {
                serde_json::from_value(serde_json::json!({
                    "key": "id",
                    "value": id,
                    "type": "cohort",
                    "operator": "in"
                }))
                .unwrap()
            })
            .collect();
        let filter_refs: Vec<&PropertyFilter> = filters.iter().collect();

        let target_properties =
            HashMap::from([("plan".to_string(), Value::String("enterprise".to_string()))]);

        // Cohort 999 is absent from the loaded list, so resolving it fails.
        let (resolved, errors) = FeatureFlagMatcher::resolve_cohort_matches_from_cache(
            &filter_refs,
            &target_properties,
            &[cohort],
            HashMap::new(),
            PropertyMatchingContext::new(Tz::UTC, false),
        );

        assert_eq!(
            errors.len(),
            1,
            "the failing cohort must be reported, so the strict path can still fail on it"
        );
        assert_eq!(
            resolved.get(&1),
            Some(&true),
            "a resolved membership must survive another cohort failing"
        );
        assert_eq!(
            resolved.get(&999),
            None,
            "an unresolvable cohort must be absent, so analysis reads it as unknown"
        );
    }
}