quonfig 0.0.8 → 0.0.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 18707780a8ad33c299973f4de01bc0b76d10161902f977b9771c10c2d4a23fde
-  data.tar.gz: 6980b904632659b97f16636e9a317bc8b3e8cbf02cc0b8f75ecf51325b8ba472
+  metadata.gz: 94866b65b3e3c4e834897981847da01f350984b2f7126f8259318ba385b8fd77
+  data.tar.gz: bc173a4300c1475f596921de2a2d24e02e5de648503318491a602c19123dd329
 SHA512:
-  metadata.gz: 74c6a59b81fd222ddd522e52301ea74a1f9bc76b18ecbfe50c01a46e21539bdc5cea6a38a927938fb497f6003a64a2e796d177f2ed3ee527d5891f6cd9ca63a4
-  data.tar.gz: 94b1c109e6db3df2ea115e62f80f099430752779faa9655ee6f53c20c614fa42ccdc8e350342985cb09861e286bd91b857381508849a81fada865927c98f7f22
+  metadata.gz: 875265c218e5a465abced6d47563ef7c86ade61ca2d98367059bc800dec55e1148badf58e60b632e468ab565ef5ec80e587b8f0fd045f5300b000f64fe12b909
+  data.tar.gz: 6725f7b13ac6ba43d0e7903963c5de4b1bbe03f1ae7e51399e4d0cc8877f6ee637ef2850e396e65c8d5c44cac2ee7cfa0b2f1724d390d43746d421d7e465c42a

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.0.10 - 2026-05-01
+
+- **BREAKING (env): `QUONFIG_TELEMETRY_URL` and `QUONFIG_API_URLS` env vars
+  removed.** Replaced by a single `QUONFIG_DOMAIN` env var (default
+  `quonfig.com`) that derives api, sse, and telemetry URLs uniformly. e.g.
+  `QUONFIG_DOMAIN=quonfig-staging.com` → `https://primary.quonfig-staging.com`,
+  `https://stream.primary.quonfig-staging.com`,
+  `https://telemetry.quonfig-staging.com`. Mirrors the CLI's
+  `domain-urls.ts` convention and matches sdk-go / sdk-node. Resolution order
+  (highest wins): explicit `api_urls:` / `telemetry_url:` kwargs >
+  `QUONFIG_DOMAIN` > hardcoded default. Fixes qfg-w6gg, where the prior
+  primary-prefix regex silently fell through to prod telemetry on staging
+  hosts. The new `Quonfig::Options#init` also accepts an explicit
+  `telemetry_url:` kwarg (was previously documented but not wired up).
+- **Default `api_urls` now includes secondary.** Was `[primary]`, now
+  `[primary, secondary]` to match every other SDK and provide failover.
+
 ## 0.0.8 - 2026-04-26
 
 - **Fix (gemspec): drop deleted `scripts/` entry from manifest** — regenerated

data/CLAUDE.md

@@ -26,4 +26,4 @@ integration suite cannot resolve its YAML specs.
 - `QUONFIG_BACKEND_SDK_KEY` — backend SDK key for authenticated config delivery
 - `QUONFIG_DIR` — path to a local Quonfig workspace (datadir mode)
 - `QUONFIG_ENVIRONMENT` — which environment to evaluate (`production`, `staging`, `development`)
-- `QUONFIG_TELEMETRY_URL` — telemetry ingest endpoint
+- `QUONFIG_DOMAIN` — base domain used to derive api/sse/telemetry URLs (default `quonfig.com`). Setting `QUONFIG_DOMAIN=quonfig-staging.com` derives `https://primary.quonfig-staging.com`, `https://stream.primary.quonfig-staging.com`, and `https://telemetry.quonfig-staging.com` automatically. Explicit `api_urls:` / `telemetry_url:` kwargs override this.

data/README.md

