quonfig 1.11.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d1016bb1930249b2a74a4f670e25cb2143ff0e664edd54062c585437a85527a
-  data.tar.gz: 8e2e0844f5853cf5c1d27f45054e71dc6cda6f8f5aa398468c982a485659d1b8
+  metadata.gz: 939842e745249a0ce6cee689801a6fe3a7cbdc56552ad88bdabaa0c36e79ef92
+  data.tar.gz: df5b171629c4b6c556f04b80a0035d5726c76929e78d11ba5382332d0e4b2293
 SHA512:
-  metadata.gz: 705580a318dd7d773b6b0b01236f0509b6d60f440e44e21d07228de7ce6915d71c9ffe9c9c60a6a4c50ed95ed39018727bbb2ed89389610d4df8c9058b196f48
-  data.tar.gz: a9e69afa6be50db19b7508e9224203dda7c62ef522d1b591d2d7050ffdd69cbef217433791330fead5435c9ebe9fcbd364c245be5127ff9fbb1443e74be6a586
+  metadata.gz: 4c6822328fa6147d3816b404fe9543991d7095a5f663a2dc045f425113daba93f18da02e739c32dfce962858b00c190809acf4a62e56f1f049669bf813d8cdcd
+  data.tar.gz: 04a636c09573823cf0895c3cbbdcd2d9d79f22b875a877e55587244a2077bf1ae054007b729cc64bb8a2208e806fbdb962a7c55be38f2663c015b41d2685e09d

data/CHANGELOG.md

@@ -1,5 +1,105 @@
 # Changelog
 
+## 2.1.0 - 2026-10-29
+
+- **Added: `evaluate_details(key, context:)`, an untyped details read (qfg-177f).** It returns a `Quonfig::EvaluationDetails` whose `value` is the config's resolved value as stored, after ENV_VAR provision and decryption, with no type check or conversion: a duration comes back as its ISO 8601 text exactly as stored (`"PT90S"`, not milliseconds), a `string_list` as an Array, JSON as stored. The new `value_type` attribute names the stored type (`"duration"`, `"int"`, ...; `nil` when nothing resolved). Reason, variant, `flag_metadata`, error codes and telemetry are the same as the typed `*_details` getters, and it never raises. A malformed stored value (a duration `"30s"`) is returned as-is with a success reason; an unset or unparseable ENV_VAR is still `reason: "ERROR"`, as in the typed getters. Available on the client and on a `with_context` bound client. It matches sdk-go's `Client.EvaluateDetails` and is meant for OpenFeature providers and other callers that do their own typing. Existing getters are unchanged. Tests: `test/test_evaluate_details.rb`.
+- **Fixed: `connection_state` no longer answers `:connected` before the SSE stream's first frame (qfg-fi1s).** On a network client with SSE on, the init fetch installs an envelope before the stream has delivered anything, and `connection_state` read that install as `:connected`. It now reports `:initializing` until the stream's first frame arrives (the connected edge), as the supervisor contract says ("after 200 headers, no frame" is initializing) and as sdk-go, sdk-java, sdk-net and sdk-python already do. Datadir clients and clients with `enable_sse: false` still read `:connected` once config is installed. Tests: `test/test_health_primitives.rb`, `test/test_sse_first_frame.rb` (Test 9a/9b now assert on the public getter).
+
+## 2.0.0 - 2026-10-26
+
+The typed-getter contract (qfg-zvyy), shared by every Quonfig SDK and pinned by
+the integration-test-data matrix (`getter.contract.*`, tag `v2026.10.26`). A
+typed read that cannot return a value of the getter's type no longer raises
+past your `default:`; your default applies.
+
+### UPGRADE to 2.0
+
+1. **A failed read returns your `default:`.** In 1.x the typed getters raised
+   even when you passed a `default:`: `get_int('k', default: 0)` on a string
+   config raised `TypeMismatchError`, and any getter on an unset ENV_VAR or a
+   secret that cannot be decrypted raised `MissingEnvVarError` /
+   `DecryptionError`. In 2.0 the getter returns the default. This covers a
+   value of another type, a malformed stored or ENV_VAR value, an unset ENV_VAR
+   and a decryption failure. The untyped `get(key, default)` does the same for
+   the failures it can see. Code that rescued these errors around a getter
+   with a `default:` now gets the default instead.
+
+2. **No default: `on_no_default` decides.** `:raise` (the default) still raises
+   the error (`TypeMismatchError`, `EnvVarParseError`, `MissingEnvVarError`,
+   `DecryptionError`), as in 1.x. Under `on_no_default: :return_nil` the getter
+   now returns `nil` instead of raising.
+
+3. **No string coercion.** A stored string is never a bool or a number:
+   `get_bool` on a string `"false"` is a type mismatch, and `enabled?` on a
+   string `"true"` is `false` (1.x returned `true`). Store values with the
+   config type you read them with.
+
+4. **Numbers convert only when exact.** `get_float` on an int config now
+   returns the value (`30` -> `30.0`); 1.x raised `TypeMismatchError`.
+   `get_int` on a double config returns the value when it is whole and within
+   +/-(2^53-1) (`3.0` -> `3`); `3.9`, `1e300` and `2^53` are type mismatches,
+   never truncated.
+
+5. **Stricter types.** `get_json` reads json configs only, `get_string_list`
+   string_list configs only, and `get_string` string and log_level configs
+   only. In 1.x `get_json` returned any value and `get_string_list` accepted
+   any array of strings.
+
+6. **`enabled?` never raises.** It returns `false` for a missing key, a flag
+   with no matching rule, a value that is not the bool `true`, and any
+   resolution error (1.x raised `MissingEnvVarError` / `DecryptionError` and
+   errors from a malformed value).
+
+7. **One WARN per key.** A failed read that returns your default or `nil`, and
+   `enabled?` returning `false` for one of the reasons above, log one WARN per
+   key per client: `[quonfig] read of "<key>" returned no value: <reason>`. It
+   names the key and the types, never the value. A wrong decryption key in
+   production now degrades to your defaults with these WARNs. **If that must be
+   fatal**, read without a `default:` on a client with `on_no_default: :raise`
+   (the default), or use `get_or_raise`, which raises `MissingEnvVarError`,
+   `EnvVarParseError` and `DecryptionError` even when you pass a `default:`.
+
+### Changed
+
+- **Major: typed getters (`get_string`, `get_int`, `get_float`, `get_bool`,
+  `get_string_list`, `get_duration`, `get_json`, and the same on
+  `BoundClient`) follow the contract above.** The 1.x identity bypass is gone:
+  a value that happened to be `equal?` to the default skipped the type check,
+  so `get_string('a_bool', default: true)` returned `true` with no error.
+- **Major: `enabled?` is true only for the bool `true`.**
+- **Major: `get(key, default)` returns the default on an unset ENV_VAR, a
+  decryption failure or a malformed value.** A malformed stored duration read
+  with no default now follows `on_no_default` (1.x returned `nil`).
+- **`*_details`: a malformed value, stored or ENV_VAR, is `TYPE_MISMATCH`** (it
+  was `GENERAL` for an ENV_VAR value), as in sdk-go. `get_int_details` /
+  `get_float_details` follow the int <-> double rule.
+- **`get_or_raise` raises `EnvVarParseError` on a malformed stored int or
+  double** (1.x raised a bare `ArgumentError`).
+- **A `decryptWith` key config that is missing, matches no rule or is empty now raises `DecryptionError`** (1.x raised a plain `Quonfig::Error`), so it counts as a decryption failure and the typed getters apply your default. `DecryptionError` is a `Quonfig::Error`, so `rescue Quonfig::Error` still catches it.
+- **`TypeMismatchError` names the config's value type** (`... expected Integer,
+  got a string value`) when the type is known.
+
+### Tests
+
+- All workflows run integration-test-data `v2026.10.26`, which adds the
+  typed-getter matrix to `get.yaml`, `get_or_raise.yaml` and `enabled.yaml`.
+  The typed `get_or_raise` cases call the typed getter on a client with
+  `on_no_default: :raise` (Ruby's untyped `get_or_raise` cannot tell a
+  wrong-type value from a found one); that generator change is
+  quonfig/integration-test-data `ruby.ts`, see the PR for this release.
+- `test/test_typed_getter_contract.rb` covers what the corpus cannot: the
+  once-per-key WARN, `enabled?` never raising, int <-> double edges (NaN,
+  infinity, 2^53), the Details error codes, and the untyped `get` /
+  `get_or_raise`.
+
+### Fixed
+
+- **A config payload refused as older no longer pins its ETag (qfg-j7ui).** When a `/api/v2/configs` 200 is dropped by the reject-older guard because its generation is lower than the one held, the SDK no longer remembers its ETag. Before, if the server later repaired that same commit to a higher generation, every poll got a 304 and the client stayed on the old config until the next commit. The same already held for a generation-0 payload (qfg-9dxb.9). A same-generation re-delivery still keeps its ETag. Pinned by supervisor contract Test 11 (integration-test-data `v2026.10.27.1`).
+
+### Docs
+
+- **README note on forking servers during a delivery outage (qfg-6vno.24).** Under Startup failure: a forked worker rebuilds its own snapshot under the same `on_init_failure` mode, `:fail` raises until delivery heals, `:wait` blocks the first request, and frequent recyclers should use `:continue`. Links to the startup-failure docs page. No code change.
+
 ## 1.11.0 - 2026-10-23
 
 - **Changed (minor): SSE events and config bodies have size caps (qfg-6vno.20.5, cross-SDK rule qfg-6vno.8).** One SSE event (any single line, and the joined lines of a multi-line `data:`) is capped at 4 MiB (4,194,304 bytes), and a 200 body from `/api/v2/configs` at 16 MiB (16,777,216 bytes). Before, both were read with no limit (1.8.0 noted "there is still no size cap"), so a broken proxy or a stream with no newline could grow memory without bound.

data/README.md

@@ -298,6 +298,24 @@ timeout runs out (false). Under `:wait`, point your readiness probe at
 `ready?`. `:raise` and `:return` are the deprecated spellings of `:fail` and
 `:continue`; they still work and log a one-time WARN.
 
+### Forking servers (Puma, Sidekiq)
+
+A forked worker (Puma cluster or phased restart, Unicorn, Sidekiq, Resque)
+never serves the parent's config: it rebuilds its own snapshot on first use and
+applies the same `on_init_failure` mode as a fresh boot (see
+[Rails integration](#rails-integration)). If delivery is unreachable when a
+worker is recycled:
+
+- `:fail` (default): the worker's first lookup raises
+  `Quonfig::Errors::InitializationError`, and later lookups keep raising until
+  delivery heals.
+- `:wait`: the worker's first request blocks until delivery is back.
+- `:continue`: the worker serves code defaults until it heals. Apps that
+  recycle workers often (frequent phased restarts, a fork per job) should use
+  this and keep their defaults safe.
+
+Details: [Startup failure: forked workers](https://docs.quonfig.com/docs/explanations/architecture/startup-failure#forked-workers-and-worker-recycling).
+
 ## Constructor options
 
 ```ruby
