posthog-ruby 3.23.7 → 3.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67be906751ad3545830e00ac558a3787ba935d08c5414b216b653b63a745a424
-  data.tar.gz: 589fa3335b009dc16e22224e4708d55079e9b236c5c6cdfdba6f996fdb191af3
+  metadata.gz: 471bfa76731003cb33a963c903119506339f2e5cc51eb5b326a8af5df7deaabd
+  data.tar.gz: c41215d0fcc1edc5894b513788ca1e5777e98061f6017e80ae845c46c009d906
 SHA512:
-  metadata.gz: 1d7c92afb919cfb24e8e3a9bcfd3605cb4fce07d784019f1dd80fd0c685bc4ddde18d5b0322091fe49ad0e474cedbcae3804baf624697be650eed0418a450cdd
-  data.tar.gz: c9bec9d494e68a63b594c6960dc5e9d30d32d918c68df1a7dd83ba3a047179ff87bf5756f5dd0434ffde305b14a392457cbac7762c84e8ea91ed9839fab09763
+  metadata.gz: f183202aacd689a033e142a57d79355b115306fc39538220c7b002828883d15c8c61cccd29f3a40c7fde95df2ddefd55cebc4f0eab8fdf5cb9a800887b2536bd
+  data.tar.gz: 02123c015cb06e724ab63576948dbf928c7ce1f919772c0e5b70d69d62e2b7ce27ccbbb8a16b24de583c608d8566f5c7da806a2756cf6a182a40d7ced73d466e

data/lib/posthog/client.rb

@@ -302,6 +302,11 @@ module PostHog
 
       symbolize_keys! attrs
       minimal_flag_called_event = attrs.delete(:_minimal_flag_called_event) == true
+      # Integrations that ride on a host application's client (e.g. PostHog::MCP)
+      # may relabel a single event's `$lib`/`$lib_version` without relabeling the
+      # client or its User-Agent.
+      lib_override = attrs.delete(:_lib)
+      lib_version_override = attrs.delete(:_lib_version)
       enrich_capture_attrs_with_context(attrs)
 
       # Precedence: an explicit `flags` snapshot always wins, regardless of
@@ -370,8 +375,8 @@ module PostHog
       end
 
       attrs[:is_server] = @is_server
-      attrs[:lib] = @lib
-      attrs[:lib_version] = @lib_version
+      attrs[:lib] = lib_override || @lib
+      attrs[:lib_version] = (lib_version_override || @lib_version).to_s
       message = FieldParser.parse_for_capture(attrs)
       # Minimal events are built from the allowlist after full assembly so
       # context properties and parser-added metadata can never leak in.
@@ -659,7 +664,8 @@ module PostHog
       flag_keys_set = flag_keys&.to_set(&:to_s)
 
       @feature_flags_poller.load_feature_flags
-      poller_flags_by_key = @feature_flags_poller.feature_flags_by_key || {}
+      definition_snapshot = @feature_flags_poller._evaluation_snapshot
+      poller_flags_by_key = definition_snapshot[:flags_by_key] || {}
 
       poller_flags_by_key.each do |key, definition|
         next if flag_keys_set && !flag_keys_set.include?(key.to_s)
@@ -667,7 +673,7 @@ module PostHog
         begin
           match = @feature_flags_poller.send(
             :_compute_flag_locally,
-            definition, distinct_id, groups, person_properties, group_properties
+            definition, distinct_id, groups, person_properties, group_properties, snapshot: definition_snapshot
           )
         rescue PostHog::RequiresServerEvaluation, PostHog::InconclusiveMatchError, StandardError
           next
@@ -680,7 +686,7 @@ module PostHog
           enabled: match.is_a?(String) || (match ? true : false),
           variant: match.is_a?(String) ? match : nil,
           payload: FeatureFlagResult.parse_payload(
-            @feature_flags_poller.send(:_compute_flag_payload_locally, key, match)
+            @feature_flags_poller.send(:_compute_flag_payload_locally, key, match, snapshot: definition_snapshot)
           ),
           id: definition[:id],
           version: nil,
