quonfig 1.8.0 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c41b5b972edb95e3718fc1b46f693cf7a1800900e9228c9fd71542b6a775a001
-  data.tar.gz: c0d0f5f0c25d44b3d580285d0459a73e829827744c89cb5d8d4ab584fb13bc9a
+  metadata.gz: 06b78bb9ba3c5950d54b844388ca57e91c23c7bf4cb595c82c57738e807a1716
+  data.tar.gz: be216cc0d6ea8cee975bc799b94ac2f5a97829dae7fcb4056fded44835deb918
 SHA512:
-  metadata.gz: b215ffbd82dc9bc5aef5211a11e8072ab5556637106dc85c65de50652c81849578b4b738d25d0fd4f0113d12ec39ed7aedd0f71bcf461646499e9b50b6001ede
-  data.tar.gz: 16836a6666e7e6648baa99f73ad4bf9c491638ad9e31d67a66821040f004ba4382ce6d7532fe40674f40c88ab0ccb467f94641b329e4ac5387590647df5be97f
+  metadata.gz: 3abbf9a8a7afe7883670d60869289fab0e1263d56a309713c89dc3d187fe9e8460905ae6d89f98bf3c1bfc17c45d81238abdc3cb693bf892aace508fff06ea59
+  data.tar.gz: fe1b42b9a3b97d41eabad20fd06610d3a7b237226e32b7af76463f98d5ee7425c0efe6958babbe4d9d0ccaf633d5d8b7c0d587a3245f2a9517534133b4691021

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 1.9.0 - 2026-10-20
+
+- **UPGRADE: SSE reports `connected` at the first frame, not at the 200 response (qfg-goi1.10.9).** A stream connection now counts as connected, for `connection_state`, the reconnect backoff and the fallback poller, only after it delivers its first valid frame: a config envelope or a keepalive. Before, it counted as soon as the 200 response headers arrived.
+  - Against Quonfig's servers the headers and the first frame arrive together, so you should see no difference.
+  - `connection_state` now reports `:disconnected` (then `:falling_back`) when the stream ends before any frame, where it used to keep reporting `:connected` on stale config; a keepalive now counts as a live stream, so a quiet workspace no longer starts fallback polling while its stream is healthy.
+  - A connection that closes before any frame is now a failed attempt. The reconnect delay grows, the client reports disconnected, and the fallback poller takes over after its usual threshold.
+
+  Before this change, a server that answered 200 and closed at once left the SDK on stale config indefinitely while `connection_state` reported `:connected`.
+- **UPGRADE: may change returned values. Minor: one config that fails to load no longer raises out of every read of its key (qfg-krjt).** A config whose rule, criterion or default has the wrong shape (for example `rules: ["oops"]`, `criteria: "oops"` or `default: "oops"`), or whose weighted value has a `weight` that is not an integer (a string, float or null), used to install and then raise `NoMethodError` or `TypeError` out of `get`, `enabled?` and the typed getters on every read of that key. That entry is now skipped when the payload is decoded (HTTP, SSE or a datadir file) with a WARN naming its key, the rest installs, and the skipped key reads as not found (your default, `false` from `enabled?`, or `FLAG_NOT_FOUND` in the `*_details` getters). A payload whose every entry fails is still rejected (a failed fetch leg on HTTP, a dropped event on SSE, a load error in datadir mode), so it cannot install as an empty workspace. A weighted value with no `weight` now counts as 0 instead of raising. Matches sdk-go, sdk-node and sdk-python. Test: `test/test_malformed_config_skip.rb`.
+- **Changed (minor): the first-frame rule in the SSE worker (qfg-goi1.10.43).** A keepalive (a comment-only block such as `: keepalive`) now resets the reconnect backoff to its initial delay and cancels the fallback poller's engage timer (or stops an engaged poller), like an envelope; it does not advance `last_successful_refresh`. A 200 stream that ends before its first frame now calls the internal `on_error` path (logged at WARN), so the poller engages at once if SSE never connected, or after 2x the poll interval following a mid-life drop. `connection_state` still stays `:connected` across a clean reconnect after a session that delivered a frame, but only until that next connection either delivers its own first frame or ends without one. Contract: integration-test-data `v2026.10.16.4`, supervisor contract Test 9 (a)-(d) and the Test 2 reset amendment, in `test/test_sse_first_frame.rb`.
+- **Tests: unit and release tests now run integration-test-data `v2026.10.16.4`.** It also moves the two `get_or_raise` init-timeout cases to `http://192.0.2.1:1` (qfg-goi1.6). The chaos workflows stay on `v2026.10.16.2`.
+- **Fix (patch): `Client#stop` no longer leaks the SSE worker thread or waits 2 seconds (qfg-yrly).** Stopping a client with a live stream left the SSE worker blocked forever: the worker left the stream with a `break` inside `read_body`, and Net::HTTP then read the rest of the endless stream to finish the response. `stop` waited 2s for the worker and then returned with the thread still running, and the thread kept the old client alive in memory. The SDK also closes the stream when it enters auth-failed, so each auth-failed entry leaked one thread too. The worker now leaves the stream without that read, so `stop` returns promptly and the thread exits. Tests: `test/test_sse_close_during_stream.rb` (close during a live stream and during a blocked read), and the close assertion in `test/test_sse_config_client.rb` now checks the real worker thread.
+- **Fix (patch): a config update is now applied to the store all at once (qfg-i86q).** The SDK wrote each config of a new envelope into the live store one key at a time, so a request evaluating during that write could see a flag from the new envelope with a segment from the old one, or a key that was briefly missing, and get the wrong value with no error or log. Each install (SSE, polling, the initial fetch and a datadir reload) now builds the new set of configs first and swaps it in with one write, like sdk-go, and each lookup reads one snapshot from start to finish (the flag, its segments and any `decryptWith` key). `ConfigStore` gains `replace_all`; `get`, `set`, `delete`, `keys` and `all_configs` behave as before. Test: `test/test_config_loader_atomic_install.rb` (a reader during 198 installs; before this fix about 40% of its reads were wrong).
+
 ## 1.8.0 - 2026-10-16
 
 - **UPGRADE: retry cadence and log levels change after a rejected 401/403/404/410 fetch cycle; a revoked key logs one config ERROR. `terminal_failure?` changes meaning. Minor (1.8.0): one auth-failure rule across the SDKs (qfg-goi1.10.26). This reverses the qfg-i5xv latch.**