@@ -114,14 +114,14 @@ client = Quonfig::Client.new  # reads QUONFIG_DIR + QUONFIG_ENVIRONMENT
 | `QUONFIG_BACKEND_SDK_KEY`   | SDK key used to authenticate against the Quonfig API. Used when `sdk_key:` is omitted.   |
 | `QUONFIG_DIR`               | Path to a workspace directory. When set, the SDK runs in datadir/offline mode.           |
 | `QUONFIG_ENVIRONMENT`       | Environment name (`production`, `staging`, `development`) evaluated in datadir mode.     |
-| `QUONFIG_TELEMETRY_URL`     | Overrides the telemetry endpoint. Defaults to `https://telemetry.quonfig.com`.           |
+| `QUONFIG_DOMAIN`            | Base domain used to derive api, sse, and telemetry URLs. Defaults to `quonfig.com`. Set to `quonfig-staging.com` to point at staging. Explicit `api_urls:` / `telemetry_url:` kwargs override this. |
 
 ## Constructor options
 
 ```ruby
 Quonfig::Client.new(
   sdk_key:         '...',                          # required unless QUONFIG_BACKEND_SDK_KEY is set
-  api_urls:        ['https://primary.quonfig.com'],
+  api_urls:        ['https://primary.quonfig.com', 'https://secondary.quonfig.com'],
   telemetry_url:   'https://telemetry.quonfig.com',
   enable_sse:      true,
   enable_polling:  false,
@@ -137,8 +137,8 @@ Quonfig::Client.new(
 | Option            | Type                       | Default                                                             | Description                                                                                       |
 |-------------------|----------------------------|---------------------------------------------------------------------|---------------------------------------------------------------------------------------------------|
 | `sdk_key`         | `String`                   | `ENV['QUONFIG_BACKEND_SDK_KEY']`                                    | SDK key for API authentication.                                                                   |
-| `api_urls`        | `Array<String>`            | `['https://primary.quonfig.com']`                                    | Ordered list of API base URLs to try. SSE stream URLs are derived by prepending `stream.` to each hostname. |
-| `telemetry_url`   | `String`                   | `https://telemetry.quonfig.com` (or `ENV['QUONFIG_TELEMETRY_URL']`) | Base URL for the telemetry service.                                                               |
+| `api_urls`        | `Array<String>`            | `["https://primary.${QUONFIG_DOMAIN}", "https://secondary.${QUONFIG_DOMAIN}"]` | Ordered list of API base URLs to try. SSE stream URLs are derived by prepending `stream.` to each hostname. Defaults derive from `QUONFIG_DOMAIN` (default `quonfig.com`). |
+| `telemetry_url`   | `String`                   | `https://telemetry.${QUONFIG_DOMAIN}`                                          | Base URL for the telemetry service. Default derives from `QUONFIG_DOMAIN`.                        |
 | `enable_sse`      | `Boolean`                  | `true`                                                              | Receive real-time updates over Server-Sent Events.                                                |
 | `enable_polling`  | `Boolean`                  | `false`                                                             | Poll the API on an interval as a fallback.                                                        |
 | `poll_interval`   | `Integer` (seconds)        | `60`                                                                | Polling interval when `enable_polling` is `true`.                                                 |

data/VERSION

@@ -1 +1 @@
-0.0.8
+0.0.10

data/lib/quonfig/bound_client.rb

@@ -40,6 +40,32 @@ module Quonfig
       @client.get_json(key, default: default, context: @context)
     end
 
+    # ---- Details getters ----------------------------------------------
+
+    def get_bool_details(key)
+      @client.get_bool_details(key, context: @context)
+    end
+
+    def get_string_details(key)
+      @client.get_string_details(key, context: @context)
+    end
+
+    def get_int_details(key)
+      @client.get_int_details(key, context: @context)
+    end
+
+    def get_float_details(key)
+      @client.get_float_details(key, context: @context)
+    end
+
+    def get_string_list_details(key)
+      @client.get_string_list_details(key, context: @context)
+    end
+
+    def get_json_details(key)
+      @client.get_json_details(key, context: @context)
+    end
+
     def enabled?(feature_name)
       @client.enabled?(feature_name, @context)
     end