@@ -699,7 +705,7 @@ module PostHog
       # the snapshot uses a remote /flags response, the response's top-level
       # `minimalFlagCalledEvents` field governs; a local-only snapshot reads
       # the gate polled with the flag definitions.
-      minimal_flag_called_events = @feature_flags_poller.minimal_flag_called_events
+      minimal_flag_called_events = definition_snapshot[:minimal_flag_called_events]
 
       # Skip the remote `/flags` round-trip when the caller scoped the request
       # to a fixed set of `flag_keys` and we've already resolved every one of

data/lib/posthog/feature_flags.rb

@@ -86,6 +86,11 @@ 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_snapshot = Concurrent::AtomicReference.new({
+        flags: @feature_flags, flags_by_key: @feature_flags_by_key,
+        group_type_mapping: @group_type_mapping, cohorts: @cohorts,
+        minimal_flag_called_events: @minimal_flag_called_events, property_matching_version: 1
+      }.freeze)
       @flag_definition_cache_provider = flag_definition_cache_provider
       FlagDefinitionCacheProvider.validate!(@flag_definition_cache_provider) if @flag_definition_cache_provider
 
@@ -221,12 +226,14 @@ module PostHog
       groups = {},
       person_properties = {},
       group_properties = {},
-      only_evaluate_locally = false
+      only_evaluate_locally = false,
+      snapshot: nil
     )
       key = key.to_s
 
       # make sure they're loaded on first run
       load_feature_flags
+      snapshot ||= _evaluation_snapshot
 
       symbolize_keys! groups
       symbolize_keys! person_properties
@@ -238,12 +245,13 @@ module PostHog
 
       response = nil
       payload = nil
-      feature_flag = @feature_flags_by_key&.[](key)
+      feature_flag = snapshot[:flags_by_key]&.[](key)
 
       unless feature_flag.nil?
         begin
-          response = _compute_flag_locally(feature_flag, distinct_id, groups, person_properties, group_properties)
-          payload = _compute_flag_payload_locally(key, response) unless response.nil?
+          response = _compute_flag_locally(feature_flag, distinct_id, groups, person_properties, group_properties,
+                                           snapshot: snapshot)
+          payload = _compute_flag_payload_locally(key, response, snapshot: snapshot) unless response.nil?
           logger.debug "Successfully computed flag locally: #{key} -> #{response}"
         rescue RequiresServerEvaluation, InconclusiveMatchError => e
           logger.debug "Failed to compute flag #{key} locally: #{e}"
@@ -262,7 +270,7 @@ module PostHog
       # Locally-evaluated flags read it from the definitions payload; remotely
       # evaluated flags read it from the /flags response. nil when the signal
       # is unavailable, which fails safe to the full event.
-      minimal_flag_called_events = @minimal_flag_called_events if flag_was_locally_evaluated
+      minimal_flag_called_events = snapshot[:minimal_flag_called_events] if flag_was_locally_evaluated
 
       request_id = nil
       evaluated_at = nil
@@ -349,17 +357,19 @@ module PostHog
       raise_on_error = false
     )
       load_feature_flags
+      snapshot = _evaluation_snapshot
 
       flags = {}
       payloads = {}
-      fallback_to_server = @feature_flags.empty?
+      fallback_to_server = snapshot[:flags].empty?
       request_id = nil # Only for /flags requests
       evaluated_at = nil # Only for /flags requests
 
-      @feature_flags.each do |flag|
-        match_value = _compute_flag_locally(flag, distinct_id, groups, person_properties, group_properties)
+      snapshot[:flags].each do |flag|
+        match_value = _compute_flag_locally(flag, distinct_id, groups, person_properties, group_properties,
+                                            snapshot: snapshot)
         flags[flag[:key]] = match_value
-        match_payload = _compute_flag_payload_locally(flag[:key], match_value)
+        match_payload = _compute_flag_payload_locally(flag[:key], match_value, snapshot: snapshot)
         payloads[flag[:key]] = match_payload if match_payload
       rescue RequiresServerEvaluation, InconclusiveMatchError
         fallback_to_server = true
