quonfig 1.9.0 → 1.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 06b78bb9ba3c5950d54b844388ca57e91c23c7bf4cb595c82c57738e807a1716
-  data.tar.gz: be216cc0d6ea8cee975bc799b94ac2f5a97829dae7fcb4056fded44835deb918
+  metadata.gz: 774d181106fd045eddb916eb177c89744a97f014d7168a4e89d4d51ca2b3d6e2
+  data.tar.gz: c34620585b746c0f013ec473870306593e45fd617b62187ebc31a3d44e14d709
 SHA512:
-  metadata.gz: 3abbf9a8a7afe7883670d60869289fab0e1263d56a309713c89dc3d187fe9e8460905ae6d89f98bf3c1bfc17c45d81238abdc3cb693bf892aace508fff06ea59
-  data.tar.gz: fe1b42b9a3b97d41eabad20fd06610d3a7b237226e32b7af76463f98d5ee7425c0efe6958babbe4d9d0ccaf633d5d8b7c0d587a3245f2a9517534133b4691021
+  metadata.gz: 1e56307ab528445682d284fc48b651dd40224ba007f245e6abc4816bbb0b329e1d8fc0f5d6eff6f73137d375b8abbaf47488f074c803fe1d2944d197c3911910
+  data.tar.gz: 8dcfd007ada4cd44417a1b57928a90bf1e47a33e609b2cc14cb4484460911730f00d9e60cc0ef15fb150de61eab245d8e26e19e0c0f51e9ad0e50132afccbc03

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 1.10.0 - 2026-10-21
+
+- **Fix (patch): the init deadline reason follows sdk-go (qfg-9p4i.17.14, design decision 10).** A new init attempt now starts whenever time remains before `init_timeout_ms`, however little. Before, a retry was skipped with under 250ms left and the boot was decided on the previous attempt, so an attempt that fails fast followed by a delivery that blackholes until the deadline raised `reason: :unavailable` where sdk-go raises `InitializationTimeoutError` (`reason: :timeout`). An attempt still in flight at the deadline decides the reason (`:timeout` only if none of its legs answered); a deadline that lands in the backoff is decided by the last completed attempt (`:timeout` only if every leg timed out). Test: `test/test_init_failure.rb`.
+- **Fix (patch): init-failure conformance (qfg-9p4i.17.4).**
+  - `init_timeout_ms` <= 0 now runs exactly one fetch attempt, lets it finish, then applies `on_init_failure`. Before, the attempt got a 1ms budget, so it was cut off before it could answer and the boot raised `InitializationTimeoutError` even against a healthy delivery.
+  - Config-fetch log lines (including the per-leg lines logged during init) show `scheme://host:port`, never URL userinfo (`user:pass@`), and no longer log the body of a 401/403 response. A non-JSON 200 body no longer reaches the init error's `errors`. The wall-clock fetch timeout message also drops userinfo.
+  - The unauthorized init line and error report the primary leg's status, not whichever leg answered first.
+  - When the init deadline cuts off an attempt, the error summary keeps the errors of legs that already failed (e.g. `primary=...: HTTP 503`) instead of reporting every leg as "no response before initTimeout". Such an attempt counts as hung (`reason` `:timeout`) only if no leg failed fast; otherwise `reason` is `:unavailable`, as in sdk-go.
+  - A connect timeout (`Net::OpenTimeout`, which Faraday wraps in `ConnectionFailed`) counts as a hung leg, so a blackholed delivery host raises `InitializationTimeoutError` (`reason` `:timeout`), as sdk-go does for a dial timeout.
+- **UPGRADE (minor): `on_init_failure` takes `:fail`, `:wait` or `:continue` (qfg-9p4i.10).** `:fail` is the default, as `:raise` was, so a boot that cannot load config still raises. What changes for you:
+  - `Client.new` now **retries** a fast failure (refused connection, DNS, 5xx) with a jittered 0.5s, 1s, 2s ... backoff until `init_timeout_ms` (default 10s) instead of raising on the first failed attempt. A boot during a short blip now succeeds, and a boot with delivery down raises after `init_timeout_ms`, not at once.
+  - When every delivery leg rejects the SDK key (401/403/404/410) the init call does not wait: `:fail` raises at once, `:continue` returns at once.
+  - The raised error is now `Quonfig::Errors::InitializationError` (`reason`: `:unavailable`, `:unauthorized` or `:timeout`; `errors`: the per-leg summary with hosts only). A hang still raises `Quonfig::Errors::InitializationTimeoutError`, now a subclass of it. **If you rescued `RuntimeError` around `Client.new`, rescue `Quonfig::Errors::InitializationError` instead**; it still descends from `StandardError` via `Quonfig::Error`.
+  - New `:wait` keeps blocking and retrying with no upper bound. `:continue` (the new name for `:return`) returns a client over an empty store that keeps retrying in the background.
+  - `:raise` and `:return` (and `ON_INITIALIZATION_FAILURE::RAISE` / `RETURN`) still work as deprecated aliases and log a one-time WARN. `Options#on_init_failure` now reads back the canonical value (`:fail` for `:raise`). An unknown value runs as `:fail` with a WARN.
+- **Added (minor): `Client#wait_for_ready(timeout_ms: nil)`.** Blocks until the client has config; returns `true`, or `false` when the timeout runs out or the client is stopped. `ready?` is unchanged.
+- **Changed (minor): init logging follows the cross-SDK contract.** A first failed attempt logs one WARN (`[quonfig] init: config not loaded yet, retrying until initTimeout (10s). primary=<host>: <error>; secondary=<host>: <error>`), then a WARN every 5s; the timeout logs one ERROR naming the options; a recovery logs `[quonfig] init recovered: ...` at WARN. A `:continue` client that is still not connected logs a WARN every 30s for 5 minutes, then every 5 minutes. The old `Initialization did not complete cleanly` line is gone. Hosts are logged, never the SDK key.
+- **Fix (patch): a boot against refused legs no longer sometimes raises a timeout (qfg-9p4i.10).** When the init backoff ended a few ms before `init_timeout_ms`, the SDK started one more attempt with that few-ms budget; its Timeout guard fired mid-connect and the boot raised `InitializationTimeoutError` (`reason: :timeout`) instead of `InitializationError` with `reason: :unavailable` (about 1 boot in 40 with a 500ms timeout). A retry now starts only with at least 250ms left; otherwise the SDK waits out the deadline and decides on the last attempt's outcome. Test: `test/test_init_failure.rb`.
+- **Added (minor): the `*_details` getters report `PROVIDER_NOT_READY` before config loads (qfg-9p4i.10, design B.3).** On a client with no config yet (`on_init_failure: :continue` before the background retry heals, or a caught init failure) `get_*_details` now return `reason: "ERROR"`, `error_code: "PROVIDER_NOT_READY"` (`Quonfig::EvaluationDetails::ERROR_PROVIDER_NOT_READY`) instead of `FLAG_NOT_FOUND`. `get(key, default)` still returns the default.
+- **Changed (minor): init log lines (section C).** The progress WARN now fires every 5s through a long backoff, and the `:wait` timeout WARN fires at `init_timeout_ms` rather than after the attempt that straddles it. The auth line names the legs (`by primary and secondary`), and a heal through the stream names its leg (`via primary`) instead of `via stream`. With SemanticLogger, each init line carries the payload `event: "quonfig.init.<name>"` (`start`, `retrying`, `waiting`, `wait`, `failed`, `continue`, `unauthorized`, `not_connected`, `recovered`, `deprecated_alias`).
+- **Fix (patch): a subclass of `Quonfig::Client` registers with the fork hook.** `register_instance` used the subclass's own (unset) registry and raised `NoMethodError` in `Client.new`.
+- **Tests: unit and release tests now run integration-test-data `v2026.10.20`.** It adds the init-failure cases (fail by default, fail on refused/hung/401 legs, continue, and the `:raise`/`:return` aliases) and drops the Prefab-era keys. The chaos workflows stay on `v2026.10.16.2`.
+
 ## 1.9.0 - 2026-10-20
 
 - **UPGRADE: SSE reports `connected` at the first frame, not at the 200 response (qfg-goi1.10.9).** A stream connection now counts as connected, for `connection_state`, the reconnect backoff and the fallback poller, only after it delivers its first valid frame: a config envelope or a keepalive. Before, it counted as soon as the 200 response headers arrived.

