quonfig 1.7.2 → 1.9.0

data/lib/quonfig/sse_config_client.rb

@@ -34,10 +34,12 @@ module Quonfig
       #
       # sse_initial_reconnect_delay / sse_max_reconnect_delay: backoff bounds.
       # Each failed reconnect doubles the delay (with +/-50% jitter) up to the
-      # max. A successful event delivery resets the delay to the initial
-      # value — matches sdk-python's policy. A clean server-initiated FIN is
-      # treated as "not a failure for backoff purposes" because LBs recycling
-      # connections is normal; the reconnect counter still increments.
+      # max. A connection that delivers its first valid frame (a config
+      # envelope or a keepalive) resets the delay to the initial value. A
+      # clean server-initiated FIN after such a frame is "not a failure for
+      # backoff purposes" because LBs recycling connections is normal; the
+      # reconnect counter still increments. A connection that ends before any
+      # frame is a failed attempt (qfg-goi1.10.43).
       def initialize(sse_read_timeout: 90,
                      sse_connect_timeout: 10,
                      sse_initial_reconnect_delay: 1.0,
@@ -51,10 +53,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
@@ -69,13 +78,22 @@ module Quonfig
 
     # +on_error+: optional callable invoked on every SSE error edge. Parent
     # Quonfig::Client wires this to drive @sse_state -> :error so that
-    # +connection_state+ reflects the disconnect (qfg-47c2.27).
-    def initialize(prefab_options, config_loader, options = nil, logger = nil, on_error: nil)
+    # +connection_state+ reflects the disconnect (qfg-47c2.27). A connection
+    # that ends before its first valid frame, clean EOF included, is an error
+    # edge too (qfg-goi1.10.43).
+    #
+    # +on_connected+: optional callable invoked once per connection, at its
+    # first valid frame (a keepalive, or a data block that validates as a
+    # config envelope), before that frame's envelope reaches +on_envelope+.
+    # Never on the 200 headers alone (supervisor-test-contract.md "Rule — a
+    # connection is `connected` at its first valid frame").
+    def initialize(prefab_options, config_loader, options = nil, logger = nil, on_error: nil, on_connected: nil)
       @prefab_options = prefab_options
       @options = options || Options.new
       @config_loader = config_loader
       @logger = logger || LOG
       @on_error = on_error
+      @on_connected = on_connected
 
       @stopped = Concurrent::AtomicBoolean.new(false)
       @restart_total = 0
@@ -88,6 +106,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,15 +240,23 @@ 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
 
-            connected_at_least_once = false
+            # First-frame rule (qfg-goi1.10.43): this connection counts as
+            # connected only at its first valid frame. Raised once, from the
+            # parser, before the frame's envelope is installed.
+            frame_seen = false
+            on_frame = lambda do
+              next if frame_seen
+
+              frame_seen = true
+              invoke_on_connected
+            end
             begin
-              stream_once do |event|
-                connected_at_least_once = true
+              ended_url = stream_once(on_frame) do |event|
                 # Persist the most recent id so the next reconnect resumes
                 # from there via Last-Event-Id. Updated *before* the user
                 # callback runs so a raising listener still advances the
@@ -239,22 +267,30 @@ module Quonfig
                 # listener must not look like a transport error and trigger
                 # a reconnect.
                 invoke_on_envelope_safely(on_envelope, event)
-                # A connection healthy enough to deliver a real envelope
-                # earns a reset of the backoff. Sustained outages never
-                # reach this branch (no event ever delivered) so the
-                # exponential growth still holds.
-                delay = @options.sse_initial_reconnect_delay
               end
+              # A clean EOF before any frame (200 headers then close) is a
+              # failed attempt, exactly like a connect error: report it so
+              # the client leaves :connected and arms the fallback poller.
+              # This is what bounds ruby's transparent reconnect: connected
+              # survives a clean-EOF reconnect only until the next connection
+              # ends frameless.
+              handle_frameless_end(ended_url) unless frame_seen || @stopped.value
             rescue StandardError => e
               handle_error(e) unless @stopped.value
             end
 
-            # Backoff only grows on failed connect attempts. A server-
-            # initiated clean FIN after a healthy session (normal LB
-            # recycling) reuses the same delay — punishing it would make
-            # us look broken under benign rolling restarts. Matches
-            # sdk-go's `connectedOK` distinction.
-            delay = [delay * 2, @options.sse_max_reconnect_delay].min unless connected_at_least_once
+            # The backoff resets only for a connection that delivered a
+            # frame; it then reconnects at the initial delay even after a
+            # clean FIN (normal LB recycling) or an IO error later in the
+            # session. Every other attempt (connect error, non-200, or a
+            # frameless 200) doubles it. Sustained outages never deliver a
+            # frame, so the exponential growth still holds. Matches sdk-go's
+            # connectOnce "frame seen" result.
+            delay = if frame_seen
+                      @options.sse_initial_reconnect_delay
+                    else
+                      [delay * 2, @options.sse_max_reconnect_delay].min
+                    end
           rescue SSEReadDeadlineExceeded => e
             # Paranoid backstop (qfg-tj18). A watchdog raise that landed
             # outside +stream_once+ — typically in +interruptible_sleep+
@@ -270,7 +306,8 @@ module Quonfig
 
     # Opens one SSE request and yields each parsed event until the stream
     # ends (clean FIN, error, or stop). Raises on transport errors so the
-    # caller can apply backoff. Clean FIN returns without raising.
+    # caller can apply backoff. Clean FIN returns the URL without raising.
+    # +on_frame+ is called at every valid frame (see EventParser#feed).
     #
     # A watchdog thread closes the socket if no bytes arrive within
     # +sse_read_timeout+. Net::HTTP#read_timeout is NOT reliable for the
@@ -279,7 +316,7 @@ module Quonfig
     # against a configured deadline). sdk-go and sdk-node hit the same
     # gotcha and solve it the same way: per-chunk reset, async close on
     # expiry (chaos scenario 02 — sse_silent_stall).
-    def stream_once(&block)
+    def stream_once(on_frame = nil, &block)
       base = current_url
       # f05 latch: record if this connection attempt targets a non-primary
       # stream leg. With the pin in #current_url this is structurally false;
@@ -314,26 +351,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
@@ -343,9 +361,14 @@ module Quonfig
           Thread.handle_interrupt(SSEReadDeadlineExceeded => :immediate) do
             resp.read_body do |chunk|
               watchdog.reset!
-              break if @stopped.value
-
-              parser.feed(chunk, &block)
+              # Never +break+ here (qfg-yrly): a break returns into
+              # Net::HTTPResponse#reading_body, which then calls +body+ to
+              # drain the rest of the response with no block. On an endless
+              # SSE stream that blocks the worker forever. Raising skips the
+              # drain, and Net::HTTP closes the socket on the way out.
+              raise SSEStopRequested if @stopped.value
+
+              parser.feed(chunk, on_frame: on_frame, &block)
             end
           end
           # read_body returned cleanly — either a server-initiated FIN, or
@@ -354,6 +377,9 @@ module Quonfig
           # next iteration.
           @logger.debug "SSE stream ended for url #{url}"
         end
+        url
+      rescue SSEStopRequested
+        url
       ensure
         watchdog.stop
         register_active(nil)
@@ -365,6 +391,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)
@@ -375,8 +430,32 @@ module Quonfig
       @restart_mutex.synchronize { @restart_total += 1 }
     end
 