@@ -391,12 +409,40 @@ Each typed getter takes a config key plus two optional keyword arguments:
 for this call). On a `BoundClient` (see `with_context` above) the getters take
 only `default:`; the context is the bound one.
 
+Upgrading from 1.x? See [UPGRADE to 2.0](CHANGELOG.md#upgrade-to-20).
+
 - **Missing key:** returns `default:` when you pass one. Without a default the
   `on_no_default` option decides: `:raise` (the default) raises
   `Quonfig::Errors::MissingDefaultError`, `:return_nil` returns `nil`.
-- **Wrong type:** a value that does not match the getter's type (for example
-  `get_int` on a string config) raises `Quonfig::Errors::TypeMismatchError`,
-  with or without a `default:`.
+- **Failed read:** a read that cannot produce a value of the getter's type
+  returns `default:` when you pass one and logs one WARN per key (it names the
+  key, never the value). Without a default it follows `on_no_default`:
+  `:return_nil` returns `nil` (and logs the WARN), `:raise` raises the error:
+
+| Situation | Error raised with no default under `:raise` |
+|---|---|
+| Value of another type (e.g. `get_bool` on a string config) | `Quonfig::Errors::TypeMismatchError` |
+| Malformed stored or ENV_VAR value (an int `"twelve"`, a duration `"30s"`) | `Quonfig::Errors::EnvVarParseError` |
+| ENV_VAR not set | `Quonfig::Errors::MissingEnvVarError` |
+| Secret cannot be decrypted | `Quonfig::Errors::DecryptionError` |
+
+Strings are never coerced: a stored `"false"` is a string, so `get_bool`
+treats it as a type mismatch instead of returning `false`. The only conversions
+are between numbers, and only when exact: `get_float` reads an int config
+(`30` -> `30.0`), and `get_int` reads a double config holding a whole number
+within +/-(2^53-1) (`3.0` -> `3`; `3.9` is a type mismatch, never truncated).
+The untyped `get(key, default)` follows the same rule for the failures it can
+see (malformed values, ENV_VAR and decryption errors).
+
+`enabled?` never raises. It returns `true` only for a flag that resolves to the
+bool `true`, and `false` (with one WARN per key) for a missing key, a flag with
+no matching rule, a value that is not a bool (a stored string `"true"`
+included) or any resolution error.
+
+A wrong decryption key or an unset ENV_VAR therefore degrades to your defaults
+with one WARN per key. If a broken config must stop your service, call the
+getter without a `default:` on a client with `on_no_default: :raise` (the
+default), or use `get_or_raise`.
 
 | Method                                              | Returns                                   |
 |-----------------------------------------------------|-------------------------------------------|