data/lib/quonfig/client.rb

@@ -32,7 +32,7 @@ module Quonfig
         else
           Quonfig::Options.new(option_kwargs)
         end
-      @global_context = normalize_context(@options.global_context)
+      @global_context = build_initial_global_context(@options)
       @instance_hash = SecureRandom.uuid
       @store = store || Quonfig::ConfigStore.new
       @evaluator = Quonfig::Evaluator.new(@store, env_id: @options.environment)
@@ -103,6 +103,38 @@ module Quonfig
       typed_get(key, :json, default: default, context: context)
     end
 
+    # ---- Details getters ----------------------------------------------
+    #
+    # Mirrors the typed getters above but returns a +Quonfig::EvaluationDetails+
+    # carrying the OpenFeature-aligned resolution +reason+ ("STATIC",
+    # "TARGETING_MATCH", "SPLIT", "DEFAULT", or "ERROR") plus an
+    # +error_code+/+error_message+ on the error path. These methods never
+    # raise — exceptions are caught and rendered as ERROR details.
+
+    def get_bool_details(key, context: NO_DEFAULT_PROVIDED)
+      evaluate_details(key, :bool, context)
+    end
+
+    def get_string_details(key, context: NO_DEFAULT_PROVIDED)
+      evaluate_details(key, String, context)
+    end
+
+    def get_int_details(key, context: NO_DEFAULT_PROVIDED)
+      evaluate_details(key, Integer, context)
+    end
+
+    def get_float_details(key, context: NO_DEFAULT_PROVIDED)
+      evaluate_details(key, Float, context)
+    end
+
+    def get_string_list_details(key, context: NO_DEFAULT_PROVIDED)
+      evaluate_details(key, :string_list, context)
+    end
+
+    def get_json_details(key, context: NO_DEFAULT_PROVIDED)
+      evaluate_details(key, :json, context)
+    end
+
     def enabled?(feature_name, jit_context = NO_DEFAULT_PROVIDED)
       value = get(feature_name, false, jit_context)
       value == true || value == 'true'
@@ -314,7 +346,7 @@ module Quonfig
         config_key: config_field(config, :key),
         config_type: config_field(config, :type),
         conditional_value_index: result.rule_index,
-        weighted_value_index: nil,
+        weighted_value_index: result.weighted_value_index,
         selected_value: result.unwrapped_value,
         reason: result.wire_reason
       )
@@ -441,6 +473,21 @@ module Quonfig
       merge_contexts(@global_context, jit)
     end
 
+    # Combine the customer-supplied globalContext with the optional dev
+    # context loaded from ~/.quonfig/tokens.json. Dev context goes UNDER the
+    # customer's so any explicit `quonfig-user` keys win on collision.
+    def build_initial_global_context(options)
+      customer = normalize_context(options.global_context)
+      enabled = options.enable_quonfig_user_context == true ||
+                ENV['QUONFIG_DEV_CONTEXT'] == 'true'
+      return customer unless enabled
+
+      dev = Quonfig::DevContext.load_quonfig_user_context
+      return customer if dev.nil?
+
+      merge_contexts(dev, customer)
+    end
+
     def normalize_context(ctx)
       return {} if ctx.nil?
       return ctx if ctx.is_a?(Hash)
@@ -485,6 +532,61 @@ module Quonfig
       nil
     end
 