+    # A connection that returned 200 and ended cleanly before its first valid
+    # frame (qfg-goi1.10.43).
+    def handle_frameless_end(url)
+      err = SSEFramelessSessionError.new
+      @logger.warn "SSE Streaming Error: stream for url #{url} ended before its first frame; " \
+                   'treating it as a failed attempt'
+      invoke_on_error(err)
+    end
+
+    def invoke_on_connected
+      return unless @on_connected
+
+      begin
+        @on_connected.call
+      rescue StandardError => e
+        @logger.error "SSE on_connected callback raised: #{e.inspect}"
+      end
+    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,19 +524,34 @@ 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
+
+    # Passed to on_error when a 200 stream ends cleanly before its first valid
+    # frame (qfg-goi1.10.43). Not raised.
+    class SSEFramelessSessionError < StandardError
+      def initialize(msg = 'SSE stream ended before its first frame')
+        super
+      end
+    end
 
     # Raised by the watchdog into the worker thread when the per-chunk
     # read deadline elapses. Caught by run_loop's rescue, indistinguishable
     # from any other transport error for backoff/restart purposes.
     class SSEReadDeadlineExceeded < StandardError; end
 
+    # Private: raised from inside +read_body+ when +close+ has been called,
+    # so the worker leaves the stream without Net::HTTP draining the body
+    # (qfg-yrly). Rescued in +stream_once+; never reaches callers.
+    class SSEStopRequested < StandardError; end
+    private_constant :SSEStopRequested
+
     # Background watchdog that interrupts the worker thread if no chunk
     # arrives within +deadline_s+ seconds. Uses Thread#raise — the only
     # reliable cross-platform way to unblock a Ruby thread blocked in
