posthog_rs/

feature_flags.rs

use chrono::{DateTime, NaiveDate, Utc};
use regex::Regex;
use serde::{Deserialize, Serialize};
use sha1::{Digest, Sha1};
use std::collections::{HashMap, HashSet};
use std::fmt;
use std::sync::{Mutex, OnceLock};

/// Global cache for compiled regexes to avoid recompilation on every flag evaluation
static REGEX_CACHE: OnceLock<Mutex<HashMap<String, Option<Regex>>>> = OnceLock::new();

/// Salt used for rollout percentage hashing. Intentionally empty to match PostHog's
/// consistent hashing algorithm across all SDKs. This ensures the same user gets
/// the same rollout decision regardless of which SDK evaluates the flag.
const ROLLOUT_HASH_SALT: &str = "";

/// Salt used for multivariate variant selection. Uses "variant" to ensure consistent
/// variant assignment across all PostHog SDKs for the same user/flag combination.
const VARIANT_HASH_SALT: &str = "variant";

fn get_cached_regex(pattern: &str) -> Option<Regex> {
    let cache = REGEX_CACHE.get_or_init(|| Mutex::new(HashMap::new()));
    let mut cache_guard = match cache.lock() {
        Ok(guard) => guard,
        Err(_) => {
            tracing::warn!(
                pattern,
                "Regex cache mutex poisoned, treating as cache miss"
            );
            return None;
        }
    };

    if let Some(cached) = cache_guard.get(pattern) {
        return cached.clone();
    }

    let compiled = Regex::new(pattern).ok();
    cache_guard.insert(pattern.to_string(), compiled.clone());
    compiled
}

/// The value of a feature flag evaluation.
///
/// Feature flags can return either a boolean (enabled/disabled) or a string
/// (for multivariate flags where users are assigned to different variants).
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(untagged)]
pub enum FlagValue {
    /// Flag is either enabled (true) or disabled (false)
    Boolean(bool),
    /// Flag returns a specific variant key (e.g., "control", "test", "variant-a")
    String(String),
}

/// Error returned when a feature flag cannot be evaluated locally.
///
/// This typically occurs when:
/// - Required person/group properties are missing
/// - A cohort referenced by the flag is not in the local cache
/// - A dependent flag is not available locally
/// - An unknown operator is encountered
#[derive(Debug)]
pub struct InconclusiveMatchError {
    /// Human-readable description of why evaluation was inconclusive
    pub message: String,
}

impl InconclusiveMatchError {
    /// Create an inconclusive-match error with a human-readable message.
    pub fn new(message: &str) -> Self {
        Self {
            message: message.to_string(),
        }
    }
}

impl fmt::Display for InconclusiveMatchError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.message)
    }
}

impl std::error::Error for InconclusiveMatchError {}

impl Default for FlagValue {
    fn default() -> Self {
        FlagValue::Boolean(false)
    }
}

/// A feature flag definition from PostHog.
///
/// Contains all the information needed to evaluate whether a flag should be
/// enabled for a given user, including targeting rules and rollout percentages.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FeatureFlag {
    /// Unique identifier for the flag (e.g., "new-checkout-flow")
    pub key: String,
    /// Whether the flag is currently active. Inactive flags always return false.
    pub active: bool,
    /// Targeting rules and rollout configuration
    #[serde(default)]
    pub filters: FeatureFlagFilters,
    /// Whether the flag is linked to an experiment, as reported by the
    /// local-evaluation definitions endpoint. Tri-state: `Some(true)`/`Some(false)`
    /// when the server reports it, `None` when it does not (older server). Drives
    /// the `$feature_flag_has_experiment` property and event minimization.
    #[serde(default)]
    pub has_experiment: Option<bool>,
}

/// Targeting rules and configuration for a feature flag.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct FeatureFlagFilters {
    /// List of condition groups (evaluated with OR logic between groups)
    #[serde(default)]
    pub groups: Vec<FeatureFlagCondition>,
    /// Multivariate configuration for A/B tests with multiple variants
    #[serde(default)]
    pub multivariate: Option<MultivariateFilter>,
    /// JSON payloads associated with flag variants
    #[serde(default)]
    pub payloads: HashMap<String, serde_json::Value>,
    /// Group type index this flag targets at the flag level. `None` means person
    /// targeting (or mixed, when individual conditions set their own).
    #[serde(default)]
    pub aggregation_group_type_index: Option<i32>,
    /// When `true`, local evaluation stops and returns a definitive disabled
    /// result as soon as a condition group's property filters match (or it has
    /// no property filters) but the rollout percentage excludes the user,
    /// instead of falling through to later condition groups. Defaults to
    /// `false`, which preserves the legacy fall-through behavior.
    #[serde(default)]
    pub early_exit: bool,
}

/// A single condition group within a feature flag's targeting rules.
///
/// All properties within a condition must match (AND logic), and the user
/// must fall within the rollout percentage to be included.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FeatureFlagCondition {
    /// Property filters that must all match (AND logic)
    #[serde(default)]
    pub properties: Vec<Property>,
    /// Percentage of matching users who should see this flag (0-100)
    pub rollout_percentage: Option<f64>,
    /// Specific variant to serve for this condition (for variant overrides)
    pub variant: Option<String>,
    /// Optional per-condition aggregation override used by mixed-targeting flags.
    /// When set, this condition targets the specified group type instead of the
    /// flag-level aggregation. `None` means person targeting under a mixed flag.
    #[serde(default)]
    pub aggregation_group_type_index: Option<i32>,
}

/// A property filter used in feature flag targeting.
///
/// Supports various operators for matching user properties against expected values.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Property {
    /// The property key to match (e.g., "email", "country", "$feature/other-flag")
    pub key: String,
    /// The value to compare against
    pub value: serde_json::Value,
    /// Comparison operator. Supported property operators include `"exact"`,
    /// `"is_not"`, `"icontains"`, `"not_icontains"`, `"starts_with"`,
    /// `"not_starts_with"`, `"ends_with"`, `"not_ends_with"`, `"regex"`,
    /// `"not_regex"`, `"gt"`, `"gte"`, `"lt"`, `"lte"`, `"is_set"`,
    /// `"is_not_set"`, `"is_date_before"`, `"is_date_after"`, and the
    /// `"semver_*"` operators used by PostHog version targeting.
    #[serde(
        default = "default_operator",
        deserialize_with = "deserialize_operator"
    )]
    pub operator: String,
    /// Property type. Use `Some("cohort")` for cohort membership checks; flag
    /// dependency checks use a property key that starts with `$feature/`.
    #[serde(rename = "type")]
    pub property_type: Option<String>,
}

fn default_operator() -> String {
    "exact".to_string()
}

fn deserialize_operator<'de, D>(deserializer: D) -> Result<String, D::Error>
where
    D: serde::Deserializer<'de>,
{
    Ok(Option::<String>::deserialize(deserializer)?.unwrap_or_else(default_operator))
}

#[derive(Deserialize)]
struct CohortProperty {
    #[serde(flatten)]
    property: Property,
    #[serde(default)]
    negation: bool,
}

/// Definition of a cohort for local evaluation
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CohortDefinition {
    /// Unique identifier for the cohort.
    pub id: String,
    /// Properties can be either:
    /// - A JSON object with "type" and "values" for complex property groups
    /// - Or a direct `Vec<Property>` for simple cases
    #[serde(default)]
    pub properties: serde_json::Value,
}

impl CohortDefinition {
    /// Create a new cohort definition with a simple property list.
    ///
    /// # Parameters
    ///
    /// - `id`: Cohort identifier.
    /// - `properties`: Property filters that define cohort membership.
    pub fn new(id: String, properties: Vec<Property>) -> Self {
        Self {
            id,
            properties: serde_json::to_value(properties).unwrap_or_default(),
        }
    }

    /// Parse the properties from the JSON structure.
    ///
    /// PostHog cohort properties come in format:
    /// `{"type": "AND", "values": [{"type": "property", "key": "...", "value": "...", "operator": "..."}]}`.
    pub fn parse_properties(&self) -> Vec<Property> {
        // If it's an array, treat it as direct property list
        if let Some(arr) = self.properties.as_array() {
            return arr
                .iter()
                .filter_map(|v| serde_json::from_value::<Property>(v.clone()).ok())
                .collect();
        }

        // If it's an object with "values" key, extract properties from there
        if let Some(obj) = self.properties.as_object() {
            if let Some(values) = obj.get("values") {
                if let Some(values_arr) = values.as_array() {
                    return values_arr
                        .iter()
                        .filter_map(|v| {
                            // Handle both direct property objects and nested property groups
                            if v.get("type").and_then(|t| t.as_str()) == Some("property") {
                                serde_json::from_value::<Property>(v.clone()).ok()
                            } else if let Some(inner_values) = v.get("values") {
                                // Recursively handle nested groups
                                inner_values.as_array().and_then(|arr| {
                                    arr.iter()
                                        .filter_map(|inner| {
                                            serde_json::from_value::<Property>(inner.clone()).ok()
                                        })
                                        .next()
                                })
                            } else {
                                None
                            }
                        })
                        .collect();
                }
            }
        }

        Vec::new()
    }
}

/// Context for evaluating properties that may depend on cohorts or other flags.
///
/// `groups`, `group_properties`, and `group_type_mapping` are used to resolve
/// group-targeted and mixed-targeting flags. A group condition (one whose
/// `aggregation_group_type_index` is set, either at the flag or condition level)
/// is bucketed on the group key and matched against group properties looked up
/// via the group type mapping.
pub struct EvaluationContext<'a> {
    /// Cohort definitions available to local evaluation, keyed by cohort ID.
    pub cohorts: &'a HashMap<String, CohortDefinition>,
    /// Feature flag definitions available to evaluate flag dependencies, keyed
    /// by flag key.
    pub flags: &'a HashMap<String, FeatureFlag>,
    /// Distinct ID used for person-targeted flag bucketing.
    pub distinct_id: &'a str,
    /// Group keys for group-targeted flags, keyed by group type.
    pub groups: &'a HashMap<String, String>,
    /// Group properties for group-targeted flags, keyed by group type and then
    /// property name.
    pub group_properties: &'a HashMap<String, HashMap<String, serde_json::Value>>,
    /// Mapping from PostHog group type index to group type name.
    pub group_type_mapping: &'a HashMap<String, String>,
}

/// Configuration for multivariate (A/B/n) feature flags.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct MultivariateFilter {
    /// List of variants with their rollout percentages
    pub variants: Vec<MultivariateVariant>,
}

/// A single variant in a multivariate feature flag.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct MultivariateVariant {
    /// Unique key for this variant (e.g., "control", "test", "variant-a")
    pub key: String,
    /// Percentage of users who should see this variant (0-100)
    pub rollout_percentage: f64,
}

/// Response from the PostHog feature flags API.
///
/// Supports both the v2 API format (with detailed flag information) and the
/// legacy format (simple flag values and payloads).
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(untagged)]
pub enum FeatureFlagsResponse {
    /// v2 API format from `/flags/?v=2` endpoint
    V2 {
        /// Map of flag keys to their detailed evaluation results
        flags: HashMap<String, FlagDetail>,
        /// Whether any errors occurred during flag computation
        #[serde(rename = "errorsWhileComputingFlags")]
        #[serde(default)]
        errors_while_computing_flags: bool,
        /// Whether the response was returned without evaluation because the
        /// project is over its feature-flag quota.
        #[serde(rename = "quotaLimited")]
        #[serde(default)]
        quota_limited: bool,
        /// Unique identifier for this evaluation request, propagated to
        /// `$feature_flag_called` events as `$feature_flag_request_id`
        /// for experiment exposure tracking.
        #[serde(rename = "requestId")]
        #[serde(default)]
        request_id: Option<String>,
        /// Server-controlled gate: when `true`, `$feature_flag_called` events for
        /// non-experiment flags evaluated from this response are minimized to a
        /// strict property allowlist. Absent (older server) fails safe to `false`.
        #[serde(rename = "minimalFlagCalledEvents")]
        #[serde(default)]
        minimal_flag_called_events: bool,
    },
    /// Legacy format from older decide endpoint
    Legacy {
        /// Map of flag keys to their values
        #[serde(rename = "featureFlags")]
        feature_flags: HashMap<String, FlagValue>,
        /// Map of flag keys to their JSON payloads
        #[serde(rename = "featureFlagPayloads")]
        #[serde(default)]
        feature_flag_payloads: HashMap<String, serde_json::Value>,
        /// Any errors that occurred during evaluation
        #[serde(default)]
        errors: Option<Vec<String>>,
    },
}

impl FeatureFlagsResponse {
    /// Convert the response to normalized flag values and payloads.
    ///
    /// # Returns
    ///
    /// A tuple of `(feature_flags, feature_flag_payloads)`, each keyed by flag
    /// key.
    pub fn normalize(
        self,
    ) -> (
        HashMap<String, FlagValue>,
        HashMap<String, serde_json::Value>,
    ) {
        match self {
            FeatureFlagsResponse::V2 { flags, .. } => {
                let mut feature_flags = HashMap::new();
                let mut payloads = HashMap::new();

                for (key, detail) in flags {
                    if detail.enabled {
                        if let Some(variant) = detail.variant {
                            feature_flags.insert(key.clone(), FlagValue::String(variant));
                        } else {
                            feature_flags.insert(key.clone(), FlagValue::Boolean(true));
                        }
                    } else {
                        feature_flags.insert(key.clone(), FlagValue::Boolean(false));
                    }

                    if let Some(metadata) = detail.metadata {
                        if let Some(payload) = metadata.payload {
                            payloads.insert(key, payload);
                        }
                    }
                }

                (feature_flags, payloads)
            }
            FeatureFlagsResponse::Legacy {
                feature_flags,
                feature_flag_payloads,
                ..
            } => (feature_flags, feature_flag_payloads),
        }
    }
}

/// Detailed information about a feature flag evaluation result.
///
/// Returned by the `/flags/?v=2` endpoint with extended information about why a
/// flag evaluated to a particular value.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FlagDetail {
    /// The feature flag key
    pub key: String,
    /// Whether the flag is enabled for this user
    pub enabled: bool,
    /// The variant key if this is a multivariate flag
    pub variant: Option<String>,
    /// Reason explaining why the flag evaluated to this value
    #[serde(default)]
    pub reason: Option<FlagReason>,
    /// Additional metadata about the flag
    #[serde(default)]
    pub metadata: Option<FlagMetadata>,
}

/// Explains why a feature flag evaluated to a particular value.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FlagReason {
    /// Reason code (e.g., "condition_match", "out_of_rollout_bound")
    pub code: String,
    /// Index of the condition that matched (if applicable)
    #[serde(default)]
    pub condition_index: Option<usize>,
    /// Human-readable description of the reason
    #[serde(default)]
    pub description: Option<String>,
}

/// Metadata about a feature flag from the PostHog server.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FlagMetadata {
    /// Unique identifier for this flag
    pub id: u64,
    /// Version number of the flag definition
    pub version: u32,
    /// Optional description of what this flag controls
    pub description: Option<String>,
    /// Optional JSON payload associated with the flag
    pub payload: Option<serde_json::Value>,
    /// Whether the flag is linked to an experiment. Tri-state: `Some(true)`/
    /// `Some(false)` when the `/flags?v=2` metadata reports it, `None` when it is
    /// absent (older server or degraded response). Drives the
    /// `$feature_flag_has_experiment` property and event minimization.
    #[serde(default)]
    pub has_experiment: Option<bool>,
}

const LONG_SCALE: f64 = 0xFFFFFFFFFFFFFFFu64 as f64; // Must be exactly 15 F's to match Python SDK

/// Compute a deterministic hash value for feature flag bucketing.
///
/// Uses SHA-1 to generate a consistent hash in the range [0, 1) for the given
/// key, distinct_id, and salt combination. This ensures users get consistent
/// flag values across requests.
pub fn hash_key(key: &str, distinct_id: &str, salt: &str) -> f64 {
    let hash_key = format!("{key}.{distinct_id}{salt}");
    let mut hasher = Sha1::new();
    hasher.update(hash_key.as_bytes());
    let result = hasher.finalize();
    // The top 60 bits of the digest, i.e. the integer value of its first 15 hex
    // digits. Matches the Python SDK's `int(sha1(...).hexdigest()[:15], 16)`.
    let hash_val = result
        .first_chunk::<8>()
        .map_or(0, |head| u64::from_be_bytes(*head) >> 4);
    hash_val as f64 / LONG_SCALE
}

/// Determine which variant a user should see for a multivariate flag.
///
/// Uses consistent hashing to assign users to variants based on their
/// rollout percentages. Returns `None` if the flag has no variants or
/// the user doesn't fall into any variant bucket.
pub fn get_matching_variant(flag: &FeatureFlag, distinct_id: &str) -> Option<String> {
    let hash_value = hash_key(&flag.key, distinct_id, VARIANT_HASH_SALT);
    let variants = flag.filters.multivariate.as_ref()?.variants.as_slice();

    let mut value_min = 0.0;
    for variant in variants {
        let value_max = value_min + variant.rollout_percentage / 100.0;
        if hash_value >= value_min && hash_value < value_max {
            return Some(variant.key.clone());
        }
        value_min = value_max;
    }
    None
}

