convert_sdk 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16cc235aa36baea77098bf6d47a5d479e840ca95a416b36b87f8f178b95895c1
-  data.tar.gz: 1354d6d78384ebea2f6b187ae601da34e7090de152fc6ca4fa95480e406c04a0
+  metadata.gz: 4971b19e554964f05a8c86555b919d102492a09190eac1747567177f375dc29e
+  data.tar.gz: b4a91c4ab52075f0268aa1f138989f406d4f9166f7cd06f859ea879a4f7e2975
 SHA512:
-  metadata.gz: 5fc43abd0fbf174055ef97a00c3c983f232287f886151990931f2635a733fcd0a626e1b35a7f7ef564b2953bcc3cee32b6fe7cb96a9e9ba7dce40b5dfc2e7ae7
-  data.tar.gz: 74e704ae66077b55a6e92a008a44933190208f8b3caaacefbea041801b4e9bfe8e8498f082205bfa71b4901834ed9cca2ce5d3e80b5e317848e4fc4a2b925e6e
+  metadata.gz: 288df65beff1f18b3dbe25334e31e852222705c0786113cb56fbd3a253ffc5edcfba335a00258c062ea7faf34728afd5e26ecd234f7df305cb74e043275e962b
+  data.tar.gz: 2ee04c45261064677c2cd2da5bd4a89e06747f39cf172a9d02a87a976ef167d48b7ddafaa5df3b1c1ad9961e5e7fced4d636313f9645dd5ac2b0bf670f9c748e

data/.rubocop.yml

@@ -82,6 +82,15 @@ Metrics/ClassLength:
     # length reflects the ported reference surface, not unmanaged growth (same
     # rationale as the DataManager/RuleManager feature surfaces above).
     - "lib/convert_sdk/feature_manager.rb"
+    # ApiManager (RB-3 / qs-03 AC4/AC8) gains #get_config_by_experience — the
+    # exp-scoped preview-config fetch + its process-wide memo. The task spec
+    # explicitly directs this onto ApiManager rather than a new file ("do not
+    # reach into Client or duplicate the qs-02 low-cache pattern wholesale —
+    # this is a distinct exp-scoped endpoint" living beside the existing
+    # HTTP-port delivery surface). Same rationale as the other cohesive-
+    # feature-surface exclusions above: the growth is the mandated surface,
+    # not unmanaged sprawl.
+    - "lib/convert_sdk/api_manager.rb"
 
 # The Client (Story 2.5) is wired by explicit constructor injection of its six
 # collaborator managers (config, log, http, data-store, event, data) — the

data/CONTRIBUTING.md

@@ -73,7 +73,7 @@ runs on CRuby only — the JRuby leg runs the suite without the gate.
 |-----------|------------------|
 | `spec/unit/` | Per-class unit specs (mock collaborators, isolated logic). |
 | `spec/integration/` | End-to-end specs: `full_chain_spec.rb` (the release-blocking create→decide→track→flush loop), `runtime_recipes_spec.rb` (the runtime-lifecycle recipes the quickstarts are transcribed from), `fork_safety_spec.rb`, `factory_wiring_spec.rb`. |
-| `spec/cross_sdk/` | The cross-SDK MurmurHash3 parity vectors (the byte-identical bucketing proof). |
+| `spec/cross_sdk/` | The cross-SDK parity proofs: MurmurHash3 hash vectors and the anchored bucketing layout vectors (`anchored_bucketing_vectors_spec.rb`) — the byte-identical bucketing proof. |
 | `spec/docs/` | Docs-snippet smoke specs — run the README/quickstart code samples against the real gem so documentation never drifts. |
 | `spec/staging/` | The live-platform suite (runs on schedule/dispatch only, never in PR CI). |
 | `spec/support/` | Shared helpers (e.g. `runtime_recipe_helpers.rb`, which co-locates the recipe wiring snippets the quickstarts ship). |

data/README.md