@@ -535,7 +629,7 @@ module Quonfig
     #   - chunks that split a line mid-way
     #   - any of CR / LF / CRLF as line terminators
     #   - +data:+, +data: + (optional space per SSE spec)
-    #   - +:comment+ lines (keepalives — ignored)
+    #   - +:comment+ lines (keepalives; a comment-only block is a frame)
     #   - multi-line +data:+ (concatenated with +\n+, per spec)
     # Ignores +event:+ and +retry:+ — api-delivery does not emit them and the
     # Quonfig wire contract does not honor reconnect-time directives.
@@ -548,16 +642,34 @@ module Quonfig
         @data = +''
         @have_data = false
         @id = nil
+        @saw_comment = false
+        @saw_field = false
       end
 
-      def feed(chunk)
+      # Yields each config envelope. +on_frame+ (optional) is called at every
+      # valid frame, before that frame's envelope is yielded. A valid frame is
+      # a block ended by a blank line that is either comment-only (the
+      # +: keepalive+ heartbeat; +:+ alone counts) or carries +data:+ that
+      # decodes and validates as a config envelope. A block cut off by EOF, a
+      # malformed or non-envelope data block, an +id:+-only block and a bare
+      # blank line are not frames (qfg-goi1.10.43).
+      def feed(chunk, on_frame: nil)
         @reader.feed(chunk) do |line|
           if line.empty?
+            comment_only = @saw_comment && !@saw_field
+            @saw_comment = false
+            @saw_field = false
             event = flush
-            yield event if event
+            if event
+              on_frame&.call
+              yield event
+            elsif comment_only
+              on_frame&.call
+            end
           elsif line.start_with?(':')
-            # comment / keepalive — ignore
+            @saw_comment = true
           else
+            @saw_field = true
             process_field(line)
           end
         end
@@ -612,10 +724,18 @@ module Quonfig
           return nil
         end
 
-        envelope = Quonfig::ConfigEnvelope.new(
-          configs: parsed['configs'] || [],
-          meta: parsed['meta'] || {}
-        )
+        meta = parsed['meta'] || {}
+        # Skip one malformed config, keep the rest (qfg-krjt); an event with
+        # no loadable config is dropped like malformed JSON.
+        begin
+          configs = Quonfig::ConfigShape.filter(parsed['configs'] || [], logger: @logger || LOG,
+                                                                         version: meta['version'])
+        rescue Quonfig::ConfigShape::AllInvalidError => e
+          (@logger || LOG).error "SSE Streaming Error: #{e.message}; event dropped"
+          return nil
+        end
+
+        envelope = Quonfig::ConfigEnvelope.new(configs: configs, meta: meta)
         StreamEvent.new(envelope, id, data)
       end
     end
@@ -630,37 +750,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.9.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/weighted_value_resolver.rb

@@ -43,7 +43,9 @@ module Quonfig
     private
 
     def weight_of(variant)
-      variant[:weight] || variant['weight']
+      # A missing weight counts as 0 (qfg-krjt); a present one is checked to
+      # be an Integer at decode (ConfigShape).
+      variant[:weight] || variant['weight'] || 0
     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'
@@ -49,6 +50,7 @@ require 'quonfig/config_store'
 require 'quonfig/evaluator'
 require 'quonfig/resolver'
 require 'quonfig/config_envelope'
+require 'quonfig/config_shape'
 require 'quonfig/config_loader'
 require 'quonfig/datadir'
 require 'listen'