+    # Build a Quonfig::EvaluationDetails for +key+, evaluated against the
+    # caller's context, after coercing/checking +expected_type+. Never
+    # raises; all exceptions become ERROR details.
+    def evaluate_details(key, expected_type, context)
+      jit = context == NO_DEFAULT_PROVIDED ? nil : context
+      ctx = build_context(jit)
+      record_context_for_telemetry(ctx)
+
+      result =
+        begin
+          @resolver.get(key, ctx)
+        rescue Quonfig::Errors::MissingDefaultError => e
+          return Quonfig::EvaluationDetails.new(
+            value: nil,
+            reason: Quonfig::EvaluationDetails::REASON_ERROR,
+            error_code: Quonfig::EvaluationDetails::ERROR_FLAG_NOT_FOUND,
+            error_message: e.message
+          )
+        end
+
+      if result.nil?
+        return Quonfig::EvaluationDetails.new(
+          value: nil,
+          reason: Quonfig::EvaluationDetails::REASON_DEFAULT
+        )
+      end
+
+      record_evaluation_for_telemetry(result)
+
+      raw_value = result.unwrapped_value
+
+      begin
+        coerced = coerce_and_check(key, raw_value, expected_type) unless raw_value.nil?
+      rescue Quonfig::Errors::TypeMismatchError => e
+        return Quonfig::EvaluationDetails.new(
+          value: nil,
+          reason: Quonfig::EvaluationDetails::REASON_ERROR,
+          error_code: Quonfig::EvaluationDetails::ERROR_TYPE_MISMATCH,
+          error_message: e.message
+        )
+      end
+
+      Quonfig::EvaluationDetails.new(
+        value: coerced,
+        reason: result.of_reason
+      )
+    rescue StandardError => e
+      Quonfig::EvaluationDetails.new(
+        value: nil,
+        reason: Quonfig::EvaluationDetails::REASON_ERROR,
+        error_code: Quonfig::EvaluationDetails::ERROR_GENERAL,
+        error_message: e.message
+      )
+    end
+
     def typed_get(key, expected_type, default:, context:)
       jit = context == NO_DEFAULT_PROVIDED ? NO_DEFAULT_PROVIDED : context
       value = get(key, default, jit)

data/lib/quonfig/dev_context.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Quonfig
+  # Dev-only context loader. Reads ~/.quonfig/tokens.json (written by
+  # `qfg login`) and returns {'quonfig-user' => {'email' => ...}} when a
+  # userEmail is present. Returns nil when the file is missing, unreadable,
+  # or has no userEmail.
+  #
+  # The attribute is dev-only by construction: production servers do not
+  # run `qfg login` and therefore have no tokens file. Rules keyed on
+  # `quonfig-user.email` are dead code in prod.
+  module DevContext
+    TOKENS_BASENAME = File.join('.quonfig', 'tokens.json')
+
+    def self.load_quonfig_user_context
+      path = File.join(Dir.home, TOKENS_BASENAME)
+      return nil unless File.exist?(path)
+
+      raw = begin
+        File.read(path)
+      rescue StandardError => e
+        warn "[quonfig] dev-context: could not read #{path} (#{e.class}: #{e.message}); skipping injection"
+        return nil
+      end
+
+      parsed = begin
+        JSON.parse(raw)
+      rescue JSON::ParserError => e
+        warn "[quonfig] dev-context: could not parse #{path} (#{e.message}); skipping injection"
+        return nil
+      end
+
+      email = parsed.is_a?(Hash) ? parsed['userEmail'] : nil
+      return nil unless email.is_a?(String) && !email.empty?
+
+      { 'quonfig-user' => { 'email' => email } }
+    end
+  end
+end