@@ -439,6 +449,8 @@ module PostHog
       only_evaluate_locally = false
     )
       key = key.to_s
+      load_feature_flags
+      snapshot = _evaluation_snapshot
 
       if match_value.nil?
         match_value = get_feature_flag(
@@ -447,11 +459,12 @@ module PostHog
           groups,
           person_properties,
           group_properties,
-          true
+          true,
+          snapshot: snapshot
         )[0]
       end
       response = nil
-      response = _compute_flag_payload_locally(key, match_value) unless match_value.nil?
+      response = _compute_flag_payload_locally(key, match_value, snapshot: snapshot) unless match_value.nil?
       if response.nil? && !only_evaluate_locally
         flags_payloads = get_feature_payloads(distinct_id, groups, person_properties, group_properties)
         response = flags_payloads[key.downcase] || nil
@@ -622,14 +635,69 @@ module PostHog
       end
     end
 
-    def self.match_property(property, property_values, cohort_properties = {})
+    # Service legacy classifies the entire filter, not individual array members.
+    def self.boolean_like?(value)
+      case value
+      when true, false then true
+      when String then %w[true false].include?(value.downcase)
+      when Array then value.all? { |member| boolean_like?(member) }
+      else false
+      end
+    end
+
+    def self.legacy_truthy?(value)
+      case value
+      when true then true
+      when String then value.downcase == 'true'
+      when Array then value.all? { |member| legacy_truthy?(member) }
+      else false
+      end
+    end
+
+    def self.sorted_composite(value)
+      case value
+      when Hash
+        value.transform_keys(&:to_s).sort.to_h.transform_values { |member| sorted_composite(member) }
+      when Array
+        value.map { |member| sorted_composite(member) }
+      else
+        value
+      end
+    end
+
+    def self.property_string(value)
+      # Keep numeric normalization unchanged; null and composites need JSON rather
+      # than Ruby's nil.to_s / Array#to_s representations.
+      case value
+      when nil, Array, Hash then JSON.generate(sorted_composite(value))
+      else value.to_s
+      end.downcase
+    end
+
+    def self.exact_property_match?(filter, value, property_matching_version)
+      return legacy_truthy?(filter) == legacy_truthy?(value) if property_matching_version != 2 && boolean_like?(filter)
+      return legacy_truthy?(value) if filter.is_a?(Array) && filter.empty?
+
+      if filter.is_a?(Array)
+        filter.any? { |member| property_string(member) == property_string(value) }
+      else
+        property_string(filter) == property_string(value)
+      end
+    end
+
+    private_class_method :boolean_like?, :legacy_truthy?, :sorted_composite, :property_string, :exact_property_match?
+
+    def self.match_property(property, property_values, cohort_properties = {}, property_matching_version: 1)
       # only looks for matches where key exists in property_values
 
       PostHog::Utils.symbolize_keys! property
       PostHog::Utils.symbolize_keys! property_values
 
       # Handle cohort properties
-      return match_cohort(property, property_values, cohort_properties) if extract_value(property, :type) == 'cohort'
+      if extract_value(property, :type) == 'cohort'
+        return match_cohort(property, property_values, cohort_properties,
+                            property_matching_version: property_matching_version)
+      end
 
       key = property[:key].to_sym
       value = property[:value]
@@ -645,18 +713,8 @@ module PostHog
 
       case operator
       when 'exact', 'is_not'
-        if value.is_a?(Array)
-          values_stringified = value.map { |val| val.to_s.downcase }
-          return values_stringified.any?(override_value.to_s.downcase) if operator == 'exact'
-
-          return values_stringified.none?(override_value.to_s.downcase)
-
-        end
-        if operator == 'exact'
-          value.to_s.downcase == override_value.to_s.downcase
-        else
-          value.to_s.downcase != override_value.to_s.downcase
-        end
+        matches = exact_property_match?(value, override_value, property_matching_version)
+        operator == 'exact' ? matches : !matches
       when 'is_set'
         property_values.key?(key)
       when 'icontains'
@@ -738,7 +796,7 @@ module PostHog
       end
     end
 