data/README.md

@@ -259,6 +259,45 @@ for the cross-SDK story (sdk-node, sdk-go, sdk-ruby, sdk-python, sdk-java).
 | `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. |
 
+## Startup failure (`on_init_failure`)
+
+`Client.new` fetches config from both delivery legs (primary, then the
+secondary in parallel) and retries through blips with a jittered backoff
+(0.5s, 1s, 2s ... capped at 30s) for up to `init_timeout_ms` (default 10s).
+A healthy boot logs nothing above DEBUG. If no config has loaded by then,
+`on_init_failure` decides:
+
+| Value | At `init_timeout_ms` | Every leg rejects the SDK key (401/403/404/410) |
+|---|---|---|
+| `:fail` (default) | Raises `Quonfig::Errors::InitializationError` (`reason` `:unavailable`), or its subclass `InitializationTimeoutError` (`reason` `:timeout`) when an attempt was still in flight. No client is returned, so your orchestrator's restart is the retry. | Raises at once (`reason` `:unauthorized`). |
+| `:wait` | Keeps blocking and retrying, with no upper bound, logging a WARN every 30s. | Logs an ERROR and keeps retrying. |
+| `:continue` | Returns a client with no config: getters return your default (and `get_or_raise` raises `MissingDefaultError`). It keeps retrying in the background and serves live config as soon as it lands. | Returns at once. |
+
+```ruby
+begin
+  client = Quonfig::Client.new(sdk_key: key, on_init_failure: :fail, init_timeout_ms: 10_000)
+rescue Quonfig::Errors::InitializationError => e
+  e.reason # => :unavailable, :unauthorized or :timeout
+  e.errors # => "primary=primary.quonfig.com:443: ...; secondary=secondary.quonfig.com:443: ..."
+  raise
+end
+```
+
+`init_timeout_ms` <= 0 runs exactly one fetch attempt and lets it finish (it
+is bounded by the per-leg fetch timeouts), then applies `on_init_failure` as
+in the table: `:fail` raises, `:continue` starts on code defaults and keeps
+retrying, `:wait` keeps retrying. It never means "no deadline".
+
+Init log lines and `InitializationError#message` / `#errors` name delivery
+hosts (`host:port`) and HTTP statuses only, never URL credentials
+(`user:pass@`) or upstream response bodies.
+
+Readiness: `client.ready?` is true once config has loaded, and
+`client.wait_for_ready(timeout_ms: nil)` blocks until it has (true) or the
+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.
+
 ## Constructor options
 
 ```ruby
@@ -270,6 +309,7 @@ Quonfig::Client.new(
   fallback_poll_enabled:     true,
   fallback_poll_interval_ms: 60_000,
   init_timeout_ms:           10_000,
+  on_init_failure:           :fail,
   on_no_default:             :raise,
   global_context:            {},
   datadir:                   '/path/to/workspace',
@@ -287,7 +327,8 @@ Quonfig::Client.new(
 | `enable_sse`              | `Boolean`                  | `true`                                                              | Receive real-time updates over Server-Sent Events.                                                |
 | `fallback_poll_enabled`   | `Boolean`                  | `true`                                                              | Engage HTTP polling as a fallback when SSE is unavailable for >= 2x `fallback_poll_interval_ms`. Deprecated alias: `enable_polling`. |
 | `fallback_poll_interval_ms` | `Integer` (ms)           | `60_000`                                                            | Interval between fallback HTTP polls, in milliseconds. Deprecated alias: `poll_interval` (seconds, multiplied by 1000 internally). |
-| `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). |
+| `init_timeout_ms` | `Integer` (ms)             | `10_000`                                                            | Maximum time to wait for the initial config load, in milliseconds. `<= 0` runs exactly one attempt, then applies `on_init_failure`. Deprecated alias: `initialization_timeout_sec` (seconds, multiplied by 1000 internally). |
+| `on_init_failure` | `Symbol`                   | `:fail`                                                             | What `Client.new` does when no config has loaded by `init_timeout_ms`: `:fail`, `:wait` or `:continue`. See [Startup failure](#startup-failure-on_init_failure). Deprecated aliases: `:raise` (= `:fail`), `:return` (= `:continue`). |
 | `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). |
@@ -500,7 +541,7 @@ Caveats:
   in-process SSE state is moot.
 - The first lookup in a forked child **blocks** on that child's own config
   fetch, under the same `init_timeout_ms` and `on_init_failure` options a
-  fresh client uses. **The default is `on_init_failure: :raise`**, so if the
+  fresh client uses. **The default is `on_init_failure: :fail`**, so if the
   child's fetch fails against every `api_urls` leg (primary and secondary
   both unreachable) the failure **raises out of that first lookup**, exactly
   as `Client.new` would at boot, and later lookups keep raising — without
@@ -508,7 +549,7 @@ Caveats:
   the client serves config normally again. On 1.3.0 and earlier a child in
   that situation silently served the parent's snapshot instead. If you would
   rather a forked child serve defaults through an outage, set
-  `on_init_failure: :return`: a failed fetch then logs one line and the child
+  `on_init_failure: :continue`: a failed fetch then logs one line and the child
   serves defaults until its stream or poller lands the first envelope.
 - **Other threads wait.** Every thread that reaches the client while that
   first fetch is in flight blocks on it and then sees the fetched config. One

data/lib/quonfig/client.rb

@@ -21,6 +21,12 @@ module Quonfig
   class Client
     LOG = Quonfig::InternalLogger.new(self)
 
+    # Init fetch loop cadence (qfg-9p4i.10; init-failure design B.3, C).
+    INIT_PROGRESS_EVERY_S = 5
+    INIT_WAIT_PROGRESS_EVERY_S = 30
+    INIT_BACKOFF_CAP_S = 30.0
+    private_constant :INIT_PROGRESS_EVERY_S, :INIT_WAIT_PROGRESS_EVERY_S, :INIT_BACKOFF_CAP_S
+
     # Auth-failed probe period bounds, rule R3 (qfg-goi1.10.26).
     AUTH_PROBE_MIN_SECONDS = 150.0
     AUTH_PROBE_MAX_SECONDS = 300.0
@@ -62,6 +68,7 @@ module Quonfig
           Quonfig::Options.new(option_kwargs)
         end
       Quonfig::InternalLogger.user_logger = @options.logger if @options.logger
+      warn_on_init_failure_spelling(@options)
       @global_context = build_initial_global_context(@options)
       @instance_hash = SecureRandom.uuid
       @store = store || Quonfig::ConfigStore.new
@@ -129,7 +136,8 @@ module Quonfig
 
       # Register only for non-store-injected clients (a caller-supplied store
       # is the test/bootstrap path; the fork hook does not apply there).
-      self.class.register_instance(self) unless store
+      # Always the base class registry: a subclass has no @instances of its own.
+      Quonfig::Client.register_instance(self) unless store
     end
 
     # ---- Lookup --------------------------------------------------------
@@ -621,6 +629,33 @@ module Quonfig
       !last_successful_refresh.nil?
     end
 
+    # Block until the client has config (see #ready?), up to +timeout_ms+ (nil
+    # = no bound). Returns true once ready, false if the timeout ran out or the
+    # client was stopped first (qfg-9p4i.10; init-failure design B.4). Never
+    # raises for an outage: under on_init_failure: :continue this is how a
+    # caller waits for the background retry to heal.
+    #
+    # In a forked child that has not used the client yet, this runs the
+    # child's re-initialization (as any first use does) and keeps waiting if
+    # that fails.
+    def wait_for_ready(timeout_ms: nil)
+      deadline = timeout_ms && (monotonic_now + (timeout_ms / 1000.0))
+      begin
+        ensure_initialized_after_fork
+      rescue Quonfig::Errors::InitializationError
+        nil
+      end
+      loop do
+        return true if ready?
+        return false if @stopped
+        return false if deadline && monotonic_now >= deadline
+
+        sleep WAIT_FOR_READY_POLL_S
+      end
+    end
+
+    WAIT_FOR_READY_POLL_S = 0.05
+
     # Meta.generation of the currently-held envelope (0 before the first install
     # or when the backend does not emit a generation). Canonical ordering: an
     # established client never regresses to a lower generation.
@@ -794,6 +829,10 @@ module Quonfig
 
       cancel_fallback_engage_timer
 
+      # Sleep-only thread with no I/O and nothing to drain: killing it is safe.
+      @not_ready_reporter&.kill
+      @not_ready_reporter = nil
+
       begin
         @poll_supervisor&.stop
       rescue StandardError => e
@@ -829,6 +868,8 @@ module Quonfig
       @telemetry_reporter = nil
       @datadir_watcher = nil
       @fallback_engage_timer = nil
+      @not_ready_reporter = nil
+      @init_heal_pending = false
 
       # Dropping our reference is not enough for the reporter: its
       # `Kernel.at_exit { final_drain_on_exit }` closure is process-wide, it
@@ -939,9 +980,9 @@ module Quonfig
         end
       end
 
-      return unless @options.on_init_failure == Quonfig::Options::ON_INITIALIZATION_FAILURE::RAISE
+      return unless @options.on_init_failure == Quonfig::Options::ON_INITIALIZATION_FAILURE::FAIL
 
-      # Parity with a fresh Client.new, which raises under :raise. Stored so
+      # Parity with a fresh Client.new, which raises under :fail. Stored so
       # later calls keep raising rather than re-running the fetch on every
       # lookup.
       @fork_rebuild_error = err
@@ -1049,7 +1090,18 @@ module Quonfig
     # path that hands an envelope to the cache: datadir load, initial HTTP
     # fetch, SSE event apply, and polling worker fetch.
     def record_refresh!
-      @state_mutex.synchronize { @last_successful_refresh = Time.now.utc }
+      healed_from = @state_mutex.synchronize do
+        @last_successful_refresh = Time.now.utc
+        next nil unless @init_heal_pending
+
+        # First install after an init that continued without config. Cleared
+        # under the lock so racing installers log the heal exactly once.
+        @init_heal_pending = false
+        @init_started_at || monotonic_now
+      end
+      # The section C heal line, at WARN so the filter level that saw the
+      # failure also sees the recovery. Logged outside the lock.
+      log_init_recovered(healed_from) if healed_from
     end
 
     def sse_restart_total
@@ -1338,6 +1390,7 @@ module Quonfig
       warn_if_hedge_abort_exceeds_init_timeout
       warn_if_explicit_api_urls_disables_failover
 
+      @network_mode = true
       # ||=: after a fork the child already built its loader over its fresh
       # store (see #reset_store_in_child!).
       @config_loader ||= Quonfig::ConfigLoader.new(@store, @options, failover_aggregator: @failover_aggregator)
@@ -1367,29 +1420,285 @@ module Quonfig
       start_polling if @options.enable_polling && !sse_started
     end
 
+    # The init call's fetch loop (qfg-9p4i.10; init-failure design B.3 and the
+    # section C log contract). Attempts the hedged primary+secondary fetch, and
+    # between failed attempts sleeps a jittered 0.5s, 1s, 2s ... (30s cap) until
+    # one installs. At init_timeout_ms, on_init_failure decides:
+    #
+    # - :fail     raise InitializationError (reason :unavailable), or
+    #             InitializationTimeoutError when an attempt was still in flight
+    # - :wait     keep going with no upper bound
+    # - :continue return over the empty store; the update channel started by
+    #             the caller keeps retrying and heals it
+    #
+    # Every leg answering an auth-class status (401/403/404/410) short-circuits
+    # :fail and :continue at once; :wait logs it and keeps retrying (the key
+    # may be provisioned late).
+    #
+    # init_timeout_ms <= 0 runs exactly one attempt, lets it finish (bounded by
+    # the per-leg fetch timeouts, not the init deadline), then applies
+    # on_init_failure. :wait keeps retrying after it (decision 8, qfg-9p4i.17).
     def perform_initial_fetch
-      timeout = (@options.init_timeout_ms || 10_000) / 1000.0
-      result = :failed
+      mode = @options.on_init_failure
+      timeout_ms = @options.init_timeout_ms || Quonfig::Options::DEFAULT_INIT_TIMEOUT_MS
+      timeout_ms = 0 if timeout_ms.negative?
+      one_shot = timeout_ms.zero?
+      timeout_s = timeout_ms / 1000.0
+      start = monotonic_now
+      @init_started_at = start
+      deadline = start + timeout_s
+      urls = Array(@options.config_api_urls)
+      LOG.debug "[quonfig] init: fetching config (initTimeout=#{format_secs(timeout_s)}, onInitFailure=#{mode})",
+                event: 'quonfig.init.start'
+
+      waiting = mode == Quonfig::Options::ON_INITIALIZATION_FAILURE::WAIT
+      attempt = 0
+      errs = ''
+      next_progress = start + init_progress_every_s
+      timed_out_logged = false
+
+      # The section C progress lines, on their own cadence: called after every
+      # attempt and at each wake-up inside the backoff sleep.
+      report = lambda do |now|
+        if waiting && !timed_out_logged && now >= deadline
+          timed_out_logged = true
+          next_progress = now + INIT_WAIT_PROGRESS_EVERY_S
+          LOG.warn "[quonfig] init: no config after #{format('%.1f', now - start)}s. onInitFailure=wait: still " \
+                   "blocking startup and retrying indefinitely. #{errs}. Use onInitFailure=fail or continue to bound startup.",
+                   event: 'quonfig.init.wait'
+        end
+        next unless now >= next_progress
+        next unless now < deadline || waiting
 
-      begin
-        Timeout.timeout(timeout) do
-          result = @config_loader.fetch!
+        if now < deadline
+          LOG.warn "[quonfig] init: still waiting for config (#{format('%.1f', now - start)}s elapsed of " \
+                   "#{format_secs(timeout_s)}, attempt #{attempt}). #{errs}", event: 'quonfig.init.waiting'
+          next_progress += init_progress_every_s while next_progress <= now
+        else
+          LOG.warn "[quonfig] init: still blocked waiting for config (#{(now - start).round}s elapsed, " \
+                   "attempt #{attempt}). #{errs}", event: 'quonfig.init.waiting'
+          next_progress += INIT_WAIT_PROGRESS_EVERY_S while next_progress <= now
         end
-      rescue Timeout::Error
-        handle_init_failure(
-          Quonfig::Errors::InitializationTimeoutError.new(timeout, nil)
-        )
-        return
       end
 
-      if result == :failed
-        handle_init_failure(RuntimeError.new('Config fetch failed against all api_urls'))
-      else
-        sync_evaluator_env_id!
-        record_refresh!
+      loop do
+        return if @stopped
+
+        attempt += 1
+        cycle = nil
+        cycle_log = @config_loader.new_cycle_log
+        leg_errors = Concurrent::Map.new
+        begin
+          if waiting || one_shot
+            cycle = @config_loader.fetch_cycle!(cycle_log: cycle_log, leg_errors: leg_errors)
+          else
+            # Never 0: Timeout.timeout(0) means "no timeout".
+            budget = [deadline - monotonic_now, 0.001].max
+            Timeout.timeout(budget) { cycle = @config_loader.fetch_cycle!(cycle_log: cycle_log, leg_errors: leg_errors) }
+          end
+        rescue Timeout::Error
+          # An attempt was still in flight at init_timeout_ms. Its legs run on
+          # until the hedge abort; their late lines go to DEBUG. Keep the leg
+          # errors already known: a leg that failed fast means the attempt did
+          # not hang, so the reason is :unavailable (decision 7).
+          cycle_log.silence!
+          errs = format_leg_errors(urls, leg_errors, in_flight: true)
+          return init_timed_out(mode, timeout_s, errs, hung: attempt_hung?(urls, leg_errors))
+        end
+
+        if cycle.result != :failed
+          log_init_recovered(start, attempt) if attempt > 1
+          sync_evaluator_env_id!
+          record_refresh!
+          return
+        end
+
+        errs = format_leg_errors(urls, cycle.leg_errors)
+        last_hung = attempt_hung?(urls, cycle.leg_errors)
+        now = monotonic_now
+        if cycle.all_legs_unauthorized?(urls.length)
+          # Every leg is auth-class here (decision 6); report the primary's.
+          status = cycle.primary_status
+          legs = leg_names_phrase(urls.length)
+          if waiting
+            LOG.error "[quonfig] init: SDK key rejected (#{status}) by #{legs}. Check the key and " \
+                      "environment. onInitFailure=wait: still retrying. #{errs}", event: 'quonfig.init.unauthorized'
+          else
+            msg = "[quonfig] init FAILED: SDK key rejected (#{status}) by #{legs}. Check the key " \
+                  "and environment. onInitFailure=#{mode}: " \
+                  "#{mode == Quonfig::Options::ON_INITIALIZATION_FAILURE::FAIL ? 'raising now' : 'starting on code defaults now'}."
+            LOG.error msg, event: 'quonfig.init.unauthorized'
+            return init_continue_on_defaults(errs) if mode == Quonfig::Options::ON_INITIALIZATION_FAILURE::CONTINUE
+
+            raise Quonfig::Errors::InitializationError.new(
+              "Quonfig init failed: SDK key rejected (#{status}) by #{legs}. #{errs}",
+              reason: :unauthorized, errors: errs
+            )
+          end
+        elsif attempt == 1 && !one_shot
+          LOG.warn "[quonfig] init: config not loaded yet, retrying until initTimeout (#{format_secs(timeout_s)}). #{errs}",
+                   event: 'quonfig.init.retrying'
+        end
+
+        if !waiting && now >= deadline
+          # A one-shot attempt reports how long it actually took.
+          elapsed_s = one_shot ? now - start : timeout_s
+          return init_timed_out(mode, elapsed_s, errs, hung: last_hung)
+        end
+
+        report.call(now)
+
+        # Decision 10 (sdk-go's rule): a new attempt starts whenever time
+        # remains before the deadline, however little. If the deadline cuts it
+        # off, it is the last attempt and decides the reason (the rescue
+        # above); if the deadline lands in this backoff, this attempt decides.
+        wake = now + init_backoff_s(attempt)
+        wake = deadline if !waiting && wake > deadline
+        wake_points = -> { [next_progress, (deadline if waiting && !timed_out_logged)].compact }
+        init_sleep_until(wake, wake_points) { |t| report.call(t) }
+        return init_timed_out(mode, timeout_s, errs, hung: last_hung) if !waiting && monotonic_now >= deadline
+      end
+    end
+
+    # Sleep until +wake+, waking early at each of +wake_points+ (re-read every
+    # time) to yield the current time, so progress lines keep their cadence
+    # through a long backoff. Returns early once the client is stopped.
+    def init_sleep_until(wake, wake_points)
+      loop do
+        return if @stopped
+
+        now = monotonic_now
+        return if now >= wake
+
+        nxt = (wake_points.call.select { |t| t > now } << wake).min
+        sleep(nxt - now)
+        yield monotonic_now
       end
     end
 
+    # Seconds between "still waiting for config" lines before the timeout.
+    def init_progress_every_s
+      INIT_PROGRESS_EVERY_S
+    end
+
+    # "primary", "primary and secondary", "primary, secondary and url2".
+    def leg_names_phrase(count)
+      names = Array.new([count, 1].max) { |i| leg_label(i) }
+      names.length == 1 ? names.first : "#{names[0..-2].join(', ')} and #{names.last}"
+    end
+
+    def leg_label(index)
+      case index
+      when 0 then 'primary'
+      when 1 then 'secondary'
+      else "url#{index}"
+      end
+    end
+
+    # 0.5s, 1s, 2s, 4s ... capped at 30s, jittered +/-20%.
+    def init_backoff_s(attempt)
+      base = [0.5 * (2**(attempt - 1)), INIT_BACKOFF_CAP_S].min
+      base * (0.8 + (rand * 0.4))
+    end
+
+    def init_timed_out(mode, timeout_s, errs, hung:)
+      elapsed = format('%.1f', timeout_s)
+      if mode == Quonfig::Options::ON_INITIALIZATION_FAILURE::CONTINUE
+        LOG.error "[quonfig] init: no config after #{elapsed}s. onInitFailure=continue: STARTING ON CODE DEFAULTS. " \
+                  'This instance may disagree with the rest of your fleet. Retrying in background.',
+                  event: 'quonfig.init.continue'
+        return init_continue_on_defaults(errs)
+      end
+
+      LOG.error "[quonfig] init FAILED: no config after #{elapsed}s. #{errs}. onInitFailure=fail: raising " \
+                'Quonfig::Errors::InitializationError. Options: on_init_failure: :wait to keep waiting, ' \
+                'on_init_failure: :continue to start on code defaults, or raise init_timeout_ms.',
+                event: 'quonfig.init.failed'
+      message = "Quonfig init failed: no config after #{elapsed}s. #{errs}"
+      raise Quonfig::Errors::InitializationTimeoutError.new(timeout_s, nil, message: message, errors: errs) if hung
+
+      raise Quonfig::Errors::InitializationError.new(message, reason: :unavailable, errors: errs)
+    end
+
+    # :continue over an empty store. The update channel the caller starts next
+    # keeps retrying; #record_refresh! logs the heal, and the not-ready reporter
+    # logs the outage on the section C cadence until then.
+    def init_continue_on_defaults(errs)
+      @state_mutex.synchronize do
+        @init_heal_pending = true
+        @init_last_errs = errs
+      end
+      start_not_ready_reporter
+      nil
+    end
+
+    # WARN every 30s for 5 minutes, then every 5 minutes, while a :continue
+    # client has no config (section C, "Background retry while not ready").
+    def start_not_ready_reporter
+      return if @not_ready_reporter&.alive?
+
+      @not_ready_reporter = Thread.new do
+        Thread.current.name = 'quonfig-not-ready-reporter' if Thread.current.respond_to?(:name=)
+        loop do
+          elapsed = monotonic_now - @init_started_at
+          sleep(elapsed < 300 ? 30 : 300)
+          break if @stopped || ready?
+
+          since = (monotonic_now - @init_started_at).round
+          errs = @state_mutex.synchronize { @init_last_errs }
+          LOG.warn "[quonfig] still not connected to Quonfig delivery (#{since / 60}m#{since % 60}s since start); " \
+                   "serving defaults. #{errs}", event: 'quonfig.init.not_connected'
+        end
+      rescue StandardError
+        nil
+      end
+    end
+
+    def log_init_recovered(start, _attempt = nil)
+      via = @config_loader.respond_to?(:resolved_from) ? @config_loader.resolved_from : ''
+      # A stream install leaves resolved_from empty: name the SSE leg.
+      via = sse_failed_over_to_secondary? ? leg_label(1) : leg_label(0) if via.to_s.empty?
+      version = @config_loader.respond_to?(:version) ? @config_loader.version : nil
+      LOG.warn "[quonfig] init recovered: config loaded after #{format('%.1f', monotonic_now - start)}s via #{via}" \
+               "#{" (version #{version})" if version}. Now serving live config.", event: 'quonfig.init.recovered'
+    end
+
+    # Whether an attempt hung (decision 7): no leg failed fast. Every leg that
+    # settled ended on a timeout, and a leg with no error yet was still in
+    # flight when the init deadline cut the attempt off.
+    def attempt_hung?(urls, leg_errors)
+      urls.each_index.all? do |i|
+        err = leg_errors[i]
+        err.nil? || err == Quonfig::ConfigLoader::LEG_TIMED_OUT
+      end
+    end
+
+    # primary=<host>: <error>; secondary=<host>: <error>. Hosts only, never the
+    # SDK key or URL credentials.
+    def format_leg_errors(urls, leg_errors, in_flight: false)
+      urls.each_with_index.map do |url, i|
+        label = leg_label(i)
+        err = leg_errors[i] || (in_flight ? 'no response before initTimeout' : 'no response')
+        "#{label}=#{safe_host(url)}: #{err}"
+      end.join('; ')
+    end
+
+    def safe_host(url)
+      uri = URI.parse(url.to_s)
+      uri.host ? "#{uri.host}:#{uri.port}" : '?'
+    rescue URI::InvalidURIError
+      '?'
+    end
+
+    # "10s" for whole seconds, "0.5s" otherwise.
+    def format_secs(secs)
+      secs == secs.to_i ? "#{secs.to_i}s" : "#{secs}s"
+    end
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
     # qfg-pinh: In SDK-key DELIVERY mode the server's `meta.environment` is
     # AUTHORITATIVE. The server scopes each config to a single environment and
     # reports the active env id in `meta.environment` (the loader captures it
@@ -1431,6 +1740,26 @@ module Quonfig
       )
     end
 
+    DEPRECATED_INIT_FAILURE_WARNED = Set.new
+    DEPRECATED_INIT_FAILURE_MUTEX = Mutex.new
+    private_constant :DEPRECATED_INIT_FAILURE_WARNED, :DEPRECATED_INIT_FAILURE_MUTEX
+
+    # One WARN per process per deprecated spelling (section C), and a WARN for
+    # an unrecognized value, which runs as :fail.
+    def warn_on_init_failure_spelling(options)
+      if (bad = options.on_init_failure_unknown)
+        LOG.warn "[quonfig] unknown on_init_failure #{bad.inspect}; using :fail (expected :fail, :wait or :continue)"
+      end
+      old = options.on_init_failure_alias
+      return if old.nil?
+
+      first = DEPRECATED_INIT_FAILURE_MUTEX.synchronize { DEPRECATED_INIT_FAILURE_WARNED.add?(old) }
+      return unless first
+
+      LOG.warn "[quonfig] on_init_failure=:#{old} is deprecated; use :#{options.on_init_failure}",
+               event: 'quonfig.init.deprecated_alias'
+    end
+
     # qfg-7h5d.1.14: the per-leg hedge abort MUST be < init_timeout_ms, otherwise
     # the init-path heal leg is clipped by the overall init deadline before it can
     # heal forward. Mirrors sdk-go's construction-time warning in options.go. Warn
@@ -1445,6 +1774,8 @@ module Quonfig
       abort_ms = @options.config_fetch_hedge_abort_ms
       init_ms = @options.init_timeout_ms
       return if abort_ms.nil? || init_ms.nil?
+      # <= 0 runs one attempt to completion; no init deadline clips its legs.
+      return if init_ms <= 0
       return if init_ms > abort_ms
 
       LOG.warn(
@@ -1476,15 +1807,6 @@ module Quonfig
       )
     end
 
-    def handle_init_failure(err)
-      if @options.on_init_failure == Quonfig::Options::ON_INITIALIZATION_FAILURE::RETURN
-        LOG.warn "[quonfig] Initialization did not complete cleanly; continuing with empty store: #{err.message}"
-        return
-      end
-
-      raise err
-    end
-
     # Returns true if SSE started successfully, false otherwise. A false here
     # signals the caller to fall back to polling.
     def start_sse
@@ -1762,6 +2084,25 @@ module Quonfig
       nil
     end
 
+    # A delivery-mode client that has never installed config (init continued
+    # on code defaults, or the caller caught a failed init): the *_details
+    # getters answer ERROR / PROVIDER_NOT_READY (init-failure design B.3)
+    # rather than claiming the key does not exist.
+    def provider_not_ready?
+      @network_mode && !ready?
+    end
+
+    def provider_not_ready_details
+      Quonfig::EvaluationDetails.new(
+        value: nil,
+        reason: Quonfig::EvaluationDetails::REASON_ERROR,
+        error_code: Quonfig::EvaluationDetails::ERROR_PROVIDER_NOT_READY,
+        error_message: 'Quonfig has not loaded config yet',
+        variant: build_variant(Quonfig::EvaluationDetails::REASON_ERROR, nil, nil),
+        flag_metadata: build_flag_metadata(nil, nil, nil, nil, nil)
+      )
+    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.
@@ -1770,6 +2111,7 @@ module Quonfig
       jit = context == NO_DEFAULT_PROVIDED ? nil : context
       ctx = build_context(jit)
       record_context_for_telemetry(ctx)
+      return provider_not_ready_details if provider_not_ready?
 
       result =
         begin

data/lib/quonfig/config_loader.rb

@@ -24,17 +24,54 @@ module Quonfig
     # poller then enters auth-failed (Client#start_polling).
     AUTH_STATUSES = [401, 403, 404, 410].freeze
 
+    # The leg error recorded when a leg ended on a timeout (its per-leg
+    # deadline or the hedge abort). The init loop reads it to tell a hung
+    # attempt from one that failed fast (init-failure design, decision 7).
+    LEG_TIMED_OUT = 'timed out'
+
+    # host:port of +url+ (scheme kept when present), never its userinfo, path
+    # or query. For log lines and leg errors (init-failure design, decision 9).
+    def self.display_url(url)
+      return url.to_s unless url.is_a?(String) || url.is_a?(URI::Generic)
+
+      uri = URI.parse(url.to_s)
+      return redact_userinfo(url.to_s) unless uri.host
+
+      "#{"#{uri.scheme}://" if uri.scheme}#{uri.host}:#{uri.port}"
+    rescue URI::InvalidURIError
+      redact_userinfo(url.to_s)
+    end
+
+    # Strip "user:pass@" from every URL in +text+.
+    def self.redact_userinfo(text)
+      text.to_s.gsub(%r{(//)[^/@\s]+@}, '\\1')
+    end
+
     # 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
+      attr_reader :result, :statuses, :primary_host, :leg_errors
 
-      def initialize(result, statuses, primary_host)
+      # +leg_errors+ maps a config_api_urls index to a one-line description of
+      # why that leg failed (host-free, key-free), for the init log contract.
+      def initialize(result, statuses, primary_host, leg_errors = {})
         @result = result
         @statuses = statuses
         @primary_host = primary_host
+        @leg_errors = leg_errors
+      end
+
+      # Every leg answered and every answer was in the auth class (401/403,
+      # plus 404/410 per rule R1): the key is rejected (init-failure design
+      # B.3, "401/403 from both legs"). Stricter than #auth_rejected? (the
+      # poller's rule R2, primary leg only), because init short-circuits on it.
+      def all_legs_unauthorized?(leg_count)
+        return false unless @result == :failed
+
+        values = @statuses.values
+        values.size >= leg_count && values.all? { |s| AUTH_STATUSES.include?(s) }
       end
 
       def primary_status
@@ -66,8 +103,16 @@ module Quonfig
         @mutex = Mutex.new
       end
 
+      # Send this cycle's remaining lines to DEBUG. The init loop calls it when
+      # it gives up on an attempt that is still in flight: its legs keep running
+      # on their own threads up to the hedge abort, and their late failures are
+      # already summarized in the init ERROR (qfg-9p4i.10).
+      def silence!
+        @silenced = true
+      end
+
       def log(level, msg, auth: false)
-        return @logger.debug(msg) if @mode == :probe
+        return @logger.debug(msg) if @mode == :probe || @silenced
 
         if @mode == :poll && auth
           hold = @mutex.synchronize do
@@ -208,27 +253,39 @@ module Quonfig
     # 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)
+    #
+    # +leg_errors+ lets a caller pass in the map the legs record their errors
+    # into, so it can still read them if it abandons the cycle mid-flight (the
+    # init loop at init_timeout_ms).
+    def fetch_cycle!(log_mode: :normal, cycle_log: nil, leg_errors: nil)
       urls = Array(@options.config_api_urls)
       statuses = Concurrent::Map.new
-      return FetchCycle.new(:failed, statuses, '') if urls.empty?
+      leg_errors ||= Concurrent::Map.new
+      return FetchCycle.new(:failed, statuses, '', leg_errors) if urls.empty?
 
-      cycle_log = CycleLog.new(@logger, log_mode)
+      cycle_log ||= new_cycle_log(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.
       result = if urls.length < 2
-                 fetch_from(urls[0], 0, timeout_ms: config_fetch_timeout_ms, statuses: statuses, cycle_log: cycle_log)
+                 fetch_from(urls[0], 0, timeout_ms: config_fetch_timeout_ms, statuses: statuses,
+                                        cycle_log: cycle_log, leg_errors: leg_errors)
                else
-                 fetch_hedged(urls, statuses: statuses, cycle_log: cycle_log)
+                 fetch_hedged(urls, statuses: statuses, cycle_log: cycle_log, leg_errors: leg_errors)
                end
-      cycle = FetchCycle.new(result, statuses, host_of(urls[0]))
+      cycle = FetchCycle.new(result, statuses, host_of(urls[0]), leg_errors)
       cycle_log.release(drop: cycle.auth_rejected?)
       cycle
     end
 
+    # A CycleLog over this loader's logger, for a caller that wants to hold on
+    # to it (see CycleLog#silence!).
+    def new_cycle_log(mode = :normal)
+      CycleLog.new(@logger, mode)
+    end
+
     # Apply a ConfigEnvelope (from SSE) to the store. Called by the SSE client
     # 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
@@ -265,7 +322,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, statuses: nil, cycle_log: nil)
+    def fetch_hedged(urls, statuses: nil, cycle_log: nil, leg_errors: nil)
       hedge_delay_s = hedge_delay_ms / 1000.0
       abort_ms = hedge_abort_ms
 
@@ -293,7 +350,8 @@ module Quonfig
         Thread.new do
           result = :failed
           begin
-            result = fetch_from(urls[index], index, timeout_ms: abort_ms, statuses: statuses, cycle_log: cycle_log)
+            result = fetch_from(urls[index], index, timeout_ms: abort_ms, statuses: statuses, cycle_log: cycle_log,
+                                                    leg_errors: leg_errors)
           rescue StandardError => e
             @logger.debug "Hedge leg #{index} failed: #{e.class}: #{e.message}"
           ensure
@@ -402,8 +460,10 @@ module Quonfig
       ''
     end
 
-    def fetch_from(source, index = nil, timeout_ms: nil, statuses: nil, cycle_log: nil)
+    def fetch_from(source, index = nil, timeout_ms: nil, statuses: nil, cycle_log: nil, leg_errors: nil)
       cycle_log ||= CycleLog.new(@logger, :normal)
+      where = self.class.display_url(source)
+      note = ->(msg) { leg_errors[index || 0] = self.class.redact_userinfo(msg)[0, 200] if leg_errors }
       # 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 /
@@ -432,35 +492,59 @@ module Quonfig
         # an equal/older payload — surface that so the caller doesn't double-count.
         result == :not_modified ? :not_modified : :updated
       when 304
-        @logger.debug "Configs not modified (304) from #{source}"
+        @logger.debug "Configs not modified (304) from #{where}"
         :not_modified
       when 401, 403
-        cycle_log.log(:warn, "Config fetch rejected (#{response.status}) from #{source}: #{short_body(response)}", auth: true)
+        note.call("HTTP #{response.status} (SDK key rejected)")
+        # Never the response body: it is upstream content (decision 9).
+        cycle_log.log(:warn, "Config fetch rejected (#{response.status}) from #{where}", auth: true)
         :failed
       else
-        cycle_log.log(:info, "Config fetch failed: status #{response.status} from #{source}",
+        note.call("HTTP #{response.status}")
+        cycle_log.log(:info, "Config fetch failed: status #{response.status} from #{where}",
                       auth: AUTH_STATUSES.include?(response.status.to_i))
         :failed
       end
     rescue NonEnvelopeError => e
+      note.call("non-envelope 200 (#{e.message})")
       # 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).
-      cycle_log.log(:warn, "Config fetch from #{source} returned a non-envelope 200 (#{e.message}); treating as a failed leg")
+      cycle_log.log(:warn, "Config fetch from #{where} returned a non-envelope 200 (#{e.message}); treating as a failed leg")
       :failed
     rescue Quonfig::ConfigShape::AllInvalidError => e
+      note.call(e.message)
       # qfg-krjt: a payload with no loadable config is a leg error, so it can
       # never install as an empty workspace.
-      cycle_log.log(:warn, "Config fetch from #{source}: #{e.message}; treating as a failed leg")
+      cycle_log.log(:warn, "Config fetch from #{where}: #{e.message}; treating as a failed leg")
+      :failed
+    rescue JSON::ParserError
+      # The parser's message quotes the body; never pass it on (decision 9).
+      note.call('non-JSON 200 body')
+      cycle_log.log(:warn, "Config fetch from #{where} returned a non-JSON 200; treating as a failed leg")
+      :failed
+    rescue Faraday::TimeoutError
+      note.call(LEG_TIMED_OUT)
+      cycle_log.log(:warn, "Timeout error fetching configs from #{where}")
       :failed
     rescue Faraday::ConnectionFailed => e
-      @logger.debug "Connection failure fetching configs from #{source}: #{e.message}"
+      # The Net::HTTP adapter wraps a connect timeout (Net::OpenTimeout) in
+      # ConnectionFailed. That is a hang, not a fast failure (decision 7).
+      note.call(connect_timeout?(e) ? LEG_TIMED_OUT : e.message)
+      @logger.debug "Connection failure fetching configs from #{where}: #{self.class.redact_userinfo(e.message)}"
       :failed
     rescue StandardError => e
-      cycle_log.log(:warn, "Unexpected error fetching configs from #{source}: #{e.message}")
+      note.call("#{e.class}: #{e.message}")
+      cycle_log.log(:warn, "Unexpected error fetching configs from #{where}: #{self.class.redact_userinfo(e.message)}")
       :failed
     end
 
+    def connect_timeout?(err)
+      cause = err.respond_to?(:wrapped_exception) ? err.wrapped_exception : nil
+      cause ||= err.cause
+      cause.is_a?(Timeout::Error) || cause.is_a?(Errno::ETIMEDOUT)
+    end
+
     def etag_for(index)
       @etag_mutex.synchronize { @etags[index || 0] }
     end
@@ -484,13 +568,6 @@ module Quonfig
       Quonfig::ConfigEnvelope.new(configs: configs, meta: meta)
     end
 
-    def short_body(response)
-      return '' if response.body.nil?
-
-      str = response.body.to_s
-      str.length > 200 ? "#{str[0, 200]}..." : str
-    end
-
     def install_envelope(envelope, source:, source_index: nil)
       meta = envelope.meta || {}
       incoming_gen = extract_generation(meta)
@@ -523,12 +600,12 @@ module Quonfig
             # Unversioned payload while a real generation is held: not provably
             # older (it carries no ordering info), so a silent no-op — NOT
             # counted as guardRejected.
-            @logger.debug "Unversioned payload ignored: held generation #{@held_generation} (source=#{source})"
+            @logger.debug "Unversioned payload ignored: held generation #{@held_generation} (source=#{self.class.display_url(source)})"
             return :not_modified
           end
 
           if incoming_gen < @held_generation
-            @logger.debug "Reject-older guard: dropping incoming generation #{incoming_gen} < held #{@held_generation} (source=#{source})"
+            @logger.debug "Reject-older guard: dropping incoming generation #{incoming_gen} < held #{@held_generation} (source=#{self.class.display_url(source)})"
             # Failover observability (qfg-41nh.18): count the guard rejection.
             # This single guard covers BOTH the HTTP config-fetch path and the
             # SSE message path (apply_envelope) — every network install funnels
@@ -548,7 +625,7 @@ module Quonfig
             # `guardRejected` made a healthy client report failover activity from
             # init alone. Not installed, not counted — but still :not_modified, so
             # the caller's liveness stamp is unchanged.
-            @logger.debug "Same-generation re-delivery: ignoring incoming generation #{incoming_gen} (source=#{source})"
+            @logger.debug "Same-generation re-delivery: ignoring incoming generation #{incoming_gen} (source=#{self.class.display_url(source)})"
           end
           return :not_modified
         end

data/lib/quonfig/errors/initialization_error.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Quonfig
+  module Errors
+    # Raised by Client.new under on_init_failure: :fail (the default) when no
+    # config could be loaded (qfg-9p4i.10; init-failure design B.4). The base
+    # of the init-failure family: rescue this to catch every init failure.
+    #
+    # +reason+ is one of:
+    # - +:unavailable+ - every attempt failed fast (refused, DNS, 5xx) until
+    #   init_timeout_ms ran out
+    # - +:unauthorized+ - every delivery leg rejected the SDK key (401/403);
+    #   raised at once, without waiting out the timeout
+    # - +:timeout+ - an attempt was still in flight at init_timeout_ms
+    #   (InitializationTimeoutError)
+    #
+    # +errors+ is the per-leg summary (+primary=<host>: <error>; ...+). It names
+    # hosts only, never the SDK key.
+    class InitializationError < Quonfig::Error
+      REASONS = %i[unavailable unauthorized timeout].freeze
+
+      attr_reader :reason, :errors
+
+      def initialize(message = 'Quonfig failed to initialize', reason: :unavailable, errors: nil)
+        @reason = reason
+        @errors = errors
+        super(message)
+      end
+    end
+  end
+end

data/lib/quonfig/errors/initialization_timeout_error.rb

@@ -2,10 +2,15 @@
 
 module Quonfig
   module Errors
-    class InitializationTimeoutError < Quonfig::Error
-      def initialize(timeout_sec, key)
-        message = "Quonfig couldn't initialize in #{timeout_sec} second timeout. Trying to fetch key `#{key}`."
-        super(message)
+    # The init-failure error for a hang: an attempt was still in flight when
+    # init_timeout_ms ran out. A subclass of InitializationError (reason
+    # +:timeout+), so rescuing either class catches it.
+    class InitializationTimeoutError < InitializationError
+      # +timeout_sec+ and +key+ keep the original positional signature.
+      def initialize(timeout_sec, key = nil, message: nil, errors: nil)
+        message ||= "Quonfig couldn't initialize in #{timeout_sec} second timeout."
+        message += " Trying to fetch key `#{key}`." if key
+        super(message, reason: :timeout, errors: errors)
       end
     end
   end

data/lib/quonfig/evaluation_details.rb

@@ -16,6 +16,8 @@ module Quonfig
   # +error_code+ (only when reason == "ERROR") is one of:
   #   "FLAG_NOT_FOUND" — the key was unknown to the store
   #   "TYPE_MISMATCH"  — the resolved value didn't satisfy the requested type
+  #   "PROVIDER_NOT_READY" — the client has no config yet (init continued
+  #                          on code defaults, or a caught init failure)
   #   "GENERAL"        — any other failure
   class EvaluationDetails
     REASON_STATIC          = 'STATIC'
@@ -27,6 +29,7 @@ module Quonfig
     ERROR_FLAG_NOT_FOUND = 'FLAG_NOT_FOUND'
     ERROR_TYPE_MISMATCH  = 'TYPE_MISMATCH'
     ERROR_GENERAL        = 'GENERAL'
+    ERROR_PROVIDER_NOT_READY = 'PROVIDER_NOT_READY'
 
     attr_reader :value, :reason, :error_code, :error_message, :variant, :flag_metadata
 

data/lib/quonfig/http_connection.rb

@@ -90,7 +90,7 @@ module Quonfig
 
       deadline_s = (@timeout_ms / 1000.0) + WALL_CLOCK_HEADROOM_S
       Timeout.timeout(deadline_s, Faraday::TimeoutError,
-                      "wall-clock per-request deadline #{deadline_s}s exceeded for #{@uri}") do
+                      "wall-clock per-request deadline #{deadline_s}s exceeded for #{Quonfig::ConfigLoader.redact_userinfo(@uri)}") do
         block.call
       end
     end