data/lib/quonfig/evaluation_details.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Quonfig
+  # Public details record returned by Quonfig::Client#get_*_details. Surfaces
+  # the resolution reason and (on error) an error_code/error_message alongside
+  # the resolved value, so downstream layers — most importantly the
+  # OpenFeature provider — can map the result without losing fidelity.
+  #
+  # +reason+ is one of the strings:
+  #   "STATIC"           — config has no targeting rules; matched value is the static default
+  #   "TARGETING_MATCH"  — a targeting rule matched (any non-ALWAYS_TRUE criterion)
+  #   "SPLIT"            — matched value came from a weighted variant
+  #   "DEFAULT"          — no rule matched (eval fell through)
+  #   "ERROR"            — evaluation failed
+  #
+  # +error_code+ (only when reason == "ERROR") is one of:
+  #   "FLAG_NOT_FOUND" — the key was unknown to the store
+  #   "TYPE_MISMATCH"  — the resolved value didn't satisfy the requested type
+  #   "GENERAL"        — any other failure
+  class EvaluationDetails
+    REASON_STATIC          = 'STATIC'
+    REASON_TARGETING_MATCH = 'TARGETING_MATCH'
+    REASON_SPLIT           = 'SPLIT'
+    REASON_DEFAULT         = 'DEFAULT'
+    REASON_ERROR           = 'ERROR'
+
+    ERROR_FLAG_NOT_FOUND = 'FLAG_NOT_FOUND'
+    ERROR_TYPE_MISMATCH  = 'TYPE_MISMATCH'
+    ERROR_GENERAL        = 'GENERAL'
+
+    attr_reader :value, :reason, :error_code, :error_message
+
+    def initialize(value:, reason:, error_code: nil, error_message: nil)
+      @value         = value
+      @reason        = reason
+      @error_code    = error_code
+      @error_message = error_message
+    end
+
+    def ==(other)
+      other.is_a?(EvaluationDetails) &&
+        other.value == @value &&
+        other.reason == @reason &&
+        other.error_code == @error_code &&
+        other.error_message == @error_message
+    end
+    alias eql? ==
+
+    def hash
+      [@value, @reason, @error_code, @error_message].hash
+    end
+
+    def inspect
+      parts = ["value=#{@value.inspect}", "reason=#{@reason.inspect}"]
+      parts << "error_code=#{@error_code.inspect}" if @error_code
+      parts << "error_message=#{@error_message.inspect}" if @error_message
+      "#<Quonfig::EvaluationDetails #{parts.join(' ')}>"
+    end
+  end
+end

data/lib/quonfig/evaluator.rb

@@ -416,14 +416,20 @@ module Quonfig
     REASON_TARGETING_MATCH  = 2
     REASON_SPLIT            = 3
 
-    attr_reader :value, :rule_index, :config
+    attr_reader :value, :rule_index, :config, :reportable_value
     attr_accessor :weighted_value_index
 
-    def initialize(value:, rule_index:, config:, weighted_value_index: nil)
+    def initialize(value:, rule_index:, config:, weighted_value_index: nil, reportable_value: nil)
       @value = value
       @rule_index = rule_index
       @config = config
       @weighted_value_index = weighted_value_index
+      # Telemetry-safe substitute for #unwrapped_value. Set by Resolver when
+      # the underlying Value was confidential / decryptWith, so callers
+      # (the eval-summary aggregator) never see the plaintext. Mirrors
+      # ReforgeHQ/sdk-ruby ConfigValueUnwrapper#reportable_value (the
+      # `*****<5-md5>` hash form).
+      @reportable_value = reportable_value
     end
 
     # Integer reason code for telemetry. Mirrors sdk-node's computeReason:
@@ -436,6 +442,19 @@ module Quonfig
       REASON_TARGETING_MATCH
     end
 
+    # OpenFeature-aligned reason string. Same classification logic as
+    # +wire_reason+ but as a public string the OF provider (and any
+    # third-party consumer of EvaluationDetails) can pass straight through.
+    #
+    # Returns one of: "STATIC", "TARGETING_MATCH", "SPLIT".
+    def of_reason
+      case wire_reason
+      when REASON_STATIC          then EvaluationDetails::REASON_STATIC
+      when REASON_SPLIT           then EvaluationDetails::REASON_SPLIT
+      else                             EvaluationDetails::REASON_TARGETING_MATCH
+      end
+    end
+
     # True if any rule on the config (default or environment) has a
     # non-ALWAYS_TRUE criterion. Used to decide STATIC vs TARGETING_MATCH.
     def self.targeting_rules?(config)

data/lib/quonfig/options.rb

@@ -21,6 +21,7 @@ module Quonfig
     attr_reader :poll_interval
     attr_reader :global_context
     attr_reader :logger_key
+    attr_reader :enable_quonfig_user_context
     attr_accessor :is_fork
 
     module ON_INITIALIZATION_FAILURE
