quonfig 1.1.1 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df149576c34f45d691f7252a2f0e05b2c02b95681ab9986fac6a373071210c7e
-  data.tar.gz: ab5dc409a48ed4f471b500d62451a8d1b3b1e7de67871172ce684327ba7a1777
+  metadata.gz: 8408e71b66de6bfe3e771b4091429d31f15f1dbdc0bb74d2e05bc3bcd83415db
+  data.tar.gz: e22b82909ffbb87dec181aa5c526ae12f7d4d7669c498027809ba8209ccd7c97
 SHA512:
-  metadata.gz: dec2b311edf9f515e00803d7f2a60c9f10897807779b26a44f4aa842ef5ac46239a432a194e72378eb23c3e03a79002ff3332e6d72be265683b707adb88134ed
-  data.tar.gz: 55c3a892dfa3af12e4db273e09faf5f0b96c8c2861cdfdb611c9ba75877a6e3a1c696568593b0cdd6283874b072f259738cc14c8d3a871a432cfbc17a194df35
+  metadata.gz: '0149ee240869602465f2ff10180f8f2c35b577bf12d6f73bf33afe02ac16e0742e93744c085cbd641c1640b542a137dbde8650e5dde580174b718d89d4b08ed6'
+  data.tar.gz: b223c20dc4cde206a30e803d43d507c1e4b5f204465c7e5e0c1f19db178842bc3a5013db7d734d09178a23cddca3df4e2b275f4f000b71bb3f2566e6395d337d

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 1.3.0 - 2026-08-18
+
+> **Heads up — datadir users will start emitting telemetry.** Datadir mode with a valid SDK key now emits usage telemetry as documented; it previously sent nothing. If you run the SDK with a `datadir:` (or `QUONFIG_DIR`) **and** an SDK key, upgrading to 1.3.0 means evaluation summaries and context telemetry begin flowing to the telemetry service from that deployment — data you were not sending on 1.2.0. Disable with the standard telemetry options if unwanted (`collect_evaluation_summaries: false` and `context_upload_mode: :none`). A datadir client with **no** SDK key still sends nothing at all.
+
+- **Fix (telemetry): the telemetry gate is SDK-key presence, not delivery mode (qfg-5x9x).** `Options#telemetry_allowed?` consulted `local_only?` (i.e. "is a datadir set?"), which forced every `collect_max_*` to `0` the moment a datadir was configured. With no collector limits the client built no aggregators, took `initialize_telemetry`'s early return, and never constructed a `TelemetryReporter` — so a datadir client holding a perfectly valid SDK key emitted **no** evaluation summaries, **no** context telemetry, nothing at all. Datadir is a config-**delivery** mode: it decides where config comes from, not whether usage is reported. The gate is now the SDK key alone, which is what identifies the workspace telemetry is attributed to. This aligns sdk-ruby with sdk-node, sdk-go, sdk-python, sdk-java, and sdk-net, and is the inverse of the defect fixed for sdk-go / sdk-python in 1.2.1 (those *over*-sent without a key). No wire-format change, no new dependencies, no public API removed.
+- **Fix (telemetry): a keyless client now collects nothing at all.** Without an SDK key there is no workspace to attribute telemetry to, so the aggregators are no longer even allocated and the reporter never starts (previously the collectors filled up in delivery mode and were discarded at flush time). Behavior for the open-source / no-account path is unchanged from the outside — still zero telemetry HTTP — but nothing is accumulated in memory on the way there.
+- **Deprecated: `allow_telemetry_in_local_mode:` is now a no-op.** It existed only to re-enable telemetry that datadir mode had suppressed; with mode out of the decision there is nothing left for it to unlock. The kwarg is still accepted so existing callers keep working, and it can neither enable telemetry without a key nor suppress it with one. Slated for removal in 2.0.0 — use `collect_evaluation_summaries: false` / `context_upload_mode: :none` to opt out.
+- **Docs:** the README's datadir section previously claimed the mode "performs no network I/O" unconditionally. It now states the delivery-side guarantee precisely (no config fetch, no SSE, no polling) and documents the telemetry gate, including how to run datadir + key with telemetry off.
+
+## 1.2.0 - 2026-07-08
+
+- **Feat (options): warn when an explicit `api_urls` disables automatic failover (qfg-41nh.26).** The default (and every `QUONFIG_DOMAIN`-derived) `api_urls` list carries a primary AND a secondary leg, and the HTTP config-fetch hedges/fails over between them (the secondary runs on separate infrastructure). An explicit `api_urls:` replaces that list wholesale, so a single-entry override silently dropped the secondary and disabled automatic failover. The client now logs one WARN at init when the caller explicitly set `api_urls` and the resolved list has fewer than two legs, pointing at the fix (pass both a primary and a secondary URL). Behavior is otherwise unchanged; no new dependencies. A new README "Failover & `QUONFIG_DOMAIN`" section documents the URL derivation and the failover model.
+- **Feat (telemetry): emit failover-behavior signals on the existing telemetry wire (qfg-41nh.18).** The SDK now folds three additive failover counters into the periodic telemetry flush so the failover dashboards can be built — previously no SDK emitted any failover signal. Each flush window that saw failover activity ships one `failover` event alongside the existing `summaries` / `contextShapes` / `exampleContexts` events: `hedgeFired` (config-fetch cycles where the parallel primary+secondary hedge fired its secondary leg), `guardRejected` (installs dropped by the reject-older ordering guard, counted on BOTH the HTTP config-fetch path and the SSE message path), and `resolvedFromPrimary` / `resolvedFromSecondary` (which upstream leg served each successful HTTP install; SSE/datadir installs are not counted). `resolvedFromLkg` is reserved and always `0`. The event is emitted only when at least one counter is non-zero in the window, so a steady-state client with no config churn emits nothing. Recording rides the existing telemetry opt-out (nothing is emitted unless telemetry is enabled) and adds only a per-config-refresh mutex increment — no new dependencies, no per-evaluation overhead. Wire shape is additive and matches sdk-go exactly (an older api-telemetry strips the unknown field).
+
 ## 1.1.1 - 2026-07-03
 
 - **Fix (SSE): the stream leg is pinned to the primary stream URL — SSE never fails over (qfg-41nh.6).** The reconnect loop previously rotated through `sse_api_urls` on every reconnect, so with the default two derived stream URLs a primary blip silently parked the live stream on `stream.secondary` and bound config freshness to the mirror. The stream now always dials `sse_api_urls[0]` and retries it forever with backoff (matching sdk-go); failover remains HTTP-poll only, and the HTTP config-fetch hedge still uses both `api_urls` legs. The `sse_failed_over_to_secondary?` diagnostic is now latched at the dial site, and the failover chaos harness hands the client both stream legs so the f05 probe actually exercises the pin.

