toggly 0.6.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f6a78a0c74623574333be32320578cdd12ee7bf1415ed199c2584716b5e98aa
-  data.tar.gz: c38ea07fda43a2ce57af893804471bd45ac819d51019e47e082aeccf0411e157
+  metadata.gz: af67c2cd1ab3f935ea72b5f3959e0958f8e7225eb8d176a40fbdb9baf3b3f57d
+  data.tar.gz: 8911b6582910f651d545a1fd625314f7a5aab4c8972188bc31844156ee37882e
 SHA512:
-  metadata.gz: 9e6ce90750098dd4d67642925c3239f1a39a43d5f894d6de60949614d5e6c1de662912073001b9e1c1db42cc6baf9fd39e99efbeeb629d71dd92c54420461539
-  data.tar.gz: 3dce06734ce96188493c9fef22d030f17e538f8ae8711a128c5918a7c9c9ecdedd3786e1d6881553b1c962185940523df22a576ec059e8649c670d70053becd2
+  metadata.gz: 78ff528d676027bb0379688179b888fae05c567f0a1f57b78982890e07fc3c68cf68c763f0ddd63c8611e21c2aea4bcc0e25d31dde2f33e6ba11adbb52653cf4
+  data.tar.gz: dbe5aad2ad173a579bd7385a24b00a18980be769ea89a46e875ec6ab31d5e5af4246a9ac74789530cc7bf673dd237addee389261e2c5fc515d3989fe520b5653

data/CHANGELOG.md

