toggly 0.5.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f5f956d153e09adf30a2d8b4ba1fb649322549cea28765622e62712f7d6be8e
-  data.tar.gz: bbd76736bd3dc8158e0873cfda05b3ad628e78ee2e6202a5bdc61878fc5a7ae7
+  metadata.gz: af67c2cd1ab3f935ea72b5f3959e0958f8e7225eb8d176a40fbdb9baf3b3f57d
+  data.tar.gz: 8911b6582910f651d545a1fd625314f7a5aab4c8972188bc31844156ee37882e
 SHA512:
-  metadata.gz: 4a436c80e94da6a310db84d5f36835de8fc79496cd9ed5c62734a79b0376852fd4dc5d0bd2672c1fc66270ddb21c260c857ab099c886cc487bedf94b99d307e0
-  data.tar.gz: 5aa1eed6b7e38353c83b5693d0d71063f47515b50130dee824ccaf7a0d8b932de981f2559e352aca381f5a193ba6515100a1320290b5aba987ff6fdfa59c0cc7
+  metadata.gz: 78ff528d676027bb0379688179b888fae05c567f0a1f57b78982890e07fc3c68cf68c763f0ddd63c8611e21c2aea4bcc0e25d31dde2f33e6ba11adbb52653cf4
+  data.tar.gz: dbe5aad2ad173a579bd7385a24b00a18980be769ea89a46e875ec6ab31d5e5af4246a9ac74789530cc7bf673dd237addee389261e2c5fc515d3989fe520b5653

data/CHANGELOG.md

@@ -5,6 +5,64 @@ 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
+
+- Server-evaluated feature variants (dual-rail). Set `enable_variants: true`
+  on `Config` to additionally fetch `evaluated-variants-signed/{app_key}/
+  {environment}` on its own rail alongside the existing `definitions` /
+  `definitions-signed` pipeline. `definitions` / `definitions-signed` remain
+  the sole source of truth for `enabled?` regardless of `enable_variants` —
+  evaluated variants are additive and only feed `get_variant` /
+  `get_variant_value`; they never override `enabled?`. New `Config` options:
+  `enable_variants`, `variant_identity`, `variant_groups`, `variant_claims`.
+  New `Client#get_variant` / `Client#get_variant_value` return the assigned
+  variant name and `configuration_value`, or `nil` when unassigned or
+  disabled. New `Client#set_variant_identity` updates the `userId` sent to
+  `evaluated-variants-signed` and refreshes.
+- `SnapshotProviders::Base#save_variants` / `#load_variants` (default no-op)
+  so `Memory` and `File` providers persist evaluated variants across
+  restarts, independent of the `definitions` snapshot.
+
+**Note:** the new `get_variant` assignment is unrelated to the existing
+`variant:` 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.
+
 ## [0.5.2] - 2026-09-17
 
 ### Fixed

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,30 +2,23 @@
 
 module Toggly
   class Client
-    # Durable snapshot load/save helpers for Client.
+    # 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 a durable snapshot was applied into memory
+      # @return [Boolean] true when the durable snapshot was applied into memory
       def load_snapshot
         return false unless @config.snapshot_provider
 
-        data = @config.snapshot_provider.load
-        return false unless data
-
-        @mutex.synchronize do
-          @definitions = data[:definitions]
-          @definitions_loaded = true
-        end
-
-        log_debug("Loaded #{@definitions.size} features from snapshot")
-        true
+        load_definitions_snapshot
       rescue StandardError => e
         log_warn("Failed to load snapshot: #{e.message}")
         false
       end
 
-      def save_snapshot
+      def save_definitions_snapshot
         return unless @config.snapshot_provider
 
         @config.snapshot_provider.save(@definitions)
@@ -33,6 +26,19 @@ module Toggly
       rescue StandardError => e
         log_warn("Failed to save snapshot: #{e.message}")
       end
+
+      def load_definitions_snapshot
+        data = @config.snapshot_provider.load
+        return false unless data
+
+        @mutex.synchronize do
+          @definitions = data[:definitions]
+          @definitions_loaded = true
+        end
+
+        log_debug("Loaded #{@definitions.size} features from snapshot")
+        true
+      end
     end
   end
 end