data/README.md

@@ -86,7 +86,8 @@ bound.get_int('rate-limit')
 
 For tests, CI, or air-gapped environments, point the client at a local workspace
 directory instead of the Quonfig API. In datadir mode the SDK loads JSON config
-files from disk and performs no network I/O.
+files from disk — config delivery does no network I/O at all: no config fetch,
+no SSE stream, no polling.
 
 ```ruby
 client = Quonfig::Client.new(
@@ -111,6 +112,32 @@ export QUONFIG_ENVIRONMENT=production
 client = Quonfig::Client.new  # reads QUONFIG_DIR + QUONFIG_ENVIRONMENT
 ```
 
+### Telemetry in datadir mode
+
+Usage telemetry is gated on **SDK-key presence, not on mode**. A datadir client
+with an `sdk_key:` configured still reports evaluation summaries and context
+telemetry to the telemetry service, exactly as a delivery-mode client does —
+that combination is what makes flag usage visible in the Quonfig UI for services
+that read config from a checked-out workspace.
+
+A datadir client with **no** SDK key has no workspace to attribute telemetry to,
+so it collects and sends nothing: fully offline, zero network I/O.
+
+To run with a key but without telemetry, use the standard opt-outs:
+
+```ruby
+client = Quonfig::Client.new(
+  datadir:                      '/path/to/workspace',
+  environment:                  'production',
+  sdk_key:                      ENV['QUONFIG_BACKEND_SDK_KEY'],
+  collect_evaluation_summaries: false,
+  context_upload_mode:          :none
+)
+```
+
+> Changed in 1.3.0: before 1.3.0 a datadir sent nothing even with a valid SDK
+> key. See the CHANGELOG.
+
 ## Datadir mode: auto-reload on file changes
 
 In datadir mode the SDK loads the workspace once at construction time and then
