posthog-ruby 3.28.4 → 3.29.0

data/lib/posthog/feature_flags.rb

@@ -9,19 +9,12 @@ require 'posthog/defaults'
 require 'posthog/backoff_policy'
 require 'posthog/feature_flag'
 require 'posthog/flag_definition_cache'
+require 'posthog/unresolved_flag_reason'
+require 'posthog/flag_evaluation_errors'
 require 'digest'
+require 'set'
 
 module PostHog
-  class InconclusiveMatchError < StandardError
-  end
-
-  # RequiresServerEvaluation is raised when feature flag evaluation requires
-  # server-side data that is not available locally (e.g., static cohorts,
-  # experience continuity). This error should propagate immediately to trigger
-  # API fallback, unlike InconclusiveMatchError which allows trying other conditions.
-  class RequiresServerEvaluation < StandardError
-  end
-
   # Polls and evaluates feature flag definitions for {PostHog::Client}.
   #
   # @api private
@@ -29,6 +22,22 @@ module PostHog
     include PostHog::Logging
     include PostHog::Utils
 
+    # When several causes apply to one flag, the spec reports the first reason in this order, so
+    # every SDK picks the same reason whatever order it inspects the filters in.
+    UNRESOLVED_REASON_PRECEDENCE = [
+      UnresolvedFlagReason::EXPERIENCE_CONTINUITY,
+      UnresolvedFlagReason::UNSUPPORTED_DEFINITION,
+      UnresolvedFlagReason::UNRESOLVED_DEPENDENCY,
+      UnresolvedFlagReason::MISSING_CONTEXT
+    ].freeze
+
+    # Operator groups that share one branch in both match_property_value and assert_filter_supported,
+    # so the load-time check stays in step with evaluation.
+    REGEX_OPERATORS = %w[regex not_regex].freeze
+    NUMERIC_OPERATORS = %w[gt gte lt lte].freeze
+    DATE_OPERATORS = %w[is_date_before is_date_after].freeze
+    SEMVER_COMPARISON_OPERATORS = %w[semver_eq semver_neq semver_gt semver_gte semver_lt semver_lte].freeze
+
     # @param polling_interval [Integer, nil] Seconds between local feature flag definition polls.
     #   Defaults to {Defaults::FeatureFlags::POLLING_INTERVAL_SECONDS}.
     # @param secret_key [String, nil] Credential used to fetch local evaluation definitions. Accepts either a
@@ -86,6 +95,8 @@ module PostHog
       # from the top-level `minimal_flag_called_events` key of the local
       # evaluation definitions payload. false when the server does not send it.
       @minimal_flag_called_events = false
