convert_sdk 1.0.1 → 2.1.0

data/lib/convert_sdk/context.rb

@@ -46,6 +46,29 @@ module ConvertSdk
   # (+nil+ for lookups, +self+ for the chainable mutator). A raising collaborator
   # degrades the call; it never crashes the host request.
   class Context
+    # The reserved keys the public per-call hash accepts (CAP-3): a +:merged_map+ row
+    # lands in the engine envelope at +destination+, a +:raw_per_call+ row in that reader.
+    RESERVED_KEYS = {
+      "location_properties" => { source: :merged_map, destination: :location_properties,
+                                 scope: "every decision entry point" },
+      "environment" => { source: :merged_map, destination: :environment,
+                         scope: "every decision entry point" },
+      "enable_tracking" => { source: :raw_per_call, destination: :tracking_enabled_for_call,
+                             scope: "honoured on run_experience(s), accepted inert on run_feature(s)" },
+      "experience_keys" => { source: :raw_per_call, destination: :experiences,
+                             scope: "run_feature(s) only; narrows the experiences decided (CAP-1)" },
+      "type_casting" => { source: :raw_per_call, destination: :type_casting,
+                          scope: "run_feature(s) only; false returns the config-stored variables (CAP-2)" },
+      "ruleData" => { source: :raw_per_call, destination: :visitor_properties,
+                      scope: "run_custom_segments only; camelCase on a snake_case surface (SD-4)" }
+    }.freeze
+
+    # Engine-readable keys the seam never lifts, each with its reason (CAP-3's negative list).
+    NOT_LIFTED = {
+      "enable_storage" => "preview owns the persistence gate (D-4)",
+      "update_visitor_properties" => "documented Ruby divergence (D-5)"
+    }.freeze
+
     # @param visitor_id [String] the resolved visitor id (validated non-blank by
     #   {Client#create_context} before construction).
     # @param attributes [Hash, nil] the per-visitor attributes; deep-stringified
@@ -86,6 +109,11 @@ module ConvertSdk
       # Deep-stringify the caller's attributes ONCE at the boundary; internals
       # only ever see string keys. nil → empty. The caller's hash is never mutated.
       @attributes = deep_stringify(attributes || {})
+      # qs-03 (RB-5) preview state — nil until {#set_preview} succeeds. A plain
+      # per-instance ivar (never a class/shared variable): two Contexts NEVER
+      # share this (AC7 isolation). Shape: +{experience_id:, variation_id:,
+      # experience:, experience_key:}+.
+      @preview = nil #: Hash[Symbol, untyped]?
     end
 
     # @return [String] the visitor id this context is bound to.
@@ -105,12 +133,25 @@ module ConvertSdk
     # +{segments: props}+ — +context.ts:482+). The merge is atomic per visitor:
     # the read-modify-write runs inside the store manager's merge mutex.
     #
+    # == Zero-trace under preview (qs-03 AC6, RB-6)
+    #
+    # On a preview-active context ONLY the store write below is skipped — the
+    # in-memory +@attributes+ merge always applies (JS parity: JS's public
+    # +updateVisitorProperties+ has no preview guard of its own, but the
+    # PRIVATE helper it calls to persist DOES skip entirely under preview —
+    # +context.ts:626-629+, +if (this._preview) return;+ — leaving the
+    # in-memory side unaffected there too). "Per-context scratch" per the
+    # qs-03 spec: a later decision on THIS context still sees the merge; no
+    # trace of it ever reaches the store.
+    #
     # @param properties [Hash] the properties to merge (symbol or string keys).
     # @return [self]
     def update_visitor_properties(properties)
       normalised = deep_stringify(properties || {})
-      @data_store_manager.merge_visitor_data(account_key, project_key, @visitor_id) do |_current|
-        { "segments" => normalised }
+      if @preview.nil?
+        @data_store_manager.merge_visitor_data(account_key, project_key, @visitor_id) do |_current|
+          { "segments" => normalised }
+        end
       end
       @attributes = @attributes.merge(normalised)
       self
@@ -170,6 +211,79 @@ module ConvertSdk
       nil
     end
 