@@ -258,6 +285,42 @@ Quonfig::Client.new(
 | `data_dir_auto_reload_debounce_ms`  | `Integer` (ms)    | `200`                                                               | Debounce window for the auto-reload watcher — events arriving inside the window are coalesced into a single re-read. Ignored when `data_dir_auto_reload` is `false`. |
 | `logger`          | Logger-like object         | `nil`                                                               | Optional host-app logger (e.g. `Rails.logger`). Must respond to `debug`/`info`/`warn`/`error`. When set, all SDK warnings/errors flow through this logger instead of the default stderr / SemanticLogger backend. |
 
+## Failover & `QUONFIG_DOMAIN`
+
+By default the SDK derives every hostname from `QUONFIG_DOMAIN` (default
+`quonfig.com`):
+
+| Role                     | URL                                     |
+|--------------------------|-----------------------------------------|
+| Config fetch (primary)   | `https://primary.quonfig.com`           |
+| SSE stream (primary)     | `https://stream.primary.quonfig.com`    |
+| Config fetch (secondary) | `https://secondary.quonfig.com`         |
+| SSE stream (secondary)   | `https://stream.secondary.quonfig.com`  |
+| Telemetry                | `https://telemetry.quonfig.com`         |
+
+Set `QUONFIG_DOMAIN` to move all of them together (e.g.
+`QUONFIG_DOMAIN=quonfig-staging.com`). **Automatic failover and hedging between
+the primary and the secondary are on by default** — the secondary runs on
+separate infrastructure, and the HTTP config-fetch fails over to it if the
+primary is unreachable and hedges to it if the primary is slow.
+
+`api_urls:` replaces the derived list wholesale. To keep automatic failover
+with custom URLs, **pass both a primary and a secondary URL**:
+
+```ruby
+Quonfig::Client.new(
+  sdk_key: 'your-sdk-key',
+  api_urls: [
+    'https://primary.your-proxy.example',
+    'https://secondary.your-proxy.example'
+  ]
+)
+```
+
+A single URL disables failover, and the SDK logs a warning at init. See
+https://docs.quonfig.com/docs/explanations/architecture/resiliency for the full
+model.
+
 ## Typed getters
 
 Each typed getter takes a config key and an optional context hash. If the key

data/lib/quonfig/client.rb

@@ -66,6 +66,16 @@ module Quonfig
       @poll_supervisor = nil
       @stopped = false
       @telemetry_reporter = nil
+      # Shared failover-telemetry aggregator (qfg-41nh.18). Created once and
+      # shared between the ConfigLoader (which records hedge-fired /
+      # guard-rejected / resolved-from at the failover call sites) and the
+      # TelemetryReporter (which drains it on each flush). Created before the
+      # ConfigLoader so the initial HTTP fetch — often the ONLY HTTP fetch when
+      # SSE is healthy — is captured. Recording is a per-config-refresh mutex +
+      # increment (negligible); nothing is EMITTED unless telemetry is enabled
+      # (the reporter, which owns the drain, only starts then). Survives fork:
+      # the pre-fork stop drains it, the child's rebuilt reporter drains onward.
+      @failover_aggregator = Quonfig::Telemetry::FailoverAggregator.new
       @state_mutex = Mutex.new
       @last_successful_refresh = nil
       @sse_state = :idle
@@ -689,6 +699,7 @@ module Quonfig
         context_shape_aggregator: shape_aggregator,
         example_contexts_aggregator: example_aggregator,
         evaluation_summaries_aggregator: summaries_aggregator,
+        failover_aggregator: @failover_aggregator,
         sync_interval: @options.collect_sync_interval
       )
 
@@ -813,8 +824,9 @@ module Quonfig
 
       warn_if_pin_ignored_in_delivery_mode
       warn_if_hedge_abort_exceeds_init_timeout
+      warn_if_explicit_api_urls_disables_failover
 
-      @config_loader = Quonfig::ConfigLoader.new(@store, @options)
+      @config_loader = Quonfig::ConfigLoader.new(@store, @options, failover_aggregator: @failover_aggregator)
 
       perform_initial_fetch
 
@@ -914,6 +926,27 @@ module Quonfig
       )
     end
 