+      # Definition fingerprint per flag key already warned about as never locally resolvable.
+      @warned_unresolvable_flags = {}
       @definition_snapshot = Concurrent::AtomicReference.new({
         flags: @feature_flags, flags_by_key: @feature_flags_by_key,
         group_type_mapping: @group_type_mapping, cohorts: @cohorts,
@@ -485,6 +496,12 @@ module PostHog
 
     # Class methods
 
+    def self.pick_unresolved_reason(current, reason)
+      return reason if current.nil?
+
+      UNRESOLVED_REASON_PRECEDENCE.index(reason) < UNRESOLVED_REASON_PRECEDENCE.index(current) ? reason : current
+    end
+
     def self.compare(lhs, rhs, operator)
       case operator
       when 'gt'
@@ -547,33 +564,36 @@ module PostHog
     end
 
     # Parse a single semver numeric identifier, rejecting empty, non-digit, or
-    # leading-zero values per semver 2.0.0 §2.
-    def self.parse_semver_numeric(part)
-      raise InconclusiveMatchError, 'Invalid semver format' if part.nil? || part.empty? || part !~ /^\d+$/
+    # leading-zero values per semver 2.0.0 §2. `reason` names the owner of the value:
+    # UNSUPPORTED_DEFINITION for a filter value, MISSING_CONTEXT for a value the call passed.
+    def self.parse_semver_numeric(part, reason: UnresolvedFlagReason::UNSUPPORTED_DEFINITION)
+      if part.nil? || part.empty? || part !~ /^\d+$/
+        raise InconclusiveMatchError.new('Invalid semver format', reason: reason)
+      end
       # Semver 2.0.0 §2: numeric identifiers MUST NOT include leading zeros.
-      raise InconclusiveMatchError, 'Invalid semver format' if part.length > 1 && part[0] == '0'
+      raise InconclusiveMatchError.new('Invalid semver format', reason: reason) if part.length > 1 && part[0] == '0'
 
       part.to_i
     end
 
     # Parse a semver string into a comparable [major, minor, patch] integer array.
     # Handles v-prefix, whitespace, pre-release suffixes. Defaults missing components to 0.
-    def self.parse_semver(value)
-      raise InconclusiveMatchError, 'Invalid semver format' if value.nil?
+    def self.parse_semver(value, reason: UnresolvedFlagReason::UNSUPPORTED_DEFINITION)
+      raise InconclusiveMatchError.new('Invalid semver format', reason: reason) if value.nil?
 
       text = value.to_s.strip.sub(/^[vV]/, '')
 
-      raise InconclusiveMatchError, 'Invalid semver format' if text.empty?
+      raise InconclusiveMatchError.new('Invalid semver format', reason: reason) if text.empty?
 
       # Strip pre-release and build metadata suffixes
       text = text.split('-')[0].split('+')[0]
       parts = text.split('.')
 
-      raise InconclusiveMatchError, 'Invalid semver format' if parts.empty? || parts[0].to_s.empty?
+      raise InconclusiveMatchError.new('Invalid semver format', reason: reason) if parts.empty? || parts[0].to_s.empty?
 
-      major = parse_semver_numeric(parts[0])
-      minor = parts.length > 1 ? parse_semver_numeric(parts[1]) : 0
-      patch = parts.length > 2 ? parse_semver_numeric(parts[2]) : 0
+      major = parse_semver_numeric(parts[0], reason: reason)
+      minor = parts.length > 1 ? parse_semver_numeric(parts[1], reason: reason) : 0
+      patch = parts.length > 2 ? parse_semver_numeric(parts[2], reason: reason) : 0
 
       [major, minor, patch]
     end
@@ -628,12 +648,16 @@ module PostHog
       cleaned = value.to_s.strip.sub(/^[vV]/, '').gsub('*', '').chomp('.')
       parts = cleaned.split('.').reject(&:empty?)
 
-      raise InconclusiveMatchError, 'Invalid semver wildcard format' if parts.empty?
+      if parts.empty?
+        raise InconclusiveMatchError.new('Invalid semver wildcard format',
+                                         reason: UnresolvedFlagReason::UNSUPPORTED_DEFINITION)
+      end
 
       numeric = parts.map do |part|
         parse_semver_numeric(part)
       rescue InconclusiveMatchError
-        raise InconclusiveMatchError, 'Invalid semver wildcard format'
+        raise InconclusiveMatchError.new('Invalid semver wildcard format',
+                                         reason: UnresolvedFlagReason::UNSUPPORTED_DEFINITION)
       end
 
       major = numeric[0]
@@ -719,12 +743,23 @@ module PostHog
                             property_matching_version: property_matching_version)
       end
 
+      begin
+        match_property_value(property, property_values, property_matching_version)
+      rescue InconclusiveMatchError => e
+        # An unusable filter outranks missing context, so check the filter before blaming the context.
+        assert_filter_supported(property) if e.reason == UnresolvedFlagReason::MISSING_CONTEXT
+        raise
+      end
+    end
+
+    def self.match_property_value(property, property_values, property_matching_version)
       key = property[:key].to_sym
       value = property[:value]
       operator = property[:operator] || 'exact'
 
       if !property_values.key?(key)
-        raise InconclusiveMatchError, "Property #{key} not found in property_values"
+        raise InconclusiveMatchError.new("Property #{key} not found in property_values",
+                                         reason: UnresolvedFlagReason::MISSING_CONTEXT)
       elsif operator == 'is_not_set'
         return false
       end
@@ -749,34 +784,32 @@ module PostHog
         string_operand(override_value).downcase(:ascii).end_with?(value.to_s.downcase(:ascii))
       when 'not_ends_with'
         !string_operand(override_value).downcase(:ascii).end_with?(value.to_s.downcase(:ascii))
-      when 'regex'
-        PostHog::Utils.is_valid_regex(value.to_s) && !Regexp.new(value.to_s).match(string_operand(override_value)).nil?
-      when 'not_regex'
-        PostHog::Utils.is_valid_regex(value.to_s) && Regexp.new(value.to_s).match(string_operand(override_value)).nil?
-      when 'gt', 'gte', 'lt', 'lte'
-        parsed_value = parse_finite_number(value)
-        raise InconclusiveMatchError, 'Invalid numeric condition' if parsed_value.nil?
+      when *REGEX_OPERATORS
+        matched = match_regex(value.to_s, string_operand(override_value))
+        return false if matched.nil?
 
+        operator == 'regex' ? matched : !matched
+      when *NUMERIC_OPERATORS
+        parsed_value = parse_numeric_filter(value)
         parsed_override = parse_finite_number(override_value)
         return false if parsed_override.nil?
 
         compare(parsed_override, parsed_value, operator)
-      when 'is_date_before', 'is_date_after'
-        override_date = PostHog::Utils.convert_to_datetime(override_value.to_s)
-        parsed_date = relative_date_parse_for_feature_flag_matching(value.to_s)
-
-        parsed_date = PostHog::Utils.convert_to_datetime(value.to_s) if parsed_date.nil?
-
-        raise InconclusiveMatchError, 'Invalid date format' unless parsed_date
+      when *DATE_OPERATORS
+        # Parses the filter before the context, so a bad filter reports unsupported_definition even
+        # when the context value is bad too.
+        parsed_date = parse_date_filter(value)
+        override_date = PostHog::Utils.convert_to_datetime(override_value.to_s,
+                                                           reason: UnresolvedFlagReason::MISSING_CONTEXT)
 
         if operator == 'is_date_before'
           override_date < parsed_date
         elsif operator == 'is_date_after'
           override_date > parsed_date
         end
-      when 'semver_eq', 'semver_neq', 'semver_gt', 'semver_gte', 'semver_lt', 'semver_lte'
-        override_parsed = parse_semver(override_value)
-        flag_parsed = parse_semver(value)
+      when *SEMVER_COMPARISON_OPERATORS
+        flag_parsed = parse_semver(value, reason: UnresolvedFlagReason::UNSUPPORTED_DEFINITION)
+        override_parsed = parse_semver(override_value, reason: UnresolvedFlagReason::MISSING_CONTEXT)
 
         case operator
         when 'semver_eq'
@@ -793,22 +826,227 @@ module PostHog
           (override_parsed <=> flag_parsed) <= 0
         end
       when 'semver_tilde'
-        override_parsed = parse_semver(override_value)
         lower, upper = semver_tilde_bounds(value)
+        override_parsed = parse_semver(override_value, reason: UnresolvedFlagReason::MISSING_CONTEXT)
         (override_parsed <=> lower) >= 0 && (override_parsed <=> upper) == -1
       when 'semver_caret'
-        override_parsed = parse_semver(override_value)
         lower, upper = semver_caret_bounds(value)
+        override_parsed = parse_semver(override_value, reason: UnresolvedFlagReason::MISSING_CONTEXT)
         (override_parsed <=> lower) >= 0 && (override_parsed <=> upper) == -1
       when 'semver_wildcard'
-        override_parsed = parse_semver(override_value)
         lower, upper = semver_wildcard_bounds(value)
+        override_parsed = parse_semver(override_value, reason: UnresolvedFlagReason::MISSING_CONTEXT)
         (override_parsed <=> lower) >= 0 && (override_parsed <=> upper) == -1
       else
-        raise InconclusiveMatchError, "Unknown operator: #{operator}"
+        raise InconclusiveMatchError.new("Unknown operator: #{operator}",
+                                         reason: UnresolvedFlagReason::UNSUPPORTED_DEFINITION)
+      end
+    end
+    private_class_method :match_property_value
+
+    # Raises an unsupported_definition error when local evaluation cannot use the filter, whatever
+    # the call passes: an unknown operator, or a filter value that the operator cannot parse.
+    def self.assert_filter_supported(property)
+      value = property[:value]
+      case property[:operator] || 'exact'
+      when 'exact', 'is_not', 'is_set', 'is_not_set', 'icontains', 'not_icontains', 'starts_with',
+           'not_starts_with', 'ends_with', 'not_ends_with'
+        nil
+      when *REGEX_OPERATORS
+        # An empty input is the most portable one, so this raises only for a pattern that needs the
+        # server whatever the value. Compile without matching, so a server-supplied pattern never runs
+        # while definitions load.
+        pattern = value.to_s
+        compile_regex(pattern, '') unless pattern.empty?
+      when *NUMERIC_OPERATORS
+        parse_numeric_filter(value)
+      when *DATE_OPERATORS
+        parse_date_filter(value)
+      when *SEMVER_COMPARISON_OPERATORS
+        parse_semver(value, reason: UnresolvedFlagReason::UNSUPPORTED_DEFINITION)
+      when 'semver_tilde'
+        semver_tilde_bounds(value)
+      when 'semver_caret'
+        semver_caret_bounds(value)
+      when 'semver_wildcard'
+        semver_wildcard_bounds(value)
+      else
+        raise InconclusiveMatchError.new("Unknown operator: #{property[:operator]}",
+                                         reason: UnresolvedFlagReason::UNSUPPORTED_DEFINITION)
       end
     end
 
+    def self.parse_numeric_filter(value)
+      parsed_value = parse_finite_number(value)
+      if parsed_value.nil?
+        raise InconclusiveMatchError.new('Invalid numeric condition',
+                                         reason: UnresolvedFlagReason::UNSUPPORTED_DEFINITION)
+      end
+
+      parsed_value
+    end
+    private_class_method :parse_numeric_filter
+
+    def self.parse_date_filter(value)
+      parsed_date = relative_date_parse_for_feature_flag_matching(value.to_s) ||
+                    PostHog::Utils.convert_to_datetime(value.to_s,
+                                                       reason: UnresolvedFlagReason::UNSUPPORTED_DEFINITION)
+      return parsed_date if parsed_date
+
+      raise InconclusiveMatchError.new('Invalid date format', reason: UnresolvedFlagReason::UNSUPPORTED_DEFINITION)
+    end
+    private_class_method :parse_date_filter
+
+    def self.match_regex(pattern, value)
+      return true if pattern.empty?
+
+      regex = compile_regex(pattern, value)
+      return nil if regex.nil?
+
+      !regex.match(value).nil?
+    rescue InconclusiveMatchError
+      raise
+    rescue StandardError
+      raise InconclusiveMatchError.new('Regex execution requires server evaluation',
+                                       reason: UnresolvedFlagReason::UNSUPPORTED_DEFINITION)
+    end
+    private_class_method :match_regex
+
+    # Returns nil for a pattern that Ruby cannot compile.
+    def self.compile_regex(pattern, value)
+      unless portable_regex?(pattern, value)
+        raise InconclusiveMatchError.new('Regex compatibility requires server evaluation',
+                                         reason: UnresolvedFlagReason::UNSUPPORTED_DEFINITION)
+      end
+
+      Regexp.new(pattern)
+    rescue RegexpError => e
+      # Ruby's repeat-count limit is smaller than the service's syntax limit.
+      if e.message.include?('too big')
+        raise InconclusiveMatchError.new('Regex compilation requires server evaluation',
+                                         reason: UnresolvedFlagReason::UNSUPPORTED_DEFINITION)
+      end
+
+      nil
+    rescue InconclusiveMatchError
+      raise
+    rescue StandardError
+      # For example, a pattern with an invalid byte sequence.
+      raise InconclusiveMatchError.new('Regex compatibility requires server evaluation',
+                                       reason: UnresolvedFlagReason::UNSUPPORTED_DEFINITION)
+    end
+    private_class_method :compile_regex
+
+    # Native compilation alone cannot establish compatibility with the flags service's Rust engine.
+    # Keep ordinary scalar matching local, but defer engine-specific syntax and backtracking assertions.
+    def self.portable_regex?(pattern, value)
+      # Ruby string offsets repeatedly traverse multibyte prefixes; tokenize once for constant-time lookahead.
+      characters = pattern.chars
+      ascii_input = value.ascii_only?
+      newline_input = value.include?("\n")
+      class_start = nil
+      previous_token = nil
+      index = 0
+      while index < characters.length
+        character = characters[index]
+        if character == '\\'
+          index += 1
+          escaped = characters[index]
+          break if escaped.nil?
+
+          if escaped == 'x'
+            hex = characters[index + 1, 2]&.join
+            return false unless hex&.match?(/\A[0-9a-fA-F]{2}\z/) && hex.to_i(16) < 128
+
+            index += 2
+          elsif 'dDsSwW'.include?(escaped)
+            # Ruby shorthand classes are ASCII-oriented, unlike the service's Unicode classes.
+            return false unless ascii_input
+          elsif class_start.nil?
+            return false if 'bB'.include?(escaped) # Even short ASCII inputs can exceed the service's boundary budget.
+            return false unless 'Azfnrtv'.include?(escaped) || escaped.match?(/[\x20-\x2f:;=?@\x5b-\x60\x7b-\x7e]/)
+          else
+            return false unless 'bfnrtv\\.^$|?*+(){}[]-'.include?(escaped)
+          end
+          previous_token = class_start.nil? && %w[A z].include?(escaped) ? :assertion : :literal
+        elsif character == '['
+          return false unless class_start.nil?
+
+          class_start = index
+        elsif character == ']' && class_start
+          content_start = class_start + (characters[class_start + 1] == '^' ? 2 : 1)
+          return false if index == content_start
+
+          class_start = nil
+          previous_token = :literal
+        elsif class_start
+          return false if %w[&& -- ~~].include?(characters[index, 2].join)
+        else
+          token = character
+          if character == '(' && characters[index + 1] == '?'
+            return false unless characters[index + 2] == ':'
+
+            index += 2
+          elsif character == '{'
+            repetition_end = regex_repetition_end(characters, index)
+            return false unless repetition_end && ![nil, '|', '('].include?(previous_token)
+            return false if %i[assertion empty_group repetition lazy_repetition
+                               bounded_repetition].include?(previous_token)
+
+            index = repetition_end
+            token = :bounded_repetition
+          elsif '*+?'.include?(character)
+            # A leading quantifier is invalid in both engines, regardless of the remaining syntax.
+            return true if [nil, '|', '('].include?(previous_token)
+            return false if %i[assertion empty_group].include?(previous_token)
+
+            repeated = %i[repetition lazy_repetition bounded_repetition].include?(previous_token)
+            return false if repeated && !(character == '?' && previous_token == :repetition)
+
+            token = :repetition
+            token = :lazy_repetition if repeated
+          elsif '^$'.include?(character)
+            # Ruby ^/$ are line anchors even without a multiline option; Rust's defaults are absolute.
+            return false if newline_input
+
+            token = :assertion
+          elsif character == ')' && ['(', :empty_group].include?(previous_token)
+            token = :empty_group
+          end
+          previous_token = token
+        end
+        index += 1
+      end
+      true
+    end
+    private_class_method :portable_regex?
+
+    def self.regex_repetition_end(characters, index)
+      index += 1
+      return nil unless characters[index]&.match?(/\A[0-9]\z/)
+
+      count = 0
+      comma = false
+      while index < characters.length
+        character = characters[index]
+        digit = character.ord - 48
+        if digit.between?(0, 9)
+          count = (count * 10) + digit
+          return nil if count > 0xffffffff
+        elsif character == ',' && !comma
+          comma = true
+          count = 0
+        elsif character == '}'
+          return index
+        else
+          return nil
+        end
+        index += 1
+      end
+      nil
+    end
+    private_class_method :regex_repetition_end
+
     def self.match_cohort(property, property_values, cohort_properties, property_matching_version: 1)
       # Cohort properties are in the form of property groups like this:
       # {
@@ -823,8 +1061,10 @@ module PostHog
       property_group = find_cohort_property(cohort_properties, cohort_id)
 
       unless property_group
-        raise RequiresServerEvaluation,
-              "cohort #{cohort_id} not found in local cohorts - likely a static cohort that requires server evaluation"
+        raise RequiresServerEvaluation.new(
+          "cohort #{cohort_id} not found in local cohorts - likely a static cohort that requires server evaluation",
+          reason: UnresolvedFlagReason::UNSUPPORTED_DEFINITION
+        )
       end
 
       match_property_group(property_group, property_values, cohort_properties,
@@ -840,11 +1080,17 @@ module PostHog
       return true if properties.nil? || properties.empty?
 
       if nested_property_group?(properties)
-        match_nested_property_group(properties, group_type, property_values, cohort_properties,
-                                    property_matching_version: property_matching_version)
+        property_group_items_match?(properties, group_type) do |group|
+          match_property_group(group, property_values, cohort_properties,
+                               property_matching_version: property_matching_version)
+        end
       else
-        match_regular_property_group(properties, group_type, property_values, cohort_properties,
-                                     property_matching_version: property_matching_version)
+        property_group_items_match?(properties, group_type) do |prop|
+          PostHog::Utils.symbolize_keys!(prop)
+          matches = match_property(prop, property_values, cohort_properties,
+                                   property_matching_version: property_matching_version)
+          prop[:negation] ? !matches : matches
+        end
       end
     end
 
@@ -869,59 +1115,32 @@ module PostHog
       first_property.key?(:values) || first_property.key?('values')
     end
 
-    def self.match_nested_property_group(properties, group_type, property_values, cohort_properties,
-                                         property_matching_version: 1)
-      case group_type
-      when 'AND'
-        properties.each do |property|
-          return false unless match_property_group(property, property_values, cohort_properties,
-                                                   property_matching_version: property_matching_version)
-        end
-        true
-      when 'OR'
-        properties.each do |property|
-          return true if match_property_group(property, property_values, cohort_properties,
-                                              property_matching_version: property_matching_version)
-        end
-        false
-      else
-        raise InconclusiveMatchError, "Unknown property group type: #{group_type}"
+    # Combines the items of a cohort property group with AND or OR. The block evaluates one item.
+    # RequiresServerEvaluation is not an InconclusiveMatchError, so it propagates at once.
+    def self.property_group_items_match?(items, group_type)
+      unless %w[AND OR].include?(group_type)
+        raise InconclusiveMatchError.new("Unknown property group type: #{group_type}",
+                                         reason: UnresolvedFlagReason::UNSUPPORTED_DEFINITION)
       end
-    end
 
-    def self.match_regular_property_group(properties, group_type, property_values, cohort_properties,
-                                          property_matching_version: 1)
-      # Validate group type upfront
-      raise InconclusiveMatchError, "Unknown property group type: #{group_type}" unless %w[AND OR].include?(group_type)
-
-      error_matching_locally = false
-
-      properties.each do |prop|
-        PostHog::Utils.symbolize_keys!(prop)
-
-        matches = match_property(prop, property_values, cohort_properties,
-                                 property_matching_version: property_matching_version)
-
-        negated = prop[:negation] || false
-        final_result = negated ? !matches : matches
-
-        # Short-circuit based on group type
+      inconclusive_reason = nil
+      items.each do |item|
+        matches = yield(item)
         if group_type == 'AND'
-          return false unless final_result
-        elsif final_result # group_type == 'OR'
+          return false unless matches
+        elsif matches
           return true
         end
-      rescue RequiresServerEvaluation
-        # Immediately propagate - this condition requires server-side data
-        raise
       rescue InconclusiveMatchError => e
-        PostHog::Logging.logger&.debug("Failed to compute property #{prop} locally: #{e}")
-        error_matching_locally = true
+        PostHog::Logging.logger&.debug("Failed to compute property #{item} locally: #{e}")
+        inconclusive_reason = pick_unresolved_reason(inconclusive_reason, e.reason)
       end
 
-      raise InconclusiveMatchError, "can't match cohort without a given cohort property value" if error_matching_locally
+      unless inconclusive_reason.nil?
+        raise InconclusiveMatchError.new("can't match cohort without a given cohort property value",
+                                         reason: inconclusive_reason)
+      end
 
-      # If we reach here, return default based on group type
       group_type == 'AND'
     end
 
@@ -935,48 +1154,38 @@ module PostHog
     # @return [Boolean] True if all dependencies in the chain evaluate to true, false otherwise
     def evaluate_flag_dependency(property, evaluation_cache, distinct_id, properties, cohort_properties,
                                  snapshot: _evaluation_snapshot)
-      if property[:operator] != 'flag_evaluates_to'
-        # Should never happen, but just in case
-        raise InconclusiveMatchError, "Operator #{property[:operator]} not supported for flag dependencies"
-      end
-
       if snapshot[:flags_by_key].nil? || evaluation_cache.nil?
         # Cannot evaluate flag dependencies without required context
-        raise InconclusiveMatchError,
-              "Cannot evaluate flag dependency on '#{property[:key] || 'unknown'}' " \
-              'without feature flags loaded or evaluation_cache'
+        raise InconclusiveMatchError.new(
+          "Cannot evaluate flag dependency on '#{property[:key] || 'unknown'}' " \
+          'without feature flags loaded or evaluation_cache',
+          reason: UnresolvedFlagReason::UNSUPPORTED_DEFINITION
+        )
       end
 
-      # Check if dependency_chain is present - it should always be provided for flag dependencies
-      unless property.key?(:dependency_chain)
-        # Missing dependency_chain indicates malformed server data
-        raise InconclusiveMatchError,
-              "Flag dependency property for '#{property[:key] || 'unknown'}' " \
-              "is missing required 'dependency_chain' field"
+      # A dependency with no definition outranks one that is only inconclusive, so this checks the whole
+      # chain before evaluating any of it. Nothing is cached for it, so a later lookup reports the same.
+      definition_error = FeatureFlagsPoller.flag_dependency_definition_error(property, snapshot[:flags_by_key])
+      unless definition_error.nil?
+        raise InconclusiveMatchError.new(definition_error, reason: UnresolvedFlagReason::UNSUPPORTED_DEFINITION)
       end
 
       dependency_chain = property[:dependency_chain]
 
-      # Handle circular dependency (empty chain means circular)
-      if dependency_chain.empty?
-        PostHog::Logging.logger&.debug("Circular dependency detected for flag: #{property[:key]}")
-        raise InconclusiveMatchError,
-              "Circular dependency detected for flag '#{property[:key] || 'unknown'}'"
-      end
-
       # Evaluate all dependencies in the chain order
       dependency_chain.each do |dep_flag_key|
         unless evaluation_cache.key?(dep_flag_key)
           # Need to evaluate this dependency first
           dep_flag = snapshot[:flags_by_key][dep_flag_key]
-          if dep_flag.nil?
-            # Missing flag dependency - cannot evaluate locally
-            evaluation_cache[dep_flag_key] = nil
-            raise InconclusiveMatchError,
-                  "Cannot evaluate flag dependency '#{dep_flag_key}' - flag not found in local flags"
-          elsif !dep_flag[:active]
+          if !dep_flag[:active]
             # Check if the flag is active (same check as in _compute_flag_locally)
             evaluation_cache[dep_flag_key] = false
+          elsif dep_flag[:ensure_experience_continuity]
+            evaluation_cache[dep_flag_key] = nil
+            raise InconclusiveMatchError.new(
+              "Cannot evaluate flag dependency '#{dep_flag_key}' - flag has experience continuity enabled",
+              reason: UnresolvedFlagReason::UNRESOLVED_DEPENDENCY
+            )
           else
             # Recursively evaluate the dependency using existing instance method
             begin
@@ -989,11 +1198,16 @@ module PostHog
                 snapshot: snapshot
               )
               evaluation_cache[dep_flag_key] = dep_result
+            rescue RequiresServerEvaluation => e
+              # The dependent flag needs the server too. Nothing is cached, so a later lookup of this
+              # dependency also requires the server instead of reading it as merely inconclusive.
+              raise RequiresServerEvaluation.new("Cannot evaluate flag dependency '#{dep_flag_key}': #{e.message}",
+                                                 reason: UnresolvedFlagReason::UNRESOLVED_DEPENDENCY)
             rescue InconclusiveMatchError => e
               # If we can't evaluate a dependency, store nil and propagate the error
               evaluation_cache[dep_flag_key] = nil
-              raise InconclusiveMatchError,
-                    "Cannot evaluate flag dependency '#{dep_flag_key}': #{e.message}"
+              raise InconclusiveMatchError.new("Cannot evaluate flag dependency '#{dep_flag_key}': #{e.message}",
+                                               reason: UnresolvedFlagReason::UNRESOLVED_DEPENDENCY)
             end
           end
         end
@@ -1002,8 +1216,8 @@ module PostHog
         cached_result = evaluation_cache[dep_flag_key]
         if cached_result.nil?
           # Previously inconclusive - raise error again
-          raise InconclusiveMatchError,
-                "Flag dependency '#{dep_flag_key}' was previously inconclusive"
+          raise InconclusiveMatchError.new("Flag dependency '#{dep_flag_key}' was previously inconclusive",
+                                           reason: UnresolvedFlagReason::UNRESOLVED_DEPENDENCY)
         elsif !cached_result
           # Definitive False result - dependency failed
           return false
@@ -1049,8 +1263,96 @@ module PostHog
       false
     end
 
+    # The unresolved reason that comes from the flag's definition alone, so it is known when
+    # definitions load. Matches the reason local evaluation reports for the same cause.
+    def self.definition_unresolved_reason(flag, flags_by_key, cohorts, group_type_mapping)
+      return nil unless flag[:active]
+      return UnresolvedFlagReason::EXPERIENCE_CONTINUITY if flag[:ensure_experience_continuity]
+
+      flag_filters = flag[:filters] || {}
+      aggregation = flag_filters[:aggregation_group_type_index]
+      if !aggregation.nil? && group_type_mapping[aggregation.to_s.to_sym].nil?
+        return UnresolvedFlagReason::UNSUPPORTED_DEFINITION
+      end
+
+      unsupported = (flag_filters[:groups] || []).any? do |condition|
+        (condition[:properties] || []).any? do |property|
+          unsupported_property?(property, flags_by_key, cohorts, Set.new)
+        end
+      end
+      unsupported ? UnresolvedFlagReason::UNSUPPORTED_DEFINITION : nil
+    end
+
+    # Why a flag dependency filter can never evaluate locally, whatever the call passes, or nil.
+    # Evaluation and the load-time warning both use it, so the warning matches the reason evaluation reports.
+    def self.flag_dependency_definition_error(property, flags_by_key)
+      operator = property[:operator]
+      return "Operator #{operator} not supported for flag dependencies" if operator != 'flag_evaluates_to'
+
+      key = property[:key] || 'unknown'
+      dependency_chain = property[:dependency_chain]
+      unless property.key?(:dependency_chain)
+        return "Flag dependency property for '#{key}' is missing required 'dependency_chain' field"
+      end
+      unless dependency_chain.is_a?(Array)
+        return "Flag dependency property for '#{key}' has an invalid 'dependency_chain' field"
+      end
+      return "Circular dependency detected for flag '#{key}'" if dependency_chain.empty?
+
+      missing_dependency = dependency_chain.find { |dep_flag_key| flags_by_key[dep_flag_key].nil? }
+      return nil if missing_dependency.nil?
+
+      "Cannot evaluate flag dependency '#{missing_dependency}' - flag not found in local flags"
+    end
+
+    def self.unsupported_property?(property, flags_by_key, cohorts, visited_cohort_ids)
+      case property[:type]
+      when 'flag'
+        !flag_dependency_definition_error(property, flags_by_key).nil?
+      when 'cohort'
+        cohort_id = property[:value].to_s
+        property_group = find_cohort_property(cohorts, cohort_id)
+        return true if property_group.nil?
+        return false unless visited_cohort_ids.add?(cohort_id)
+
+        unsupported_property_group?(property_group, flags_by_key, cohorts, visited_cohort_ids)
+      else
+        unsupported_filter?(property)
+      end
+    end
+
+    def self.unsupported_property_group?(property_group, flags_by_key, cohorts, visited_cohort_ids)
+      properties = extract_value(property_group, :values)
+      return false if properties.nil? || properties.empty?
+      return true unless %w[AND OR].include?(extract_value(property_group, :type))
+
+      if nested_property_group?(properties)
+        return properties.any? do |group|
+          unsupported_property_group?(group, flags_by_key, cohorts, visited_cohort_ids)
+        end
+      end
+
+      properties.any? do |property|
+        filter = PostHog::Utils.symbolize_keys(property)
+        if filter[:type] == 'cohort'
+          unsupported_property?(filter, flags_by_key, cohorts, visited_cohort_ids)
+        else
+          # Like evaluation, a cohort group checks a flag filter as an ordinary property.
+          unsupported_filter?(filter)
+        end
+      end
+    end
+
+    def self.unsupported_filter?(property)
+      assert_filter_supported(property)
+      false
+    rescue InconclusiveMatchError
+      true
+    end
+
     private_class_method :extract_value, :find_cohort_property, :nested_property_group?,
-                         :match_nested_property_group, :match_regular_property_group
+                         :property_group_items_match?, :assert_filter_supported,
+                         :unsupported_property?, :unsupported_property_group?, :unsupported_filter?
 
     # Publish/capture all matching state together so a poll cannot switch semantics
     # (or dependency/cohort definitions) halfway through one local evaluation.
@@ -1060,10 +1362,14 @@ module PostHog
 
     def _compute_flag_locally(flag, distinct_id, groups = {}, person_properties = {}, group_properties = {},
                               snapshot: _evaluation_snapshot)
-      raise RequiresServerEvaluation, 'Flag has experience continuity enabled' if flag[:ensure_experience_continuity]
-
+      # An inactive flag is false whatever its experience continuity setting.
       return false unless flag[:active]
 
+      if flag[:ensure_experience_continuity]
+        raise RequiresServerEvaluation.new('Flag has experience continuity enabled',
+                                           reason: UnresolvedFlagReason::EXPERIENCE_CONTINUITY)
+      end
+
       # Create evaluation cache for flag dependencies
       evaluation_cache = {}
 
@@ -1088,7 +1394,8 @@ module PostHog
           "[FEATURE FLAGS] Unknown group type index #{aggregation_group_type_index} for feature flag #{flag[:key]}"
         )
         # failover to `/flags/`
