convert_sdk 1.0.0 → 2.0.0

data/lib/convert_sdk/data_manager.rb

@@ -18,19 +18,21 @@ module ConvertSdk
   #
   # == No raw config hash crosses the boundary
   #
-  # The parsed config envelope is wrapped here and exposed ONLY through
-  # hand-written reader methods (+#experiences+, +#feature_by_key(key)+, …) that
-  # return frozen sub-hashes / arrays. There is no public accessor for the raw
-  # snapshot and no OpenAPI codegen — the reader inventory is derived by hand
-  # from the actual config wire shape (the vendored +test-config.json+ fixture).
+  # The parsed config snapshot is exposed ONLY through hand-written reader methods
+  # (+#experiences+, +#feature_by_key(key)+, …) that return frozen sub-hashes /
+  # arrays. There is no public accessor for the raw snapshot and no OpenAPI codegen
+  # — the reader inventory is derived by hand from the actual config wire shape
+  # (the vendored +test-config.json+ fixture).
   #
-  # == Wire shape
+  # == Wire shape (flat/root — JS/PHP/Android parity)
   #
-  # The config envelope is +{"environment" => ..., "data" => {...}}+; the entity
-  # collections (+experiences+, +features+, +goals+, +audiences+, +segments+,
-  # optional +locations+) plus +account_id+ and the +project+ sub-hash live under
-  # +"data"+. +#project_id+ is +data.project.id+. Readers tolerate sparse or
-  # absent keys (return +nil+ / +[]+) so a partial config never crashes a reader.
+  # Entities live at the ROOT of the config snapshot: +account_id+, +project+,
+  # +experiences+, +features+, +goals+, +audiences+, +segments+,
+  # +archived_experiences+, and optional +locations+. +#project_id+ is
+  # +root["project"]["id"]+. This matches the live endpoint shape (no +"data"+
+  # wrapper), the JS SDK, the PHP SDK, and the Android OpenAPI-generated schema.
+  # Readers tolerate sparse or absent keys (return +nil+ / +[]+) so a partial
+  # config never crashes a reader.
   #
   # == Degrade-gracefully (NFR12)
   #
@@ -90,23 +92,27 @@ module ConvertSdk
     #   so a Context can supply its own resolution without re-reading config.
     # @param project_resolver [#call, nil] returns the project id for the visitor
     #   store key; defaults to {#project_id}.
+    # @param config_cache_disabled [Boolean] when true, {#cache_config} is a
+    #   no-op — the config-cache WRITE is suppressed. Ruby-SDK-only hardening
+    #   (qs-03, NOT a JS-parity concern): while a +debug_token+ is configured,
+    #   a shared store (e.g. Redis) must never be poisoned with a
+    #   debug-widened config that a production reader could later pick up.
+    #   Sourced by {ConvertSdk.build_data_manager} from +!config.debug_token.nil?+.
+    #   Defaults to +false+ (cache writes enabled) for standalone construction.
     def initialize(log_manager:, data_store_manager: nil, config_key: nil, ttl: nil,
                    clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }, refetch: nil,
                    bucketing_manager: nil, rule_manager: nil,
-                   account_resolver: nil, project_resolver: nil)
+                   account_resolver: nil, project_resolver: nil, config_cache_disabled: false)
       @log_manager = log_manager
       @data_store_manager = data_store_manager
       @config_key = config_key
       @ttl = ttl
+      @config_cache_disabled = config_cache_disabled
       # Timer-off (Lambda/CLI) mode is exactly "no refresh interval configured".
       @timer_off = ttl.nil?
       @clock = clock
       @refetch = refetch
-      # Decision-flow collaborators (Story 2.11). Config-read-only when absent.
-      @bucketing_manager = bucketing_manager
-      @rule_manager = rule_manager
-      @account_resolver = account_resolver || -> { account_id }
-      @project_resolver = project_resolver || -> { project_id }
+      assign_collaborators(bucketing_manager, rule_manager, account_resolver, project_resolver)
       # The deep-frozen config envelope, or nil before the first install. Read
       # lock-free by every reader; replaced atomically under @config_mutex.
       @config = nil #: Hash[String, untyped]?
@@ -138,8 +144,8 @@ module ConvertSdk
     # marker, so exactly one install in the manager's lifetime is +:first+ even
     # under concurrent installs.
     #
-    # @param hash [Hash{String=>Object}] the parsed config envelope
-    #   (+{"environment" => ..., "data" => {...}}+).
+    # @param hash [Hash{String=>Object}] the parsed flat config snapshot
+    #   (entities at the root — +account_id+, +project+, +experiences+, etc.).
     # @return [Symbol, false] +:first+ on the first successful install,
     #   +:updated+ on any subsequent install, or +false+ when the argument was
     #   rejected (non-Hash) and no swap happened.
@@ -223,22 +229,31 @@ module ConvertSdk
       (@clock.call - fetched_at) > effective_ttl
     end
 
-    # @return [Boolean] true once a config snapshot has been installed.
+    # @return [Boolean] true once a USABLE config (account_id + project.id both
+    #   present) is installed. Mirrors JS SDK's +isValidConfigData+ check
+    #   (+account_id && project.id+). A snapshot that carries a +project+ key but
+    #   no id (e.g. +project: {}+) or a malformed +project+ value is NOT considered
+    #   available — avoids silently serving nil reads to decision paths.
     def config_available?
-      !@config.nil?
+      !account_id.nil? && !project_id.nil?
     end
 
-    # @return [String, nil] the account id (+data.account_id+), or nil pre-config.
+    # @return [String, nil] the account id (+account_id+ at the config root), or nil pre-config.
     def account_id
       data&.fetch("account_id", nil)
     end
 
-    # @return [String, nil] the project id (+data.project.id+), or nil pre-config.
+    # @return [String, nil] the project id (+project.id+ at the config root), or nil pre-config.
+    #   Type-safe against a non-Hash +project+ value (e.g. a String in a malformed
+    #   direct-data config): +&.+ guards nil only; a non-nil non-Hash would raise
+    #   NoMethodError on +#fetch+. Mirrors JS optional-chaining safety
+    #   (+data?.project?.id+).
     def project_id
-      project&.fetch("id", nil)
+      p = project
+      p.is_a?(Hash) ? p.fetch("id", nil) : nil
     end
 
-    # @return [Hash, nil] the frozen +data.project+ sub-hash, or nil pre-config.
+    # @return [Hash, nil] the frozen +project+ sub-hash at the config root, or nil pre-config.
     def project
       data&.fetch("project", nil)
     end
@@ -280,6 +295,17 @@ module ConvertSdk
       find_by_key(experiences, key)
     end
 
+    # @param id [String] the experience +id+ to find (+to_s+ compared — ids may
+    #   arrive as Integer or String across the wire, e.g. a caller-supplied
+    #   +experience_id+ vs. the config's JSON-parsed +id+). Used by the qs-03
+    #   preview resolution ({Context#set_preview}) to look the previewed
+    #   experience up against the CURRENT installed config before falling back
+    #   to the +?exp=+ live fetch.
+    # @return [Hash, nil] the frozen experience with that id, or nil.
+    def experience_by_id(experience_id)
+      find_by_id(experiences, experience_id)
+    end
+
     # @param key [String] the feature +key+ to find.
     # @return [Hash, nil] the frozen feature with that key, or nil.
     def feature_by_key(key)
@@ -327,6 +353,32 @@ module ConvertSdk
       retrieve_bucketing(visitor_id, experience, attributes)
     end
 
+    # ============================ PREVIEW (qs-03) ===========================
+    # Force-decide a specific variation on a caller-supplied experience,
+    # bypassing the ENTIRE decision flow above: audiences, segments, locations,
+    # the environment check, experience status, variation status/traffic
+    # filters, stored decisions, and the bucketing hash. Mirrors JS
+    # data-manager.ts +getPreviewDecision+ (qs-03 / SDK-4).
+    #
+    # PURE by construction: reads ONLY +experience["variations"]+ (via
+    # {#retrieve_variation}) -- never the installed config -- because a preview
+    # experience fetched via +?exp=+ may not be registered there. Has ZERO side
+    # effects: never calls {#persist_bucketing} / +merge_visitor_data+ and never
+    # enqueues anything (this method has no store or transport collaborator to
+    # call in the first place).
+    #
+    # @param experience [Hash] the experience config entity to preview (may be
+    #   absent from the installed config).
+    # @param variation_id [String] the variation id to force (+to_s+ compared).
+    # @return [BucketedVariation, nil] the forced decision, or nil when
+    #   +variation_id+ does not match any variation on +experience+.
+    def get_preview_decision(experience, variation_id)
+      variation = retrieve_variation(experience, variation_id)
+      return nil if variation.nil?
+
+      build_bucketed_variation(experience, variation, nil)
+    end
+
     # ========================== CONVERSION TRACKING =========================
     # Track a conversion for +visitor_id+ on +goal_key+ with optional revenue /
     # transaction +goal_data+, applying two-level goal dedup (Story 4.3).