@@ -5,6 +5,39 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.0] - 2026-09-23
+
+### Changed (Breaking)
+
+- **Catalog-local, MF-parity feature variants**, replacing the
+  `enable_variants` / `evaluated-variants-signed` dual-rail from 0.6.0.
+  `Client#get_variant` / `#get_variant_value` now assign variants **locally**
+  from the same `variants` / `allocation` payload on the `definitions` /
+  `definitions-signed` catalog that drives `enabled?` — there is no separate
+  network call. Assignment matches `Microsoft.FeatureManagement` 4.7.0's
+  `IVariantFeatureManager` bit-for-bit (user → group → percentile → default,
+  `StatusOverride`, percentile SHA-256 hashing) and is verified against the
+  shared `variant-allocator-corpus/cases.json` gold corpus (100% pass).
+  - `get_variant(feature_key, context: nil)` / `get_variant_value(feature_key,
+    context: nil)` now take the same `context:` (`userId` + `groups`) used by
+    `enabled?`, instead of a client-wide `variant_identity`.
+  - `VariantResult` gains `enabled` (effective enabled after the assigned
+    variant's `StatusOverride` — `enabled?` itself stays filter-based only)
+    and `reason` (`"User"` | `"Group"` | `"Percentile"` |
+    `"DefaultWhenEnabled"` | `"DefaultWhenDisabled"`).
+  - New `FeatureDefinition#variants` / `#allocation` (`FeatureVariant`,
+    `FeatureVariantAllocation`), parsed from the `definitions` wire.
+- **Removed**: `Config#enable_variants` / `#variant_identity` /
+  `#variant_groups` / `#variant_claims` / `#variants_endpoint`,
+  `Client#variant_defs` / `#set_variant_identity`, `EvaluatedVariantDef`,
+  and the `evaluated-variants-signed` fetch/cache rail (including the
+  `SnapshotProviders` `save_variants` / `load_variants` hooks — variants are
+  now part of the ordinary definitions snapshot via `FeatureDefinition`).
+
+**Migration**: drop `enable_variants` / `variant_identity` /
+`set_variant_identity` from your config. Pass targeting via
+`get_variant(key, context: Toggly::Context.new(identity: ..., groups: ...))`.
+
 ## [0.6.0] - 2026-09-22
 
 ### Added

data/README.md

@@ -38,6 +38,28 @@ if client.enabled?(:my_feature)
 end
 ```
 
+## Feature variants (catalog-local, MF-parity)
+
+`get_variant` / `get_variant_value` assign a variant purely from the
+feature's `variants` / `allocation` catalog data (no network round-trip),
+matching `Microsoft.FeatureManagement`'s `IVariantFeatureManager`
+bit-for-bit — verified against the shared
+`variant-allocator-corpus/cases.json` gold corpus.
+
+```ruby
+variant = client.get_variant('checkout-flow', context: Toggly::Context.new(identity: 'user-1'))
+variant&.name                 # assigned variant name, or nil
+variant&.configuration_value  # untyped configuration payload
+variant&.enabled               # effective enabled after StatusOverride
+variant&.reason                # "User" | "Group" | "Percentile" | "DefaultWhenEnabled" | "DefaultWhenDisabled"
+
+client.get_variant_value('checkout-flow', context: context) # shortcut for configuration_value
+```
+
+`enabled?` stays filter-based only. The `enable_variants` /
+`evaluated-variants-signed` dual-rail (and `set_variant_identity`) was
+removed in 1.0 — see [CHANGELOG.md](CHANGELOG.md).
+
 ## Usage & metrics telemetry
 
 When `app_key` is set, usage tracking and metrics default **on** (disable with

data/lib/toggly/client/snapshot_support.rb

@@ -2,31 +2,22 @@
 
 module Toggly
   class Client
-    # Durable snapshot load/save helpers for Client. Dual-rail: `definitions`
-    # is always persisted/restored (sole source of truth for `enabled?`).
-    # `variant_defs` is an additive rail, persisted/restored independently
-    # only when `config.enable_variants` is true — it never replaces the
-    # definitions snapshot.
+    # Durable snapshot load/save helpers for Client. Definitions (including
+    # `variants` / `allocation`) are the only persisted rail — there is no
+    # separate evaluated-variants snapshot (removed with the dual-rail).
     module SnapshotSupport
       private
 
-      # @return [Boolean] true when any durable snapshot rail was applied
-      #   into memory (definitions and/or evaluated variants)
+      # @return [Boolean] true when the durable snapshot was applied into memory
       def load_snapshot
         return false unless @config.snapshot_provider
 
-        definitions_loaded = load_definitions_snapshot
-        variants_loaded = @config.enable_variants && load_variants_snapshot
-
-        definitions_loaded || variants_loaded
+        load_definitions_snapshot
       rescue StandardError => e
         log_warn("Failed to load snapshot: #{e.message}")
         false
       end
 
-      # Persist the definitions rail. Always available regardless of
-      # `config.enable_variants` — definitions remain authoritative for
-      # `enabled?`.
       def save_definitions_snapshot
         return unless @config.snapshot_provider
 
@@ -36,17 +27,6 @@ module Toggly
         log_warn("Failed to save snapshot: #{e.message}")
       end
 
-      # Persist the evaluated-variants rail. Additive only; called only when
-      # `config.enable_variants` is true.
-      def save_variants_snapshot
-        return unless @config.snapshot_provider
-
-        @config.snapshot_provider.save_variants(@variant_defs)
-        log_debug("Saved variants snapshot with #{@variant_defs.size} features")
-      rescue StandardError => e
-        log_warn("Failed to save variants snapshot: #{e.message}")
-      end
-
       def load_definitions_snapshot
         data = @config.snapshot_provider.load
         return false unless data
@@ -59,20 +39,6 @@ module Toggly
         log_debug("Loaded #{@definitions.size} features from snapshot")
         true
       end
-
-      def load_variants_snapshot
-        return false unless @config.snapshot_provider.respond_to?(:load_variants)
-
-        data = @config.snapshot_provider.load_variants
-        return false unless data
-
-        @mutex.synchronize do
-          @variant_defs = data[:variants] || {}
-        end
-
-        log_debug("Loaded #{@variant_defs.size} evaluated variants from snapshot")
-        true
-      end
     end
   end
 end

data/lib/toggly/client.rb

@@ -33,10 +33,6 @@ module Toggly
     # @return [Hash<String, FeatureDefinition>] Current definitions
     attr_reader :definitions
 
-    # @return [Hash<String, EvaluatedVariantDef>] Current evaluated variants
-    #   (populated only when `config.enable_variants` is true)
-    attr_reader :variant_defs
-
     # @return [Boolean] Whether the client is ready
     attr_reader :ready
 
@@ -48,7 +44,6 @@ module Toggly
       @config.validate!
 
       @definitions = {}
-      @variant_defs = {}
       # True once a revision (including empty) or durable snapshot was applied.
       @definitions_loaded = false
       @mutex = Mutex.new
@@ -85,10 +80,9 @@ module Toggly
 
       definition = @mutex.synchronize { @definitions[key] }
 
-      # Dual-rail: definitions/definitions-signed are the sole source of
-      # truth for enabled? — this holds even when config.enable_variants is
-      # true. Evaluated variants (@variant_defs) are an additive rail read
-      # only by get_variant / get_variant_value and never override this.
+      # `enabled?` stays filter-based only (definitions/definitions-signed).
+      # It never reflects a variant's StatusOverride — see `get_variant`
+      # (`VariantResult#enabled`) for MF-identical effective-enabled semantics.
       result = if definition.nil?
                  if !default.nil?
                    default
@@ -117,52 +111,52 @@ module Toggly
       !enabled?(feature_key, context: context, default: default.nil? ? nil : !default)
     end
 
-    # Get the assigned variant for a feature. Requires `config.enable_variants`;
-    # returns nil when variants are disabled, unknown, or unassigned.
+    # Get the assigned variant for a feature, computed locally from the
+    # feature's catalog `variants` / `allocation` (MF-parity, bit-for-bit
+    # with `Microsoft.FeatureManagement`'s `IVariantFeatureManager`). Returns
+    # nil when the feature is unknown, has no variants configured, or no
+    # variant resolves for this context (see {VariantAllocator}).
+    #
+    # There is no network round-trip here — this superseded the
+    # `enable_variants` / `evaluated-variants-signed` dual-rail removed in
+    # 1.0 (see CHANGELOG).
     #
     # NOTE: this is the actual A/B assignment. It is unrelated to the
     # `variant:` telemetry label on `record_usage` / `record_view`, which is
-    # a free-form usage tag (defaults to "enabled"/"disabled") and does not
-    # reflect `evaluated-variants-signed` results.
+    # a free-form usage tag (defaults to "enabled"/"disabled").
     #
     # @param feature_key [String, Symbol] The feature key
+    # @param context [Context, nil] Optional targeting context (userId + groups)
     # @return [VariantResult, nil]
-    def get_variant(feature_key)
-      return nil unless @config.enable_variants
-
+    def get_variant(feature_key, context: nil)
       key = feature_key.to_s
-      entry = @mutex.synchronize { @variant_defs[key] }
-      return nil if entry.nil? || entry.variant.nil? || entry.variant.to_s.empty?
+      definition = @mutex.synchronize { @definitions[key] }
+      return nil if definition.nil?
+
+      enabled = @engine.evaluate(definition, context)
+      assignment = VariantAllocator.assign(
+        definition,
+        enabled: enabled,
+        identity: context&.identity,
+        groups: context&.groups || []
+      )
+      return nil if assignment.variant_name.nil?
 
-      VariantResult.new(name: entry.variant, configuration_value: entry.configuration_value)
+      VariantResult.new(
+        name: assignment.variant_name,
+        configuration_value: assignment.configuration_value,
+        enabled: assignment.enabled,
+        reason: assignment.reason
+      )
     end
 
     # Get the configuration value for the assigned variant, if any.
     #
     # @param feature_key [String, Symbol] The feature key
+    # @param context [Context, nil] Optional targeting context (userId + groups)
     # @return [Object, nil]
-    def get_variant_value(feature_key)
-      get_variant(feature_key)&.configuration_value
-    end
-
-    # Update the `userId` sent to `evaluated-variants-signed` and, when
-    # `config.enable_variants` is true, clear cached variants and refresh.
-    # No-op (besides updating provider state) when variants are disabled.
-    # Named as an action (not `variant_identity=`) because it also triggers
-    # a network refresh — it is not a passive attribute writer.
-    #
-    # @param identity [String, nil]
-    # @return [Boolean] true if the identity changed
-    # rubocop:disable-next Naming/AccessorMethodName
-    def set_variant_identity(identity)
-      changed = @provider.set_variant_identity(identity)
-
-      if changed && @config.enable_variants
-        @mutex.synchronize { @variant_defs = {} }
-        refresh(force: true) unless @config.offline_mode?
-      end
-
-      changed
+    def get_variant_value(feature_key, context: nil)
+      get_variant(feature_key, context: context)&.configuration_value
     end
 
     # Get detailed evaluation result
@@ -217,15 +211,7 @@ module Toggly
       end
 
       begin
-        # Dual-rail: definitions/definitions-signed are always refreshed —
-        # the sole source of truth for enabled?. When config.enable_variants
-        # is true, evaluated-variants-signed is ALSO fetched on its own rail,
-        # additive only for get_variant / get_variant_value. A failure on
-        # either rail must never affect the other.
-        definitions_updated = refresh_definitions_rail(force: force)
-        variants_updated = @config.enable_variants ? refresh_variants_rail(force: force) : false
-
-        definitions_updated || variants_updated
+        refresh_definitions_rail(force: force)
       ensure
         drain_pending = false
         @mutex.synchronize do
@@ -334,9 +320,9 @@ module Toggly
 
     private
 
-    # Definitions rail: `definitions` / `definitions-signed` → local rule eval.
-    # Always runs (dual-rail): the sole source of truth for `enabled?`,
-    # regardless of `config.enable_variants`.
+    # `definitions` / `definitions-signed` → local rule eval. The sole
+    # source of truth for `enabled?`; also carries `variants` / `allocation`
+    # for the catalog-local `get_variant` assignment.
     def refresh_definitions_rail(force:)
       refresh_definitions(force: force)
     rescue StandardError => e
@@ -365,36 +351,6 @@ module Toggly
       end
     end
 
-    # Variants rail: `evaluated-variants-signed` → server-evaluated assignment.
-    # Additive only (used by get_variant / get_variant_value); runs only when
-    # `config.enable_variants` is true and never influences `enabled?`. A
-    # failure here must never affect the definitions rail above, and is not
-    # counted in definition cache-hit/miss telemetry (that metric is scoped
-    # to the definitions rail).
-    def refresh_variants_rail(force:)
-      refresh_variants(force: force)
-    rescue StandardError => e
-      log_error("Failed to refresh evaluated variants: #{e.message}")
-      false
-    end
-
-    def refresh_variants(force:)
-      result = @provider.fetch_variants(force: force)
-
-      if result.variants
-        @mutex.synchronize do
-          @variant_defs = result.variants
-          @ready = true
-        end
-
-        save_variants_snapshot
-        log_info("Evaluated variants refreshed (#{result.variants.size} features)")
-        true
-      else
-        false
-      end
-    end
-
     def initialize_definitions
       # Startup served from durable snapshot before first network — cache hit.
       # Distinct from the subsequent refresh() network outcome (no double-count
@@ -419,7 +375,7 @@ module Toggly
       log_error("Failed to initialize definitions: #{e.message}")
 
       # Use snapshot or defaults as fallback
-      @ready = true if @definitions.any? || @variant_defs.any? || @config.defaults.any?
+      @ready = true if @definitions.any? || @config.defaults.any?
     end
 
     def start_background_refresh

data/lib/toggly/config.rb

@@ -55,25 +55,6 @@ module Toggly
     # @return [Array<String>] Allowed key IDs for signed definitions
     attr_accessor :allowed_key_ids
 
-    # @return [Boolean] When true, additionally fetch server-evaluated variants
-    #   from `evaluated-variants-signed` on their own rail (dual-rail).
-    #   `definitions` / `definitions-signed` remain the sole source of truth
-    #   for `enabled?` regardless of this setting — evaluated variants are
-    #   additive and only feed `Client#get_variant` / `#get_variant_value`.
-    attr_accessor :enable_variants
-
-    # @return [String, nil] `userId` sent to `evaluated-variants-signed` for targeting.
-    #   Separate from the per-call `Context#identity` used for local rule evaluation.
-    attr_accessor :variant_identity
-
-    # @return [Array<String>] Application-wide group memberships sent to
-    #   `evaluated-variants-signed` (not request-local booleans).
-    attr_accessor :variant_groups
-
-    # @return [Hash<String, String>] Application-wide string claims sent to
-    #   `evaluated-variants-signed` (at most 20 on the wire).
-    attr_accessor :variant_claims
-
     # @return [Logger, nil] Logger instance
     attr_accessor :logger
 
@@ -123,10 +104,6 @@ module Toggly
       @snapshot_provider = options[:snapshot_provider]
       @use_signed_definitions = options[:use_signed_definitions] || false
       @allowed_key_ids = options[:allowed_key_ids] || []
-      @enable_variants = options[:enable_variants] || false
-      @variant_identity = options[:variant_identity]
-      @variant_groups = Array(options[:variant_groups])
-      @variant_claims = options[:variant_claims] || {}
       @logger = options[:logger]
 
       @usage_tracking_explicit = options.key?(:enable_usage_tracking)
@@ -150,16 +127,6 @@ module Toggly
       "#{normalize_url(base)}#{endpoint}/#{@app_key}/#{@environment}"
     end
 
-    # Get the evaluated-variants-signed endpoint URL. Always signed; query
-    # params (userId/groups/claims) are added by the provider since they can
-    # change at runtime (see `Client#set_variant_identity`).
-    #
-    # @return [String]
-    def variants_endpoint
-      base = @definitions_url || @base_url
-      "#{normalize_url(base)}evaluated-variants-signed/#{@app_key}/#{@environment}"
-    end
-
     # Validate the configuration
     #
     # @raise [ConfigError] if configuration is invalid
@@ -219,7 +186,6 @@ module Toggly
         enable_undefined_in_dev: @enable_undefined_in_dev,
         disable_background_refresh: @disable_background_refresh,
         enable_live_updates: @enable_live_updates,
-        enable_variants: @enable_variants,
         app_version: @app_version,
         instance_name: @instance_name,
         use_signed_definitions: @use_signed_definitions,

data/lib/toggly/definitions_provider.rb

@@ -17,12 +17,6 @@ module Toggly
     # Result of one HTTP definitions fetch with cache telemetry outcome.
     FetchResult = Struct.new(:definitions, :cache_outcome, keyword_init: true)
 
-    # Result of one HTTP evaluated-variants fetch with cache telemetry outcome.
-    VariantFetchResult = Struct.new(:variants, :cache_outcome, keyword_init: true)
-
-    # Maximum number of string claims sent on the evaluated-variants-signed wire.
-    MAX_VARIANT_CLAIMS = 20
-
     # Fallback HTTP refresh interval when WebSocket is connected (20 minutes)
     FALLBACK_REFRESH_INTERVAL = 20 * 60
 
@@ -43,13 +37,6 @@ module Toggly
       @last_modified = nil
       @last_ts = 0
 
-      # Evaluated-variants rail state — separate ETag/Last-Modified/timestamp
-      # namespace from definitions so the two rails never cross-invalidate.
-      @variant_etag = nil
-      @variant_last_modified = nil
-      @variant_last_ts = 0
-      @variant_identity = config.variant_identity
-
       # WebSocket state
       @ws = nil
       @ws_connected = false
@@ -90,56 +77,6 @@ module Toggly
       @last_ts = 0
     end
 
-    # Fetch server-evaluated variants from `evaluated-variants-signed`.
-    # Independent ETag/timestamp cache from {#fetch} (separate rail).
-    #
-    # @param force [Boolean] Force fetch even if cached
-    # @return [VariantFetchResult] variants (Hash or nil) plus :hit / :miss outcome
-    # @raise [NetworkError] On network failures
-    # @raise [DefinitionsError] On API errors
-    def fetch_variants(force: false)
-      return VariantFetchResult.new(variants: nil, cache_outcome: :hit) if @config.offline_mode?
-
-      uri = URI.parse(build_variant_request_url)
-      http = build_http(uri)
-      request = build_variant_request(uri, force)
-
-      response = http.request(request)
-      handle_variant_response(response)
-    rescue Net::OpenTimeout, Net::ReadTimeout => e
-      raise NetworkError, "Request timeout: #{e.message}"
-    rescue SocketError, Errno::ECONNREFUSED => e
-      raise NetworkError, "Connection failed: #{e.message}"
-    rescue NetworkError, DefinitionsError
-      raise
-    rescue StandardError => e
-      raise NetworkError, "Request failed: #{e.message}"
-    end
-
-    # Update the `userId` sent to `evaluated-variants-signed`. Distinct from
-    # any per-call `Context#identity` used for local rule evaluation. Named
-    # as an action (not `variant_identity=`) because it also invalidates the
-    # variants cache — it is not a passive attribute writer.
-    #
-    # @param identity [String, nil]
-    # @return [Boolean] true if the identity changed (cache invalidated)
-    # rubocop:disable-next Naming/AccessorMethodName
-    def set_variant_identity(identity)
-      normalized = identity&.to_s
-      return false if normalized == @variant_identity
-
-      @variant_identity = normalized
-      reset_variant_cache
-      true
-    end
-
-    # Reset cached variant headers/timestamp (force full fetch next time)
-    def reset_variant_cache
-      @variant_etag = nil
-      @variant_last_modified = nil
-      @variant_last_ts = 0
-    end
-
     # Check whether the periodic refresh should be skipped because the
     # WebSocket connection is active and the fallback interval has not elapsed.
     #
@@ -299,110 +236,6 @@ module Toggly
       @last_modified = last_modified if last_modified && !last_modified.empty?
     end
 
-    def build_variant_request_url
-      pairs = variant_query_pairs
-      base = @config.variants_endpoint
-      pairs.empty? ? base : "#{base}?#{URI.encode_www_form(pairs)}"
-    end
-
-    def variant_query_pairs
-      pairs = []
-      pairs << ["userId", @variant_identity] if @variant_identity && !@variant_identity.empty?
-
-      Array(@config.variant_groups).each do |group|
-        next unless group.is_a?(String)
-
-        trimmed = group.strip
-        pairs << ["g", trimmed] unless trimmed.empty?
-      end
-
-      normalized_claims = {}
-      (@config.variant_claims || {}).each do |key, value|
-        next unless key.is_a?(String) && value.is_a?(String)
-        next if key.empty? || value.empty?
-
-        normalized_claims[key] = value
-      end
-      normalized_claims.keys.sort.first(MAX_VARIANT_CLAIMS).each do |key|
-        pairs << ["claim.#{key}", normalized_claims[key]]
-      end
-
-      pairs
-    end
-
-    def build_variant_request(uri, force)
-      request = Net::HTTP::Get.new(uri)
-      request["Accept"] = "application/json"
-      request["User-Agent"] = "toggly-ruby/#{Toggly::VERSION}"
-      request["X-App-Version"] = @config.app_version if @config.app_version
-      request["X-Instance-Name"] = @config.instance_name if @config.instance_name
-
-      unless force
-        request["If-None-Match"] = @variant_etag if @variant_etag
-        request["If-Modified-Since"] = @variant_last_modified if @variant_last_modified
-      end
-
-      request
-    end
-
-    def handle_variant_response(response)
-      status = response.code.to_i
-      response_etag = response["ETag"]
-      response_lm = response["Last-Modified"]
-      kind = DefinitionCache.classify_http(
-        status,
-        @variant_etag,
-        response_etag,
-        existing_last_modified: @variant_last_modified,
-        response_last_modified: response_lm
-      )
-
-      case kind
-      when :not_modified
-        log_debug("Evaluated variants not modified")
-        VariantFetchResult.new(variants: nil, cache_outcome: :hit)
-      when :same_revision
-        log_debug("Evaluated variants revision matches existing (ETag or Last-Modified)")
-        store_variant_revision_headers(response_etag, response_lm)
-        VariantFetchResult.new(variants: nil, cache_outcome: :hit)
-      when :new_content
-        handle_new_variant_content(response, response_etag, response_lm)
-      when :error_status
-        handle_error_status(status, response, resource: "evaluated variants")
-      end
-    end
-
-    def handle_new_variant_content(response, response_etag, response_lm)
-      data = JSON.parse(response.body)
-      signed_ts = extract_signed_timestamp(data)
-      if DefinitionCache.cached_signed_timestamp?(@variant_last_ts, signed_ts)
-        log_debug("Evaluated variants signed timestamp is not newer than cached revision")
-        store_variant_revision_headers(response_etag, response_lm)
-        return VariantFetchResult.new(variants: nil, cache_outcome: :hit)
-      end
-
-      variants = parse_variant_defs(data)
-      store_variant_revision_headers(response_etag, response_lm)
-      @variant_last_ts = signed_ts if signed_ts&.positive?
-      VariantFetchResult.new(variants: variants, cache_outcome: :miss)
-    rescue JSON::ParserError => e
-      raise DefinitionsError, "Failed to parse evaluated variants: #{e.message}"
-    end
-
-    def store_variant_revision_headers(etag, last_modified)
-      @variant_etag = etag if etag && !etag.empty?
-      @variant_last_modified = last_modified if last_modified && !last_modified.empty?
-    end
-
-    def parse_variant_defs(data)
-      raw = data.is_a?(Hash) ? data["defs"] : nil
-      return {} unless raw.is_a?(Hash)
-
-      raw.each_with_object({}) do |(key, value), hash|
-        hash[key] = EvaluatedVariantDef.from_hash(value) if value.is_a?(Hash)
-      end
-    end
-
     def extract_signed_timestamp(data)
       return nil unless data.is_a?(Hash)
 

data/lib/toggly/feature_definition.rb

@@ -35,6 +35,12 @@ module Toggly
     # @return [String, nil] Feature description
     attr_reader :description
 
+    # @return [Array<FeatureVariant>] Named variants for MF-parity assignment
+    attr_reader :variants
+
+    # @return [FeatureVariantAllocation, nil] Allocation rules for variant assignment
+    attr_reader :allocation
+
     # Feature types
     TYPES = %w[Release Experiment Ops Permission].freeze
 
@@ -50,7 +56,9 @@ module Toggly
       updated_at: nil,
       requirement_type: "Any",
       context_kind: nil,
-      context_requirement_type: nil
+      context_requirement_type: nil,
+      variants: [],
+      allocation: nil
     )
       @feature_key = feature_key.to_s
       @feature_type = validate_type(feature_type)
