convert_sdk 1.0.0

data/lib/convert_sdk/stores/redis_store.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "json"
+
+module ConvertSdk
+  module Stores
+    # A first-party, in-tree store adapter backed by Redis — the cross-process
+    # answer to {MemoryStore}'s per-process limitation.
+    #
+    # == Why Redis (FR49)
+    #
+    # {MemoryStore} keeps state in a single process. Puma clusters, Sidekiq
+    # worker fleets, and Lambda invocations each run in separate processes, so
+    # sticky bucketing (Story 2.11) and goal deduplication (Story 4.3) that
+    # round-trip through a +MemoryStore+ are inconsistent across the fleet.
+    # +RedisStore+ shares that state through a Redis instance, giving every
+    # process the same view.
+    #
+    # == Zero gemspec footprint
+    #
+    # The +redis+ gem is the *user's* dependency, never the SDK's: it is NOT a
+    # gemspec runtime dependency and is +require+-d *lazily* inside {#initialize}
+    # — and only when a client is built from connection options. Requiring this
+    # file (which +lib/convert_sdk.rb+ does unconditionally) therefore never
+    # pulls in +redis+, so +require "convert_sdk"+ stays green for users who do
+    # not install it. If a caller asks +RedisStore+ to build its own client
+    # without +redis+ installed, instantiation raises an actionable error naming
+    # the gem to add — a wiring-time programmer error, sanctioned in the same
+    # class as +ConvertSdk.create+'s argument validation, NOT a business path.
+    #
+    # == Construction
+    #
+    #   # Preferred: inject an existing client (connection reuse / pooling).
+    #   # No `require "redis"`, no `Redis.new` — works even where the adapter
+    #   # file is loaded without the gem present.
+    #   store = ConvertSdk::Stores::RedisStore.new(redis: Redis.new(url: ...))
+    #
+    #   # Or pass connection options; the adapter lazily requires `redis` and
+    #   # constructs the client itself.
+    #   store = ConvertSdk::Stores::RedisStore.new(url: "redis://localhost:6379/0")
+    #
+    # An optional +key_prefix+ namespaces every key (default +"convert:"+) so the
+    # SDK's keys do not collide with other tenants of the same Redis database.
+    #
+    # == Thin adapter — resilience lives upstream
+    #
+    # This adapter is serialization + connection only. It does NOT rescue Redis
+    # client exceptions: {DataStoreManager} (Story 2.1) already wraps every
+    # +get+/+set+ in a rescue-log passthrough, degrading a raising store to
+    # +nil+/no-op instead of crashing the host. Duplicating that rescue here
+    # would swallow errors the manager is responsible for logging.
+    #
+    # == Cross-process consistency caveat
+    #
+    # Visitor-data merges are a read-modify-write. In-process that sequence is
+    # atomic under {DataStoreManager}'s mutex, but across processes sharing one
+    # Redis there is no such lock: concurrent writers race and the last write
+    # wins. This matches the JS SDK contract. The SDK does NOT use Lua scripts
+    # or +WATCH+/+MULTI+ to close that race — that is deliberately out of scope.
+    #
+    # Sidekiq / Lambda deployment guidance: see the Epic 5 documentation.
+    class RedisStore
+      # Default namespace prepended to every key written to Redis.
+      DEFAULT_KEY_PREFIX = "convert:"
+
+      # @param redis [Object, nil] an existing redis-rb-compatible client
+      #   responding to +#get+/+#set+. When supplied, +redis+ is NOT required and
+      #   no new client is constructed (preferred — enables connection reuse).
+      # @param key_prefix [String] namespace prepended to every key
+      #   (default +"convert:"+).
+      # @param options [Hash] connection options (e.g. +url:+) forwarded to
+      #   +Redis.new+ when no +redis:+ client is injected. Triggers the lazy
+      #   +require "redis"+.
+      # @raise [LoadError] re-raised as an actionable error when +redis:+ is
+      #   omitted and the +redis+ gem is not installed.
+      def initialize(redis: nil, key_prefix: DEFAULT_KEY_PREFIX, **options)
+        @key_prefix = key_prefix
+        @client = redis || build_client(options)
+      end
+
+      # Read and deserialize the value stored under +key+.
+      #
+      # @param key [String] the (unprefixed) lookup key.
+      # @return [Object, nil] the JSON-parsed value (string-keyed hashes,
+      #   numbers, arrays, booleans), or +nil+ when the key is absent.
+      def get(key)
+        raw = @client.get(namespaced(key))
+        raw.nil? ? nil : JSON.parse(raw)
+      end
+
+      # Serialize +value+ to JSON and store it under +key+, overwriting any
+      # existing value.
+      #
+      # @param key [String] the (unprefixed) storage key.
+      # @param value [Object] a JSON-serializable value (StoreData shape).
+      # @return [Object] the client's +set+ return value.
+      def set(key, value)
+        @client.set(namespaced(key), JSON.generate(value))
+      end
+
+      private
+
+      # Lazily require the +redis+ gem and construct a client from +options+.
+      # Called ONLY when no client was injected; this is the single site that
+      # depends on the gem being installed.
+      #
+      # @param options [Hash] connection options forwarded to +Redis.new+.
+      # @return [Object] a new redis-rb client.
+      # @raise [LoadError] with an actionable message when the gem is absent.
+      def build_client(options)
+        require "redis"
+        Redis.new(**options)
+      rescue LoadError
+        raise LoadError,
+              "RedisStore requires the 'redis' gem — add `gem 'redis'` to your Gemfile " \
+              "(or inject an existing client via `redis:`)."
+      end
+
+      # @param key [String] the unprefixed key.
+      # @return [String] the key with the configured namespace prepended.
+      def namespaced(key)
+        "#{@key_prefix}#{key}"
+      end
+    end
+  end
+end

data/lib/convert_sdk/version.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module ConvertSdk
+  # The gem version string (semantic version).
+  #
+  # This is a DEV PLACEHOLDER. The real version is written here at release time
+  # by the semantic-release `@semantic-release/exec` prepareCmd (release.config.mjs),
+  # as an UNCOMMITTED working-tree edit — the gem builds carrying the computed
+  # version, but `main` never receives a version-bump commit. The next release
+  # 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"
+end

data/lib/convert_sdk/visitors_queue.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+module ConvertSdk
+  # The per-visitor event queue — the in-memory buffer between the decision flow
+  # (which enqueues bucketing/conversion events) and {ApiManager} (which drains
+  # and POSTs them in the Convert wire format).
+  #
+  # == Per-visitor merge (structural invariant, FR36)
+  #
+  # The queue holds ONE entry per visitor — a string-keyed wire-shaped hash
+  # +{"visitorId" => id, "segments" => {...}?, "events" => [...]}+. Enqueuing an
+  # event for a visitor already in the queue APPENDS to that visitor's +events+
+  # array; it never adds a duplicate visitor entry and never flattens to a bare
+  # event list. The platform attributes events by walking +visitors[].events+, so
+  # flattening or duplicating corrupts report attribution. The structure itself
+  # enforces the invariant — there is no public path that bypasses the merge.
+  # (JS parity: +api-manager.ts:117-144+; PHP +VisitorsQueue.php:64-70+.)
+  #
+  # +segments+ ride on the visitor entry and are captured ONLY when the entry is
+  # first created (omitted entirely when none are supplied) — a later enqueue for
+  # the same visitor never overwrites them (JS +if (segments) visitor.segments = …+).
+  #
+  # == Bounded memory (FR39/NFR10)
+  #
+  # The queue is bounded at {MAX_EVENTS} EVENTS (events, not visitors). On
+  # overflow the OLDEST event is dropped — and the visitor entry is removed once
+  # its last event is gone — with a +warn+ log per drop. An endpoint outage can
+  # never grow host memory without bound; dropping the oldest (not the newest)
+  # keeps the most recent traffic. (Optimizely +DEFAULT_QUEUE_CAPACITY = 1000+
+  # precedent; research frozen register #7.)
+  #
+  # == Thread safety (NFR2/NFR13)
+  #
+  # Every operation is serialized by +@queue_mutex+. {#enqueue} is pure in-memory
+  # and never blocks on I/O, so the calling request thread is never held on the
+  # network. {#drain!} is an atomic drain-and-swap inside the lock returning the
+  # drained visitors array — {ApiManager} builds the payload and POSTs OUTSIDE the
+  # lock, so network I/O never holds the queue. The drained array is re-enqueueable
+  # without violating the per-visitor merge (the retention path Story 4.2 needs).
+  #
+  # @api private
+  class VisitorsQueue
+    # The hard upper bound on buffered events (events, not visitors). Research
+    # frozen register #7; the JS SDK has no equivalent memory cap.
+    MAX_EVENTS = 1000
+
+    # @param log_manager [LogManager] the redacting logging surface (warn on overflow).
+    def initialize(log_manager:)
+      @log_manager = log_manager
+      # Thread safety: guarded by @queue_mutex. @items is the ordered list of
+      # per-visitor entries; @size is the total event count (the cap dimension).
+      @queue_mutex = Thread::Mutex.new
+      @items = [] #: Array[Hash[String, untyped]]
+      @size = 0
+    end
+
+    # Enqueue one wire-shaped event for +visitor_id+, merging into the visitor's
+    # existing entry (append) or creating a new one. Pure in-memory — never blocks
+    # on I/O. On overflow past {MAX_EVENTS} the oldest event is dropped (+warn+).
+    #
+    # @param visitor_id [String] the visitor the event belongs to.
+    # @param event [Hash{String=>Object}] a wire-shaped (string-keyed camelCase)
+    #   event hash, e.g. +{"eventType"=>"bucketing", "data"=>{...}}+.
+    # @param segments [Hash{String=>Object}, nil] the visitor's report-segments,
+    #   attached ONLY when this enqueue first creates the visitor's entry.
+    # @return [void]
+    def enqueue(visitor_id, event, segments: nil)
+      @queue_mutex.synchronize do
+        entry = @items.find { |item| item["visitorId"] == visitor_id }
+        if entry
+          entry["events"] << event
+        else
+          entry = { "visitorId" => visitor_id, "events" => [event] } #: Hash[String, untyped]
+          entry["segments"] = segments unless segments.nil?
+          @items << entry
+        end
+        @size += 1
+        trim_to_cap
+      end
+    end
+
+    # Atomically drain the queue: swap out the current per-visitor entries and
+    # reset to empty inside the lock, returning the drained array. The caller
+    # (ApiManager) builds the payload and POSTs OUTSIDE the lock.
+    #
+    # @return [Array<Hash{String=>Object}>] the drained per-visitor entries
+    #   (empty when nothing was queued); re-enqueueable verbatim.
+    def drain!
+      @queue_mutex.synchronize do
+        drained = @items
+        @items = []
+        @size = 0
+        drained
+      end
+    end
+
+    # Re-enqueue previously drained per-visitor entries after a failed delivery
+    # (Story 4.2 failure retention), PRESERVING the per-visitor merge. Runs as one
+    # atomic compound operation inside +@queue_mutex+.
+    #
+    # The drained events are OLDER than anything the queue received during the
+    # failed POST, so they are placed BEFORE newer events: a drained visitor that
+    # already has a live entry (new events arrived for it mid-failure) has its
+    # drained events PREPENDED to that entry — never a duplicate visitor entry;
+    # a drained visitor with no live entry is inserted at the FRONT of the queue
+    # (its events are the oldest). Segments ride from whichever entry has them
+    # (the live entry wins; otherwise the drained entry's segments are adopted).
+    #
+    # Re-enqueued events count toward {MAX_EVENTS}: a sustained outage that keeps
+    # requeuing drops the OLDEST events (+warn+ per drop), bounding host memory
+    # without bound (NFR10).
+    #
+    # @param visitors [Array<Hash{String=>Object}>] drained per-visitor entries
+    #   (as returned by {#drain!}); an empty array is a no-op.
+    # @return [void]
+    def requeue(visitors)
+      return if visitors.empty?
+
+      @queue_mutex.synchronize do
+        # Walk the drained entries in reverse so that successive front-inserts
+        # preserve their original relative order at the head of the queue.
+        visitors.reverse_each { |drained| merge_drained(drained) }
+        trim_to_cap
+      end
+    end
+
+    # @return [Integer] the total number of buffered EVENTS (not visitors).
+    def size
+      @queue_mutex.synchronize { @size }
+    end
+
+    # Atomically empty the queue WITHOUT returning the entries (Story 4.4 child
+    # queue-ownership clear). A forked child inherits a COPY of the parent's
+    # queued events; clearing the child's copy ensures the child never
+    # double-delivers the parent's events (the parent's timer still runs there
+    # and delivers them). Distinct from {#drain!} (which allocates and returns
+    # the entries for delivery) — this just discards. Idempotent.
+    # @return [void]
+    def clear
+      @queue_mutex.synchronize do
+        @items = []
+        @size = 0
+      end
+    end
+
+    private
+
+    # Merge ONE drained per-visitor entry back into @items, preserving the
+    # per-visitor merge. Caller holds @queue_mutex.
+    #
+    # When a live entry exists for the visitor, the drained (older) events are
+    # PREPENDED to it and the live entry adopts the drained segments only if it
+    # has none. Otherwise the drained entry is inserted at the FRONT of the queue
+    # (its events are older than all live traffic). @size grows by the drained
+    # event count; {#trim_to_cap} (run by the caller after all merges) bounds it.
+    def merge_drained(drained)
+      visitor_id = drained["visitorId"]
+      drained_events = drained["events"]
+      existing = @items.find { |item| item["visitorId"] == visitor_id }
+      if existing
+        existing["events"].unshift(*drained_events)
+        existing["segments"] = drained["segments"] if !existing.key?("segments") && drained.key?("segments")
+      else
+        @items.unshift(drained)
+      end
+      @size += drained_events.size
+    end
+
+    # Drop oldest events until the event count is within {MAX_EVENTS}. Removes a
+    # visitor entry once its last event is gone. Caller holds @queue_mutex.
+    # Emits ONE aggregated warn after the loop (never one per dropped event) to
+    # avoid a warn burst when +requeue+ overshoots the cap by a full drained batch
+    # during a sustained outage.
+    def trim_to_cap
+      dropped_count = 0
+      while @size > MAX_EVENTS
+        oldest = @items.first
+        break if oldest.nil?
+
+        oldest["events"].shift
+        @items.shift if oldest["events"].empty?
+        @size -= 1
+        dropped_count += 1
+      end
+      return if dropped_count.zero?
+
+      @log_manager.warn("VisitorsQueue#trim_to_cap: queue full, dropped #{dropped_count} oldest event(s)")
+    end
+  end
+end

