mixpanel-ruby 3.2.0 → 3.4.0

data/openfeature-provider/README.md

@@ -1,6 +1,6 @@
 # mixpanel-ruby-openfeature
 
-##### _May 13, 2026_ - [openfeature/v0.1.0](https://github.com/mixpanel/mixpanel-ruby/releases/tag/openfeature/v0.1.0)
+##### _July 28, 2026_ - [openfeature/v0.2.0](https://github.com/mixpanel/mixpanel-ruby/releases/tag/openfeature/v0.2.0)
 
 [![Gem Version](https://img.shields.io/gem/v/mixpanel-ruby-openfeature.svg)](https://rubygems.org/gems/mixpanel-ruby-openfeature)
 [![OpenFeature](https://img.shields.io/badge/OpenFeature-compatible-green)](https://openfeature.dev/)
@@ -201,6 +201,34 @@ When you are done using the provider, shut it down to stop any background pollin
 provider.shutdown
 ```
 
+## Async Exposure Tracking
+
+By default, every flag evaluation tracks an exposure event inline — the `/track` HTTP round trip happens on the calling thread before `fetch_*_value` returns. For latency-sensitive code paths, pass an `:exposure_executor` so exposure tracking runs off-thread. The executor is duck-typed — anything that responds to `#post(&block)` works:
+
+```ruby
+# With concurrent-ruby (recommended)
+require 'concurrent'
+exposure_executor = Concurrent::FixedThreadPool.new(1)
+
+provider = Mixpanel::OpenFeature::Provider.from_local(
+  'YOUR_PROJECT_TOKEN',
+  { exposure_executor: exposure_executor },
+)
+
+# Without concurrent-ruby (minimal wrapper)
+class ThreadPerCall
+  def post(&block) = Thread.new(&block)
+end
+provider = Mixpanel::OpenFeature::Provider.from_local(
+  'YOUR_PROJECT_TOKEN',
+  { exposure_executor: ThreadPerCall.new },
+)
+```
+
+Available on both local and remote flag configs. Defaults to `nil` (inline behavior); existing setups are unaffected.
+
+> **Executor lifecycle:** `provider.shutdown` stops the flags provider's own resources (polling) but does NOT shut down a user-supplied executor. Own the executor's lifecycle explicitly — e.g. `at_exit { exposure_executor.shutdown; exposure_executor.wait_for_termination(5) }` for `Concurrent::FixedThreadPool`. Skipping this can leave background threads alive at process exit and delay shutdown.
+
 ## Error Handling
 
 The provider uses OpenFeature's standard error codes to indicate issues during flag evaluation:

data/openfeature-provider/lib/mixpanel/openfeature/provider.rb

@@ -69,16 +69,41 @@ module Mixpanel
 
         begin
           result = @flags_provider.get_variant(flag_key, fallback, context, report_exposure: true)
-        rescue StandardError
-          return error_result(default_value, ::OpenFeature::SDK::Provider::ErrorCode::GENERAL)
+        rescue StandardError => e
+          return error_result(default_value, ::OpenFeature::SDK::Provider::ErrorCode::GENERAL, e.message)
         end
 
-        if result.equal?(fallback)
+        # variant_source distinguishes local / remote / fallback. When fallback,
+        # fallback_reason carries the specific reason (PHP-aligned constants)
+        # so we can map each to the spec-correct OpenFeature response instead
+        # of collapsing every fallback to FLAG_NOT_FOUND. SDK-83: BACKEND_ERROR
+        # also carries the backend message, forwarded as error_message.
+        case result.fallback_reason&.kind
+        when :flag_not_found
           return ::OpenFeature::SDK::Provider::ResolutionDetails.new(
             value: default_value,
             error_code: ::OpenFeature::SDK::Provider::ErrorCode::FLAG_NOT_FOUND,
             reason: ::OpenFeature::SDK::Provider::Reason::DEFAULT
           )
+        when :missing_context_key
+          return error_result(
+            default_value,
+            ::OpenFeature::SDK::Provider::ErrorCode::TARGETING_KEY_MISSING,
+            result.fallback_reason.message
+          )
+        when :no_rollout_match
+          # Flag exists, user just didn't match any rollout — per the
+          # OpenFeature spec this is `reason: DEFAULT` with no error.
+          return ::OpenFeature::SDK::Provider::ResolutionDetails.new(
+            value: default_value,
+            reason: ::OpenFeature::SDK::Provider::Reason::DEFAULT
+          )
+        when :backend_error
+          return error_result(
+            default_value,
+            ::OpenFeature::SDK::Provider::ErrorCode::GENERAL,
+            result.fallback_reason.message
+          )
         end
 
         value = result.variant_value
@@ -158,10 +183,11 @@ module Mixpanel
         end
       end
 
-      def error_result(default_value, error_code)
+      def error_result(default_value, error_code, error_message = nil)
         ::OpenFeature::SDK::Provider::ResolutionDetails.new(
           value: default_value,
           error_code: error_code,
+          error_message: error_message,
           reason: ::OpenFeature::SDK::Provider::Reason::ERROR
         )
       end

data/openfeature-provider/lib/mixpanel/openfeature/version.rb

@@ -2,6 +2,6 @@
 
 module Mixpanel
   module OpenFeature
-    VERSION = '0.1.0'
+    VERSION = '0.2.0'
   end
 end

data/openfeature-provider/mixpanel-ruby-openfeature.gemspec

@@ -17,7 +17,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
 
   spec.add_runtime_dependency 'openfeature-sdk', '~> 0.5'
-  spec.add_runtime_dependency 'mixpanel-ruby', '~> 3.1'
+  spec.add_runtime_dependency 'mixpanel-ruby', '~> 3.3'
 
   spec.add_development_dependency 'rspec', '~> 3.0'
   spec.add_development_dependency 'simplecov'

data/openfeature-provider/spec/mixpanel_openfeature_provider_spec.rb

@@ -75,15 +75,25 @@ RSpec.describe Mixpanel::OpenFeature::Provider do
   def setup_flag(flag_key, value, variant_key: 'variant-key')
     allow(mock_flags).to receive(:get_variant) do |key, fallback, _ctx, **_kwargs|
       if key == flag_key
-        Mixpanel::Flags::SelectedVariant.new(variant_key: variant_key, variant_value: value)
+        Mixpanel::Flags::SelectedVariant.new(
+          variant_key: variant_key,
+          variant_value: value,
+          variant_source: Mixpanel::Flags::VariantSource::LOCAL
+        )
       else
-        fallback
+        fallback.as_fallback(Mixpanel::Flags::FallbackReason.flag_not_found)
       end
     end
   end
 
+  def setup_fallback(reason)
+    allow(mock_flags).to receive(:get_variant) do |_key, fallback, _ctx, **_kwargs|
+      fallback.as_fallback(reason)
+    end
+  end
+
   def setup_flag_not_found
-    allow(mock_flags).to receive(:get_variant) { |_key, fallback, _ctx, **_kwargs| fallback }
+    setup_fallback(Mixpanel::Flags::FallbackReason.flag_not_found)
   end
 
   # --- Metadata ---
@@ -305,6 +315,67 @@ RSpec.describe Mixpanel::OpenFeature::Provider do
     end
   end
 
+  # --- NO_ROLLOUT_MATCH (flag exists, no rollout matched) ---
+
+  describe 'no rollout match' do
+    before { setup_fallback(Mixpanel::Flags::FallbackReason.no_rollout_match) }
+
+    it 'returns DEFAULT reason without an error code' do
+      result = provider.fetch_boolean_value(flag_key: 'flag', default_value: true)
+      expect(result.value).to be true
+      expect(result.reason).to eq('DEFAULT')
+      expect(result.error_code).to be_nil
+    end
+
+    it 'works for strings' do
+      result = provider.fetch_string_value(flag_key: 'flag', default_value: 'default')
+      expect(result.value).to eq('default')
+      expect(result.reason).to eq('DEFAULT')
+      expect(result.error_code).to be_nil
+    end
+  end
+
+  # --- MISSING_CONTEXT_KEY ---
+
+  describe 'missing context key' do
+    before { setup_fallback(Mixpanel::Flags::FallbackReason.missing_context_key('distinct_id')) }
+
+    it 'returns TARGETING_KEY_MISSING for boolean' do
+      result = provider.fetch_boolean_value(flag_key: 'flag', default_value: false)
+      expect(result.value).to be false
+      expect(result.error_code).to eq('TARGETING_KEY_MISSING')
+      expect(result.reason).to eq('ERROR')
+    end
+
+    it 'returns TARGETING_KEY_MISSING for string and forwards the missing key as error_message' do
+      result = provider.fetch_string_value(flag_key: 'flag', default_value: 'default')
+      expect(result.value).to eq('default')
+      expect(result.error_code).to eq('TARGETING_KEY_MISSING')
+      expect(result.error_message).to eq('distinct_id')
+      expect(result.reason).to eq('ERROR')
+    end
+  end
+
+  # --- BACKEND_ERROR (SDK-83: forwards the backend's response message) ---
+
+  describe 'backend error' do
+    before do
+      setup_fallback(
+        Mixpanel::Flags::FallbackReason.backend_error(
+          'HTTP 400: distinct_id must be provided in evalContext as a string'
+        )
+      )
+    end
+
+    it 'maps to GENERAL and forwards the backend message as error_message' do
+      result = provider.fetch_string_value(flag_key: 'flag', default_value: 'default')
+      expect(result.value).to eq('default')
+      expect(result.error_code).to eq('GENERAL')
+      expect(result.reason).to eq('ERROR')
+      expect(result.error_message).to include('distinct_id must be provided')
+    end
+  end
+
   # --- PROVIDER_NOT_READY ---
 
   describe 'provider not ready' do

data/spec/fixtures/datetime_compare_tests.json

@@ -0,0 +1,100 @@
+[
+  "A list of golden vectors for custom operators, to ensure logic parity across platforms",
+
+  "# Ordering and the six symbols",
+  ["2026-07-15T00:00:00Z", "<", 1784160000000, true],
+  ["2026-07-16T00:00:00Z", "<", 1784160000000, false],
+  ["2026-07-16T00:00:00Z", "===", 1784160000000, true],
+  ["2026-07-17T00:00:00Z", "!==", 1784160000000, true],
+  ["2026-07-16T00:00:00Z", ">=", 1784160000000, true],
+  ["2026-07-17T00:00:00Z", ">", 1784160000000, true],
+  ["2026-07-15T00:00:00Z", ">", 1784160000000, false],
+  ["2026-07-16T00:00:00Z", "<=", 1784160000000, true],
+  ["2026-07-17T00:00:00Z", "<=", 1784160000000, false],
+  ["2026-07-17T00:00:00Z", "===", 1784160000000, false],
+  ["2026-07-16T00:00:00Z", "!==", 1784160000000, false],
+  ["2026-07-15T00:00:00Z", ">=", 1784160000000, false],
+
+  "# Leap day",
+  ["2024-02-29T00:00:00Z", "===", 1709164800000, true],
+
+  "# Time-zone offsets change the instant",
+  ["2026-07-16T00:00:00+05:30", "===", 1784140200000, true],
+  ["2026-07-16T02:00:00+02:00", "===", 1784160000000, true],
+  ["2026-07-16T00:00:00+05:30", "<", 1784160000000, true],
+  ["2026-07-16T00:00:00-08:00", "===", 1784188800000, true],
+  ["2026-07-16T00:00:00-08:00", ">", 1784160000000, true],
+  ["2026-07-16T00:00:00+00:00", "===", 1784160000000, true],
+
+  "# Sub-second precision is dropped",
+  ["2026-07-16T00:00:00.5Z", "===", 1784160000000, true],
+  ["2026-07-16T00:00:00.500Z", "===", 1784160000000, true],
+  ["2026-07-16T00:00:00.123456Z", "===", 1784160000000, true],
+  ["2026-07-16T00:00:00.999999999Z", "===", 1784160000000, true],
+  ["2026-07-16T00:00:00.0Z", "===", 1784160000000, true],
+  ["2026-07-16T00:00:00.500Z", ">=", 1784160000000, true],
+  ["2026-07-16T23:59:59Z", "===", 1784246399000, true],
+  ["2026-07-16T23:59:59Z", "<=", 1784246399000, true],
+  ["2026-07-16T23:59:59.999Z", "===", 1784246399000, true],
+  ["2026-07-16T23:59:59.999Z", "<=", 1784246399000, true],
+
+  "# Trimming and lowercasing",
+  ["2026-07-16t00:00:00.500z", "===", 1784160000000, true],
+  ["2026-07-16t02:00:00+02:00", "===", 1784160000000, true],
+  [" 2026-07-16T00:00:00Z ", "===", 1784160000000, true],
+  ["2026-07-16t00:00:00z", "===", 1784160000000, true],
+
+  "# Wrong shapes, checked under both symbols",
+  ["2026-7-16T00:00:00Z", "===", 1784160000000, false],
+  ["2026-7-16T00:00:00Z", "!==", 1784160000000, false],
+  ["2026-07-16 00:00:00Z", "===", 1784160000000, false],
+  ["2026-07-16 00:00:00Z", "!==", 1784160000000, false],
+  ["2026-07-16T00:00:00", "===", 1784160000000, false],
+  ["2026-07-16T00:00:00", "!==", 1784160000000, false],
+  ["2026-07-16T00:00:00.Z", "===", 1784160000000, false],
+  ["2026-07-16T00:00:00.Z", "!==", 1784160000000, false],
+  ["2026-07-16T00:00:00+0200", "===", 1784160000000, false],
+  ["2026-07-16T00:00:00+0200", "!==", 1784160000000, false],
+  ["2026-07-16T00:00:00+02", "===", 1784160000000, false],
+  ["2026-07-16T00:00:00+02", "!==", 1784160000000, false],
+  ["2026-07-16T00:00:00Zextra", "===", 1784160000000, false],
+  ["2026-07-16T00:00:00Zextra", "!==", 1784160000000, false],
+  ["2026-07-16", "===", 1784160000000, false],
+  ["2026-07-16", "!==", 1784160000000, false],
+  ["20260716T000000Z", "===", 1784160000000, false],
+  ["20260716T000000Z", "!==", 1784160000000, false],
+  ["2026-07-16T00:00:00z00:00", "===", 1784160000000, false],
+  ["2026-07-16T00:00:00z00:00", "!==", 1784160000000, false],
+  ["2026-07-16T00:00:00,5Z", "===", 1784160000000, false],
+  ["2026-07-16T00:00:00,5Z", "!==", 1784160000000, false],
+
+  "# Missing or wrong-typed values",
+  [1784160000000, "===", 1784160000000, false],
+  ["2026-07-16T00:00:00Z", "===", 1e19, false],
+  ["2026-07-16T00:00:00Z", ">", 1e19, false],
+  ["2026-07-16T00:00:00Z", "<", 1e19, false],
+  ["2026-07-16", "===", 1784160000000, false],
+  ["2026-07-16T00:00:00", "===", 1784160000000, false],
+  ["yesterday", "===", 1784160000000, false],
+  [null, "===", 1784160000000, false],
+
+  "# Targets before 1970",
+  ["1969-12-31T23:59:59Z", "===", -1000, true],
+  ["1969-12-31T23:59:59Z", "!==", -1000, false],
+  ["1969-12-31T23:59:59Z", ">=", -1000, true],
+  ["1969-12-31T23:59:58Z", "<", -1000, true],
+  ["1969-12-31T23:59:59Z", ">", -2000, true],
+  ["1969-12-31T23:59:58.500Z", "===", -2000, true],
+  ["1969-12-31T23:59:58.500Z", "!==", -1000, true],
+
+  "# Impossible dates and out-of-range fields",
+  ["2026-02-30T00:00:00Z", "===", 1784160000000, false],
+  ["2026-02-30T00:00:00Z", "!==", 1784160000000, false],
+  ["2026-02-29T00:00:00Z", "!==", 1784160000000, false],
+  ["2025-02-29T00:00:00Z", "!==", 1784160000000, false],
+  ["2026-04-31T00:00:00Z", "!==", 1784160000000, false],
+  ["2026-06-31T00:00:00Z", "!==", 1784160000000, false],
+  ["2026-07-16T24:00:00Z", "!==", 1784160000000, false],
+  ["2026-13-01T00:00:00Z", "!==", 1784160000000, false],
+  ["2026-01-32T00:00:00Z", "!==", 1784160000000, false]
+]

data/spec/fixtures/semver_compare_tests.json

@@ -0,0 +1,161 @@
+[
+  "A list of golden vectors for custom operators, to ensure logic parity across platforms",
+
+  "# Ordering and the six symbols",
+  ["1.2.3", "===", "1.2.3", true],
+  ["1.2.4", "===", "1.2.3", false],
+  ["1.2.4", "!==", "1.2.3", true],
+  ["1.2.2", "<", "1.2.3", true],
+  ["1.2.3", "<", "1.2.3", false],
+  ["1.2.3", "<=", "1.2.3", true],
+  ["1.3.0", ">", "1.2.3", true],
+  ["1.2.3", ">=", "1.2.3", true],
+  ["1.10.0", ">", "1.9.0", true],
+  ["10.0.0", ">", "9.0.0", true],
+  ["1.0.10", ">", "1.0.9", true],
+  ["2.0.0", ">", "1.9.9", true],
+  ["1.0.0-alpha", "<", "1.0.0", true],
+  ["v1.2.3", "===", "1.2.3", true],
+  ["1.2.0", "===", "1.2", true],
+  [" 1.2.3 ", "===", "1.2.3", true],
+  ["1.2.3", "!==", "1.2.3", false],
+  ["1.2.4", "<=", "1.2.3", false],
+  ["1.2.2", ">", "1.2.3", false],
+  ["1.2.2", ">=", "1.2.3", false],
+
+  "# Pre-release ordering",
+  ["1.0.0-alpha", "<", "1.0.0-beta", true],
+  ["1.0.0-beta", "<", "1.0.0-rc1", true],
+  ["1.0.0-rc1", "<", "1.0.0-rc2", true],
+  ["1.0.0-alpha", "<", "1.0.0-alpha.1", true],
+  ["1.0.0-alpha.1", "<", "1.0.0-alpha.beta", true],
+  ["1.0.0-alpha", "<", "1.0.0-alpha.beta", true],
+  ["1.0.0-beta.2", "<", "1.0.0-beta.11", true],
+  ["1.0.0-a.1", "<", "1.0.0-b.1", true],
+  ["1.0.0-a.1", "<", "1.0.0-a.2", true],
+  ["1.0.0-rc1", "===", "1.0.0-rc1", true],
+  ["1.0.0-rc1", ">", "1.0.0-rc.1", true],
+  ["2.0.0-alpha", ">", "1.9.9", true],
+
+  "# A pre-release and a plain release, compared directly",
+  ["1.0.0", ">", "1.0.0-alpha", true],
+  ["1.0.0", ">=", "1.0.0-rc1", true],
+  ["1.0.0", "!==", "1.0.0-alpha", true],
+  ["1.0.0-alpha", "!==", "1.0.0", true],
+  ["1.0.0-alpha", "<=", "1.0.0", true],
+  ["1.0.0-alpha", ">", "0.9.9", true],
+  ["1.0.0-rc1", "<", "1.0.1", true],
+
+  "# How pre-release identifiers compare, SemVer 2.0.0 item 11",
+  ["1.0.0-2", "<", "1.0.0-10", true],
+  ["1.0.0-1", "<", "1.0.0-alpha", true],
+  ["1.0.0-alpha", "<", "1.0.0-alpha-1", true],
+  ["1.0.0-beta.11", "<", "1.0.0-rc.1", true],
+  ["1.0.0-rc.1", "<", "1.0.0", true],
+  ["1.0.0-alpha.1.2.3", "<", "1.0.0-beta", true],
+  ["1.0.0-beta", ">", "1.0.0-alpha.1", true],
+
+  "# Build metadata is ignored",
+  ["1.0.0+build1", "===", "1.0.0+build2", true],
+  ["1.0.0-alpha+build", "===", "1.0.0-alpha", true],
+  ["1.2.3+build.1-2", "===", "1.2.3", true],
+  ["1.0.0+build1", "!==", "1.0.0+build2", false],
+  ["1.0.0+build1", "<", "1.0.0+build2", false],
+  ["1.0.0+build1", ">", "1.0.0+build2", false],
+  ["1.0.0+build1", "<=", "1.0.0+build2", true],
+  ["1.0.0+build1", ">=", "1.0.0+build2", true],
+  ["1.0.0+build9", "<", "1.0.1+build1", true],
+  ["1.0.1+build1", ">", "1.0.0+build9", true],
+
+  "# Partial versions",
+  ["1.2-alpha", "===", "1.2.0-alpha", true],
+  ["1.2-alpha", "<", "1.3.1", true],
+  ["1.2-alpha", "<", "1.2.0", true],
+  ["1-rc1", "<", "1.0.0", true],
+  ["1.2+build", "===", "1.2.0", true],
+
+  "# Zero versions",
+  ["0.0.0", "===", "0.0.0", true],
+  ["0.0.0", "<", "0.0.1", true],
+  ["0", "===", "0.0.0", true],
+
+  "# A version ending in a bare hyphen is rejected",
+  ["1.0.0-", "===", "1.0.0", false],
+  ["1.0.0-", "!==", "1.0.0", false],
+  ["1.2-", "===", "1.2.0", false],
+  ["1.2-", "!==", "1.2.0", false],
+
+  "# Hyphens inside a pre-release are fine, since they are part of the pre-release identifier",
+  ["1.0.0-alpha-", "<", "1.0.0", true],
+
+  "# Leading zeros are rejected",
+  ["01.2.3", "===", "1.2.3", false],
+  ["01.2.3", "!==", "1.2.3", false],
+  ["1.02.3", "===", "1.2.3", false],
+  ["1.02.3", "!==", "1.2.3", false],
+  ["1.2.03", "===", "1.2.3", false],
+  ["1.2.03", "!==", "1.2.3", false],
+  ["01.02.03", "===", "1.2.3", false],
+  ["01.02.03", "!==", "1.2.3", false],
+
+  "# Leading zeros in a numeric pre-release are rejected too, SemVer 2.0.0 item 9",
+  ["1.2.3-01", "===", "1.2.3", false],
+  ["1.2.3-01", "!==", "1.2.3", false],
+  ["1.2.3-rc.01", "===", "1.2.3", false],
+  ["1.2.3-rc.01", "!==", "1.2.3", false],
+
+  "# A lone zero is a legal pre-release identifier",
+  ["1.2.3-0", "<", "1.2.3", true],
+
+  "# Digits inside a word are still valid",
+  ["1.2.3-rc01", "<", "1.2.3", true],
+
+  "# A leading v is accepted, in either case",
+  ["V1.2.3", "===", "1.2.3", true],
+  ["v1.0.0-alpha", "<", "1.0.0", true],
+  ["v1.2.4", "!==", "1.2.3", true],
+  ["v1.2.3", "<=", "1.2.3", true],
+  ["v1.2.4", ">", "1.2.3", true],
+  ["v1.2.3", ">=", "1.2.3", true],
+
+  "# Missing or wrong-typed values",
+  ["not-a-version", "===", "1.2.3", false],
+  [123, "===", "1.2.3", false],
+  [null, "===", "1.2.3", false],
+
+  "# Malformed versions, checked under both symbols",
+  ["", "===", "1.2.3", false],
+  ["", "!==", "1.2.3", false],
+  ["v", "===", "1.2.3", false],
+  ["v", "!==", "1.2.3", false],
+  ["-1.2.3", "===", "1.2.3", false],
+  ["-1.2.3", "!==", "1.2.3", false],
+  ["1.", "===", "1.2.3", false],
+  ["1.", "!==", "1.2.3", false],
+  ["1.2.3.", "===", "1.2.3", false],
+  ["1.2.3.", "!==", "1.2.3", false],
+  ["1..2", "===", "1.2.3", false],
+  ["1..2", "!==", "1.2.3", false],
+  ["1.2.3.4", "===", "1.2.3", false],
+  ["1.2.3.4", "!==", "1.2.3", false],
+  ["^1.2.3", "===", "1.2.3", false],
+  ["^1.2.3", "!==", "1.2.3", false],
+  ["abc1.2.3", "===", "1.2.3", false],
+  ["abc1.2.3", "!==", "1.2.3", false],
+  ["1.2.3+", "===", "1.2.3", false],
+  ["1.2.3+", "!==", "1.2.3", false],
+  ["1.2.3-alpha..1", "===", "1.2.3", false],
+  ["1.2.3-alpha..1", "!==", "1.2.3", false],
+  ["1.2.3-.", "===", "1.2.3", false],
+  ["1.2.3-.", "!==", "1.2.3", false],
+  ["1.2.3-ALPHA_BETA", "===", "1.2.3", false],
+  ["1.2.3-ALPHA_BETA", "!==", "1.2.3", false],
+  ["vv1.2.3", "===", "1.2.3", false],
+  ["vv1.2.3", "!==", "1.2.3", false],
+
+  "# Operand length cap",
+  ["1.2.3-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "===", "1.2.3", false],
+  ["1.2.3-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "!==", "1.2.3", false],
+  ["1.2.3", "!==", "1.2.3-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", false],
+  ["1.2.3-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "!==", "1.2.3", true]
+]

data/spec/mixpanel-ruby/flags/custom_operators_spec.rb

@@ -0,0 +1,74 @@
+require 'json'
+require 'rspec'
+require 'json_logic'
+require 'mixpanel-ruby/flags/custom_operators'
+
+# The golden vectors are the cross-SDK contract for the custom operators; the canonical copy and its
+# README live in the analytics monorepo. Cases run through JsonLogic.apply so that operator
+# registration is covered alongside the comparison itself.
+#
+# Defined at the top level so the case tables can be built while the describe blocks are collected.
+FIXTURES = File.expand_path('../../fixtures', __dir__)
+
+# The property key the vectors are evaluated against. It is plumbing the spec supplies, so any name
+# works as long as the rule and the data agree on it.
+VECTOR_KEY = 'value'.freeze
+
+def rule_for(operator, symbol, target)
+  { "#{operator}_compare" => [{ 'var' => VECTOR_KEY }, symbol, target] }
+end
+
+# Build the event the rule reads from, omitting the key entirely for an unset property.
+def data_for(subject)
+  subject.nil? ? {} : { VECTOR_KEY => subject }
+end
+
+# Read a golden-vector file. String entries are headings, array entries are cases.
+def load_vectors(operator)
+  entries = JSON.parse(File.read(File.join(FIXTURES, "#{operator}_compare_tests.json")))
+
+  section = ''
+  cases = []
+  entries.each_with_index do |entry, index|
+    if entry.is_a?(String)
+      section = entry
+      next
+    end
+    subject, symbol, target, want = entry
+    name = "#{index} #{section}: #{subject.to_json} #{symbol} #{target.to_json}"
+    cases << [name, rule_for(operator, symbol, target), data_for(subject), want]
+  end
+  cases
+end
+
+SEMVER_CASES = load_vectors('semver')
+DATETIME_CASES = load_vectors('datetime')
+
+describe Mixpanel::Flags::CustomOperators do
+  def apply(rule, data)
+    JsonLogic.apply(rule, data)
+  end
+
+  describe 'semver_compare' do
+    SEMVER_CASES.each do |name, rule, data, want|
+      it name do
+        expect(apply(rule, data)).to eq(want)
+      end
+    end
+  end
+
+  describe 'datetime_compare' do
+    DATETIME_CASES.each do |name, rule, data, want|
+      it name do
+        expect(apply(rule, data)).to eq(want)
+      end
+    end
+  end
+
+  # An unset property must produce an event with no key at all, rather than a key holding a nil.
+  # Both spellings fail closed, so the vectors alone cannot tell them apart.
+  it 'omits the property for an unset subject' do
+    expect(data_for(nil)).to eq({})
+    expect(data_for('1.2.3')).to eq({ VECTOR_KEY => '1.2.3' })
+  end
+end