Skip to content

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

68.3 KB
Raw Blame
use crate::api::errors::FlagError;
use crate::cohorts::cohort_models::Cohort;
use crate::database::get_connection_with_metrics;
use crate::flags::flag_models::{
    EvaluationMetadata, FeatureFlag, FeatureFlagId, FeatureFlagList, FeatureFlagRow, FlagFilters,
    FlagPropertyGroup, HypercacheFlagsWrapper,
};
use crate::metrics::consts::{
    FLAG_MALFORMED_FILTER_COUNTER, FLAG_MALFORMED_FILTER_READ_COUNTER, TOMBSTONE_COUNTER,
};
use common_database::PostgresReader;
use common_types::TeamId;
use metrics::counter;
use serde::de::Deserializer;
use serde::Deserialize;
use serde_json::value::RawValue;
use std::collections::HashMap;
use std::collections::HashSet;
use std::sync::Arc;

/// Parsed hypercache result: flags, evaluation metadata, optional preloaded cohorts.
type HypercacheParseResult = (Vec<FeatureFlag>, EvaluationMetadata, Option<Vec<Cohort>>);

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum UndecodableDocument {
    NotAnObject,
    /// A v1 object whose `groups`, or a group's `properties`, is neither falsy nor a list of
    /// objects.
    /// Python's builder cannot read it either.
    MalformedV1Groups,
    /// A v1 object that Python's builder reads but the typed decoder rejects, such as one
    /// with a property filter that has no `type` key.
    UnreadableV1Object,
}

/// Rows `from_pg_keeping_undecodable` kept with blank filters, and why.
pub type UndecodableFlags = HashMap<FeatureFlagId, UndecodableDocument>;

/// `Arc<[FeatureFlag]>` with regexes pre-compiled. Every constructor routes
/// through [`PreparedFlags::seal`] (or `from_arc` for already-sealed input),
/// so a value of this type is guaranteed to have been through
/// `prepare_regexes_in_place`.
#[derive(Clone, Debug)]
pub struct PreparedFlags(Arc<[FeatureFlag]>);

impl PreparedFlags {
    pub fn seal(mut flags: Vec<FeatureFlag>) -> Self {
        FeatureFlagList::prepare_regexes_in_place(&mut flags);
        Self(Arc::from(flags))
    }

    /// Wraps an already-sealed `Arc<[FeatureFlag]>`. Crate-private so external
    /// callers can't smuggle in an unsealed Arc.
    pub(crate) fn from_arc(flags: Arc<[FeatureFlag]>) -> Self {
        Self(flags)
    }

    pub fn as_arc(&self) -> &Arc<[FeatureFlag]> {
        &self.0
    }
}

impl std::ops::Deref for PreparedFlags {
    type Target = [FeatureFlag];
    fn deref(&self) -> &[FeatureFlag] {
        &self.0
    }
}

impl Default for PreparedFlags {
    fn default() -> Self {
        Self(Arc::from(Vec::<FeatureFlag>::new()))
    }
}

impl From<Vec<FeatureFlag>> for PreparedFlags {
    fn from(flags: Vec<FeatureFlag>) -> Self {
        Self::seal(flags)
    }
}

fn record_dropped_flags(dropped: u64) {
    counter!(FLAG_MALFORMED_FILTER_COUNTER).increment(dropped);
    counter!(FLAG_MALFORMED_FILTER_READ_COUNTER).increment(1);
}

/// A flags array that skips an element it cannot deserialize, instead of
/// failing the whole array. Keeps the key and parse error of each skipped flag,
/// because the caller knows the team id and the deserializer does not.
#[derive(Debug)]
pub struct LenientFlags {
    flags: Vec<FeatureFlag>,
    skipped: Vec<(String, serde_json::Error)>,
}

impl<'de> Deserialize<'de> for LenientFlags {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        // This first splits the array into one borrowed JSON slice per flag, because
        // serde cannot resume a sequence after one element fails. A borrowed RawValue
        // fails unless the deserializer reads a string or byte slice, as the
        // hypercache reader's `serde_json::from_str` does.
        let raw_flags: Vec<&'de RawValue> = Vec::deserialize(deserializer)?;

        let mut flags = Vec::with_capacity(raw_flags.len());
        let mut skipped = Vec::new();
        for raw in &raw_flags {
            match serde_json::from_str::<FeatureFlag>(raw.get()) {
                Ok(flag) => flags.push(flag),
                Err(e) => {
                    let flag_key = serde_json::from_str::<serde_json::Value>(raw.get())
                        .ok()
                        .and_then(|v| v["key"].as_str().map(str::to_owned))
                        .unwrap_or_else(|| "<unknown>".to_owned());
                    skipped.push((flag_key, e));
                }
            }
        }
        Ok(LenientFlags { flags, skipped })
    }
}

/// The hypercache payload as the serving read parses it. The contract test
/// parses its fixture with this type and with the strict default, so a flag
/// shape that Rust cannot read fails that test instead of being skipped silently.
pub type LenientHypercacheFlagsWrapper = HypercacheFlagsWrapper<LenientFlags>;

impl LenientHypercacheFlagsWrapper {
    /// Drops the flags that failed to parse, and every metadata reference to them.
    pub fn into_wrapper(self, team_id: TeamId) -> HypercacheFlagsWrapper {
        let HypercacheFlagsWrapper {
            flags,
            mut evaluation_metadata,
            cohorts,
        } = self;

        if !flags.skipped.is_empty() {
            for (flag_key, e) in &flags.skipped {
                tracing::warn!(
                    "Failed to deserialize cached flag {} in team {}: {}",
                    flag_key,
                    team_id,
                    e
                );
            }
            let dropped = flags.skipped.len() as u64;
            record_dropped_flags(dropped);
            // Details (team_id, flag_key) are logged above to avoid high-cardinality labels
            counter!(
                TOMBSTONE_COUNTER,
                "namespace" => "feature_flags",
                "operation" => "hypercache_flag_deserialization_error",
                "component" => "feature_flag_list",
            )
            .increment(dropped);

            evaluation_metadata.has_unparseable_flags = true;
            // Django computes the metadata over every flag, so it still points at
            // the flags we just skipped.
            let kept_flag_ids: HashSet<i32> = flags.flags.iter().map(|f| f.id).collect();
            evaluation_metadata.retain_flags(&kept_flag_ids);
        }

        HypercacheFlagsWrapper {
            flags: flags.flags,
            evaluation_metadata,
            cohorts,
        }
    }
}

impl FeatureFlagList {
    pub fn new(flags: Vec<FeatureFlag>) -> Self {
        Self {
            flags: PreparedFlags::seal(flags),
            ..Default::default()
        }
    }

    /// Pre-compiles all regex patterns in property filters across a flag slice.
    /// The v2 parser compiles its own predicates.
    pub fn prepare_regexes_in_place(flags: &mut [FeatureFlag]) {
        for flag in flags.iter_mut().filter(|flag| flag.filters.is_v1()) {
            Self::prepare_group_regexes(&mut flag.filters.groups);
        }
    }

    fn prepare_group_regexes(groups: &mut [FlagPropertyGroup]) {
        for group in groups {
            if let Some(properties) = &mut group.properties {
                for filter in properties.iter_mut() {
                    filter.prepare_regex();
                }
            }
        }
    }