data/lib/convert_sdk.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require_relative "convert_sdk/version"
+require_relative "convert_sdk/murmur_hash3"
+require_relative "convert_sdk/sentinel"
+require_relative "convert_sdk/enums/rule_error"
+require_relative "convert_sdk/enums/bucketing_error"
+require_relative "convert_sdk/enums/feature_status"
+require_relative "convert_sdk/enums/log_level"
+require_relative "convert_sdk/enums/system_events"
+require_relative "convert_sdk/enums/goal_data_key"
+require_relative "convert_sdk/bucketed_variation"
+require_relative "convert_sdk/bucketed_feature"
+require_relative "convert_sdk/redactor"
+require_relative "convert_sdk/log_manager"
+require_relative "convert_sdk/config_validator"
+require_relative "convert_sdk/config"
+require_relative "convert_sdk/bucketing_manager"
+require_relative "convert_sdk/comparisons"
+require_relative "convert_sdk/rule_manager"
+require_relative "convert_sdk/http_client"
+require_relative "convert_sdk/stores/memory_store"
+require_relative "convert_sdk/stores/redis_store"
+require_relative "convert_sdk/data_store_manager"
+require_relative "convert_sdk/event_manager"
+require_relative "convert_sdk/fork_guard"
+require_relative "convert_sdk/background_timer"
+require_relative "convert_sdk/data_manager"
+require_relative "convert_sdk/visitors_queue"
+require_relative "convert_sdk/api_manager"
+require_relative "convert_sdk/experience_manager"
+require_relative "convert_sdk/feature_manager"
+require_relative "convert_sdk/segments_manager"
+require_relative "convert_sdk/context"
+require_relative "convert_sdk/client"
+
+# Install the SDK's only global mutation — the Process._fork prepend — at load
+# (it must exist before any fork; installing it is cheap and thread-free, so it
+# respects the NFR4 zero-threads-until-use rule, which concerns THREADS, not the
+# hook). A no-op on JRuby by construction.
+ConvertSdk::ForkGuard.install!
+
+# The Convert Experiences full-stack SDK for Ruby.
+#
+# {ConvertSdk.create} is THE public entry point (frozen API name): it builds the
+# validated {Config}, wires the managers, and returns a ready-to-use {Client}.
+module ConvertSdk
+  # The default config-cache TTL in seconds, used by the timer-off (Lambda/CLI)
+  # decision-time staleness check when +data_refresh_interval+ is +nil+
+  # (timer-off ≠ TTL-off). 300s converges on the same cadence the background
+  # timer uses, on demand. A Ruby-SDK design constant (PHP on-demand TTL
+  # semantics) — the JS SDK has no timer-off TTL concept. See Story 2.7.
+  DEFAULT_CONFIG_TTL = 300
+
+  # The SDK's base error type. Note the SDK has NO custom exception hierarchy for
+  # runtime/infra failures (Decision 3 — it degrades gracefully with cached
+  # config / sentinels); misconfiguration surfaces as a plain +ArgumentError+
+  # from {Config}. This type exists only as a namespace anchor.
+  class Error < StandardError; end
+
+  # Whether {Client} registers its PID-guarded +at_exit+ flush handler at
+  # construction (Story 4.4 AC#5). Always +true+ in production. The TEST HARNESS
+  # alone flips this off (a +spec/support+ hook) so unit specs that build clients
+  # do NOT register live +at_exit+ handlers — which would fire +flush+ during
+  # RSpec suite teardown. The handler BODY is unit-tested directly via
+  # +Client#run_at_exit_flush+; the live-registration path is proven end-to-end
+  # in a SUBPROCESS in spec/integration/fork_safety_spec.rb.
+  # @return [Boolean]
+  def self.at_exit_registration_enabled?
+    @at_exit_registration_enabled = true unless defined?(@at_exit_registration_enabled)
+    @at_exit_registration_enabled
+  end
+
+  # Set the {at_exit_registration_enabled?} flag (test harness only).
+  # @param value [Boolean]
+  # @return [Boolean]
+  def self.at_exit_registration_enabled=(value)
+    @at_exit_registration_enabled = value
+  end
+
+  # Build an SDK client from an SDK key (live config fetch) or a pre-fetched
+  # +data:+ object (direct data mode). THE public entry point.
+  #
+  # Wiring order: a {LogManager} is built first, then {Config} (which registers
+  # any +sdk_key+ / +sdk_key_secret+ with the manager's Redactor before any log
+  # line can carry them and raises +ArgumentError+ on misconfiguration — the
+  # SDK's only raising surface), then the {HttpClient}, {DataStoreManager},
+  # {EventManager}, and {DataManager} ports, then the {Client} (which fetches /
+  # installs config and fires +ready+). No background threads are started here
+  # (NFR4 — lazy start; the refresh / flush timers are wired by their own
+  # stories).
+  #
+  # @param sdk_key [String, nil] the account/project SDK key (fetch mode).
+  # @param data [Hash, nil] a pre-fetched config object (direct data mode); when
+  #   supplied, no fetch occurs.
+  # @param store [Object, nil] an optional duck-typed data store (get/set);
+  #   defaults to an in-memory store.
+  # @param clock [#call, nil] an optional monotonic time source (seconds) for
+  #   the config-cache TTL math (Story 2.7); defaults to the SDK's monotonic
+  #   clock. Injectable so tests control staleness without real waits. NOT a
+  #   {Config} option — extracted here before validation.
+  # @param sink [Object, nil] an optional initial log sink (anything responding
+  #   to debug/info/warn/error). Forwarded to the internally-built {LogManager}
+  #   so the FULL lifecycle — including the construction-time config fetch
+  #   (+HttpClient#request+ debug line, which carries the sdk_key in the config
+  #   URL) — is observable through the public entry point. Without this seam a
+  #   host could only attach a sink AFTER {create}, missing every init-time line
+  #   (and therefore the init-time redaction proof). NOT a {Config} option —
+  #   extracted here before validation (like +clock+). Invalid sinks are rejected
+  #   by {LogManager#add_sink}, not raised.
+  # @param options [Hash{Symbol=>Object}] any other {Config::DEFAULTS} option
+  #   (+sdk_key_secret+, +environment+, +log_level+, timeouts, …).
+  # @raise [ArgumentError] on misconfiguration (missing sdk_key+data, bad types,
+  #   unknown option) — the only exception {create} lets escape.
+  # @return [Client] the wired SDK client.
+  def self.create(sdk_key: nil, data: nil, store: nil, clock: nil, sink: nil, **options)
+    config_options = options.merge(sdk_key: sdk_key, data: data)
+    log_manager = LogManager.new(
+      level: options.fetch(:log_level, Config::DEFAULTS[:log_level]), sink: sink
+    )
+    # Wire the ForkGuard re-arm logger (Story 2.7) so fork-detection debug lines
+    # flow through the redacting LogManager. nil-safe before wiring.
+    ForkGuard.logger = log_manager
+    config = Config.new(log_manager: log_manager, **config_options)
+
+    Client.new(config: config, log_manager: log_manager, **build_managers(config, log_manager, store, clock))
+  end
+
+  # Build the full collaborator graph wired around a validated {Config}: the HTTP
+  # port, the store/event ports, the Story 2.9/2.10 decision engines, the
+  # {DataManager} (decision flow), the {ApiManager} (delivery), and the per-context
+  # decisioning surfaces (Story 2.11 / 3.1 / 3.2). All thread-free (NFR4 — no
+  # timers start here). Returned as the keyword map {Client#initialize} consumes.
+  # @api private
+  def self.build_managers(config, log_manager, store, clock)
+    http_client = HttpClient.new(
+      log_manager: log_manager, open_timeout: config.open_timeout, read_timeout: config.read_timeout
+    )
+    data_store_manager = DataStoreManager.new(log_manager: log_manager, store: store)
+    event_manager = EventManager.new(log_manager: log_manager)
+    # The pure-math decision engines (Story 2.9 / 2.10) — thread-free, config-bound.
+    bucketing_manager = BucketingManager.new(config: config, log_manager: log_manager)
+    rule_manager = RuleManager.new(config: config, comparisons: Comparisons, log_manager: log_manager)
+    # The DataManager owns the ordered decision flow; it needs the two engines to
+    # bucket and walk rules (without them it is config-read-only — the 2.5/2.7 use).
+    data_manager = build_data_manager(
+      config, log_manager, data_store_manager, clock, bucketing_manager, rule_manager
+    )
+    api_manager = build_api_manager(config, log_manager, http_client, event_manager, data_manager)
+    decisioning = build_decisioning_managers(log_manager, data_store_manager, data_manager, rule_manager)
+    {
+      http_client: http_client, data_store_manager: data_store_manager,
+      event_manager: event_manager, data_manager: data_manager, api_manager: api_manager,
+      experience_manager: decisioning[:experience_manager],
+      feature_manager: decisioning[:feature_manager],
+      segments_manager: decisioning[:segments_manager]
+    }
+  end
+  private_class_method :build_managers
+
+  # Build the per-context decisioning surfaces (Story 2.11 / 3.1 / 3.2) as a
+  # thread-free trio (NFR4 — no timers start here). SegmentsManager reuses the
+  # rule engine and resolves the store-key halves from the DataManager readers
+  # (its account/project resolvers).
+  # @api private
+  def self.build_decisioning_managers(log_manager, data_store_manager, data_manager, rule_manager)
+    {
+      experience_manager: ExperienceManager.new(data_manager: data_manager, log_manager: log_manager),
+      feature_manager: FeatureManager.new(data_manager: data_manager, log_manager: log_manager),
+      segments_manager: SegmentsManager.new(
+        data_manager: data_manager, data_store_manager: data_store_manager,
+        account_resolver: -> { data_manager.account_id }, project_resolver: -> { data_manager.project_id },
+        rule_manager: rule_manager, log_manager: log_manager
+      )
+    }
+  end
+  private_class_method :build_decisioning_managers
+
+  # Build the outbound delivery surface (Story 4.1): the {ApiManager} owns the
+  # per-visitor event queue and the wire-payload builder. No thread is started
+  # here (NFR4 — the background flush timer lands in Story 4.2); construction is
+  # thread-free.
+  # @api private
+  def self.build_api_manager(config, log_manager, http_client, event_manager, data_manager)
+    ApiManager.new(
+      config: config, data_manager: data_manager, http_client: http_client,
+      event_manager: event_manager, log_manager: log_manager
+    )
+  end
+  private_class_method :build_api_manager
+
+  # Build the {DataManager} wired with the Story 2.7 config-cache surface AND the
+  # Story 2.9/2.10 decision engines: the cache lives under
+  # +convert_sdk.config.{sdkKey}+ (the DataManager writes through on every install
+  # and runs the timer-off TTL check against it). A nil sdk_key (direct-data mode)
+  # leaves the cache key nil, so no cache write happens. The +clock+ (monotonic
+  # TTL source) is injected only when supplied. The +bucketing_manager+ /
+  # +rule_manager+ make the ordered decision flow operative (without them the
+  # DataManager is config-read-only). The account/project resolvers are left to
+  # the DataManager's own readers (its constructor defaults to +#account_id+ /
+  # +#project_id+) — the live config IS the source of those store-key halves here.
+  # @api private
+  def self.build_data_manager(config, log_manager, data_store_manager, clock,
+                              bucketing_manager, rule_manager)
+    config_key = config.sdk_key.nil? ? nil : data_store_manager.config_key(config.sdk_key)
+    clock_option = clock.nil? ? {} : { clock: clock } #: Hash[Symbol, ^() -> Float]
+    DataManager.new(
+      log_manager: log_manager,
+      data_store_manager: data_store_manager,
+      config_key: config_key,
+      ttl: config.data_refresh_interval,
+      bucketing_manager: bucketing_manager,
+      rule_manager: rule_manager,
+      **clock_option
+    )
+  end
+  private_class_method :build_data_manager
+end