@@ -382,6 +434,17 @@ module ConvertSdk
 
     private
 
+    # Assign the decision-flow collaborators (Story 2.11) and their store-key
+    # resolvers — extracted from #initialize to keep it small. Collaborators
+    # are config-read-only when absent; resolvers default to this manager's
+    # own {#account_id} / {#project_id} readers when not injected.
+    def assign_collaborators(bucketing_manager, rule_manager, account_resolver, project_resolver)
+      @bucketing_manager = bucketing_manager
+      @rule_manager = rule_manager
+      @account_resolver = account_resolver || -> { account_id }
+      @project_resolver = project_resolver || -> { project_id }
+    end
+
     # The atomic check-then-mark (Story 4.3 / qs-01). Runs the dedup decision AND
     # the mark inside ONE store-merge block (the merge mutex). Returns true when
     # the caller should enqueue, false when the conversion is deduplicated.
@@ -465,6 +528,35 @@ module ConvertSdk
       bucketing.is_a?(Hash) ? bucketing : {}
     end
 
+    # qs-04 mutual-exclusion resolver builder: a per-call pure
+    # +->(target_experience_key) { true | false | nil }+ closure over
+    # +visitor_id+ ONLY (no global state, no cross-visitor memoization — a
+    # fresh lambda per {#match_rules_by_field} call) matching
+    # {RuleManager#is_rule_matched}'s +resolver:+ contract exactly.
+    #
+    # Resolution (the qs-04 normative algorithm):
+    #   target       = config experience whose key == target_experience_key
+    #   bucketed_raw = target exists AND the visitor's stored bucketing map
+    #                  contains an entry for target["id"].to_s
+    #
+    # Both reads are pure: {#experience_by_key} reads the frozen installed
+    # config; {#stored_bucketing_map} reads the visitor's StoreData via the
+    # store seam. Neither ever triggers bucketing of the target
+    # (BucketingManager is never called here), never writes (no
+    # +merge_visitor_data+), and never tracks — the AC5 read-only invariant.
+    #
+    # @return [Proc] +nil+ from the built lambda means "target key
+    #   unresolvable" — RuleManager itself logs the AC8 warning naming the key
+    #   and applies negation around a +bucketed_raw = false+.
+    def mutual_exclusion_resolver(visitor_id)
+      lambda do |target_experience_key|
+        target = experience_by_key(target_experience_key)
+        next nil if target.nil?
+
+        stored_bucketing_map(visitor_id).key?(target["id"].to_s)
+      end
+    end
+
     # Steps 1-7: resolve the experience and run every eligibility gate up to (but
     # not including) traffic allocation. Returns the matched experience Hash, a
     # {Sentinel} (a propagated {RuleError} from a rule walk), or +nil+ (a plain
@@ -484,7 +576,11 @@ module ConvertSdk
       return reason_miss(experience, "location not match") unless location_outcome
 
       # Step 6 — audiences (permanent skipped when bucketed; transient always).
-      audiences_outcome = match_audiences(experience, attributes[:visitor_properties], is_bucketed)
+      # qs-04: build the mutual-exclusion resolver here (visitor_id is in scope)
+      # and thread it down through match_audiences -> matched_audiences ->
+      # RuleManager#is_rule_matched — the ONLY site that builds it.
+      resolver = mutual_exclusion_resolver(visitor_id)
+      audiences_outcome = match_audiences(experience, attributes[:visitor_properties], is_bucketed, resolver)
       return audiences_outcome if audiences_outcome.is_a?(Sentinel)
 
       # Step 7 — custom segments. Both must pass to reach variation selection.
@@ -555,8 +651,7 @@ module ConvertSdk
     # No covering bucket OR a drifted-out selected id -> VARIATION_NOT_DECIDED.
     def bucket_fresh(visitor_id, experience, attributes)
       experience_id = experience["id"].to_s
-      buckets = build_buckets(experience)
-      decision = @bucketing_manager&.bucket_for_visitor(buckets, visitor_id, experience_id: experience_id)
+      decision = fresh_bucketing_decision(visitor_id, experience, experience_id)
       variation_id = decision&.fetch(:variation_id, nil)
       variation = variation_id && retrieve_variation(experience, variation_id)
       if variation.nil?