data/lib/quonfig/internal_logger.rb

@@ -34,28 +34,28 @@ module Quonfig
     end
 
     # Log methods
-    def trace(message = nil, &block)
-      log_message(:trace, message, &block)
+    def trace(message = nil, event: nil, &block)
+      log_message(:trace, message, event: event, &block)
     end
 
-    def debug(message = nil, &block)
-      log_message(:debug, message, &block)
+    def debug(message = nil, event: nil, &block)
+      log_message(:debug, message, event: event, &block)
     end
 
-    def info(message = nil, &block)
-      log_message(:info, message, &block)
+    def info(message = nil, event: nil, &block)
+      log_message(:info, message, event: event, &block)
     end
 
-    def warn(message = nil, &block)
-      log_message(:warn, message, &block)
+    def warn(message = nil, event: nil, &block)
+      log_message(:warn, message, event: event, &block)
     end
 
-    def error(message = nil, &block)
-      log_message(:error, message, &block)
+    def error(message = nil, event: nil, &block)
+      log_message(:error, message, event: event, &block)
     end
 
-    def fatal(message = nil, &block)
-      log_message(:fatal, message, &block)
+    def fatal(message = nil, event: nil, &block)
+      log_message(:fatal, message, event: event, &block)
     end
 
     def level
@@ -172,7 +172,10 @@ module Quonfig
       level_str&.downcase&.to_sym
     end
 
-    def log_message(level, message, &block)
+    # +event+ (e.g. 'quonfig.init.failed') is a structured field: SemanticLogger
+    # gets it as the payload ({ event: ... }); plain Logger-shaped sinks only
+    # get the message, which already carries the full line.
+    def log_message(level, message, event: nil, &block)
       override = Quonfig::InternalLogger.user_logger
       if override
         write_to_user_logger(override, level, message, &block)
@@ -180,7 +183,11 @@ module Quonfig
       end
 
       if @using_semantic
-        @logger.send(level, message, &block)
+        if event
+          @logger.send(level, message, { event: event }, &block)
+        else
+          @logger.send(level, message, &block)
+        end
       else
         # stdlib Logger doesn't have trace
         level = :debug if level == :trace

data/lib/quonfig/options.rb

@@ -13,6 +13,11 @@ module Quonfig
                 :telemetry_max_retained_bytes, :telemetry_max_retained_age_ms
     attr_accessor :is_fork
 
+    # The deprecated on_init_failure spelling passed (:raise / :return), or nil.
+    attr_reader :on_init_failure_alias
+    # An unrecognized on_init_failure value (treated as :fail), or nil.
+    attr_reader :on_init_failure_unknown
+
     # Default fallback poll interval, in milliseconds. The SDK polls api-delivery
     # at this cadence only when SSE is unavailable for >= 2x this value.
     DEFAULT_FALLBACK_POLL_INTERVAL_MS = 60_000