@@ -407,11 +453,10 @@ only `default:`; the context is the bound one.
 | `get_string_list(key, default:, context:)`          | `Array<String>`                           |
 | `get_duration(key, default:, context:)`             | `Integer` (milliseconds)                  |
 | `get_json(key, default:, context:)`                 | `Hash`, `Array`, or a scalar              |
-| `enabled?(feature_name, context = nil)`             | `true` or `false` (`false` when missing)  |
+| `enabled?(feature_name, context = nil)`             | `true` or `false`; never raises           |
 
 `get_duration` returns integer milliseconds (`PT1.5S` is `1500`). A duration
-value that is not valid ISO-8601 returns `default:` and logs one warning per
-key; with no default it follows `on_no_default`.
+value that is not valid ISO-8601 is a malformed value (see above).
 
 Example:
 
@@ -426,13 +471,33 @@ client.get_json('homepage.layout', default: {})
 client.enabled?('beta-feature', user: { key: 'user-123' })
 ```
 
-`get_or_raise(key, default:, context:)` returns the value like `get`, but a
-missing key without a `default:` always raises
-`Quonfig::Errors::MissingDefaultError` (whatever `on_no_default` is set to), and
-an unset or malformed ENV_VAR value, a malformed stored duration, or a
-decryption failure raises its error. `get_duration_details(key, context:)`
-returns `Quonfig::EvaluationDetails` with the duration in integer milliseconds,
-like the other `*_details` getters.
+`get_or_raise(key, default:, context:)` returns the value like `get` (untyped),
+but a missing key without a `default:` always raises
+`Quonfig::Errors::MissingDefaultError` (whatever `on_no_default` is set to),
+and an unset or malformed ENV_VAR value, a malformed stored value, or a
+decryption failure raises its error even when you pass a `default:` (the
+default only covers a missing key). For a typed read that raises, call the
+typed getter with no `default:` under `on_no_default: :raise`.
+
+The `*_details` getters (`get_int_details(key, context:)` and so on) never
+raise. They return `Quonfig::EvaluationDetails`; a wrong-type or malformed
+value is `reason: "ERROR"` with `error_code: "TYPE_MISMATCH"`.
+`get_duration_details` carries the duration in integer milliseconds.
+
+To read a value without a type, use `evaluate_details(key, context:)`. It
+returns the value as stored, with `value_type` naming its type, and the same
+`reason`, `variant` and `flag_metadata` as the typed details getters. A
+duration comes back as its ISO 8601 text:
+
+```ruby
+details = client.evaluate_details('http.timeout', context: { user: { key: 'u1' } })
+details.value       # => "PT90S"
+details.value_type  # => "duration"
+details.reason      # => "STATIC"
+```
+
+It does no type check and never raises; a missing key is `reason: "ERROR"`
+with `error_code: "FLAG_NOT_FOUND"`.
 
 ## Dynamic log levels (SemanticLogger)
 
@@ -557,8 +622,8 @@ Caveats:
   threads race the first request.
 - **`connection_state` never triggers the re-initialization** — a diagnostic
   must not open a socket. A child that has not used the client yet answers
-  `:initializing`, which is exactly what it is; it flips to `:connected` on
-  first use.
+  `:initializing`, which is exactly what it is; it flips to `:connected`
+  after its first use, once the stream delivers its first frame.
 - The child's telemetry aggregators start empty. The parent flushes the data
   it collected before the fork; the child reports only its own.
 - **Per-job forking pays per job.** A Resque-style worker that forks a child
@@ -707,7 +772,9 @@ reuse the parent's client object in a child process without it.
   envelope install (any source: datadir, initial HTTP fetch, SSE, or fallback
   polling). Returns `nil` before the first install. Preserved across `stop`.
 - `client.connection_state` — a `Symbol` describing the aggregate state:
-  `:initializing`, `:connected`, `:disconnected`, or `:falling_back`.
+  `:initializing`, `:connected`, `:disconnected`, or `:falling_back`. With
+  SSE on, the client reads `:initializing` until the stream delivers its
+  first frame, even after the initial fetch has installed config.
 - `client.callback_errors_total(callback: 'on_config_update')` — how many
   times your `on_update` block raised. The SDK catches the error, logs it at
   ERROR with its stack, and keeps delivering updates; a raise is not a worker

data/lib/quonfig/bound_client.rb

@@ -74,6 +74,11 @@ module Quonfig
       @client.get_duration_details(key, context: @context)
     end
 
+    # See Quonfig::Client#evaluate_details.
+    def evaluate_details(key)
+      @client.evaluate_details(key, context: @context)
+    end
+
     def enabled?(feature_name)
       @client.enabled?(feature_name, @context)
     end

data/lib/quonfig/client.rb

@@ -21,6 +21,42 @@ module Quonfig
   class Client
     LOG = Quonfig::InternalLogger.new(self)
 
+    # Errors that make a read of a present key fail (qfg-zvyy). Each one is
+    # handled by #failed_read: the caller's default, nil, or the error.
+    READ_FAILURES = [
+      Quonfig::Errors::TypeMismatchError,
+      Quonfig::Errors::EnvVarParseError,
+      Quonfig::Errors::MissingEnvVarError,
+      Quonfig::Errors::DecryptionError
+    ].freeze
+
+    # Largest integer a double holds exactly: +/-(2^53-1), the bound the
+    # cross-SDK contract (and cli verify) uses for a double -> int read.
+    MAX_SAFE_INTEGER = (2**53) - 1
+
+    # Declared value type each typed getter reads. The only conversions are
+    # between numbers, and only when exact (see #typed_number).
+    ACCEPTED_TYPES = {
+      String => %w[string log_level],
+      Integer => %w[int double],
+      Float => %w[double int],
+      bool: %w[bool],
+      string_list: %w[string_list],
+      json: %w[json],
+      duration: %w[duration]
+    }.freeze
+
+    TYPE_NAMES = {
+      String => 'String',
+      Integer => 'Integer',
+      Float => 'Float',
+      bool: 'Boolean',
+      string_list: 'Array<String>',
+      json: 'JSON',
+      duration: 'ISO-8601 Duration'
+    }.freeze
+    private_constant :READ_FAILURES, :MAX_SAFE_INTEGER, :ACCEPTED_TYPES, :TYPE_NAMES
+
     # The +callback+ label values of quonfig_sdk_callback_errors_total
     # (supervisor contract). sdk-ruby has no public connection-state callback,
     # so +on_connection_state_change+ stays 0; it is listed so a reader of
@@ -81,9 +117,12 @@ module Quonfig
       @evaluator = Quonfig::Evaluator.new(@store, env_id: @options.environment)
       @resolver = Quonfig::Resolver.new(@store, @evaluator)
       @semantic_logger_filters = {}
-      # Keys already warned about for a malformed duration value (qfg-2agi.10).
-      @malformed_duration_warned = Set.new
-      @malformed_duration_mutex = Mutex.new
+      # Keys already warned about for a failed read: a wrong-type value, a
+      # malformed value, an unset ENV_VAR or a decryption failure, plus
+      # enabled? returning false for a missing key (qfg-2agi.10, qfg-zvyy).
+      # One WARN per key per client.
+      @read_failure_warned = Set.new
+      @read_failure_mutex = Mutex.new
       @sse_client = nil
       @poll_supervisor = nil
       @stopped = false
@@ -151,23 +190,27 @@ module Quonfig
 
     # ---- Lookup --------------------------------------------------------
 
+    # The config's value, untyped.
+    #
+    # A missing key returns +default+, or applies +on_no_default+ (nil under
+    # :return_nil, MissingDefaultError under :raise). A read that fails (an
+    # unset ENV_VAR, a decryption failure, a malformed stored or ENV_VAR
+    # value) follows the typed-getter contract (qfg-zvyy): +default+ when one
+    # is given, otherwise nil under :return_nil or the error itself under
+    # :raise, and one WARN per key either way.
     def get(key, default = NO_DEFAULT_PROVIDED, jit_context = NO_DEFAULT_PROVIDED)
       ensure_initialized_after_fork
       ctx = build_context(jit_context)
       record_context_for_telemetry(ctx)
-      result =
-        begin
-          @resolver.get(key, ctx)
-        rescue Quonfig::Errors::MissingDefaultError
-          # The Resolver raises (matching Quonfig.get_or_raise semantics).
-          # The Client's get applies the caller-provided default *or* the
-          # configured on_no_default policy via handle_missing.
-          nil
-        end
-      return handle_missing(key, default) if result.nil?
+      begin
+        result = resolve_for_read(key, ctx)
+        return handle_missing(key, default) if result.nil?
 
-      record_evaluation_for_telemetry(result)
-      result.unwrapped_value
+        record_evaluation_for_telemetry(result)
+        unwrap_for_read(result)
+      rescue *READ_FAILURES => e
+        failed_read(key, default, e)
+      end
     end
 
     def get_string(key, default: NO_DEFAULT_PROVIDED, context: NO_DEFAULT_PROVIDED)
@@ -190,31 +233,13 @@ module Quonfig
       typed_get(key, :string_list, default: default, context: context)
     end
 
-    # Integer milliseconds for a duration config (qfg-2agi.10).
-    #
-    # - A config whose valueType is not duration raises TypeMismatchError,
-    #   like get_int on a string config.
-    # - Values follow the shared grammar (Quonfig::Duration); ms are rounded
-    #   half up on both the stored and the ENV_VAR path.
-    # - A malformed value (stored or ENV_VAR) returns +default+ and logs one
-    #   warning per key. With no default it returns nil under
-    #   on_no_default: :return_nil and raises EnvVarParseError under :raise.
+    # Integer milliseconds for a duration config (qfg-2agi.10). Values follow
+    # the shared grammar (Quonfig::Duration); ms are rounded half up on both
+    # the stored and the ENV_VAR path. A config whose valueType is not
+    # duration, or a malformed duration, is a failed read under the
+    # typed-getter contract (see #typed_get).
     def get_duration(key, default: NO_DEFAULT_PROVIDED, context: NO_DEFAULT_PROVIDED)
-      ensure_initialized_after_fork
-      ctx = build_context(context)
-      record_context_for_telemetry(ctx)
-      result =
-        begin
-          @resolver.get(key, ctx)
-        rescue Quonfig::Errors::MissingDefaultError
-          nil
-        rescue Quonfig::Errors::EnvVarParseError => e
-          return malformed_duration(key, default, e)
-        end
-      return handle_missing(key, default) if result.nil?
-
-      record_evaluation_for_telemetry(result)
-      duration_millis(key, result, default)
+      typed_get(key, :duration, default: default, context: context)
     end
 
     def get_json(key, default: NO_DEFAULT_PROVIDED, context: NO_DEFAULT_PROVIDED)
@@ -248,10 +273,7 @@ module Quonfig
       end
 
       record_evaluation_for_telemetry(result)
-      value = result.unwrapped_value
-      raise malformed_stored_duration_error(result) if malformed_stored_duration?(result, value)
-
-      value
+      unwrap_for_read(result)
     end
 
     # ---- Details getters ----------------------------------------------
@@ -263,39 +285,71 @@ module Quonfig
     # raise — exceptions are caught and rendered as ERROR details.
 
     def get_bool_details(key, context: NO_DEFAULT_PROVIDED)
-      evaluate_details(key, :bool, context)
+      build_details(key, :bool, context)
     end
 
     def get_string_details(key, context: NO_DEFAULT_PROVIDED)
-      evaluate_details(key, String, context)
+      build_details(key, String, context)
     end
 
     def get_int_details(key, context: NO_DEFAULT_PROVIDED)
-      evaluate_details(key, Integer, context)
+      build_details(key, Integer, context)
     end
 
     def get_float_details(key, context: NO_DEFAULT_PROVIDED)
-      evaluate_details(key, Float, context)
+      build_details(key, Float, context)
     end
 
     def get_string_list_details(key, context: NO_DEFAULT_PROVIDED)
-      evaluate_details(key, :string_list, context)
+      build_details(key, :string_list, context)
     end
 
     def get_json_details(key, context: NO_DEFAULT_PROVIDED)
-      evaluate_details(key, :json, context)
+      build_details(key, :json, context)
     end
 
     # Integer milliseconds in +value+ (qfg-2agi.27). A config whose valueType
     # is not duration is ERROR / TYPE_MISMATCH; a malformed value (stored or
     # ENV_VAR) is ERROR with a nil value.
     def get_duration_details(key, context: NO_DEFAULT_PROVIDED)
-      evaluate_details(key, :duration, context)
-    end
-
+      build_details(key, :duration, context)
+    end
+
+    # Untyped details read (matches sdk-go Client.EvaluateDetails). +value+
+    # is the resolved value in its stored form, after ENV_VAR provision and
+    # decryption, with no type check, coercion or parse validation: a
+    # duration is its ISO 8601 text exactly as stored ("PT90S"), a
+    # string_list an Array, a json value as stored. +value_type+ is the
+    # stored value type ('string', 'int', 'double', 'bool', 'string_list',
+    # 'duration', 'json', ...; nil when nothing resolved). Reason, variant,
+    # error_code and telemetry are the same as the typed *_details getters,
+    # and like them it never raises. Meant for OpenFeature providers and
+    # other callers that do their own typing.
+    def evaluate_details(key, context: NO_DEFAULT_PROVIDED)
+      build_details(key, nil, context)
+    end
+
+    # True only when the flag resolves to the bool +true+. Never raises
+    # (qfg-zvyy): a missing key, a flag with no matching rule, a value that is
+    # not a bool (a stored string "true" included) or any resolution error
+    # returns false and logs one WARN per key.
     def enabled?(feature_name, jit_context = NO_DEFAULT_PROVIDED)
-      value = get(feature_name, false, jit_context)
-      [true, 'true'].include?(value)
+      ensure_initialized_after_fork
+      begin
+        ctx = build_context(jit_context)
+        record_context_for_telemetry(ctx)
+        result = resolve_for_read(feature_name, ctx)
+        if result.nil?
+          warn_read_failure(feature_name, 'missing key or no matching rule; enabled? returns false')
+          return false
+        end
+
+        record_evaluation_for_telemetry(result)
+        typed_value(feature_name, result, :bool) == true
+      rescue StandardError => e
+        warn_read_failure(feature_name, "#{e.message}; enabled? returns false")
+        false
+      end
     end
 
     def defined?(key)
@@ -610,7 +664,8 @@ module Quonfig
     # Aggregate connection state. Returns one of:
     #
     # - +:initializing+ — no envelope has been installed and SSE is not yet
-    #   connected.
+    #   connected, or (SSE clients) the stream has not delivered its first
+    #   frame yet, even if the init fetch already installed an envelope.
     # - +:connected+ — SSE is live, or the SDK is delivering configs from a
     #   loaded envelope (datadir mode or post-initial-fetch with no SSE).
     # - +:disconnected+ — +stop+ was called, or SSE errored and no fallback
@@ -641,9 +696,14 @@ module Quonfig
         next :disconnected if sse_channel_expected? && !sse_worker_alive?
         next :connected if @sse_state == :connected
         next :disconnected if @sse_state == :error
+        # First-frame rule (qfg-fi1s): a client that is supposed to hold an
+        # SSE stream is not :connected until that stream delivers its first
+        # frame. The init fetch's install alone does not make it connected;
+        # "after 200 headers, no frame" is :initializing (contract Test 6).
+        next :initializing if sse_channel_expected? && !@sse_ever_connected
 
         # No SSE state change yet: state is driven by whether any envelope
-        # has been installed (datadir / initial fetch).
+        # has been installed (datadir / SSE disabled / initial fetch).
         @last_successful_refresh.nil? ? :initializing : :connected
       end
     end
@@ -918,7 +978,7 @@ module Quonfig
     end
 
     # Lazy post-fork re-initialization. Called from every read entry point
-    # (+get+, +evaluate_details+, +defined?+, +keys+) — the flag read is a
+    # (+get+, +evaluate_details+ / the +*_details+ getters, +defined?+, +keys+) — the flag read is a
     # plain boolean, so the steady-state cost is one comparison per lookup.
     #
     # The first caller in the child does what +Client.new+ does: its own
@@ -1857,19 +1917,25 @@ module Quonfig
         # last_successful_refresh (only an install or fetch does that).
         on_connected: sse_connected_callback
       )
+      # The block returns the install result (:updated / :not_modified); the
+      # SSE client clears its oversized gate only on :updated (qfg-6vno.20.8).
+      # The connected edge comes from on_connected at the first frame (or,
+      # while the oversized gate is set, at the first installed envelope), so
+      # an envelope the reject-older guard drops never reports connected here.
       @sse_client.start do |envelope, _event, _source|
         next if @stopped
 
         begin
-          @config_loader.apply_envelope(envelope)
+          result = @config_loader.apply_envelope(envelope)
           sync_evaluator_env_id!
-          handle_sse_state_change(:connected)
+          handle_sse_state_change(:connected) if result == :updated
           record_refresh!
         rescue StandardError => e
           LOG.warn "[quonfig] Error applying SSE envelope: #{e.message}"
           next
         end
         notify_on_update_callback
+        result
       end
       true
     rescue StandardError => e
@@ -2139,9 +2205,11 @@ module Quonfig
     end
 
     # Build a Quonfig::EvaluationDetails for +key+, evaluated against the
-    # caller's context, after coercing/checking +expected_type+. Never
-    # raises; all exceptions become ERROR details.
-    def evaluate_details(key, expected_type, context)
+    # caller's context, after coercing/checking +expected_type+. A nil
+    # +expected_type+ is the untyped #evaluate_details read: the stored value
+    # with no type check, plus +value_type+. Never raises; all
+    # exceptions become ERROR details.
+    def build_details(key, expected_type, context)
       ensure_initialized_after_fork
       jit = context == NO_DEFAULT_PROVIDED ? nil : context
       ctx = build_context(jit)
@@ -2160,6 +2228,17 @@ module Quonfig
             variant: build_variant(Quonfig::EvaluationDetails::REASON_ERROR, nil, nil),
             flag_metadata: build_flag_metadata(nil, nil, nil, nil, nil)
           )
+        rescue Quonfig::Errors::EnvVarParseError => e
+          # An ENV_VAR value that does not parse as the config's type is
+          # TYPE_MISMATCH, like a malformed stored value (as in sdk-go).
+          return Quonfig::EvaluationDetails.new(
+            value: nil,
+            reason: Quonfig::EvaluationDetails::REASON_ERROR,
+            error_code: Quonfig::EvaluationDetails::ERROR_TYPE_MISMATCH,
+            error_message: e.message,
+            variant: build_variant(Quonfig::EvaluationDetails::REASON_ERROR, nil, nil),
+            flag_metadata: build_flag_metadata(nil, nil, nil, nil, nil)
+          )
         end
 
       if result.nil?
@@ -2175,15 +2254,12 @@ module Quonfig
 
       config_id = result.config&.dig('id') || result.config&.dig(:id)
       config_type = result.config&.dig('type') || result.config&.dig(:type)
-      raw_value = result.unwrapped_value
 
       begin
-        if expected_type == :duration
-          raise Quonfig::Errors::TypeMismatchError.new(key, 'ISO-8601 Duration', raw_value) unless duration_result?(result)
-          raise malformed_stored_duration_error(result) if malformed_stored_duration?(result, raw_value)
-        end
-        coerced = coerce_and_check(key, raw_value, expected_type) unless raw_value.nil?
-      rescue Quonfig::Errors::TypeMismatchError => e
+        coerced = expected_type.nil? ? stored_value(result) : typed_value(key, result, expected_type)
+      rescue Quonfig::Errors::TypeMismatchError, Quonfig::Errors::EnvVarParseError => e
+        # A wrong-type value and a malformed one (the getter cannot produce
+        # a value of its type) are both TYPE_MISMATCH, as in sdk-go.
         return Quonfig::EvaluationDetails.new(
           value: nil,
           reason: Quonfig::EvaluationDetails::REASON_ERROR,
@@ -2203,7 +2279,8 @@ module Quonfig
         value: coerced,
         reason: reason,
         variant: build_variant(reason, result.rule_index, result.weighted_value_index),
-        flag_metadata: flag_metadata
+        flag_metadata: flag_metadata,
+        value_type: expected_type.nil? ? stored_value_type(result) : nil
       )
     rescue StandardError => e
       Quonfig::EvaluationDetails.new(
@@ -2216,6 +2293,22 @@ module Quonfig
       )
     end
 
+    # +result+'s resolved value in stored form (after ENV_VAR provision and
+    # decryption) with no coercion or parse validation: a duration is its
+    # ISO 8601 text as stored. Hashes and Arrays are copied so a caller
+    # mutating the result cannot rewrite the cached config.
+    def stored_value(result)
+      copy_containers(result.raw_value)
+    end
+
+    def copy_containers(value)
+      case value
+      when Hash then value.to_h { |k, v| [k, copy_containers(v)] }
+      when Array then value.map { |v| copy_containers(v) }
+      else value
+      end
+    end
+
     # Build the variant string per the cross-SDK spec
     # (project/plans/openfeature-resolution-details.md §2).
     def build_variant(reason, rule_index, weighted_value_index)
@@ -2248,32 +2341,122 @@ module Quonfig
       md
     end
 
+    # A typed read under the typed-getter contract (qfg-zvyy, shared with
+    # every Quonfig SDK and pinned by integration-test-data getter.contract.*).
+    #
+    # A missing key returns +default+ or applies +on_no_default+. A read that
+    # fails (a value of another type, a malformed stored or ENV_VAR value, an
+    # unset ENV_VAR, a decryption failure) returns +default+ when one is
+    # given; with no default it returns nil under on_no_default: :return_nil
+    # and raises the error (TypeMismatchError, EnvVarParseError,
+    # MissingEnvVarError, DecryptionError) under :raise. Either way it logs
+    # one WARN per key per client.
     def typed_get(key, expected_type, default:, context:)
-      jit = context == NO_DEFAULT_PROVIDED ? NO_DEFAULT_PROVIDED : context
-      value = get(key, default, jit)
+      ensure_initialized_after_fork
+      ctx = build_context(context)
+      record_context_for_telemetry(ctx)
+      begin
+        result = resolve_for_read(key, ctx)
+        return handle_missing(key, default) if result.nil?
+
+        record_evaluation_for_telemetry(result)
+        typed_value(key, result, expected_type)
+      rescue *READ_FAILURES => e
+        failed_read(key, default, e)
+      end
+    end
+
+    # The resolved Evaluation for +key+, or nil when the key is missing or no
+    # rule matched. Resolution errors (MissingEnvVarError, EnvVarParseError,
+    # DecryptionError) propagate.
+    def resolve_for_read(key, ctx)
+      @resolver.get(key, ctx)
+    rescue Quonfig::Errors::MissingDefaultError
+      nil
+    end
+
+    # +result+'s value with no type check. A stored value that does not parse
+    # as its declared type (an int "twelve", a duration "30s") raises
+    # EnvVarParseError, as a malformed ENV_VAR value does.
+    def unwrap_for_read(result)
+      value =
+        begin
+          result.unwrapped_value
+        rescue ArgumentError, TypeError, FloatDomainError
+          raise malformed_stored_value_error(result)
+        end
+      raise malformed_stored_value_error(result) if malformed_stored_duration?(result, value)
+
+      value
+    end
+
+    # +result+'s value as +expected_type+, or raise TypeMismatchError (a value
+    # of another type) / EnvVarParseError (a malformed value). Strings are
+    # never coerced: a stored "false" is not a bool and "3" is not an int.
+    def typed_value(key, result, expected_type)
+      stored = stored_value_type(result)
+      accepted = ACCEPTED_TYPES.fetch(expected_type)
+      raise Quonfig::Errors::TypeMismatchError.new(key, TYPE_NAMES.fetch(expected_type), nil, actual_type: stored) unless stored.nil? || accepted.include?(stored)
 
-      # Missing path: resolver returned the caller's default (or nil under
-      # on_no_default=:return_nil) — skip type coercion.
-      return value if default != NO_DEFAULT_PROVIDED && value.equal?(default)
+      value = unwrap_for_read(result)
       return nil if value.nil?
 
-      coerce_and_check(key, value, expected_type)
+      if [Integer, Float].include?(expected_type)
+        typed_number(key, result, value, expected_type)
+      elsif expected_type == :bool
+        typed_bool(key, result)
+      else
+        check_class(key, value, expected_type)
+      end
     end
 
-    def duration_millis(key, result, default)
-      raise Quonfig::Errors::TypeMismatchError.new(key, 'ISO-8601 Duration', result.unwrapped_value) unless duration_result?(result)
+    # The Value's declared type ('int', 'string', ...); a resolved ENV_VAR or
+    # decrypted value carries the type it was coerced to. Nil when unknown.
+    def stored_value_type(result)
+      type = result.type
+      if type.nil? || type == 'provided'
+        config = result.config || {}
+        type = config['valueType'] || config[:valueType] || config['value_type'] || config[:value_type]
+      end
+      type&.to_s
+    end
 
-      value = result.unwrapped_value
-      millis = value.is_a?(Integer) ? value : Quonfig::Duration.parse_millis(value)
-      return millis unless millis.nil?
+    # Double getter: any int or double (30 -> 30.0). Int getter: an int, or a
+    # double that is whole and within +/-(2^53-1) (3.0 -> 3). Never truncates:
+    # 3.9, 1e300 and NaN are type mismatches.
+    def typed_number(key, result, value, expected_type)
+      # A stored int whose raw value is a Float would unwrap truncated.
+      raw = result.raw_value
+      number = raw.is_a?(Numeric) ? raw : value
+      mismatch = -> { Quonfig::Errors::TypeMismatchError.new(key, TYPE_NAMES.fetch(expected_type), number) }
+      raise mismatch.call unless number.is_a?(Integer) || number.is_a?(Float)
 
-      malformed_duration(key, default, malformed_stored_duration_error(result))
+      return number.to_f if expected_type == Float
+      return number if number.is_a?(Integer)
+      raise mismatch.call unless number.finite? && number == number.floor && number.abs <= MAX_SAFE_INTEGER
+
+      number.to_i
     end
 
-    def duration_result?(result)
-      config = result.config || {}
-      value_type = config['valueType'] || config[:valueType] || config['value_type'] || config[:value_type]
-      value_type == 'duration' || result.type == 'duration'
+    # A bool Value unwraps with !!raw, so check the raw value: only a real
+    # true/false is a bool.
+    def typed_bool(key, result)
+      raw = result.raw_value
+      raise Quonfig::Errors::TypeMismatchError.new(key, 'Boolean', raw) unless [true, false].include?(raw)
+
+      raw
+    end
+
+    def check_class(key, value, expected_type)
+      ok =
+        if expected_type == String then value.is_a?(String)
+        elsif expected_type == :string_list then value.is_a?(Array) && value.all?(String)
+        elsif expected_type == :duration then value.is_a?(Integer)
+        else true # :json: any JSON value
+        end
+      raise Quonfig::Errors::TypeMismatchError.new(key, TYPE_NAMES.fetch(expected_type), value) unless ok
+
+      value
     end
 
     # A stored duration string outside the shared grammar unwraps to nil.
@@ -2281,49 +2464,27 @@ module Quonfig
       unwrapped.nil? && result.type == 'duration' && !result.raw_value.nil?
     end
 
-    def malformed_stored_duration_error(result)
+    def malformed_stored_value_error(result)
       Quonfig::Errors::EnvVarParseError.new(result.raw_value, result.config || {}, nil, stored: true)
     end
 
-    def malformed_duration(key, default, error)
-      if @malformed_duration_mutex.synchronize { @malformed_duration_warned.add?(key.to_s) }
-        LOG.warn "[quonfig] #{key} is not a valid ISO-8601 duration; " \
-                 "#{default == NO_DEFAULT_PROVIDED ? 'no default given' : 'returning the default'}"
-      end
-      return default unless default == NO_DEFAULT_PROVIDED
-      raise error if @options.on_no_default == Quonfig::Options::ON_NO_DEFAULT::RAISE
+    # The failed-read rule (qfg-zvyy): +default+ when one is given, else nil
+    # under on_no_default: :return_nil, each with one WARN per key; else
+    # +error+ under :raise (the raise is the signal, so it is not logged).
+    def failed_read(key, default, error)
+      no_default = default == NO_DEFAULT_PROVIDED
+      raise error if no_default && @options.on_no_default == Quonfig::Options::ON_NO_DEFAULT::RAISE
 
-      nil
+      warn_read_failure(key, "#{error.message}; #{no_default ? 'returning nil' : 'returning the default'}")
+      no_default ? nil : default
     end
 
-    def coerce_and_check(key, value, expected_type)
-      case expected_type
-      when :bool
-        raise Quonfig::Errors::TypeMismatchError.new(key, 'Boolean', value) unless [true, false].include?(value)
-
-        value
-      when :string_list
-        arr = value.is_a?(Array) ? value : nil
-        raise Quonfig::Errors::TypeMismatchError.new(key, 'Array<String>', value) unless arr&.all?(String)
+    # Logs once per config key per client. The reason names the key and the
+    # types involved, never the value (it can be a decrypted secret).
+    def warn_read_failure(key, reason)
+      return unless @read_failure_mutex.synchronize { @read_failure_warned.add?(key.to_s) }
 
-        arr
-      when :duration
-        return value if value.is_a?(Integer)
-
-        millis = Quonfig::Duration.parse_millis(value)
-        raise Quonfig::Errors::TypeMismatchError.new(key, 'ISO-8601 Duration', value) if millis.nil?
-
-        millis
-      when :json
-        # JSON values are returned as-is (Hash, Array, or scalar from the wire).
-        value
-      when Class
-        raise Quonfig::Errors::TypeMismatchError.new(key, expected_type.to_s, value) unless value.is_a?(expected_type)
-
-        value
-      else
-        value
-      end
+      LOG.warn "[quonfig] read of #{key.to_s.inspect} returned no value: #{reason}"
     end
   end
 

data/lib/quonfig/config_loader.rb

@@ -300,7 +300,8 @@ module Quonfig
     # when a new event arrives. SSE is a single-leg live stream, so it carries no
     # config_api_urls index and does not change #resolved_from — but it IS
     # guarded by the same reject-older rule (a late SSE snapshot must not regress
-    # an established client).
+    # an established client). Returns :updated when the envelope installed and
+    # :not_modified when the guard dropped it.
     def apply_envelope(envelope)
       install_envelope(envelope, source: :sse, source_index: nil)
     end
@@ -494,11 +495,12 @@ module Quonfig
         envelope = parse_envelope(response.body)
         result = install_envelope(envelope, source: source, source_index: index)
         # Write this leg's ETag back AFTER the response (per-leg, race-free).
-        # Exception (qfg-9dxb.9): an ignored gen<=0 payload keeps the previous
-        # ETag. Its ETag is the git sha, and the server may later repair the
-        # generation for the SAME sha; remembering it would 304 that repair.
-        ignored_unversioned = result == :not_modified && extract_generation(envelope.meta || {}) <= 0
-        set_etag_for(index, new_etag) unless ignored_unversioned
+        # Exception (qfg-9dxb.9, qfg-j7ui; supervisor contract Test 11): an
+        # ignored gen<=0 payload, or one dropped as STRICTLY older, keeps the
+        # previous ETag. Its ETag is the git sha, and the server may later
+        # repair the generation for the SAME sha; remembering it would 304 that
+        # repair until the next commit. A same-generation 200 stores its ETag.
+        set_etag_for(index, new_etag) unless result == :not_modified && refused_by_generation?(envelope)
         end_oversized_episode(index) if result == :updated
         # install_envelope returns :not_modified when the reject-older guard drops
         # an equal/older payload — surface that so the caller doesn't double-count.
@@ -706,9 +708,22 @@ module Quonfig
         # SSE / datadir installs pass source_index nil and are ignored by the
         # aggregator, so they are never counted.
         @failover_aggregator&.record_resolved_from(source_index)
+        :updated
       end
     end
 
+    # Whether the reject-older guard refused this envelope as unversioned
+    # (gen <= 0) or strictly older than the held generation, rather than as a
+    # same-generation re-delivery. The held generation only rises, so a
+    # payload older at decision time is still older here.
+    def refused_by_generation?(envelope)
+      incoming_gen = extract_generation(envelope.meta || {})
+      return true if incoming_gen <= 0
+
+      held = @held_generation
+      !held.nil? && incoming_gen < held
+    end
+
     # The install decision for a network payload (see #install_envelope).
     def should_install?(incoming_gen)
       return true if @held_generation.nil?

data/lib/quonfig/errors/type_mismatch_error.rb

@@ -7,8 +7,11 @@ module Quonfig
       # class only. The value itself is never interpolated: it can be a
       # decrypted secret, and exception messages end up in logs and error
       # trackers (qfg-goi1.2.11).
-      def initialize(key, expected, actual_value)
-        super("Quonfig value for key '#{key}' expected #{expected}, got #{actual_value.class}")
+      # +actual_type+, when given, is the config's declared value type
+      # ('string', 'duration', ...) and is named instead of the Ruby class.
+      def initialize(key, expected, actual_value, actual_type: nil)
+        got = actual_type ? "a #{actual_type} value" : actual_value.class
+        super("Quonfig value for key '#{key}' expected #{expected}, got #{got}")
       end
     end
   end

data/lib/quonfig/evaluation_details.rb

@@ -19,6 +19,10 @@ module Quonfig
   #   "PROVIDER_NOT_READY" — the client has no config yet (init continued
   #                          on code defaults, or a caught init failure)
   #   "GENERAL"        — any other failure
+  #
+  # +value_type+ is set only by Client#evaluate_details: the stored value
+  # type ("string", "int", "double", "bool", "string_list", "duration",
+  # "json", ...), or nil when nothing resolved. The typed getters leave it nil.
   class EvaluationDetails
     REASON_STATIC          = 'STATIC'
     REASON_TARGETING_MATCH = 'TARGETING_MATCH'
@@ -31,16 +35,17 @@ module Quonfig
     ERROR_GENERAL        = 'GENERAL'
     ERROR_PROVIDER_NOT_READY = 'PROVIDER_NOT_READY'
 
-    attr_reader :value, :reason, :error_code, :error_message, :variant, :flag_metadata
+    attr_reader :value, :reason, :error_code, :error_message, :variant, :flag_metadata, :value_type
 
     def initialize(value:, reason:, error_code: nil, error_message: nil,
-                   variant: nil, flag_metadata: nil)
+                   variant: nil, flag_metadata: nil, value_type: nil)
       @value         = value
       @reason        = reason
       @error_code    = error_code
       @error_message = error_message
       @variant       = variant
       @flag_metadata = flag_metadata
+      @value_type    = value_type
     end
 
     def ==(other)
@@ -50,12 +55,13 @@ module Quonfig
         other.error_code == @error_code &&
         other.error_message == @error_message &&
         other.variant == @variant &&
-        other.flag_metadata == @flag_metadata
+        other.flag_metadata == @flag_metadata &&
+        other.value_type == @value_type
     end
     alias eql? ==
 
     def hash
-      [@value, @reason, @error_code, @error_message, @variant, @flag_metadata].hash
+      [@value, @reason, @error_code, @error_message, @variant, @flag_metadata, @value_type].hash
     end
 
     def inspect
@@ -64,6 +70,7 @@ module Quonfig
       parts << "error_message=#{@error_message.inspect}" if @error_message
       parts << "variant=#{@variant.inspect}" if @variant
       parts << "flag_metadata=#{@flag_metadata.inspect}" if @flag_metadata
+      parts << "value_type=#{@value_type.inspect}" if @value_type
       "#<Quonfig::EvaluationDetails #{parts.join(' ')}>"
     end
   end

data/lib/quonfig/resolver.rb

@@ -257,15 +257,27 @@ module Quonfig
         )
       end
 
+      # A missing, unmatched or empty key is a decryption failure too, so the
+      # typed getters apply the caller's default (qfg-zvyy). DecryptionError is
+      # a Quonfig::Error, so rescuing Quonfig::Error still catches it.
       key_cfg = @store.get(decrypt_with)
-      raise Quonfig::Error, %(Decryption key config "#{decrypt_with}" not found) if key_cfg.nil?
+      if key_cfg.nil?
+        raise Quonfig::Errors::DecryptionError.new(config_key(config),
+                                                   %(decryption key config "#{decrypt_with}" not found))
+      end
 
       key_match = @evaluator.evaluate_config(key_cfg, context, resolver: self)
-      raise Quonfig::Error, %(Decryption key config "#{decrypt_with}" did not match) if key_match.nil?
+      if key_match.nil?
+        raise Quonfig::Errors::DecryptionError.new(config_key(config),
+                                                   %(decryption key config "#{decrypt_with}" did not match))
+      end
 
       resolved_key = resolve_value_on_path(key_match.value, key_cfg, context, key_path)
       secret_key = vget(resolved_key, :value, 'value').to_s
-      raise Quonfig::Error, %(Decryption key from "#{decrypt_with}" is empty) if secret_key.empty?
+      if secret_key.empty?
+        raise Quonfig::Errors::DecryptionError.new(config_key(config),
+                                                   %(decryption key from "#{decrypt_with}" is empty))
+      end
 
       ciphertext = vget(value, :value, 'value').to_s
       begin

data/lib/quonfig/sse_config_client.rb

@@ -130,8 +130,10 @@ module Quonfig
       # ended on an event over MAX_EVENT_BYTES. While set, a keepalive is not
       # a frame, so a connection that only re-delivers the oversized snapshot
       # never reports connected and the fallback poller keeps config fresh.
-      # The first envelope clears it (and ends the WARN episode). Touched only
-      # by the worker thread.
+      # The first INSTALLED envelope clears it (and ends the WARN episode):
+      # the on_envelope block returns :updated for an install, and an
+      # envelope the reject-older guard drops neither clears the gate nor
+      # counts as a frame (qfg-6vno.20.8). Touched only by the worker thread.
       @oversized = false
     end
 
@@ -263,16 +265,22 @@ module Quonfig
             # 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.
+            #
+            # While the oversized gate is set the parser reports only
+            # envelopes as frames, and even those are deferred until the
+            # on_envelope block says the envelope installed (:updated): an
+            # envelope the reject-older guard drops is not an install, so it
+            # neither ends the episode nor makes the connection connected.
             frame_seen = false
-            on_frame = lambda do
-              # Gated, the parser reports only envelopes as frames; one ends
-              # the oversized episode.
-              @oversized = false
+            mark_frame = lambda do
               next if frame_seen
 
               frame_seen = true
               invoke_on_connected
             end
+            on_frame = lambda do
+              mark_frame.call unless @oversized
+            end
             begin
               ended_url = stream_once(on_frame) do |event|
                 # Persist the most recent id so the next reconnect resumes
@@ -284,7 +292,11 @@ module Quonfig
                 # qfg-m3lk: callback exceptions are isolated. A buggy
                 # listener must not look like a transport error and trigger
                 # a reconnect.
-                invoke_on_envelope_safely(on_envelope, event)
+                result = invoke_on_envelope_safely(on_envelope, event)
+                if @oversized && result == :updated
+                  @oversized = false
+                  mark_frame.call
+                end
               end
               # A clean EOF before any frame (200 headers then close) is a
               # failed attempt, exactly like a connect error: report it so
@@ -474,7 +486,7 @@ module Quonfig
 
     # Size caps R4: one WARN per oversized episode (redacted source + cap in
     # bytes), repeats at DEBUG. The episode lasts until an envelope gets
-    # through (@oversized cleared in run_loop's on_frame).
+    # through (@oversized cleared in run_loop at the first installed envelope).
     def handle_oversized_event(error)
       where = Quonfig::ConfigLoader.redact_userinfo("#{current_url}/api/v2/sse/config")
       msg = "SSE event from #{where} exceeds the maximum size of #{MAX_EVENT_BYTES} bytes; " \
@@ -497,7 +509,8 @@ module Quonfig
     # qfg-m3lk: rescue StandardError (NOT Exception) so SystemExit /
     # Interrupt / SignalException still escape — Ctrl-C inside a customer
     # callback must still kill the process. StandardError is the right
-    # boundary for "the caller's listener has a bug".
+    # boundary for "the caller's listener has a bug". Returns the block's
+    # value (:updated for an installed envelope), or nil when it raised.
     def invoke_on_envelope_safely(on_envelope, event)
       on_envelope.call(event.envelope, event, :sse)
     rescue StandardError => e

data/lib/quonfig/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: quonfig
 version: !ruby/object:Gem::Version
-  version: 1.11.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Jeff Dwyer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-23 00:00:00.000000000 Z
+date: 2026-10-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport