quonfig 1.7.1 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b22d7d46b27ff2ab1452b41eaa68940d886216aaeb16c61a3faddf0778d352c
-  data.tar.gz: 0ca1f8e621bcfcd839a28d1d754560b5cf023eff205b24b83049196e64a8e4b0
+  metadata.gz: c41b5b972edb95e3718fc1b46f693cf7a1800900e9228c9fd71542b6a775a001
+  data.tar.gz: c0d0f5f0c25d44b3d580285d0459a73e829827744c89cb5d8d4ab584fb13bc9a
 SHA512:
-  metadata.gz: 720d2acbfe8d30a785c1197fa319d608b1b4e11a1b60657b23d7b3dd921ed0c4882c99e7446b469a009552f09ca54538482509d9dc6a6968dc11df6f0e42d7c2
-  data.tar.gz: 11a8f0fbb7851dba082a46a7b657e9ec49aa61ae4af155cf9bf2272a35a3e5f75fa8148acdf0f3df8b936798cae5d8619dbc86bb981199f5bf29ceadf5f79567
+  metadata.gz: b215ffbd82dc9bc5aef5211a11e8072ab5556637106dc85c65de50652c81849578b4b738d25d0fd4f0113d12ec39ed7aedd0f71bcf461646499e9b50b6001ede
+  data.tar.gz: 16836a6666e7e6648baa99f73ad4bf9c491638ad9e31d67a66821040f004ba4382ce6d7532fe40674f40c88ab0ccb467f94641b329e4ac5387590647df5be97f

data/CHANGELOG.md

@@ -1,5 +1,44 @@
 # 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.