data/lib/toggly/client.rb

@@ -80,7 +80,9 @@ module Toggly
 
       definition = @mutex.synchronize { @definitions[key] }
 
-      # Check defaults if not found
+      # `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
@@ -109,6 +111,54 @@ module Toggly
       !enabled?(feature_key, context: context, default: default.nil? ? nil : !default)
     end
 
+    # 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").
+    #
+    # @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, context: nil)
+      key = feature_key.to_s
+      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: 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, context: nil)
+      get_variant(feature_key, context: context)&.configuration_value
+    end
+
     # Get detailed evaluation result
     #
     # @param feature_key [String, Symbol] The feature key
@@ -161,27 +211,7 @@ module Toggly
       end
 
       begin
-        result = @provider.fetch(force: force)
-        record_refresh_cache_outcome(result.cache_outcome)
-
-        if result.definitions
-          @mutex.synchronize do
-            @definitions = result.definitions
-            @definitions_loaded = true
-            @ready = true
-          end
-
-          save_snapshot
-          log_info("Definitions refreshed (#{result.definitions.size} features)")
-          true
-        else
-          false
-        end
-      rescue StandardError => e
-        log_error("Failed to refresh definitions: #{e.message}")
-        # Network error / timeout keeping last-good revision (incl. empty) — hit.
-        record_definition_cache_hit if definitions_cached?
-        false
+        refresh_definitions_rail(force: force)
       ensure
         drain_pending = false
         @mutex.synchronize do
@@ -290,6 +320,37 @@ module Toggly
 
     private
 