+    # Force a specific variation of an experience for THIS context — bypassing
+    # audiences, segments, locations, the environment check, experience status,
+    # variation status/traffic filters, stored decisions, and the bucketing
+    # hash for that experience only (qs-03 AC4/AC5). Mirrors JS
+    # +Context#setPreview+ (+context.ts:143-205+); this Ruby surface is
+    # synchronous — the +?exp=+ fallback fetch runs through
+    # {ApiManager#get_config_by_experience}, itself process-wide memoized for
+    # 60s (qs-03 AC8), so no async/await equivalent is needed here.
+    #
+    # == Resolution
+    #
+    # The CURRENT installed config is tried first, by id
+    # ({DataManager#experience_by_id}); when absent, a live
+    # +?exp={experience_id}+ fetch resolves it instead (never touches the
+    # installed config or the store — a previewed experience may be draft/
+    # paused and must never be cached alongside production config). The
+    # resolved experience is held BY REFERENCE, never duped or rebuilt:
+    # DataManager's installed config entities are already deep-frozen (Story
+    # 2.7), so simply holding the reference carries none of the JS SDK-7
+    # in-place-mutation risk (mutating a frozen Ruby Hash raises
+    # +FrozenError+ rather than silently corrupting shared state); a fetched
+    # experience is a brand-new object that is never installed anywhere, so it
+    # is never shared to begin with.
+    #
+    # == Inert on bad input (AC7)
+    #
+    # A blank +experience_id+/+variation_id+, an unresolvable experience
+    # (absent from both the installed config and the +?exp=+ fetch response),
+    # or an unknown +variation_id+ on the resolved experience all leave preview
+    # state UNSET (a +warn+ log, never a raise) — a subsequent
+    # {#run_experience} on this context decides exactly as if this method had
+    # never been called.
+    #
+    # == Isolation (AC7)
+    #
+    # Preview state lives on THIS +Context+ instance only (a plain ivar) — two
+    # +Context+s, even for the same client/config, never share it.
+    #
+    # Never raises into the host: an internal failure degrades to an +error+
+    # log + leaves preview state unset (NFR9).
+    #
+    # @param experience_id [String] the previewed experience's +id+.
+    # @param variation_id [String] the variation +id+ to force.
+    # @return [self]
+    def set_preview(experience_id:, variation_id:)
+      return warn_preview_inert("experience_id/variation_id required") if blank?(experience_id) || blank?(variation_id)
+
+      # Coerce ONCE at this public entry (review round 2) — ids may arrive as
+      # different types (an Integer id read straight off a link param, a
+      # String elsewhere); every downstream reference (resolution, the
+      # decision lookup, the stored @preview hash) threads these coerced
+      # locals instead of the original keyword args, mirroring
+      # {#fetch_preview_experience}'s existing "ids may arrive as different
+      # types" +.to_s+ convention.
+      exp_id = experience_id.to_s
+      var_id = variation_id.to_s
+
+      experience = resolve_preview_experience(exp_id)
+      return warn_preview_inert("no experience found for id=#{exp_id}", clear: true) if experience.nil?
+
+      decision = @data_manager.get_preview_decision(experience, var_id)
+      return warn_preview_inert("no variation found for id=#{var_id}", clear: true) if decision.nil?
+
+      @preview = {
+        experience_id: exp_id, variation_id: var_id,
+        experience: experience, experience_key: experience["key"]
+      }
+      self
+    rescue StandardError => e
+      @log_manager.error("Context#set_preview: #{e.class}: #{e.message}")
+      self
+    end
+
     # Decide a single experience for this visitor and return its variation.
     #
     # The optional per-call +attributes+ are deep-stringified and merged OVER the
@@ -197,6 +311,29 @@ module ConvertSdk
     # NO bucketing event is enqueued (a +debug+ line records the suppression). The
     # global Config +tracking: false+ switch ALWAYS wins over a per-call +true+.
     #