@@ -1,7 +1,7 @@
 # Convert Ruby SDK
 
 [![Quality Checks](https://github.com/convertcom/ruby-sdk/actions/workflows/qa.yml/badge.svg)](https://github.com/convertcom/ruby-sdk/actions/workflows/qa.yml)
-[![Gem Version](https://badge.fury.io/rb/convert_sdk.svg)](https://rubygems.org/gems/convert_sdk)
+[![Gem Version](https://img.shields.io/gem/v/convert_sdk.svg)](https://rubygems.org/gems/convert_sdk)
 [![API docs](https://img.shields.io/badge/API_docs-YARD-blue)](https://convertcom.github.io/ruby-sdk)
 
 The official Convert Experiences FullStack Ruby SDK — server-side A/B testing,

data/lib/convert_sdk/api_manager.rb

@@ -2,6 +2,8 @@
 
 require "json"
 
+require "uri"
+
 module ConvertSdk
   # The outbound delivery manager — it owns the {VisitorsQueue}, the tracking
   # endpoint, queue release, and THE wire-payload builder.
@@ -59,6 +61,97 @@ module ConvertSdk
     # dataStore is configured, and Ruby always provides one (api-manager.ts:94).
     ENRICH_DATA = false
 
+    # qs-03 AC8 — the {#get_config_by_experience} memo TTL in seconds. JS
+    # oracle: +CONFIG_BY_EXPERIENCE_TTL+ (api-manager.ts, ms there, seconds
+    # here — Ruby-side math is wall-clock seconds via +Time.now.to_f+).
+    CONFIG_BY_EXPERIENCE_TTL = 60
+
+    # qs-03 AC8 — the PROCESS-WIDE {#get_config_by_experience} memo: a class-
+    # level Hash (NOT a class variable — see architecture's "no globals or
+    # singletons" constructor-injection mandate; this is the one deliberate,
+    # narrowly-scoped exception, mirroring the JS oracle's module-level
+    # +configByExperienceCache+ Map so every {ApiManager} instance sharing an
+    # +sdk_key+ shares one fetch) keyed +"{sdk_key}:{experience_id}"+, entries
+    # shaped +{"config" => Hash, "expires_at" => Float}+. Mutated only under
+    # the +@config_by_experience_mutex+ below (fork-safety + thread-safety) —
+    # mirrors {ForkGuard}'s own module-level-state + mutex discipline
+    # (fork_guard.rb).
+    @config_by_experience_cache = {}
+    # qs-03 AC8 — guards {@config_by_experience_cache}. Class-level (not
+    # per-instance) because the cache it protects is process-wide.
+    @config_by_experience_mutex = Thread::Mutex.new
+
+    class << self
+      # Read a still-fresh (within {CONFIG_BY_EXPERIENCE_TTL}) memoized config
+      # for +cache_key+, or +nil+ when absent/expired (qs-03 AC8).
+      # @api private
+      # @param cache_key [String]
+      # @return [Hash{String=>Object}, nil]
+      def cached_config_by_experience(cache_key)
+        @config_by_experience_mutex.synchronize do
+          entry = @config_by_experience_cache[cache_key]
+          entry["config"] if entry && Time.now.to_f < entry["expires_at"]
+        end
+      end
+
+      # Memoize +config+ under +cache_key+ for {CONFIG_BY_EXPERIENCE_TTL}
+      # seconds (qs-03 AC8). A failed fetch must NEVER reach this method (the
+      # caller only memoizes on success).
+      #
+      # FIX-1 (code review round 1) — sweeps every OTHER already-expired entry
+      # from the process-wide cache before inserting, mirroring the JS oracle
+      # (+api-manager.ts+ ~367-370, which does the same on every
+      # +getConfigByExperience+ write). +experience_id+ is
+      # operator/attacker-influenced (the +convert_preview={expId}.{varId}+
+      # link param), so without this sweep a stream of distinct ids would grow
+      # this Hash without bound in a long-lived process (a Puma/Rails worker) —
+      # it would otherwise only shrink on fork or process exit.
+      # @api private
+      # @param cache_key [String]
+      # @param config [Hash{String=>Object}]
+      # @return [void]
+      def memoize_config_by_experience(cache_key, config)
+        @config_by_experience_mutex.synchronize do
+          now = Time.now.to_f
+          @config_by_experience_cache.delete_if { |_key, entry| entry["expires_at"] <= now }
+          @config_by_experience_cache[cache_key] = {
+            "config" => config,
+            "expires_at" => now + CONFIG_BY_EXPERIENCE_TTL
+          }
+        end
+      end
+
+      # Test-only reset (mirrors {ForkGuard.reset_for_tests!}) so specs stay
+      # order-independent against this process-wide memo. Also the FORK-side
+      # clear (registered per-instance in {#initialize} via
+      # +ForkGuard.register_child_callback+): even though a stale memo isn't
+      # unsafe to serve, clearing it on fork matches this file's existing
+      # queue-ownership-clear discipline ({#clear_queue_ownership}) and avoids
+      # a forked child transparently serving a parent process's stale
+      # preview-experience config across a fork boundary.
+      # @api private
+      # @return [void]
+      def reset_config_by_experience_cache_for_tests!
+        @config_by_experience_mutex.synchronize { @config_by_experience_cache = {} }
+      end
+
+      # Test-only inspection: the current size of {@config_by_experience_cache}
+      # (FIX-1, code review round 1, qs-03 AC8 hardening). Lets specs assert
+      # that {.memoize_config_by_experience}'s expired-entry sweep actually
+      # shrinks the process-wide Hash — not merely that an expired LOOKUP
+      # returns nil. `experience_id` is operator/attacker-influenced (the
+      # +convert_preview={expId}.{varId}+ link param), so without a sweep a
+      # stream of distinct ids would accumulate unbounded entries in a
+      # long-lived process (Puma/Rails worker). Mirrors
+      # {.reset_config_by_experience_cache_for_tests!}'s test-only scope and
+      # mutex discipline.
+      # @api private
+      # @return [Integer]
+      def config_by_experience_cache_size_for_tests
+        @config_by_experience_mutex.synchronize { @config_by_experience_cache.size }
+      end
+    end
+
     # @param config [Config] the validated configuration (track endpoint, sdk_key,
     #   sdk_key_secret).
     # @param data_manager [DataManager] supplies +account_id+ / +project_id+ for
@@ -95,6 +188,12 @@ module ConvertSdk
       # knows nothing about the queue; ApiManager owns its own clear (architecture
       # Decision 6 callback-registry design).
       ForkGuard.register_child_callback(-> { clear_queue_ownership })
+      # qs-03 AC8 — clear the process-wide config-by-experience memo in a
+      # forked child (see {ApiManager.reset_config_by_experience_cache_for_tests!}
+      # doc for the rationale). Registered ALONGSIDE (not replacing) the
+      # queue-ownership-clear callback above — ForkGuard fires every
+      # registered callback in registration order.
+      ForkGuard.register_child_callback(-> { ApiManager.reset_config_by_experience_cache_for_tests! })
     end
 
     # @return [VisitorsQueue] the underlying per-visitor event queue.
@@ -167,6 +266,42 @@ module ConvertSdk
       @log_manager.error("ApiManager#release_queue: #{e.class}: #{e.message}")
     end
 
+    # Fetch (or reuse a memoized) config scoped to a single experience — qs-03
+    # AC4 fetch resolution / AC8 memoization, the preview lookup path. Always
+    # requests +_conv_low_cache=1+ (bypassing the CDN cache) and scopes the
+    # response with +exp=<experience_id>+; includes +environment+ /
+    # +debug_token+ when configured. JS oracle: +getConfigByExperience+
+    # (api-manager.ts ~344).
+    #
+    # Memoized PROCESS-WIDE (see {CONFIG_BY_EXPERIENCE_TTL}), keyed
+    # +"{sdk_key}:{experience_id}"+ — repeated lookups within the TTL window,
+    # including from a DIFFERENT {ApiManager} instance sharing the same
+    # +sdk_key+, reuse the same fetch. Never touches the store (qs-03: "TTL
+    # 60s (in-memory only; never the store)") — the memo lives entirely in the
+    # class-level cache.
+    #
+    # On a failed fetch (transport failure, non-2xx, or a non-Hash body):
+    # returns +nil+ WITHOUT memoizing, so the next lookup retries (graceful
+    # degradation, NFR9 — never raises).
+    #
+    # @param experience_id [String]
+    # @return [Hash{String=>Object}, nil] the fetched/memoized config, or nil
+    #   on a failed fetch.
+    def get_config_by_experience(experience_id)
+      # Data-only mode guard (review round 2) — a direct-data Config has no
+      # sdk_key, and therefore no config-fetch endpoint to hit; without this
+      # guard a preview resolution reachable in that mode would build a
+      # +.../config/?exp=…+ URL with a nil key and fire a guaranteed-failing
+      # HTTP request.
+      return nil if @config.sdk_key.nil?
+
+      cache_key = "#{@config.sdk_key}:#{experience_id}"
+      cached = self.class.cached_config_by_experience(cache_key)
+      return cached unless cached.nil?
+
+      fetch_config_by_experience(cache_key, experience_id)
+    end
+
     private
 
     # POST the drained per-visitor entries and branch on the result. On SUCCESS:
@@ -284,5 +419,37 @@ module ConvertSdk
 
       { "Authorization" => "Bearer #{secret}" }
     end
+
+    # GET {config_by_experience_url(experience_id)} through the HTTP port; on
+    # success with a Hash body, memoize and return it, else return nil WITHOUT
+    # memoizing (qs-03 AC4/AC8). +@config.sdk_key+ is used directly (no
+    # account/project fallback — the config-fetch convention this endpoint
+    # mirrors, {Client#config_url}, uses +@config.sdk_key+ unconditionally; the
+    # fallback in {#sdk_key} is a track-URL-only concern).
+    def fetch_config_by_experience(cache_key, experience_id)
+      response = @http_client.request(method: :get, url: config_by_experience_url(experience_id), headers: auth_headers)
+      return nil unless response.success? && response.body.is_a?(Hash)
+
+      self.class.memoize_config_by_experience(cache_key, response.body)
+      response.body
+    end
+
+    # Build +{config_endpoint}/config/{sdk_key}+ with query params in the
+    # FIXED order the qs-03 contract mandates: +environment+ (when set), then
+    # +exp=<experience_id>+ (always), then +_conv_low_cache=1+ (always), then
+    # +debug_token+ (when set). Values are URI-encoded (mirrors
+    # {Client#config_url_params}'s encoding convention).
+    def config_by_experience_url(experience_id)
+      env = @config.environment
+      debug_token = @config.debug_token
+
+      params = [] #: Array[String]
+      params << "environment=#{URI.encode_www_form_component(env)}" unless env.nil?
+      params << "exp=#{URI.encode_www_form_component(experience_id)}"
+      params << "_conv_low_cache=1"
+      params << "debug_token=#{URI.encode_www_form_component(debug_token)}" unless debug_token.nil?
+
+      "#{@config.config_endpoint}/config/#{@config.sdk_key}?#{params.join("&")}"
+    end
   end
 end

data/lib/convert_sdk/bucketing_manager.rb

@@ -39,6 +39,16 @@ module ConvertSdk
   #
   # @api private
   class BucketingManager
+    # Fixed anchor-scale constant for the ANCHORED bucketing layout (contract
+    # v12, qs-01). Unlike +max_traffic+ (config-supplied, used only to scale the
+    # visitor's HASH value in {#value_visitor_based}), the anchor/width scale for
+    # the anchored range walk is a FIXED module constant in the JS oracle
+    # (+bucketing-manager.ts:25+ +DEFAULT_MAX_TRAFFIC = 10000+) — never read from
+    # config. Named here (rather than an inline literal in {#select_bucket_anchored})
+    # so the constant stays traceable to its JS origin without conflating it with
+    # the per-config +@max_traffic+ used elsewhere in this class.
+    ANCHORED_MAX_TRAFFIC = 10_000
+
     # Build a bucketing engine bound to a {Config}'s frozen bucketing constants.
     #
     # @param config [Config] supplies +max_traffic+, +hash_seed+, +max_hash+.
@@ -130,5 +140,156 @@ module ConvertSdk
 
       { variation_id: selected, bucketing_allocation: value }
     end
+
+    # Select the variation whose ANCHORED range contains +value+ (contract v12,
+    # qs-01/BUCK-2). Given the FULL ordered variation config list (active AND
+    # inactive/stopped arms — never pre-filtered), this folds the JS reference's
+    # +getBucketRanges+ + +selectBucketAnchored+ (bm.ts:145-190) into one pass so
+    # the method stays self-contained and independently unit-testable:
+    #
+    #   allocation = anchored_allocation(ta) — Float(ta, exception: false) coercion; a
+    #     nil coercion result (non-numeric/absent ta) defaults to 100.0, mirroring the
+    #     JS oracle's `isNaN(ta) ? 100.0 : Number(ta)`
+    #   active     = anchored_active?(status, allocation) — ((status.nil? || status == "")
+    #     ? true : status == "running") && allocation.positive?
+    #   total_weight = sum(allocation) over ALL entries (active AND inactive)
+    #   return nil if total_weight <= 0
+    #   cum = 0.0
+    #   each entry: anchor = (cum / total_weight) * ANCHORED_MAX_TRAFFIC
+    #               width  = active ? allocation * 100 : 0
+    #               hit iff anchor <= value < anchor + width (first match wins)
+    #               cum += allocation
+    #
+    # Inactive arms (stopped, or an explicit +traffic_allocation: 0+) keep their
+    # weight (anchor stability for the OTHER arms) but get zero width, so they
+    # can never themselves be selected. This is a DIFFERENT method from the
+    # packed {#select_bucket} — that packed walk is untouched for version<=11.
+    #
+    # @param variations [Array<Hash>] the FULL ordered variation config list
+    #   (+"id"+, +"traffic_allocation"+, +"status"+) — inactive arms included.
+    # @param value [Integer] a bucket value in +[0, ANCHORED_MAX_TRAFFIC)+.
+    # @return [String, nil] the selected variation id, or +nil+ (including when
+    #   +total_weight <= 0+ or the list is empty).
+    def select_bucket_anchored(variations, value)
+      entries = anchored_allocations(variations)
+      # NAIVE left-to-right fold — NOT +Array#sum+. Ruby's +Array#sum+ uses a
+      # Kahan-Babuska (Neumaier) compensated algorithm for Float arrays, which
+      # can differ from a plain fold at the float64 ULP level. The JS oracle
+      # computes +totalWeight+ via a naive +Array.prototype.reduce+
+      # (+bucketing-manager.ts:153-156+: +allocations.reduce((sum, {allocation})
+      # => sum + allocation, 0)+) — every other SDK (PHP/Python/Android/iOS)
+      # matches that same naive fold. A compensated sum here would diverge from
+      # every other SDK's +total_weight+ by 1+ ULP on some inputs, which can
+      # flip which arm a boundary +value+ resolves to (verified: a 3-way
+      # ~33.34/33.33/33.33-style split picks a different arm at its exact
+      # anchor boundary depending on the fold algorithm) — a cross-SDK parity
+      # break, not just a cosmetic rounding difference.
+      total_weight = entries.reduce(0.0) { |acc, entry| acc + entry[:allocation] }
+      variation = total_weight.positive? ? anchored_walk(entries, total_weight, value) : nil
+
+      @log_manager&.debug(
+        "BucketingManager#select_bucket_anchored: " \
+        "value=#{value} total_weight=#{total_weight} variation=#{variation.inspect}"
+      )
+      variation
+    end
+
+    # Resolve a visitor to a variation under the ANCHORED layout (contract v12),
+    # returning the SAME shape as {#bucket_for_visitor} (AC9 — no return-shape
+    # drift): +{variation_id:, bucketing_allocation:}+ or +nil+. Reuses the
+    # existing visitor-hash value unchanged (JS +getBucketForVisitorAnchored+,
+    # bm.ts:195-215) then resolves it through {#select_bucket_anchored}.
+    #
+    # @param variations [Array<Hash>] the FULL ordered variation config list
+    #   (active AND inactive arms) — see {#select_bucket_anchored}.
+    # @param visitor_id [#to_s] the visitor identifier.
+    # @param experience_id [String] the experience identifier (default +""+).
+    # @param seed [Integer] MurmurHash3 seed (default Config hash seed).
+    # @return [Hash{Symbol=>Object}, nil] +{variation_id:, bucketing_allocation:}+
+    #   or +nil+ (caller treats +nil+ as VARIATION_NOT_DECIDED).
+    def bucket_for_visitor_anchored(variations, visitor_id, experience_id: "", seed: @hash_seed)
+      value = value_visitor_based(visitor_id, experience_id: experience_id, seed: seed)
+      selected = select_bucket_anchored(variations, value)
+
+      @log_manager&.debug(
+        "BucketingManager#bucket_for_visitor_anchored: " \
+        "experience_id=#{experience_id.inspect} visitor_id=#{visitor_id.inspect} " \
+        "bucket_value=#{value} selected_variation_id=#{selected.inspect}"
+      )
+
+      return nil if selected.nil?
+
+      { variation_id: selected, bucketing_allocation: value }
+    end
+
+    private
+
+    # Build +{id:, allocation:, active:}+ entries from the raw ordered variation
+    # config list, mirroring the JS +_buildVariationAllocations+ mapping
+    # (data-manager.ts:591-610). Entries without an +"id"+ are skipped entirely
+    # (never counted in +total_weight+, never selectable) — defensive against a
+    # sparse/malformed config row, same tolerance the rest of the SDK applies.
+    def anchored_allocations(variations)
+      variations.each_with_object([]) do |variation, entries|
+        next unless variation.is_a?(Hash) && variation["id"]
+
+        allocation = anchored_allocation(variation["traffic_allocation"])
+        active = anchored_active?(variation["status"], allocation)
+        entries << { id: variation["id"], allocation: allocation, active: active }
+      end
+    end
+
+    # Mirrors the JS +isNaN(ta) ? 100.0 : Number(ta)+ mapping
+    # (data-manager.ts:594-601) via +Float(x, exception: false)+ coercion: a
+    # numeric-looking String (e.g. +"50"+) coerces to its numeric weight
+    # exactly like the JS oracle's +Number()+, not just a genuine
+    # Integer/Float. A genuinely non-numeric value, +nil+, or an absent field
+    # coerces to +nil+ and defaults to +100.0+ (full-allocation weight, AC5) —
+    # RBS core types +Float(untyped, exception: false)+ as +Float?+, so the
+    # nil-check both implements the JS default and narrows the return to the
+    # declared +-> Float+.
+    #
+    # Hard boundary (documented, not fixable in Ruby): +JSON.parse+ collapses
+    # an explicit JSON +null+ +traffic_allocation+ and an ABSENT field to the
+    # same Ruby +nil+, so this SDK cannot reproduce JS's split (JS: absent ->
+    # +undefined+ -> +isNaN+ -> 100.0/active; explicit +null+ ->
+    # +Number(null)+ is +0+ -> 0/inactive). We match JS for the served/tested
+    # case (absent -> 100.0/active); explicit-null +traffic_allocation+ is
+    # never served (0 occurrences in the 59-vector golden fixture). The same
+    # coercion-class divergence applies to an empty-string/whitespace-only
+    # +traffic_allocation+: +Float("", exception: false)+ (and whitespace-only
+    # strings) coerce to +nil+ -> defaults to 100.0/active here, whereas JS's
+    # +Number("")+ is +0+ -> 0/inactive; behaviorally neutral for the actual
+    # contract since +traffic_allocation+ is a backend-served numeric field
+    # and this value is never served (0 occurrences of empty-string/
+    # whitespace-only +ta+ in the 59-vector golden cross-SDK fixture).
+    def anchored_allocation(traffic_allocation)
+      coerced = Float(traffic_allocation, exception: false)
+      coerced.nil? ? 100.0 : coerced
+    end
+
+    # +true+ when the variation is eligible for a non-zero anchored width: a
+    # +nil+/+""+ status defaults to running (JS +status ? status === RUNNING :
+    # true+, treating an empty string as falsy), AND the allocation is positive
+    # (an explicit +traffic_allocation: 0+ is inactive, never defaulted to 100).
+    def anchored_active?(status, allocation)
+      status_active = status.nil? || status == "" ? true : status == "running"
+      status_active && allocation.positive?
+    end
+
+    # Walk the anchored +entries+ in config order, returning the first entry
+    # whose half-open +[anchor, anchor + width)+ band contains +value+, or +nil+
+    # when no band covers it. +total_weight+ is guaranteed positive by the caller.
+    def anchored_walk(entries, total_weight, value)
+      cum = 0.0
+      entries.each do |entry|
+        anchor = (cum / total_weight) * ANCHORED_MAX_TRAFFIC
+        width = entry[:active] ? entry[:allocation] * 100 : 0
+        return entry[:id] if value >= anchor && value < anchor + width
+
+        cum += entry[:allocation]
+      end
+      nil
+    end
   end
 end

data/lib/convert_sdk/client.rb

@@ -347,12 +347,15 @@ module ConvertSdk
     # Fetch config through the HTTP port and install it on success. A failed
     # response degrades gracefully: it MAY fall back to a non-stale cached entry
     # from the store (meaningful across processes with a shared store like
-    # Redis), otherwise a +warn+ line, no config, no raise.
+    # Redis), otherwise a +warn+ line, no config, no raise. The store fallback
+    # is skipped entirely when +debug_token+ is configured (qs-03 AC2 —
+    # always-live: a stale copy is misleading during QA, so a failed live
+    # fetch degrades straight to the no-config warn path).
     def fetch_and_install_config
       response = @http_client.request(method: :get, url: config_url, headers: fetch_headers)
       if response.success? && response.body.is_a?(Hash)
         install(response.body, "Client#initialize: installed fetched config")
-      elsif @data_manager.install_from_cache_if_fresh
+      elsif @config.debug_token.nil? && @data_manager.install_from_cache_if_fresh
         @event_manager.fire(SystemEvents::READY, deferred: true)
       else
         @log_manager.warn(
@@ -378,14 +381,46 @@ module ConvertSdk
       end
     end
 
-    # Build the config-fetch URL: +{config_endpoint}/config/{sdkKey}+ with an
-    # +environment+ query parameter appended only when one is configured.
-    def config_url
+    # Build the config-fetch URL: +{config_endpoint}/config/{sdkKey}+ with
+    # query params appended in a fixed order — +environment+ (when configured),
+    # then +_conv_low_cache=1+ (when effective low-cache is active), then
+    # +debug_token=<value>+ (when configured) — joined with +&+ and prefixed
+    # with a single +?+ only when at least one param is present. +environment+
+    # stays first so the no-cache_level/no-override shape (the pre-RB-2 AC2
+    # regression lock) stays byte-identical: bare URL when no environment,
+    # +?environment=...+ with no trailing +&+ otherwise.
+    #
+    # +force_low_cache:+ is a private, internal-only seam (qs-03's per-fetch
+    # experiment-preview override) — not part of the public API. Effective
+    # low-cache is an OR of the override, the configured +cache_level+, and a
+    # configured +debug_token+ (qs-03 AC1 — a debug token always forces
+    # low-cache, regardless of +cache_level+):
+    # +force_low_cache || @config.cache_level == "low" || !@config.debug_token.nil?+.
+    # +debug_token+ requires no call-site argument — every #config_url call
+    # (construction fetch, refresh tick, timer-off refetch) picks it up
+    # directly from +@config.debug_token+.
+    def config_url(force_low_cache: false)
       url = "#{@config.config_endpoint}/config/#{@config.sdk_key}"
+      params = config_url_params(force_low_cache)
+
+      return url if params.empty?
+
+      "#{url}?#{params.join("&")}"
+    end
+
+    # The ordered query-param list for {#config_url} — extracted so the URL
+    # builder itself stays small: +environment+, then +_conv_low_cache=1+
+    # (effective low-cache), then +debug_token+, each only when applicable.
+    def config_url_params(force_low_cache)
       env = @config.environment
-      return url if env.nil?
+      debug_token = @config.debug_token
+      low_cache = force_low_cache || @config.cache_level == "low" || !debug_token.nil?
 
-      "#{url}?environment=#{URI.encode_www_form_component(env)}"
+      params = [] #: Array[String]
+      params << "environment=#{URI.encode_www_form_component(env)}" unless env.nil?
+      params << "_conv_low_cache=1" if low_cache
+      params << "debug_token=#{URI.encode_www_form_component(debug_token)}" unless debug_token.nil?
+      params
     end
 
     # The fetch headers: an +Authorization: Bearer {secret}+ value when a secret

data/lib/convert_sdk/config.rb

@@ -82,7 +82,16 @@ module ConvertSdk
       tracking: true,
       # HTTP client timeouts in seconds (consumed by HttpClient, Story 1.5).
       open_timeout: 5,
-      read_timeout: 10
+      read_timeout: 10,
+      # Network cache-level signal (qs-02); nil is a no-op, "low" appends the
+      # platform's low-cache query param to config-fetch URLs.
+      cache_level: nil,
+      # QA config-transport token (qs-03); nil is a no-op. When set, every
+      # config-fetch URL carries debug_token=<value> AND is forced to
+      # low-cache, config caching (read fallback + write-through) is disabled,
+      # and the value is redacted like sdk_key_secret (never logged in clear,
+      # never included in the wire payload built by #to_internal).
+      debug_token: nil
     }.freeze
 
     # @!attribute [r] sdk_key
@@ -121,11 +130,19 @@ module ConvertSdk
     #   @return [Numeric] HTTP connect timeout seconds (HttpClient, NFR3).
     # @!attribute [r] read_timeout
     #   @return [Numeric] HTTP read timeout seconds (HttpClient, NFR3).
+    # @!attribute [r] cache_level
+    #   @return [String, nil] network cache-level signal (JS +network.cacheLevel+);
+    #     nil is a no-op, "low" appends a low-cache signal to config fetches (qs-02).
+    # @!attribute [r] debug_token
+    #   @return [String, nil] QA config-transport token (qs-03); nil is a no-op.
+    #     When set, forces a live, low-cache config fetch carrying
+    #     +debug_token=<value>+ and disables config caching; redacted like
+    #     +sdk_key_secret+ and never present in {#to_internal}.
     attr_reader :sdk_key, :sdk_key_secret, :data, :environment,
                 :config_endpoint, :track_endpoint, :max_traffic, :hash_seed,
                 :data_refresh_interval, :event_batch_size, :flush_interval,
                 :keys_case_sensitive, :negation, :log_level, :tracking,
-                :open_timeout, :read_timeout
+                :open_timeout, :read_timeout, :cache_level, :debug_token
 
     # Build a validated configuration from snake_case keyword options merged over
     # {DEFAULTS}. Raises +ArgumentError+ (the SDK's only raising surface) on any
@@ -209,6 +226,7 @@ module ConvertSdk
 
       log_manager.register_secret(@sdk_key) unless @sdk_key.nil?
       log_manager.register_secret(@sdk_key_secret) unless @sdk_key_secret.nil?
+      log_manager.register_secret(@debug_token) unless @debug_token.nil?
     end
   end
 end

data/lib/convert_sdk/config_validator.rb

@@ -20,7 +20,9 @@ module ConvertSdk
   # * intervals — +data_refresh_interval+ / +flush_interval+ are Numeric or nil
   #   (nil = timer-off); +open_timeout+ / +read_timeout+ are Numeric;
   # * booleans — +keys_case_sensitive+ / +tracking+ (strict true/false);
-  # * log level — must be one of the {LogLevel} values.
+  # * log level — must be one of the {LogLevel} values;
+  # * cache level (qs-02) — must be +nil+ or the String +"low"+;
+  # * debug token (qs-03) — must be +nil+ or a String (no fixed allow-list).
   class ConfigValidator
     # The accepted {LogLevel} integer values (TRACE..SILENT).
     LOG_LEVEL_VALUES = [
@@ -28,6 +30,9 @@ module ConvertSdk
       LogLevel::WARN, LogLevel::ERROR, LogLevel::SILENT
     ].freeze
 
+    # The accepted +cache_level+ values (qs-02): nil (no-op) or "low".
+    CACHE_LEVEL_VALUES = [nil, "low"].freeze
+
     # @param values [Hash{Symbol=>Object}] the merged option values, keyed by the
     #   public snake_case option names (the {Config::DEFAULTS} keys).
     def initialize(values)
@@ -46,6 +51,7 @@ module ConvertSdk
       validate_intervals!
       validate_booleans!
       validate_log_level!
+      validate_cache_level!
     end
 
     private
@@ -59,7 +65,7 @@ module ConvertSdk
 
     # String-or-nil options, plus the Hash-or-nil data option.
     def validate_strings!
-      %i[sdk_key sdk_key_secret environment config_endpoint track_endpoint negation].each do |name|
+      %i[sdk_key sdk_key_secret environment config_endpoint track_endpoint negation debug_token].each do |name|
         require_string(name, @values[name])
       end
       require_type(:data, @values[:data], Hash) unless @values[:data].nil?
@@ -96,6 +102,16 @@ module ConvertSdk
             "log_level must be a LogLevel value (#{LOG_LEVEL_VALUES.join(", ")}), got #{level.inspect}"
     end
 
+    # cache_level (qs-02) must be nil or "low" — the platform's low-cache signal.
+    def validate_cache_level!
+      value = @values[:cache_level]
+      return if CACHE_LEVEL_VALUES.include?(value)
+
+      raise ArgumentError,
+            "cache_level must be nil or \"low\" (#{CACHE_LEVEL_VALUES.map(&:inspect).join(", ")}), " \
+            "got #{value.inspect}"
+    end
+
     # Require String-or-nil (nil acceptable for optional strings).
     def require_string(name, value)
       return if value.nil? || value.is_a?(String)