+- **Fix: datadir mode and the dev-context loader read their JSON files as UTF-8 whatever the process locale (qfg-goi1.2.11, qfg-xy92).** Under `LANG` unset or `LANG=C` (systemd units, cron, many minimal and distroless images) Ruby's default external encoding is US-ASCII, and any non-ASCII byte in a config file (for example an em dash in a `description`) or in `quonfig.json` made `Client.new` raise `Encoding::InvalidByteSequenceError`, so the app could not boot in datadir mode. The same applied to a non-ASCII email in `~/.quonfig/tokens.json`. These files are now always read as UTF-8.
+- **Fix: `SemanticLoggerFilter` no longer raises out of the host app's log calls (qfg-goi1.2.11).** `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 filter let that escape, so every log call through SemanticLogger raised. The filter now treats any such error like a missing key: it returns `true` and SemanticLogger's own static level decides.
+- **Docs: the README typed-getter section now matches the code (qfg-goi1.2.11).** It documented `get_string(key, contexts = nil)`, said a missing key or a type mismatch returns `nil`, and said `get_duration` returns `Float` seconds; the examples passed the context as `user: {...}`, which raises `ArgumentError: unknown keyword: :user`. The getters are `get_*(key, default:, context:)`; a missing key returns `default:` or follows `on_no_default` (`:raise` by default); a type mismatch raises `TypeMismatchError`; `get_duration` returns integer milliseconds. No code change.
+- **Fix: concurrent `Quonfig.init` calls build one client (qfg-goi1.2.11).** The "already initialized" check ran outside the write lock, so two threads calling `Quonfig.init` at the same time could each build a `Client`, leaving one orphaned with a live SSE stream and telemetry thread that nothing stopped. The check is now repeated inside the lock; the second caller gets the existing client and the usual "already initialized" warning.
+- **Tests: pin `minitest` below 6 in the Gemfile (qfg-goi1.2.11).** A fresh resolve without `Gemfile.lock` picked minitest 6.0.6, which drops `minitest/mock`, and the suite failed to load. The committed lock already held 5.27.0, so CI was unaffected. No library change.
+- **Fix: `PROP_MATCHES` / `PROP_DOES_NOT_MATCH` regexes have a 0.1s match timeout on Ruby 3.2+ (qfg-goi1.2.11).** A pattern that backtracks catastrophically (backreferences and lookarounds defeat Ruby 3.2's regex memoization) could pin the evaluating thread for seconds to hours. On Ruby 3.2+ the match now stops after 0.1s and the criterion does not match, the same as an invalid regex. Ruby 3.0 and 3.1 have no regex timeout and are unchanged.
+- **Chaos: `server_metric(...)` expectations are now reported as SKIPPED with a reason instead of silently evaluating to 0 and passing (qfg-goi1.1.3).** api-delivery exports its metrics only by OTLP push, so the rig has nothing to scrape; server-side lag is covered by the staging drill (qfg-47c2.19) and the `QuonfigSubscriberLagHigh` alert. Each skipped expectation prints a `SKIP` line with the reason, the scenario summary counts skips separately, and the run ends with a tally of every skipped expression. In a compound expression the skipped leaf is neutral: the other leaves are still enforced (scenario 02 still requires `connected`). No library change.
+- **Chaos: an unknown `client.sdkMetric(...)` name now fails the expectation with `unknown sdkMetric "<name>"` instead of silently evaluating to 0 (qfg-goi1.2.21).** The chaos probe returned 0 for any metric it did not implement, so a typo such as `client.sdkMetric('typo_total') == 0` passed without checking anything. The probe now reports the name as unknown and the evaluator fails loudly, matching sdk-go. Every metric name used by integration-test-data `v2026.10.03` is implemented, so no current result changes. No library change.
+- **CI: the Chaos and Failover Chaos workflows now run integration-test-data `v2026.10.03`, the same tag as the unit and contract tests (qfg-goi1.1.3).** They were on `v2026.05.13` and `v2026.06.19.1`. The new tag adds the continuous freshness hold on scenario 05-sse-down (qfg-e3ja). Both workflows still build api-delivery from `main` on purpose (they exist to catch api-delivery drift) and now write the resolved api-delivery SHA to the run summary. No library change.
+
 ## 1.7.1 - 2026-10-03
 
 - **Behaviour change (bug fix): weighted rollouts now hash non-ASCII text the same way as every other Quonfig SDK (qfg-1mvb).** The MurmurHash3 used to pick a weighted variant counted characters instead of UTF-8 bytes, so a config key or hash value containing non-ASCII text (for example `josé`, `日本語`, `🚀`) hashed to a different number than sdk-java, sdk-python, sdk-go and sdk-node. It now hashes the UTF-8 bytes. Ruby users whose hash value (or the flag's key) contains non-ASCII characters may move to a different variant on upgrade; afterwards they get the same variant as in the other SDKs. ASCII-only values and keys are unchanged.

data/README.md

@@ -35,8 +35,8 @@ limit   = client.get_int('rate-limit')
 name    = client.get_string('app.display-name')
 regions = client.get_string_list('allowed-regions')
 
-# Context-aware evaluation — pass a context hash as the last argument
-value = client.get_string('homepage-hero', user: { key: 'user-123', country: 'US' })
+# Context-aware evaluation — pass a context hash with `context:`
+value = client.get_string('homepage-hero', context: { user: { key: 'user-123', country: 'US' } })
 ```
 
 ## Context
@@ -47,7 +47,7 @@ attach a context in three ways:
 ### 1. Per-call context
 
 ```ruby
-client.get_bool('beta-feature', user: { key: 'user-123', plan: 'pro' })
+client.get_bool('beta-feature', context: { user: { key: 'user-123', plan: 'pro' } })
 ```
 
 ### 2. `with_context` block
@@ -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). |
@@ -333,31 +345,43 @@ model.
 
 ## Typed getters
 
-Each typed getter takes a config key and an optional context hash. If the key
-is missing or the stored value does not match the requested type, the getter
-returns `nil`.
-
-| Method                                          | Returns                       |
-|-------------------------------------------------|-------------------------------|
-| `get_string(key, contexts = nil)`               | `String` or `nil`             |
-| `get_int(key, contexts = nil)`                  | `Integer` or `nil`            |
-| `get_float(key, contexts = nil)`                | `Float` or `nil`              |
-| `get_bool(key, contexts = nil)`                 | `true`, `false`, or `nil`     |
-| `get_string_list(key, contexts = nil)`          | `Array<String>` or `nil`      |
-| `get_duration(key, contexts = nil)`             | `Float` (seconds) or `nil`    |
-| `get_json(key, contexts = nil)`                 | `Hash`, `Array`, or `nil`     |
-| `enabled?(feature_name, contexts = nil)`        | `true` or `false`             |
+Each typed getter takes a config key plus two optional keyword arguments:
+`default:` (returned when the key is missing) and `context:` (a context hash
+for this call). On a `BoundClient` (see `with_context` above) the getters take
+only `default:`; the context is the bound one.
+
+- **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:`.
+
+| Method                                              | Returns                                   |
+|-----------------------------------------------------|-------------------------------------------|
+| `get_string(key, default:, context:)`               | `String`                                  |
+| `get_int(key, default:, context:)`                  | `Integer`                                 |
+| `get_float(key, default:, context:)`                | `Float`                                   |
+| `get_bool(key, default:, context:)`                 | `true` or `false`                         |
+| `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)  |
+
+`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`.
 
 Example:
 
 ```ruby
 client.get_string('app.display-name')
-client.get_int('rate-limit', user: { key: 'user-123' })
-client.get_float('pricing.multiplier')
-client.get_bool('flags.new-checkout')
-client.get_string_list('allowed-regions')
-client.get_duration('request-timeout')
-client.get_json('homepage.layout')
+client.get_int('rate-limit', default: 100, context: { user: { key: 'user-123' } })
+client.get_float('pricing.multiplier', default: 1.0)
+client.get_bool('flags.new-checkout', default: false)
+client.get_string_list('allowed-regions', default: [])
+client.get_duration('request-timeout', default: 5_000) # milliseconds
+client.get_json('homepage.layout', default: {})
 client.enabled?('beta-feature', user: { key: 'user-123' })
 ```
 
@@ -652,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)
@@ -1830,7 +1934,7 @@ module Quonfig
         # JSON values are returned as-is (Hash, Array, or scalar from the wire).
         value
       when Class
-        raise Quonfig::Errors::TypeMismatchError.new(key, "expected #{expected_type}", value) unless value.is_a?(expected_type)
+        raise Quonfig::Errors::TypeMismatchError.new(key, expected_type.to_s, value) unless value.is_a?(expected_type)
 
         value
       else