+    # == Preview forcing (qs-03 AC4/AC5)
+    #
+    # When {#set_preview} has forced a variation for THIS +key+ on this context,
+    # that forced decision is returned DIRECTLY — bypassing decisioning entirely
+    # (no audience/location/environment/status/traffic/stored-decision/bucketing
+    # walk) and firing NO {SystemEvents::BUCKETING} event (mirrors JS
+    # +context.ts:228-235+). Because this check runs FIRST, it naturally takes
+    # precedence over a stored decision or fresh bucketing for that experience;
+    # every OTHER experience on this same context still decides normally.
+    #
+    # == Zero-trace on OTHER experiences under preview (qs-03 AC6, RB-6)
+    #
+    # When THIS context has a preview active but +key+ is NOT the previewed
+    # experience, decisioning proceeds NORMALLY — only tracking/persistence are
+    # suppressed: {#decision_attributes} threads +enable_storage: false+ so
+    # {DataManager#persist_bucketing} never writes sticky StoreData, and the
+    # per-call tracking verdict is forced +false+ so {#fire_bucketing}'s
+    # {#suppress_bucketing_enqueue?} skips the outbound enqueue.
+    # {#fire_bucketing} ALSO suppresses the in-process {SystemEvents::BUCKETING}
+    # lifecycle-event fire while a preview is active on this context (JS parity
+    # — +context.ts:260+: +if (!this._preview) { fire BUCKETING }+). No event
+    # fires for any experience on a preview-active context.
+    #
     # @param key [String] the experience +key+.
     # @param attributes [Hash, nil] optional per-call visitor properties merged
     #   over the context attributes (deep-stringified). May carry +:enable_tracking+.
@@ -205,9 +342,13 @@ module ConvertSdk
       manager = @experience_manager
       return RuleError::NO_DATA_FOUND if manager.nil?
 
+      preview = @preview
+      return forced_preview_variation(preview) if preview && key == preview[:experience_key]
+
       @data_manager.ensure_fresh_config!
       variation = manager.select_variation(@visitor_id, key, decision_attributes(attributes))
-      fire_bucketing(key, variation, track: tracking_enabled_for_call?(attributes)) unless variation.is_a?(Sentinel)
+      track = preview.nil? && tracking_enabled_for_call?(attributes)
+      fire_bucketing(key, variation, track: track) unless variation.is_a?(Sentinel)
       variation
     rescue StandardError => e
       @log_manager.error("Context#run_experience: #{e.class}: #{e.message}")
@@ -230,6 +371,22 @@ module ConvertSdk
     # enqueue for THIS call (decisioning + sticky writes unaffected); the global
     # Config +tracking: false+ switch always wins (Story 4.5).
     #
+    # On a preview-active context (qs-03 AC6, RB-6) the previewed experience is
+    # FORCED to its preview variation here too — run-all forcing is API-agnostic,
+    # matching {#run_experience} and the PHP/Android/Python/iOS SDKs. Its
+    # normally-decided entry is dropped and the forced variation appended (or
+    # appended outright when the previewed experience is absent from the run-all
+    # set, e.g. a draft resolved only via +?exp=+); the forced entry fires no
+    # {SystemEvents::BUCKETING} event, exactly as {#run_experience}'s forced
+    # branch returns before {#fire_bucketing}. Every OTHER decided variation is
+    # zero-trace like {#run_experience}'s other-experience branch:
+    # {#decision_attributes} suppresses the sticky persist, the tracking verdict
+    # is forced +false+ so the outbound enqueue is skipped, and
+    # {#fire_bucketing}'s +@preview.nil?+ guard suppresses the
+    # {SystemEvents::BUCKETING} event as well — NO event fires for ANY
+    # experience on a preview-active context (JS parity — +context.ts:260+:
+    # +if (!this._preview) { fire BUCKETING }+).
+    #
     # @param attributes [Hash, nil] optional per-call visitor properties merged
     #   over the context attributes (deep-stringified). May carry +:enable_tracking+.
     # @return [Array<BucketedVariation>] the frozen variations (misses excluded).
@@ -239,6 +396,9 @@ module ConvertSdk
 
       @data_manager.ensure_fresh_config!
       variations = manager.select_variations(@visitor_id, decision_attributes(attributes))
+      preview = @preview
+      return force_preview_in_run_all(variations, preview) if preview
+
       track = tracking_enabled_for_call?(attributes)
       variations.each { |variation| fire_bucketing(variation.experience_key, variation, track: track) }
       variations
@@ -268,23 +428,30 @@ module ConvertSdk
     #     render_legacy_checkout
     #   end
     #