-    def self.match_cohort(property, property_values, cohort_properties)
+    def self.match_cohort(property, property_values, cohort_properties, property_matching_version: 1)
       # Cohort properties are in the form of property groups like this:
       # {
       #   "cohort_id" => {
@@ -756,10 +814,11 @@ module PostHog
               "cohort #{cohort_id} not found in local cohorts - likely a static cohort that requires server evaluation"
       end
 
-      match_property_group(property_group, property_values, cohort_properties)
+      match_property_group(property_group, property_values, cohort_properties,
+                           property_matching_version: property_matching_version)
     end
 
-    def self.match_property_group(property_group, property_values, cohort_properties)
+    def self.match_property_group(property_group, property_values, cohort_properties, property_matching_version: 1)
       return true if property_group.nil? || property_group.empty?
 
       group_type = extract_value(property_group, :type)
@@ -768,9 +827,11 @@ 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)
+        match_nested_property_group(properties, group_type, property_values, cohort_properties,
+                                    property_matching_version: property_matching_version)
       else
-        match_regular_property_group(properties, group_type, property_values, cohort_properties)
+        match_regular_property_group(properties, group_type, property_values, cohort_properties,
+                                     property_matching_version: property_matching_version)
       end
     end
 
@@ -795,16 +856,19 @@ module PostHog
       first_property.key?(:values) || first_property.key?('values')
     end
 
-    def self.match_nested_property_group(properties, group_type, property_values, cohort_properties)
+    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)
+          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)
+          return true if match_property_group(property, property_values, cohort_properties,
+                                              property_matching_version: property_matching_version)
         end
         false
       else
@@ -812,7 +876,8 @@ module PostHog
       end
     end
 
-    def self.match_regular_property_group(properties, group_type, property_values, cohort_properties)
+    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)
 
@@ -821,7 +886,8 @@ module PostHog
       properties.each do |prop|
         PostHog::Utils.symbolize_keys!(prop)
 
-        matches = match_property(prop, property_values, cohort_properties)
+        matches = match_property(prop, property_values, cohort_properties,
+                                 property_matching_version: property_matching_version)
 
         negated = prop[:negation] || false
         final_result = negated ? !matches : matches
@@ -854,13 +920,14 @@ module PostHog
     # @param properties [Hash] Person properties for evaluation
     # @param cohort_properties [Hash] Cohort properties for evaluation
     # @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)
+    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 @feature_flags_by_key.nil? || evaluation_cache.nil?
+      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'}' " \
@@ -888,7 +955,7 @@ module PostHog
       dependency_chain.each do |dep_flag_key|
         unless evaluation_cache.key?(dep_flag_key)
           # Need to evaluate this dependency first
-          dep_flag = @feature_flags_by_key[dep_flag_key]
+          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
@@ -905,7 +972,8 @@ module PostHog
                 distinct_id,
                 properties,
                 evaluation_cache,
-                cohort_properties
+                cohort_properties,
+                snapshot: snapshot
               )
               evaluation_cache[dep_flag_key] = dep_result
             rescue InconclusiveMatchError => e
@@ -971,7 +1039,14 @@ module PostHog
     private_class_method :extract_value, :find_cohort_property, :nested_property_group?,
                          :match_nested_property_group, :match_regular_property_group
 
-    def _compute_flag_locally(flag, distinct_id, groups = {}, person_properties = {}, group_properties = {})
+    # Publish/capture all matching state together so a poll cannot switch semantics
+    # (or dependency/cohort definitions) halfway through one local evaluation.
+    def _evaluation_snapshot
+      @definition_snapshot.value
+    end
+
+    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]
 
       return false unless flag[:active]
@@ -988,11 +1063,12 @@ module PostHog
           local_person_properties = local_person_properties.merge(distinct_id: distinct_id)
         end
 
-        return match_feature_flag_properties(flag, distinct_id, local_person_properties, evaluation_cache, @cohorts,
-                                             groups: groups, group_properties: group_properties)
+        return match_feature_flag_properties(flag, distinct_id, local_person_properties, evaluation_cache,
+                                             snapshot[:cohorts], groups: groups, group_properties: group_properties,
+                                                                 snapshot: snapshot)
       end
 