@@ -38,10 +39,38 @@ module Quonfig
     DEFAULT_MAX_EXAMPLE_CONTEXTS = 100_000
     DEFAULT_MAX_EVAL_SUMMARIES = 100_000
 
+    # Hardcoded fallback domain. Overridden by ENV['QUONFIG_DOMAIN'].
+    DEFAULT_DOMAIN = 'quonfig.com'
+
+    # Hardcoded fallback API URLs (used only when no QUONFIG_DOMAIN is set
+    # and no explicit api_urls are provided). Mirrors derive_api_urls(DEFAULT_DOMAIN).
     DEFAULT_API_URLS = [
       'https://primary.quonfig.com',
+      'https://secondary.quonfig.com',
     ].freeze
 
+    # Resolve the active domain. Reads QUONFIG_DOMAIN; falls back to
+    # DEFAULT_DOMAIN. Mirrors `cli/src/util/domain-urls.ts#getDomain`.
+    def self.domain
+      env = ENV['QUONFIG_DOMAIN']
+      env && !env.empty? ? env : DEFAULT_DOMAIN
+    end
+
+    # Derive default api_urls for a given domain. e.g. for domain
+    # `quonfig-staging.com` returns
+    # `["https://primary.quonfig-staging.com", "https://secondary.quonfig-staging.com"]`.
+    def self.derive_api_urls(domain)
+      [
+        "https://primary.#{domain}",
+        "https://secondary.#{domain}",
+      ]
+    end
+
+    # Derive the telemetry URL for a given domain.
+    def self.derive_telemetry_url(domain)
+      "https://telemetry.#{domain}"
+    end
+
     # Derive the SSE stream URL for a given API URL by prepending `stream.` to
     # the hostname. Preserves scheme, port, and path.
     #
@@ -57,6 +86,7 @@ module Quonfig
 
     private def init(
       api_urls: nil,
+      telemetry_url: nil,
       sdk_key: ENV['QUONFIG_BACKEND_SDK_KEY'],
       environment: ENV['QUONFIG_ENVIRONMENT'],
       datadir: ENV['QUONFIG_DIR'],
@@ -74,7 +104,8 @@ module Quonfig
       collect_max_evaluation_summaries: DEFAULT_MAX_EVAL_SUMMARIES,
       allow_telemetry_in_local_mode: false,
       global_context: {},
-      logger_key: nil
+      logger_key: nil,
+      enable_quonfig_user_context: false
     )
       @sdk_key = sdk_key
       @environment = environment
@@ -94,6 +125,7 @@ module Quonfig
       @is_fork = false
       @global_context = global_context
       @logger_key = logger_key
+      @enable_quonfig_user_context = enable_quonfig_user_context
 
       # defaults that may be overridden by context_upload_mode
       @collect_shapes = false
@@ -101,16 +133,19 @@ module Quonfig
       @collect_example_contexts = false
       @collect_max_example_contexts = 0
 
-      if ENV['QUONFIG_API_URLS'] && ENV['QUONFIG_API_URLS'].length > 0
-        api_urls = ENV['QUONFIG_API_URLS']
-      end
+      # URL resolution order (highest wins):
+      #   1. Explicit kwargs (api_urls:, telemetry_url:)
+      #   2. ENV['QUONFIG_DOMAIN'] -> derives all three
+      #   3. Hardcoded DEFAULT_DOMAIN ('quonfig.com')
+      domain = Quonfig::Options.domain
 
-      @api_urls = Array(api_urls || DEFAULT_API_URLS).map { |url| remove_trailing_slash(url) }
+      @api_urls = Array(api_urls || Quonfig::Options.derive_api_urls(domain))
+                    .map { |url| remove_trailing_slash(url) }
 
       @sse_api_urls = @api_urls.map { |url| Quonfig::Options.derive_stream_url(url) }
       @config_api_urls = @api_urls
 