-    # NOTE (accepted parity break): JS +runFeature+ accepts an optional
-    # +experienceKeys+ filter argument; this Ruby surface intentionally OMITS it
-    # (deferred feature). Resolution always spans all configured experiences.
+    # A per-call +experience_keys+ Array narrows which experiences are decided,
+    # and so which sticky assignments the read commits (CAP-1); absent, nil or
+    # empty decides every configured experience (D-6).
+    # A per-call +type_casting+ of +false+ returns variables as config stores them (CAP-2).
+    #
+    # NOTE (accepted parity break): +type_casting: nil+ leaves casting ON here,
+    # where the JS presence-based rule would disable it (D-8).
     #
     # Never raises into the host: an internal failure degrades to a DISABLED
     # {BucketedFeature} (carrying the requested key) + an +error+ log (NFR9).
     #
     # @param key [String] the feature +key+ to evaluate.
-    # @param attributes [Hash, nil] optional per-call visitor properties merged
-    #   over the context attributes (deep-stringified).
+    # @param attributes [Hash, nil] optional per-call visitor properties merged over
+    #   the context attributes (deep-stringified). May carry +:experience_keys+
+    #   (CAP-1) and +:type_casting+ (CAP-2); only a boolean +false+ disables casting (D-8).
     # @return [BucketedFeature, Array<BucketedFeature>] the resolved feature(s).
     def run_feature(key, attributes = nil)
       manager = @feature_manager
       return disabled_feature(key) if manager.nil?
 
       @data_manager.ensure_fresh_config!
-      manager.run_feature(@visitor_id, key, decision_attributes(attributes))
+      manager.run_feature(@visitor_id, key, decision_attributes(attributes),
+                          experiences: experience_keys_for_call(attributes),
+                          type_casting: type_casting_for_call?(attributes))
     rescue StandardError => e
       @log_manager.error("Context#run_feature: #{e.class}: #{e.message}")
       disabled_feature(key)
@@ -303,15 +470,18 @@ module ConvertSdk
     # Never raises into the host: an internal failure degrades to +[]+ + an
     # +error+ log (NFR9).
     #
-    # @param attributes [Hash, nil] optional per-call visitor properties merged
-    #   over the context attributes (deep-stringified).
+    # @param attributes [Hash, nil] optional per-call visitor properties merged over
+    #   the context attributes (deep-stringified). May carry +:experience_keys+
+    #   (CAP-1) and +:type_casting+ (CAP-2); only a boolean +false+ disables casting (D-8).
     # @return [Array<BucketedFeature>] the resolved features (enabled + disabled).
     def run_features(attributes = nil)
       manager = @feature_manager
       return [] if manager.nil?
 
       @data_manager.ensure_fresh_config!
-      manager.run_features(@visitor_id, decision_attributes(attributes))
+      manager.run_features(@visitor_id, decision_attributes(attributes),
+                           experiences: experience_keys_for_call(attributes),
+                           type_casting: type_casting_for_call?(attributes))
     rescue StandardError => e
       @log_manager.error("Context#run_features: #{e.class}: #{e.message}")
       []
@@ -328,6 +498,12 @@ module ConvertSdk
     # NO lifecycle event fires on segment attachment (JS parity — neither
     # +setDefaultSegments+ nor +runCustomSegments+ fire +SystemEvents.SEGMENTS+).
     #
+    # == Zero-trace under preview (qs-03 AC6, RB-6)
+    #
+    # +enable_storage: @preview.nil?+ threads through to
+    # {SegmentsManager#put_segments}, suppressing ONLY the persistence write
+    # (mirrors JS SDK-6, +context.ts:571+ — +!this._preview+ passed the same way).
+    #
     # Never raises into the host: a failure degrades to an +error+ log and returns
     # +self+ (NFR9).
     #
@@ -337,7 +513,7 @@ module ConvertSdk
       manager = @segments_manager
       return self if manager.nil?
 
-      manager.put_segments(@visitor_id, deep_stringify(segments || {}))
+      manager.put_segments(@visitor_id, deep_stringify(segments || {}), enable_storage: @preview.nil?)
       self
     rescue StandardError => e
       @log_manager.error("Context#set_default_segments: #{e.class}: #{e.message}")
@@ -355,6 +531,13 @@ module ConvertSdk
     #
     # NO lifecycle event fires on attachment (JS parity, F-014).
     #