/// Result of resolving a condition's effective bucketing + properties.
enum ConditionTarget<'a> {
    /// Use these for bucketing and property matching.
    Use {
        bucketing: String,
        properties: &'a HashMap<String, serde_json::Value>,
    },
    /// Skip this condition (group type unknown or required group not passed in).
    Skip,
    /// Required group properties not provided — try other conditions, surface
    /// inconclusive if nothing else matches.
    Inconclusive,
}

/// Resolve effective bucketing id and properties for a single condition based on
/// the (possibly per-condition) aggregation group type index. Pure-person flags
/// fall through with `distinct_id` and `person_properties`. Group conditions
/// (either flag-level or per-condition aggregation) require the corresponding
/// group key and group properties to be present.
fn resolve_condition_target<'a>(
    condition: &FeatureFlagCondition,
    flag_aggregation: Option<i32>,
    distinct_id: &str,
    person_properties: &'a HashMap<String, serde_json::Value>,
    groups: &HashMap<String, String>,
    group_properties: &'a HashMap<String, HashMap<String, serde_json::Value>>,
    group_type_mapping: &HashMap<String, String>,
) -> ConditionTarget<'a> {
    // Per-condition aggregation falls back to the flag-level value when absent.
    // The two together drive whether this condition is person- or group-targeted.
    let effective_aggregation = condition.aggregation_group_type_index.or(flag_aggregation);

    match effective_aggregation {
        None => ConditionTarget::Use {
            bucketing: distinct_id.to_string(),
            properties: person_properties,
        },
        Some(idx) => {
            let key = idx.to_string();
            let Some(group_type) = group_type_mapping.get(&key) else {
                return ConditionTarget::Skip;
            };
            let Some(group_key) = groups.get(group_type) else {
                return ConditionTarget::Skip;
            };
            let Some(props) = group_properties.get(group_type) else {
                return ConditionTarget::Inconclusive;
            };
            ConditionTarget::Use {
                bucketing: group_key.clone(),
                properties: props,
            }
        }
    }
}

/// Evaluate a feature flag definition against person and optional group
/// context.
///
/// # Parameters
///
/// - `flag`: Feature flag definition to evaluate.
/// - `distinct_id`: Distinct ID used for person bucketing.
/// - `person_properties`: Person properties available to release conditions.
/// - `groups`: Group keys for group-targeted flags, keyed by group type.
/// - `group_properties`: Group properties for group-targeted flags.
/// - `group_type_mapping`: Mapping from PostHog group type index to group type
///   name.
///
/// # Returns
///
/// The matched flag value: `Boolean(false)` for inactive or unmatched flags,
/// `Boolean(true)` for matched boolean flags, or `String(variant)` for matched
/// multivariate flags.
///
/// # Errors
///
/// Returns [`InconclusiveMatchError`] when required properties are missing or an
/// operator cannot be evaluated locally.
#[must_use = "feature flag evaluation result should be used"]
#[allow(clippy::too_many_arguments)]
pub fn match_feature_flag(
    flag: &FeatureFlag,
    distinct_id: &str,
    person_properties: &HashMap<String, serde_json::Value>,
    groups: &HashMap<String, String>,
    group_properties: &HashMap<String, HashMap<String, serde_json::Value>>,
    group_type_mapping: &HashMap<String, String>,
) -> Result<FlagValue, InconclusiveMatchError> {
    if !flag.active {
        return Ok(FlagValue::Boolean(false));
    }

    let conditions = &flag.filters.groups;
    let flag_aggregation = flag.filters.aggregation_group_type_index;

    // Sort conditions to evaluate variant overrides first
    let mut sorted_conditions = conditions.clone();
    sorted_conditions.sort_by_key(|c| if c.variant.is_some() { 0 } else { 1 });

    let mut is_inconclusive = false;

    for condition in sorted_conditions {
        let (effective_bucketing, effective_properties) = match resolve_condition_target(
            &condition,
            flag_aggregation,
            distinct_id,
            person_properties,
            groups,
            group_properties,
            group_type_mapping,
        ) {
            ConditionTarget::Use {
                bucketing,
                properties,
            } => (bucketing, properties),
            ConditionTarget::Skip => continue,
            ConditionTarget::Inconclusive => {
                is_inconclusive = true;
                continue;
            }
        };

        match is_condition_match(flag, &effective_bucketing, &condition, effective_properties) {
            Ok(ConditionMatch::Match) => {
                if let Some(variant_override) = &condition.variant {
                    // Check if variant is valid
                    if let Some(ref multivariate) = flag.filters.multivariate {
                        let valid_variants: Vec<String> = multivariate
                            .variants
                            .iter()
                            .map(|v| v.key.clone())
                            .collect();

                        if valid_variants.contains(variant_override) {
                            return Ok(FlagValue::String(variant_override.clone()));
                        }
                    }
                }

                // Try to get matching variant or return true
                if let Some(variant) = get_matching_variant(flag, &effective_bucketing) {
                    return Ok(FlagValue::String(variant));
                }
                return Ok(FlagValue::Boolean(true));
            }
            Ok(ConditionMatch::OutOfRolloutBound) => {
                // The user's properties matched this group but the rollout
                // excluded them. With early_exit enabled the flag is
                // definitively disabled; otherwise fall through to later groups.
                // Only short-circuit when no prior group was inconclusive — an
                // inconclusive result means we can't evaluate locally and must
                // fall back to the server, so it takes priority over early_exit.
                if flag.filters.early_exit && !is_inconclusive {
                    return Ok(FlagValue::Boolean(false));
                }
            }
            Ok(ConditionMatch::NoMatch) => continue,
            Err(_) => {
                is_inconclusive = true;
            }
        }
    }

    if is_inconclusive {
        return Err(InconclusiveMatchError::new(
            "Can't determine if feature flag is enabled or not with given properties",
        ));
    }

    Ok(FlagValue::Boolean(false))
}

/// Outcome of evaluating a single condition group, mirroring the PostHog Rust
/// evaluation engine's tri-state so the local loop can distinguish a
/// property-filter miss (always fall through) from a rollout exclusion (which
/// can short-circuit when `early_exit` is enabled).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum ConditionMatch {
    /// Property filters matched (or there were none) and the rollout included
    /// the user — the flag matches.
    Match,
    /// A property filter did not match — always continue to the next group.
    NoMatch,
    /// Property filters matched (or there were none) but the rollout excluded
    /// the user.
    OutOfRolloutBound,
}

fn is_condition_match(
    flag: &FeatureFlag,
    bucketing_id: &str,
    condition: &FeatureFlagCondition,
    properties: &HashMap<String, serde_json::Value>,
) -> Result<ConditionMatch, InconclusiveMatchError> {
    // Check properties first
    for prop in &condition.properties {
        if !match_property(prop, properties)? {
            return Ok(ConditionMatch::NoMatch);
        }
    }

    // If all properties match (or no properties), check rollout percentage
    if let Some(rollout_percentage) = condition.rollout_percentage {
        let hash_value = hash_key(&flag.key, bucketing_id, ROLLOUT_HASH_SALT);
        if hash_value > (rollout_percentage / 100.0) {
            return Ok(ConditionMatch::OutOfRolloutBound);
        }
    }

    Ok(ConditionMatch::Match)
}

/// Match a feature flag with full context (cohorts, other flags).
///
/// This version supports cohort membership checks and flag dependency checks.
/// `person_properties` carries person-level property values; group-level
/// properties are looked up from `ctx.group_properties` when a condition (or
/// the flag itself) targets a group via `aggregation_group_type_index`.
///
/// # Errors
///
/// Returns [`InconclusiveMatchError`] when local evaluation cannot determine a
/// result with the provided context.
#[must_use = "feature flag evaluation result should be used"]
pub fn match_feature_flag_with_context(
    flag: &FeatureFlag,
    person_properties: &HashMap<String, serde_json::Value>,
    ctx: &EvaluationContext,
) -> Result<FlagValue, InconclusiveMatchError> {
    if !flag.active {
        return Ok(FlagValue::Boolean(false));
    }

    let conditions = &flag.filters.groups;
    let flag_aggregation = flag.filters.aggregation_group_type_index;

    // Sort conditions to evaluate variant overrides first
    let mut sorted_conditions = conditions.clone();
    sorted_conditions.sort_by_key(|c| if c.variant.is_some() { 0 } else { 1 });

    let mut is_inconclusive = false;

    for condition in sorted_conditions {
        let (effective_bucketing, effective_properties) = match resolve_condition_target(
            &condition,
            flag_aggregation,
            ctx.distinct_id,
            person_properties,
            ctx.groups,
            ctx.group_properties,
            ctx.group_type_mapping,
        ) {
            ConditionTarget::Use {
                bucketing,
                properties,
            } => (bucketing, properties),
            ConditionTarget::Skip => continue,
            ConditionTarget::Inconclusive => {
                is_inconclusive = true;
                continue;
            }
        };

        match is_condition_match_with_context(
            flag,
            &effective_bucketing,
            &condition,
            effective_properties,
            ctx,
        ) {
            Ok(ConditionMatch::Match) => {
                if let Some(variant_override) = &condition.variant {
                    // Check if variant is valid
                    if let Some(ref multivariate) = flag.filters.multivariate {
                        let valid_variants: Vec<String> = multivariate
                            .variants
                            .iter()
                            .map(|v| v.key.clone())
                            .collect();

                        if valid_variants.contains(variant_override) {
                            return Ok(FlagValue::String(variant_override.clone()));
                        }
                    }
                }

                // Try to get matching variant or return true
                if let Some(variant) = get_matching_variant(flag, &effective_bucketing) {
                    return Ok(FlagValue::String(variant));
                }
                return Ok(FlagValue::Boolean(true));
            }
            Ok(ConditionMatch::OutOfRolloutBound) => {
                // The user's properties matched this group but the rollout
                // excluded them. With early_exit enabled the flag is
                // definitively disabled; otherwise fall through to later groups.
                // Only short-circuit when no prior group was inconclusive — an
                // inconclusive result means we can't evaluate locally and must
                // fall back to the server, so it takes priority over early_exit.
                if flag.filters.early_exit && !is_inconclusive {
                    return Ok(FlagValue::Boolean(false));
                }
            }
            Ok(ConditionMatch::NoMatch) => continue,
            Err(_) => {
                is_inconclusive = true;
            }
        }
    }

    if is_inconclusive {
        return Err(InconclusiveMatchError::new(
            "Can't determine if feature flag is enabled or not with given properties",
        ));
    }

    Ok(FlagValue::Boolean(false))
}

fn is_condition_match_with_context(
    flag: &FeatureFlag,
    bucketing_id: &str,
    condition: &FeatureFlagCondition,
    properties: &HashMap<String, serde_json::Value>,
    ctx: &EvaluationContext,
) -> Result<ConditionMatch, InconclusiveMatchError> {
    // Check properties first (using context-aware matching for cohorts/flag dependencies)
    for prop in &condition.properties {
        if !match_property_with_context(prop, properties, ctx)? {
            return Ok(ConditionMatch::NoMatch);
        }
    }

    // If all properties match (or no properties), check rollout percentage
    if let Some(rollout_percentage) = condition.rollout_percentage {
        let hash_value = hash_key(&flag.key, bucketing_id, ROLLOUT_HASH_SALT);
        if hash_value > (rollout_percentage / 100.0) {
            return Ok(ConditionMatch::OutOfRolloutBound);
        }
    }

    Ok(ConditionMatch::Match)
}

/// Match a property with additional context for cohorts and flag dependencies.
///
/// Use this when evaluating local feature flag conditions that can reference
/// cohort membership (`type = "cohort"`) or another feature flag via
/// `$feature/<flag-key>`.
///
/// # Errors
///
/// Returns [`InconclusiveMatchError`] when the property, cohort, or dependent
/// flag cannot be evaluated from the supplied context.
pub fn match_property_with_context(
    property: &Property,
    properties: &HashMap<String, serde_json::Value>,
    ctx: &EvaluationContext,
) -> Result<bool, InconclusiveMatchError> {
    // Check if this is a cohort membership check
    if property.property_type.as_deref() == Some("cohort") {
        return match_cohort_property(property, properties, ctx);
    }

    // Check if this is a flag dependency check
    if property.key.starts_with("$feature/") {
        return match_flag_dependency_property(property, ctx);
    }

    // Fall back to regular property matching
    match_property(property, properties)
}

/// Evaluate cohort membership referenced by a flag property (`type = "cohort"`).
fn match_cohort_property(
    property: &Property,
    properties: &HashMap<String, serde_json::Value>,
    ctx: &EvaluationContext,
) -> Result<bool, InconclusiveMatchError> {
    let cohort_id = cohort_id_to_string(&property.value)
        .ok_or_else(|| InconclusiveMatchError::new("Cohort ID must be a string or number"))?;

    let mut active_cohorts = HashSet::new();
    let is_in_cohort = match_cohort_by_id(&cohort_id, properties, ctx, &mut active_cohorts, 0)
        .map_err(CohortMatchError::into_inconclusive)?;

    // Cohort references omit the operator in API payloads, so "exact" means membership.
    Ok(match property.operator.as_str() {
        "exact" | "in" => is_in_cohort,
        "not_in" => !is_in_cohort,
        op => {
            return Err(InconclusiveMatchError::new(&format!(
                "Unknown cohort operator: {}",
                op
            )));
        }
    })
}

/// Cohort IDs arrive as either a JSON string or a number depending on where the
/// reference lives (top-level flag property vs a nested cohort filter). Normalize
/// both to the string keys used in the cohort cache.
fn cohort_id_to_string(value: &serde_json::Value) -> Option<String> {
    match value {
        serde_json::Value::String(s) => Some(s.clone()),
        serde_json::Value::Number(n) => Some(n.to_string()),
        _ => None,
    }
}

#[derive(Debug)]
enum CohortMatchError {
    Inconclusive(InconclusiveMatchError),
    InvalidDefinition(InconclusiveMatchError),
    MissingCohort(InconclusiveMatchError),
}

impl CohortMatchError {
    fn into_inconclusive(self) -> InconclusiveMatchError {
        match self {
            Self::Inconclusive(error)
            | Self::InvalidDefinition(error)
            | Self::MissingCohort(error) => error,
        }
    }

    fn requires_server_evaluation(&self) -> bool {
        !matches!(self, Self::Inconclusive(_))
    }
}

/// How deeply local cohort evaluation will recurse through cohort references
/// and nested property groups combined.
///
/// A cycle check alone bounds repeats, not depth: a chain of distinct cohorts is
/// acyclic and still recurses once per link. Counting only cohort references is
/// also insufficient because each cohort can contain nested property groups.
/// Real cohort nesting is a handful of levels at most.
const MAX_COHORT_RESOLUTION_DEPTH: usize = 100;

/// Look up a cohort by ID and evaluate its property group against `properties`.
///
/// `active_cohorts` holds the IDs on the current resolution path so a cohort
/// that references itself, directly or through others, is rejected as a cycle.
/// `resolution_depth` bounds the combined path through cohort references and
/// nested property groups. IDs are removed on the way back out, so a cohort
/// referenced twice down sibling branches still resolves normally.
fn match_cohort_by_id(
    cohort_id: &str,
    properties: &HashMap<String, serde_json::Value>,
    ctx: &EvaluationContext,
    active_cohorts: &mut HashSet<String>,
    resolution_depth: usize,
) -> Result<bool, CohortMatchError> {
    let cohort = ctx.cohorts.get(cohort_id).ok_or_else(|| {
        CohortMatchError::MissingCohort(InconclusiveMatchError::new(&format!(
            "Cohort '{}' not found in local cache",
            cohort_id
        )))
    })?;

    if resolution_depth >= MAX_COHORT_RESOLUTION_DEPTH {
        return Err(CohortMatchError::InvalidDefinition(
            InconclusiveMatchError::new(&format!(
                "Cohort '{}' is nested deeper than the limit of {}",
                cohort_id, MAX_COHORT_RESOLUTION_DEPTH
            )),
        ));
    }

    if !active_cohorts.insert(cohort_id.to_string()) {
        return Err(CohortMatchError::InvalidDefinition(
            InconclusiveMatchError::new(&format!(
                "Cohort '{}' is part of a reference cycle",
                cohort_id
            )),
        ));
    }

    let result = match_property_group(
        &cohort.properties,
        properties,
        ctx,
        active_cohorts,
        resolution_depth,
    );
    active_cohorts.remove(cohort_id);
    result
}

