quonfig 1.7.2 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 07d679520810cf5814af80cd173f859976ce05ccd24f2c03bcbd417b57565a17
-  data.tar.gz: aebf8fecb3821bd58cfa1465028ddefadf977e1c4c30d11f18e486ef2c290e67
+  metadata.gz: c41b5b972edb95e3718fc1b46f693cf7a1800900e9228c9fd71542b6a775a001
+  data.tar.gz: c0d0f5f0c25d44b3d580285d0459a73e829827744c89cb5d8d4ab584fb13bc9a
 SHA512:
-  metadata.gz: 8823f04fc9b80149680bb384355309f2df1cca790932ede846c56f2a116f0aa9ae88858f956b43c11360aa546e979777652541e027a1865246335564c2d33b1a
-  data.tar.gz: 1f930fffeba37875820d6871d1b9ec83981579856d12e79a5c812919a1a41f9d262618450e986d138bd1bdd84d69eb9fd4a240bd678cecdfe3bf464c8cd25aa3
+  metadata.gz: b215ffbd82dc9bc5aef5211a11e8072ab5556637106dc85c65de50652c81849578b4b738d25d0fd4f0113d12ec39ed7aedd0f71bcf461646499e9b50b6001ede
+  data.tar.gz: 16836a6666e7e6648baa99f73ad4bf9c491638ad9e31d67a66821040f004ba4382ce6d7532fe40674f40c88ab0ccb467f94641b329e4ac5387590647df5be97f

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 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.**
+  - **No latch.** Before, the first SSE 401, 403 or 404 stopped the stream for the life of the client and kept the fallback poller off, so a key that was rejected once (or a transient primary 401) left the client on stale config until it was rebuilt. Now an auth-class stream response (401, 403, 404, and now 410) keeps the normal reconnect ladder, and the fallback poller engages on its usual schedule (at once if SSE never connected, 2x the poll interval after a mid-life drop).
+  - **Auth-failed.** A poll cycle (the fallback poller's, or each poll with `enable_sse: false`) that gets no 200 or 304 on any leg and a 401/403/404/410 on the primary leg puts the client in auth-failed. Primary rejected + secondary 503 or timeout enters; primary 503 + secondary rejected does not. While auth-failed: no stream, no polling, one fetch probe across every leg every 150-300s (with `enable_sse: false`, the larger of that and the poll interval), with no doubling and no give-up. The first probe that gets a valid 200 or a 304 on any leg installs it, logs one INFO and resumes streaming (from its base backoff) and polling. `connection_state` is `:disconnected` while auth-failed, never `:falling_back`.
+  - **Logging.** On entry: one ERROR, `config fetch rejected (HTTP <status> from <host:port>) ...`, naming the status and host, never the key, in place of that cycle's per-leg lines. Probes log at DEBUG. Before entry, an SSE 401/403/404/410 logs one WARN per status (re-armed by a 200) and DEBUG after that; before, a 401/403/404 logged one ERROR and a 410 logged two ERRORs per attempt. Other SSE errors (5xx) log as before.
+  - **`terminal_failure?` now means "auth-failed right now".** It turns true when a poll cycle is rejected as above (about 120s after a mid-life stream drop, at once if SSE never connected), not on the first SSE 401, and it goes back to false when a probe is accepted. Code that rebuilt the client when it saw `true` can stop doing so; the client recovers by itself. Name, signature and return type are unchanged.
+  - `SSEConfigClient::SSEHTTPTerminalError` and `TERMINAL_HTTP_CODES` are deprecated aliases of the new `SSEHTTPAuthError` and `AUTH_HTTP_CODES` (`[401, 403, 404, 410]`).
+  - Tests: supervisor contract Test 8 (a)-(g) (integration-test-data `v2026.10.16`, already contained in the pinned `v2026.10.16.1`) in `test/test_supervisor_auth_failure.rb`, plus the repro8 regression (a revoked key on every leg: one poll cycle, then probes, then recovery).
+- **UPGRADE: may change who matches a rule. Minor: one set of rule-operator semantics across the SDKs (qfg-goi1.5.7).** Pass dates to `PROP_BEFORE` / `PROP_AFTER` rules as epoch milliseconds (an Integer, a Float, or an all-digit string) or as an ISO 8601 / RFC3339 timestamp with `Z` or a numeric offset, such as `2025-01-01T00:00:00Z` or `2025-01-01T09:00:00+09:00`. Three changes:
+  - **Dates are strict on both sides.** The context value and the rule's date are now read with one grammar: epoch ms, or RFC3339 with an uppercase `T` and a `Z` or `+hh:mm` / `-hh:mm` offset (fractional seconds allowed, truncated to ms). `DateTime.parse` is gone, so a date-only string (`"2020-01-01"`), an offset-less one (`"2020-01-01T00:00:00"`, which was read as UTC) and free-form text (`"Jan 1 2020"`) are not dates any more, and a rule comparing them does not match. Digit strings no longer accept `Integer()` extras such as `"0x10"` or `"1_000"`. A `Float::NAN` or `Float::INFINITY` context date no longer raises `FloatDomainError`; it does not match.
+  - **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.
+- **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.
+- **CI: unit, contract and release tests now run integration-test-data `v2026.10.12` (qfg-goi1.10.21).** It adds the coercion-message cases above, confidential weighted-variant and ENV_VAR telemetry redaction cases, and an env-scoped decryption key case. The chaos workflows stay on `v2026.10.03`.
+- **Docs: the README now says that the SDK adds the `qfg login` email to every evaluation as `quonfig-user.email` by default, and how to turn it off (`enable_quonfig_user_context: false` or `QUONFIG_DEV_CONTEXT=false`) (qfg-goi1.2.40).** No code change.
+- **Fix (security, patch): a `confidential` or `decryptWith` variant inside a weighted rollout is now redacted in telemetry (qfg-goi1.2.39).** The evaluation-summary redaction looked only at the outer `weighted_values` wrapper, which is never flagged, so the selected variant went out as `selectedValue` in plaintext (for `decryptWith`, the decrypted secret). The selected variant is now sent as `*****<md5[0,5]>` over its stored value (the ciphertext for `decryptWith`), the same as a non-rollout secret and the same as sdk-go, sdk-node and sdk-java.
+- **Fix (patch): `Client#stdlib_formatter` no longer raises out of the host app's `::Logger` calls (qfg-goi1.2.28).** `Client#get` raises on a resolution error (for example `MissingEnvVarError` when the log level is provided by an env var that is unset on this host, or `DecryptionError`) even when a default is passed, and the formatter let that escape, so every `logger.info` raised. The formatter now emits the line in that case, the same as `SemanticLoggerFilter` since 1.7.2. `Client#should_log?` itself is unchanged.
+- **Fix (patch): example-context telemetry now copies the context when it is recorded (qfg-goi1.2.35).** The SDK kept the caller's nested Hashes and Arrays by reference and serialized them later on the telemetry thread, so changing them after `get` changed what was sent. A `Float::NAN` or `Float::INFINITY`, or a Hash or Array that contains itself, made the whole telemetry window fail to serialize, so that window's evaluation summaries, context shapes and example contexts were all lost. Now, at record time: nested Hashes and Arrays are copied (keys as strings, up to 32 levels deep), strings are copied, symbols become strings, NaN and Infinity become `null`, the edge that closes a cycle is left out, and any other object is sent as its `to_s`, as before (so a UUID-like key object still makes the example reportable). Only a value whose `to_s` raises is left out. Context shapes are unchanged. Evaluation is unchanged.
+- **Tests: the datadir auto-reload burst test no longer sleeps between writes (qfg-goi1.2.29).** A 10ms sleep between five rewrites could outlast the 150ms debounce on a starved CI runner, so the test saw more than one reload (it failed once on Ruby 3.2 CI). The writes are now back to back, and a new filesystem-free test drives `DatadirWatcher` directly: events in one window fire once, a later event fires again, and `stop` cancels a pending fire. No library change.
+- **Fix (patch): an install interrupted part-way through the store write is now repaired by the next delivery of the same envelope (qfg-goi1.10.2).** The SDK recorded the new config generation before it wrote the configs into the store, so an interrupt during the write (for example `Thread#raise` or `Timeout`) left a partly updated store marked as fully installed, and the same-generation redelivery that follows (SSE re-sends the current envelope on every connect) was ignored as a duplicate. The generation now advances only after the store write.
+- **Fix (patch): the SSE line reader no longer rescans its whole buffer on every chunk (qfg-goi1.10.2).** A long SSE line (a large config envelope) delivered in small chunks cost O(n^2) time: 100,000 one-byte chunks took about 9 seconds. Scanning now resumes where the previous chunk stopped, and the consumed bytes are dropped once per chunk instead of once per line. Parsing results are unchanged; there is still no size cap.
+
 ## 1.7.2 - 2026-10-09
 
 - **Fix (security): `TypeMismatchError` and `EnvVarParseError` messages no longer include the value (qfg-goi1.2.11).** Reading a `confidential` or `decryptWith` config through the wrong typed getter (for example `get_int` on a secret) put the decrypted plaintext into the exception message and into `*_details.error_message`, which end up in logs and error trackers. An unparseable ENV_VAR or a malformed stored duration put the raw value into `EnvVarParseError`. The messages now name the key, the expected type and the actual class (`TypeMismatchError`), or the key, the env var name (or `stored value`) and the target type (`EnvVarParseError`). The doubled word in `expected expected Integer` is fixed. Only the message text changes; the exception classes and when they are raised are unchanged.

data/README.md

@@ -82,6 +82,16 @@ bound.get_int('rate-limit')
 > `in_context` is a deprecated alias of `with_context` kept for backward
 > compatibility through 1.0.0. New code should use `with_context`.
 
+### Developer context (on by default)
+
+On a machine where someone ran `qfg login`, the SDK reads the signed-in email
+from `~/.quonfig/tokens.json` and adds it to every evaluation as
+`quonfig-user.email`, so rules can target it and it reaches telemetry example
+contexts; pass `enable_quonfig_user_context: false` or set
+`QUONFIG_DEV_CONTEXT=false` to turn it off. Servers without that file are
+unaffected, and a `quonfig-user` context you pass in `global_context:`
+replaces it.
+
 ## Datadir / offline mode
 
 For tests, CI, or air-gapped environments, point the client at a local workspace
@@ -246,6 +256,7 @@ for the cross-SDK story (sdk-node, sdk-go, sdk-ruby, sdk-python, sdk-java).
 | `QUONFIG_BACKEND_SDK_KEY`   | SDK key used to authenticate against the Quonfig API. Used when `sdk_key:` is omitted.   |
 | `QUONFIG_DIR`               | Path to a workspace directory. When set, the SDK runs in datadir/offline mode.           |
 | `QUONFIG_ENVIRONMENT`       | Environment name (`production`, `staging`, `development`) evaluated in datadir mode.     |
+| `QUONFIG_DEV_CONTEXT`       | `false` turns off the developer context (`quonfig-user.email` from `qfg login`). An explicit `enable_quonfig_user_context:` wins. See [Developer context](#developer-context-on-by-default). |
 | `QUONFIG_DOMAIN`            | Base domain used to derive api, sse, and telemetry URLs. Defaults to `quonfig.com`. Set to `quonfig-staging.com` to point at staging. Explicit `api_urls:` / `telemetry_url:` kwargs override this. |
 
 ## Constructor options
@@ -279,6 +290,7 @@ Quonfig::Client.new(
 | `init_timeout_ms` | `Integer` (ms)             | `10_000`                                                            | Maximum time to wait for the initial config load, in milliseconds. Deprecated alias: `initialization_timeout_sec` (seconds, multiplied by 1000 internally). |
 | `on_no_default`   | `Symbol`                   | `:raise`                                                            | Behavior when a key has no value and no default: `:raise` (raise `Quonfig::Errors::MissingDefaultError`) or `:return_nil`. |
 | `global_context`  | `Hash`                     | `{}`                                                                | Context applied to every evaluation.                                                              |
+| `enable_quonfig_user_context` | `Boolean` or `nil`  | `nil` (on, unless `QUONFIG_DEV_CONTEXT=false`)                      | Add the `qfg login` email as `quonfig-user.email`. See [Developer context](#developer-context-on-by-default). |
 | `datadir`         | `String`                   | `ENV['QUONFIG_DIR']`                                                | Path to a local workspace. When set, the SDK runs offline from disk.                              |
 | `environment`     | `String`                   | `ENV['QUONFIG_ENVIRONMENT']`                                        | Environment to evaluate in datadir mode. Required when `datadir` is set.                          |
 | `data_dir_auto_reload`              | `Boolean`         | `false`                                                             | Datadir mode only. When `true`, the SDK watches the datadir and re-reads the envelope when files change. See [Datadir mode: auto-reload on file changes](#datadir-mode-auto-reload-on-file-changes). |
@@ -664,6 +676,18 @@ process.
 
 There is intentionally no `client.healthy?` primitive.
 
+### A rejected SDK key
+
+When a whole config fetch cycle is rejected (no 200 or 304 on any leg, and a
+401, 403, 404 or 410 on the primary), the SDK key is invalid or revoked. The
+SDK logs one ERROR naming the status and host, stops streaming and polling,
+and retries with one fetch every 150-300 seconds for as long as the process
+runs. The first accepted fetch installs the config, logs one INFO, and resumes
+streaming and polling on its own; you do not need to rebuild the client. While
+this lasts `client.connection_state` is `:disconnected` and
+`client.terminal_failure?` is `true`. A rejection on the stream alone never
+does this: the SDK keeps reconnecting and its fallback poller decides.
+
 ## Telemetry
 
 With an SDK key the client sends usage telemetry to `telemetry_url` so the

data/lib/quonfig/client.rb

@@ -21,6 +21,10 @@ module Quonfig
   class Client
     LOG = Quonfig::InternalLogger.new(self)
 
+    # Auth-failed probe period bounds, rule R3 (qfg-goi1.10.26).
+    AUTH_PROBE_MIN_SECONDS = 150.0
+    AUTH_PROBE_MAX_SECONDS = 300.0
+
     # qfg-ryov: instance registry for the Process._fork hook. Every live
     # Client is tracked here so the hook can fan out after_fork_in_child
     # across all of them without the customer needing to name a specific
@@ -86,7 +90,11 @@ module Quonfig
       @sse_state = :idle
       @sse_ever_connected = false
       @fallback_engage_timer = nil
-      @sse_terminal_failure = false
+      # Auth-failed regime (rule R2-R4, qfg-goi1.10.26). Set by the poller's
+      # fetch cycle on entry, cleared by the first accepted probe. While set:
+      # no SSE, no polling, one probe per [150s, 300s]. Read by
+      # #terminal_failure? and #connection_state.
+      @auth_failed = false
       # The process that owns this client's threads, sockets, and store.
       # Re-stamped when a child takes ownership in #rebuild_in_child!. A pid
       # mismatch is PROOF that we are looking at a fork(2) child, which is
@@ -493,7 +501,7 @@ module Quonfig
       # (it had connected, it had errored, ...). None of them apply here.
       @sse_state = :idle
       @sse_ever_connected = false
-      @sse_terminal_failure = false
+      @auth_failed = false
       @sse_error_callback = nil
 
       # A client that never finished network init has nothing to rebuild.
@@ -581,6 +589,9 @@ module Quonfig
         # running. Saying so is the honest answer, and a diagnostic must not
         # be what triggers a blocking fetch.
         next :initializing if @fork_rebuild_pending
+        # Auth-failed is not a state of its own (R6): SSE and the poller are
+        # off, so the client is disconnected, never falling_back.
+        next :disconnected if @auth_failed
         next :falling_back if @poll_supervisor&.alive?
         # Liveness beats the stored flag (qfg-lv4n.1). A client whose SSE
         # session was torn down keeps a stale @sse_state; answering
@@ -1079,31 +1090,27 @@ module Quonfig
       @sse_error_callback ||= ->(error) { handle_sse_error(error) }
     end
 
-    def handle_sse_error(error)
-      # qfg-i5xv: classify terminal HTTP failures (401/403/404). The same SDK
-      # key that won't auth over SSE won't auth over HTTP polling either, so
-      # we must NOT engage the Layer 2 fallback — that just moves the
-      # auth-failure storm from one endpoint to another. Once flipped,
-      # @sse_terminal_failure latches: a buggy customer retry loop cannot
-      # un-classify the failure by driving the state machine.
-      @state_mutex.synchronize { @sse_terminal_failure = true } if error.is_a?(Quonfig::SSEConfigClient::SSEHTTPTerminalError)
+    # 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
+    # its fetch cycle decides.
+    def handle_sse_error(_error)
       handle_sse_state_change(:error)
     end
 
     def handle_sse_state_change(new_state)
       state = new_state.to_sym
-      ever_connected, terminal = @state_mutex.synchronize do
+      ever_connected, auth_failed = @state_mutex.synchronize do
         @sse_state = state
         @sse_ever_connected = true if state == :connected
-        [@sse_ever_connected, @sse_terminal_failure]
+        [@sse_ever_connected, @auth_failed]
       end
 
       return unless @options.respond_to?(:fallback_poll_enabled) && @options.fallback_poll_enabled
       return if @stopped
-      # qfg-i5xv: a terminal SSE classification suppresses polling engage in
-      # every branch — the customer's key is bad and HTTP polling will fail
-      # identically. Operators surface this via #terminal_failure?.
-      return if terminal
+      # While auth-failed SSE is stopped; a late edge from the stream being
+      # torn down changes nothing (the probe loop owns the schedule).
+      return if auth_failed
 
       case state
       when :connected
@@ -1120,15 +1127,22 @@ module Quonfig
 
     public
 
-    # qfg-i5xv: true once the SSE layer has classified an HTTP response as
-    # terminal (401/403/404) — bad SDK key, revoked workspace permission,
-    # or wrong endpoint. The classification latches: the SDK will not
-    # auto-recover, and a customer-supplied retry must rebuild the client.
-    # Surfaced for operator alerting; `connection_state` still reports
-    # `:disconnected` to honor the documented connection_state vocabulary
-    # (supervisor-test-contract.md §"connectionState()" — values fixed).
+    # True while the client is auth-failed (since 1.8.0, qfg-goi1.10.26): a
+    # whole config fetch cycle got no 200/304 on any leg and a 401, 403, 404
+    # or 410 on the primary leg, which means the SDK key is invalid or
+    # revoked. It turns true when the fallback poller's cycle (or, with
+    # +enable_sse: false+, a poll) is rejected: about 120s after a mid-life
+    # stream drop, at once if SSE never connected. While true, SSE and polling
+    # are off and the client sends one fetch probe every 150-300s. It goes back
+    # to false on the first probe that gets a valid 200 or a 304, and the
+    # client resumes streaming and polling on its own; there is no need to
+    # rebuild the client.
+    #
+    # Before 1.8.0 this latched true on the first SSE 401/403/404 for the life
+    # of the client (qfg-i5xv). +connection_state+ reports +:disconnected+
+    # while this is true.
     def terminal_failure?
-      @state_mutex.synchronize { @sse_terminal_failure }
+      @state_mutex.synchronize { @auth_failed }
     end
 
     private
@@ -1179,7 +1193,7 @@ module Quonfig
 
         @fallback_engage_timer = Thread.new do
           Thread.current.report_on_exception = false
-          sleep grace_seconds
+          Quonfig::Waits.sleep(:engage, grace_seconds)
           @state_mutex.synchronize { @fallback_engage_timer = nil }
           start_polling unless @stopped
         end
@@ -1522,30 +1536,41 @@ module Quonfig
       # engage() (immediate Fetch, then ticker). A sleep-first worker made the
       # first post-engage data arrive a full extra interval late (~180s after
       # SSE loss with the default 60s interval, vs ~120s in go).
+      #
+      # Auth-failure rule (qfg-goi1.10.26, R2-R4): a poll cycle with no 200/304
+      # on any leg and an auth-class status on the primary enters auth-failed.
+      # The same worker then probes once per T in [150s, 300s] (polling mode:
+      # max(T, interval)) until a probe is accepted. The flag lives on the
+      # client, so a supervisor restart of this worker keeps probing.
       worker = lambda do |notify_delivered|
         loop do
           break if stopped_ref.call
 
-          result = @config_loader.fetch!
-          # Liveness honesty (qfg-41nh.6): stamp freshness only when the fetch
-          # actually SUCCEEDED. :updated and :not_modified (a 304, or a
-          # guard-rejected-but-successful response) are successes — the
-          # channel is healthy; :failed must NOT advance
-          # last_successful_refresh (pre-fix every tick stamped + notified
-          # regardless of outcome, so ready?/freshness reported healthy over
-          # an empty store through a total outage). on_update fires only on a
-          # real install, matching sdk-go (OnConfigUpdate fires in
-          # installEnvelope only).
-          if result != :failed
-            sync_evaluator_env_id!
-            record_refresh!
-            notify_delivered.call
+          if auth_failed?
+            Quonfig::Waits.sleep(:probe, auth_probe_wait(poll_seconds))
+            break if stopped_ref.call
+
+            case run_auth_probe(notify_delivered)
+            when :rejected then next
+            when :handed_to_sse then break
+            end
+            # Accepted in polling mode: resume at the interval, no immediate
+            # fetch (the probe just fetched).
+            Quonfig::Waits.sleep(:poll, poll_seconds)
+            next
           end
-          notify_on_update_callback if result == :updated
+
+          cycle = @config_loader.fetch_cycle!(log_mode: :poll)
+          if cycle.auth_rejected?
+            enter_auth_failed!(cycle) unless stopped_ref.call
+            next
+          end
+
+          after_poll_result(cycle.result, notify_delivered)
 
           break if stopped_ref.call
 
-          sleep poll_seconds
+          Quonfig::Waits.sleep(:poll, poll_seconds)
         end
       end
 
@@ -1560,6 +1585,85 @@ module Quonfig
       LOG.warn "[quonfig] Layer 2 fallback poller engaged (interval=#{poll_ms}ms)"
     end
 
+    # Liveness honesty (qfg-41nh.6): stamp freshness only when the fetch
+    # actually SUCCEEDED. :updated and :not_modified (a 304, or a
+    # guard-rejected-but-successful response) are successes — the channel is
+    # healthy; :failed must NOT advance last_successful_refresh (pre-fix every
+    # tick stamped + notified regardless of outcome, so ready?/freshness
+    # reported healthy over an empty store through a total outage). on_update
+    # fires only on a real install, matching sdk-go (OnConfigUpdate fires in
+    # installEnvelope only).
+    def after_poll_result(result, notify_delivered)
+      if result != :failed
+        sync_evaluator_env_id!
+        record_refresh!
+        notify_delivered.call
+      end
+      notify_on_update_callback if result == :updated
+    end
+
+    def auth_failed?
+      @state_mutex.synchronize { @auth_failed }
+    end
+
+    # Rule R3: T uniform in [150s, 300s], re-drawn per probe, never doubled.
+    # With SSE disabled the wait is max(T, poll interval). Internal: tests
+    # reach it through Quonfig::Waits, it is not a customer option.
+    def auth_probe_wait(poll_seconds)
+      t = AUTH_PROBE_MIN_SECONDS + (rand * (AUTH_PROBE_MAX_SECONDS - AUTH_PROBE_MIN_SECONDS))
+      t = poll_seconds if !@options.enable_sse && poll_seconds > t
+      t
+    end
+
+    # Entry (R2-R5), on the poller's thread, in this order: SSE off (stream
+    # closed and its worker joined, the engage timer cancelled), the flag up,
+    # then one ERROR naming the status and the primary host, never the key.
+    def enter_auth_failed!(cycle)
+      cancel_fallback_engage_timer
+      sse = @state_mutex.synchronize do
+        @auth_failed = true
+        @sse_state = :idle
+        s = @sse_client
+        @sse_client = nil
+        s
+      end
+      begin
+        sse&.close
+      rescue StandardError => e
+        LOG.debug "Error closing SSE client on auth-failed entry: #{e.message}"
+      end
+      LOG.error "[quonfig] config fetch rejected (HTTP #{cycle.primary_status} from #{cycle.primary_host}): " \
+                'the SDK key is invalid or revoked (check the SDK key); streaming and polling stopped, ' \
+                'retrying every few minutes until it is accepted'
+    end
+
+    # One auth-failed probe: a fetch cycle across every leg (R3), logged at
+    # DEBUG only. The first valid 200 or a 304 on any leg exits (R4): one
+    # INFO, and SSE restarts from its base backoff (a brand-new stream
+    # client), handing the update channel back from this poller. With SSE
+    # disabled the poller resumes polling. Returns :rejected, :handed_to_sse
+    # or :resume_polling.
+    def run_auth_probe(notify_delivered)
+      cycle = @config_loader.fetch_cycle!(log_mode: :probe)
+      if cycle.result == :failed
+        LOG.debug "[quonfig] auth-failed probe rejected (HTTP #{cycle.primary_status} from #{cycle.primary_host}); " \
+                  'retrying later'
+        return :rejected
+      end
+
+      after_poll_result(cycle.result, notify_delivered)
+      handing_to_sse = @options.enable_sse && !@stopped
+      # Stop this poller first (from its own thread: WorkerSupervisor#stop only
+      # flags it) so connection_state never reads falling_back on the way out.
+      stop_fallback_poller('auth-recovered') if handing_to_sse
+      @state_mutex.synchronize { @auth_failed = false }
+      LOG.info '[quonfig] config fetch accepted; leaving auth-failed and resuming streaming and polling'
+      return :resume_polling unless handing_to_sse
+
+      start_sse
+      :handed_to_sse
+    end
+
     # Invoke the customer-supplied on_update callback under a rescue. A raise
     # here is the customer's bug, but it must NOT take down the SSE listener
     # or polling supervisor. Log at ERROR with a message containing
@@ -1794,7 +1898,7 @@ module Quonfig
     end
 
     def malformed_stored_duration_error(result)
-      Quonfig::Errors::EnvVarParseError.new(result.raw_value, result.config || {}, 'stored value')
+      Quonfig::Errors::EnvVarParseError.new(result.raw_value, result.config || {}, nil, stored: true)
     end
 
     def malformed_duration(key, default, error)

data/lib/quonfig/config_loader.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'uri'
 
 module Quonfig
   # Fetches config envelopes from the Quonfig delivery API and installs them
@@ -18,6 +19,79 @@ module Quonfig
 
     CONFIGS_PATH = '/api/v2/configs'
 
+    # Rule R1 (qfg-goi1.10.26): the auth class. A fetch cycle with no 200/304
+    # on any leg and one of these on the primary leg is rejected; the client's
+    # poller then enters auth-failed (Client#start_polling).
+    AUTH_STATUSES = [401, 403, 404, 410].freeze
+
+    # Result of one fetch cycle across the configured legs. +statuses+ maps a
+    # config_api_urls index to the HTTP status that leg returned (0 = no
+    # response: timeout, connection failure). +primary_host+ is host:port of
+    # the primary leg, for the entry ERROR (never the key).
+    class FetchCycle
+      attr_reader :result, :statuses, :primary_host
+
+      def initialize(result, statuses, primary_host)
+        @result = result
+        @statuses = statuses
+        @primary_host = primary_host
+      end
+
+      def primary_status
+        @statuses[0] || 0
+      end
+
+      # Rule R2: no leg returned 200/304 and the primary returned an
+      # auth-class status. A 200 the guard dropped, or a 304, never qualifies.
+      def auth_rejected?
+        return false unless @result == :failed
+        return false if @statuses.values.any? { |s| [200, 304].include?(s) }
+
+        AUTH_STATUSES.include?(primary_status)
+      end
+    end
+
+    # Collects one cycle's per-leg log lines. +mode+:
+    #   :normal - log at once, as always (init fetch, refresh, legacy callers)
+    #   :poll   - a poller cycle: hold the auth-class lines until the cycle is
+    #             classified, so an entering cycle logs its one ERROR in their
+    #             place (rule R5); otherwise they are logged unchanged
+    #   :probe  - an auth-failed probe: every line at DEBUG (rule R5)
+    class CycleLog
+      def initialize(logger, mode)
+        @logger = logger
+        @mode = mode
+        @held = []
+        @released = false
+        @mutex = Mutex.new
+      end
+
+      def log(level, msg, auth: false)
+        return @logger.debug(msg) if @mode == :probe
+
+        if @mode == :poll && auth
+          hold = @mutex.synchronize do
+            @held << [level, msg] unless @released
+            !@released
+          end
+          return if hold
+        end
+        @logger.public_send(level, msg)
+      end
+
+      # Log (or with +drop+, discard) the held lines. Lines from a leg that
+      # settles later are logged as they come.
+      def release(drop: false)
+        held = @mutex.synchronize do
+          @released = true
+          h = @held
+          @held = []
+          h
+        end
+        held.each { |level, msg| @logger.public_send(level, msg) } unless drop
+      end
+    end
+
     attr_reader :version, :environment_id
 
     # qfg-7h5d.1.9 (canonical ordering). Diagnostic surface read by the failover/
@@ -127,17 +201,32 @@ module Quonfig
     #   :not_modified  -- a leg answered 304 (no change) and nothing installed
     #   :failed        -- every fired leg failed
     def fetch!
+      fetch_cycle!.result
+    end
+
+    # One fetch cycle, as #fetch!, returning a FetchCycle that carries each
+    # leg's status (rule R2, qfg-goi1.10.26). +log_mode+ is one of CycleLog's
+    # modes; the poller passes :poll for an ordinary cycle and :probe while
+    # auth-failed.
+    def fetch_cycle!(log_mode: :normal)
       urls = Array(@options.config_api_urls)
-      return :failed if urls.empty?
+      statuses = Concurrent::Map.new
+      return FetchCycle.new(:failed, statuses, '') if urls.empty?
 
+      cycle_log = CycleLog.new(@logger, log_mode)
       # Single leg (or no secondary configured): no hedge, just fetch on the
       # calling thread under the SEQUENTIAL per-URL timeout (config_fetch_timeout_ms
       # is unchanged and still governs any non-hedged path). Preserves the
       # synchronous, single-request-per-call shape the legacy/mock callers depend
       # on.
-      return fetch_from(urls[0], 0, timeout_ms: config_fetch_timeout_ms) if urls.length < 2
-
-      fetch_hedged(urls)
+      result = if urls.length < 2
+                 fetch_from(urls[0], 0, timeout_ms: config_fetch_timeout_ms, statuses: statuses, cycle_log: cycle_log)
+               else
+                 fetch_hedged(urls, statuses: statuses, cycle_log: cycle_log)
+               end
+      cycle = FetchCycle.new(result, statuses, host_of(urls[0]))
+      cycle_log.release(drop: cycle.auth_rejected?)
+      cycle
     end
 
     # Apply a ConfigEnvelope (from SSE) to the store. Called by the SSE client
@@ -176,7 +265,7 @@ module Quonfig
     # the hedge abort inside fetch_from, and heals forward through the
     # reject-older guard. We never join the slow leg — a hung primary must not
     # block a successful secondary install.
-    def fetch_hedged(urls)
+    def fetch_hedged(urls, statuses: nil, cycle_log: nil)
       hedge_delay_s = hedge_delay_ms / 1000.0
       abort_ms = hedge_abort_ms
 
@@ -204,7 +293,7 @@ module Quonfig
         Thread.new do
           result = :failed
           begin
-            result = fetch_from(urls[index], index, timeout_ms: abort_ms)
+            result = fetch_from(urls[index], index, timeout_ms: abort_ms, statuses: statuses, cycle_log: cycle_log)
           rescue StandardError => e
             @logger.debug "Hedge leg #{index} failed: #{e.class}: #{e.message}"
           ensure
@@ -306,7 +395,15 @@ module Quonfig
       @options.respond_to?(:config_fetch_timeout_ms) ? @options.config_fetch_timeout_ms : nil
     end
 
-    def fetch_from(source, index = nil, timeout_ms: nil)
+    def host_of(url)
+      uri = URI(url.to_s)
+      uri.host ? "#{uri.host}:#{uri.port}" : url.to_s
+    rescue URI::InvalidURIError
+      ''
+    end
+
+    def fetch_from(source, index = nil, timeout_ms: nil, statuses: nil, cycle_log: nil)
+      cycle_log ||= CycleLog.new(@logger, :normal)
       # qfg-7h5d.1.9 / .1.14: bound this single per-leg attempt so a hung upstream
       # aborts (Faraday::TimeoutError, caught below as :failed). On the hedged
       # path the caller passes config_fetch_hedge_abort_ms; on the sequential /
@@ -318,6 +415,7 @@ module Quonfig
       etag = etag_for(index)
       headers['If-None-Match'] = etag if etag
       response = conn.get(CONFIGS_PATH, headers)
+      statuses[index || 0] = response.status.to_i if statuses
 
       case response.status
       when 200
@@ -337,23 +435,24 @@ module Quonfig
         @logger.debug "Configs not modified (304) from #{source}"
         :not_modified
       when 401, 403
-        @logger.warn "Config fetch rejected (#{response.status}) from #{source}: #{short_body(response)}"
+        cycle_log.log(:warn, "Config fetch rejected (#{response.status}) from #{source}: #{short_body(response)}", auth: true)
         :failed
       else
-        @logger.info "Config fetch failed: status #{response.status} from #{source}"
+        cycle_log.log(:info, "Config fetch failed: status #{response.status} from #{source}",
+                      auth: AUTH_STATUSES.include?(response.status.to_i))
         :failed
       end
     rescue NonEnvelopeError => e
       # qfg-9dxb.3: a non-envelope 200 is a leg error, NOT an install — the
       # hedge/failover proceeds and this leg's ETag is never stored (so a junk
       # 200 cannot pin itself through later 304s).
-      @logger.warn "Config fetch from #{source} returned a non-envelope 200 (#{e.message}); treating as a failed leg"
+      cycle_log.log(:warn, "Config fetch from #{source} returned a non-envelope 200 (#{e.message}); treating as a failed leg")
       :failed
     rescue Faraday::ConnectionFailed => e
       @logger.debug "Connection failure fetching configs from #{source}: #{e.message}"
       :failed
     rescue StandardError => e
-      @logger.warn "Unexpected error fetching configs from #{source}: #{e.message}"
+      cycle_log.log(:warn, "Unexpected error fetching configs from #{source}: #{e.message}")
       :failed
     end
 
@@ -461,6 +560,25 @@ module Quonfig
         @version = meta['version'] || meta[:version] || @version
         @environment_id = meta['environment'] || meta[:environment] || @environment_id
 
+        # Replace the live store first, then advance the generation
+        # (qfg-goi1.10.2). An interrupt part-way through the store write
+        # (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.
+        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)
+
+          envelope.configs.each do |cfg|
+            key = config_key(cfg)
+            next if key.nil?
+
+            @store.set(key, cfg)
+          end
+        end
+
         # qfg-9dxb.3 Fix A: an unversioned install (generation <= 0) carries no
         # ordering info and must never LOWER a positive held generation. Under
         # the qfg-9dxb.9 rule it only installs when held is nil/0 anyway, so
@@ -473,21 +591,6 @@ 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)
-
-        # Replace the live store atomically.
-        return if @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)
-
-        envelope.configs.each do |cfg|
-          key = config_key(cfg)
-          next if key.nil?
-
-          @store.set(key, cfg)
-        end
       end
     end