+    # == Zero-trace under preview (qs-03 AC6, RB-6)
+    #
+    # +enable_storage: @preview.nil?+ threads through to
+    # {SegmentsManager#select_custom_segments}, suppressing ONLY the persistence
+    # write — rule MATCHING still runs exactly as normal (mirrors JS SDK-6,
+    # +context.ts:610+ — +!this._preview+ passed the same way).
+    #
     # Never raises into the host: a failure degrades to an +error+ log + +nil+ (NFR9).
     #
     # @param segment_keys [Array<String>] the segment keys to evaluate.
@@ -366,7 +549,9 @@ module ConvertSdk
       manager = @segments_manager
       return nil if manager.nil?
 
-      result = manager.select_custom_segments(@visitor_id, segment_keys, visitor_properties(attributes))
+      result = manager.select_custom_segments(
+        @visitor_id, segment_keys, visitor_properties(attributes), enable_storage: @preview.nil?
+      )
       result.is_a?(Sentinel) ? result : nil
     rescue StandardError => e
       @log_manager.error("Context#run_custom_segments: #{e.class}: #{e.message}")
@@ -408,6 +593,14 @@ module ConvertSdk
     # @param force_multiple_transactions [Boolean] bypass the per-goal dedup check.
     # @return [self]
     def track_conversion(goal_key, goal_data: nil, force_multiple_transactions: false)
+      # qs-03 (RB-6) — zero-trace: a preview-active context is a FULL no-op here,
+      # checked BEFORE the global tracking gate below (and BEFORE
+      # DataManager#convert) so NOTHING happens — no enqueue, no CONVERSION
+      # event, and no dedup mark (the mark lives inside #convert's atomic
+      # dedup-and-mark, never reached). Mirrors JS +context.ts:512-519+
+      # (+if (this._preview) return;+ at the top of +trackConversion+).
+      return self if @preview
+
       # Story 4.5 — the global tracking gate sits BEFORE DataManager#convert so a
       # suppressed conversion neither enqueues NOR marks dedup (the goals[goalId]
       # mark lives inside #convert's atomic dedup-and-mark). A subsequent same-goal
@@ -433,6 +626,91 @@ module ConvertSdk
 
     private
 