data/scripts/check-generated-rbs-header.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# check-generated-rbs-header.sh — PR-blocking guard (qs-03 / B5).
+#
+# Mirrors the android-sdk "Enforce generated-file header (OpenAPI types)" guard
+# (android-sdk/.github/workflows/ci.yml:51). Every .rbs file under
+# sig/convert_sdk/config/generated/ MUST start with the generated-marker
+# comment. Files that lack the header are either hand-edited or mistakenly
+# added to the directory — both are PR blockers. Regenerate via the backend
+# serving workflow and re-sync; never edit generated files in place.
+#
+# Usage: ./scripts/check-generated-rbs-header.sh
+#   Run from the ruby-sdk repo root. Exits 0 when all files carry the marker;
+#   exits 1 listing every offending file.
+
+set -euo pipefail
+
+GEN_DIR="sig/convert_sdk/config/generated"
+MARKER="AUTO-GENERATED FROM backend apiDoc/serving"
+
+if [ ! -d "$GEN_DIR" ]; then
+  echo "ERROR: generated directory not found: $GEN_DIR"
+  echo "       Expected the directory to exist after Task B1 (qs-03)."
+  exit 1
+fi
+
+missing=0
+while IFS= read -r -d '' file; do
+  if ! head -1 "$file" | grep -q "$MARKER"; then
+    echo "ERROR: $file is missing the auto-generated header."
+    echo "       Expected line 1 to contain: $MARKER"
+    echo "       Regenerate via 'yarn generateRubyRbs' in backend/apiDoc/serving"
+    echo "       and re-sync per sig/convert_sdk/config/generated/. Do not hand-edit."
+    missing=1
+  fi
+done < <(find "$GEN_DIR" -name '*.rbs' -print0)
+
+if [ "$missing" -ne 0 ]; then
+  exit 1
+fi
+
+echo "OK: every .rbs file under $GEN_DIR carries the auto-generated header."