/// Recursively evaluate a cohort property group against a user's properties.
///
/// The `/flags/definitions/?send_cohorts` payload nests groups as
/// `{"type": "AND"|"OR", "values": [...]}`, where each `values` entry is either
/// another group (it has its own `values`), a cohort reference
/// (`{"type": "cohort", "value": <id>, "negation": <bool>}`), or a leaf property
/// filter. This mirrors posthog-python's `match_property_group`: `AND` requires
/// every entry to match, `OR` requires any, and a bare JSON array is treated as
/// an implicit `AND` of leaf properties (as produced by
/// [`CohortDefinition::new`]).
fn match_property_group(
    group: &serde_json::Value,
    properties: &HashMap<String, serde_json::Value>,
    ctx: &EvaluationContext,
    active_cohorts: &mut HashSet<String>,
    resolution_depth: usize,
) -> Result<bool, CohortMatchError> {
    if resolution_depth >= MAX_COHORT_RESOLUTION_DEPTH {
        return Err(CohortMatchError::InvalidDefinition(
            InconclusiveMatchError::new(&format!(
                "Cohort property groups are nested deeper than the limit of {}",
                MAX_COHORT_RESOLUTION_DEPTH
            )),
        ));
    }

    if let Some(arr) = group.as_array() {
        return match_property_group_values(
            "AND",
            arr,
            properties,
            ctx,
            active_cohorts,
            resolution_depth,
        );
    }

    let Some(obj) = group.as_object() else {
        return Err(CohortMatchError::InvalidDefinition(
            InconclusiveMatchError::new("Cohort property group must be an object or array"),
        ));
    };

    // The backend serializes a valid empty PropertyGroup as an empty object.
    if obj.is_empty() {
        return Ok(true);
    }

    let group_type = obj.get("type").and_then(|t| t.as_str()).unwrap_or("AND");

    let Some(values) = obj.get("values").and_then(|v| v.as_array()) else {
        return Err(CohortMatchError::InvalidDefinition(
            InconclusiveMatchError::new("Cohort property group values must be an array"),
        ));
    };

    match_property_group_values(
        group_type,
        values,
        properties,
        ctx,
        active_cohorts,
        resolution_depth,
    )
}

/// Combine the `values` of a property group under AND/OR semantics.
///
/// An ordinary inconclusive entry (missing property, unknown operator, ...) is
/// remembered but deferred: a definitive result (`false` under AND, `true` under
/// OR) still resolves the group. Every entry is inspected so missing cohorts and
/// malformed definitions always force server-side evaluation regardless of
/// branch order.
fn match_property_group_values(
    group_type: &str,
    values: &[serde_json::Value],
    properties: &HashMap<String, serde_json::Value>,
    ctx: &EvaluationContext,
    active_cohorts: &mut HashSet<String>,
    resolution_depth: usize,
) -> Result<bool, CohortMatchError> {
    if values.is_empty() {
        return Ok(true);
    }

    let is_and = !group_type.eq_ignore_ascii_case("OR");
    let mut decisive_result = None;
    let mut inconclusive: Option<CohortMatchError> = None;

    for value in values {
        let result = if value.get("values").is_some() {
            // Nested property group.
            match_property_group(value, properties, ctx, active_cohorts, resolution_depth + 1)
        } else if value.get("type").and_then(|t| t.as_str()) == Some("cohort") {
            // A cohort filter nested inside another cohort.
            match_nested_cohort(value, properties, ctx, active_cohorts, resolution_depth + 1)
        } else {
            // Leaf property filter.
            match serde_json::from_value::<CohortProperty>(value.clone()) {
                Ok(prop) => match_property_with_context(&prop.property, properties, ctx)
                    .map(|matches| matches != prop.negation)
                    .map_err(CohortMatchError::Inconclusive),
                Err(e) => Err(CohortMatchError::InvalidDefinition(
                    InconclusiveMatchError::new(&format!("Unable to parse cohort property: {}", e)),
                )),
            }
        };

        match result {
            Ok(true) if !is_and => decisive_result = Some(true),
            Ok(false) if is_and => decisive_result = Some(false),
            Ok(_) => {}
            Err(error) if error.requires_server_evaluation() => return Err(error),
            Err(error) => inconclusive = Some(error),
        }
    }

    if let Some(result) = decisive_result {
        return Ok(result);
    }

    if let Some(error) = inconclusive {
        return Err(error);
    }

    // AND: every entry matched. OR: none matched.
    Ok(is_and)
}

/// Evaluate a cohort reference nested inside another cohort's property group,
/// honoring the optional `negation` flag.
fn match_nested_cohort(
    value: &serde_json::Value,
    properties: &HashMap<String, serde_json::Value>,
    ctx: &EvaluationContext,
    active_cohorts: &mut HashSet<String>,
    resolution_depth: usize,
) -> Result<bool, CohortMatchError> {
    let cohort_id = value
        .get("value")
        .and_then(cohort_id_to_string)
        .ok_or_else(|| {
            CohortMatchError::InvalidDefinition(InconclusiveMatchError::new(
                "Nested cohort ID must be a string or number",
            ))
        })?;

    let negation = value
        .get("negation")
        .and_then(|n| n.as_bool())
        .unwrap_or(false);

    let is_member = match_cohort_by_id(
        &cohort_id,
        properties,
        ctx,
        active_cohorts,
        resolution_depth,
    )?;
    Ok(is_member != negation)
}

/// Evaluate flag dependency
fn match_flag_dependency_property(
    property: &Property,
    ctx: &EvaluationContext,
) -> Result<bool, InconclusiveMatchError> {
    // Extract flag key from "$feature/flag-key"
    let flag_key = property
        .key
        .strip_prefix("$feature/")
        .ok_or_else(|| InconclusiveMatchError::new("Invalid flag dependency format"))?;

    let flag = ctx.flags.get(flag_key).ok_or_else(|| {
        InconclusiveMatchError::new(&format!("Flag '{}' not found in local cache", flag_key))
    })?;

    // Evaluate the dependent flag for this user (with empty properties to avoid recursion issues).
    // Group context flows through from the outer ctx so dependent group/mixed flags can resolve.
    let empty_props = HashMap::new();
    let flag_value = match_feature_flag(
        flag,
        ctx.distinct_id,
        &empty_props,
        ctx.groups,
        ctx.group_properties,
        ctx.group_type_mapping,
    )?;

    // Compare the flag value with the expected value
    let expected = &property.value;

    let matches = match (&flag_value, expected) {
        (FlagValue::Boolean(b), serde_json::Value::Bool(expected_b)) => b == expected_b,
        (FlagValue::String(s), serde_json::Value::String(expected_s)) => {
            s.eq_ignore_ascii_case(expected_s)
        }
        (FlagValue::Boolean(true), serde_json::Value::String(s)) => {
            // Flag is enabled (boolean true) but we're checking for a specific variant
            // This should not match
            s.is_empty() || s == "true"
        }
        (FlagValue::Boolean(false), serde_json::Value::String(s)) => s.is_empty() || s == "false",
        (FlagValue::String(s), serde_json::Value::Bool(true)) => {
            // Flag returns a variant string, checking for "enabled" (any variant is enabled)
            !s.is_empty()
        }
        (FlagValue::String(_), serde_json::Value::Bool(false)) => false,
        _ => false,
    };

    // Handle different operators
    Ok(match property.operator.as_str() {
        "exact" => matches,
        "is_not" => !matches,
        op => {
            return Err(InconclusiveMatchError::new(&format!(
                "Unknown flag dependency operator: {}",
                op
            )));
        }
    })
}

/// Parse a relative date string like "-7d", "-24h", "-2w", "-3m", "-1y"
/// Returns the DateTime<Utc> that the relative date represents
fn parse_relative_date(value: &str) -> Option<DateTime<Utc>> {
    let value = value.trim();
    // Need at least 3 chars: "-", digit(s), and unit (e.g., "-7d")
    if value.len() < 3 || !value.starts_with('-') {
        return None;
    }

    let (num_str, unit) = value[1..].split_at(value.len() - 2);
    let num: i64 = num_str.parse().ok()?;

    let duration = match unit {
        "h" => chrono::Duration::hours(num),
        "d" => chrono::Duration::days(num),
        "w" => chrono::Duration::weeks(num),
        "m" => chrono::Duration::days(num * 30), // Approximate month as 30 days
        "y" => chrono::Duration::days(num * 365), // Approximate year as 365 days
        _ => return None,
    };

    Some(Utc::now() - duration)
}

/// Parse a date value from a string (ISO date, ISO datetime, or relative date)
fn parse_date_value(value: &serde_json::Value) -> Option<DateTime<Utc>> {
    let date_str = value.as_str()?;

    // Try relative date first (e.g., "-7d")
    if date_str.starts_with('-') && date_str.len() > 1 {
        if let Some(dt) = parse_relative_date(date_str) {
            return Some(dt);
        }
    }

    // Try ISO datetime with timezone (e.g., "2024-06-15T10:30:00Z")
    if let Ok(dt) = DateTime::parse_from_rfc3339(date_str) {
        return Some(dt.with_timezone(&Utc));
    }

    // Try ISO date only (e.g., "2024-06-15")
    if let Ok(date) = NaiveDate::parse_from_str(date_str, "%Y-%m-%d") {
        return Some(
            date.and_hms_opt(0, 0, 0)
                .expect("midnight is always valid")
                .and_utc(),
        );
    }

    None
}

/// A parsed semantic version as (major, minor, patch)
type SemverTuple = (u64, u64, u64);

/// Parse a semantic version string into a (major, minor, patch) tuple.
///
/// Rules:
/// 1. Strip leading/trailing whitespace
/// 2. Strip `v` or `V` prefix (e.g., "v1.2.3" → "1.2.3")
/// 3. Strip pre-release and build metadata suffixes (split on `-` or `+`, take first part)
/// 4. Split on `.` and parse first 3 components as integers
/// 5. Default missing components to 0 (e.g., "1.2" → (1, 2, 0), "1" → (1, 0, 0))
/// 6. Ignore extra components beyond the third (e.g., "1.2.3.4" → (1, 2, 3))
/// 7. Return None for invalid input (empty string, non-numeric parts, leading dot,
///    or numeric components with leading zeros per semver 2.0.0 §2)
fn parse_semver(value: &str) -> Option<SemverTuple> {
    let value = value.trim();
    if value.is_empty() {
        return None;
    }

    // Strip v/V prefix
    let value = value
        .strip_prefix('v')
        .or_else(|| value.strip_prefix('V'))
        .unwrap_or(value);
    if value.is_empty() {
        return None;
    }

    // Strip pre-release/build metadata (everything after - or +)
    let value = value.split(['-', '+']).next().unwrap_or(value);
    if value.is_empty() {
        return None;
    }

    // Leading dot is invalid
    if value.starts_with('.') {
        return None;
    }

    // Split on dots and parse components
    let parts: Vec<&str> = value.split('.').collect();
    if parts.is_empty() {
        return None;
    }

    let major = parse_semver_numeric(parts.first()?)?;
    let minor = parts.get(1).map_or(Some(0), |s| parse_semver_numeric(s))?;
    let patch = parts.get(2).map_or(Some(0), |s| parse_semver_numeric(s))?;

    Some((major, minor, patch))
}

/// Parse a single semver numeric identifier.
///
/// Per semver 2.0.0 §2, numeric identifiers MUST NOT include leading zeros, so
/// "07" and "001" are rejected while the literal "0" remains valid.
fn parse_semver_numeric(part: &str) -> Option<u64> {
    if part.is_empty() || !part.bytes().all(|b| b.is_ascii_digit()) {
        return None;
    }
    if part.len() > 1 && part.starts_with('0') {
        return None;
    }
    part.parse().ok()
}

/// Parse a wildcard pattern like "1.*" or "1.2.*" and return (lower_bound, upper_bound)
/// Returns None if the pattern is invalid
fn parse_semver_wildcard(pattern: &str) -> Option<(SemverTuple, SemverTuple)> {
    let pattern = pattern.trim();
    if pattern.is_empty() {
        return None;
    }

    // Strip v/V prefix
    let pattern = pattern
        .strip_prefix('v')
        .or_else(|| pattern.strip_prefix('V'))
        .unwrap_or(pattern);
    if pattern.is_empty() {
        return None;
    }

    let parts: Vec<&str> = pattern.split('.').collect();

    match parts.as_slice() {
        // "X.*" pattern
        [major_str, "*"] => {
            let major = parse_semver_numeric(major_str)?;
            Some(((major, 0, 0), (major + 1, 0, 0)))
        }
        // "X.Y.*" pattern
        [major_str, minor_str, "*"] => {
            let major = parse_semver_numeric(major_str)?;
            let minor = parse_semver_numeric(minor_str)?;
            Some(((major, minor, 0), (major, minor + 1, 0)))
        }
        _ => None,
    }
}

/// Compute bounds for tilde range: ~X.Y.Z means >=X.Y.Z and <X.(Y+1).0
fn compute_tilde_bounds(version: SemverTuple) -> (SemverTuple, SemverTuple) {
    let (major, minor, patch) = version;
    ((major, minor, patch), (major, minor + 1, 0))
}

/// Compute bounds for caret range per semver spec:
/// - ^X.Y.Z where X > 0: >=X.Y.Z <(X+1).0.0
/// - ^0.Y.Z where Y > 0: >=0.Y.Z <0.(Y+1).0
/// - ^0.0.Z: >=0.0.Z <0.0.(Z+1)
fn compute_caret_bounds(version: SemverTuple) -> (SemverTuple, SemverTuple) {
    let (major, minor, patch) = version;
    if major > 0 {
        ((major, minor, patch), (major + 1, 0, 0))
    } else if minor > 0 {
        ((0, minor, patch), (0, minor + 1, 0))
    } else {
        ((0, 0, patch), (0, 0, patch + 1))
    }
}

fn parse_target_semver(
    target_value: &serde_json::Value,
) -> Result<SemverTuple, InconclusiveMatchError> {
    let target_str = value_to_string(target_value);
    parse_semver(&target_str).ok_or_else(|| {
        InconclusiveMatchError::new(&format!(
            "Unable to parse target semver value: {:?}",
            target_value
        ))
    })
}

fn match_property(
    property: &Property,
    properties: &HashMap<String, serde_json::Value>,
) -> Result<bool, InconclusiveMatchError> {
    let value = match properties.get(&property.key) {
        Some(v) => v,
        None => {
            return Err(InconclusiveMatchError::new(&format!(
                "Property '{}' not found in provided properties",
                property.key
            )));
        }
    };

    let parse_property_semver = || {
        let prop_str = value_to_string(value);
        parse_semver(&prop_str).ok_or_else(|| {
            InconclusiveMatchError::new(&format!(
                "Unable to parse property semver value for '{}': {:?}",
                property.key, value
            ))
        })
    };
    let parse_semver_operands = || {
        Ok((
            parse_property_semver()?,
            parse_target_semver(&property.value)?,
        ))
    };

    Ok(match property.operator.as_str() {
        "exact" => compute_exact_match(&property.value, value),
        "is_not" => !compute_exact_match(&property.value, value),
        "is_set" => true,      // We already know the property exists
        "is_not_set" => false, // We already know the property exists
        "icontains" => {
            let prop_str = value_to_string(value);
            let search_str = value_to_string(&property.value);
            prop_str
                .to_ascii_lowercase()
                .contains(&search_str.to_ascii_lowercase())
        }
        "not_icontains" => {
            let prop_str = value_to_string(value);
            let search_str = value_to_string(&property.value);
            !prop_str
                .to_ascii_lowercase()
                .contains(&search_str.to_ascii_lowercase())
        }
        "starts_with" => {
            let prop_str = value_to_string(value);
            let search_str = value_to_string(&property.value);
            prop_str
                .to_ascii_lowercase()
                .starts_with(&search_str.to_ascii_lowercase())
        }
        "not_starts_with" => {
            let prop_str = value_to_string(value);
            let search_str = value_to_string(&property.value);
            !prop_str
                .to_ascii_lowercase()
                .starts_with(&search_str.to_ascii_lowercase())
        }
        "ends_with" => {
            let prop_str = value_to_string(value);
            let search_str = value_to_string(&property.value);
            prop_str
                .to_ascii_lowercase()
                .ends_with(&search_str.to_ascii_lowercase())
        }
        "not_ends_with" => {
            let prop_str = value_to_string(value);
            let search_str = value_to_string(&property.value);
            !prop_str
                .to_ascii_lowercase()
                .ends_with(&search_str.to_ascii_lowercase())
        }
        "regex" => {
            let prop_str = value_to_string(value);
            let regex_str = value_to_string(&property.value);
            get_cached_regex(&regex_str)
                .map(|re| re.is_match(&prop_str))
                .unwrap_or(false)
        }
        "not_regex" => {
            let prop_str = value_to_string(value);
            let regex_str = value_to_string(&property.value);
            get_cached_regex(&regex_str)
                .map(|re| !re.is_match(&prop_str))
                .unwrap_or(true)
        }
        "gt" | "gte" | "lt" | "lte" => compare_numeric(&property.operator, &property.value, value),
        "is_date_before" | "is_date_after" => {
            let target_date = parse_date_value(&property.value).ok_or_else(|| {
                InconclusiveMatchError::new(&format!(
                    "Unable to parse target date value: {:?}",
                    property.value
                ))
            })?;

            let prop_date = parse_date_value(value).ok_or_else(|| {
                InconclusiveMatchError::new(&format!(
                    "Unable to parse property date value for '{}': {:?}",
                    property.key, value
                ))
            })?;

            if property.operator == "is_date_before" {
                prop_date < target_date
            } else {
                prop_date > target_date
            }
        }
        // Semver comparison operators
        "semver_eq" | "semver_neq" | "semver_gt" | "semver_gte" | "semver_lt" | "semver_lte" => {
            let (prop_version, target_version) = parse_semver_operands()?;

            match property.operator.as_str() {
                "semver_eq" => prop_version == target_version,
                "semver_neq" => prop_version != target_version,
                "semver_gt" => prop_version > target_version,
                "semver_gte" => prop_version >= target_version,
                "semver_lt" => prop_version < target_version,
                "semver_lte" => prop_version <= target_version,
                _ => unreachable!(),
            }
        }
        "semver_tilde" => {
            let (prop_version, target_version) = parse_semver_operands()?;
            let (lower, upper) = compute_tilde_bounds(target_version);
            prop_version >= lower && prop_version < upper
        }
        "semver_caret" => {
            let (prop_version, target_version) = parse_semver_operands()?;
            let (lower, upper) = compute_caret_bounds(target_version);
            prop_version >= lower && prop_version < upper
        }
        "semver_wildcard" => {
            let prop_version = parse_property_semver()?;
            let target_str = value_to_string(&property.value);

            let (lower, upper) = parse_semver_wildcard(&target_str).ok_or_else(|| {
                InconclusiveMatchError::new(&format!(
                    "Unable to parse target semver wildcard pattern: {:?}",
                    property.value
                ))
            })?;

            prop_version >= lower && prop_version < upper
        }
        unknown => {
            return Err(InconclusiveMatchError::new(&format!(
                "Unknown operator: {}",
                unknown
            )));
        }
    })
}