+    # {#set_preview}'s inert-path helper: warn-log +detail+ under the
+    # +Context#set_preview+ prefix (the single log-message shape every inert
+    # branch shares — AC7) and return +self+.
+    #
+    # +clear:+ mirrors JS +Context#setPreview+ (+context.ts:143-205+) exactly:
+    # the BLANK-input guard (this method's caller with +clear: false+, the
+    # default) leaves a prior successful +@preview+ untouched — JS's own
+    # +if (!experienceId || !variationId)+ branch returns without touching
+    # +this._preview+ (+context.ts:146-152+). Every OTHER failure path — an
+    # unresolvable experience (+context.ts:172,182+) or an unknown variation id
+    # on the resolved experience (+context.ts:195+) — explicitly nulls the
+    # preview (JS: +this._preview = null;+ before each of those returns), so a
+    # FAILED re-preview after a prior success falls back to normal decisioning
+    # rather than stranding the stale forced pick. Callers pass +clear: true+
+    # for those two paths only.
+    def warn_preview_inert(detail, clear: false)
+      @preview = nil if clear
+      @log_manager.warn("Context#set_preview: #{detail}")
+      self
+    end
+
+    # {#run_experience}'s preview-forcing branch: force-decide THIS visitor's
+    # previewed variation via {DataManager#get_preview_decision}. +#set_preview+
+    # only ever stores a preview whose (experience, variation_id) pair already
+    # resolved a decision, and the resolved experience is a frozen Hash that can
+    # never drift afterward, so a nil result here is a defensive fallback, not
+    # an expected path.
+    def forced_preview_variation(preview)
+      @data_manager.get_preview_decision(preview[:experience], preview[:variation_id]) || RuleError::NO_DATA_FOUND
+    end
+
+    # {#run_experiences}'s preview branch, extracted to keep #run_experiences
+    # within RuboCop's ABC/complexity budget: drop the previewed experience's
+    # normally-decided entry (the forced decision replaces it), route every
+    # OTHER experience through {#fire_bucketing} with +track: false+, then
+    # append the forced variation. On a preview-active context that
+    # {#fire_bucketing} call is inert BY DESIGN — its +@preview.nil?+ guard
+    # suppresses the {SystemEvents::BUCKETING} event and +track: false+
+    # suppresses the enqueue, so all it emits is the +debug+ suppression line.
+    # The seam is kept rather than skipped so the zero-trace verdict stays
+    # enforced at the SINGLE bucketing site instead of being duplicated here.
+    # A defensive Sentinel from {#forced_preview_variation} (set_preview
+    # pre-validates, so not expected) appends nothing.
+    def force_preview_in_run_all(variations, preview)
+      others = variations.reject { |variation| variation.experience_key == preview[:experience_key] }
+      others.each { |variation| fire_bucketing(variation.experience_key, variation, track: false) }
+      forced = forced_preview_variation(preview)
+      forced.is_a?(Sentinel) ? others : others + [forced]
+    end
+
+    # Resolve the previewed experience for {#set_preview}: the installed
+    # config's by-id reader first ({DataManager#experience_by_id}); when
+    # absent, the +?exp=+ live-fetch fallback ({#fetch_preview_experience}).
+    def resolve_preview_experience(experience_id)
+      @data_manager.experience_by_id(experience_id) || fetch_preview_experience(experience_id)
+    end
+
+    # The +?exp={experience_id}+ fallback fetch ({ApiManager#get_config_by_experience},
+    # process-wide memoized for 60s — qs-03 AC8) for an experience absent from
+    # the installed config (e.g. a draft/paused preview target). A nil
+    # {ApiManager} (no Client-wired collaborator) or a failed fetch (the port
+    # never raises — it degrades to nil) both resolve to a miss here; the
+    # response's own +experiences+ collection is scanned by id (+to_s+
+    # compared, ids may arrive as different types).
+    def fetch_preview_experience(experience_id)
+      manager = @api_manager
+      return nil if manager.nil?
+
+      config = manager.get_config_by_experience(experience_id)
+      return nil unless config.is_a?(Hash)
+
+      experiences = config["experiences"]
+      return nil unless experiences.is_a?(Array)
+
+      target = experience_id.to_s
+      experiences.find { |candidate| candidate.is_a?(Hash) && candidate["id"].to_s == target }
+    end
+
+    # True for +nil+ or a (post-+#strip+) empty String — the blank-input guard
+    # for {#set_preview}'s +experience_id+/+variation_id+ (mirrors
+    # {Client#create_context}'s blank +visitor_id+ guard).
+    def blank?(value)
+      value.nil? || (value.respond_to?(:strip) && value.strip.empty?)
+    end
+
     # The single conversion seam (mirrors {#fire_bucketing}): enqueue the
     # wire-shaped event THEN fire the lifecycle event with +deferred: true+ (late
     # subscribers replay — JS context.ts:416-424). Fired on SUCCESS only (the
@@ -469,7 +747,8 @@ module ConvertSdk
     # per-call +ruleData+ (and context attributes) win over stored segments. All
     # deep-stringified to string keys (the rule engine reads string keys).
     def visitor_properties(attributes)
-      rule_data = attributes.is_a?(Hash) ? (attributes[:ruleData] || attributes["ruleData"]) : nil
+      key = reserved_key_name(:visitor_properties)&.to_s
+      rule_data = key && attributes.is_a?(Hash) ? attributes[key.to_sym] || attributes[key] : nil
       empty = {} #: Hash[String, untyped]
       merged = @attributes.merge(deep_stringify(rule_data || empty))
       stored = get_visitor_data["segments"]
@@ -491,13 +770,53 @@ module ConvertSdk
     # it never defaults location matching to the visitor properties) — supplied
     # only when the caller passes +location_properties+/+"location_properties"+.
     # +environment+ is lifted out so the flow's environment-match step sees it.
+    #
+    # +enable_storage: @preview.nil?+ (qs-03 / RB-6 zero-trace) rides along on
+    # EVERY decision built through this ONE seam — {#run_experience},
+    # {#run_experiences}, {#run_feature}, and {#run_features} all call it — so a
+    # preview-active context's ENTIRE decisioning surface (not just experiences)
+    # never persists sticky StoreData ({DataManager#persist_bucketing}'s gate).
+    # Absent preview (the overwhelming default), this is always +true+ —
+    # byte-identical to the pre-qs-03 behavior.
     def decision_attributes(per_call)
       merged = @attributes.merge(deep_stringify(per_call || {}))