@@ -76,9 +81,42 @@ module Quonfig
       ms == ms.to_i ? ms.to_i : ms
     end
 
+    # What Client.new does when no config has loaded by +init_timeout_ms+
+    # (qfg-9p4i.10; project/plans/2026-10-05-init-failure-design.md B.1-B.3):
+    #
+    # - +:fail+ (default): raise Quonfig::Errors::InitializationError. Every
+    #   delivery leg answering 401/403 raises at once, without waiting out the
+    #   timeout.
+    # - +:wait+: keep blocking and retrying with no upper bound.
+    # - +:continue+: return a client over an empty store (getters answer with
+    #   the caller's default) that keeps retrying in the background.
+    #
+    # +:raise+ and +:return+ are the deprecated earlier spellings of +:fail+ and
+    # +:continue+. They are still accepted and log a one-time WARN.
     module ON_INITIALIZATION_FAILURE
+      FAIL = :fail
+      WAIT = :wait
+      CONTINUE = :continue
+      # @deprecated Use FAIL.
       RAISE = :raise
+      # @deprecated Use CONTINUE.
       RETURN = :return
+
+      MODES = [FAIL, WAIT, CONTINUE].freeze
+      ALIASES = { RAISE => FAIL, RETURN => CONTINUE }.freeze
+
+      # [canonical mode, deprecated alias given or nil, unknown value or nil].
+      # Strings are accepted ('fail', ':raise'). An unknown value resolves to
+      # FAIL, the safe default, and is reported so the client can warn.
+      def self.resolve(value)
+        return [FAIL, nil, nil] if value.nil?
+
+        sym = value.to_s.delete_prefix(':').to_sym
+        return [sym, nil, nil] if MODES.include?(sym)
+        return [ALIASES[sym], sym, nil] if ALIASES.key?(sym)
+
+        [FAIL, nil, value]
+      end
     end
 
     module ON_NO_DEFAULT