@@ -569,6 +664,37 @@ module ConvertSdk
       build_bucketed_variation(experience, variation, decision&.fetch(:bucketing_allocation, nil))
     end
 
+    # qs-01 (bucketing contract v12) anchored-vs-packed GATE. Mirrors the JS
+    # reference's +Number(experience.version) > 11+ (data-manager.ts:695) via
+    # +Float(x, exception: false)+ coercion: a numeric-looking String (e.g.
+    # +"12"+) counts as anchored exactly like the JS oracle, not just a
+    # genuine +Numeric+. Missing / nil / genuinely non-numeric (e.g.
+    # +"twelve"+) / <= 11 all coerce to +nil+ or a value <= 11 and take the
+    # EXISTING packed walk, byte-for-byte unchanged (+build_buckets+ +
+    # +bucket_for_visitor+, both untouched by this story). The anchored branch
+    # is fed the FULL ordered {#variation_list} (inactive arms retained for
+    # anchor stability) — never {#build_buckets}, which drops inactive arms
+    # for the packed walk.
+    #
+    # Hard boundary (documented, not fixable in Ruby): +JSON.parse+ collapses
+    # an explicit JSON +null+ version and an ABSENT version to the same Ruby
+    # +nil+, so this SDK cannot reproduce a JS split between the two (JS:
+    # absent -> +undefined+ -> +Number(undefined)+ is +NaN+ -> packed;
+    # explicit +null+ -> +Number(null)+ is +0+ -> also packed here, so the two
+    # actually agree for this field). Never served in practice regardless.
+    def fresh_bucketing_decision(visitor_id, experience, experience_id)
+      version = Float(experience["version"], exception: false)
+      anchored = !version.nil? && version > 11
+      if anchored
+        @bucketing_manager&.bucket_for_visitor_anchored(
+          variation_list(experience), visitor_id, experience_id: experience_id
+        )
+      else
+        buckets = build_buckets(experience)
+        @bucketing_manager&.bucket_for_visitor(buckets, visitor_id, experience_id: experience_id)
+      end
+    end
+
     # True when +experience.id+ is in the archived-experiences list (to_s match).
     def archived?(experience)
       id = experience["id"].to_s
@@ -642,7 +768,7 @@ module ConvertSdk
     # re-evaluated. +matching_options.audiences == "all"+ requires every checked
     # audience to match; otherwise any match suffices. Returns true/false or a
     # propagated {RuleError} sentinel. Mirrors JS data-manager.ts:350-416.
-    def match_audiences(experience, visitor_properties, is_bucketed)
+    def match_audiences(experience, visitor_properties, is_bucketed, resolver)
       # JS parity (data-manager.ts:356-416): +audiencesMatched+ defaults to FALSE
       # and is only ever set true INSIDE +if (visitorProperties)+. A nil/absent
       # visitor-properties bag therefore GATES the experience (false), even when
@@ -654,7 +780,7 @@ module ConvertSdk
       to_check = audiences_to_check(experience, is_bucketed)
       return true if to_check.empty? # unrestricted (no audiences, or all permanent+bucketed)
 
-      matched = matched_audiences(to_check, visitor_properties)
+      matched = matched_audiences(to_check, visitor_properties, resolver)
       return matched if matched.is_a?(Sentinel)
 
       audiences_verdict?(experience, matched, to_check)
@@ -679,12 +805,17 @@ module ConvertSdk
 
     # Walk each checked audience's rules; collect the matches. A propagated
     # {RuleError} sentinel from any walk short-circuits and is returned as-is.
-    def matched_audiences(to_check, visitor_properties)
+    # qs-04: +resolver+ is threaded unchanged into {RuleManager#is_rule_matched}
+    # — consulted ONLY by a +bucketed_into_experience_key+ leaf; every other
+    # leaf (the 3 generic rule types, AC7) ignores it, byte-identical to before.
+    def matched_audiences(to_check, visitor_properties, resolver)
       matched = [] #: Array[Hash[String, untyped]]
       to_check.each do |audience|
         next unless audience["rules"]
 
-        result = @rule_manager&.is_rule_matched(visitor_properties, audience["rules"], "audience ##{audience["id"]}")
+        result = @rule_manager&.is_rule_matched(
+          visitor_properties, audience["rules"], "audience ##{audience["id"]}", resolver: resolver
+        )
         return result if result.is_a?(Sentinel)
 
         matched << audience if result == true