-      group_name = @group_type_mapping[aggregation_group_type_index.to_s.to_sym]
+      group_name = snapshot[:group_type_mapping][aggregation_group_type_index.to_s.to_sym]
 
       if group_name.nil?
         logger.warn(
@@ -1013,24 +1089,25 @@ module PostHog
 
       focused_group_properties = group_properties[group_name_symbol]
       match_feature_flag_properties(flag, groups[group_name_symbol], focused_group_properties, evaluation_cache,
-                                    @cohorts, groups: groups, group_properties: group_properties)
+                                    snapshot[:cohorts], groups: groups, group_properties: group_properties,
+                                                        snapshot: snapshot)
     end
 
-    def _compute_flag_payload_locally(key, match_value)
-      return nil if @feature_flags_by_key.nil?
+    def _compute_flag_payload_locally(key, match_value, snapshot: _evaluation_snapshot)
+      return nil if snapshot[:flags_by_key].nil?
 
       key = key.to_s
       response = nil
       if [true, false].include? match_value
-        response = @feature_flags_by_key.dig(key, :filters, :payloads, match_value.to_s.to_sym)
+        response = snapshot[:flags_by_key].dig(key, :filters, :payloads, match_value.to_s.to_sym)
       elsif match_value.is_a? String
-        response = @feature_flags_by_key.dig(key, :filters, :payloads, match_value.to_sym)
+        response = snapshot[:flags_by_key].dig(key, :filters, :payloads, match_value.to_sym)
       end
       response
     end
 
     def match_feature_flag_properties(flag, distinct_id, properties, evaluation_cache, cohort_properties = {},
-                                      groups: {}, group_properties: {})
+                                      groups: {}, group_properties: {}, snapshot: _evaluation_snapshot)
       flag_filters = flag[:filters] || {}
 
       flag_conditions = flag_filters[:groups] || []
@@ -1055,7 +1132,7 @@ module PostHog
           if condition_aggregation.nil?
             # Person condition under a mixed flag — caller already passed person props/bucketing.
           else
-            group_name = @group_type_mapping[condition_aggregation.to_s.to_sym]
+            group_name = snapshot[:group_type_mapping][condition_aggregation.to_s.to_sym]
             if group_name.nil? || !groups.key?(group_name.to_sym)
               logger.debug do
                 "[FEATURE FLAGS] Skipping group condition for flag '#{flag[:key]}': " \
@@ -1073,7 +1150,7 @@ module PostHog
         end
 
         case condition_match_outcome(flag, effective_bucketing, condition, effective_properties, evaluation_cache,
-                                     cohort_properties)
+                                     cohort_properties, snapshot: snapshot)
         when :match
           variant_override = condition[:variant]
           flag_multivariate = flag_filters[:multivariate] || {}
@@ -1107,9 +1184,10 @@ module PostHog
       false
     end
 
-    def condition_match(flag, distinct_id, condition, properties, evaluation_cache, cohort_properties = {})
+    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,
-                              cohort_properties) == :match
+                              cohort_properties, snapshot: snapshot) == :match
     end
 
     # Evaluates a single condition group and returns a tri-state outcome:
@@ -1119,15 +1197,18 @@ module PostHog
     #                            rollout percentage excluded the user
     # Distinguishing :no_match from :out_of_rollout_bound lets the caller implement the
     # early_exit behavior (mirrors the server-side Rust evaluation engine).
-    def condition_match_outcome(flag, distinct_id, condition, properties, evaluation_cache, cohort_properties = {})
+    def condition_match_outcome(flag, distinct_id, condition, properties, evaluation_cache, cohort_properties = {},
+                                snapshot: _evaluation_snapshot)
       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)
+            evaluate_flag_dependency(prop, evaluation_cache, distinct_id, properties, cohort_properties,
+                                     snapshot: snapshot)
           else