+    # qfg-41nh.26: the SDK's default (and every QUONFIG_DOMAIN-derived) api_urls
+    # list carries a primary AND a secondary leg, and the HTTP config-fetch
+    # hedges/fails over between them (secondary runs on separate infra). An
+    # explicit `api_urls:` replaces that list wholesale, so a single-entry
+    # override silently drops the secondary and disables automatic failover.
+    # Warn once at init in delivery mode so the customer isn't surprised.
+    # Mirrors sdk-go's construction-time warning (quonfig.go). Does not change
+    # behavior. Fired only when the caller explicitly set api_urls AND the
+    # resolved list has fewer than two legs — never on the default/derived
+    # two-URL list.
+    def warn_if_explicit_api_urls_disables_failover
+      return unless @options.respond_to?(:api_urls_explicit)
+      return unless @options.api_urls_explicit
+      return unless Array(@options.config_api_urls).length < 2
+
+      LOG.warn(
+        '[quonfig] explicit api_urls disables automatic failover to the ' \
+        'secondary; pass both primary and secondary URLs to keep it'
+      )
+    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}"

data/lib/quonfig/config_loader.rb

@@ -37,7 +37,7 @@ module Quonfig
     #
     # Backward compat: callers that pass a single +base_client+ (mock client
     # used by tests that expects `.options`) are still supported.
-    def initialize(store_or_base_client, options = nil, logger: nil)
+    def initialize(store_or_base_client, options = nil, logger: nil, failover_aggregator: nil)
       if options.nil? && store_or_base_client.respond_to?(:options)
         # Legacy shape: ConfigLoader.new(base_client)
         @options = store_or_base_client.options
@@ -47,6 +47,11 @@ module Quonfig
         @options = options
       end
 
+      # Optional failover-telemetry sink (qfg-41nh.18). When telemetry is
+      # enabled the Client passes the shared FailoverAggregator; nil otherwise,
+      # so every record call below is a no-op under a telemetry opt-out.
+      @failover_aggregator = failover_aggregator
+
       @api_config = Concurrent::Map.new
       # qfg-7h5d.1.14: per-leg ETag is load-bearing for the parallel hedge. The
       # hedge runs the primary and secondary legs concurrently; a SINGLE shared
@@ -179,6 +184,10 @@ module Quonfig
       # mutually exclusive — exactly one of suppress/fire wins.
       gate = Mutex.new
       secondary_fired = false
+      # Distinct from secondary_fired (which is ALSO set true by suppress on a
+      # fast primary win): this is set only when the secondary leg was ACTUALLY
+      # spawned, so it is the exact "the hedge fired" signal (qfg-41nh.18).
+      secondary_spawned = false
 
       # Each leg is wall-clock bounded by abort_ms (HttpConnection enforces a
       # whole-request deadline, qfg-41nh.6), so a leg ALWAYS settles — a
@@ -203,6 +212,7 @@ module Quonfig
           next false if secondary_fired
 
           secondary_fired = true
+          secondary_spawned = true
         end
         run_leg.call(1) if spawn
       end
@@ -256,6 +266,14 @@ module Quonfig
       # Stop the timer if it is still sleeping (already-fired is harmless).
       hedge_timer.kill if hedge_timer.alive?
 
+      # Failover observability (qfg-41nh.18): if the secondary leg was actually
+      # spawned this cycle, the hedge fired (the primary was slow past the hedge
+      # delay or errored fast). Recorded once per cycle regardless of which leg's
+      # payload won the reject-older guard. Read under the gate — the flag is
+      # written under it by fire_secondary, which may run on the timer thread.
+      hedged = gate.synchronize { secondary_spawned }
+      @failover_aggregator&.record_hedge_fired if hedged
+
       return :updated if installed
       return :not_modified if saw_not_modified
 
@@ -369,6 +387,10 @@ module Quonfig
         # on stale config would be worse (mirrors sdk-node).
         unless @held_generation.nil? || incoming_gen <= 0 || incoming_gen > @held_generation
           @logger.debug "Reject-older guard: dropping incoming generation #{incoming_gen} <= held #{@held_generation} (source=#{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 here.
+          @failover_aggregator&.record_guard_rejected
           return :not_modified
         end
 
@@ -388,6 +410,11 @@ module Quonfig
         @held_generation = incoming_gen
         @install_count += 1
         @resolved_from_index = source_index unless source_index.nil?
+        # Failover observability (qfg-41nh.18): record which leg served this
+        # successful HTTP install (source_index 0 = primary, > 0 = secondary).
+        # SSE / datadir installs pass source_index nil and are ignored by the
+        # aggregator, so they are never counted.
+        @failover_aggregator&.record_resolved_from(source_index)
 
         # Replace the live store atomically.
         return if @store.nil?

data/lib/quonfig/options.rb

@@ -8,7 +8,7 @@ module Quonfig
     attr_reader :sdk_key, :environment, :api_urls, :sse_api_urls, :telemetry_destination, :config_api_urls,
                 :on_no_default, :init_timeout_ms, :on_init_failure, :collect_sync_interval, :datadir, :enable_sse, :fallback_poll_enabled, :fallback_poll_interval_ms, :global_context, :logger_key, :logger, :enable_quonfig_user_context,
                 :data_dir_auto_reload, :data_dir_auto_reload_debounce_ms, :config_fetch_timeout_ms,
-                :config_fetch_hedge_delay_ms, :config_fetch_hedge_abort_ms
+                :config_fetch_hedge_delay_ms, :config_fetch_hedge_abort_ms, :api_urls_explicit
     attr_accessor :is_fork
 
     # Default fallback poll interval, in milliseconds. The SDK polls api-delivery
@@ -140,10 +140,21 @@ module Quonfig
 
     # In datadir mode the SDK evaluates config from a local workspace and does
     # not connect to the delivery service.
+    #
+    # NOTE: this says nothing about telemetry. Datadir mode is a config-DELIVERY
+    # mode; usage telemetry still flows whenever an SDK key is configured. See
+    # #telemetry_allowed?.
     def local_only?
       !@datadir.nil?
     end
 
+    # True when an SDK key is configured. The SDK key is what identifies the
+    # workspace telemetry is attributed to, so it is the single gate on whether
+    # any collection happens at all (qfg-j001 / qfg-5x9x).
+    def sdk_key?
+      !(@sdk_key.nil? || @sdk_key.to_s.empty?)
+    end
+
     def datadir?
       !@datadir.nil?
     end
@@ -202,6 +213,13 @@ module Quonfig
     #     Debounce window in milliseconds. Filesystem events arriving
     #     inside the window are coalesced into a single re-read. Ignored
     #     when +:data_dir_auto_reload+ is +false+.