@@ -63,6 +71,8 @@ module Toggly
       @requirement_type = requirement_type || "Any"
       @context_kind = context_kind
       @context_requirement_type = context_requirement_type
+      @variants = Array(variants)
+      @allocation = allocation
     end
 
     # Create from a hash (e.g., from JSON)
@@ -83,6 +93,9 @@ module Toggly
                   !rules.empty?
                 end
 
+      variants = Array(hash[:variants]).map { |v| FeatureVariant.from_hash(v) }
+      allocation = FeatureVariantAllocation.from_hash(hash[:allocation])
+
       new(
         feature_key: hash[:featureKey] || hash[:feature_key],
         feature_type: hash[:featureType] || hash[:feature_type] || "Release",
@@ -94,7 +107,9 @@ module Toggly
         updated_at: hash[:updatedAt] || hash[:updated_at],
         requirement_type: hash[:requirementType] || hash[:requirement_type] || "Any",
         context_kind: hash[:contextKind] || hash[:context_kind],
-        context_requirement_type: hash[:contextRequirementType] || hash[:context_requirement_type]
+        context_requirement_type: hash[:contextRequirementType] || hash[:context_requirement_type],
+        variants: variants,
+        allocation: allocation
       )
     end
 
@@ -110,7 +125,9 @@ module Toggly
         metadata: @metadata,
         description: @description,
         created_at: @created_at&.iso8601,
-        updated_at: @updated_at&.iso8601
+        updated_at: @updated_at&.iso8601,
+        variants: @variants.map(&:to_h),
+        allocation: @allocation&.to_h
       }
     end