-            FeatureFlagsPoller.match_property(prop, properties, cohort_properties)
+            FeatureFlagsPoller.match_property(prop, properties, cohort_properties,
+                                              property_matching_version: snapshot[:property_matching_version])
           end
         end
           return :no_match
@@ -1236,6 +1317,11 @@ module PostHog
           @cohorts = Concurrent::Hash.new
           @flag_definitions_loaded_at.value = nil
           @minimal_flag_called_events = false
+          @definition_snapshot.value = {
+            flags: @feature_flags, flags_by_key: @feature_flags_by_key,
+            group_type_mapping: @group_type_mapping, cohorts: @cohorts,
+            minimal_flag_called_events: false, property_matching_version: 1
+          }.freeze
           @loaded_flags_successfully_once.make_false
           @quota_limited.make_true
           @on_flag_definitions_updated&.call if definitions_were_loaded
@@ -1258,11 +1344,13 @@ module PostHog
       return unless @flag_definition_cache_provider
 
       begin
+        snapshot = _evaluation_snapshot
         data = {
-          flags: @feature_flags.to_a,
-          group_type_mapping: @group_type_mapping.to_h,
-          cohorts: @cohorts.to_h,
-          minimal_flag_called_events: @minimal_flag_called_events
+          flags: snapshot[:flags].to_a,
+          group_type_mapping: snapshot[:group_type_mapping].to_h,
+          cohorts: snapshot[:cohorts].to_h,
+          minimal_flag_called_events: snapshot[:minimal_flag_called_events],
+          property_matching_version: snapshot[:property_matching_version]
         }
         @flag_definition_cache_provider.on_flag_definitions_received(data)
       rescue StandardError => e
@@ -1276,6 +1364,7 @@ module PostHog
       cohorts = get_by_symbol_or_string_key(data, 'cohorts') || {}
       minimal_flag_called_events = get_by_symbol_or_string_key(data, 'minimal_flag_called_events')
 
+      property_matching_version = get_by_symbol_or_string_key(data, 'property_matching_version') || 1
       new_flags = Concurrent::Array.new(flags.map { |f| deep_symbolize_keys(f) })
       new_by_key = {}
       new_flags.each do |flag|
@@ -1286,6 +1375,12 @@ module PostHog
 
       # A read of the new definitions must not record its event before the tracker reset.
       @flag_definitions_update_mutex.synchronize do
+        @definition_snapshot.value = {
+          flags: new_flags, flags_by_key: new_by_key,
+          group_type_mapping: new_group_type_mapping, cohorts: new_cohorts,
+          minimal_flag_called_events: minimal_flag_called_events == true,
+          property_matching_version: property_matching_version
+        }.freeze
         @feature_flags = new_flags
         @feature_flags_by_key = new_by_key
         @group_type_mapping = new_group_type_mapping

data/lib/posthog/flag_definition_cache.rb

@@ -14,11 +14,14 @@ module PostHog
   #
   # @!method flag_definitions
   #   Retrieve cached flag definitions. Return a Hash with +:flags+,
-  #   +:group_type_mapping+, +:cohorts+, and +:minimal_flag_called_events+
+  #   +:group_type_mapping+, +:cohorts+, +:minimal_flag_called_events+, and +:property_matching_version+
   #   keys, or +nil+ if the cache is empty. Returning +nil+ triggers an API
   #   fetch when no flags are loaded yet (emergency fallback). Providers
   #   written before +:minimal_flag_called_events+ existed continue to work;
-  #   a missing key is treated as +false+.
+  #   a missing key is treated as +false+. Preserve +:property_matching_version+
+  #   with the definitions: exactly +2+ selects explicit equality; missing/1
+  #   (including older cache entries) selects service legacy boolean matching.
+  #   A fresh entry without the version resets to legacy, even after version 2.
   #   @return [Hash, nil]
   #
   # @!method should_fetch_flag_definitions?
@@ -29,9 +32,10 @@ module PostHog
   #
   # @!method on_flag_definitions_received(data)
   #   Called after successfully fetching new definitions from the API.
