quonfig 1.7.2 → 1.8.0

data/lib/quonfig/errors/env_var_parse_error.rb

@@ -3,7 +3,9 @@
 module Quonfig
   module Errors
     class EnvVarParseError < Quonfig::Error
-      def initialize(_env_var, config, env_var_name)
+      # +stored: true+ marks a malformed stored value (no env var involved);
+      # the message then names the stored value rather than a variable.
+      def initialize(_env_var, config, env_var_name, stored: false)
         key, value_type =
           if config.is_a?(Hash)
             [config[:key] || config['key'],
@@ -12,8 +14,13 @@ module Quonfig
             [config.key, config.value_type]
           end
         # +_env_var+ (the raw value) is deliberately left out of the message:
-        # an env var or stored value can be a secret (qfg-goi1.2.11).
-        super("Evaluating #{key} couldn't coerce #{env_var_name} to #{value_type}")
+        # an env var or stored value can be a secret (qfg-goi1.2.11). The
+        # wording is the cross-SDK template pinned by integration-test-data
+        # (v2026.10.12): it names the variable, the lowercase type and the
+        # config key, never the value or a parser message quoting it.
+        type_name = value_type.to_s.downcase
+        source = stored ? 'stored value' : %(environment variable "#{env_var_name}")
+        super(%(#{source} cannot be converted to #{type_name} for config "#{key}"))
       end
     end
   end

data/lib/quonfig/evaluator.rb

@@ -54,6 +54,16 @@ module Quonfig
     OP_IS_PRESENT                      = 'IS_PRESENT'
     OP_IS_NOT_PRESENT                  = 'IS_NOT_PRESENT'
 
+    MAX_SAFE_INTEGER = (2**53) - 1
+
+    # Timestamp grammar for PROP_BEFORE / PROP_AFTER; see #date_to_millis.
+    INTEGER_STRING = /\A-?[0-9]+\z/
+    RFC3339_TIMESTAMP = /
+      \A(?<y>[0-9]{4})-(?<mo>[0-9]{2})-(?<d>[0-9]{2})
+      T(?<h>[0-9]{2}):(?<mi>[0-9]{2}):(?<s>[0-9]{2})(?:\.(?<frac>[0-9]+))?
+      (?:Z|(?<sign>[+-])(?<oh>[0-9]{2}):(?<om>[0-9]{2}))\z
+    /x
+
     MAGIC_CURRENT_TIME_PROPS = %w[quonfig.current-time prefab.current-time reforge.current-time].freeze
 
     # PROP_MATCHES / PROP_DOES_NOT_MATCH match timeout (qfg-goi1.2.11). Ruby
@@ -282,8 +292,8 @@ module Quonfig
       when OP_PROP_SEMVER_LESS_THAN, OP_PROP_SEMVER_EQUAL, OP_PROP_SEMVER_GREATER_THAN
         mv = hget(match_value, :value)
         if context_exists && context_value.is_a?(String) && mv.is_a?(String)
-          sv_ctx = SemanticVersion.parse_quietly(context_value)
-          sv_mv  = SemanticVersion.parse_quietly(mv)
+          sv_ctx = SemanticVersion.parse_quietly(context_value, allow_abbreviated: true)
+          sv_mv  = SemanticVersion.parse_quietly(mv, allow_abbreviated: true)
           if sv_ctx && sv_mv
             cmp = (sv_ctx <=> sv_mv)
             case operator
@@ -356,12 +366,27 @@ module Quonfig
 
     # --- Type coercion helpers ----------------------------------------
 
+    # Canonical string form (qfg-goi1.5 R1) for *_ONE_OF, the string
+    # operators and HIERARCHICAL_MATCH: strings as-is, booleans as
+    # "true"/"false", and an integral number below 2^53 as plain digits
+    # whatever its runtime type, so 1.0 is "1" and 5e9 is "5000000000"
+    # (Float#to_s would give "1.0" and "5.0e9").
     def to_s_nil(v)
       return '' if v.nil?
+      return v if v.is_a?(String)
+      return canonical_number(v) if v.is_a?(Numeric) && !v.is_a?(Integer)
 
       v.to_s
     end
 
+    def canonical_number(v)
+      return v.to_s unless v.real?
+      return v.to_s if v.respond_to?(:finite?) && !v.finite?
+      return v.to_s unless v == v.truncate && v.abs <= MAX_SAFE_INTEGER
+
+      v.to_i.to_s
+    end
+
     def to_string_slice(v)
       return [] if v.nil?
       return v.map { |i| to_s_nil(i) } if v.is_a?(Array)
@@ -414,21 +439,43 @@ module Quonfig
       [start_v || min, end_v || max]
     end
 
+    # The ONE timestamp grammar for PROP_BEFORE / PROP_AFTER (qfg-goi1.5 R5),
+    # applied to both the context value and the criterion: a number (epoch
+    # ms, truncated), an all-digit string (epoch ms), or RFC3339 with an
+    # uppercase T and a Z or numeric offset (fractional seconds allowed,
+    # truncated to ms). Date-only, offset-less and free-form strings are not
+    # timestamps and never match. This replaces DateTime.parse, which read
+    # any of those (offset-less as UTC).
     def date_to_millis(val)
       case val
-      when Integer, Float
-        val.to_i
+      when Integer
+        val
+      when Float
+        val.finite? ? val.to_i : nil
       when String
-        # Try ISO-8601 / RFC3339 first, fall back to integer-string.
-        begin
-          t = DateTime.parse(val)
-          return (t.to_time.to_f * 1000).to_i
-        rescue ArgumentError, TypeError
-          # not a date; try integer
-        end
-        Integer(val, exception: false)
+        return Integer(val, 10) if INTEGER_STRING.match?(val)
+
+        rfc3339_to_millis(val)
+      end
+    end
+
+    def rfc3339_to_millis(str)
+      m = RFC3339_TIMESTAMP.match(str)
+      return nil if m.nil?
+
+      y, mo, d, h, mi, s = %i[y mo d h mi s].map { |k| m[k].to_i }
+      return nil unless Date.valid_date?(y, mo, d) && h <= 23 && mi <= 59 && s <= 59
+
+      offset_seconds = 0
+      if m[:sign]
+        oh = m[:oh].to_i
+        om = m[:om].to_i
+        return nil if oh > 23 || om > 59
 
+        offset_seconds = ((oh * 3600) + (om * 60)) * (m[:sign] == '-' ? -1 : 1)
       end
+      epoch_seconds = Time.utc(y, mo, d, h, mi, s).to_i - offset_seconds
+      (epoch_seconds * 1000) + (m[:frac] || '').ljust(3, '0')[0, 3].to_i
     end
   end
 
@@ -540,8 +587,11 @@ module Quonfig
       when 'log_level'   then raw.is_a?(Numeric) ? raw : raw.to_s
       when 'duration'    then duration_to_millis(raw)
       when 'json'
-        # JSON values must be native JS/Ruby types on the wire.
-        raw
+        # JSON values must be native JS/Ruby types on the wire. Hashes and
+        # Arrays are copied so a caller mutating the result cannot rewrite
+        # the cached config for every later read (qfg-goi1.10.3, sdk-go
+        # qfg-9dxb.6). Leaf values (strings included) are not copied.
+        copy_json_containers(raw)
       else
         raw
       end
@@ -555,6 +605,14 @@ module Quonfig
 
     private
 
+    def copy_json_containers(value)
+      case value
+      when Hash then value.to_h { |k, v| [k, copy_json_containers(v)] }
+      when Array then value.map { |v| copy_json_containers(v) }
+      else value
+      end
+    end
+
     # Coerce an ISO 8601 duration value (e.g. "PT0.2S", "P1DT6H2M1.5S")
     # to integer milliseconds. The wire format may either be a bare ISO
     # string in `value` or the structured `{ seconds, nanos }` proto-style

data/lib/quonfig/resolver.rb

@@ -56,15 +56,21 @@ module Quonfig
 
       weighted_index = nil
       hash_missing = []
-      resolved_value = resolve_value_on_path(eval_result.value, config, context, [], hash_missing) do |idx|
+      selected_variants = []
+      resolved_value = resolve_value_on_path(eval_result.value, config, context, [], hash_missing,
+                                             selected_variants) do |idx|
         weighted_index = idx
       end
+      # Redact from the selected rollout variant, not only the outer
+      # weighted_values wrapper (which is never flagged), so a confidential or
+      # decryptWith variant never reaches telemetry in plaintext (qfg-goi1.2.39).
+      reportable = redacted_reportable_value(eval_result.value) || redacted_reportable_value(selected_variants.last)
       EvalResult.new(
         value: resolved_value,
         rule_index: eval_result.rule_index,
         config: config,
         weighted_value_index: weighted_index,
-        reportable_value: redacted_reportable_value(eval_result.value),
+        reportable_value: reportable,
         hash_property_missing: !hash_missing.empty?
       )
     end
@@ -91,15 +97,21 @@ module Quonfig
     # DecryptionError instead of recursing until SystemStackError
     # (qfg-9dxb.7, matching sdk-go qfg-9dxb.4). +hash_missing+, when given,
     # gets an entry for each weighted rollout whose hash property was missing
-    # from the context (qfg-9dxb.8).
-    def resolve_value_on_path(value, config, context, key_path, hash_missing = nil, &on_weighted_index)
+    # from the context (qfg-9dxb.8). +selected_variants+, when given, gets the
+    # stored (pre-resolution) Value of each weighted variant picked, so get()
+    # can redact a confidential/decryptWith variant (qfg-goi1.2.39).
+    def resolve_value_on_path(value, config, context, key_path, hash_missing = nil, selected_variants = nil,
+                              &on_weighted_index)
       return nil if value.nil?
 
       type = vget(value, :type, 'type')
 
       return resolve_provided(value, config) if type == 'provided'
 
-      return resolve_weighted(value, config, context, key_path, hash_missing, &on_weighted_index) if type == 'weighted_values'
+      if type == 'weighted_values'
+        return resolve_weighted(value, config, context, key_path, hash_missing, selected_variants,
+                                &on_weighted_index)
+      end
 
       confidential = vget(value, :confidential, 'confidential')
       decrypt_with = vget(value, :decryptWith, 'decryptWith', :decrypt_with, 'decrypt_with')
@@ -184,7 +196,8 @@ module Quonfig
     # nil) hashes an empty value, the same bucket as a present "", and warns
     # once per config key (qfg-9dxb.8). With no hash property configured the
     # pick stays random per call.
-    def resolve_weighted(value, config, context, key_path, hash_missing = nil, &on_weighted_index)
+    def resolve_weighted(value, config, context, key_path, hash_missing = nil, selected_variants = nil,
+                         &on_weighted_index)
       payload = vget(value, :value, 'value') || {}
       weighted = vget(payload, :weightedValues, 'weightedValues', :weighted_values, 'weighted_values')
       return value unless weighted.is_a?(Array) && !weighted.empty?
@@ -213,7 +226,9 @@ module Quonfig
       variant, index = picker.resolve
       on_weighted_index&.call(index)
       variant_value = vget(variant, :value, 'value')
-      resolve_value_on_path(variant_value, config, context, key_path, hash_missing, &on_weighted_index)
+      selected_variants&.push(variant_value)
+      resolve_value_on_path(variant_value, config, context, key_path, hash_missing, selected_variants,
+                            &on_weighted_index)
     end
 
     def warn_hash_property_missing(cfg_key, hash_property)

data/lib/quonfig/semver.rb

@@ -18,6 +18,11 @@ class SemanticVersion
     $
   /x
 
+  # Abbreviated "x" and "x.y" (qfg-goi1.5 Q5), read as x.0.0 and x.y.0 by
+  # the PROP_SEMVER_* operators, matching LaunchDarkly. A prerelease or build
+  # suffix needs the full x.y.z.
+  ABBREVIATED_PATTERN = /\A(?<major>0|[1-9]\d*)(?:\.(?<minor>0|[1-9]\d*))?\z/
+
   attr_reader :major, :minor, :patch, :prerelease, :build_metadata
 
   def self.parse(version_string)
@@ -36,7 +41,12 @@ class SemanticVersion
     )
   end
 
-  def self.parse_quietly(version_string)
+  def self.parse_quietly(version_string, allow_abbreviated: false)
+    if allow_abbreviated && version_string.is_a?(String)
+      match = ABBREVIATED_PATTERN.match(version_string)
+      return new(major: match[:major].to_i, minor: match[:minor].to_i, patch: 0) if match
+    end
+
     parse(version_string)
   rescue ArgumentError
     nil

data/lib/quonfig/sse_config_client.rb

@@ -51,10 +51,17 @@ module Quonfig
 
     LOG = Quonfig::InternalLogger.new(self)
 
-    # qfg-i5xv: HTTP status codes the SDK classifies as terminal — these will
-    # not heal by retrying (bad key, revoked permission, missing endpoint).
-    # Anything else (5xx, 429, network errors) stays on the transient path.
-    TERMINAL_HTTP_CODES = [401, 403, 404].freeze
+    # Auth-class statuses (rule R1, qfg-goi1.10.26). On the stream they keep the
+    # normal reconnect ladder: SSE alone never stops retrying and never enters
+    # auth-failed (R2); the client's fallback poller decides that from a whole
+    # fetch cycle. They only get their own log line: WARN once per status,
+    # re-armed by a 200, DEBUG otherwise (R5).
+    AUTH_HTTP_CODES = [401, 403, 404, 410].freeze
+
+    # @deprecated since 1.8.0. qfg-i5xv's "terminal" codes. Nothing is terminal
+    # any more (the latch is gone, qfg-goi1.10.26); kept as an alias of
+    # AUTH_HTTP_CODES for code that references the constant.
+    TERMINAL_HTTP_CODES = AUTH_HTTP_CODES
 
     # qfg-6y44: headroom added to +sse_read_timeout+ when configuring
     # Net::HTTP#read_timeout. The ReadDeadlineWatchdog already covers both the
@@ -88,6 +95,8 @@ module Quonfig
       @active_http = nil
 
       @last_event_id = nil
+      # Auth-class statuses already logged at WARN since the last 200 (R5).
+      @auth_warned = Set.new
       # qfg-7h5d.1.9 / qfg-41nh.6: latches true if a connection attempt ever
       # targets a non-primary sse_api_urls leg. The failover epic asserts SSE
       # does NOT fail over to the secondary (f05) — the stream is PINNED to
@@ -220,7 +229,7 @@ module Quonfig
           begin
             unless first_attempt
               increment_restart!
-              interruptible_sleep(jittered(delay))
+              interruptible_sleep(jittered(Quonfig::Waits.duration(:sse, delay)))
               break if @stopped.value
             end
             first_attempt = false
@@ -314,26 +323,7 @@ module Quonfig
 
       begin
         http.request(req) do |resp|
-          code = resp.code.to_i
-          if TERMINAL_HTTP_CODES.include?(code)
-            # qfg-i5xv: 401/403/404 will not heal by retrying — bad key,
-            # revoked permission, or wrong endpoint. Mark stopped *before*
-            # invoking on_error so the loop's terminal-error branch is
-            # already locked in if the parent callback inspects state, and
-            # so the inner rescue's `handle_error(e) unless @stopped.value`
-            # guard suppresses a second on_error edge.
-            err = SSEHTTPTerminalError.new(code)
-            @logger.error "SSE Streaming Terminal Error: HTTP #{code} for url #{url}; will not retry"
-            @stopped.make_true
-            invoke_on_error(err)
-            raise err
-          end
-          if code != 200
-            err = SSEHTTPStatusError.new(code)
-            @logger.error "SSE Streaming Error: HTTP #{code} for url #{url}"
-            invoke_on_error(err)
-            raise err
-          end
+          check_response_status!(resp.code.to_i, url)
 
           parser = EventParser.new
           # qfg-tj18: run_loop wraps the body in +:on_blocking+ which
@@ -365,6 +355,35 @@ module Quonfig
       end
     end
 
+    # Classify the stream response. Raises for any non-200 so run_loop applies
+    # its backoff.
+    #
+    # Auth class (401/403/404/410, qfg-goi1.10.26): no latch. The normal
+    # ladder applies and run_loop's handle_error fires on_error once, so the
+    # client schedules the fallback poller exactly as for any drop; that
+    # poller's fetch cycle is what decides auth-failed (R2). Logged WARN once
+    # per status until a 200 re-arms it, DEBUG otherwise (R5), so a revoked
+    # key does not log two ERRORs per attempt for the ~2 min before entry.
+    def check_response_status!(code, url)
+      if AUTH_HTTP_CODES.include?(code)
+        if @auth_warned.add?(code)
+          @logger.warn "SSE Streaming Error: HTTP #{code} for url #{url}; " \
+                       'the SDK key may be invalid or revoked (check the SDK key); retrying'
+        else
+          @logger.debug "SSE Streaming Error: HTTP #{code} for url #{url}; retrying"
+        end
+        raise SSEHTTPAuthError, code
+      end
+      if code != 200
+        err = SSEHTTPStatusError.new(code)
+        @logger.error "SSE Streaming Error: HTTP #{code} for url #{url}"
+        invoke_on_error(err)
+        raise err
+      end
+
+      @auth_warned.clear
+    end
+
     # Track the active connection so close() can interrupt a blocked
     # read_body from another thread. Guarded by @conn_mutex.
     def register_active(http)
@@ -376,7 +395,12 @@ module Quonfig
     end
 
     def handle_error(error)
-      @logger.error "SSE Streaming Error: #{error.inspect}"
+      if error.is_a?(SSEHTTPAuthError)
+        # Already logged once by check_response_status! (R5).
+        @logger.debug "SSE Streaming Error: #{error.inspect}"
+      else
+        @logger.error "SSE Streaming Error: #{error.inspect}"
+      end
       invoke_on_error(error)
     end
 
@@ -445,13 +469,14 @@ module Quonfig
       end
     end
 
-    # qfg-i5xv: terminal HTTP failures the SDK will not retry. 401 = bad key,
-    # 403 = revoked workspace permission, 404 = wrong endpoint / missing
-    # workspace. A subclass of SSEHTTPStatusError so existing on_error
-    # callbacks that only check `is_a?(SSEHTTPStatusError)` keep working,
-    # while customers that want to distinguish (alerting, OpenFeature
-    # provider error events) can dispatch on the subclass.
-    class SSEHTTPTerminalError < SSEHTTPStatusError; end
+    # An auth-class (401/403/404/410) stream response (qfg-goi1.10.26). A
+    # subclass of SSEHTTPStatusError so on_error callbacks that only check
+    # `is_a?(SSEHTTPStatusError)` keep working. The stream keeps retrying.
+    class SSEHTTPAuthError < SSEHTTPStatusError; end
+
+    # @deprecated since 1.8.0: qfg-i5xv's name for SSEHTTPAuthError. The stream
+    # no longer stops on these statuses.
+    SSEHTTPTerminalError = SSEHTTPAuthError # rubocop:disable Lint/UselessConstantScoping
 
     # Raised by the watchdog into the worker thread when the per-chunk
     # read deadline elapses. Caught by run_loop's rescue, indistinguishable
@@ -630,37 +655,59 @@ module Quonfig
       def initialize
         @buffer = +''.b
         @last_was_cr = false
+        # Bytes of @buffer already scanned without finding a terminator, so
+        # the next feed resumes there instead of rescanning from byte 0
+        # (qfg-goi1.10.2; O(n^2) on a long line in small chunks).
+        @scanned = 0
       end
 
+      # Lines are sliced out by position and the consumed prefix is dropped
+      # once per feed (in +ensure+, so a raising block does not see a line
+      # twice), not once per line.
       def feed(chunk)
         @buffer << chunk.b
-        loop do
-          idx = @buffer.index(/[\r\n]/)
-          break if idx.nil?
+        pos = 0
+        begin
+          loop do
+            idx = @buffer.index(/[\r\n]/, [pos, @scanned].max)
+            if idx.nil?
+              @scanned = @buffer.bytesize
+              break
+            end
 
-          ch = @buffer[idx]
-          if idx.zero? && ch == "\n" && @last_was_cr
-            # Dangling LF of a CRLF pair split across chunks — consume and skip.
-            @last_was_cr = false
-            @buffer.slice!(0, 1)
-            next
-          end
+            ch = @buffer.getbyte(idx)
+            if idx == pos && ch == LF && @last_was_cr
+              # Dangling LF of a CRLF pair split across chunks — consume and skip.
+              @last_was_cr = false
+              pos += 1
+              next
+            end
 
-          line = @buffer[0, idx].force_encoding('UTF-8')
-          consume = idx + 1
-          @last_was_cr = false
-          if ch == "\r"
-            if consume == @buffer.bytesize
-              # CR at end of buffer — could be CRLF split across feeds.
-              @last_was_cr = true
-            elsif @buffer[consume] == "\n"
-              consume += 1
+            line = @buffer.byteslice(pos, idx - pos).force_encoding('UTF-8')
+            consume_to = idx + 1
+            @last_was_cr = false
+            if ch == CR
+              if consume_to == @buffer.bytesize
+                # CR at end of buffer — could be CRLF split across feeds.
+                @last_was_cr = true
+              elsif @buffer.getbyte(consume_to) == LF
+                consume_to += 1
+              end
             end
+            pos = consume_to
+            yield line
+          end
+        ensure
+          if pos.positive?
+            @buffer = @buffer.byteslice(pos, @buffer.bytesize - pos)
+            @scanned = [@scanned - pos, 0].max
           end
-          @buffer.slice!(0, consume)
-          yield line
         end
       end
+
+      CR = 13
+      LF = 10
+      private_constant :CR, :LF
     end
   end
 end

data/lib/quonfig/stdlib_formatter.rb

@@ -74,7 +74,7 @@ module Quonfig
         path = logger_name || progname
         level = SEVERITY_TO_LEVEL[severity.to_s.upcase] || :info
 
-        if client.should_log?(logger_path: path, desired_level: level)
+        if emit?(client, path, level)
           format_record(severity, datetime, progname, msg)
         else
           ''
@@ -82,6 +82,17 @@ module Quonfig
       end
     end
 
+    # The formatter runs inside the host app's Logger calls and must never
+    # raise out of them. A resolution error (unset ENV_VAR, decryption
+    # failure, ...) emits the line, matching SemanticLoggerFilter
+    # (qfg-goi1.2.11, qfg-goi1.2.28). Nothing is logged here, since logging
+    # from inside a formatter can recurse.
+    def self.emit?(client, path, level)
+      client.should_log?(logger_path: path, desired_level: level)
+    rescue StandardError
+      true
+    end
+
     # Default record formatter. Matches ::Logger::Formatter's general shape
     # ("I, [timestamp pid] SEVERITY -- progname: message") but without the
     # process-id first-letter noise so output is readable in tests and

data/lib/quonfig/telemetry/example_contexts_aggregator.rb

@@ -15,6 +15,10 @@ module Quonfig
       # prunes expired entries, and is not recorded if it is still full.
       SEEN_CAP = 100_000
 
+      # Max nesting depth copied from a context value; deeper levels are left
+      # out. Guards the recursive copy against stack exhaustion.
+      MAX_SNAPSHOT_DEPTH = 32
+
       attr_reader :data, :cache
 
       def initialize(max_contexts:, rate_limit_seconds: ONE_HOUR_SECONDS, seen_cap: SEEN_CAP)
@@ -38,7 +42,7 @@ module Quonfig
         return unless room_in_cache?
 
         @cache.set(key)
-        @data.push([Quonfig::TimeHelpers.now_in_ms, context])
+        @data.push([Quonfig::TimeHelpers.now_in_ms, snapshot(context)])
       end
 
       def prepare_data
@@ -65,6 +69,19 @@ module Quonfig
 
       private
 
+      # Copy +context+ into plain JSON-safe data at record time (qfg-goi1.2.35).
+      # The caller owns its nested Hashes/Arrays and may mutate them after
+      # get() returns, while the window is serialized later on the reporter
+      # thread. NaN/Infinity become nil, and an edge that closes a cycle is
+      # left out, so one bad value no longer makes JSON.generate raise and drop
+      # the whole window. Any other object is rendered with #to_s, which is
+      # what JSON.generate already sent for it (a UUID-like key keeps the
+      # example reportable); one whose #to_s raises is left out.
+      def snapshot(context)
+        named = contexts_to_list(context)
+        named.to_h { |entry| [entry['type'], snapshot_value(entry['values'], 0, {})] }
+      end
+
       def room_in_cache?
         return true if @cache.data.size < @seen_cap
 
@@ -102,6 +119,43 @@ module Quonfig
         end
       end
 
+      OMIT = Object.new.freeze
+      private_constant :OMIT
+
+      def snapshot_value(value, depth, ancestors)
+        case value
+        when nil, true, false, Integer then value
+        when Float then value.finite? ? value : nil
+        when String then value.frozen? ? value : value.dup
+        when Symbol then value.to_s
+        when Hash, Array then snapshot_container(value, depth, ancestors)
+        else value.to_s
+        end
+      rescue StandardError
+        OMIT
+      end
+
+      # +ancestors+ holds the containers on the current path only, so the same
+      # value reached twice without a cycle is still copied both times.
+      def snapshot_container(value, depth, ancestors)
+        id = value.object_id
+        return OMIT if depth >= MAX_SNAPSHOT_DEPTH || ancestors.key?(id)
+
+        ancestors[id] = true
+        begin
+          if value.is_a?(Hash)
+            value.each_with_object({}) do |(k, v), acc|
+              copied = snapshot_value(v, depth + 1, ancestors)
+              acc[k.to_s] = copied unless copied.equal?(OMIT)
+            end
+          else
+            value.map { |v| snapshot_value(v, depth + 1, ancestors) }.reject { |v| v.equal?(OMIT) }
+          end
+        ensure
+          ancestors.delete(id)
+        end
+      end
+
       def stringify_values(hash)
         return {} unless hash.is_a?(Hash)
 

data/lib/quonfig/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Quonfig
-  VERSION = '1.7.2'
+  VERSION = '1.8.0'
 end

data/lib/quonfig/waits.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Quonfig
+  # Internal test seam for the SDK's background waits (qfg-goi1.10.26).
+  #
+  # Every long background wait goes through here with a kind:
+  #   :sse    - SSE reconnect backoff (the unjittered base delay)
+  #   :engage - fallback-poller grace after a mid-life SSE drop
+  #   :poll   - fallback / polling-mode poll interval
+  #   :probe  - auth-failed probe period (rule R3)
+  #
+  # A hook, when set, sees the REQUESTED seconds and returns the seconds to
+  # actually wait. Tests use it to record the requested values and compress
+  # time (supervisor-test-contract.md Test 8). It is not a customer option and
+  # is nil in production.
+  module Waits
+    class << self
+      attr_accessor :hook
+
+      def duration(kind, seconds)
+        h = hook
+        h ? h.call(kind, seconds) : seconds
+      end
+
+      def sleep(kind, seconds)
+        Kernel.sleep(duration(kind, seconds))
+      end
+    end
+  end
+end

data/lib/quonfig/worker_supervisor.rb

@@ -95,6 +95,11 @@ module Quonfig
         t
       end
       return if thread.nil?
+      # Called from the worker itself (the poller leaving auth-failed hands
+      # back to SSE, qfg-goi1.10.26): the flag is enough. The worker returns,
+      # run_loop sees stop? and exits without a restart. Raising into or
+      # joining the current thread would kill it mid-handoff.
+      return if thread == Thread.current
 
       raise_shutdown(thread)
       thread.join(SHUTDOWN_TIMEOUT_SEC)

data/lib/quonfig.rb

@@ -29,6 +29,7 @@ require 'quonfig/evaluation'
 require 'quonfig/evaluation_details'
 require 'quonfig/encryption'
 require 'quonfig/exponential_backoff'
+require 'quonfig/waits'
 require 'quonfig/worker_supervisor'
 require 'quonfig/periodic_sync'
 require 'quonfig/errors/initialization_timeout_error'