fn compute_exact_match(value: &serde_json::Value, override_value: &serde_json::Value) -> bool {
    if is_truthy_or_falsy_property_value(value) {
        return is_truthy_property_value(value) == is_truthy_property_value(override_value);
    }

    if let Some(values) = value.as_array() {
        return values
            .iter()
            .any(|candidate| compare_values(candidate, override_value));
    }

    compare_values(value, override_value)
}

fn is_truthy_or_falsy_property_value(value: &serde_json::Value) -> bool {
    match value {
        serde_json::Value::Bool(_) => true,
        serde_json::Value::String(value) => {
            value.eq_ignore_ascii_case("true") || value.eq_ignore_ascii_case("false")
        }
        serde_json::Value::Array(values) => values.iter().all(is_truthy_or_falsy_property_value),
        _ => false,
    }
}

fn is_truthy_property_value(value: &serde_json::Value) -> bool {
    match value {
        serde_json::Value::Bool(value) => *value,
        serde_json::Value::String(value) => value.eq_ignore_ascii_case("true"),
        serde_json::Value::Array(values) => values.iter().all(is_truthy_property_value),
        _ => false,
    }
}

fn compare_values(a: &serde_json::Value, b: &serde_json::Value) -> bool {
    value_to_string(a).to_lowercase() == value_to_string(b).to_lowercase()
}

fn value_to_string(value: &serde_json::Value) -> String {
    match value {
        serde_json::Value::String(s) => s.clone(),
        serde_json::Value::Number(n) => n.to_string(),
        serde_json::Value::Bool(b) => b.to_string(),
        _ => value.to_string(),
    }
}