@@ -217,6 +255,13 @@ module Quonfig
     private
 
     # @!method initialize(options = {})
+    #   @option options [Integer] :init_timeout_ms (10000)
+    #     How long +Client.new+ retries the initial config fetch before
+    #     +:on_init_failure+ decides. A value <= 0 runs exactly one fetch
+    #     attempt, lets it finish (it is bounded by the per-leg fetch timeouts,
+    #     not by this option), then applies +:on_init_failure+: +:fail+ raises,
+    #     +:continue+ starts on code defaults and keeps retrying in the
+    #     background, +:wait+ keeps retrying. It never means "no deadline".
     #   @option options [Boolean] :data_dir_auto_reload (false)
     #     Datadir mode only. When +true+, the SDK watches the workspace
     #     directory and re-reads the envelope whenever files inside it
@@ -271,7 +316,7 @@ module Quonfig
       on_no_default: ON_NO_DEFAULT::RAISE,
       init_timeout_ms: nil,
       initialization_timeout_sec: nil,
-      on_init_failure: ON_INITIALIZATION_FAILURE::RAISE,
+      on_init_failure: ON_INITIALIZATION_FAILURE::FAIL,
       config_fetch_timeout_ms: nil,
       config_fetch_hedge_delay_ms: nil,
       config_fetch_hedge_abort_ms: nil,