    /// Validates and extracts flags from a deserialized `HypercacheFlagsWrapper`.
    /// `None` means the `__missing__` sentinel (team has no flags).
    pub fn from_wrapper(
        wrapper: Option<HypercacheFlagsWrapper>,
        team_id: TeamId,
    ) -> Result<HypercacheParseResult, FlagError> {
        let wrapper = match wrapper {
            None => {
                tracing::debug!("Hypercache sentinel (no flags) for team {}", team_id);
                return Ok((vec![], EvaluationMetadata::default(), None));
            }
            Some(w) => w,
        };

        tracing::debug!(
            "Parsed {} flags and {} cohorts for team {}",
            wrapper.flags.len(),
            wrapper.cohorts.as_ref().map_or(0, |c| c.len()),
            team_id,
        );

        let evaluation_metadata = wrapper.evaluation_metadata;
        // A team whose every flag is in or depends on a dependency cycle has no stage. Its
        // metadata lists every flag in `flags_with_missing_deps`.
        let flag_without_stage = if evaluation_metadata.dependency_stages.is_empty() {
            wrapper.flags.iter().find(|flag| {
                !evaluation_metadata
                    .flags_with_missing_deps
                    .contains(&flag.id)
            })
        } else {
            None
        };
        if let Some(flag) = flag_without_stage {
            let message = format!(
                "evaluation_metadata.dependency_stages is empty but flag {} for team {team_id} is not in flags_with_missing_deps",
                flag.id
            );
            tracing::error!("{message}");
            return Err(FlagError::flag_data_parsing(message));
        }

        Ok((wrapper.flags, evaluation_metadata, wrapper.cohorts))
    }

    /// Returns feature flags from postgres given a team_id
    pub async fn from_pg(
        client: PostgresReader,
        team_id: TeamId,
    ) -> Result<Vec<FeatureFlag>, FlagError> {
        let (mut flags, undecodable) = Self::from_pg_keeping_undecodable(client, team_id).await?;
        flags.retain(|flag| !undecodable.contains_key(&flag.id));
        Ok(flags)
    }

    /// Like `from_pg`, but a row whose `filters` document could not be decoded stays in
    /// the list with blank filters and is reported in `UndecodableFlags`, so the cache
    /// builder can classify it and its dependents.
    pub async fn from_pg_keeping_undecodable(
        client: PostgresReader,
        team_id: TeamId,
    ) -> Result<(Vec<FeatureFlag>, UndecodableFlags), FlagError> {
        let mut conn = get_connection_with_metrics(&client, "non_persons_reader", "fetch_flags")
            .await
            .map_err(|e| {
                tracing::error!(
                    "Failed to get database connection for team {}: {}",
                    team_id,
                    e
                );
                FlagError::DatabaseUnavailable
            })?;

        let query = r#"
            SELECT f.id,
                  f.team_id,
                  f.name,
                  f.key,
                  f.filters,
                  f.deleted,
                  f.active,
                  f.ensure_experience_continuity,
                  f.version,
                  f.evaluation_runtime,
                  -- DISTINCT makes Postgres sort the names before it aggregates them, which
                  -- matches ArrayAgg(..., distinct=True) on the two Python paths that write
                  -- this cache entry: products/feature_flags/backend/flags_cache.py (batch) and
                  -- products/feature_flags/backend/models/feature_flag.py (single team, which is
                  -- also what the cache verifier compares against). Without DISTINCT the array
                  -- order follows the join, so the sides disagree for a flag with two or more
                  -- contexts. Keep all three in lockstep.
                  COALESCE(
                      ARRAY_AGG(DISTINCT ctx.name) FILTER (WHERE ctx.name IS NOT NULL),
                      '{}'::text[]
                  ) AS evaluation_tags,
                  bucketing_identifier,
                  -- Mirror the canonical Django predicate (live_experiment_exists in
                  -- products/experiments/backend/models/experiment.py,
                  -- Experiment.objects.filter(feature_flag_id=..., deleted=False)). Keep this in lockstep with it.
                  EXISTS (
                      SELECT 1 FROM posthog_experiment e
                      WHERE e.feature_flag_id = f.id AND e.deleted = false
                  ) AS has_experiment
              FROM posthog_featureflag AS f
              JOIN posthog_team AS t ON (f.team_id = t.id)
              LEFT JOIN posthog_featureflagevaluationcontext AS ec ON (f.id = ec.feature_flag_id)
              LEFT JOIN posthog_evaluationcontext AS ctx ON (ec.evaluation_context_id = ctx.id)
            WHERE t.id = $1
              AND f.deleted = false
              -- Exclude encrypted remote config flags - they can only be accessed via
              -- the dedicated /remote_config endpoint which handles decryption.
              -- Use IS TRUE to handle NULL values (NULL IS TRUE evaluates to FALSE, not NULL)
              AND NOT (f.is_remote_configuration IS TRUE AND f.has_encrypted_payloads IS TRUE)
            GROUP BY f.id, f.team_id, f.name, f.key, f.filters, f.deleted, f.active,
                     f.ensure_experience_continuity, f.version, f.evaluation_runtime
        "#;
        let flags_row = sqlx::query_as::<
            _,
            FeatureFlagRow<sqlx::types::Json<Box<serde_json::value::RawValue>>>,
        >(query)
        .bind(team_id)
        .fetch_all(&mut *conn)
        .await
        .map_err(|e| {
            tracing::error!(
                "Failed to fetch feature flags from database for team {}: {}",
                team_id,
                e
            );
            let message = format!("Database query error: {e}");
            FlagError::internal(anyhow::Error::new(e).context(message))
        })?;

        let mut undecodable = UndecodableFlags::default();
        let flags: Vec<FeatureFlag> = flags_row
            .into_iter()
            .map(|row| {
                let filters = crate::flags::config_format::decode_raw_filters(row.filters.0)
                    .unwrap_or_else(|e| {
                        // Serde fails the whole `filters` struct when a required field is
                        // absent, so one bad property filter costs the entire flag. A property
                        // filter with no `"type"` key does that, because
                        // PropertyFilter::prop_type has no default. Python reads only the cohort
                        // and flag references. It reads a property's `type` with `.get`, so it
                        // keeps such a flag when the flag is active. Those drops are real
                        // builder divergences, which `UnreadableV1Object` marks. Either way the
                        // team keeps the rest of its flags, rather than failing the read.
                        tracing::warn!(
                            "Failed to deserialize filters for flag {} in team {}: {}",
                            row.key,
                            row.team_id,
                            e
                        );
                        // Details (team_id, flag_key) are logged above to avoid high-cardinality labels
                        counter!(
                            TOMBSTONE_COUNTER,
                            "namespace" => "feature_flags",
                            "operation" => "flag_filter_deserialization_error",
                            "component" => "feature_flag_list",
                        )
                        .increment(1);
                        undecodable.insert(row.id, e.document);
                        FlagFilters::default()
                    });
                FeatureFlag {
                    id: row.id,
                    team_id: row.team_id,
                    name: row.name,
                    key: row.key,
                    filters,
                    deleted: row.deleted,
                    active: row.active,
                    ensure_experience_continuity: row.ensure_experience_continuity,
                    version: row.version,
                    evaluation_runtime: row.evaluation_runtime,
                    evaluation_tags: row.evaluation_tags,
                    bucketing_identifier: row.bucketing_identifier,
                    has_experiment: row.has_experiment,
                }
            })
            .collect();

        if !undecodable.is_empty() {
            record_dropped_flags(undecodable.len() as u64);
        }

        tracing::debug!(
            "Successfully fetched {} flags from database for team {}",
            flags.len() - undecodable.len(),
            team_id
        );

        Ok((flags, undecodable))
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::{
        flags::{flag_models::FlagFilters, test_helpers::get_flags_from_redis},
        properties::property_models::{OperatorType, PropertyFilter, PropertyType},
        utils::test_utils::{
            insert_flags_for_team_in_redis, insert_new_team_in_redis, setup_invalid_pg_client,
            setup_redis_client, TestContext,
        },
    };

    #[tokio::test]
    async fn test_fetch_flags_from_redis() {
        let redis_client = setup_redis_client(None).await;

        let team = insert_new_team_in_redis(redis_client.clone())
            .await
            .expect("Failed to insert team");

        insert_flags_for_team_in_redis(redis_client.clone(), team.id, None)
            .await
            .expect("Failed to insert flags");

        let flags_from_redis = get_flags_from_redis(redis_client.clone(), team.id)
            .await
            .expect("Failed to fetch flags from redis");
        assert_eq!(flags_from_redis.flags.len(), 1);
        let flag = flags_from_redis
            .flags
            .first()
            .expect("Empty flags in redis");
        assert_eq!(flag.key, "flag1");
        assert_eq!(flag.team_id, team.id);
        assert_eq!(flag.filters.groups.len(), 1);
        assert_eq!(flag.filters.groups[0].properties.as_ref().unwrap().len(), 1);
    }

    #[tokio::test]
    async fn test_fetch_invalid_team_from_redis() {
        let redis_client = setup_redis_client(None).await;

        match get_flags_from_redis(redis_client.clone(), 1234).await {
            Err(FlagError::TokenValidationError) => {
                // Expected error
            }
            _ => panic!("Expected TokenValidationError"),
        }
    }

    #[tokio::test]
    #[should_panic(expected = "Failed to create redis client")]
    async fn test_cant_connect_to_redis_error_is_not_token_validation_error() {
        // Test that client creation fails when Redis is unavailable
        setup_redis_client(Some("redis://localhost:1111/".to_string())).await;
    }

    #[tokio::test]
    async fn test_fetch_flags_from_pg() {
        let context = TestContext::new(None).await;
        let team = context
            .insert_new_team(None)
            .await
            .expect("Failed to insert team");

        context
            .insert_flag(team.id, None)
            .await
            .expect("Failed to insert flag");

        let flags_from_pg = FeatureFlagList::from_pg(context.non_persons_reader.clone(), team.id)
            .await
            .expect("Failed to fetch flags from pg");

        assert_eq!(flags_from_pg.len(), 1);
        let flag = flags_from_pg.first().expect("Flags should be in pg");
        assert_eq!(flag.key, "flag1");
        assert_eq!(flag.team_id, team.id);
        assert_eq!(flag.filters.groups.len(), 1);
        assert_eq!(flag.filters.groups[0].properties.as_ref().unwrap().len(), 1);
    }

    #[tokio::test]
    async fn test_from_pg_computes_has_experiment() {
        let context = TestContext::new(None).await;
        let team = context
            .insert_new_team(None)
            .await
            .expect("Failed to insert team");

        let make_row = |key: &str| FeatureFlagRow {
            team_id: team.id,
            name: Some(key.to_string()),
            key: key.to_string(),
            filters: serde_json::json!({"groups": [{"properties": [], "rollout_percentage": 100}]}),
            active: true,
            ..Default::default()
        };

        let live = context
            .insert_flag(team.id, Some(make_row("flag_with_live_experiment")))
            .await
            .expect("Failed to insert flag");
        let deleted_only = context
            .insert_flag(team.id, Some(make_row("flag_with_deleted_experiment")))
            .await
            .expect("Failed to insert flag");
        context
            .insert_flag(team.id, Some(make_row("flag_without_experiment")))
            .await
            .expect("Failed to insert flag");

        context
            .insert_experiment(live.id, team.id, false)
            .await
            .expect("Failed to insert live experiment");
        // A deleted experiment must not count as linkage.
        context
            .insert_experiment(deleted_only.id, team.id, true)
            .await
            .expect("Failed to insert deleted experiment");

        let flags = FeatureFlagList::from_pg(context.non_persons_reader.clone(), team.id)
            .await
            .expect("Failed to fetch flags from pg");

        let by_key = |key: &str| {
            flags
                .iter()
                .find(|f| f.key == key)
                .unwrap_or_else(|| panic!("missing flag {key}"))
                .has_experiment
        };

        assert!(by_key("flag_with_live_experiment"));
        assert!(!by_key("flag_with_deleted_experiment"));
        assert!(!by_key("flag_without_experiment"));
    }

    #[tokio::test]
    async fn test_fetch_empty_team_from_pg() {
        let context = TestContext::new(None).await;

        let flags = FeatureFlagList::from_pg(context.non_persons_reader.clone(), 1234)
            .await
            .expect("Failed to fetch flags from pg");

        assert_eq!(flags.len(), 0);
    }

    #[tokio::test]
    async fn test_fetch_nonexistent_team_from_pg() {
        let context = TestContext::new(None).await;

        match FeatureFlagList::from_pg(context.non_persons_reader.clone(), -1).await {
            Ok(flags) => assert_eq!(flags.len(), 0),
            Err(err) => panic!("Expected empty result, got error: {err:?}"),
        }
    }

    #[tokio::test]
    async fn test_fetch_flags_db_connection_failure() {
        let invalid_client = setup_invalid_pg_client().await;

        match FeatureFlagList::from_pg(invalid_client, 1).await {
            Ok(_) => panic!("Expected error for invalid database connection"),
            Err(FlagError::DatabaseUnavailable) => {
                // Expected error
            }
            Err(e) => panic!("Unexpected error: {e:?}"),
        }
    }

    #[tokio::test]
    async fn test_fetch_multiple_flags_from_pg() {
        let context = TestContext::new(None).await;
        let team = context
            .insert_new_team(None)
            .await
            .expect("Failed to insert team");

        let flag1 = FeatureFlagRow {
            id: 0,
            team_id: team.id,
            name: Some("Test Flag".to_string()),
            key: "test_flag".to_string(),
            filters: serde_json::json!({"groups": [{"properties": [], "rollout_percentage": 100}]}),
            deleted: false,
            active: true,
            ensure_experience_continuity: Some(false),
            version: Some(1),
            evaluation_runtime: Some("all".to_string()),
            evaluation_tags: None,
            bucketing_identifier: None,
            has_experiment: false,
        };

        let flag2 = FeatureFlagRow {
            id: 0,
            team_id: team.id,
            name: Some("Test Flag 2".to_string()),
            key: "test_flag_2".to_string(),
            filters: serde_json::json!({"groups": [{"properties": [], "rollout_percentage": 100}]}),
            deleted: false,
            active: true,
            ensure_experience_continuity: Some(false),
            version: Some(1),
            evaluation_runtime: Some("all".to_string()),
            evaluation_tags: None,
            bucketing_identifier: None,
            has_experiment: false,
        };

        // Insert multiple flags for the team
        context
            .insert_flag(team.id, Some(flag1))
            .await
            .expect("Failed to insert flags");

        context
            .insert_flag(team.id, Some(flag2))
            .await
            .expect("Failed to insert flags");

        let flags_from_pg = FeatureFlagList::from_pg(context.non_persons_reader.clone(), team.id)
            .await
            .expect("Failed to fetch flags from pg");

        assert_eq!(flags_from_pg.len(), 2);
        for flag in &flags_from_pg {
            assert_eq!(flag.team_id, team.id);
        }
    }

    #[tokio::test]
    async fn test_flag_with_malformed_filters_is_dropped_and_counted() {
        use metrics_util::debugging::{DebugValue, DebuggingRecorder};

        // `set_default_local_recorder` returns a thread-local guard; safe across
        // `.await` because `#[tokio::test]` defaults to a current-thread runtime.
        let recorder = DebuggingRecorder::new();
        let snapshotter = recorder.snapshotter();
        let _guard = metrics::set_default_local_recorder(&recorder);

        let context = TestContext::new(None).await;
        let team = context
            .insert_new_team(None)
            .await
            .expect("Failed to insert team");

        let good_flag = FeatureFlagRow {
            id: 0,
            team_id: team.id,
            name: Some("Good flag".to_string()),
            key: "good_flag".to_string(),
            filters: serde_json::json!({"groups": [{"properties": [], "rollout_percentage": 100}]}),
            deleted: false,
            active: true,
            ensure_experience_continuity: Some(false),
            version: Some(1),
            evaluation_runtime: Some("all".to_string()),
            evaluation_tags: None,
            bucketing_identifier: None,
            has_experiment: false,
        };

        // `groups` holds a string where FlagFilters wants a list, so this blob stays
        // unparseable whatever PropertyFilter later does with a missing `"type"`.
        let malformed_flag = FeatureFlagRow {
            id: 0,
            team_id: team.id,
            name: Some("Malformed flag".to_string()),
            key: "malformed_flag".to_string(),
            filters: serde_json::json!({"groups": "not-a-list"}),
            deleted: false,
            active: true,
            ensure_experience_continuity: Some(false),
            version: Some(1),
            evaluation_runtime: Some("all".to_string()),
            evaluation_tags: None,
            bucketing_identifier: None,
            has_experiment: false,
        };

        context
            .insert_flag(team.id, Some(good_flag))
            .await
            .expect("Failed to insert good flag");
        context
            .insert_flag(team.id, Some(malformed_flag))
            .await
            .expect("Failed to insert malformed flag");

        let flags = FeatureFlagList::from_pg(context.non_persons_reader.clone(), team.id)
            .await
            .expect("A malformed flag must not fail the whole read");

        let keys: Vec<&str> = flags.iter().map(|f| f.key.as_str()).collect();
        assert_eq!(keys, vec!["good_flag"]);

        let counter_value = |name: &str| {
            snapshotter
                .snapshot()
                .into_vec()
                .into_iter()
                .find(|(ckey, _, _, _)| ckey.key().name() == name)
                .map(|(_, _, _, value)| value)
        };

        assert_eq!(
            counter_value(FLAG_MALFORMED_FILTER_COUNTER),
            Some(DebugValue::Counter(1))
        );
        assert_eq!(
            counter_value(FLAG_MALFORMED_FILTER_READ_COUNTER),
            Some(DebugValue::Counter(1))
        );
    }

    #[tokio::test]
    async fn test_fetch_flags_with_evaluation_tags_from_pg() {
        let context = TestContext::new(None).await;
        let team = context
            .insert_new_team(None)
            .await
            .expect("Failed to insert team");

        let flag_row = context
            .insert_flag(team.id, None)
            .await
            .expect("Failed to insert flag");

        // Insert evaluation tags for the flag
        context
            .insert_evaluation_tags_for_flag(
                flag_row.id,
                team.id,
                vec!["docs-page", "marketing-site", "app"],
            )
            .await
            .expect("Failed to insert evaluation tags");

        let flags_from_pg = FeatureFlagList::from_pg(context.non_persons_reader.clone(), team.id)
            .await
            .expect("Failed to fetch flags from pg");

        assert_eq!(flags_from_pg.len(), 1);
        let flag = flags_from_pg.first().expect("Should have one flag");
        assert_eq!(flag.key, "flag1");
        assert_eq!(flag.team_id, team.id);

        // ARRAY_AGG(DISTINCT ...) sorts, so this is not the insertion order.
        let tags = flag
            .evaluation_tags
            .as_ref()
            .expect("Should have evaluation tags");
        let tag_names: Vec<&str> = tags.iter().map(String::as_str).collect();
        assert_eq!(tag_names, ["app", "docs-page", "marketing-site"]);
    }

    #[tokio::test]
    async fn test_encrypted_remote_config_flags_excluded_from_pg() {
        let context = TestContext::new(None).await;
        let team = context
            .insert_new_team(None)
            .await
            .expect("Failed to insert team");

        let mut conn = context
            .non_persons_writer
            .get_connection()
            .await
            .expect("Failed to get connection");

        // Insert a regular feature flag via raw SQL (is_remote_configuration = false)
        sqlx::query(
            r#"INSERT INTO posthog_featureflag
            (team_id, name, key, filters, deleted, active, ensure_experience_continuity,
             is_remote_configuration, has_encrypted_payloads, created_at)
            VALUES ($1, $2, $3, $4, false, true, false, false, false, '2024-06-17')"#,
        )
        .bind(team.id)
        .bind("Regular Flag")
        .bind("regular_flag")
        .bind(serde_json::json!({"groups": [{"properties": [], "rollout_percentage": 100}]}))
        .execute(&mut *conn)
        .await
        .expect("Failed to insert regular flag");

        // Insert an unencrypted remote config flag via raw SQL
        sqlx::query(
            r#"INSERT INTO posthog_featureflag
            (team_id, name, key, filters, deleted, active, ensure_experience_continuity,
             is_remote_configuration, has_encrypted_payloads, created_at)
            VALUES ($1, $2, $3, $4, false, true, false, true, false, '2024-06-17')"#,
        )
        .bind(team.id)
        .bind("Unencrypted Remote Config Flag")
        .bind("unencrypted_remote_config_flag")
        .bind(serde_json::json!({"groups": [{"properties": [], "rollout_percentage": 100}]}))
        .execute(&mut *conn)
        .await
        .expect("Failed to insert unencrypted remote config flag");

        // Insert an encrypted remote config flag via raw SQL
        sqlx::query(
            r#"INSERT INTO posthog_featureflag
            (team_id, name, key, filters, deleted, active, ensure_experience_continuity,
             is_remote_configuration, has_encrypted_payloads, created_at)
            VALUES ($1, $2, $3, $4, false, true, false, true, true, '2024-06-17')"#,
        )
        .bind(team.id)
        .bind("Encrypted Remote Config Flag")
        .bind("encrypted_remote_config_flag")
        .bind(serde_json::json!({"groups": [{"properties": [], "rollout_percentage": 100}]}))
        .execute(&mut *conn)
        .await
        .expect("Failed to insert encrypted remote config flag");

        let flags_from_pg = FeatureFlagList::from_pg(context.non_persons_reader.clone(), team.id)
            .await
            .expect("Failed to fetch flags from pg");

        // Regular flag and unencrypted remote config flag should be returned
        // Encrypted remote config flag should be excluded
        assert_eq!(flags_from_pg.len(), 2);

        let flag_keys: Vec<&str> = flags_from_pg.iter().map(|f| f.key.as_str()).collect();
        assert!(flag_keys.contains(&"regular_flag"));
        assert!(flag_keys.contains(&"unencrypted_remote_config_flag"));
        assert!(!flag_keys.contains(&"encrypted_remote_config_flag"));
    }

    #[tokio::test]
    async fn test_null_values_included_in_pg_query() {
        // Verify that flags with NULL values for is_remote_configuration and/or
        // has_encrypted_payloads are correctly included (not excluded by the filter).
        // This tests the IS TRUE logic: NULL IS TRUE evaluates to FALSE, so
        // NOT (NULL IS TRUE AND ...) evaluates to TRUE, including the row.
        let context = TestContext::new(None).await;
        let team = context
            .insert_new_team(None)
            .await
            .expect("Failed to insert team");

        let mut conn = context
            .non_persons_writer
            .get_connection()
            .await
            .expect("Failed to get connection");

        // Insert flag with is_remote_configuration = NULL, has_encrypted_payloads = false
        sqlx::query(
            r#"INSERT INTO posthog_featureflag
            (team_id, name, key, filters, deleted, active, ensure_experience_continuity,
             is_remote_configuration, has_encrypted_payloads, created_at)
            VALUES ($1, $2, $3, $4, false, true, false, NULL, false, '2024-06-17')"#,
        )
        .bind(team.id)
        .bind("Null Remote Config Flag")
        .bind("null_remote_config")
        .bind(serde_json::json!({"groups": [{"properties": [], "rollout_percentage": 100}]}))
        .execute(&mut *conn)
        .await
        .expect("Failed to insert null remote config flag");

        // Insert flag with is_remote_configuration = true, has_encrypted_payloads = NULL
        sqlx::query(
            r#"INSERT INTO posthog_featureflag
            (team_id, name, key, filters, deleted, active, ensure_experience_continuity,
             is_remote_configuration, has_encrypted_payloads, created_at)
            VALUES ($1, $2, $3, $4, false, true, false, true, NULL, '2024-06-17')"#,
        )
        .bind(team.id)
        .bind("Null Encrypted Flag")
        .bind("null_encrypted")
        .bind(serde_json::json!({"groups": [{"properties": [], "rollout_percentage": 100}]}))
        .execute(&mut *conn)
        .await
        .expect("Failed to insert null encrypted flag");

        // Insert legacy flag with both fields NULL
        sqlx::query(
            r#"INSERT INTO posthog_featureflag
            (team_id, name, key, filters, deleted, active, ensure_experience_continuity,
             is_remote_configuration, has_encrypted_payloads, created_at)
            VALUES ($1, $2, $3, $4, false, true, false, NULL, NULL, '2024-06-17')"#,
        )
        .bind(team.id)
        .bind("Legacy Flag")
        .bind("legacy_flag")
        .bind(serde_json::json!({"groups": [{"properties": [], "rollout_percentage": 100}]}))
        .execute(&mut *conn)
        .await
        .expect("Failed to insert legacy flag");

        // Insert flag with is_remote_configuration = NULL, has_encrypted_payloads = true
        // This should still be included because is_remote_configuration is not TRUE
        sqlx::query(
            r#"INSERT INTO posthog_featureflag
            (team_id, name, key, filters, deleted, active, ensure_experience_continuity,
             is_remote_configuration, has_encrypted_payloads, created_at)
            VALUES ($1, $2, $3, $4, false, true, false, NULL, true, '2024-06-17')"#,
        )
        .bind(team.id)
        .bind("Null Remote Encrypted True Flag")
        .bind("null_remote_encrypted_true")
        .bind(serde_json::json!({"groups": [{"properties": [], "rollout_percentage": 100}]}))
        .execute(&mut *conn)
        .await
        .expect("Failed to insert null remote encrypted true flag");

        let flags_from_pg = FeatureFlagList::from_pg(context.non_persons_reader.clone(), team.id)
            .await
            .expect("Failed to fetch flags from pg");

        // All flags with NULL values should be included
        assert_eq!(flags_from_pg.len(), 4);

        let flag_keys: Vec<&str> = flags_from_pg.iter().map(|f| f.key.as_str()).collect();
        assert!(
            flag_keys.contains(&"null_remote_config"),
            "Flag with NULL is_remote_configuration should be included"
        );
        assert!(
            flag_keys.contains(&"null_encrypted"),
            "Flag with NULL has_encrypted_payloads should be included"
        );
        assert!(
            flag_keys.contains(&"legacy_flag"),
            "Legacy flag with both NULL should be included"
        );
        assert!(
            flag_keys.contains(&"null_remote_encrypted_true"),
            "Flag with NULL is_remote_configuration and TRUE has_encrypted_payloads should be included"
        );
    }

    #[test]
    fn test_cache_format_backward_compatibility() {
        // This test verifies that the cache format (Vec<FeatureFlag>) remains stable.
        // We cache Vec<FeatureFlag> directly, and any format change would invalidate
        // all existing cache entries, causing a thundering herd of database queries.
        use crate::flags::flag_models::{FeatureFlag, FlagFilters};

        // Create test flags in the format we cache
        let cached_flags = vec![FeatureFlag {
            id: 1,
            team_id: 123,
            name: Some("Test Flag".to_string()),
            key: "test_flag".to_string(),
            has_experiment: false,
            filters: FlagFilters::default(),
            deleted: false,
            active: true,
            ensure_experience_continuity: Some(false),
            version: Some(1),
            evaluation_runtime: Some("all".to_string()),
            evaluation_tags: None,
            bucketing_identifier: None,
        }];

        // Serialize as we do in production cache
        let cached_json =
            serde_json::to_string(&cached_flags).expect("Failed to serialize flags for cache");

        // Verify we can deserialize it back (cache read path)
        let result = serde_json::from_str::<Vec<FeatureFlag>>(&cached_json);

        assert!(
            result.is_ok(),
            "FAILED: Cannot deserialize cached flags. This indicates a cache format change \
             that will invalidate all existing cache entries, causing thundering herd. \
             Cached JSON: {}\nError: {:?}",
            cached_json,
            result.unwrap_err()
        );

        // Verify the deserialized data is correct
        let deserialized_flags = result.unwrap();
        assert_eq!(deserialized_flags.len(), 1);
        assert_eq!(deserialized_flags[0].key, "test_flag");
        assert_eq!(deserialized_flags[0].id, 1);
    }

    // =========================================================================
    // Tests for from_wrapper()
    // =========================================================================

    use serde_json::json;

    #[test]
    fn test_lenient_wrapper_skips_unparseable_flag_and_keeps_the_rest() {
        use crate::flags::test_helpers::payload_with_unparseable_flag;
        use crate::utils::test_utils::counter_total;
        use metrics_util::debugging::DebuggingRecorder;

        let recorder = DebuggingRecorder::new();
        let snapshotter = recorder.snapshotter();
        let _guard = metrics::set_default_local_recorder(&recorder);

        let wrapper: LenientHypercacheFlagsWrapper =
            serde_json::from_str(&payload_with_unparseable_flag(123).to_string()).unwrap();

        let wrapper = wrapper.into_wrapper(123);
        let metadata = &wrapper.evaluation_metadata;

        let keys: Vec<&str> = wrapper.flags.iter().map(|f| f.key.as_str()).collect();
        assert_eq!(keys, vec!["healthy_flag", "dependent_flag"]);
        assert_eq!(metadata.dependency_stages, vec![vec![1], vec![3]]);
        assert_eq!(metadata.flags_with_missing_deps, vec![1, 3]);
        assert!(metadata.has_unparseable_flags);
        assert!(!metadata.transitive_deps.contains_key(&2));
        assert!(metadata.transitive_deps[&3].is_empty());

        assert_eq!(
            counter_total(&snapshotter, FLAG_MALFORMED_FILTER_COUNTER, &[]),
            1
        );
        assert_eq!(
            counter_total(&snapshotter, FLAG_MALFORMED_FILTER_READ_COUNTER, &[]),
            1
        );
    }

    #[test]
    fn test_from_wrapper_valid_flags() {
        let wrapper: HypercacheFlagsWrapper = serde_json::from_value(json!({
            "flags": [
                {
                    "id": 1,
                    "key": "test_flag",
                    "team_id": 123,
                    "active": true,
                    "deleted": false,
                    "filters": { "groups": [] }
                },
                {
                    "id": 2,
                    "key": "another_flag",
                    "team_id": 123,
                    "active": false,
                    "deleted": false,
                    "filters": { "groups": [] }
                }
            ],
            "evaluation_metadata": {
                "dependency_stages": [[1, 2]],
                "flags_with_missing_deps": [],
                "transitive_deps": {}
            }
        }))
        .unwrap();

        let (flags, metadata, _cohorts) =
            FeatureFlagList::from_wrapper(Some(wrapper), 123).unwrap();
        assert_eq!(metadata.dependency_stages, vec![vec![1, 2]]);
        assert!(metadata.flags_with_missing_deps.is_empty());
        assert!(metadata.transitive_deps.is_empty());
        assert_eq!(flags.len(), 2);
        assert_eq!(flags[0].key, "test_flag");
        assert!(flags[0].active);
        assert_eq!(flags[1].key, "another_flag");
        assert!(!flags[1].active);
    }

    #[test]
    fn test_from_wrapper_with_evaluation_context_valid_flags() {
        let wrapper: HypercacheFlagsWrapper = serde_json::from_value(json!({
            "evaluation_metadata": {
                "dependency_stages": [
                    [766, 768, 769],
                    [765]
                ],
                "flags_with_missing_deps": [768],
                "transitive_deps": {
                    "765": [766],
                    "766": [],
                    "768": [],
                    "769": []
                }
            },
            "flags": [
                {
                    "active": true,
                    "bucketing_identifier": null,
                    "deleted": false,
                    "ensure_experience_continuity": false,
                    "evaluation_contexts": [],
                    "evaluation_runtime": "all",
                    "filters": {
                        "groups": [
                            {
                                "properties": [
                                    {
                                        "key": "766",
                                        "label": "client-only-flag",
                                        "operator": "flag_evaluates_to",
                                        "type": "flag",
                                        "value": true
                                    }
                                ],
                                "rollout_percentage": 100,
                                "variant": null
                            }
                        ],
                        "multivariate": null,
                        "payloads": {}
                    },
                    "has_encrypted_payloads": false,
                    "id": 765,
                    "key": "all-flag-with-flag-dependency",
                    "name": "",
                    "team_id": 15,
                    "version": 3
                },
                {
                    "active": true,
                    "bucketing_identifier": null,
                    "deleted": false,
                    "ensure_experience_continuity": false,
                    "evaluation_contexts": [],
                    "evaluation_runtime": "client",
                    "filters": {
                        "groups": [
                            {
                                "properties": [],
                                "rollout_percentage": 100,
                                "variant": null
                            }
                        ],
                        "multivariate": null,
                        "payloads": {}
                    },
                    "has_encrypted_payloads": false,
                    "id": 766,
                    "key": "client-only-flag",
                    "name": "",
                    "team_id": 15,
                    "version": 2
                },
                {
                    "active": true,
                    "bucketing_identifier": null,
                    "deleted": false,
                    "ensure_experience_continuity": false,
                    "evaluation_contexts": [],
                    "evaluation_runtime": "all",
                    "filters": {
                        "groups": [
                            {
                                "properties": [
                                    {
                                        "key": "9999",
                                        "label": "boolean-flag",
                                        "operator": "flag_evaluates_to",
                                        "type": "flag",
                                        "value": true
                                    }
                                ],
                                "rollout_percentage": 100,
                                "variant": null
                            }
                        ],
                        "multivariate": null,
                        "payloads": {}
                    },
                    "has_encrypted_payloads": false,
                    "id": 768,
                    "key": "flag-with-truly-missing-dependency",
                    "name": "",
                    "team_id": 15,
                    "version": 2
                },
                {
                    "active": true,
                    "bucketing_identifier": null,
                    "deleted": false,
                    "ensure_experience_continuity": false,
                    "evaluation_contexts": [],
                    "evaluation_runtime": "all",
                    "filters": {
                        "groups": [
                            {
                                "properties": [
                                    {
                                        "cohort_name": "[Test] Dependent Cohort",
                                        "key": "id",
                                        "operator": "in",
                                        "type": "cohort",
                                        "value": 5
                                    }
                                ],
                                "rollout_percentage": 100,
                                "variant": null
                            }
                        ],
                        "multivariate": null,
                        "payloads": {}
                    },
                    "has_encrypted_payloads": false,
                    "id": 769,
                    "key": "cohort-dependency-flag",
                    "name": "",
                    "team_id": 15,
                    "version": 1
                }
            ]
        }))
        .unwrap();

        let (flags, evaluation_metadata, _cohorts) =
            FeatureFlagList::from_wrapper(Some(wrapper), 123).unwrap();
        assert_eq!(evaluation_metadata.dependency_stages.len(), 2);
        assert_eq!(
            evaluation_metadata.dependency_stages[0],
            vec![766, 768, 769]
        );
        assert_eq!(evaluation_metadata.dependency_stages[1], vec![765]);
        assert_eq!(evaluation_metadata.flags_with_missing_deps, vec![768]);
        assert_eq!(evaluation_metadata.transitive_deps.len(), 4);
        assert_eq!(evaluation_metadata.transitive_deps[&765].len(), 1);
        assert!(evaluation_metadata.transitive_deps[&765].contains(&766));
        assert!(evaluation_metadata.transitive_deps[&766].is_empty());
        assert!(evaluation_metadata.transitive_deps[&768].is_empty());
        assert!(evaluation_metadata.transitive_deps[&769].is_empty());
        assert_eq!(flags.len(), 4);
        assert_eq!(flags[0].key, "all-flag-with-flag-dependency");
        assert!(flags[0].active);
        assert_eq!(flags[1].key, "client-only-flag");
        assert!(flags[1].active);
        assert_eq!(flags[2].key, "flag-with-truly-missing-dependency");
        assert!(flags[2].active);
        assert_eq!(flags[3].key, "cohort-dependency-flag");
        assert!(flags[3].active);
    }

    #[test]
    fn test_from_wrapper_none_returns_empty() {
        let (flags, metadata, cohorts) = FeatureFlagList::from_wrapper(None, 123).unwrap();
        assert!(flags.is_empty());
        assert_eq!(metadata, EvaluationMetadata::default());
        assert!(cohorts.is_none());
    }

    #[test]
    fn test_from_wrapper_empty_flags_array() {
        let wrapper: HypercacheFlagsWrapper = serde_json::from_value(json!({
            "flags": [],
            "evaluation_metadata": {
                "dependency_stages": [],
                "flags_with_missing_deps": [],
                "transitive_deps": {}
            }
        }))
        .unwrap();
        let (flags, metadata, _cohorts) =
            FeatureFlagList::from_wrapper(Some(wrapper), 123).unwrap();
        assert!(flags.is_empty());
        assert_eq!(metadata, EvaluationMetadata::default());
    }

    #[test]
    fn test_from_wrapper_with_all_optional_fields() {
        let wrapper: HypercacheFlagsWrapper = serde_json::from_value(json!({
            "flags": [
                {
                    "id": 42,
                    "key": "full_flag",
                    "team_id": 123,
                    "name": "Full Feature Flag",
                    "active": true,
                    "deleted": false,
                    "filters": {
                        "groups": [{
                            "properties": [{
                                "key": "email",
                                "value": "[email protected]",
                                "type": "person",
                                "operator": "exact"
                            }],
                            "rollout_percentage": 50
                        }]
                    },
                    "ensure_experience_continuity": true,
                    "version": 5,
                    "evaluation_runtime": "frontend"
                }
            ],
            "evaluation_metadata": {
                "dependency_stages": [[42]],
                "flags_with_missing_deps": [],
                "transitive_deps": {}
            }
        }))
        .unwrap();

        let (flags, metadata, _cohorts) =
            FeatureFlagList::from_wrapper(Some(wrapper), 123).unwrap();
        assert_eq!(metadata.dependency_stages, vec![vec![42]]);
        assert!(metadata.flags_with_missing_deps.is_empty());
        assert!(metadata.transitive_deps.is_empty());
        assert_eq!(flags.len(), 1);
        let flag = &flags[0];
        assert_eq!(flag.id, 42);
        assert_eq!(flag.key, "full_flag");
        assert_eq!(flag.name, Some("Full Feature Flag".to_string()));
        assert_eq!(flag.ensure_experience_continuity, Some(true));
        assert_eq!(flag.version, Some(5));
        assert_eq!(flag.evaluation_runtime, Some("frontend".to_string()));
        assert_eq!(flag.filters.groups.len(), 1);
        assert_eq!(flag.filters.groups[0].rollout_percentage, Some(50.0));
    }

    #[test]
    fn test_from_wrapper_with_cohorts() {
        let wrapper: HypercacheFlagsWrapper = serde_json::from_value(json!({
            "flags": [],
            "evaluation_metadata": {
                "dependency_stages": [],
                "flags_with_missing_deps": [],
                "transitive_deps": {}
            },
            "cohorts": [{
                "id": 42,
                "name": "Test Cohort",
                "description": null,
                "team_id": 123,
                "deleted": false,
                "filters": {"properties": {"type": "AND", "values": []}},
                "query": null,
                "version": 1,
                "pending_version": null,
                "count": 100,
                "is_calculating": false,
                "is_static": false,
                "errors_calculating": 0,
                "groups": [],
                "created_by_id": null,
                "cohort_type": null
            }]
        }))
        .unwrap();
        let (_flags, _metadata, cohorts) =
            FeatureFlagList::from_wrapper(Some(wrapper), 123).unwrap();
        let cohorts = cohorts.expect("cohorts should be Some");
        assert_eq!(cohorts.len(), 1);
        assert_eq!(cohorts[0].id, 42);
        assert_eq!(cohorts[0].name, Some("Test Cohort".to_string()));
        assert_eq!(cohorts[0].team_id, 123);
        assert!(!cohorts[0].deleted);
    }

    #[test]
    fn test_from_wrapper_without_cohorts_defaults_to_none() {
        let wrapper: HypercacheFlagsWrapper = serde_json::from_value(json!({
            "flags": [{
                "id": 1,
                "team_id": 123,
                "name": "flag",
                "key": "flag-key",
                "filters": {"groups": []}
            }],
            "evaluation_metadata": {
                "dependency_stages": [[1]],
                "flags_with_missing_deps": [],
                "transitive_deps": {}
            }
        }))
        .unwrap();
        let (_flags, _metadata, cohorts) =
            FeatureFlagList::from_wrapper(Some(wrapper), 123).unwrap();
        assert!(cohorts.is_none());
    }

    fn wrapper_with_empty_stages(
        flags_with_missing_deps: serde_json::Value,
    ) -> HypercacheFlagsWrapper {
        serde_json::from_value(json!({
            "flags": [
                {"id": 10, "key": "a", "team_id": 1, "active": true, "deleted": false, "filters": {"groups": []}},
                {"id": 20, "key": "b", "team_id": 1, "active": true, "deleted": false, "filters": {"groups": []}}
            ],
            "evaluation_metadata": {
                "dependency_stages": [],
                "flags_with_missing_deps": flags_with_missing_deps,
                "transitive_deps": {}
            }
        }))
        .unwrap()
    }

    #[rstest::rstest]
    #[case::no_flag_has_missing_deps(json!([]))]
    #[case::one_flag_unaccounted(json!([10]))]
    fn test_from_wrapper_empty_stages_with_unaccounted_flags_is_error(
        #[case] flags_with_missing_deps: serde_json::Value,
    ) {
        let result = FeatureFlagList::from_wrapper(
            Some(wrapper_with_empty_stages(flags_with_missing_deps)),
            1,
        );
        assert!(matches!(
            result,
            Err(FlagError::InternalError {
                code: "flag_data_parsing_error",
                ..
            })
        ));
    }

    #[test]
    fn test_from_wrapper_accepts_empty_stages_when_every_flag_has_missing_deps() {
        let (flags, _, _) =
            FeatureFlagList::from_wrapper(Some(wrapper_with_empty_stages(json!([10, 20]))), 1)
                .expect("metadata listing every flag as missing a dependency should parse");
        assert_eq!(flags.len(), 2);
    }

    #[test]
    fn test_single_stage_places_all_flag_ids_in_one_stage() {
        let flags: Vec<FeatureFlag> = serde_json::from_value(json!([
            {"id": 10, "key": "a", "team_id": 1, "active": true, "deleted": false, "filters": {"groups": []}},
            {"id": 20, "key": "b", "team_id": 1, "active": true, "deleted": false, "filters": {"groups": []}}
        ]))
        .unwrap();

        let meta = EvaluationMetadata::single_stage(&flags);
        assert_eq!(meta.dependency_stages, vec![vec![10, 20]]);
        assert!(meta.flags_with_missing_deps.is_empty());
        // Each flag gets an empty dep set so flag_keys filtering works for independent flags
        assert_eq!(meta.transitive_deps.len(), 2);
        assert!(meta.transitive_deps[&10].is_empty());
        assert!(meta.transitive_deps[&20].is_empty());
    }

    #[test]
    fn test_single_stage_empty_flags() {
        let meta = EvaluationMetadata::single_stage(&[]);
        assert_eq!(meta.dependency_stages, vec![Vec::<i32>::new()]);
        assert!(meta.flags_with_missing_deps.is_empty());
        assert!(meta.transitive_deps.is_empty()); // no flags → genuinely empty
    }

    /// Golden fixture contract test: verifies that Rust can deserialize the hypercache
    /// format that Python produces. If this test fails, you've changed the cache schema
    /// in a way that breaks deserialization.
    ///
    /// See the expand-and-contract process in the HYPERCACHE CONTRACT comments at:
    ///   - products/feature_flags/backend/api/feature_flag.py (MinimalFeatureFlagSerializer)
    ///   - rust/feature-flags/src/flags/flag_models.rs (FeatureFlag struct)
    #[test]
    fn test_hypercache_contract() {
        let fixture = include_str!("../../tests/fixtures/hypercache_contract.json");
        let wrapper: HypercacheFlagsWrapper = serde_json::from_str(fixture).expect(
            "Failed to deserialize hypercache_contract.json as HypercacheFlagsWrapper. \
             The fixture file must be valid JSON matching the wrapper schema.",
        );

        let result = FeatureFlagList::from_wrapper(Some(wrapper), 99);
        let (flags, metadata, cohorts) = result.expect(
            "\n\
             ==============================================================================\n\
             WARNING: HYPERCACHE BOUNDARY CONTRACT VIOLATION\n\
             ==============================================================================\n\n\
             Rust failed to deserialize the golden fixture. This means a schema change\n\
             has broken the cache format that Python writes and Rust reads.\n\n\
             DO NOT just update the fixture or tweak the struct to make this test green.\n\
             The Python serializer is already writing this shape to production caches.\n\n\
             Before proceeding, consider:\n\
             \x20 1. Is the change backwards-compatible? (adding a new Optional/default\n\
             \x20    field is usually safe; renaming/removing a field is not)\n\
             \x20 2. Do you need a phased rollout? Schema changes must follow\n\
             \x20    expand-and-contract:\n\
             \x20    a. Add #[serde(default)] or #[serde(alias = ...)] in Rust, deploy\n\
             \x20    b. Change Python serializer, deploy, run warm_flags_cache\n\
             \x20    c. Remove compatibility shim in follow-up PR\n\
             \x20 3. Will the cache need re-warming? Old cached payloads will still\n\
             \x20    have the previous shape until they expire or are invalidated.\n\n\
             See: rust/feature-flags/tests/fixtures/hypercache_contract.json\n\
             ==============================================================================",
        );

        // Verify flags parsed correctly
        assert_eq!(flags.len(), 7, "Expected 7 flags in contract fixture");

        let served: LenientHypercacheFlagsWrapper = serde_json::from_str(fixture)
            .expect("The serving read failed to deserialize hypercache_contract.json");
        assert_eq!(
            served.into_wrapper(99).flags.len(),
            7,
            "The serving read skipped a flag that the contract fixture holds"
        );

        // Full flag with all optional fields
        let full_flag = &flags[0];
        assert_eq!(full_flag.key, "full-flag");
        assert_eq!(full_flag.id, 1);
        assert!(full_flag.active);
        assert!(!full_flag.deleted);
        assert_eq!(full_flag.ensure_experience_continuity, Some(true));
        assert_eq!(full_flag.version, Some(3));
        assert_eq!(full_flag.evaluation_runtime, Some("all".to_string()));
        assert_eq!(
            full_flag.bucketing_identifier,
            Some("device_id".to_string())
        );
        // evaluation_contexts is aliased to evaluation_tags in Rust
        let tags = full_flag
            .evaluation_tags
            .as_ref()
            .expect("evaluation_tags (aliased from evaluation_contexts) should be present");
        assert_eq!(
            tags,
            &vec!["docs-page".to_string(), "marketing-site".to_string()]
        );
        // Filter structure
        assert_eq!(full_flag.filters.groups.len(), 1);
        assert!(full_flag.filters.multivariate.is_some());
        assert_eq!(full_flag.filters.feature_enrollment, Some(true));
        assert!(full_flag.filters.holdout.is_some());
        let holdout = full_flag.filters.holdout.as_ref().unwrap();
        assert_eq!(holdout.id, 42);
        assert!((holdout.exclusion_percentage - 10.0).abs() < f64::EPSILON);

        // Minimal flag: verify defaults for absent optional fields
        let minimal_flag = &flags[1];
        assert_eq!(minimal_flag.key, "minimal-flag");
        assert_eq!(minimal_flag.ensure_experience_continuity, Some(false));
        assert!(minimal_flag.bucketing_identifier.is_none());
        assert!(minimal_flag.filters.multivariate.is_none());

        // Cohort flag: verify cohort property type parsed
        let cohort_flag = &flags[2];
        assert_eq!(cohort_flag.key, "cohort-flag");
        assert_eq!(cohort_flag.filters.groups.len(), 1);

        // Flag with dependency: verify dependency property type parsed
        let dep_flag = &flags[3];
        assert_eq!(dep_flag.key, "dependent-flag");
        assert_eq!(dep_flag.filters.groups.len(), 1);
        assert_eq!(dep_flag.version, Some(2));

        // Flag with missing dependency: verify it parses despite referencing a nonexistent flag
        let missing_dep_flag = &flags[4];
        assert_eq!(missing_dep_flag.key, "missing-dep-flag");
        assert_eq!(missing_dep_flag.filters.groups.len(), 1);

        // Referenced disabled flag: both writers keep it for the dependency below,
        // with filters blanked to the empty shape.
        let referenced_disabled = &flags[5];
        assert_eq!(referenced_disabled.key, "referenced-disabled-flag");
        assert!(!referenced_disabled.active);
        assert!(referenced_disabled.filters.groups.is_empty());

        // Its dependent: an active flag whose condition points at the disabled flag.
        let disabled_dependent = &flags[6];
        assert_eq!(disabled_dependent.key, "disabled-dependent-flag");
        assert_eq!(disabled_dependent.filters.groups.len(), 1);

        // Verify evaluation_metadata parsed correctly
        let meta = metadata;
        assert_eq!(meta.dependency_stages.len(), 2);
        assert_eq!(meta.dependency_stages[0], vec![1, 2, 3, 5, 6]);
        assert_eq!(meta.dependency_stages[1], vec![4, 7]);
        assert_eq!(meta.flags_with_missing_deps, vec![5]);
        assert_eq!(meta.transitive_deps.len(), 7);
        assert!(meta.transitive_deps[&4].contains(&2));
        assert!(meta.transitive_deps[&7].contains(&6));

        // Verify cohorts parsed correctly
        let cohorts = cohorts.expect("cohorts should be present in contract fixture");
        assert_eq!(cohorts.len(), 1);
        assert_eq!(cohorts[0].id, 100);
        assert_eq!(cohorts[0].name, Some("Test Cohort".to_string()));
        assert_eq!(cohorts[0].team_id, 99);
        assert!(!cohorts[0].deleted);

        assert!(
            cohorts[0].last_backfill_person_properties_at.is_some(),
            "last_backfill_person_properties_at should deserialize from ISO 8601 timestamp"
        );
        assert!(
            cohorts[0].last_realtime_cohort_calculation_at.is_some(),
            "last_realtime_cohort_calculation_at should deserialize from ISO 8601 timestamp"
        );

        // Verify cohort filters can parse into the expected CohortProperty structure
        let filters_value = cohorts[0]
            .filters
            .as_ref()
            .expect("cohort should have filters");
        let _parsed: crate::cohorts::cohort_models::CohortProperty =
            serde_json::from_value(filters_value.clone())
                .expect("Cohort filters should parse as CohortProperty");
    }

    #[test]
    fn test_prepared_flags_seal_compiles_regex_filters_only() {
        let flags = vec![FeatureFlag {
            id: 1,
            team_id: 1,
            name: None,
            key: "test_flag".to_string(),
            has_experiment: false,
            filters: FlagFilters {
                non_v1: None,
                groups: vec![FlagPropertyGroup {
                    properties: Some(vec![
                        PropertyFilter {
                            key: "email".to_string(),
                            value: Some(json!(r"^test@.*\.com$")),
                            operator: Some(OperatorType::Regex),
                            prop_type: PropertyType::Person,
                            group_type_index: None,
                            negation: None,
                            compiled_regex: None,
                            extra: Default::default(),
                        },
                        PropertyFilter {
                            key: "name".to_string(),
                            value: Some(json!("Alice")),
                            operator: Some(OperatorType::Exact),
                            prop_type: PropertyType::Person,
                            group_type_index: None,
                            negation: None,
                            compiled_regex: None,
                            extra: Default::default(),
                        },
                    ]),
                    rollout_percentage: Some(100.0),
                    ..Default::default()
                }],
                multivariate: None,
                aggregation_group_type_index: None,
                payloads: None,
                feature_enrollment: None,
                holdout: None,
                early_exit: None,
                extra: Default::default(),
            },
            active: true,
            deleted: false,
            ensure_experience_continuity: None,
            version: None,
            evaluation_runtime: None,
            evaluation_tags: None,
            bucketing_identifier: None,
        }];

        let sealed = PreparedFlags::seal(flags);

        let props = sealed[0].filters.groups[0].properties.as_ref().unwrap();
        assert!(
            matches!(
                props[0].compiled_regex,
                Some(crate::properties::property_models::CompiledRegex::Compiled(
                    _
                ))
            ),
            "Regex filter should have compiled regex"
        );
        assert!(
            props[1].compiled_regex.is_none(),
            "Exact filter should NOT have compiled regex"
        );
    }

    // =========================================================================
    // Tests for evaluation_contexts JSON key (renamed from evaluation_tags)
    // =========================================================================

    #[test]
    fn test_deserialize_flag_with_evaluation_contexts() {
        // Cache entries use `evaluation_contexts` key (renamed from `evaluation_tags` in PR #52186)
        let data = json!({
            "id": 1,
            "key": "test_flag",
            "team_id": 123,
            "active": true,
            "deleted": false,
            "filters": { "groups": [] },
            "evaluation_contexts": ["app", "dashboard"]
        });

        let flag: FeatureFlag =
            serde_json::from_value(data).expect("Should deserialize with evaluation_contexts");
        assert_eq!(flag.key, "test_flag");
        // Rust field is still named `evaluation_tags` for internal compatibility
        let tags = flag.evaluation_tags.expect("Should have evaluation_tags");
        assert_eq!(tags.len(), 2);
        assert!(tags.contains(&"app".to_string()));
        assert!(tags.contains(&"dashboard".to_string()));
    }

    #[test]
    fn test_deserialize_flag_without_evaluation_contexts() {
        let data = json!({
            "id": 2,
            "key": "no_contexts_flag",
            "team_id": 123,
            "active": true,
            "deleted": false,
            "filters": { "groups": [] }
        });

        let flag: FeatureFlag =
            serde_json::from_value(data).expect("Should deserialize without evaluation_contexts");
        assert_eq!(flag.key, "no_contexts_flag");
        assert!(flag.evaluation_tags.is_none());
    }

    #[test]
    fn test_serialize_flag_uses_evaluation_contexts_key() {
        let flag = FeatureFlag {
            id: 3,
            team_id: 123,
            name: Some("Serialization Test".to_string()),
            key: "serialize_test".to_string(),
            has_experiment: false,
            filters: FlagFilters::default(),
            deleted: false,
            active: true,
            ensure_experience_continuity: None,
            version: None,
            evaluation_runtime: None,
            evaluation_tags: Some(vec!["context-1".to_string(), "context-2".to_string()]),
            bucketing_identifier: None,
        };

        let json_str = serde_json::to_string(&flag).expect("Should serialize");
        // Rust field `evaluation_tags` serializes to JSON key `evaluation_contexts`
        assert!(
            json_str.contains("evaluation_contexts"),
            "Should use evaluation_contexts key when serializing"
        );
        assert!(
            !json_str.contains("evaluation_tags"),
            "Should NOT use evaluation_tags key when serializing"
        );
    }
}