fn compare_numeric(
    operator: &str,
    property_value: &serde_json::Value,
    value: &serde_json::Value,
) -> bool {
    let prop_num = match property_value {
        serde_json::Value::Number(n) => n.as_f64(),
        serde_json::Value::String(s) => s.parse::<f64>().ok(),
        _ => None,
    };

    let val_num = match value {
        serde_json::Value::Number(n) => n.as_f64(),
        serde_json::Value::String(s) => s.parse::<f64>().ok(),
        _ => None,
    };

    if let (Some(prop), Some(val)) = (prop_num, val_num) {
        match operator {
            "gt" => val > prop,
            "gte" => val >= prop,
            "lt" => val < prop,
            "lte" => val <= prop,
            _ => false,
        }
    } else {
        // Fall back to string comparison
        let prop_str = value_to_string(property_value);
        let val_str = value_to_string(value);
        match operator {
            "gt" => val_str > prop_str,
            "gte" => val_str >= prop_str,
            "lt" => val_str < prop_str,
            "lte" => val_str <= prop_str,
            _ => false,
        }
    }
}

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

    /// Test salt constant to avoid CodeQL warnings about empty cryptographic values
    const TEST_SALT: &str = "test-salt";

    #[test]
    fn test_hash_key() {
        let hash = hash_key("test-flag", "user-123", TEST_SALT);
        assert!((0.0..=1.0).contains(&hash));

        // Same inputs should produce same hash
        let hash2 = hash_key("test-flag", "user-123", TEST_SALT);
        assert_eq!(hash, hash2);

        // Different inputs should produce different hash
        let hash3 = hash_key("test-flag", "user-456", TEST_SALT);
        assert_ne!(hash, hash3);
    }

    /// Bucketing must stay bit-identical across SDKs, so pin known values.
    /// Generated with the Python SDK's algorithm:
    /// `int(hashlib.sha1(f"{key}.{distinct_id}{salt}".encode()).hexdigest()[:15], 16) / 0xfffffffffffffff`
    #[test]
    fn test_hash_key_matches_known_vectors() {
        for (key, distinct_id, salt, expected) in [
            ("test-flag", "user-123", TEST_SALT, 0.982_062_667_408_254_5),
            ("test-flag", "user-456", TEST_SALT, 0.695_145_973_300_181_1),
            (
                "beta-feature",
                "distinct_id",
                ROLLOUT_HASH_SALT,
                0.875_596_347_947_407_8,
            ),
            (
                "beta-feature",
                "distinct_id",
                VARIANT_HASH_SALT,
                0.228_302_715_824_090_7,
            ),
            (
                "multivariate-flag",
                "user_1",
                ROLLOUT_HASH_SALT,
                0.223_607_742_058_685_7,
            ),
        ] {
            assert_eq!(
                hash_key(key, distinct_id, salt),
                expected,
                "hash_key({key:?}, {distinct_id:?}, {salt:?}) drifted from the other SDKs"
            );
        }
    }

    #[test]
    fn test_simple_flag_match() {
        let flag = FeatureFlag {
            key: "test-flag".to_string(),
            active: true,
            has_experiment: None,
            filters: FeatureFlagFilters {
                groups: vec![FeatureFlagCondition {
                    properties: vec![],
                    rollout_percentage: Some(100.0),
                    variant: None,
                    aggregation_group_type_index: None,
                }],
                multivariate: None,
                payloads: HashMap::new(),
                aggregation_group_type_index: None,
                early_exit: false,
            },
        };

        let properties = HashMap::new();
        let result = match_feature_flag(
            &flag,
            "user-123",
            &properties,
            &HashMap::new(),
            &HashMap::new(),
            &HashMap::new(),
        )
        .unwrap();
        assert_eq!(result, FlagValue::Boolean(true));
    }

    #[test]
    fn test_property_matching() {
        let prop = Property {
            key: "country".to_string(),
            value: json!("US"),
            operator: "exact".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        properties.insert("country".to_string(), json!("US"));

        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("country".to_string(), json!("UK"));
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_property_case_folding_matches_flags_service() {
        let matches = |operator: &str, expected, actual| {
            let property = Property {
                key: "key".to_string(),
                value: expected,
                operator: operator.to_string(),
                property_type: None,
            };
            match_property(&property, &HashMap::from([("key".to_string(), actual)])).unwrap()
        };

        // Serde preserves a float's decimal point; exact matching must not collapse it to an integer.
        assert_eq!(value_to_string(&json!(323.0)), "323.0");

        let cases = [
            // Exact matching stringifies both sides and applies Unicode lowercase.
            ("exact", json!("PRO"), json!("pro"), true),
            ("exact", json!("Ä"), json!("ä"), true),
            ("exact", json!("ß"), json!("ss"), false),
            ("exact", json!("Σ"), json!("ς"), false),
            ("exact", json!("ΟΣ"), json!("ος"), true),
            ("exact", json!("ΟΣ"), json!("οσ"), false),
            ("exact", json!("İ"), json!("i\u{0307}"), true),
            ("exact", json!("İ"), json!("i"), false),
            ("exact", json!(323), json!("323"), true),
            ("exact", json!(["FREE", "PRÖ"]), json!("prö"), true),
            ("is_not", json!(["FREE", "PRÖ"]), json!("prö"), false),
            ("is_not", json!(["FREE", "PRÖ"]), json!("team"), true),
            ("exact", json!("323.0"), json!(323.0), true),
            ("exact", json!("323"), json!(323.0), false),
            // Substring and anchored operators fold ASCII only.
            ("icontains", json!("ADMIN"), json!("admin-user"), true),
            ("icontains", json!("Ä"), json!("äbc"), false),
            ("not_icontains", json!("Ä"), json!("äbc"), true),
            ("starts_with", json!("Ä"), json!("äbc"), false),
            ("not_starts_with", json!("Ä"), json!("äbc"), true),
            ("ends_with", json!("Ä"), json!("bcä"), false),
            ("not_ends_with", json!("Ä"), json!("bcä"), true),
        ];

        for (operator, expected, actual, should_match) in cases {
            let result = matches(operator, expected.clone(), actual.clone());
            assert_eq!(
                result, should_match,
                "operator {operator} comparing {actual} against {expected}"
            );
        }
    }

    #[test]
    fn test_exact_boolean_coercion_matches_flags_service() {
        let matches = |operator: &str, expected, actual| {
            let property = Property {
                key: "key".to_string(),
                value: expected,
                operator: operator.to_string(),
                property_type: None,
            };
            match_property(&property, &HashMap::from([("key".to_string(), actual)])).unwrap()
        };

        let cases = [
            // Boolean-like filters compare aggregate truthiness before array membership.
            (json!(false), json!("banana"), true),
            (json!("false"), json!(0), true),
            (json!(["false"]), json!(null), true),
            (json!(["true", "false"]), json!("true"), false),
            (json!(["true", "false"]), json!("pro"), true),
            // Empty arrays are boolean-like and truthy because all() on an empty iterator is true.
            (json!([]), json!(true), true),
            (json!([]), json!("true"), true),
            (json!([]), json!([]), true),
            (json!([]), json!([true]), true),
            (json!([]), json!(false), false),
            (json!([]), json!("banana"), false),
            // Non-boolean-like arrays retain ordinary ANY membership.
            (json!(["FREE", "PRO"]), json!("pro"), true),
            (json!(["FREE", "PRO"]), json!("team"), false),
        ];

        for (expected, actual, exact_match) in cases {
            assert_eq!(
                matches("exact", expected.clone(), actual.clone()),
                exact_match,
                "exact comparing {actual} against {expected}"
            );
            assert_eq!(
                matches("is_not", expected.clone(), actual.clone()),
                !exact_match,
                "is_not comparing {actual} against {expected}"
            );
        }
    }

    #[test]
    fn test_null_property_operator_defaults_to_exact() {
        let prop: Property = serde_json::from_value(json!({
            "key": "country",
            "value": "US",
            "operator": null,
            "type": "person"
        }))
        .unwrap();

        assert_eq!(prop.operator, "exact");
    }

    #[test]
    fn test_multivariate_variants() {
        let flag = FeatureFlag {
            key: "test-flag".to_string(),
            active: true,
            has_experiment: None,
            filters: FeatureFlagFilters {
                groups: vec![FeatureFlagCondition {
                    properties: vec![],
                    rollout_percentage: Some(100.0),
                    variant: None,
                    aggregation_group_type_index: None,
                }],
                multivariate: Some(MultivariateFilter {
                    variants: vec![
                        MultivariateVariant {
                            key: "control".to_string(),
                            rollout_percentage: 50.0,
                        },
                        MultivariateVariant {
                            key: "test".to_string(),
                            rollout_percentage: 50.0,
                        },
                    ],
                }),
                payloads: HashMap::new(),
                aggregation_group_type_index: None,
                early_exit: false,
            },
        };

        let properties = HashMap::new();
        let result = match_feature_flag(
            &flag,
            "user-123",
            &properties,
            &HashMap::new(),
            &HashMap::new(),
            &HashMap::new(),
        )
        .unwrap();

        match result {
            FlagValue::String(variant) => {
                assert!(variant == "control" || variant == "test");
            }
            _ => panic!("Expected string variant"),
        }
    }

    #[test]
    fn test_inactive_flag() {
        let flag = FeatureFlag {
            key: "inactive-flag".to_string(),
            active: false,
            has_experiment: None,
            filters: FeatureFlagFilters {
                groups: vec![FeatureFlagCondition {
                    properties: vec![],
                    rollout_percentage: Some(100.0),
                    variant: None,
                    aggregation_group_type_index: None,
                }],
                multivariate: None,
                payloads: HashMap::new(),
                aggregation_group_type_index: None,
                early_exit: false,
            },
        };

        let properties = HashMap::new();
        let result = match_feature_flag(
            &flag,
            "user-123",
            &properties,
            &HashMap::new(),
            &HashMap::new(),
            &HashMap::new(),
        )
        .unwrap();
        assert_eq!(result, FlagValue::Boolean(false));
    }

    #[test]
    fn test_rollout_percentage() {
        let flag = FeatureFlag {
            key: "rollout-flag".to_string(),
            active: true,
            has_experiment: None,
            filters: FeatureFlagFilters {
                groups: vec![FeatureFlagCondition {
                    properties: vec![],
                    rollout_percentage: Some(30.0), // 30% rollout
                    variant: None,
                    aggregation_group_type_index: None,
                }],
                multivariate: None,
                payloads: HashMap::new(),
                aggregation_group_type_index: None,
                early_exit: false,
            },
        };

        let properties = HashMap::new();

        // Test with multiple users to ensure distribution
        let mut enabled_count = 0;
        for i in 0..1000 {
            let result = match_feature_flag(
                &flag,
                &format!("user-{}", i),
                &properties,
                &HashMap::new(),
                &HashMap::new(),
                &HashMap::new(),
            )
            .unwrap();
            if result == FlagValue::Boolean(true) {
                enabled_count += 1;
            }
        }

        // Should be roughly 30% enabled (allow for some variance)
        assert!(enabled_count > 250 && enabled_count < 350);
    }

    #[test]
    fn test_regex_operator() {
        let prop = Property {
            key: "email".to_string(),
            value: json!(".*@company\\.com$"),
            operator: "regex".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        properties.insert("email".to_string(), json!("user@company.com"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("email".to_string(), json!("user@example.com"));
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_icontains_operator() {
        let prop = Property {
            key: "name".to_string(),
            value: json!("ADMIN"),
            operator: "icontains".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        properties.insert("name".to_string(), json!("admin_user"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("name".to_string(), json!("regular_user"));
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_starts_with_operator() {
        let prop = Property {
            key: "name".to_string(),
            value: json!("Val"),
            operator: "starts_with".to_string(),
            property_type: None,
        };

        // Case-insensitive match anchored to the start.
        let mut properties = HashMap::new();
        properties.insert("name".to_string(), json!("value"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("name".to_string(), json!("VALUE"));
        assert!(match_property(&prop, &properties).unwrap());

        // Substring present but not at the start.
        properties.insert("name".to_string(), json!("prevalue"));
        assert!(!match_property(&prop, &properties).unwrap());

        properties.insert("name".to_string(), json!("Alakazam"));
        assert!(!match_property(&prop, &properties).unwrap());

        // Numeric property values are stringified before matching.
        let numeric_prop = Property {
            key: "name".to_string(),
            value: json!("3"),
            operator: "starts_with".to_string(),
            property_type: None,
        };

        properties.insert("name".to_string(), json!(323));
        assert!(match_property(&numeric_prop, &properties).unwrap());

        properties.insert("name".to_string(), json!(123));
        assert!(!match_property(&numeric_prop, &properties).unwrap());

        let negated_prop = Property {
            key: "name".to_string(),
            value: json!("Val"),
            operator: "not_starts_with".to_string(),
            property_type: None,
        };

        properties.insert("name".to_string(), json!("value"));
        assert!(!match_property(&negated_prop, &properties).unwrap());

        properties.insert("name".to_string(), json!("prevalue"));
        assert!(match_property(&negated_prop, &properties).unwrap());

        // Missing property is inconclusive.
        assert!(match_property(&prop, &HashMap::new()).is_err());
    }

    #[test]
    fn test_ends_with_operator() {
        let prop = Property {
            key: "name".to_string(),
            value: json!("lUe"),
            operator: "ends_with".to_string(),
            property_type: None,
        };

        // Case-insensitive match anchored to the end.
        let mut properties = HashMap::new();
        properties.insert("name".to_string(), json!("value"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("name".to_string(), json!("VALUE"));
        assert!(match_property(&prop, &properties).unwrap());

        // Substring present but not at the end.
        properties.insert("name".to_string(), json!("value2"));
        assert!(!match_property(&prop, &properties).unwrap());

        properties.insert("name".to_string(), json!("Alakazam"));
        assert!(!match_property(&prop, &properties).unwrap());

        // Numeric property values are stringified before matching.
        let numeric_prop = Property {
            key: "name".to_string(),
            value: json!("3"),
            operator: "ends_with".to_string(),
            property_type: None,
        };

        properties.insert("name".to_string(), json!(323));
        assert!(match_property(&numeric_prop, &properties).unwrap());

        properties.insert("name".to_string(), json!(321));
        assert!(!match_property(&numeric_prop, &properties).unwrap());

        let negated_prop = Property {
            key: "name".to_string(),
            value: json!("lUe"),
            operator: "not_ends_with".to_string(),
            property_type: None,
        };

        properties.insert("name".to_string(), json!("value"));
        assert!(!match_property(&negated_prop, &properties).unwrap());

        properties.insert("name".to_string(), json!("value2"));
        assert!(match_property(&negated_prop, &properties).unwrap());

        // Missing property is inconclusive.
        assert!(match_property(&prop, &HashMap::new()).is_err());
    }

    #[test]
    fn test_numeric_operators() {
        // Greater than
        let prop_gt = Property {
            key: "age".to_string(),
            value: json!(18),
            operator: "gt".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        properties.insert("age".to_string(), json!(25));
        assert!(match_property(&prop_gt, &properties).unwrap());

        properties.insert("age".to_string(), json!(15));
        assert!(!match_property(&prop_gt, &properties).unwrap());

        // Less than or equal
        let prop_lte = Property {
            key: "score".to_string(),
            value: json!(100),
            operator: "lte".to_string(),
            property_type: None,
        };

        properties.insert("score".to_string(), json!(100));
        assert!(match_property(&prop_lte, &properties).unwrap());

        properties.insert("score".to_string(), json!(101));
        assert!(!match_property(&prop_lte, &properties).unwrap());
    }

    #[test]
    fn test_is_set_operator() {
        let prop = Property {
            key: "email".to_string(),
            value: json!(true),
            operator: "is_set".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        for value in [
            json!(null),
            json!(false),
            json!(0),
            json!(""),
            json!([]),
            json!({}),
        ] {
            properties.insert("email".to_string(), value);
            assert!(match_property(&prop, &properties).unwrap());
        }

        properties.remove("email");
        assert!(matches!(
            match_property(&prop, &properties),
            Err(InconclusiveMatchError { .. })
        ));
    }

    #[test]
    fn test_is_not_set_operator() {
        let prop = Property {
            key: "phone".to_string(),
            value: json!(true),
            operator: "is_not_set".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        for value in [
            json!(null),
            json!(false),
            json!(0),
            json!(""),
            json!([]),
            json!({}),
        ] {
            properties.insert("phone".to_string(), value);
            assert!(!match_property(&prop, &properties).unwrap());
        }

        properties.remove("phone");
        assert!(matches!(
            match_property(&prop, &properties),
            Err(InconclusiveMatchError { .. })
        ));
    }

    #[test]
    fn test_empty_groups() {
        let flag = FeatureFlag {
            key: "empty-groups".to_string(),
            active: true,
            has_experiment: None,
            filters: FeatureFlagFilters {
                groups: vec![],
                multivariate: None,
                payloads: HashMap::new(),
                aggregation_group_type_index: None,
                early_exit: false,
            },
        };

        let properties = HashMap::new();
        let result = match_feature_flag(
            &flag,
            "user-123",
            &properties,
            &HashMap::new(),
            &HashMap::new(),
            &HashMap::new(),
        )
        .unwrap();
        assert_eq!(result, FlagValue::Boolean(false));
    }

    #[test]
    fn test_hash_scale_constant() {
        // Verify the constant is exactly 15 F's (not 16)
        assert_eq!(LONG_SCALE, 0xFFFFFFFFFFFFFFFu64 as f64);
        assert_ne!(LONG_SCALE, 0xFFFFFFFFFFFFFFFFu64 as f64);
    }

    // ==================== Tests for missing operators ====================

    #[test]
    fn test_unknown_operator_returns_inconclusive_error() {
        let prop = Property {
            key: "status".to_string(),
            value: json!("active"),
            operator: "unknown_operator".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        properties.insert("status".to_string(), json!("active"));

        let result = match_property(&prop, &properties);
        assert!(result.is_err());
        let err = result.unwrap_err();
        assert!(err.message.contains("unknown_operator"));
    }

    #[test]
    fn test_is_date_before_with_relative_date() {
        let prop = Property {
            key: "signup_date".to_string(),
            value: json!("-7d"), // 7 days ago
            operator: "is_date_before".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        // Date 10 days ago should be before -7d
        let ten_days_ago = chrono::Utc::now() - chrono::Duration::days(10);
        properties.insert(
            "signup_date".to_string(),
            json!(ten_days_ago.format("%Y-%m-%d").to_string()),
        );
        assert!(match_property(&prop, &properties).unwrap());

        // Date 3 days ago should NOT be before -7d
        let three_days_ago = chrono::Utc::now() - chrono::Duration::days(3);
        properties.insert(
            "signup_date".to_string(),
            json!(three_days_ago.format("%Y-%m-%d").to_string()),
        );
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_is_date_after_with_relative_date() {
        let prop = Property {
            key: "last_seen".to_string(),
            value: json!("-30d"), // 30 days ago
            operator: "is_date_after".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        // Date 10 days ago should be after -30d
        let ten_days_ago = chrono::Utc::now() - chrono::Duration::days(10);
        properties.insert(
            "last_seen".to_string(),
            json!(ten_days_ago.format("%Y-%m-%d").to_string()),
        );
        assert!(match_property(&prop, &properties).unwrap());

        // Date 60 days ago should NOT be after -30d
        let sixty_days_ago = chrono::Utc::now() - chrono::Duration::days(60);
        properties.insert(
            "last_seen".to_string(),
            json!(sixty_days_ago.format("%Y-%m-%d").to_string()),
        );
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_is_date_before_with_iso_date() {
        let prop = Property {
            key: "expiry_date".to_string(),
            value: json!("2024-06-15"),
            operator: "is_date_before".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        properties.insert("expiry_date".to_string(), json!("2024-06-10"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("expiry_date".to_string(), json!("2024-06-20"));
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_is_date_after_with_iso_date() {
        let prop = Property {
            key: "start_date".to_string(),
            value: json!("2024-01-01"),
            operator: "is_date_after".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        properties.insert("start_date".to_string(), json!("2024-03-15"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("start_date".to_string(), json!("2023-12-01"));
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_is_date_with_relative_hours() {
        let prop = Property {
            key: "last_active".to_string(),
            value: json!("-24h"), // 24 hours ago
            operator: "is_date_after".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        // 12 hours ago should be after -24h
        let twelve_hours_ago = chrono::Utc::now() - chrono::Duration::hours(12);
        properties.insert(
            "last_active".to_string(),
            json!(twelve_hours_ago.to_rfc3339()),
        );
        assert!(match_property(&prop, &properties).unwrap());

        // 48 hours ago should NOT be after -24h
        let forty_eight_hours_ago = chrono::Utc::now() - chrono::Duration::hours(48);
        properties.insert(
            "last_active".to_string(),
            json!(forty_eight_hours_ago.to_rfc3339()),
        );
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_is_date_with_relative_weeks() {
        let prop = Property {
            key: "joined".to_string(),
            value: json!("-2w"), // 2 weeks ago
            operator: "is_date_before".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        // 3 weeks ago should be before -2w
        let three_weeks_ago = chrono::Utc::now() - chrono::Duration::weeks(3);
        properties.insert(
            "joined".to_string(),
            json!(three_weeks_ago.format("%Y-%m-%d").to_string()),
        );
        assert!(match_property(&prop, &properties).unwrap());

        // 1 week ago should NOT be before -2w
        let one_week_ago = chrono::Utc::now() - chrono::Duration::weeks(1);
        properties.insert(
            "joined".to_string(),
            json!(one_week_ago.format("%Y-%m-%d").to_string()),
        );
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_is_date_with_relative_months() {
        let prop = Property {
            key: "subscription_date".to_string(),
            value: json!("-3m"), // 3 months ago
            operator: "is_date_after".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        // 1 month ago should be after -3m
        let one_month_ago = chrono::Utc::now() - chrono::Duration::days(30);
        properties.insert(
            "subscription_date".to_string(),
            json!(one_month_ago.format("%Y-%m-%d").to_string()),
        );
        assert!(match_property(&prop, &properties).unwrap());

        // 6 months ago should NOT be after -3m
        let six_months_ago = chrono::Utc::now() - chrono::Duration::days(180);
        properties.insert(
            "subscription_date".to_string(),
            json!(six_months_ago.format("%Y-%m-%d").to_string()),
        );
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_is_date_with_relative_years() {
        let prop = Property {
            key: "created_at".to_string(),
            value: json!("-1y"), // 1 year ago
            operator: "is_date_before".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        // 2 years ago should be before -1y
        let two_years_ago = chrono::Utc::now() - chrono::Duration::days(730);
        properties.insert(
            "created_at".to_string(),
            json!(two_years_ago.format("%Y-%m-%d").to_string()),
        );
        assert!(match_property(&prop, &properties).unwrap());

        // 6 months ago should NOT be before -1y
        let six_months_ago = chrono::Utc::now() - chrono::Duration::days(180);
        properties.insert(
            "created_at".to_string(),
            json!(six_months_ago.format("%Y-%m-%d").to_string()),
        );
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_is_date_with_invalid_date_format() {
        let prop = Property {
            key: "date".to_string(),
            value: json!("-7d"),
            operator: "is_date_before".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        properties.insert("date".to_string(), json!("not-a-date"));

        // Invalid date formats should return inconclusive
        let result = match_property(&prop, &properties);
        assert!(result.is_err());
    }

    #[test]
    fn test_is_date_with_iso_datetime() {
        let prop = Property {
            key: "event_time".to_string(),
            value: json!("2024-06-15T10:30:00Z"),
            operator: "is_date_before".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        properties.insert("event_time".to_string(), json!("2024-06-15T08:00:00Z"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("event_time".to_string(), json!("2024-06-15T12:00:00Z"));
        assert!(!match_property(&prop, &properties).unwrap());
    }

    // ==================== Tests for cohort membership ====================

    #[test]
    fn test_cohort_membership_in() {
        // Create a cohort that matches users with country = US
        let mut cohorts = HashMap::new();
        cohorts.insert(
            "cohort_1".to_string(),
            CohortDefinition::new(
                "cohort_1".to_string(),
                vec![Property {
                    key: "country".to_string(),
                    value: json!("US"),
                    operator: "exact".to_string(),
                    property_type: None,
                }],
            ),
        );

        // Property filter checking cohort membership
        let prop = Property {
            key: "$cohort".to_string(),
            value: json!("cohort_1"),
            operator: "in".to_string(),
            property_type: Some("cohort".to_string()),
        };

        // User with country = US should be in the cohort
        let mut properties = HashMap::new();
        properties.insert("country".to_string(), json!("US"));

        let ctx = EvaluationContext {
            cohorts: &cohorts,
            flags: &HashMap::new(),
            distinct_id: "user-123",
            groups: &HashMap::new(),
            group_properties: &HashMap::new(),
            group_type_mapping: &HashMap::new(),
        };
        assert!(match_property_with_context(&prop, &properties, &ctx).unwrap());

        // User with country = UK should NOT be in the cohort
        properties.insert("country".to_string(), json!("UK"));
        assert!(!match_property_with_context(&prop, &properties, &ctx).unwrap());
    }

    #[test]
    fn test_cohort_membership_not_in() {
        let mut cohorts = HashMap::new();
        cohorts.insert(
            "cohort_blocked".to_string(),
            CohortDefinition::new(
                "cohort_blocked".to_string(),
                vec![Property {
                    key: "status".to_string(),
                    value: json!("blocked"),
                    operator: "exact".to_string(),
                    property_type: None,
                }],
            ),
        );

        let prop = Property {
            key: "$cohort".to_string(),
            value: json!("cohort_blocked"),
            operator: "not_in".to_string(),
            property_type: Some("cohort".to_string()),
        };

        let mut properties = HashMap::new();
        properties.insert("status".to_string(), json!("active"));

        let ctx = EvaluationContext {
            cohorts: &cohorts,
            flags: &HashMap::new(),
            distinct_id: "user-123",
            groups: &HashMap::new(),
            group_properties: &HashMap::new(),
            group_type_mapping: &HashMap::new(),
        };
        // User with status = active should NOT be in the blocked cohort (so not_in returns true)
        assert!(match_property_with_context(&prop, &properties, &ctx).unwrap());

        // User with status = blocked IS in the cohort (so not_in returns false)
        properties.insert("status".to_string(), json!("blocked"));
        assert!(!match_property_with_context(&prop, &properties, &ctx).unwrap());
    }

    #[test]
    fn test_cohort_not_found_returns_inconclusive() {
        let cohorts = HashMap::new(); // No cohorts defined

        let prop = Property {
            key: "$cohort".to_string(),
            value: json!("nonexistent_cohort"),
            operator: "in".to_string(),
            property_type: Some("cohort".to_string()),
        };

        let properties = HashMap::new();
        let ctx = EvaluationContext {
            cohorts: &cohorts,
            flags: &HashMap::new(),
            distinct_id: "user-123",
            groups: &HashMap::new(),
            group_properties: &HashMap::new(),
            group_type_mapping: &HashMap::new(),
        };

        let result = match_property_with_context(&prop, &properties, &ctx);
        assert!(result.is_err());
        assert!(result.unwrap_err().message.contains("Cohort"));
    }

    /// Build an `EvaluationContext` over just a cohort map (no flags/groups),
    /// which is all cohort-membership tests need.
    fn cohort_ctx(cohorts: &HashMap<String, CohortDefinition>) -> EvaluationContext<'_> {
        EvaluationContext {
            cohorts,
            flags: EMPTY_FLAGS.get_or_init(HashMap::new),
            distinct_id: "user-123",
            groups: EMPTY_GROUPS.get_or_init(HashMap::new),
            group_properties: EMPTY_GROUP_PROPS.get_or_init(HashMap::new),
            group_type_mapping: EMPTY_GROUP_MAPPING.get_or_init(HashMap::new),
        }
    }

    static EMPTY_FLAGS: OnceLock<HashMap<String, FeatureFlag>> = OnceLock::new();
    static EMPTY_GROUPS: OnceLock<HashMap<String, String>> = OnceLock::new();
    static EMPTY_GROUP_PROPS: OnceLock<HashMap<String, HashMap<String, serde_json::Value>>> =
        OnceLock::new();
    static EMPTY_GROUP_MAPPING: OnceLock<HashMap<String, String>> = OnceLock::new();

    /// A cohort whose properties are an `OR` group must match when *either*
    /// branch matches — the old flatten-and-AND logic broke this entirely.
    #[test]
    fn test_cohort_or_group() {
        let mut cohorts = HashMap::new();
        cohorts.insert(
            "cohort_or".to_string(),
            CohortDefinition {
                id: "cohort_or".to_string(),
                properties: json!({
                    "type": "OR",
                    "values": [
                        {"key": "country", "value": "US", "operator": "exact", "type": "person"},
                        {"key": "country", "value": "CA", "operator": "exact", "type": "person"},
                    ],
                }),
            },
        );

        let prop = Property {
            key: "$cohort".to_string(),
            value: json!("cohort_or"),
            operator: "in".to_string(),
            property_type: Some("cohort".to_string()),
        };

        let ctx = cohort_ctx(&cohorts);

        // Either branch of the OR is enough.
        let mut properties = HashMap::new();
        properties.insert("country".to_string(), json!("US"));
        assert!(match_property_with_context(&prop, &properties, &ctx).unwrap());

        properties.insert("country".to_string(), json!("CA"));
        assert!(match_property_with_context(&prop, &properties, &ctx).unwrap());

        // Neither branch matches.
        properties.insert("country".to_string(), json!("UK"));
        assert!(!match_property_with_context(&prop, &properties, &ctx).unwrap());
    }

    /// A nested group inside an `AND` must be evaluated as a whole group, not
    /// collapsed to its first property (the old `.next()` bug).
    #[test]
    fn test_cohort_nested_and_of_or() {
        let mut cohorts = HashMap::new();
        cohorts.insert(
            "cohort_nested".to_string(),
            CohortDefinition {
                id: "cohort_nested".to_string(),
                properties: json!({
                    "type": "AND",
                    "values": [
                        {"key": "plan", "value": "paid", "operator": "exact", "type": "person"},
                        {
                            "type": "OR",
                            "values": [
                                {"key": "country", "value": "US", "operator": "exact", "type": "person"},
                                {"key": "country", "value": "CA", "operator": "exact", "type": "person"},
                            ],
                        },
                    ],
                }),
            },
        );

        let prop = Property {
            key: "$cohort".to_string(),
            value: json!("cohort_nested"),
            operator: "in".to_string(),
            property_type: Some("cohort".to_string()),
        };

        let ctx = cohort_ctx(&cohorts);

        // paid + (US or CA) → in cohort.
        let mut properties = HashMap::new();
        properties.insert("plan".to_string(), json!("paid"));
        properties.insert("country".to_string(), json!("CA"));
        assert!(match_property_with_context(&prop, &properties, &ctx).unwrap());

        // paid but country outside the OR → not in cohort. Under the old
        // first-property-only logic the OR group was dropped and this matched.
        properties.insert("country".to_string(), json!("UK"));
        assert!(!match_property_with_context(&prop, &properties, &ctx).unwrap());

        // Wrong plan → the leading AND term fails.
        properties.insert("plan".to_string(), json!("free"));
        properties.insert("country".to_string(), json!("US"));
        assert!(!match_property_with_context(&prop, &properties, &ctx).unwrap());
    }

    /// A cohort referenced from inside another cohort's group is resolved
    /// recursively, honoring the `negation` flag.
    #[test]
    fn test_cohort_nested_cohort_reference() {
        let mut cohorts = HashMap::new();
        cohorts.insert(
            "child".to_string(),
            CohortDefinition {
                id: "child".to_string(),
                properties: json!({
                    "type": "AND",
                    "values": [
                        {"key": "country", "value": "US", "operator": "exact", "type": "person"},
                    ],
                }),
            },
        );
        cohorts.insert(
            "parent".to_string(),
            CohortDefinition {
                id: "parent".to_string(),
                properties: json!({
                    "type": "AND",
                    "values": [
                        {"type": "cohort", "value": "child", "negation": false},
                    ],
                }),
            },
        );

        let prop = Property {
            key: "$cohort".to_string(),
            value: json!("parent"),
            operator: "in".to_string(),
            property_type: Some("cohort".to_string()),
        };

        let ctx = cohort_ctx(&cohorts);

        let mut properties = HashMap::new();
        properties.insert("country".to_string(), json!("US"));
        assert!(match_property_with_context(&prop, &properties, &ctx).unwrap());

        properties.insert("country".to_string(), json!("UK"));
        assert!(!match_property_with_context(&prop, &properties, &ctx).unwrap());
    }

    /// A cohort cycle must surface as inconclusive so the flag falls back to
    /// server-side evaluation. Recursing until the stack runs out aborts the
    /// process, which takes the caller's whole server down.
    #[test]
    fn test_cyclic_cohort_reference_is_inconclusive() {
        let mut cohorts = HashMap::new();
        cohorts.insert(
            "a".to_string(),
            CohortDefinition {
                id: "a".to_string(),
                properties: json!({
                    "type": "AND",
                    "values": [{"type": "cohort", "value": "b", "negation": false}],
                }),
            },
        );
        cohorts.insert(
            "b".to_string(),
            CohortDefinition {
                id: "b".to_string(),
                properties: json!({
                    "type": "AND",
                    "values": [{"type": "cohort", "value": "a", "negation": false}],
                }),
            },
        );

        let prop = Property {
            key: "$cohort".to_string(),
            value: json!("a"),
            operator: "in".to_string(),
            property_type: Some("cohort".to_string()),
        };
        let ctx = cohort_ctx(&cohorts);

        let error = match_property_with_context(&prop, &HashMap::new(), &ctx)
            .expect_err("a cohort cycle must not resolve locally");
        assert!(
            error.to_string().contains("cycle"),
            "error should name the cycle, got: {}",
            error
        );
    }

    /// A cycle guard alone only bounds repeats, not depth. A chain of distinct
    /// cohorts is acyclic, so it never trips the cycle check and recurses once
    /// per link. Each cohort is its own shallow map entry, so the manifest also
    /// clears serde_json's nesting limit on the way in.
    #[test]
    fn test_deep_acyclic_cohort_chain_is_inconclusive() {
        let chain_len = MAX_COHORT_RESOLUTION_DEPTH + 50;
        let mut cohorts = HashMap::new();
        for link in 0..chain_len {
            let properties = if link == chain_len - 1 {
                json!({
                    "type": "AND",
                    "values": [
                        {"key": "country", "value": "US", "operator": "exact", "type": "person"},
                    ],
                })
            } else {
                json!({
                    "type": "AND",
                    "values": [{"type": "cohort", "value": (link + 1).to_string()}],
                })
            };
            cohorts.insert(
                link.to_string(),
                CohortDefinition {
                    id: link.to_string(),
                    properties,
                },
            );
        }

        let prop = Property {
            key: "$cohort".to_string(),
            value: json!("0"),
            operator: "in".to_string(),
            property_type: Some("cohort".to_string()),
        };
        let ctx = cohort_ctx(&cohorts);
        let mut properties = HashMap::new();
        properties.insert("country".to_string(), json!("US"));

        assert!(
            match_property_with_context(&prop, &properties, &ctx).is_err(),
            "a cohort chain deeper than the limit must not resolve locally"
        );
    }

    /// The depth bound has to leave realistic nesting alone.
    #[test]
    fn test_cohort_chain_within_the_depth_limit_still_resolves() {
        let chain_len = 10;
        let mut cohorts = HashMap::new();
        for link in 0..chain_len {
            let properties = if link == chain_len - 1 {
                json!({
                    "type": "AND",
                    "values": [
                        {"key": "country", "value": "US", "operator": "exact", "type": "person"},
                    ],
                })
            } else {
                json!({
                    "type": "AND",
                    "values": [{"type": "cohort", "value": (link + 1).to_string()}],
                })
            };
            cohorts.insert(
                link.to_string(),
                CohortDefinition {
                    id: link.to_string(),
                    properties,
                },
            );
        }

        let prop = Property {
            key: "$cohort".to_string(),
            value: json!("0"),
            operator: "in".to_string(),
            property_type: Some("cohort".to_string()),
        };
        let ctx = cohort_ctx(&cohorts);
        let mut properties = HashMap::new();
        properties.insert("country".to_string(), json!("US"));

        assert!(match_property_with_context(&prop, &properties, &ctx).unwrap());
    }

    #[test]
    fn test_self_referencing_cohort_is_inconclusive() {
        let mut cohorts = HashMap::new();
        cohorts.insert(
            "loop".to_string(),
            CohortDefinition {
                id: "loop".to_string(),
                properties: json!({
                    "type": "AND",
                    "values": [{"type": "cohort", "value": "loop", "negation": false}],
                }),
            },
        );

        let prop = Property {
            key: "$cohort".to_string(),
            value: json!("loop"),
            operator: "in".to_string(),
            property_type: Some("cohort".to_string()),
        };
        let ctx = cohort_ctx(&cohorts);

        assert!(match_property_with_context(&prop, &HashMap::new(), &ctx).is_err());
    }

    /// Referencing the same cohort twice down different branches is a diamond,
    /// not a cycle. Tracking visited IDs for the whole evaluation instead of the
    /// active path would wrongly reject this.
    #[test]
    fn test_repeated_cohort_reference_is_not_a_cycle() {
        let mut cohorts = HashMap::new();
        cohorts.insert(
            "shared".to_string(),
            CohortDefinition {
                id: "shared".to_string(),
                properties: json!({
                    "type": "AND",
                    "values": [
                        {"key": "country", "value": "US", "operator": "exact", "type": "person"},
                    ],
                }),
            },
        );
        for branch in ["left", "right"] {
            cohorts.insert(
                branch.to_string(),
                CohortDefinition {
                    id: branch.to_string(),
                    properties: json!({
                        "type": "AND",
                        "values": [{"type": "cohort", "value": "shared", "negation": false}],
                    }),
                },
            );
        }
        cohorts.insert(
            "parent".to_string(),
            CohortDefinition {
                id: "parent".to_string(),
                properties: json!({
                    "type": "AND",
                    "values": [
                        {"type": "cohort", "value": "left", "negation": false},
                        {"type": "cohort", "value": "right", "negation": false},
                    ],
                }),
            },
        );

        let prop = Property {
            key: "$cohort".to_string(),
            value: json!("parent"),
            operator: "in".to_string(),
            property_type: Some("cohort".to_string()),
        };
        let ctx = cohort_ctx(&cohorts);

        let mut properties = HashMap::new();
        properties.insert("country".to_string(), json!("US"));
        assert!(match_property_with_context(&prop, &properties, &ctx).unwrap());

        properties.insert("country".to_string(), json!("UK"));
        assert!(!match_property_with_context(&prop, &properties, &ctx).unwrap());
    }

    #[test]
    fn test_cohort_leaf_negation() {
        let mut cohorts = HashMap::new();
        cohorts.insert(
            "negated_leaf".to_string(),
            CohortDefinition {
                id: "negated_leaf".to_string(),
                properties: json!({
                    "type": "AND",
                    "values": [
                        {
                            "key": "country",
                            "value": "US",
                            "operator": "exact",
                            "type": "person",
                            "negation": true
                        },
                    ],
                }),
            },
        );

        let prop = Property {
            key: "$cohort".to_string(),
            value: json!("negated_leaf"),
            operator: "in".to_string(),
            property_type: Some("cohort".to_string()),
        };
        let ctx = cohort_ctx(&cohorts);
        let mut properties = HashMap::new();

        properties.insert("country".to_string(), json!("US"));
        assert!(!match_property_with_context(&prop, &properties, &ctx).unwrap());

        properties.insert("country".to_string(), json!("UK"));
        assert!(match_property_with_context(&prop, &properties, &ctx).unwrap());
    }

    #[test]
    fn test_missing_nested_cohort_is_not_suppressed() {
        let missing_cohort = json!({"type": "cohort", "value": "missing"});
        let country_leaf = json!({
            "key": "country",
            "value": "US",
            "operator": "exact",
            "type": "person"
        });
        let mut cohorts = HashMap::new();
        cohorts.insert(
            "or_parent".to_string(),
            CohortDefinition {
                id: "or_parent".to_string(),
                properties: json!({
                    "type": "OR",
                    "values": [country_leaf.clone(), missing_cohort.clone()],
                }),
            },
        );
        cohorts.insert(
            "and_parent".to_string(),
            CohortDefinition {
                id: "and_parent".to_string(),
                properties: json!({
                    "type": "AND",
                    "values": [country_leaf, missing_cohort],
                }),
            },
        );

        let ctx = cohort_ctx(&cohorts);
        for (cohort_id, country) in [("or_parent", "US"), ("and_parent", "UK")] {
            let prop = Property {
                key: "$cohort".to_string(),
                value: json!(cohort_id),
                operator: "in".to_string(),
                property_type: Some("cohort".to_string()),
            };
            let properties = HashMap::from([("country".to_string(), json!(country))]);

            assert!(match_property_with_context(&prop, &properties, &ctx).is_err());
        }
    }

    #[test]
    fn test_malformed_cohort_groups_are_inconclusive() {
        let mut cohorts = HashMap::new();
        cohorts.insert(
            "scalar".to_string(),
            CohortDefinition {
                id: "scalar".to_string(),
                properties: json!("invalid"),
            },
        );
        cohorts.insert(
            "object_values".to_string(),
            CohortDefinition {
                id: "object_values".to_string(),
                properties: json!({"type": "AND", "values": {}}),
            },
        );
        cohorts.insert(
            "missing_values".to_string(),
            CohortDefinition {
                id: "missing_values".to_string(),
                properties: json!({"type": "AND"}),
            },
        );
        cohorts.insert(
            "empty_object".to_string(),
            CohortDefinition {
                id: "empty_object".to_string(),
                properties: json!({}),
            },
        );
        cohorts.insert(
            "empty_values".to_string(),
            CohortDefinition {
                id: "empty_values".to_string(),
                properties: json!({"type": "AND", "values": []}),
            },
        );

        let ctx = cohort_ctx(&cohorts);
        let properties = HashMap::new();
        for cohort_id in ["scalar", "object_values", "missing_values"] {
            let prop = Property {
                key: "$cohort".to_string(),
                value: json!(cohort_id),
                operator: "in".to_string(),
                property_type: Some("cohort".to_string()),
            };

            assert!(match_property_with_context(&prop, &properties, &ctx).is_err());
        }

        for cohort_id in ["empty_object", "empty_values"] {
            let empty = Property {
                key: "$cohort".to_string(),
                value: json!(cohort_id),
                operator: "in".to_string(),
                property_type: Some("cohort".to_string()),
            };
            assert!(match_property_with_context(&empty, &properties, &ctx).unwrap());
        }
    }

    // ==================== Tests for flag dependencies ====================

    #[test]
    fn test_flag_dependency_enabled() {
        let mut flags = HashMap::new();
        flags.insert(
            "prerequisite-flag".to_string(),
            FeatureFlag {
                key: "prerequisite-flag".to_string(),
                active: true,
                has_experiment: None,
                filters: FeatureFlagFilters {
                    groups: vec![FeatureFlagCondition {
                        properties: vec![],
                        rollout_percentage: Some(100.0),
                        variant: None,
                        aggregation_group_type_index: None,
                    }],
                    multivariate: None,
                    payloads: HashMap::new(),
                    aggregation_group_type_index: None,
                    early_exit: false,
                },
            },
        );

        // Property checking if prerequisite-flag is enabled
        let prop = Property {
            key: "$feature/prerequisite-flag".to_string(),
            value: json!(true),
            operator: "exact".to_string(),
            property_type: None,
        };

        let properties = HashMap::new();
        let ctx = EvaluationContext {
            cohorts: &HashMap::new(),
            flags: &flags,
            distinct_id: "user-123",
            groups: &HashMap::new(),
            group_properties: &HashMap::new(),
            group_type_mapping: &HashMap::new(),
        };

        // The prerequisite flag is enabled for user-123, so this should match
        assert!(match_property_with_context(&prop, &properties, &ctx).unwrap());
    }

    #[test]
    fn test_flag_dependency_disabled() {
        let mut flags = HashMap::new();
        flags.insert(
            "disabled-flag".to_string(),
            FeatureFlag {
                key: "disabled-flag".to_string(),
                active: false, // Flag is inactive
                has_experiment: None,
                filters: FeatureFlagFilters {
                    groups: vec![],
                    multivariate: None,
                    payloads: HashMap::new(),
                    aggregation_group_type_index: None,
                    early_exit: false,
                },
            },
        );

        // Property checking if disabled-flag is enabled
        let prop = Property {
            key: "$feature/disabled-flag".to_string(),
            value: json!(true),
            operator: "exact".to_string(),
            property_type: None,
        };

        let properties = HashMap::new();
        let ctx = EvaluationContext {
            cohorts: &HashMap::new(),
            flags: &flags,
            distinct_id: "user-123",
            groups: &HashMap::new(),
            group_properties: &HashMap::new(),
            group_type_mapping: &HashMap::new(),
        };

        // The flag is disabled, so checking for true should fail
        assert!(!match_property_with_context(&prop, &properties, &ctx).unwrap());
    }

    #[test]
    fn test_flag_dependency_variant_match() {
        let mut flags = HashMap::new();
        flags.insert(
            "ab-test-flag".to_string(),
            FeatureFlag {
                key: "ab-test-flag".to_string(),
                active: true,
                has_experiment: None,
                filters: FeatureFlagFilters {
                    groups: vec![FeatureFlagCondition {
                        properties: vec![],
                        rollout_percentage: Some(100.0),
                        variant: None,
                        aggregation_group_type_index: None,
                    }],
                    multivariate: Some(MultivariateFilter {
                        variants: vec![
                            MultivariateVariant {
                                key: "control".to_string(),
                                rollout_percentage: 50.0,
                            },
                            MultivariateVariant {
                                key: "test".to_string(),
                                rollout_percentage: 50.0,
                            },
                        ],
                    }),
                    payloads: HashMap::new(),
                    aggregation_group_type_index: None,
                    early_exit: false,
                },
            },
        );

        // Check if user is in "control" variant
        let prop = Property {
            key: "$feature/ab-test-flag".to_string(),
            value: json!("control"),
            operator: "exact".to_string(),
            property_type: None,
        };

        let properties = HashMap::new();
        let ctx = EvaluationContext {
            cohorts: &HashMap::new(),
            flags: &flags,
            distinct_id: "user-gets-control", // This distinct_id should deterministically get "control"
            groups: &HashMap::new(),
            group_properties: &HashMap::new(),
            group_type_mapping: &HashMap::new(),
        };

        // The result depends on the hash - we just check it doesn't error
        let result = match_property_with_context(&prop, &properties, &ctx);
        assert!(result.is_ok());
    }

    #[test]
    fn test_flag_dependency_not_found_returns_inconclusive() {
        let flags = HashMap::new(); // No flags defined

        let prop = Property {
            key: "$feature/nonexistent-flag".to_string(),
            value: json!(true),
            operator: "exact".to_string(),
            property_type: None,
        };

        let properties = HashMap::new();
        let ctx = EvaluationContext {
            cohorts: &HashMap::new(),
            flags: &flags,
            distinct_id: "user-123",
            groups: &HashMap::new(),
            group_properties: &HashMap::new(),
            group_type_mapping: &HashMap::new(),
        };

        let result = match_property_with_context(&prop, &properties, &ctx);
        assert!(result.is_err());
        assert!(result.unwrap_err().message.contains("Flag"));
    }

    // ==================== Date parsing edge case tests ====================

    #[test]
    fn test_parse_relative_date_edge_cases() {
        // These test the internal parse_relative_date function indirectly via match_property
        let prop = Property {
            key: "date".to_string(),
            value: json!("placeholder"),
            operator: "is_date_before".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        properties.insert("date".to_string(), json!("2024-01-01"));

        // Empty string as target date should fail
        let empty_prop = Property {
            value: json!(""),
            ..prop.clone()
        };
        assert!(match_property(&empty_prop, &properties).is_err());

        // Single dash should fail
        let dash_prop = Property {
            value: json!("-"),
            ..prop.clone()
        };
        assert!(match_property(&dash_prop, &properties).is_err());

        // Missing unit (just "-7") should fail
        let no_unit_prop = Property {
            value: json!("-7"),
            ..prop.clone()
        };
        assert!(match_property(&no_unit_prop, &properties).is_err());

        // Missing number (just "-d") should fail
        let no_number_prop = Property {
            value: json!("-d"),
            ..prop.clone()
        };
        assert!(match_property(&no_number_prop, &properties).is_err());

        // Invalid unit should fail
        let invalid_unit_prop = Property {
            value: json!("-7x"),
            ..prop.clone()
        };
        assert!(match_property(&invalid_unit_prop, &properties).is_err());
    }

    #[test]
    fn test_parse_relative_date_large_values() {
        // Very large relative dates should work
        let prop = Property {
            key: "created_at".to_string(),
            value: json!("-1000d"), // ~2.7 years ago
            operator: "is_date_before".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        // Date 5 years ago should be before -1000d
        let five_years_ago = chrono::Utc::now() - chrono::Duration::days(1825);
        properties.insert(
            "created_at".to_string(),
            json!(five_years_ago.format("%Y-%m-%d").to_string()),
        );
        assert!(match_property(&prop, &properties).unwrap());
    }

    // ==================== Tests for invalid regex patterns ====================

    #[test]
    fn test_regex_with_invalid_pattern_returns_false() {
        // Invalid regex pattern (unclosed group)
        let prop = Property {
            key: "email".to_string(),
            value: json!("(unclosed"),
            operator: "regex".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        properties.insert("email".to_string(), json!("test@example.com"));

        // Invalid regex should return false (not match)
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_not_regex_with_invalid_pattern_returns_true() {
        // Invalid regex pattern (unclosed group)
        let prop = Property {
            key: "email".to_string(),
            value: json!("(unclosed"),
            operator: "not_regex".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        properties.insert("email".to_string(), json!("test@example.com"));

        // Invalid regex with not_regex should return true (no match means "not matching")
        assert!(match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_regex_with_various_invalid_patterns() {
        let invalid_patterns = vec![
            "(unclosed", // Unclosed group
            "[unclosed", // Unclosed bracket
            "*invalid",  // Invalid quantifier at start
            "(?P<bad",   // Unclosed named group
            r"\",        // Trailing backslash
        ];

        for pattern in invalid_patterns {
            let prop = Property {
                key: "value".to_string(),
                value: json!(pattern),
                operator: "regex".to_string(),
                property_type: None,
            };

            let mut properties = HashMap::new();
            properties.insert("value".to_string(), json!("test"));

            // All invalid patterns should return false for regex
            assert!(
                !match_property(&prop, &properties).unwrap(),
                "Invalid pattern '{}' should return false for regex",
                pattern
            );

            // And true for not_regex
            let not_regex_prop = Property {
                operator: "not_regex".to_string(),
                ..prop
            };
            assert!(
                match_property(&not_regex_prop, &properties).unwrap(),
                "Invalid pattern '{}' should return true for not_regex",
                pattern
            );
        }
    }

    // ==================== Semver parsing tests ====================

    #[test]
    fn test_parse_semver_basic() {
        assert_eq!(parse_semver("1.2.3"), Some((1, 2, 3)));
        assert_eq!(parse_semver("0.0.0"), Some((0, 0, 0)));
        assert_eq!(parse_semver("10.20.30"), Some((10, 20, 30)));
    }

    #[test]
    fn test_parse_semver_v_prefix() {
        assert_eq!(parse_semver("v1.2.3"), Some((1, 2, 3)));
        assert_eq!(parse_semver("V1.2.3"), Some((1, 2, 3)));
    }

    #[test]
    fn test_parse_semver_whitespace() {
        assert_eq!(parse_semver("  1.2.3  "), Some((1, 2, 3)));
        assert_eq!(parse_semver(" v1.2.3 "), Some((1, 2, 3)));
    }

    #[test]
    fn test_parse_semver_prerelease_stripped() {
        assert_eq!(parse_semver("1.2.3-alpha"), Some((1, 2, 3)));
        assert_eq!(parse_semver("1.2.3-beta.1"), Some((1, 2, 3)));
        assert_eq!(parse_semver("1.2.3-rc.1+build.123"), Some((1, 2, 3)));
        assert_eq!(parse_semver("1.2.3+build.456"), Some((1, 2, 3)));
    }

    #[test]
    fn test_parse_semver_partial_versions() {
        assert_eq!(parse_semver("1.2"), Some((1, 2, 0)));
        assert_eq!(parse_semver("1"), Some((1, 0, 0)));
        assert_eq!(parse_semver("v1.2"), Some((1, 2, 0)));
    }

    #[test]
    fn test_parse_semver_extra_components_ignored() {
        assert_eq!(parse_semver("1.2.3.4"), Some((1, 2, 3)));
        assert_eq!(parse_semver("1.2.3.4.5.6"), Some((1, 2, 3)));
    }

    #[test]
    fn test_parse_semver_leading_zeros_rejected() {
        // Per semver 2.0.0 §2, numeric identifiers must not include leading zeros.
        assert_eq!(parse_semver("01.02.03"), None);
        assert_eq!(parse_semver("001.002.003"), None);
        assert_eq!(parse_semver("1.07.3"), None);
        assert_eq!(parse_semver("1.2.03"), None);
        assert_eq!(parse_semver("v01.2.3"), None);

        // Literal "0" components remain valid.
        assert_eq!(parse_semver("0.1.0"), Some((0, 1, 0)));
        assert_eq!(parse_semver("1.0.0"), Some((1, 0, 0)));
        assert_eq!(parse_semver("0.0.0"), Some((0, 0, 0)));
    }

    #[test]
    fn test_parse_semver_invalid() {
        assert_eq!(parse_semver(""), None);
        assert_eq!(parse_semver("   "), None);
        assert_eq!(parse_semver("v"), None);
        assert_eq!(parse_semver(".1.2.3"), None);
        assert_eq!(parse_semver("abc"), None);
        assert_eq!(parse_semver("1.abc.3"), None);
        assert_eq!(parse_semver("1.2.abc"), None);
        assert_eq!(parse_semver("not-a-version"), None);
    }

    // ==================== Semver eq/neq tests ====================

    #[test]
    fn test_semver_eq_basic() {
        let prop = Property {
            key: "version".to_string(),
            value: json!("1.2.3"),
            operator: "semver_eq".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();

        properties.insert("version".to_string(), json!("1.2.3"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("1.2.4"));
        assert!(!match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("1.3.3"));
        assert!(!match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("2.2.3"));
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_semver_eq_with_v_prefix() {
        let prop = Property {
            key: "version".to_string(),
            value: json!("1.2.3"),
            operator: "semver_eq".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();

        // v-prefix on property value
        properties.insert("version".to_string(), json!("v1.2.3"));
        assert!(match_property(&prop, &properties).unwrap());

        // v-prefix on target value
        let prop_with_v = Property {
            value: json!("v1.2.3"),
            ..prop.clone()
        };
        properties.insert("version".to_string(), json!("1.2.3"));
        assert!(match_property(&prop_with_v, &properties).unwrap());
    }

    #[test]
    fn test_semver_eq_prerelease_stripped() {
        let prop = Property {
            key: "version".to_string(),
            value: json!("1.2.3"),
            operator: "semver_eq".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();

        properties.insert("version".to_string(), json!("1.2.3-alpha"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("1.2.3-beta.1"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("1.2.3+build.456"));
        assert!(match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_semver_eq_partial_versions() {
        let prop = Property {
            key: "version".to_string(),
            value: json!("1.2.0"),
            operator: "semver_eq".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();

        // "1.2" should equal "1.2.0"
        properties.insert("version".to_string(), json!("1.2"));
        assert!(match_property(&prop, &properties).unwrap());

        // Target as partial version
        let partial_prop = Property {
            value: json!("1.2"),
            ..prop.clone()
        };
        properties.insert("version".to_string(), json!("1.2.0"));
        assert!(match_property(&partial_prop, &properties).unwrap());
    }

    #[test]
    fn test_semver_neq() {
        let prop = Property {
            key: "version".to_string(),
            value: json!("1.2.3"),
            operator: "semver_neq".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();

        properties.insert("version".to_string(), json!("1.2.3"));
        assert!(!match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("1.2.4"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("2.0.0"));
        assert!(match_property(&prop, &properties).unwrap());
    }

    // ==================== Semver gt/gte/lt/lte tests ====================

    #[test]
    fn test_semver_gt() {
        let prop = Property {
            key: "version".to_string(),
            value: json!("1.2.3"),
            operator: "semver_gt".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();

        // Greater versions
        properties.insert("version".to_string(), json!("1.2.4"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("1.3.0"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("2.0.0"));
        assert!(match_property(&prop, &properties).unwrap());

        // Equal version
        properties.insert("version".to_string(), json!("1.2.3"));
        assert!(!match_property(&prop, &properties).unwrap());

        // Lesser versions
        properties.insert("version".to_string(), json!("1.2.2"));
        assert!(!match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("1.1.9"));
        assert!(!match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("0.9.9"));
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_semver_gte() {
        let prop = Property {
            key: "version".to_string(),
            value: json!("1.2.3"),
            operator: "semver_gte".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();

        // Greater versions
        properties.insert("version".to_string(), json!("1.2.4"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("2.0.0"));
        assert!(match_property(&prop, &properties).unwrap());

        // Equal version
        properties.insert("version".to_string(), json!("1.2.3"));
        assert!(match_property(&prop, &properties).unwrap());

        // Lesser versions
        properties.insert("version".to_string(), json!("1.2.2"));
        assert!(!match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("0.9.9"));
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_semver_lt() {
        let prop = Property {
            key: "version".to_string(),
            value: json!("1.2.3"),
            operator: "semver_lt".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();

        // Lesser versions
        properties.insert("version".to_string(), json!("1.2.2"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("1.1.9"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("0.9.9"));
        assert!(match_property(&prop, &properties).unwrap());

        // Equal version
        properties.insert("version".to_string(), json!("1.2.3"));
        assert!(!match_property(&prop, &properties).unwrap());

        // Greater versions
        properties.insert("version".to_string(), json!("1.2.4"));
        assert!(!match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("2.0.0"));
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_semver_lte() {
        let prop = Property {
            key: "version".to_string(),
            value: json!("1.2.3"),
            operator: "semver_lte".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();

        // Lesser versions
        properties.insert("version".to_string(), json!("1.2.2"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("0.9.9"));
        assert!(match_property(&prop, &properties).unwrap());

        // Equal version
        properties.insert("version".to_string(), json!("1.2.3"));
        assert!(match_property(&prop, &properties).unwrap());

        // Greater versions
        properties.insert("version".to_string(), json!("1.2.4"));
        assert!(!match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("2.0.0"));
        assert!(!match_property(&prop, &properties).unwrap());
    }

    // ==================== Semver tilde tests ====================

    #[test]
    fn test_semver_tilde_basic() {
        // ~1.2.3 means >=1.2.3 <1.3.0
        let prop = Property {
            key: "version".to_string(),
            value: json!("1.2.3"),
            operator: "semver_tilde".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();

        // Exact match
        properties.insert("version".to_string(), json!("1.2.3"));
        assert!(match_property(&prop, &properties).unwrap());

        // Within range
        properties.insert("version".to_string(), json!("1.2.4"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("1.2.99"));
        assert!(match_property(&prop, &properties).unwrap());

        // At upper bound (excluded)
        properties.insert("version".to_string(), json!("1.3.0"));
        assert!(!match_property(&prop, &properties).unwrap());

        // Above upper bound
        properties.insert("version".to_string(), json!("1.3.1"));
        assert!(!match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("2.0.0"));
        assert!(!match_property(&prop, &properties).unwrap());

        // Below lower bound
        properties.insert("version".to_string(), json!("1.2.2"));
        assert!(!match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("1.1.9"));
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_semver_tilde_zero_versions() {
        // ~0.2.3 means >=0.2.3 <0.3.0
        let prop = Property {
            key: "version".to_string(),
            value: json!("0.2.3"),
            operator: "semver_tilde".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();

        properties.insert("version".to_string(), json!("0.2.3"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("0.2.9"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("0.3.0"));
        assert!(!match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("0.2.2"));
        assert!(!match_property(&prop, &properties).unwrap());
    }

    // ==================== Semver caret tests ====================

    #[test]
    fn test_semver_caret_major_nonzero() {
        // ^1.2.3 means >=1.2.3 <2.0.0
        let prop = Property {
            key: "version".to_string(),
            value: json!("1.2.3"),
            operator: "semver_caret".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();

        // Exact match
        properties.insert("version".to_string(), json!("1.2.3"));
        assert!(match_property(&prop, &properties).unwrap());

        // Within range
        properties.insert("version".to_string(), json!("1.2.4"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("1.3.0"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("1.99.99"));
        assert!(match_property(&prop, &properties).unwrap());

        // At upper bound (excluded)
        properties.insert("version".to_string(), json!("2.0.0"));
        assert!(!match_property(&prop, &properties).unwrap());

        // Above upper bound
        properties.insert("version".to_string(), json!("2.0.1"));
        assert!(!match_property(&prop, &properties).unwrap());

        // Below lower bound
        properties.insert("version".to_string(), json!("1.2.2"));
        assert!(!match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("0.9.9"));
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_semver_caret_major_zero_minor_nonzero() {
        // ^0.2.3 means >=0.2.3 <0.3.0
        let prop = Property {
            key: "version".to_string(),
            value: json!("0.2.3"),
            operator: "semver_caret".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();

        // Exact match
        properties.insert("version".to_string(), json!("0.2.3"));
        assert!(match_property(&prop, &properties).unwrap());

        // Within range
        properties.insert("version".to_string(), json!("0.2.4"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("0.2.99"));
        assert!(match_property(&prop, &properties).unwrap());

        // At upper bound (excluded)
        properties.insert("version".to_string(), json!("0.3.0"));
        assert!(!match_property(&prop, &properties).unwrap());

        // Above upper bound
        properties.insert("version".to_string(), json!("0.3.1"));
        assert!(!match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("1.0.0"));
        assert!(!match_property(&prop, &properties).unwrap());

        // Below lower bound
        properties.insert("version".to_string(), json!("0.2.2"));
        assert!(!match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("0.1.9"));
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_semver_caret_major_zero_minor_zero() {
        // ^0.0.3 means >=0.0.3 <0.0.4
        let prop = Property {
            key: "version".to_string(),
            value: json!("0.0.3"),
            operator: "semver_caret".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();

        // Exact match
        properties.insert("version".to_string(), json!("0.0.3"));
        assert!(match_property(&prop, &properties).unwrap());

        // At upper bound (excluded)
        properties.insert("version".to_string(), json!("0.0.4"));
        assert!(!match_property(&prop, &properties).unwrap());

        // Above upper bound
        properties.insert("version".to_string(), json!("0.0.5"));
        assert!(!match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("0.1.0"));
        assert!(!match_property(&prop, &properties).unwrap());

        // Below lower bound
        properties.insert("version".to_string(), json!("0.0.2"));
        assert!(!match_property(&prop, &properties).unwrap());
    }

    // ==================== Semver wildcard tests ====================

    #[test]
    fn test_semver_wildcard_major() {
        // 1.* means >=1.0.0 <2.0.0
        let prop = Property {
            key: "version".to_string(),
            value: json!("1.*"),
            operator: "semver_wildcard".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();

        // At lower bound
        properties.insert("version".to_string(), json!("1.0.0"));
        assert!(match_property(&prop, &properties).unwrap());

        // Within range
        properties.insert("version".to_string(), json!("1.2.3"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("1.99.99"));
        assert!(match_property(&prop, &properties).unwrap());

        // At upper bound (excluded)
        properties.insert("version".to_string(), json!("2.0.0"));
        assert!(!match_property(&prop, &properties).unwrap());

        // Above upper bound
        properties.insert("version".to_string(), json!("2.0.1"));
        assert!(!match_property(&prop, &properties).unwrap());

        // Below lower bound
        properties.insert("version".to_string(), json!("0.9.9"));
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_semver_wildcard_minor() {
        // 1.2.* means >=1.2.0 <1.3.0
        let prop = Property {
            key: "version".to_string(),
            value: json!("1.2.*"),
            operator: "semver_wildcard".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();

        // At lower bound
        properties.insert("version".to_string(), json!("1.2.0"));
        assert!(match_property(&prop, &properties).unwrap());

        // Within range
        properties.insert("version".to_string(), json!("1.2.3"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("1.2.99"));
        assert!(match_property(&prop, &properties).unwrap());

        // At upper bound (excluded)
        properties.insert("version".to_string(), json!("1.3.0"));
        assert!(!match_property(&prop, &properties).unwrap());

        // Above upper bound
        properties.insert("version".to_string(), json!("1.3.1"));
        assert!(!match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("2.0.0"));
        assert!(!match_property(&prop, &properties).unwrap());

        // Below lower bound
        properties.insert("version".to_string(), json!("1.1.9"));
        assert!(!match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_semver_wildcard_zero() {
        // 0.* means >=0.0.0 <1.0.0
        let prop = Property {
            key: "version".to_string(),
            value: json!("0.*"),
            operator: "semver_wildcard".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();

        properties.insert("version".to_string(), json!("0.0.0"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("0.99.99"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("1.0.0"));
        assert!(!match_property(&prop, &properties).unwrap());
    }

    // ==================== Semver error handling tests ====================

    #[test]
    fn test_semver_invalid_property_value() {
        let prop = Property {
            key: "version".to_string(),
            value: json!("1.2.3"),
            operator: "semver_eq".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();

        // Invalid semver strings
        properties.insert("version".to_string(), json!("not-a-version"));
        assert!(match_property(&prop, &properties).is_err());

        properties.insert("version".to_string(), json!(""));
        assert!(match_property(&prop, &properties).is_err());

        properties.insert("version".to_string(), json!(".1.2.3"));
        assert!(match_property(&prop, &properties).is_err());

        properties.insert("version".to_string(), json!("abc.def.ghi"));
        assert!(match_property(&prop, &properties).is_err());
    }

    #[test]
    fn test_semver_invalid_target_value() {
        let mut properties = HashMap::new();
        properties.insert("version".to_string(), json!("1.2.3"));

        // Invalid target semver
        let prop = Property {
            key: "version".to_string(),
            value: json!("not-valid"),
            operator: "semver_eq".to_string(),
            property_type: None,
        };
        assert!(match_property(&prop, &properties).is_err());

        let prop = Property {
            key: "version".to_string(),
            value: json!(""),
            operator: "semver_gt".to_string(),
            property_type: None,
        };
        assert!(match_property(&prop, &properties).is_err());
    }

    #[test]
    fn test_semver_invalid_wildcard_pattern() {
        let mut properties = HashMap::new();
        properties.insert("version".to_string(), json!("1.2.3"));

        // Invalid wildcard patterns
        let invalid_patterns = vec![
            "*",       // Just wildcard
            "*.2.3",   // Wildcard in wrong position
            "1.*.3",   // Wildcard in wrong position
            "1.2.3.*", // Too many parts
            "abc.*",   // Non-numeric major
        ];

        for pattern in invalid_patterns {
            let prop = Property {
                key: "version".to_string(),
                value: json!(pattern),
                operator: "semver_wildcard".to_string(),
                property_type: None,
            };
            assert!(
                match_property(&prop, &properties).is_err(),
                "Pattern '{}' should be invalid",
                pattern
            );
        }
    }

    #[test]
    fn test_semver_missing_property() {
        let prop = Property {
            key: "version".to_string(),
            value: json!("1.2.3"),
            operator: "semver_eq".to_string(),
            property_type: None,
        };

        let properties = HashMap::new(); // Empty properties
        assert!(match_property(&prop, &properties).is_err());
    }

    #[test]
    fn test_semver_null_property_value() {
        let prop = Property {
            key: "version".to_string(),
            value: json!("1.2.3"),
            operator: "semver_eq".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        properties.insert("version".to_string(), json!(null));

        // null converts to "null" string which is not a valid semver
        assert!(match_property(&prop, &properties).is_err());
    }

    #[test]
    fn test_semver_numeric_property_value() {
        // When property value is a number, it gets converted to string
        let prop = Property {
            key: "version".to_string(),
            value: json!("1.0.0"),
            operator: "semver_eq".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        // Number 1 becomes "1" which parses as (1, 0, 0)
        properties.insert("version".to_string(), json!(1));
        assert!(match_property(&prop, &properties).unwrap());
    }

    // ==================== Semver edge cases ====================

    #[test]
    fn test_semver_four_part_versions() {
        let prop = Property {
            key: "version".to_string(),
            value: json!("1.2.3.4"),
            operator: "semver_eq".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();

        // 1.2.3.4 should equal 1.2.3 (extra parts ignored)
        properties.insert("version".to_string(), json!("1.2.3"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("1.2.3.4"));
        assert!(match_property(&prop, &properties).unwrap());

        properties.insert("version".to_string(), json!("1.2.3.999"));
        assert!(match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_semver_large_version_numbers() {
        let prop = Property {
            key: "version".to_string(),
            value: json!("1000.2000.3000"),
            operator: "semver_eq".to_string(),
            property_type: None,
        };

        let mut properties = HashMap::new();
        properties.insert("version".to_string(), json!("1000.2000.3000"));
        assert!(match_property(&prop, &properties).unwrap());
    }

    #[test]
    fn test_semver_comparison_ordering() {
        // Test that version ordering is correct across major/minor/patch
        let cases = vec![
            ("0.0.1", "0.0.2", "semver_lt", true),
            ("0.1.0", "0.0.99", "semver_gt", true),
            ("1.0.0", "0.99.99", "semver_gt", true),
            ("1.0.0", "1.0.0", "semver_eq", true),
            ("2.0.0", "10.0.0", "semver_lt", true), // Numeric, not string comparison
            ("9.0.0", "10.0.0", "semver_lt", true), // Numeric, not string comparison
            ("1.9.0", "1.10.0", "semver_lt", true), // Numeric, not string comparison
            ("1.2.9", "1.2.10", "semver_lt", true), // Numeric, not string comparison
        ];

        for (prop_val, target_val, op, expected) in cases {
            let prop = Property {
                key: "version".to_string(),
                value: json!(target_val),
                operator: op.to_string(),
                property_type: None,
            };

            let mut properties = HashMap::new();
            properties.insert("version".to_string(), json!(prop_val));

            assert_eq!(
                match_property(&prop, &properties).unwrap(),
                expected,
                "{} {} {} should be {}",
                prop_val,
                op,
                target_val,
                expected
            );
        }
    }

    #[test]
    fn test_match_property_semver_rejects_leading_zeros() {
        // Per semver 2.0.0 §2, numeric identifiers must not include leading zeros.
        // Both property (override) values and target (flag) values should fail to
        // parse, surfacing InconclusiveMatchError so the condition does not match.

        let bad_versions = ["1.07.3", "01.02.03", "1.2.03", "v01.2.3", "001.0.0"];

        // Override values are rejected across semver_eq.
        for bad in bad_versions {
            let prop = Property {
                key: "version".to_string(),
                value: json!("1.2.3"),
                operator: "semver_eq".to_string(),
                property_type: None,
            };
            let mut properties = HashMap::new();
            properties.insert("version".to_string(), json!(bad));
            assert!(
                match_property(&prop, &properties).is_err(),
                "override '{}' should be rejected",
                bad
            );
        }

        // Literal "0" components still work for semver_eq.
        for good in ["0.1.0", "1.0.0", "0.0.0"] {
            let prop = Property {
                key: "version".to_string(),
                value: json!(good),
                operator: "semver_eq".to_string(),
                property_type: None,
            };
            let mut properties = HashMap::new();
            properties.insert("version".to_string(), json!(good));
            assert!(
                match_property(&prop, &properties).unwrap(),
                "'{}' should parse and match itself",
                good
            );
        }

        // Flag (target) values are rejected across the remaining operators.
        let mut properties = HashMap::new();
        properties.insert("version".to_string(), json!("1.2.3"));

        for op in ["semver_gt", "semver_caret", "semver_tilde"] {
            for bad in bad_versions {
                let prop = Property {
                    key: "version".to_string(),
                    value: json!(bad),
                    operator: op.to_string(),
                    property_type: None,
                };
                assert!(
                    match_property(&prop, &properties).is_err(),
                    "target '{}' for {} should be rejected",
                    bad,
                    op
                );
            }
        }

        // Wildcard patterns with leading-zero numeric components are rejected.
        for bad_pattern in ["01.*", "1.07.*", "v01.2.*"] {
            let prop = Property {
                key: "version".to_string(),
                value: json!(bad_pattern),
                operator: "semver_wildcard".to_string(),
                property_type: None,
            };
            assert!(
                match_property(&prop, &properties).is_err(),
                "wildcard target '{}' should be rejected",
                bad_pattern
            );
        }
    }

    // ==================== Tests for early_exit ====================

    /// Build a two-group flag where the first group always lands
    /// out-of-rollout-bound (no property filters, 0% rollout) and the second
    /// group always matches (no property filters, 100% rollout). Without
    /// `early_exit`, evaluation falls through to the matching second group.
    fn early_exit_flag(early_exit: bool) -> FeatureFlag {
        FeatureFlag {
            key: "early-exit-flag".to_string(),
            active: true,
            has_experiment: None,
            filters: FeatureFlagFilters {
                groups: vec![
                    // Group 1: matches on properties (none) but rollout excludes
                    // everyone -> OUT_OF_ROLLOUT_BOUND.
                    FeatureFlagCondition {
                        properties: vec![],
                        rollout_percentage: Some(0.0),
                        variant: None,
                        aggregation_group_type_index: None,
                    },
                    // Group 2: would match everyone -> MATCH.
                    FeatureFlagCondition {
                        properties: vec![],
                        rollout_percentage: Some(100.0),
                        variant: None,
                        aggregation_group_type_index: None,
                    },
                ],
                multivariate: None,
                payloads: HashMap::new(),
                aggregation_group_type_index: None,
                early_exit,
            },
        }
    }

    macro_rules! test_early_exit {
        ($name:ident, $early_exit:expr, $expected:expr) => {
            #[test]
            fn $name() {
                let flag = early_exit_flag($early_exit);
                let result = match_feature_flag(
                    &flag,
                    "user-123",
                    &HashMap::new(),
                    &HashMap::new(),
                    &HashMap::new(),
                    &HashMap::new(),
                )
                .unwrap();
                assert_eq!(result, $expected);
            }
        };
    }

    test_early_exit!(
        test_early_exit_enabled_returns_false_without_evaluating_later_group,
        true,
        FlagValue::Boolean(false)
    );
    test_early_exit!(
        test_early_exit_unset_falls_through_to_matching_group,
        false,
        FlagValue::Boolean(true)
    );

    #[test]
    fn test_early_exit_default_is_false_from_json() {
        // A flag definition that omits `early_exit` must deserialize to false
        // and preserve the legacy fall-through behavior.
        let flag: FeatureFlag = serde_json::from_value(json!({
            "key": "early-exit-flag",
            "active": true,
            "filters": {
                "groups": [
                    { "properties": [], "rollout_percentage": 0.0, "variant": null },
                    { "properties": [], "rollout_percentage": 100.0, "variant": null }
                ]
            }
        }))
        .unwrap();
        assert!(!flag.filters.early_exit);
        let result = match_feature_flag(
            &flag,
            "user-123",
            &HashMap::new(),
            &HashMap::new(),
            &HashMap::new(),
            &HashMap::new(),
        )
        .unwrap();
        assert_eq!(result, FlagValue::Boolean(true));
    }

    #[test]
    fn test_early_exit_explicit_false_falls_through() {
        let flag: FeatureFlag = serde_json::from_value(json!({
            "key": "early-exit-flag",
            "active": true,
            "filters": {
                "early_exit": false,
                "groups": [
                    { "properties": [], "rollout_percentage": 0.0, "variant": null },
                    { "properties": [], "rollout_percentage": 100.0, "variant": null }
                ]
            }
        }))
        .unwrap();
        assert!(!flag.filters.early_exit);
        let result = match_feature_flag(
            &flag,
            "user-123",
            &HashMap::new(),
            &HashMap::new(),
            &HashMap::new(),
            &HashMap::new(),
        )
        .unwrap();
        assert_eq!(result, FlagValue::Boolean(true));
    }

    #[test]
    fn test_early_exit_property_mismatch_does_not_short_circuit() {
        // First group fails on a property filter (NO_MATCH), not rollout, so
        // even with early_exit enabled we must fall through to the matching
        // second group.
        let flag = FeatureFlag {
            key: "early-exit-flag".to_string(),
            active: true,
            has_experiment: None,
            filters: FeatureFlagFilters {
                groups: vec![
                    FeatureFlagCondition {
                        properties: vec![Property {
                            key: "country".to_string(),
                            value: json!("US"),
                            operator: "exact".to_string(),
                            property_type: None,
                        }],
                        rollout_percentage: Some(100.0),
                        variant: None,
                        aggregation_group_type_index: None,
                    },
                    FeatureFlagCondition {
                        properties: vec![],
                        rollout_percentage: Some(100.0),
                        variant: None,
                        aggregation_group_type_index: None,
                    },
                ],
                multivariate: None,
                payloads: HashMap::new(),
                aggregation_group_type_index: None,
                early_exit: true,
            },
        };

        let mut properties = HashMap::new();
        properties.insert("country".to_string(), json!("UK")); // does not match "US"

        let result = match_feature_flag(
            &flag,
            "user-123",
            &properties,
            &HashMap::new(),
            &HashMap::new(),
            &HashMap::new(),
        )
        .unwrap();
        // Property mismatch must not trigger early-exit; second group matches.
        assert_eq!(result, FlagValue::Boolean(true));
    }

    macro_rules! test_early_exit_with_context {
        ($name:ident, $early_exit:expr, $expected:expr) => {
            #[test]
            fn $name() {
                let flag = early_exit_flag($early_exit);
                let ctx = EvaluationContext {
                    cohorts: &HashMap::new(),
                    flags: &HashMap::new(),
                    distinct_id: "user-123",
                    groups: &HashMap::new(),
                    group_properties: &HashMap::new(),
                    group_type_mapping: &HashMap::new(),
                };
                let result = match_feature_flag_with_context(&flag, &HashMap::new(), &ctx).unwrap();
                assert_eq!(result, $expected);
            }
        };
    }

    test_early_exit_with_context!(
        test_early_exit_enabled_short_circuits_with_context,
        true,
        FlagValue::Boolean(false)
    );
    test_early_exit_with_context!(
        test_early_exit_unset_falls_through_with_context,
        false,
        FlagValue::Boolean(true)
    );

    #[test]
    fn test_early_exit_does_not_short_circuit_when_prior_group_inconclusive() {
        // Group 1: group-targeted (aggregation_group_type_index = 0). The
        // group_type_mapping resolves "0" → "company" and groups supplies the
        // company key, but group_properties has no entry for "company" →
        // ConditionTarget::Inconclusive → is_inconclusive = true.
        // Group 2: person-targeted, rollout 0% → OutOfRolloutBound.
        // With early_exit = true, the !is_inconclusive guard must prevent
        // short-circuiting, and the overall result must be InconclusiveMatchError.
        let flag = FeatureFlag {
            key: "early-exit-flag".to_string(),
            active: true,
            has_experiment: None,
            filters: FeatureFlagFilters {
                groups: vec![
                    FeatureFlagCondition {
                        properties: vec![],
                        rollout_percentage: Some(100.0),
                        variant: None,
                        aggregation_group_type_index: Some(0),
                    },
                    FeatureFlagCondition {
                        properties: vec![],
                        rollout_percentage: Some(0.0),
                        variant: None,
                        aggregation_group_type_index: None,
                    },
                ],
                multivariate: None,
                payloads: HashMap::new(),
                aggregation_group_type_index: None,
                early_exit: true,
            },
        };

        let mut group_type_mapping = HashMap::new();
        group_type_mapping.insert("0".to_string(), "company".to_string());

        let mut groups = HashMap::new();
        groups.insert("company".to_string(), "acme".to_string());

        // group_properties intentionally omitted for "company" → Inconclusive
        let result = match_feature_flag(
            &flag,
            "user-123",
            &HashMap::new(),
            &groups,
            &HashMap::new(), // empty group_properties
            &group_type_mapping,
        );
        assert!(
            result.is_err(),
            "expected InconclusiveMatchError, got {:?}",
            result
        );
    }
}