+    # `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
+      log_error("Failed to refresh definitions: #{e.message}")
+      # Network error / timeout keeping last-good revision (incl. empty) — hit.
+      record_definition_cache_hit if definitions_cached?
+      false
+    end
+
+    def refresh_definitions(force:)
+      result = @provider.fetch(force: force)
+      record_refresh_cache_outcome(result.cache_outcome)
+
+      if result.definitions
+        @mutex.synchronize do
+          @definitions = result.definitions
+          @definitions_loaded = true
+          @ready = true
+        end
+
+        save_definitions_snapshot
+        log_info("Definitions refreshed (#{result.definitions.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

data/lib/toggly/definitions_provider.rb

@@ -195,7 +195,7 @@ module Toggly
       when :new_content
         handle_new_content(response, response_etag, response_lm)
       when :error_status
-        handle_error_status(status, response)
+        handle_error_status(status, response, resource: "definitions")
       end
     end
 
@@ -216,12 +216,12 @@ module Toggly
       raise DefinitionsError, "Failed to parse definitions: #{e.message}"
     end
 
-    def handle_error_status(status, response)
+    def handle_error_status(status, response, resource: "definitions")
       case status
       when 401, 403
         raise DefinitionsError, "Authentication failed: #{status}"
       when 404
-        raise DefinitionsError, "Definitions not found (check app_key and environment)"
+        raise DefinitionsError, "#{resource.capitalize} not found (check app_key and environment)"
       else
         raise NetworkError.new(
           "API error: #{status}",

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
 

data/lib/toggly/feature_variant.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module Toggly
+  # A single named variant of a feature flag, as sent on the catalog
+  # (`definitions` / `definitions-signed`) wire alongside `filters`.
+  #
+  # Matches the shape produced by `Microsoft.FeatureManagement`'s
+  # `VariantDefinition` (`Name`, `ConfigurationValue`, `StatusOverride`).
+  class FeatureVariant
+    # Valid `StatusOverride` values (MF `StatusOverride` enum as strings).
+    STATUS_OVERRIDES = %w[None Enabled Disabled].freeze
+
+    # @return [String] Variant name
+    attr_reader :name
+
+    # @return [Object, nil] Untyped configuration payload for this variant
+    attr_reader :configuration_value
+
+    # @return [String] "None" | "Enabled" | "Disabled"
+    attr_reader :status_override
+
+    def initialize(name:, configuration_value: nil, status_override: "None")
+      @name = name.to_s
+      @configuration_value = configuration_value
+      @status_override = STATUS_OVERRIDES.include?(status_override.to_s) ? status_override.to_s : "None"
+    end
+
+    # @param hash [Hash] Variant hash (camelCase wire or snake_case snapshot)
+    # @return [FeatureVariant]
+    def self.from_hash(hash)
+      hash = symbolize_keys(hash)
+      configuration_value = if hash.key?(:configurationValue)
+                              hash[:configurationValue]
+                            else
+                              hash[:configuration_value]
+                            end
+
+      new(
+        name: hash[:name],
+        configuration_value: configuration_value,
+        status_override: hash[:statusOverride] || hash[:status_override] || "None"
+      )
+    end
+
+    # @return [Boolean] True when this variant forces the feature to be
+    #   reported enabled regardless of the base filter-evaluated state.
+    def enabled_override?
+      @status_override == "Enabled"
+    end
+
+    # @return [Boolean] True when this variant forces the feature to be
+    #   reported disabled regardless of the base filter-evaluated state.
+    def disabled_override?
+      @status_override == "Disabled"
+    end
+
+    # @return [Hash]
+    def to_h
+      {
+        name: @name,
+        configuration_value: @configuration_value,
+        status_override: @status_override
+      }
+    end
+
+    def ==(other)
+      other.is_a?(FeatureVariant) &&
+        @name == other.name &&
+        @configuration_value == other.configuration_value &&
+        @status_override == other.status_override
+    end
+    alias eql? ==
+
+    def hash
+      [@name, @configuration_value, @status_override].hash
+    end
+
+    def self.symbolize_keys(hash)
+      return {} unless hash.is_a?(Hash)
+
+      hash.transform_keys { |k| k.is_a?(String) ? k.to_sym : k }
+    end
+    private_class_method :symbolize_keys
+  end
+
+  # Allocation rules for assigning variants to users/groups/percentile
+  # buckets, matching `Microsoft.FeatureManagement`'s `Allocation` schema.
+  class FeatureVariantAllocation
+    # @return [String, nil] Variant assigned when the feature is enabled and
+    #   no user/group/percentile allocation matched.
+    attr_reader :default_when_enabled
+
+    # @return [String, nil] Variant assigned when the feature is disabled.
+    attr_reader :default_when_disabled
+
+    # @return [String, nil] Seed for the percentile hash; falls back to
+    #   "allocation\n{featureName}" when nil.
+    attr_reader :seed
+
+    # @return [Array<Hash>] `[{ variant:, users: [...] }, ...]`
+    attr_reader :user
+
+    # @return [Array<Hash>] `[{ variant:, groups: [...] }, ...]`
+    attr_reader :group
+
+    # @return [Array<Hash>] `[{ variant:, from:, to: }, ...]`
+    attr_reader :percentile
+
+    def initialize(default_when_enabled: nil, default_when_disabled: nil, seed: nil, user: [], group: [], percentile: [])
+      @default_when_enabled = default_when_enabled
+      @default_when_disabled = default_when_disabled
+      @seed = seed
+      @user = Array(user)
+      @group = Array(group)
+      @percentile = Array(percentile)
+    end
+
+    # @param hash [Hash, nil]
+    # @return [FeatureVariantAllocation, nil] nil when +hash+ is nil (no allocation configured)
+    def self.from_hash(hash)
+      return nil unless hash.is_a?(Hash)
+
+      hash = symbolize_keys(hash)
+      new(
+        default_when_enabled: hash[:defaultWhenEnabled] || hash[:default_when_enabled],
+        default_when_disabled: hash[:defaultWhenDisabled] || hash[:default_when_disabled],
+        seed: hash[:seed],
+        user: parse_entries(hash[:user], :users),
+        group: parse_entries(hash[:group], :groups),
+        percentile: parse_percentile_entries(hash[:percentile])
+      )
+    end
+
+    # @return [Hash]
+    def to_h
+      {
+        default_when_enabled: @default_when_enabled,
+        default_when_disabled: @default_when_disabled,
+        seed: @seed,
+        user: @user,
+        group: @group,
+        percentile: @percentile
+      }
+    end
+
+    def ==(other)
+      other.is_a?(FeatureVariantAllocation) &&
+        @default_when_enabled == other.default_when_enabled &&
+        @default_when_disabled == other.default_when_disabled &&
+        @seed == other.seed &&
+        @user == other.user &&
+        @group == other.group &&
+        @percentile == other.percentile
+    end
+    alias eql? ==
+
+    def hash
+      [@default_when_enabled, @default_when_disabled, @seed, @user, @group, @percentile].hash
+    end
+
+    def self.parse_entries(raw, members_key)
+      Array(raw).filter_map do |entry|
+        next unless entry.is_a?(Hash)
+
+        entry = symbolize_keys(entry)
+        { variant: entry[:variant], members_key => Array(entry[members_key]).map(&:to_s) }
+      end
+    end
+    private_class_method :parse_entries
+
+    def self.parse_percentile_entries(raw)
+      Array(raw).filter_map do |entry|
+        next unless entry.is_a?(Hash)
+
+        entry = symbolize_keys(entry)
+        { variant: entry[:variant], from: entry[:from].to_f, to: entry[:to].to_f }
+      end
+    end
+    private_class_method :parse_percentile_entries
+
+    def self.symbolize_keys(hash)
+      return {} unless hash.is_a?(Hash)
+
+      hash.transform_keys { |k| k.is_a?(String) ? k.to_sym : k }
+    end
+    private_class_method :symbolize_keys
+  end
+end

data/lib/toggly/variant_allocator.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Toggly
+  # Catalog-local, MF-parity variant allocator.
+  #
+  # Assigns a feature variant purely from a {FeatureDefinition}'s
+  # `variants` / `allocation` and a targeting context (`identity` + `groups`),
+  # bit-for-bit matching `Microsoft.FeatureManagement` 4.7.0's
+  # `FeatureManager#GetVariantAsync`. Verified against the shared
+  # `variant-allocator-corpus/cases.json` gold corpus.
+  #
+  # This replaces the `evaluated-variants-signed` dual-rail: there is no
+  # network call here — the caller supplies the already filter-evaluated
+  # `enabled` boolean (the same value `Client#enabled?` would return for
+  # this feature/context) and this module does the rest locally.
+  module VariantAllocator
+    module_function
+
+    # Assignment reasons (mirrors MF `AssignmentReason`).
+    REASON_NONE = "None"
+    REASON_USER = "User"
+    REASON_GROUP = "Group"
+    REASON_PERCENTILE = "Percentile"
+    REASON_DEFAULT_WHEN_ENABLED = "DefaultWhenEnabled"
+    REASON_DEFAULT_WHEN_DISABLED = "DefaultWhenDisabled"
+
+    # Result of a variant assignment.
+    #
+    # @!attribute variant_name [String, nil] Assigned variant name, or nil if unassigned
+    # @!attribute configuration_value [Object, nil] The assigned variant's configuration payload
+    # @!attribute enabled [Boolean] Effective enabled flag after StatusOverride is applied
+    # @!attribute reason [String] One of the REASON_* constants above
+    Assignment = Struct.new(:variant_name, :configuration_value, :enabled, :reason, keyword_init: true)
+
+    # Assign a variant for a feature + targeting context.
+    #
+    # @param definition [FeatureDefinition] Feature definition (variants + allocation)
+    # @param enabled [Boolean] The filter-evaluated enabled state for this context
+    #   (i.e. what `EvaluationEngine#evaluate` returns for this definition/context)
+    # @param identity [String, nil] Targeting user id
+    # @param groups [Array<String>] Targeting groups
+    # @param ignore_case [Boolean] MF `TargetingEvaluationOptions.IgnoreCase` parity knob.
+    #   Defaults to `false`, matching Microsoft.FeatureManagement's default.
+    # @return [Assignment]
+    def assign(definition, enabled:, identity: nil, groups: [], ignore_case: false)
+      variants = definition&.variants || []
+      allocation = definition&.allocation
+
+      return build_assignment(nil, variants, enabled, REASON_NONE) if variants.empty?
+
+      unless enabled
+        variant_name = allocation&.default_when_disabled
+        return build_assignment(variant_name, variants, enabled, REASON_DEFAULT_WHEN_DISABLED)
+      end
+
+      variant_name, reason = resolve_enabled_allocation(
+        allocation, identity, groups, ignore_case, definition.feature_key
+      )
+      build_assignment(variant_name, variants, enabled, reason)
+    end
+
+    def resolve_enabled_allocation(allocation, identity, groups, ignore_case, feature_key)
+      return [nil, REASON_DEFAULT_WHEN_ENABLED] unless allocation
+
+      user_variant = match_user(allocation.user, identity, ignore_case)
+      return [user_variant, REASON_USER] if user_variant
+
+      group_variant = match_group(allocation.group, groups, ignore_case)
+      return [group_variant, REASON_GROUP] if group_variant
+
+      percentile_variant = match_percentile(allocation.percentile, allocation.seed, identity, feature_key, ignore_case)
+      return [percentile_variant, REASON_PERCENTILE] if percentile_variant
+
+      [allocation.default_when_enabled, REASON_DEFAULT_WHEN_ENABLED]
+    end
+
+    def match_user(entries, identity, ignore_case)
+      return nil if identity.nil? || identity.to_s.empty?
+
+      Array(entries).each do |entry|
+        users = Array(entry[:users])
+        matched = if ignore_case
+                    users.any? { |u| u.to_s.casecmp?(identity.to_s) }
+                  else
+                    users.include?(identity.to_s)
+                  end
+        return entry[:variant] if matched
+      end
+      nil
+    end
+
+    def match_group(entries, groups, ignore_case)
+      context_groups = Array(groups).map(&:to_s)
+      return nil if context_groups.empty?
+
+      Array(entries).each do |entry|
+        entry_groups = Array(entry[:groups]).map(&:to_s)
+        matched = if ignore_case
+                    entry_groups.any? { |eg| context_groups.any? { |cg| cg.casecmp?(eg) } }
+                  else
+                    entry_groups.intersect?(context_groups)
+                  end
+        return entry[:variant] if matched
+      end
+      nil
+    end
+
+    def match_percentile(entries, seed, identity, feature_key, ignore_case)
+      list = Array(entries)
+      return nil if list.empty?
+
+      pct = compute_percentile(identity, seed, feature_key, ignore_case)
+      list.each do |entry|
+        from = entry[:from].to_f
+        to = entry[:to].to_f
+        matched = to >= 100.0 ? pct >= from : (pct >= from && pct < to)
+        return entry[:variant] if matched
+      end
+      nil
+    end
+
+    # MF-parity percentile hash.
+    #
+    # `contextId = "{userId}\n{hint}"`, `hint = seed` (if non-nil) else
+    # `"allocation\n{featureName}"`. SHA-256 over the UTF-8 bytes; the first
+    # 4 bytes read as a little-endian uint32; `pct = marker / 0xFFFFFFFF * 100`.
+    #
+    # @return [Float] Percentile in [0, 100]
+    def compute_percentile(identity, seed, feature_key, ignore_case)
+      user_id = identity.to_s
+      user_id = user_id.downcase if ignore_case
+      hint = seed.nil? ? "allocation\n#{feature_key}" : seed.to_s
+      context_id = "#{user_id}\n#{hint}"
+
+      digest = Digest::SHA256.digest(context_id)
+      marker = digest.byteslice(0, 4).unpack1("V") # little-endian uint32; unpack1("V") is endian-explicit
+      (marker.to_f / 0xFFFFFFFF) * 100.0
+    end
+
+    def build_assignment(variant_name, variants, base_enabled, reason)
+      variant = Array(variants).find { |v| v.name == variant_name }
+      effective_enabled =
+        if variant&.enabled_override?
+          true
+        elsif variant&.disabled_override?
+          false
+        else
+          base_enabled
+        end
+
+      Assignment.new(
+        variant_name: variant_name,
+        configuration_value: variant&.configuration_value,
+        enabled: effective_enabled,
+        reason: reason
+      )
+    end
+  end
+end

data/lib/toggly/variant_result.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Toggly
+  # Assigned variant for a feature, returned by `Client#get_variant`.
+  #
+  # Assignment is computed locally from the feature's catalog
+  # `variants` / `allocation` (see {VariantAllocator}), matching
+  # `Microsoft.FeatureManagement`'s `IVariantFeatureManager` bit-for-bit.
+  # There is no network round-trip: this is not the `enable_variants`
+  # dual-rail from earlier releases (removed; see CHANGELOG).
+  class VariantResult
+    # @return [String] Variant name
+    attr_reader :name
+
+    # @return [Object, nil] Untyped configuration payload for this variant
+    attr_reader :configuration_value
+
+    # @return [Boolean] Effective enabled flag for this feature/context after
+    #   the variant's `StatusOverride` is applied. This can differ from
+    #   `Client#enabled?`, which stays filter-based only; use this field when
+    #   you need MF-identical `GetVariantAsync`-style effective-enabled
+    #   semantics (e.g. a variant with `StatusOverride: "Enabled"` on an
+    #   otherwise-disabled feature).
+    attr_reader :enabled
+
+    # @return [String] Assignment reason: "User" | "Group" | "Percentile" |
+    #   "DefaultWhenEnabled" | "DefaultWhenDisabled"
+    attr_reader :reason
+
+    def initialize(name:, configuration_value: nil, enabled: true, reason: nil)
+      @name = name
+      @configuration_value = configuration_value
+      @enabled = enabled
+      @reason = reason
+    end
+
+    # @return [Hash]
+    def to_h
+      { name: @name, configuration_value: @configuration_value, enabled: @enabled, reason: @reason }
+    end
+
+    def ==(other)
+      other.is_a?(VariantResult) &&
+        @name == other.name &&
+        @configuration_value == other.configuration_value &&
+        @enabled == other.enabled &&
+        @reason == other.reason
+    end
+    alias eql? ==
+  end
+end

data/lib/toggly/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Toggly
-  VERSION = "0.5.2"
+  VERSION = "1.0.0"
 end

data/lib/toggly.rb

@@ -9,7 +9,10 @@ require_relative "toggly/sticky_hash"
 require_relative "toggly/user_agent_parser"
 require_relative "toggly/context"
 require_relative "toggly/errors"
+require_relative "toggly/feature_variant"
 require_relative "toggly/feature_definition"
+require_relative "toggly/variant_allocator"
+require_relative "toggly/variant_result"
 require_relative "toggly/evaluators/base"
 require_relative "toggly/evaluators/segment_helpers"
 require_relative "toggly/evaluators/always_on"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: toggly
 version: !ruby/object:Gem::Version
-  version: 0.5.2
+  version: 1.0.0
 platform: ruby
 authors:
 - Ops.ai
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-18 00:00:00.000000000 Z
+date: 2026-09-23 00:00:00.000000000 Z
 dependencies: []
 description: High-performance Ruby SDK for Toggly feature flag management. Works with
   or without Toggly.io.
@@ -48,6 +48,7 @@ files:
 - lib/toggly/evaluators/time_window.rb
 - lib/toggly/evaluators/user_claims.rb
 - lib/toggly/feature_definition.rb
+- lib/toggly/feature_variant.rb
 - lib/toggly/http_request_mapper.rb
 - lib/toggly/registry.rb
 - lib/toggly/request_context.rb
@@ -66,6 +67,8 @@ files:
 - lib/toggly/telemetry/runtime_flush.rb
 - lib/toggly/telemetry/usage_batcher.rb
 - lib/toggly/user_agent_parser.rb
+- lib/toggly/variant_allocator.rb
+- lib/toggly/variant_result.rb
 - lib/toggly/version.rb
 - proto/metrics.proto
 - proto/usage.proto