-        raise InconclusiveMatchError, 'Flag has unknown group type index'
+        raise InconclusiveMatchError.new('Flag has unknown group type index',
+                                         reason: UnresolvedFlagReason::UNSUPPORTED_DEFINITION)
       end
 
       group_name_symbol = group_name.to_sym
@@ -1133,7 +1440,7 @@ module PostHog
       flag_conditions = flag_filters[:groups] || []
       flag_aggregation = flag_filters[:aggregation_group_type_index]
       early_exit = flag_filters[:early_exit] == true
-      is_inconclusive = false
+      inconclusive_reason = nil
       result = nil
 
       # NOTE: This NEEDS to be `each` because `each_key` breaks
@@ -1161,7 +1468,9 @@ module PostHog
               next
             end
             unless group_properties.key?(group_name.to_sym)
-              is_inconclusive = true
+              inconclusive_reason = FeatureFlagsPoller.pick_unresolved_reason(
+                inconclusive_reason, UnresolvedFlagReason::MISSING_CONTEXT
+              )
               next
             end
             effective_properties = group_properties[group_name.to_sym]
@@ -1185,25 +1494,38 @@ module PostHog
         when :out_of_rollout_bound
           break if early_exit
         end
-      rescue RequiresServerEvaluation
-        # Static cohort or other missing server-side data - must fallback to API
-        raise
-      rescue InconclusiveMatchError
+      rescue RequiresServerEvaluation => e
+        # Static cohort or other missing server-side data - must fallback to API. Evaluation stops here and
+        # skips filters it did not reach, so the flag's definition still counts toward the reason.
+        reason = FeatureFlagsPoller.pick_unresolved_reason(inconclusive_reason, e.reason)
+        definition_reason = _definition_unresolved_reason(flag, snapshot)
+        reason = FeatureFlagsPoller.pick_unresolved_reason(reason, definition_reason) unless definition_reason.nil?
+        raise RequiresServerEvaluation.new(e.message, reason: reason)
+      rescue InconclusiveMatchError => e
         # Evaluation error (bad regex, invalid date, missing property, etc.)
         # Track that we had an inconclusive match, but try other conditions