@@ -14,6 +28,7 @@
   - **Whole-number floats compare as plain digits.** In `PROP_IS_ONE_OF` / `PROP_IS_NOT_ONE_OF`, the starts-with / ends-with / contains operators and `HIERARCHICAL_MATCH`, a context value of `1.0`, `1234567.0` or `5e9` now reads as `"1"`, `"1234567"`, `"5000000000"` (it was `"1.0"`, `"1234567.0"`, `"5.0e9"`), so `is one of ["1234567"]` matches it and a list holding `"1.0"` no longer does. Non-integral floats (`1.5`) and Integers are unchanged; booleans still read `"true"` / `"false"`.
   - **Abbreviated versions.** `PROP_SEMVER_*` reads `"2"` as `2.0.0` and `"2.0"` / `"4.1"` as `2.0.0` / `4.1.0`, on the context and the rule side, so an app reporting `"4.1"` now matches a `4.1.0` rule. A prerelease or build suffix still needs the full `x.y.z`, and a `v` prefix is still not a version. `SemanticVersion.parse` itself stays strict.
   Matches integration-test-data `v2026.10.16.1` and the other SDKs.
+  Approved as minors under Decision 1 (qfg-goi1.5, 2026-10-09).
 - **UPGRADE: may change returned values. Minor: JSON values are returned as a fresh copy on every call (qfg-goi1.10.3).** `get`, `get_json` and `get_json_details` (also on `BoundClient`) used to return the SDK's own Hash or Array for a JSON config. If your code changed the result (for example added a key or appended to a list), every later read in the process saw the change. Each call now returns its own copy of the Hashes and Arrays, so changes stay local. What changes for you: two calls no longer return the same object (`equal?` is false; `==` is still true), and code that relied on mutating the result to change config no longer does. Values are not frozen, so code that mutates its own copy keeps working. Strings are not copied: `get_string` and the strings inside a JSON value are the same objects as before. Matches sdk-go, sdk-net and sdk-java.
 - **CI: unit and release tests now run integration-test-data `v2026.10.16.1` (qfg-goi1.5.7).** It adds the OPERATOR EDGES cases (bool and digit-string one-of, int ranges, prerelease and abbreviated semver, strict dates). The chaos workflows stay on `v2026.10.03`.
 - **Fix (patch): `EnvVarParseError` messages now use the cross-SDK wording (qfg-goi1.10.21).** An ENV_VAR value that cannot be converted to the config's type now raises with `environment variable "<NAME>" cannot be converted to <type> for config "<key>"` (for example `... cannot be converted to int for config "my.key"`), the template pinned by integration-test-data `v2026.10.12`. It was `Evaluating <key> couldn't coerce <NAME> to <type>`. A malformed stored duration reads `stored value cannot be converted to duration for config "<key>"`. The value is still never in the message. Only the message text changes; the exception class and when it is raised are unchanged.

data/lib/quonfig/client.rb

@@ -1090,6 +1090,10 @@ module Quonfig
       @sse_error_callback ||= ->(error) { handle_sse_error(error) }
     end
 
+    def sse_connected_callback
+      @sse_connected_callback ||= -> { handle_sse_state_change(:connected) unless @stopped }
+    end
+
     # Every SSE error, auth-class included, is an ordinary drop: SSE alone
     # never enters auth-failed (rule R2, qfg-goi1.10.26; this reverses the
     # qfg-i5xv latch). The fallback poller engages on its usual schedule and
@@ -1273,10 +1277,8 @@ module Quonfig
     # propagates through the auto-reload path. Records a refresh timestamp.
     # Caller is responsible for firing on_update.
     def apply_datadir_envelope(envelope)
-      new_keys = envelope.configs.map { |cfg| cfg['key'] }.compact.to_set
-      old_keys = @store.keys.to_set
-      (old_keys - new_keys).each { |k| @store.delete(k) }
-      envelope.configs.each { |cfg| @store.set(cfg['key'], cfg) }
+      # One atomic swap, like a network install (qfg-i86q).
+      @store.replace_all(envelope.configs.to_h { |cfg| [cfg['key'], cfg] })
       # qfg-pinh: evaluate against the installed envelope's meta.environment,
       # matching sdk-go. In datadir mode the loader stamps meta.environment =
       # the resolved env (the `environment:` pin or QUONFIG_ENVIRONMENT), so
@@ -1494,7 +1496,12 @@ module Quonfig
         @config_loader,
         nil,
         nil,
-        on_error: sse_error_callback
+        on_error: sse_error_callback,
+        # First-frame rule (qfg-goi1.10.43): connected at the connection's
+        # first valid frame, keepalive included, never on the 200 headers.
+        # Cancels the engage timer / disengages the poller without stamping
+        # last_successful_refresh (only an install or fetch does that).
+        on_connected: sse_connected_callback
       )
       @sse_client.start do |envelope, _event, _source|
         next if @stopped

data/lib/quonfig/config_loader.rb

@@ -448,6 +448,11 @@ module Quonfig
       # 200 cannot pin itself through later 304s).
       cycle_log.log(:warn, "Config fetch from #{source} returned a non-envelope 200 (#{e.message}); treating as a failed leg")
       :failed
+    rescue Quonfig::ConfigShape::AllInvalidError => e
+      # qfg-krjt: a payload with no loadable config is a leg error, so it can
+      # never install as an empty workspace.
+      cycle_log.log(:warn, "Config fetch from #{source}: #{e.message}; treating as a failed leg")
+      :failed
     rescue Faraday::ConnectionFailed => e
       @logger.debug "Connection failure fetching configs from #{source}: #{e.message}"
       :failed
@@ -472,10 +477,11 @@ module Quonfig
       data = body.is_a?(String) ? JSON.parse(body) : body
       raise NonEnvelopeError, 'missing meta.version' unless Quonfig::ConfigEnvelope.wire_envelope?(data)
 
-      Quonfig::ConfigEnvelope.new(
-        configs: data['configs'] || [],
-        meta: data['meta'] || {}
-      )
+      meta = data['meta'] || {}
+      # Skip one malformed config, keep the rest (qfg-krjt). Raises
+      # ConfigShape::AllInvalidError when none is loadable.
+      configs = Quonfig::ConfigShape.filter(data['configs'] || [], logger: @logger, version: meta['version'])
+      Quonfig::ConfigEnvelope.new(configs: configs, meta: meta)
     end
 
     def short_body(response)
@@ -565,18 +571,20 @@ module Quonfig
         # (Thread#raise, Timeout) then leaves the held generation where it
         # was, so the same-generation redelivery that follows installs again
         # and repairs the store instead of being ignored as a duplicate.
+        #
+        # The new config set is built off to the side and swapped in with one
+        # reference write (qfg-i86q), so a concurrent lookup never sees a flag
+        # from this envelope with a segment from the last one, or a key that
+        # is momentarily absent.
         unless @store.nil?
-          new_keys = next_map.keys.to_set
-          old_keys = @store.keys.to_set
-          # Drop keys that disappeared server-side.
-          (old_keys - new_keys).each { |k| @store.delete(k) } if @store.respond_to?(:delete)
-
+          next_configs = {}
           envelope.configs.each do |cfg|
             key = config_key(cfg)
             next if key.nil?
 
-            @store.set(key, cfg)
+            next_configs[key] = cfg
           end
+          @store.replace_all(next_configs)
         end
 
         # qfg-9dxb.3 Fix A: an unversioned install (generation <= 0) carries no

data/lib/quonfig/config_shape.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Quonfig
+  # Decode-time shape check for config entries (qfg-krjt; the WS8
+  # skip-one-bad-config rule, as sdk-go 2f6b98b, sdk-node qfg-goi1.10.1 and
+  # sdk-python qfg-goi1.10.5).
+  #
+  # The store keeps raw JSON and the evaluator walks it as Hashes and Arrays,
+  # so a config whose rule, criterion or default has the wrong shape, or whose
+  # weighted value has a non-integer weight, would install and then raise
+  # NoMethodError/TypeError out of every read of that key. Each delivery path
+  # (HTTP, SSE, datadir) runs its configs through .filter instead: a bad entry
+  # is skipped with a WARN naming its key, so the key reads as not found, and
+  # the rest installs. If every entry fails, .filter raises AllInvalidError so
+  # the payload is rejected and can never install as an empty workspace.
+  module ConfigShape
+    LOG = Quonfig::InternalLogger.new(self)
+
+    # Raised by .filter when a non-empty payload has no loadable config.
+    class AllInvalidError < StandardError; end
+
+    module_function
+
+    # Returns the configs that pass #problem, in order. +version+ is only used
+    # in the log line.
+    def filter(configs, logger: nil, version: nil)
+      raise AllInvalidError, 'every config failed to load: configs is not a list' unless configs.is_a?(Array)
+
+      log = logger || LOG
+      first_problem = nil
+      kept = configs.select do |cfg|
+        reason = problem(cfg)
+        next true if reason.nil?
+
+        first_problem ||= reason
+        log.warn "[quonfig] skipping config \"#{key_of(cfg)}\" that failed to load (version #{version}): " \
+                 "#{reason}; other configs are unaffected"
+        false
+      end
+      raise AllInvalidError, "every config failed to load (first: #{first_problem})" if kept.empty? && first_problem
+
+      kept
+    end
+
+    # nil when +cfg+ has a shape the evaluator can walk, else a short reason.
+    def problem(cfg)
+      return 'config entry is not an object' unless cfg.is_a?(Hash)
+
+      key = field(cfg, 'key')
+      return 'config entry has no key' unless key.is_a?(String) && !key.empty?
+
+      default = field(cfg, 'default')
+      unless default.nil?
+        return 'default is not an object' unless default.is_a?(Hash)
+
+        reason = rules_problem(field(default, 'rules'), 'default')
+        return reason if reason
+      end
+
+      env = field(cfg, 'environment')
+      return nil if env.nil?
+      return 'environment is not an object' unless env.is_a?(Hash)
+
+      rules_problem(field(env, 'rules'), 'environment')
+    end
+
+    def rules_problem(rules, where)
+      return nil if rules.nil?
+      return "#{where}.rules is not a list" unless rules.is_a?(Array)
+
+      rules.each_with_index do |rule, i|
+        reason = rule_problem(rule)
+        return "#{where}.rules[#{i}]: #{reason}" if reason
+      end
+      nil
+    end
+
+    def rule_problem(rule)
+      return 'rule is not an object' unless rule.is_a?(Hash)
+
+      criteria = field(rule, 'criteria')
+      unless criteria.nil?
+        return 'criteria is not a list' unless criteria.is_a?(Array)
+
+        criteria.each_with_index do |criterion, i|
+          return "criteria[#{i}] is not an object" unless criterion.is_a?(Hash)
+
+          match = field(criterion, 'valueToMatch')
+          return "criteria[#{i}].valueToMatch is not an object" unless match.nil? || match.is_a?(Hash)
+        end
+      end
+
+      value_problem(field(rule, 'value'))
+    end
+
+    def value_problem(value)
+      return nil if value.nil?
+      return 'value is not an object' unless value.is_a?(Hash)
+      return nil unless field(value, 'type') == 'weighted_values'
+
+      weighted = field(value, 'value')
+      return 'weighted_values value is not an object' unless weighted.is_a?(Hash)
+
+      entries = field(weighted, 'weightedValues')
+      return nil if entries.nil?
+      return 'weightedValues is not a list' unless entries.is_a?(Array)
+
+      entries.each_with_index do |entry, i|
+        return "weightedValues[#{i}] is not an object" unless entry.is_a?(Hash)
+
+        # A missing weight counts as 0; a present one must be an Integer
+        # (sdk-go's int weight fails json.Unmarshal the same way).
+        next unless entry.key?('weight') || entry.key?(:weight)
+        next if field(entry, 'weight').is_a?(Integer)
+
+        return "weightedValues[#{i}].weight must be an integer (got #{field(entry, 'weight').class})"
+      end
+      nil
+    end
+
+    def field(hash, name)
+      return hash[name] if hash.key?(name)
+
+      hash[name.to_sym]
+    end
+
+    def key_of(cfg)
+      return '' unless cfg.is_a?(Hash)
+
+      key = field(cfg, 'key')
+      key.is_a?(String) ? key : ''
+    end
+  end
+end

data/lib/quonfig/config_store.rb

@@ -3,48 +3,94 @@
 module Quonfig
   # In-memory store of configs keyed by config key.
   #
-  # Mirrors sdk-node's ConfigStore (src/store.ts). Integration tests and the
-  # new Resolver/Evaluator trio construct this directly, independent of any
-  # Client/ConfigLoader plumbing.
+  # Integration tests and the Resolver/Evaluator trio construct this
+  # directly, independent of any Client/ConfigLoader plumbing.
   #
-  # Thread-safety: backed by Concurrent::Map, whose per-key reads, writes, and
-  # deletes are atomic. There is no compound multi-key operation here that
-  # needs an outer lock — envelope application in ConfigLoader is a sequence
-  # of independent set/delete calls, and readers tolerate seeing the
-  # in-progress mix. Eventual consistency across an envelope is acceptable
-  # and matches sdk-node behavior.
+  # Thread-safety (qfg-i86q): the store holds one frozen Hash snapshot behind
+  # an AtomicReference. An install builds the next Hash off to the side and
+  # swaps the reference once (#replace_all), so a reader sees the old
+  # envelope or the new one, never a mix. Matches sdk-go runtime_store.go.
+  # #set / #delete / #clear are copy-on-write under a writer mutex, for the
+  # test harness and single-key callers.
+  #
+  # One lookup can read several keys (a flag, then the segments it
+  # references, then a decryptWith key). #pinned holds one snapshot for the
+  # current thread for the duration of a block, so every read in that
+  # lookup comes from the same envelope even if an install swaps the store
+  # mid-evaluation.
   class ConfigStore
+    EMPTY = {}.freeze
+    private_constant :EMPTY
+
     def initialize(initial_configs = nil)
-      @configs = Concurrent::Map.new
+      @write_mutex = Mutex.new
+      @pin_key = :"__quonfig_store_pin_#{object_id}"
+      @snapshot = Concurrent::AtomicReference.new(EMPTY)
       return unless initial_configs
 
-      initial_configs.each { |k, v| @configs[k] = v }
+      replace_all(initial_configs.to_h)
     end
 
     def get(key)
-      @configs[key]
+      snapshot[key]
     end
 
     def set(key, config)
-      @configs[key] = config
+      @write_mutex.synchronize do
+        @snapshot.set(@snapshot.get.merge(key => config).freeze)
+      end
+      config
     end
 
     def delete(key)
-      @configs.delete(key)
+      @write_mutex.synchronize do
+        current = @snapshot.get
+        return nil unless current.key?(key)
+
+        next_map = current.dup
+        value = next_map.delete(key)
+        @snapshot.set(next_map.freeze)
+        value
+      end
     end
 
     def clear
-      @configs.each_key { |k| @configs.delete(k) }
+      replace_all(EMPTY)
+    end
+
+    # Atomically replace every config with +configs+ (a Hash of key =>
+    # config). Readers see either the previous set or this one.
+    def replace_all(configs)
+      next_map = configs.frozen? ? configs : configs.dup.freeze
+      @write_mutex.synchronize { @snapshot.set(next_map) }
+      nil
     end
 
     def keys
-      @configs.keys
+      snapshot.keys
     end
 
     def all_configs
-      h = {}
-      @configs.each_pair { |k, v| h[k] = v }
-      h
+      snapshot.dup
+    end
+
+    # Run the block with this thread's reads pinned to the current snapshot.
+    # Re-entrant: a nested call keeps the outer pin.
+    def pinned
+      return yield if Thread.current[@pin_key]
+
+      Thread.current[@pin_key] = @snapshot.get
+      begin
+        yield
+      ensure
+        Thread.current[@pin_key] = nil
+      end
+    end
+
+    private
+
+    def snapshot
+      Thread.current[@pin_key] || @snapshot.get
     end
   end
 end

data/lib/quonfig/datadir.rb

@@ -50,18 +50,18 @@ module Quonfig
         end
       end
 
+      version = "datadir:#{datadir}"
+      # Skip one malformed config file, keep the rest (qfg-krjt).
       Quonfig::ConfigEnvelope.new(
-        configs: configs,
-        meta: { 'version' => "datadir:#{datadir}", 'environment' => env_id }
+        configs: Quonfig::ConfigShape.filter(configs, version: version),
+        meta: { 'version' => version, 'environment' => env_id }
       )
     end
 
     # Convenience: load the envelope and populate a fresh ConfigStore.
     def load_store(datadir, environment = nil)
       envelope = load_envelope(datadir, environment)
-      store = Quonfig::ConfigStore.new
-      envelope.configs.each { |cfg| store.set(cfg['key'], cfg) }
-      store
+      Quonfig::ConfigStore.new(envelope.configs.to_h { |cfg| [cfg['key'], cfg] })
     end
 
     def resolve_environment(quonfig_path, environment)

data/lib/quonfig/resolver.rb

@@ -47,7 +47,33 @@ module Quonfig
     # the legacy "return nil if absent" shape can rescue and recover (see
     # IntegrationTestHelpers.assert_resolved, which folds a missing-key
     # raise into the test's expected default).
+    # The whole lookup reads one store snapshot (qfg-i86q): the flag, the
+    # segments it references and any decryptWith key all come from the same
+    # envelope even if an install lands mid-evaluation.
     def get(key, context = nil)
+      return get_unpinned(key, context) unless @store.respond_to?(:pinned)
+
+      @store.pinned { get_unpinned(key, context) }
+    end
+
+    # Post-evaluation value resolution. Mirrors sdk-node Resolver#resolveValue
+    # and sdk-go resolver.Resolve:
+    # - "provided" + ENV_VAR  → read ENV[lookup], coerce to config's valueType
+    # - confidential + decryptWith → look up the key config, decrypt
+    # - everything else passes through unchanged
+    def resolve_value(value, config, context = nil, &on_weighted_index)
+      resolve_value_on_path(value, config, context, [], &on_weighted_index)
+    end
+
+    # Integration shims for code that expects a ConfigResolver. Keep these
+    # narrow; the real ConfigResolver still owns the production hot path.
+    def symbolize_json_names?
+      false
+    end
+
+    private
+
+    def get_unpinned(key, context)
       config = raw(key)
       raise Quonfig::Errors::MissingDefaultError, key if config.nil?
 
@@ -75,23 +101,6 @@ module Quonfig
       )
     end
 
-    # Post-evaluation value resolution. Mirrors sdk-node Resolver#resolveValue
-    # and sdk-go resolver.Resolve:
-    # - "provided" + ENV_VAR  → read ENV[lookup], coerce to config's valueType
-    # - confidential + decryptWith → look up the key config, decrypt
-    # - everything else passes through unchanged
-    def resolve_value(value, config, context = nil, &on_weighted_index)
-      resolve_value_on_path(value, config, context, [], &on_weighted_index)
-    end
-
-    # Integration shims for code that expects a ConfigResolver. Keep these
-    # narrow; the real ConfigResolver still owns the production hot path.
-    def symbolize_json_names?
-      false
-    end
-
-    private
-
     # resolve_value plus +key_path+: the config keys already being resolved
     # above this one through decryptWith, so a decryptWith cycle raises a
     # DecryptionError instead of recursing until SystemStackError

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,
@@ -76,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
@@ -234,10 +245,18 @@ module Quonfig
             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
@@ -248,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+
@@ -279,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
@@ -288,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;
@@ -333,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
@@ -344,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)
@@ -394,6 +430,25 @@ 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)
       if error.is_a?(SSEHTTPAuthError)
         # Already logged once by check_response_status! (R5).
@@ -478,11 +533,25 @@ module Quonfig
     # 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
@@ -560,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.
@@ -573,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
@@ -637,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

data/lib/quonfig/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Quonfig
-  VERSION = '1.8.0'
+  VERSION = '1.9.0'
 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.rb

@@ -50,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'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: quonfig
 version: !ruby/object:Gem::Version
-  version: 1.8.0
+  version: 1.9.0
 platform: ruby
 authors:
 - Jeff Dwyer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-16 00:00:00.000000000 Z
+date: 2026-10-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -90,6 +90,7 @@ files:
 - lib/quonfig/client.rb
 - lib/quonfig/config_envelope.rb
 - lib/quonfig/config_loader.rb
+- lib/quonfig/config_shape.rb
 - lib/quonfig/config_store.rb
 - lib/quonfig/context.rb
 - lib/quonfig/datadir.rb