@@ -770,7 +901,17 @@ module ConvertSdk
     # (atomic merge via DataStoreManager). Optionally also stores visitor
     # properties as segments (JS updateVisitorProperties path). In-memory store
     # ops only (NFR1; user-supplied Redis trades the no-disk contract).
+    #
+    # +attributes[:enable_storage]+ (qs-03 / RB-6 zero-trace) gates this write:
+    # a preview {Context} threads +enable_storage: false+ through
+    # {Context#decision_attributes} for the ENTIRE call (target AND other
+    # experiences), so a fresh decision made while previewing is never
+    # persisted. Absent (or any non-false value) defaults to +true+ — every
+    # existing non-preview caller (including direct {#get_bucketing} unit
+    # calls with a bare +{}+ attributes hash) is unaffected.
     def persist_bucketing(visitor_id, experience_id, variation_id, attributes)
+      return unless attributes.fetch(:enable_storage, true)
+
       manager = @data_store_manager
       return if manager.nil?
 
@@ -829,9 +970,14 @@ module ConvertSdk
 
     # Write the freshly-installed config through to the store, wrapped with a
     # WALL-CLOCK +fetched_at+ for cross-process staleness. A no-op when no store
-    # or key is wired (standalone unit construction). The DataStoreManager
-    # contains any store failure (logged), so this never crashes an install.
+    # or key is wired (standalone unit construction), or when
+    # +config_cache_disabled+ was set at construction (qs-03 — an active
+    # +debug_token+ suppresses the write so a shared store is never poisoned
+    # with a debug-widened config). The DataStoreManager contains any store
+    # failure (logged), so this never crashes an install.
     def cache_config(frozen)
+      return if @config_cache_disabled
+
       store = @data_store_manager
       key = @config_key
       return if store.nil? || key.nil?
@@ -856,13 +1002,14 @@ module ConvertSdk
       @ttl || ConvertSdk::DEFAULT_CONFIG_TTL
     end
 
-    # The frozen +"data"+ sub-hash of the live snapshot, or nil pre-config.
-    # Read lock-free: @config is either nil or a fully-frozen graph.
+    # The live snapshot root (entities live at the root — JS/PHP/Android parity),
+    # or nil pre-config. Read lock-free: @config is either nil or a fully-frozen
+    # graph.
     def data
-      @config&.fetch("data", nil)
+      @config
     end
 
-    # Fetch a frozen collection under +"data"+, defaulting to a frozen empty
+    # Fetch a frozen collection at the config root, defaulting to a frozen empty
     # array when the snapshot or the key is absent.
     def collection(name)
       found = data&.fetch(name, nil)
@@ -875,6 +1022,14 @@ module ConvertSdk
       list.find { |entity| entity.is_a?(Hash) && entity["key"] == key }
     end
 
+    # Linear scan for the entity whose +"id"+ +to_s+-matches +id+. Mirrors
+    # {#find_by_key}; +to_s+ comparison because ids may arrive as different
+    # types across the wire (JSON Integer vs. a caller-supplied String).
+    def find_by_id(list, entity_id)
+      target = entity_id.to_s
+      list.find { |entity| entity.is_a?(Hash) && entity["id"].to_s == target }
+    end
+
     # Build a recursively-frozen copy of +node+. Hashes and arrays are rebuilt
     # with frozen children then frozen; strings are duped-and-frozen; immutable
     # scalars (Integer/Float/Symbol/true/false/nil) pass through unchanged. The

data/lib/convert_sdk/redactor.rb

@@ -31,9 +31,11 @@ module ConvertSdk
     # The single-character ellipsis appended after the unmasked prefix (or used
     # as the whole replacement for short secrets).
     MASK_GLYPH = "…"