-      {
-        visitor_properties: merged,
-        location_properties: merged["location_properties"],
-        environment: merged["environment"]
-      }
+      envelope = { visitor_properties: merged } #: Hash[Symbol, untyped]
+      reserved_rows(:merged_map).each { |name, fields| envelope[fields[:destination]] = merged[name.to_s] }
+      envelope[:enable_storage] = @preview.nil?
+      envelope
+    end
+
+    def reserved_rows(source)
+      RESERVED_KEYS.reject { |name, fields| NOT_LIFTED.key?(name.to_s) || fields[:source] != source }
+    end
+
+    # The per-call key name the enumeration routes to +destination+, nil when none does.
+    def reserved_key_name(destination)
+      row = reserved_rows(:raw_per_call).find { |_, fields| fields[:destination] == destination }
+      row&.first
+    end
+
+    # The per-call experience-key filter (CAP-1). A non-Array value degrades to
+    # no filter with a +warn+ (SD-2); nil is absence and never warns.
+    def experience_keys_for_call(attributes)
+      key = reserved_key_name(:experiences)&.to_s
+      return nil unless key && attributes.is_a?(Hash)
+
+      value = attributes.fetch(key.to_sym) { attributes.fetch(key, nil) }
+      return value if value.nil? || value.is_a?(Array)
+
+      @log_manager.warn("Context#run_feature: #{key} must be an Array, got #{value.class} — ignoring it")
+      nil
+    end
+
+    # The per-call casting switch (CAP-2): only an explicit +false+ turns it off (D-8).
+    def type_casting_for_call?(attributes)
+      return true unless attributes.is_a?(Hash)
+
+      key = reserved_key_name(:type_casting)&.to_s
+      return true if key.nil?
+
+      attributes.fetch(key.to_sym) { attributes.fetch(key, true) } != false
     end
 
     # The single named seam fired once per fresh/decided variation. It does TWO
@@ -514,20 +833,26 @@ module ConvertSdk
     #    wire entry omits the +segments+ key entirely.
     #
     # The SOLE bucketing enqueue site. The {SystemEvents::BUCKETING} LIFECYCLE event
-    # ALWAYS fires (it is decisioning observability, not tracking — a host listener
-    # may need to react to the decision even under consent denial); only the
-    # outbound ENQUEUE is gated by the tracking switch (Story 4.5). +track+ is the
+    # fires for every fresh/decided variation on a NON-preview context (decisioning
+    # observability, not tracking — a host listener may need to react to the
+    # decision even under consent denial); a preview-active context (qs-03,
+    # +@preview+ set) fires NO {SystemEvents::BUCKETING} event for ANY
+    # experience on this context, matching JS +context.ts:260+
+    # (+if (!this._preview) { fire BUCKETING }+). Independently, the outbound
+    # ENQUEUE is gated by the tracking switch (Story 4.5). +track+ is the
     # composed verdict ({#tracking_enabled_for_call?} — global AND per-call); when +false+
     # the wire enqueue is suppressed with a +debug+ line and stickiness/decisioning
     # are untouched. Contained — a raising listener never crosses back (EventManager
     # swallows it); the enqueue is pure in-memory and inert when no ApiManager is wired.
     def fire_bucketing(experience_key, variation, track: true)
-      @event_manager.fire(
-        SystemEvents::BUCKETING,
-        { visitor_id: @visitor_id, experience_key: experience_key, variation_key: variation.key },
-        nil,
-        deferred: true
-      )
+      if @preview.nil?
+        @event_manager.fire(
+          SystemEvents::BUCKETING,
+          { visitor_id: @visitor_id, experience_key: experience_key, variation_key: variation.key },
+          nil,
+          deferred: true
+        )
+      end
       return if suppress_bucketing_enqueue?(track)
 
       enqueue_bucketing_event(variation)
@@ -557,7 +882,10 @@ module ConvertSdk
     def tracking_enabled_for_call?(attributes)
       return true unless attributes.is_a?(Hash)
 
-      value = attributes.fetch(:enable_tracking) { attributes.fetch("enable_tracking", true) }
+      key = reserved_key_name(:tracking_enabled_for_call)&.to_s
+      return true if key.nil?
+
+      value = attributes.fetch(key.to_sym) { attributes.fetch(key, true) }
       value != false
     end