-      @telemetry_destination = ENV['QUONFIG_TELEMETRY_URL'] || derive_telemetry_destination(@api_urls)
+      @telemetry_destination = telemetry_url || Quonfig::Options.derive_telemetry_url(domain)
 
       case context_upload_mode
       when :none
@@ -185,16 +220,5 @@ module Quonfig
     def remove_trailing_slash(url)
       url.end_with?('/') ? url[0..-2] : url
     end
-
-    # Derive a telemetry URL from the configured api_urls by swapping the
-    # primary/secondary host prefix for `telemetry` on a *.quonfig.com host.
-    # Falls back to https://telemetry.quonfig.com if no URL matches.
-    def derive_telemetry_destination(api_urls)
-      api_urls.each do |api_url|
-        match = api_url.match(%r{\Ahttps?://(?:primary|secondary)\.([^/]*quonfig\.com)}i)
-        return "https://telemetry.#{match[1]}" if match
-      end
-      'https://telemetry.quonfig.com'
-    end
   end
 end

data/lib/quonfig/resolver.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'digest'
+
 module Quonfig
   # Public-API resolver: looks up a config by key in a ConfigStore and runs
   # it through an Evaluator against a Context.
@@ -15,6 +17,11 @@ module Quonfig
   # Quonfig::ConfigResolver — the two coexist during the JSON migration.
   class Resolver
     TRUE_VALUES = %w[true 1 t yes].freeze
+    # Prefix the eval-summary aggregator stamps onto redacted confidential
+    # values before the 5-char MD5 hash. Matches CONFIDENTIAL_PREFIX in
+    # ReforgeHQ/sdk-ruby/lib/reforge/config_value_unwrapper.rb so dashboards
+    # built against the predecessor wire format keep working.
+    CONFIDENTIAL_PREFIX = '*****'
 
     attr_reader :store, :evaluator
     attr_accessor :project_env_id
@@ -50,7 +57,8 @@ module Quonfig
         value: resolved_value,
         rule_index: eval_result.rule_index,
         config: config,
-        weighted_value_index: weighted_index
+        weighted_value_index: weighted_index,
+        reportable_value: redacted_reportable_value(eval_result.value)
       )
     end
 
@@ -87,6 +95,26 @@ module Quonfig
 
     private
 
+    # If +value+ is confidential or has a decryptWith key, return the
+    # `*****<5-hex>` redacted string the eval-summary telemetry aggregator
+    # should ship in place of the resolved plaintext. The hash is computed
+    # over the raw `value[:value]` (ciphertext when decryptWith is set,
+    # plaintext-as-stored when only `confidential: true`) — matches
+    # ReforgeHQ/sdk-ruby ConfigValueUnwrapper#reportable_wrapped_value
+    # (CONFIDENTIAL_PREFIX + first 5 chars of MD5).
+    def redacted_reportable_value(value)
+      return nil if value.nil?
+
+      confidential = vget(value, :confidential, 'confidential')
+      decrypt_with = vget(value, :decryptWith, 'decryptWith', :decrypt_with, 'decrypt_with')
+      return nil unless confidential || (decrypt_with && !decrypt_with.to_s.empty?)
+
+      raw = vget(value, :value, 'value')
+      return nil if raw.nil?
+
+      "#{CONFIDENTIAL_PREFIX}#{Digest::MD5.hexdigest(raw.to_s)[0, 5]}"
+    end
+
     def vget(hash, *keys)
       return nil if hash.nil?
 
@@ -179,7 +207,7 @@ module Quonfig
       begin
         plaintext = Quonfig::Encryption.new(secret_key).decrypt(ciphertext)
       rescue StandardError => e
-        raise Quonfig::Errors::DecryptionError.new(config_key(config), e.message)
+        raise Quonfig::Errors::DecryptionError.new(config_key(config), e.message), cause: e
       end
 
       {

data/lib/quonfig/telemetry/telemetry_reporter.rb

@@ -153,11 +153,23 @@ module Quonfig
         @at_exit_registered = true
       end
 
+      # Wait this long for the background reporter thread to exit before
+      # giving up. Bounded so a thread blocked on a dead telemetry endpoint
+      # can't hang process exit.
+      AT_EXIT_THREAD_JOIN_TIMEOUT_SECONDS = 1.0
+
       # Idempotent final drain. Safe to call after #stop has already
       # drained: aggregators return nil when empty and #sync becomes a
-      # no-op.
+      # no-op. Bounded so a stuck reporter thread or dead telemetry
+      # endpoint can't hang process exit.
       def final_drain_on_exit
         @stopped.make_true
+        thread = @thread
+        @thread = nil
+        if thread&.alive?
+          thread.wakeup
+          thread.join(AT_EXIT_THREAD_JOIN_TIMEOUT_SECONDS)
+        end
         sync
       rescue StandardError => e
         LOG.debug "[quonfig] at_exit telemetry drain failed: #{e.class}: #{e.message}"

data/lib/quonfig.rb

@@ -25,6 +25,7 @@ require 'quonfig/error'
 require 'quonfig/duration'
 require 'quonfig/reason'
 require 'quonfig/evaluation'
+require 'quonfig/evaluation_details'
 require 'quonfig/encryption'
 require 'quonfig/exponential_backoff'
 require 'quonfig/periodic_sync'
@@ -39,6 +40,7 @@ require 'quonfig/errors/decryption_error'
 require 'quonfig/errors/missing_environment_error'
 require 'quonfig/errors/invalid_environment_error'
 require 'quonfig/options'
+require 'quonfig/dev_context'
 require 'quonfig/rate_limit_cache'
 require 'quonfig/weighted_value_resolver'
 require 'quonfig/config_store'

data/quonfig.gemspec

@@ -2,16 +2,16 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Juwelier::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
-# stub: quonfig 0.0.8 ruby lib
+# stub: quonfig 0.0.10 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "quonfig".freeze
-  s.version = "0.0.8".freeze
+  s.version = "0.0.10".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
   s.authors = ["Jeff Dwyer".freeze]
-  s.date = "2026-04-26"
+  s.date = "2026-05-01"
   s.description = "Quonfig \u2014 feature flags and live config, stored as files in git.".freeze
   s.email = "jeff@quonfig.com".freeze
   s.extra_rdoc_files = [
@@ -54,6 +54,7 @@ Gem::Specification.new do |s|
     "lib/quonfig/config_store.rb",
     "lib/quonfig/context.rb",
     "lib/quonfig/datadir.rb",
+    "lib/quonfig/dev_context.rb",
     "lib/quonfig/duration.rb",
     "lib/quonfig/encryption.rb",
     "lib/quonfig/error.rb",
@@ -68,6 +69,7 @@ Gem::Specification.new do |s|
     "lib/quonfig/errors/type_mismatch_error.rb",
     "lib/quonfig/errors/uninitialized_error.rb",
     "lib/quonfig/evaluation.rb",
+    "lib/quonfig/evaluation_details.rb",
     "lib/quonfig/evaluator.rb",
     "lib/quonfig/exponential_backoff.rb",
     "lib/quonfig/fixed_size_hash.rb",
@@ -96,6 +98,7 @@ Gem::Specification.new do |s|
     "test/fixtures/datafile.json",
     "test/integration/test_context_precedence.rb",
     "test/integration/test_datadir_environment.rb",
+    "test/integration/test_dev_overrides.rb",
     "test/integration/test_enabled.rb",
     "test/integration/test_enabled_with_contexts.rb",
     "test/integration/test_get.rb",
@@ -119,6 +122,8 @@ Gem::Specification.new do |s|
     "test/test_context_shape.rb",
     "test/test_context_shape_aggregator.rb",
     "test/test_datadir.rb",
+    "test/test_details_getters.rb",
+    "test/test_dev_context.rb",
     "test/test_duration.rb",
     "test/test_encryption.rb",
     "test/test_evaluation_summaries_aggregator.rb",