-  #   +data+ is a Hash with +:flags+, +:group_type_mapping+, +:cohorts+, and
-  #   +:minimal_flag_called_events+ keys (plain Ruby types, not Concurrent::
-  #   wrappers). Store it in your external cache.
+  #   +data+ is a Hash with +:flags+, +:group_type_mapping+, +:cohorts+,
+  #   +:minimal_flag_called_events+, and +:property_matching_version+ keys
+  #   (plain Ruby types, not Concurrent:: wrappers). Store the entire snapshot
+  #   together in your external cache, including version-only updates.
   #   @param data [Hash]
   #   @return [void]
   #

data/lib/posthog/mcp/README.md

@@ -0,0 +1,53 @@
+# PostHog MCP analytics for Ruby
+
+> **Experimental and unsupported.** `PostHog::MCP` is not an officially supported PostHog SDK: no
+> support is provided for it, and its API, options, and the captured `$mcp_*` event schema may change
+> in a minor release. A one-line warning is logged when you require it. Bug reports and patches are
+> welcome at https://github.com/PostHog/posthog-ruby/issues, but don't build production reporting on
+> it yet.
+
+Product analytics for [Model Context Protocol](https://modelcontextprotocol.io) servers built on the
+official Ruby [`mcp`](https://rubygems.org/gems/mcp) gem. Wrap an `MCP::Server` so every tool call,
+agent intent, handshake, listing, prompt, resource read, and failure is captured to PostHog.
+
+**Documentation: https://posthog.com/docs/mcp-analytics** — setup, every option, the event and
+property catalog, sessions on stateless/multi-pod servers, conversation ids, intent, identifying
+users, privacy, and custom dispatchers. That's the single source of truth; this directory
+deliberately keeps no second copy of it.
+
+Install is just `gem 'posthog-ruby'`. `PostHog::MCP.instrument` needs the `mcp` gem (`>= 1.4`) at
+runtime, but anyone wrapping a server already has it. `PostHog::MCP::Client` (custom dispatchers)
+needs nothing beyond `posthog-ruby`.
+
+## Ruby-specific notes
+
+These are the few things that differ from what the docs describe for the other SDKs.
+
+* **`$lib` is per event.** MCP events report `$lib: "posthog-ruby-mcp"` while the client you pass in
+  keeps its own identity (`posthog-ruby` or `posthog-rails`) for everything else it sends, so
+  instrumenting a server inside a Rails app doesn't relabel the app's other events.
+* **Truncation is tighter.** Events are truncated to fit the core client's 32KB per-message limit,
+  because posthog-ruby drops larger messages at batch time - truncating harder beats losing the
+  event.
+* **Request scope needs Ruby 3.2+ to be inherited.** A custom event captured from a thread or fiber
+  a tool spawns is attributed to that request on 3.2+ (fiber storage); before 3.2 capture from the
+  tool body itself, or an HTTP server falls back to a standalone session.
+* **Composed schemas are left alone.** A tool whose `input_schema` is `oneOf`/`allOf`/`anyOf` or a
+  `$ref` has nothing injected into it and nothing stripped from its calls.
+* **stdio servers own `$stdout`.** The integration's own messages go only to the `logger:` you pass
+  (default: nowhere); the experimental notice and misconfiguration warnings go to stderr. Point the
+  core SDK's logger away from stdout too: `PostHog::Logging.logger = Logger.new($stderr)`.
+
+## Layout
+
+| File | What it does |
+|---|---|
+| `mcp.rb` (parent dir) | `PostHog::MCP.instrument` and the public helpers |
+| `server_extension.rb` | Prepended onto `MCP::Server` and the Streamable HTTP transport |
+| `instrumentation.rb` | Per-request dispatch: intent, identity, sessions, recording |
+| `client.rb` | `PostHog::MCP::Client` for custom dispatchers |
+| `rack_middleware.rb` | `Mcp-Session-Id` tokens for a custom Rack stack |
+| `sanitization.rb`, `truncation.rb` | Redaction and payload budgets |
+
+Runnable example: [`examples/mcp_server.rb`](../../../examples/mcp_server.rb). Specs:
+`spec/posthog/mcp/`.