-    # Matches an +http(s)+ URL's query string: a +?+ and everything up to the
-    # next whitespace. The query is stripped; the path is kept.
-    URL_QUERY_PATTERN = %r{(https?://\S*?)\?\S*}
+    # Matches an +http(s)+ URL up to the next whitespace. +strip_url_queries+
+    # then drops the +?query+ portion in code, keeping the path. A single
+    # trailing quantifier (no quantifier competing after +https?://+) keeps the
+    # match linear — no polynomial backtracking on repeated +http://+ prefixes.
+    URL_QUERY_PATTERN = %r{https?://\S*}
 
     # @param secrets [Array<String, nil>] secret values to mask. nil/blank
     #   entries are ignored.
@@ -87,7 +89,7 @@ module ConvertSdk
 
     # Drop the query string from any URL in the message, keeping the path.
     def strip_url_queries(message)
-      message.gsub(URL_QUERY_PATTERN, '\1')
+      message.gsub(URL_QUERY_PATTERN) { |url| url.split("?", 2).first }
     end
   end
 end

data/lib/convert_sdk/rule_manager.rb

@@ -65,9 +65,17 @@ module ConvertSdk
     # @param data [Hash{String=>Object}] the key-value data to match.
     # @param rule_set [Hash] the OR/AND/OR_WHEN rule structure.
     # @param log_entry [String, nil] an optional label for the entity being matched.
+    # @param resolver [Proc, nil] qs-04 mutual-exclusion resolver:
+    #   +->(target_experience_key) { true | false | nil }+. Threaded unchanged
+    #   through the whole walk and consulted ONLY by a
+    #   +bucketed_into_experience_key+ leaf ({#process_rule_item}); every other
+    #   leaf ignores it. +nil+ (no resolver injected at all) makes such a leaf
+    #   fall closed to +false+ with negation unapplied; a resolver that itself
+    #   returns +nil+ for an unresolvable target key is treated as
+    #   +bucketed_raw = false+ plus a warning naming the key.
     # @return [Boolean, Sentinel] true/false, or a {RuleError} sentinel propagated
     #   from a leaf.
-    def is_rule_matched(data, rule_set, log_entry = nil)
+    def is_rule_matched(data, rule_set, log_entry = nil, resolver: nil)
       or_groups = nonempty_block(rule_set, "OR")
       unless or_groups
         warn_rule_not_valid("RuleManager#is_rule_matched", log_entry)
@@ -76,7 +84,7 @@ module ConvertSdk
 
       match = false
       or_groups.each do |and_group|
-        match = process_and(data, and_group)
+        match = process_and(data, and_group, resolver)
         return true if match == true
 
         log_outcome("RuleManager#is_rule_matched", match, log_entry)
@@ -90,7 +98,7 @@ module ConvertSdk
 
     # AND block: every OR_WHEN leaf-list must return true. Returns the first
     # non-true result (false or a sentinel short-circuits). rule-manager.ts:191-220.
-    def process_and(data, and_group)
+    def process_and(data, and_group, resolver)
       leaves = nonempty_block(and_group, "AND")
       unless leaves
         warn_rule_not_valid("RuleManager#process_and")
@@ -98,7 +106,7 @@ module ConvertSdk
       end
 
       leaves.each do |or_when|
-        match = process_or_when(data, or_when)
+        match = process_or_when(data, or_when, resolver)
         return match if match != true
       end
       @log_manager&.debug("RuleManager#process_and: AND block matched")
@@ -107,7 +115,7 @@ module ConvertSdk
 
     # OR_WHEN block: the first matching leaf wins. After the loop, returns the
     # last result unless false (so a sentinel propagates). rule-manager.ts:229-255.
-    def process_or_when(data, or_when)
+    def process_or_when(data, or_when, resolver)
       leaves = nonempty_block(or_when, "OR_WHEN")
       unless leaves
         warn_rule_not_valid("RuleManager#process_or_when")
@@ -116,7 +124,7 @@ module ConvertSdk
 
       match = false
       leaves.each do |rule|
-        match = process_rule_item(data, rule)
+        match = process_rule_item(data, rule, resolver)
         return true if match == true
       end
       return match if match != false
@@ -124,11 +132,20 @@ module ConvertSdk
       false
     end
 
-    # A single leaf rule. Validates shape, resolves the operator from the
-    # comparison processor's dispatch map, and evaluates it against the matching
-    # data value — or against {Comparisons::UNDEFINED} for an absent key under an
-    # existence operator. rule-manager.ts:264-365.
-    def process_rule_item(data, rule)
+    # A single leaf rule. A +bucketed_into_experience_key+ leaf (qs-04 mutual
+    # exclusion) is dispatched to {#process_mutual_exclusion_rule} BEFORE the
+    # generic shape validation / comparison-operator dispatch below — it never
+    # consults +match_type+ or +@comparisons+ (vestigial for this rule_type).
+    # Every other leaf takes the unchanged generic path: validates shape,
+    # resolves the operator from the comparison processor's dispatch map, and
+    # evaluates it against the matching data value — or against
+    # {Comparisons::UNDEFINED} for an absent key under an existence operator.
+    # rule-manager.ts:264-365.
+    def process_rule_item(data, rule, resolver)
+      if rule.is_a?(Hash) && rule["rule_type"] == "bucketed_into_experience_key"
+        return process_mutual_exclusion_rule(rule, resolver)
+      end
+
       unless valid_rule?(rule)
         warn_rule_not_valid("RuleManager#process_rule_item")
         return false
@@ -147,6 +164,48 @@ module ConvertSdk
       evaluate_leaf(data, rule, match_type, method, negation)
     end
 
+    # The qs-04 mutual-exclusion leaf (+bucketed_into_experience_key+): resolves
+    # against the injected +resolver+ — a pure +->(target_experience_key) { true
+    # | false | nil }+ function of the target key — never against
+    # +@comparisons+; +match_type+ is vestigial and is never consulted for this
+    # rule_type.
+    #
+    # * No resolver threaded through the call at all (+resolver+ is +nil+):
+    #   fail closed to +false+, negation UNAPPLIED (the capability is entirely
+    #   absent, distinct from "resolver present but target unknown" below).
+    # * Resolver present, target key unresolvable (+resolver.call+ returns
+    #   +nil+): warn naming the unresolved key, treat +bucketed_raw+ as +false+,
+    #   THEN apply negation like any other known outcome.
+    # * Resolver present, target key resolved to +true+/+false+: that is
+    #   +bucketed_raw+; negation applies on top of it as usual.
+    # * +rule["matching"]+ is malformed — a non-Hash, non-+nil+ value (e.g. a
+    #   stray +match_type+ string) OR the +matching+ key missing entirely: this
+    #   leaf skips +valid_rule?+ (unlike the generic path), so the malformed
+    #   shape is guarded here directly. Fails closed to +false+, negation
+    #   UNAPPLIED, and the resolver is NEVER invoked — mirrors the "no resolver
+    #   injected" case's fail-closed spirit for a leaf that cannot be trusted.
+    def process_mutual_exclusion_rule(rule, resolver)
+      return false unless resolver
+
+      matching = rule["matching"]
+      return false unless matching.is_a?(Hash)
+
+      negated = matching["negated"] || false
+      target_key = rule["value"]
+      raw = resolver.call(target_key)
+
+      if raw.nil?
+        @log_manager&.warn(
+          "RuleManager#process_mutual_exclusion_rule: unresolved mutual-exclusion target #{target_key.inspect}"
+        )
+        bucketed_raw = false
+      else
+        bucketed_raw = raw == true
+      end
+
+      negated ? !bucketed_raw : bucketed_raw
+    end
+
     # Resolve the data value for the leaf's key and invoke the operator. Iterates
     # the data keys honoring +keys_case_sensitive+; on a key match invokes the
     # operator with the data value. On no key match, an existence operator is

data/lib/convert_sdk/segments_manager.rb

@@ -44,6 +44,16 @@ module ConvertSdk
   # (Story 2.1) into +StoreData["segments"]+. Stored data is string-keyed
   # wire-world by design (so Epic 4's payload builder needs zero translation).
   #
+  # == Zero-trace preview gate (qs-03 / RB-6)
+  #
+  # {#put_segments} and {#select_custom_segments} accept an +enable_storage:+
+  # keyword (default +true+) that suppresses ONLY the persistence write above —
+  # filtering / rule MATCHING is never affected. {Context#set_default_segments}
+  # and {Context#run_custom_segments} thread +!@preview+ through it so a
+  # preview-active context leaves zero trace in the store while still
+  # evaluating segment rules normally (mirrors JS SDK-6,
+  # +segments-manager.ts:74-174+).
+  #
   # @api private
   class SegmentsManager
     # The +customSegments+ wire key — byte-identical to JS
@@ -89,12 +99,18 @@ module ConvertSdk
     #
     # @param visitor_id [String]
     # @param segments [Hash] the candidate report-segments (string-keyed wire shape).
+    # @param enable_storage [Boolean] when +false+, suppress ONLY the persistence
+    #   write below — the filtering above still runs identically. Threaded by
+    #   {Context#set_default_segments} as +!@preview+ (qs-03 / RB-6 zero-trace);
+    #   mirrors JS +SegmentsManager#putSegments+'s +enableStorage+ param
+    #   (JS SDK-6, +segments-manager.ts:74-89+). Defaults to +true+ (every
+    #   pre-qs-03 caller is unaffected).
     # @return [void]
-    def put_segments(visitor_id, segments)
+    def put_segments(visitor_id, segments, enable_storage: true)
       report_segments = filter_report_segments(segments)
       return if report_segments.empty?
 
-      merge_segments(visitor_id, report_segments)
+      merge_segments(visitor_id, report_segments) if enable_storage
       nil
     end
 
@@ -113,11 +129,17 @@ module ConvertSdk
     # @param segment_rule [Hash, nil] the visitor data the segment rules match
     #   against; +nil+ attaches every resolved segment unconditionally (JS:
     #   +if (!segmentRule || segmentsMatched)+).
+    # @param enable_storage [Boolean] when +false+, suppress ONLY the eventual
+    #   {#put_segments} persistence write — rule MATCHING (and a propagated
+    #   {RuleError}) is unaffected. Threaded by {Context#run_custom_segments} as
+    #   +!@preview+ (qs-03 / RB-6 zero-trace); mirrors JS
+    #   +SegmentsManager#selectCustomSegments+'s +enableStorage+ param
+    #   (JS SDK-6, +segments-manager.ts:156-174+). Defaults to +true+.
     # @return [Hash, Sentinel, nil] the updated segments hash, a propagated
     #   {RuleError}, or +nil+ when nothing matched.
-    def select_custom_segments(visitor_id, segment_keys, segment_rule = nil)
+    def select_custom_segments(visitor_id, segment_keys, segment_rule = nil, enable_storage: true)
       segments = lookup_segments(segment_keys)
-      set_custom_segments(visitor_id, segments, segment_rule)
+      set_custom_segments(visitor_id, segments, segment_rule, enable_storage: enable_storage)
     end
 
     private
@@ -163,8 +185,9 @@ module ConvertSdk
     # For each resolved segment: when a rule is supplied and nothing has matched
     # yet, walk the segment's rules — a {RuleError} sentinel short-circuits and
     # propagates out. On a match (or when no rule was supplied) append the segment
-    # id unless already stored. A non-empty append is persisted via {#put_segments}.
-    def set_custom_segments(visitor_id, segments, segment_rule)
+    # id unless already stored. A non-empty append is persisted via {#put_segments}
+    # (gated on +enable_storage+ — see {#select_custom_segments}).
+    def set_custom_segments(visitor_id, segments, segment_rule, enable_storage: true)
       existing = stored_custom_segments(visitor_id)
       segment_ids = [] #: Array[String]
       matched = false #: (bool | Sentinel)
@@ -180,7 +203,7 @@ module ConvertSdk
         append_segment_id(segment, existing, segment_ids)
       end
 
-      persist_custom_segments(visitor_id, existing, segment_ids)
+      persist_custom_segments(visitor_id, existing, segment_ids, enable_storage: enable_storage)
     end
 
     # Append +segment["id"]+ (stringified) to the pending list unless it is already
@@ -199,15 +222,16 @@ module ConvertSdk
 
     # Persist the newly-matched ids (appended to the existing list) into
     # +StoreData["segments"]["customSegments"]+, or no-op + debug when nothing
-    # matched (JS +SEGMENTS_NOT_FOUND+). Returns the persisted segments hash or nil.
-    def persist_custom_segments(visitor_id, existing, segment_ids)
+    # matched (JS +SEGMENTS_NOT_FOUND+). Returns the persisted segments hash or
+    # nil. +enable_storage+ passes straight through to {#put_segments}.
+    def persist_custom_segments(visitor_id, existing, segment_ids, enable_storage: true)
       if segment_ids.empty?
         @log_manager&.debug("SegmentsManager#set_custom_segments: no segments matched")
         return nil
       end
 
       segments_data = { CUSTOM_SEGMENTS => existing + segment_ids }
-      put_segments(visitor_id, segments_data)
+      put_segments(visitor_id, segments_data, enable_storage: enable_storage)
       segments_data
     end
 

data/lib/convert_sdk/version.rb

@@ -10,5 +10,5 @@ module ConvertSdk
   # derives its version from this run's git tag, not from this file (FR66).
   # Mirrors the Android SDK's `0.0.0` placeholder in gradle/libs.versions.toml.
   # @return [String]
-  VERSION = "1.0.0"
+  VERSION = "2.0.0"
 end