@@ -334,7 +379,10 @@ module Quonfig
                          else
                            DEFAULT_INIT_TIMEOUT_MS
                          end
-      @on_init_failure = on_init_failure
+      # Stored canonical (:fail / :wait / :continue); the deprecated spelling
+      # the caller used, if any, is kept for the client's one-time WARN.
+      @on_init_failure, @on_init_failure_alias, @on_init_failure_unknown =
+        ON_INITIALIZATION_FAILURE.resolve(on_init_failure)
       # qfg-7h5d.1.9: per-URL config-fetch timeout. nil → DEFAULT_CONFIG_FETCH_TIMEOUT_MS.
       @config_fetch_timeout_ms = config_fetch_timeout_ms || DEFAULT_CONFIG_FETCH_TIMEOUT_MS
       # qfg-7h5d.1.14: parallel-failover hedge knobs. nil → defaults. The hedge

data/lib/quonfig/version.rb

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

data/lib/quonfig.rb

@@ -32,6 +32,7 @@ require 'quonfig/exponential_backoff'
 require 'quonfig/waits'
 require 'quonfig/worker_supervisor'
 require 'quonfig/periodic_sync'
+require 'quonfig/errors/initialization_error'
 require 'quonfig/errors/initialization_timeout_error'
 require 'quonfig/errors/invalid_sdk_key_error'
 require 'quonfig/errors/missing_default_error'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: quonfig
 version: !ruby/object:Gem::Version
-  version: 1.9.0
+  version: 1.10.0
 platform: ruby
 authors:
 - Jeff Dwyer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-20 00:00:00.000000000 Z
+date: 2026-10-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -101,6 +101,7 @@ files:
 - lib/quonfig/error.rb
 - lib/quonfig/errors/decryption_error.rb
 - lib/quonfig/errors/env_var_parse_error.rb
+- lib/quonfig/errors/initialization_error.rb
 - lib/quonfig/errors/initialization_timeout_error.rb
 - lib/quonfig/errors/invalid_environment_error.rb
 - lib/quonfig/errors/invalid_sdk_key_error.rb