+    #   @option options [Boolean] :allow_telemetry_in_local_mode (false)
+    #     @deprecated No-op since 1.3.0 (qfg-5x9x). Telemetry is gated on SDK-key
+    #       presence alone, so datadir mode no longer suppresses it and this flag
+    #       has nothing left to unlock. Still accepted so existing callers keep
+    #       working; slated for removal in 2.0.0. To turn telemetry off, use the
+    #       standard opt-outs (+:collect_evaluation_summaries+ +false+,
+    #       +:context_upload_mode+ +:none+).
     def init(
       api_urls: nil,
       telemetry_url: nil,
@@ -226,6 +244,7 @@ module Quonfig
       context_max_size: DEFAULT_MAX_EVAL_SUMMARIES,
       collect_evaluation_summaries: true,
       collect_max_evaluation_summaries: DEFAULT_MAX_EVAL_SUMMARIES,
+      # Deprecated no-op since 1.3.0 (qfg-5x9x) — see the @option doc above.
       allow_telemetry_in_local_mode: false,
       global_context: {},
       logger_key: nil,
@@ -287,6 +306,7 @@ module Quonfig
       @collect_sync_interval = collect_sync_interval
       @collect_evaluation_summaries = collect_evaluation_summaries
       @collect_max_evaluation_summaries = collect_max_evaluation_summaries
+      # Retained for back-compat only; nothing reads it (qfg-5x9x).
       @allow_telemetry_in_local_mode = allow_telemetry_in_local_mode
       @is_fork = false
       @global_context = global_context
@@ -308,6 +328,16 @@ module Quonfig
       #   3. Hardcoded DEFAULT_DOMAIN ('quonfig.com')
       domain = Quonfig::Options.domain
 
+      # Whether the caller explicitly supplied api_urls (vs. the SDK deriving
+      # both legs from QUONFIG_DOMAIN / DEFAULT_DOMAIN). The default and every
+      # domain-derived list carries a primary AND a secondary leg, so the SDK
+      # hedges/fails over automatically; an explicit single-entry override
+      # silently drops the secondary. Client warns once at init when this is
+      # true and the resolved list has < 2 legs (see
+      # Client#warn_if_explicit_api_urls_disables_failover). Mirrors sdk-go's
+      # apiURLsExplicit flag (qfg-41nh.26).
+      @api_urls_explicit = !api_urls.nil?
+
       @api_urls = Array(api_urls || Quonfig::Options.derive_api_urls(domain))
                   .map { |url| remove_trailing_slash(url) }
 
@@ -332,8 +362,21 @@ module Quonfig
       end
     end
 
+    # The telemetry gate: an explicit per-collector opt-out (+option+) AND the
+    # presence of an SDK key. Mode is deliberately NOT part of this decision.
+    #
+    # qfg-5x9x: this used to read
+    #   `option && (!local_only? || @allow_telemetry_in_local_mode)`
+    # which zeroed every collect_max_* the moment a datadir was set, so a
+    # datadir client holding a perfectly valid SDK key built no aggregators and
+    # therefore never constructed a reporter — it emitted nothing at all.
+    # Datadir + SDK key is a supported combination and telemetry has to flow
+    # there like it does in delivery mode. Conversely a keyless client (the
+    # open-source / no-account path) has no workspace to attribute data to, so
+    # nothing is collected and the reporter never starts. Mirrors sdk-node's
+    # `isTelemetryEnabled` and sdk-go's `Options.TelemetryEnabled()`.
     def telemetry_allowed?(option)
-      option && (!local_only? || @allow_telemetry_in_local_mode)
+      option && sdk_key?
     end
 
     def remove_trailing_slash(url)

data/lib/quonfig/telemetry/failover_aggregator.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Quonfig
+  module Telemetry
+    # Accumulates failover-behavior counters over a flush window: how many times
+    # the config-fetch hedge fired its secondary leg, how many installs the
+    # reject-older ordering guard dropped, and which upstream leg served each
+    # successful HTTP install. Every counter is additive and carries NO user
+    # data.
+    #
+    # The aggregator is independently thread-safe (its own mutex) and is written
+    # directly from the failover call sites in ConfigLoader rather than through
+    # any queue — the call rate is per-config-refresh, not per-evaluation, so a
+    # plain mutex has negligible overhead.
+    #
+    # Wire shape matches sdk-go's FailoverEvent (the canonical reference) and
+    # api-telemetry's failover schema EXACTLY — camelCase keys, unix-millis
+    # window. #drain_event returns +nil+ when every counter is zero, so a healthy
+    # steady-state client emits no failover event at all.
+    #
+    #   { "failover": {
+    #       "start": <int ms>, "end": <int ms>,
+    #       "hedgeFired": <int>, "guardRejected": <int>,
+    #       "resolvedFromPrimary": <int>, "resolvedFromSecondary": <int>,
+    #       "resolvedFromLkg": <int>
+    #   } }
+    class FailoverAggregator
+      def initialize
+        @mutex = Mutex.new
+        @start_at_ms = nil
+        @hedge_fired = 0
+        @guard_rejected = 0
+        @resolved_from_primary = 0
+        @resolved_from_secondary = 0
+        # Reserved for a future last-known-good delivery path; backends emit 0.
+        @resolved_from_lkg = 0
+      end
+
+      # Count one config-fetch cycle whose hedge fired the secondary leg (the
+      # primary was slow past the hedge delay or errored fast).
+      def record_hedge_fired
+        @mutex.synchronize do
+          @start_at_ms ||= Quonfig::TimeHelpers.now_in_ms
+          @hedge_fired += 1
+        end
+      end
+
+      # Count one install dropped by the reject-older ordering guard (an
+      # equal-or-older snapshot on any install path — HTTP config-fetch or SSE).
+      def record_guard_rejected
+        @mutex.synchronize do
+          @start_at_ms ||= Quonfig::TimeHelpers.now_in_ms
+          @guard_rejected += 1
+        end
+      end
+
+      # Count one successful HTTP install by the leg that served it: source_index
+      # 0 is the primary, any index > 0 is a failover/secondary leg. A nil or
+      # negative index (SSE / datadir install with no HTTP leg) is ignored.
+      def record_resolved_from(source_index)
+        return if source_index.nil? || source_index.negative?
+
+        @mutex.synchronize do
+          @start_at_ms ||= Quonfig::TimeHelpers.now_in_ms
+          if source_index.zero?
+            @resolved_from_primary += 1
+          else
+            @resolved_from_secondary += 1
+          end
+        end
+      end
+
+      # Return the window's counters as a telemetry event hash and reset state.
+      # Returns +nil+ when no failover activity occurred (every counter zero).
+      def drain_event
+        @mutex.synchronize do
+          if @hedge_fired.zero? && @guard_rejected.zero? &&
+             @resolved_from_primary.zero? && @resolved_from_secondary.zero? &&
+             @resolved_from_lkg.zero?
+            return nil
+          end
+
+          event = {
+            'failover' => {
+              'start' => @start_at_ms || Quonfig::TimeHelpers.now_in_ms,
+              'end' => Quonfig::TimeHelpers.now_in_ms,
+              'hedgeFired' => @hedge_fired,
+              'guardRejected' => @guard_rejected,
+              'resolvedFromPrimary' => @resolved_from_primary,
+              'resolvedFromSecondary' => @resolved_from_secondary,
+              'resolvedFromLkg' => @resolved_from_lkg
+            }
+          }
+
+          reset
+          event
+        end
+      end
+
+      private
+
+      # Caller holds @mutex.
+      def reset
+        @start_at_ms = nil
+        @hedge_fired = 0
+        @guard_rejected = 0
+        @resolved_from_primary = 0
+        @resolved_from_secondary = 0
+        @resolved_from_lkg = 0
+      end
+    end
+  end
+end

data/lib/quonfig/telemetry/telemetry_reporter.rb

@@ -13,7 +13,8 @@ module Quonfig
     #     "events": [
     #       { "summaries":       { "start": ..., "end": ..., "summaries": [...] } },
     #       { "contextShapes":   { "shapes":   [...] } },
-    #       { "exampleContexts": { "examples": [...] } }
+    #       { "exampleContexts": { "examples": [...] } },
+    #       { "failover":        { "start": ..., "end": ..., "hedgeFired": ..., ... } }
     #     ]
     #   }
     #
@@ -30,6 +31,7 @@ module Quonfig
                      context_shape_aggregator: nil,
                      example_contexts_aggregator: nil,
                      evaluation_summaries_aggregator: nil,
+                     failover_aggregator: nil,
                      sync_interval: nil,
                      http_connection: nil)
         @options = options