-        is_inconclusive = true
+        inconclusive_reason = FeatureFlagsPoller.pick_unresolved_reason(inconclusive_reason, e.reason)
       end
 
       if !result.nil?
         return result
-      elsif is_inconclusive
-        raise InconclusiveMatchError, "Can't determine if feature flag is enabled or not with given properties"
+      elsif !inconclusive_reason.nil?
+        raise InconclusiveMatchError.new("Can't determine if feature flag is enabled or not with given properties",
+                                         reason: inconclusive_reason)
       end
 
       # We can only return False when all conditions are False
       false
     end
 
+    def _definition_unresolved_reason(flag, snapshot)
+      self.class.definition_unresolved_reason(flag, snapshot[:flags_by_key] || {}, snapshot[:cohorts],
+                                              snapshot[:group_type_mapping])
+    rescue StandardError
+      # A malformed definition must not stop the fallback to the server.
+      nil
+    end
+
     def condition_match(flag, distinct_id, condition, properties, evaluation_cache, cohort_properties = {},
                         snapshot: _evaluation_snapshot)
       condition_match_outcome(flag, distinct_id, condition, properties, evaluation_cache,
@@ -1222,16 +1544,44 @@ module PostHog
       rollout_percentage = condition[:rollout_percentage]
 
       unless (condition[:properties] || []).empty?
-        unless condition[:properties].all? do |prop|
-          if prop[:type] == 'flag'
-            evaluate_flag_dependency(prop, evaluation_cache, distinct_id, properties, cohort_properties,
-                                     snapshot: snapshot)
-          else
-            FeatureFlagsPoller.match_property(prop, properties, cohort_properties,
-                                              property_matching_version: snapshot[:property_matching_version])
-          end
+        # Filters in a condition have no defined order, so an inconclusive filter does not stop the
+        # loop: a later filter can still rule the condition out or carry a higher-precedence reason.
+        inconclusive_reason = nil
+        server_evaluation_error = nil
+        condition[:properties].each do |prop|
+          matches =
+            if prop[:type] == 'flag'
+              evaluate_flag_dependency(prop, evaluation_cache, distinct_id, properties, cohort_properties,
+                                       snapshot: snapshot)
+            else
+              FeatureFlagsPoller.match_property(prop, properties, cohort_properties,
+                                                property_matching_version: snapshot[:property_matching_version])
+            end
+          return :no_match unless matches
+        rescue RequiresServerEvaluation => e
+          # Fall back to the server only when this is the first filter that could not be checked, as
+          # when the loop stopped there. After another inconclusive filter, later conditions must still
+          # be able to resolve the flag locally.
+          server_evaluation_error ||= e if inconclusive_reason.nil?
+          inconclusive_reason = FeatureFlagsPoller.pick_unresolved_reason(inconclusive_reason, e.reason)
+        rescue InconclusiveMatchError => e
+          inconclusive_reason = FeatureFlagsPoller.pick_unresolved_reason(inconclusive_reason, e.reason)
+        rescue StandardError
+          raise if inconclusive_reason.nil?
+
+          # The condition is already inconclusive, so an unexpected error in a later filter must not
+          # fail the whole flag. Later conditions can still resolve it.
+          break
+        end
+
+        # Raise the original error type: match_feature_flag_properties stops at it and falls back to the
+        # server instead of trying later conditions. A later filter can still carry a higher-precedence reason.
+        unless server_evaluation_error.nil?
+          raise RequiresServerEvaluation.new(server_evaluation_error.message, reason: inconclusive_reason)
         end
-          return :no_match
+        unless inconclusive_reason.nil?
+          raise InconclusiveMatchError.new("Can't determine if a condition of flag #{flag[:key]} matches",
+                                           reason: inconclusive_reason)
         end
 
         return :match if rollout_percentage.nil?
@@ -1432,6 +1782,8 @@ module PostHog
       end
       new_group_type_mapping = Concurrent::Hash[deep_symbolize_keys(group_type_mapping)]
       new_cohorts = Concurrent::Hash[deep_symbolize_keys(cohorts)]
+      unresolvable_flags = _unresolvable_flags(new_flags, new_by_key, new_cohorts, new_group_type_mapping)
+      unwarned_flags = nil
 
       # A read of the new definitions must not record its event before the tracker reset.
       @flag_definitions_update_mutex.synchronize do
@@ -1448,11 +1800,57 @@ module PostHog
         @minimal_flag_called_events = minimal_flag_called_events == true
         @flag_definitions_loaded_at.value = (Time.now.to_f * 1000).to_i
         @loaded_flags_successfully_once.make_true if @loaded_flags_successfully_once.false?
+        # Rebuilt from the current definitions, so a flag that is deleted or becomes resolvable is
+        # forgotten and warns again if it later returns to an unresolvable definition.
+        unwarned_flags = unresolvable_flags.reject { |key, entry| @warned_unresolvable_flags[key] == entry }
+        @warned_unresolvable_flags = unresolvable_flags
         @on_flag_definitions_updated&.call
       end
+      _warn_about_unresolvable_flags(unwarned_flags)
       logger.debug "Loaded #{new_flags.length} feature flags and #{new_cohorts.length} cohorts"
     end
 
+    # Flag key => [reason, definition] for each flag that local evaluation never resolves. Hash#== compares
+    # the definition by content and ignores key order, so a reordered copy does not warn again.
+    def _unresolvable_flags(flags, flags_by_key, cohorts, group_type_mapping)
+      flags.each_with_object({}) do |flag, unresolvable|
+        reason = self.class.definition_unresolved_reason(flag, flags_by_key, cohorts, group_type_mapping)
+        next if reason.nil? || flag[:key].nil?
+
+        unresolvable[flag[:key]] = [reason, flag]
+      rescue StandardError
+        # Evaluation reports a definition this malformed when the flag is used.
+        next
+      end
+    end
+
+    def _warn_about_unresolvable_flags(unresolvable_flags)
+      keys_by_reason = unresolvable_flags.keys.group_by { |key| unresolvable_flags[key].first }
+
+      experience_continuity_keys = keys_by_reason[UnresolvedFlagReason::EXPERIENCE_CONTINUITY]
+      if experience_continuity_keys
+        logger.warn(
+          "[FEATURE FLAGS] #{experience_continuity_keys.length} flag(s) have experience continuity enabled and " \
+          "can't be evaluated locally (reason: #{UnresolvedFlagReason::EXPERIENCE_CONTINUITY}): " \
+          "#{experience_continuity_keys.join(', ')}. Evaluating them makes a remote request, or leaves them " \
+          'unresolved with only_evaluate_locally: true. To evaluate them locally, disable experience continuity ' \
+          'on these flags in PostHog.'
+        )
+      end
+
+      unsupported_definition_keys = keys_by_reason[UnresolvedFlagReason::UNSUPPORTED_DEFINITION]
+      return unless unsupported_definition_keys
+
+      logger.warn(
+        "[FEATURE FLAGS] #{unsupported_definition_keys.length} flag(s) use something local evaluation doesn't " \
+        'support, such as a static cohort, an unknown operator, a malformed value, or a missing or circular flag ' \
+        "dependency (reason: #{UnresolvedFlagReason::UNSUPPORTED_DEFINITION}): " \
+        "#{unsupported_definition_keys.join(', ')}. Evaluating them makes a remote request when evaluation " \
+        'reaches that part, or leaves them unresolved with only_evaluate_locally: true. To evaluate them ' \
+        'locally, change these flags in PostHog or upgrade posthog-ruby.'
+      )
+    end
+
     def _request_feature_flag_definitions(etag: nil)
       uri = URI("#{@host}/flags/definitions")
       uri.query = URI.encode_www_form([['token', @project_api_key], %w[send_cohorts true]])