@@ -39,6 +41,11 @@ module Quonfig
         @context_shape_aggregator = context_shape_aggregator
         @example_contexts_aggregator = example_contexts_aggregator
         @evaluation_summaries_aggregator = evaluation_summaries_aggregator
+        # Failover counters carry no user data and are the operational signal for
+        # the secondary-delivery hardening (qfg-41nh.18), so they ride the
+        # existing telemetry stream. The ConfigLoader records directly into this
+        # aggregator at the failover call sites; the reporter only drains it.
+        @failover_aggregator = failover_aggregator
         @http_connection = http_connection
         @sync_interval = calculate_sync_interval(sync_interval)
         @stopped = Concurrent::AtomicBoolean.new(false)
@@ -125,6 +132,9 @@ module Quonfig
         if (example_event = @example_contexts_aggregator&.drain_event)
           events << example_event
         end
+        if (failover_event = @failover_aggregator&.drain_event)
+          events << failover_event
+        end
 
         return if events.empty?
 

data/lib/quonfig/version.rb

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

data/lib/quonfig.rb

@@ -61,6 +61,7 @@ require 'quonfig/telemetry/context_shape'
 require 'quonfig/telemetry/context_shape_aggregator'
 require 'quonfig/telemetry/example_contexts_aggregator'
 require 'quonfig/telemetry/evaluation_summaries_aggregator'
+require 'quonfig/telemetry/failover_aggregator'
 require 'quonfig/telemetry/telemetry_reporter'
 require 'quonfig/client'
 require 'quonfig/bound_client'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: quonfig
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.3.0
 platform: ruby
 authors:
 - Jeff Dwyer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-06 00:00:00.000000000 Z
+date: 2026-08-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -130,6 +130,7 @@ files:
 - lib/quonfig/telemetry/context_shape_aggregator.rb
 - lib/quonfig/telemetry/evaluation_summaries_aggregator.rb
 - lib/quonfig/telemetry/example_contexts_aggregator.rb
+- lib/quonfig/telemetry/failover_aggregator.rb
 - lib/quonfig/telemetry/telemetry_reporter.rb
 - lib/quonfig/time_helpers.rb
 - lib/quonfig/types.rb