convert_sdk 1.0.0

data/lib/convert_sdk/client.rb

@@ -0,0 +1,417 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module ConvertSdk
+  # The SDK runtime handle returned by {ConvertSdk.create}.
+  #
+  # +Client+ owns the wiring of the injected managers (config, logging, HTTP,
+  # store, events, data) and drives the config lifecycle at construction:
+  #
+  # * *Direct data mode* (+data:+ supplied) — the inline object is normalised to
+  #   string keys and installed straight into {DataManager}; NO config fetch
+  #   happens (a single network-free path for testing / advanced setups).
+  # * *Fetch mode* (+sdk_key:+ only) — config is fetched via
+  #   +GET {config_endpoint}/config/{sdkKey}+ (+?environment=...+ when set)
+  #   through {HttpClient} ONLY, with +Authorization: Bearer {sdk_key_secret}+
+  #   attached when a secret is configured. A failed fetch is logged at +warn+
+  #   and the client is constructed WITHOUT config (degrade-gracefully, NFR12) —
+  #   it never raises.
+  #
+  # == ready exactly once (FR9)
+  #
+  # The first successful config install (fetched OR direct) fires
+  # {SystemEvents::READY} exactly once for the client's lifetime; the once-guard
+  # is the +:first+ marker {DataManager#install_config} computes atomically inside
+  # its config mutex. Subsequent installs (Story 2.7's refresh) fire
+  # {SystemEvents::CONFIG_UPDATED}, never +ready+ again.
+  #
+  # == Never-crash boundary
+  #
+  # Every public method rescues +StandardError+, logs it, and returns its
+  # per-contract value — only {ConvertSdk.create}'s +ArgumentError+ (raised by
+  # {Config} on misconfiguration) is allowed to escape. The endpoints are touched
+  # ONLY through {HttpClient} (the single hardened HTTP port); the Client never
+  # touches the network library directly or builds wire headers beyond passing
+  # the Bearer header VALUE through the port.
+  #
+  # == Decisioning surface (fully wired)
+  #
+  # {#create_context} injects the per-context decisioning managers
+  # ({ExperienceManager}, {FeatureManager}, {SegmentsManager}) and the outbound
+  # {ApiManager} into each {Context}, so a context returned by a factory-built
+  # client decides through the real Story 2.9–3.2 machinery and enqueues bucketing
+  # / conversion events for delivery. No background threads are started by the
+  # Client or the factory (NFR4 lazy start); the refresh timer (Story 2.7),
+  # flush/fork/at_exit (Epic 4) wiring is lazy. Constructor injection throughout —
+  # no globals.
+  class Client
+    # @param config [Config] the validated configuration surface.
+    # @param log_manager [LogManager] shared logging surface (secrets armed).
+    # @param http_client [HttpClient] the single HTTP port (config fetch only here).
+    # @param data_store_manager [DataStoreManager] persistence port (wired; config
+    #   caching is Story 2.7 — in-memory install only here).
+    # @param event_manager [EventManager] lifecycle pub/sub (fires +ready+).
+    # @param data_manager [DataManager] holds the deep-frozen config snapshot.
+    # @param api_manager [ApiManager] the outbound event queue + delivery surface
+    #   (Story 4.1) — drives {#flush} and the bucketing-event enqueue seam.
+    # @param experience_manager [ExperienceManager, nil] the variation-selection
+    #   surface (Story 2.11) injected into every {Context}. nil leaves contexts
+    #   decisioning-less (the never-crash unit harness builds clients without it).
+    # @param feature_manager [FeatureManager, nil] the feature-resolution surface
+    #   (Story 3.1) injected into every {Context}. nil leaves features miss-only.
+    # @param segments_manager [SegmentsManager, nil] the visitor-segmentation
+    #   surface (Story 3.2) injected into every {Context}. nil leaves segmentation
+    #   inert.
+    def initialize(config:, log_manager:, http_client:, data_store_manager:,
+                   event_manager:, data_manager:, api_manager:,
+                   experience_manager: nil, feature_manager: nil, segments_manager: nil)
+      @config = config
+      @log_manager = log_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 = experience_manager
+      @feature_manager = feature_manager
+      @segments_manager = segments_manager
+      # The lazily-started config-refresh BackgroundTimer (Story 2.7). Created
+      # here (interval bound, registered with ForkGuard) but NEVER started in the
+      # factory — #ensure_refresh_timer! starts it on first decision-path use
+      # (NFR4). A nil data_refresh_interval makes #start a guarded no-op (2.6),
+      # so timer-off mode never spawns a thread.
+      @refresh_timer = build_refresh_timer
+      # Wire the synchronous timer-off refresh callable into the DataManager so
+      # its decision-time TTL check (#ensure_fresh_config!) runs one full refresh
+      # cycle through the single HTTP port (the I/O happens under DataManager's
+      # thundering-herd fetch mutex, never the config mutex).
+      @data_manager.refetch = -> { refresh_config }
+      bootstrap_config
+      # Story 4.4 AC#5 — register the PID-guarded at_exit flush ONCE per client
+      # (the gem's ONLY at_exit site; the third and final single-site after the
+      # BackgroundTimer thread-spawn site and the ForkGuard _fork site).
+      # Registering an at_exit handler creates NO thread (NFR4-safe). The test
+      # harness disables live registration (the handler body is tested directly).
+      register_at_exit_flush
+    rescue StandardError => e
+      # Construction must never crash the host: log and continue config-less.
+      @log_manager.error("Client#initialize: #{e.class}: #{e.message}")
+    end
+
+    # @return [Config] the configuration this client was built with.
+    attr_reader :config
+
+    # @return [DataManager] the config snapshot reader surface.
+    attr_reader :data_manager
+
+    # @return [ApiManager] the outbound event queue + delivery surface (Story 4.1).
+    attr_reader :api_manager
+
+    # Subscribe to a lifecycle event. Public API; delegates to {EventManager#on}
+    # (which normalises {SystemEvents} constants and matching strings to one key
+    # and replays deferred one-shot events to late subscribers).
+    #
+    # @param event [String] a {SystemEvents} value or matching string.
+    # @yieldparam payload [Object, nil]
+    # @yieldparam err [Object, nil]
+    # @return [self]
+    def on(event, &)
+      @event_manager.on(event, &)
+      self
+    rescue StandardError => e
+      @log_manager.error("Client#on: #{e.class}: #{e.message}")
+      self
+    end
+
+    # @return [Boolean] true once a config snapshot is installed (degrade probe).
+    def config_available?
+      @data_manager.config_available?
+    end
+
+    # Create a per-visitor decisioning {Context} — the object an integrator holds
+    # for the lifetime of one request/job.
+    #
+    # The +visitor_id+ is validated for presence (blank/nil → an +error+ log line
+    # + +nil+ return, NOT an +ArgumentError+: validation here is request-time, and
+    # the never-crash contract forbids raising into the host on a per-request call;
+    # only {ConvertSdk.create}'s config-time misconfiguration raises). Creation is
+    # the SDK's "first use" trigger, so it fires the lazy-start refresh-timer hook
+    # ({#ensure_refresh_timer!}, NFR4) — no threads start before the first context.
+    #
+    # Each call returns a NEW, independent {Context} (no caching, no shared mutable
+    # in-memory visitor state across instances — FR12); contexts for the same
+    # visitor share only the store-backed {StoreData} (stickiness). Attributes are
+    # deep-stringified at the {Context} boundary.
+    #
+    # @param visitor_id [String] the visitor id (must be non-blank).
+    # @param attributes [Hash, nil] optional per-visitor attributes.
+    # @return [Context, nil] the new Context, or nil for a blank visitor id.
+    def create_context(visitor_id = nil, attributes = nil)
+      if visitor_id.nil? || (visitor_id.respond_to?(:strip) && visitor_id.strip.empty?)
+        @log_manager.error("Client#create_context: blank visitor_id; returning nil")
+        return nil
+      end
+
+      # Story 4.4 — re-arm when a Process.daemon bypass left owner_pid stale.
+      # Mirrors ApiManager#guard_fork_boundary and Client#postfork: after rearm!
+      # marks the inherited refresh timer dead, the ensure_refresh_timer! call
+      # below spawns a fresh thread (BackgroundTimer#start is a no-op only when
+      # @running is true; mark_dead resets it to false). The check is a free PID
+      # comparison; always false on JRuby.
+      ForkGuard.rearm! if ForkGuard.forked?
+
+      # Context creation is "first use" — lazily arm the background refresh timer.
+      ensure_refresh_timer!
+      build_context(visitor_id, attributes)
+    rescue StandardError => e
+      @log_manager.error("Client#create_context: #{e.class}: #{e.message}")
+      nil
+    end
+
+    # Lazily start the background config-refresh timer (NFR4 — never in the
+    # factory). Called at the first decision-path entry (consumed by 2.8/2.11);
+    # idempotent (2.6 {BackgroundTimer#start} is idempotent and re-arms after a
+    # fork). A nil +data_refresh_interval+ makes this a guarded no-op (no thread
+    # is ever created — timer-off mode). Never raises into the host.
+    # @return [self]
+    def ensure_refresh_timer!
+      @refresh_timer.start
+      self
+    rescue StandardError => e
+      @log_manager.error("Client#ensure_refresh_timer!: #{e.class}: #{e.message}")
+      self
+    end
+
+    # Decision-time freshness hook for timer-off mode (Lambda/CLI). Delegates to
+    # {DataManager#ensure_fresh_config!}, which performs an on-demand TTL check
+    # and a synchronous, thundering-herd-guarded refetch when the cached config
+    # is stale. A no-op when the refresh timer is enabled. Never raises.
+    # @return [self]
+    def ensure_fresh_config!
+      @data_manager.ensure_fresh_config!
+      self
+    rescue StandardError => e
+      @log_manager.error("Client#ensure_fresh_config!: #{e.class}: #{e.message}")
+      self
+    end
+
+    # Explicitly release the queued visitor events synchronously (FR40). THE
+    # single flush entry point — delegates to {ApiManager#release_queue}, which
+    # drains-and-swaps inside the queue lock and POSTs OUTSIDE it (the enqueue
+    # path is never blocked on network I/O). A failed POST is logged inside the
+    # ApiManager and never raised; the full failed-POST queue-retention behaviour
+    # lands in Story 4.2. An empty queue is a no-op.
+    #
+    # +release_queues+ is the frozen-name alias (FR40) and shares this exact path.
+    #
+    # NOTE (Story 4.4 seam): this is the single point where a ForkGuard PID check
+    # will gate the flush in a forked child — added here so all flush callers
+    # (explicit, at_exit, timer) inherit it from one place.
+    #
+    # Never raises into the host (NFR9 never-crash boundary).
+    #
+    # @param reason [String, nil] a human-readable release reason (logged).
+    # @return [self]
+    def flush(reason = nil)
+      @api_manager.release_queue(reason)
+      self
+    rescue StandardError => e
+      @log_manager.error("Client#flush: #{e.class}: #{e.message}")
+      self
+    end
+    alias release_queues flush
+
+    # Manually re-arm the SDK after a fork (Story 4.4 AC#4 — frozen API name
+    # +postfork+). The exotic-setup escape hatch: in the default Puma/Unicorn/
+    # Sidekiq deployments the +Process._fork+ hook (ForkGuard) and the PID checks
+    # at flush boundaries detect forks AUTOMATICALLY with zero configuration, so
+    # +postfork+ is rarely needed. It exists for setups that bypass +_fork+
+    # entirely and never reach a flush boundary in time (or integrators who prefer
+    # an explicit +on_worker_boot+/+after_fork+ call, LaunchDarkly-style).
+    #
+    # Delegates to the SAME {ForkGuard.rearm!} path as automatic detection: marks
+    # both registered timers dead (lazy re-arm on next use), clears queue
+    # ownership in this process, and resets the owning PID. Idempotent (calling it
+    # in the owning process simply resets owner_pid to the current PID and
+    # re-fires the harmless clears). Never raises into the host (NFR9).
+    #
+    # @return [self]
+    def postfork
+      ForkGuard.rearm!
+      self
+    rescue StandardError => e
+      @log_manager.error("Client#postfork: #{e.class}: #{e.message}")
+      self
+    end
+
+    private
+
+    # Build a fully-wired {Context} for +visitor_id+: the shared config/store/event/
+    # log surfaces plus the per-context decisioning managers (Story 2.11 / 3.1 / 3.2)
+    # and the outbound {ApiManager} (Story 4.1). A nil decisioning manager leaves
+    # the corresponding Context method inert (the never-crash unit harness path).
+    def build_context(visitor_id, attributes)
+      Context.new(
+        visitor_id: visitor_id,
+        attributes: attributes,
+        data_manager: @data_manager,
+        data_store_manager: @data_store_manager,
+        event_manager: @event_manager,
+        log_manager: @log_manager,
+        config: @config,
+        experience_manager: @experience_manager,
+        feature_manager: @feature_manager,
+        segments_manager: @segments_manager,
+        api_manager: @api_manager
+      )
+    end
+
+    # Story 4.4 AC#5 — capture the registering PID and register the gem's single
+    # at_exit handler (the Split-gem ROOT_PROCESS_ID pattern). Skipped under the
+    # test harness (+ConvertSdk.at_exit_registration_enabled?+ is false there) so
+    # specs never register a live handler that would fire flush at suite exit.
+    # Registering an at_exit handler creates no thread (NFR4-safe).
+    def register_at_exit_flush
+      @at_exit_pid = Process.pid
+      return unless ConvertSdk.at_exit_registration_enabled?
+
+      at_exit { run_at_exit_flush }
+    end
+
+    # The at_exit handler body (Story 4.4 AC#5). PID-guarded: it flushes ONLY in
+    # the process that registered it — a forked child that inherited the handler
+    # is suppressed (its events belong to the child's own lifecycle, and the
+    # parent flushes the parent's). Best-effort: it does not run under SIGKILL
+    # (Lambda) — that path relies on the size/interval triggers. Never raises at
+    # exit (a raise during interpreter teardown is especially hostile).
+    def run_at_exit_flush
+      if Process.pid == @at_exit_pid
+        @log_manager.debug("Client#run_at_exit_flush: registering process exiting, flushing")
+        @api_manager.release_queue("exit")
+      else
+        @log_manager.debug("Client#run_at_exit_flush: suppressed in forked child (pid mismatch)")
+      end
+    rescue StandardError => e
+      @log_manager.error("Client#run_at_exit_flush: #{e.class}: #{e.message}")
+    end
+
+    # Build the config-refresh BackgroundTimer bound to +data_refresh_interval+
+    # and register it with ForkGuard (so a forked child marks it dead and the
+    # next #ensure_refresh_timer! re-arms it). The tick body is {#refresh_config}.
+    def build_refresh_timer
+      timer = BackgroundTimer.new(
+        interval: @config.data_refresh_interval,
+        log_manager: @log_manager,
+        name: "refresh"
+      ) { refresh_config }
+      ForkGuard.register_timer(timer)
+      timer
+    end
+
+    # One refresh cycle (the timer tick AND the synchronous timer-off refetch
+    # share this path): refetch through the HTTP port and, on success, install
+    # (deep-freeze + atomic swap + cache write via DataManager) which fires
+    # +config.updated+ (never +ready+ again — the 2.5 ready-once guard). A failed
+    # refetch keeps the current snapshot, warns, and lets the timer retry on the
+    # next tick (no inline retry, no backoff — frozen decision).
+    def refresh_config
+      envelope = refetch_config
+      if envelope.is_a?(Hash)
+        install(envelope, "Client#refresh_config: refreshed config installed")
+      else
+        @log_manager.warn("Client#refresh_config: refresh failed, serving cached config")
+      end
+    end
+
+    # Refetch the config through the single HTTP port and return the parsed
+    # envelope on success, or nil on any failed response. The single network
+    # refetch primitive — used by the timer tick and the timer-off synchronous
+    # refresh; the I/O here never holds the config mutex.
+    def refetch_config
+      response = @http_client.request(method: :get, url: config_url, headers: fetch_headers)
+      response.success? && response.body.is_a?(Hash) ? response.body : nil
+    end
+
+    # Drive the config lifecycle at construction: direct-data install when a
+    # +data:+ object was supplied, otherwise a live fetch. Either path that
+    # yields a usable config installs it identically (and fires +ready+ once).
+    def bootstrap_config
+      if @config.data.nil?
+        fetch_and_install_config
+      else
+        install(@config.data, "Client#initialize: installed direct data config")
+      end
+    end
+
+    # Fetch config through the HTTP port and install it on success. A failed
+    # response degrades gracefully: it MAY fall back to a non-stale cached entry
+    # from the store (meaningful across processes with a shared store like
+    # Redis), otherwise a +warn+ line, no config, no raise.
+    def fetch_and_install_config
+      response = @http_client.request(method: :get, url: config_url, headers: fetch_headers)
+      if response.success? && response.body.is_a?(Hash)
+        install(response.body, "Client#initialize: installed fetched config")
+      elsif @data_manager.install_from_cache_if_fresh
+        @event_manager.fire(SystemEvents::READY, deferred: true)
+      else
+        @log_manager.warn(
+          "Client#initialize: config fetch failed (status #{response.status}); " \
+          "continuing without config"
+        )
+      end
+    end
+
+    # Install a config envelope and fire the correct lifecycle event based on the
+    # atomic first/updated marker from {DataManager}. Symbol-keyed inputs (direct
+    # data mode) are normalised to string keys at this public boundary before
+    # install so readers see the same string-keyed wire shape as fetched config.
+    def install(source, log_message)
+      marker = @data_manager.install_config(stringify_keys(source))
+      return unless marker
+
+      @log_manager.info(log_message)
+      if marker == :first
+        @event_manager.fire(SystemEvents::READY, deferred: true)
+      else
+        @event_manager.fire(SystemEvents::CONFIG_UPDATED)
+      end
+    end
+
+    # Build the config-fetch URL: +{config_endpoint}/config/{sdkKey}+ with an
+    # +environment+ query parameter appended only when one is configured.
+    def config_url
+      url = "#{@config.config_endpoint}/config/#{@config.sdk_key}"
+      env = @config.environment
+      return url if env.nil?
+
+      "#{url}?environment=#{URI.encode_www_form_component(env)}"
+    end
+
+    # The fetch headers: an +Authorization: Bearer {secret}+ value when a secret
+    # is configured, else none. The port (HttpClient) owns UA / HTTPS / Bearer
+    # plaintext-stripping mechanics — the Client only supplies the header VALUE.
+    def fetch_headers
+      secret = @config.sdk_key_secret
+      return {} if secret.nil?
+
+      { "Authorization" => "Bearer #{secret}" }
+    end
+
+    # Recursively normalise a (possibly symbol-keyed) config object to string
+    # keys — the public-boundary normalisation for direct data mode, so the
+    # installed snapshot matches the string-keyed fetched wire shape exactly.
+    def stringify_keys(node)
+      case node
+      when Hash
+        result = {} #: Hash[String, untyped]
+        node.each { |k, v| result[k.to_s] = stringify_keys(v) }
+        result
+      when Array
+        node.map { |element| stringify_keys(element) }
+      else
+        node
+      end
+    end
+  end
+end

data/lib/convert_sdk/comparisons.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+module ConvertSdk
+  # The 13 rule comparison operators — the cross-SDK audience-targeting predicate
+  # set, ported BYTE-FOR-BYTE from the JS SDK
+  # +packages/utils/src/comparisons.ts+.
+  #
+  # JS is the ONLY truth here. The PHP reference is QUARANTINED for this surface:
+  # it ships zero +exists+/+not_exists+ handling (a disk-verified gap) and folds
+  # case on the +isIn+ values side (a second divergence), so it must not influence
+  # the Ruby contract. Every operator below mirrors its JS body at the cited
+  # +comparisons.ts+ line; the goldens in the cross-SDK vector suite are the CI
+  # proof of parity.
+  #
+  # Two-worlds dispatch (operators): the platform sends operator names as
+  # camelCase WIRE strings inside the rule JSON (+equalsNumber+, +startsWith+, …).
+  # Those strings are config-world identifiers and stay byte-identical; the Ruby
+  # methods underneath are snake_case. {dispatch} is the map from the wire name to
+  # the Ruby method symbol, consumed by {RuleManager}.
+  #
+  # The undefined/nil distinction (the subtle one): JS distinguishes +undefined+
+  # (a data key is ABSENT) from +null+ (the key is present with a null value).
+  # Ruby hashes collapse both to +nil+, so absence is modeled EXPLICITLY with the
+  # frozen private {UNDEFINED} marker — {RuleManager} passes {UNDEFINED} for an
+  # absent key so the existence operators (and JS-parity need-more-data
+  # propagation) behave exactly as JS does with +undefined+. For the existence
+  # operators themselves +UNDEFINED+, +nil+, and +""+ are all "does not exist",
+  # matching +value !== undefined && value !== null && value !== ''+
+  # (+comparisons.ts:159+).
+  #
+  # Pure and stateless (NFR1): every method is a singleton (+self.+) method with
+  # no I/O and no instance state (the same module form as {MurmurHash3}).
+  #
+  # @api private
+  module Comparisons
+    # Sentinel for an ABSENT data key, distinct from +nil+ (a present null value).
+    # Frozen so it is a stable, comparable singleton. Mirrors JS +undefined+ on
+    # the rule-evaluation path.
+    UNDEFINED = Object.new.freeze
+
+    # JS +isNumeric+ regex (+string-utils.ts:69+): optional leading minus, then
+    # either grouped thousands (+1,234+) or plain digits, with an optional
+    # fractional part, or a bare fraction (+.5+).
+    NUMERIC_REGEXP = /\A-?(?:(?:\d{1,3}(?:,\d{3})+|\d+)(?:\.\d+)?|\.\d+)\z/
+
+    # Case-insensitive equality. Mirrors +comparisons.ts:15-40+:
+    # Array value -> membership of +test_against+; non-empty Hash value -> key
+    # membership; otherwise both sides are stringified, lowercased, and compared.
+    #
+    # @param value [Object] the data value (String, Numeric, Boolean, Array, Hash).
+    # @param test_against [Object] the rule's expected value.
+    # @param negation [Boolean] when true, the result is inverted.
+    # @return [Boolean]
+    def self.equals(value, test_against, negation = false)
+      return negation_check(value.include?(test_against), negation) if value.is_a?(Array)
+      return negation_check(value.key?(test_against.to_s), negation) if value.is_a?(Hash) && !value.empty?
+
+      negation_check(value.to_s.downcase == test_against.to_s.downcase, negation)
+    end
+
+    # Alias of {equals} (+comparisons.ts:42+ — +equalsNumber = this.equals+).
+    def self.equals_number(value, test_against, negation = false)
+      equals(value, test_against, negation)
+    end
+
+    # Alias of {equals} (+comparisons.ts:43+ — +matches = this.equals+).
+    def self.matches(value, test_against, negation = false)
+      equals(value, test_against, negation)
+    end
+
+    # Strict less-than over numerically-normalized inputs (+comparisons.ts:45-56+).
+    # Numeric-looking strings/numbers normalize to a number; anything else keeps
+    # its type. When the normalized types differ the result is +false+ (JS
+    # +typeof value !== typeof testAgainst+, ts:52-54).
+    #
+    # @return [Boolean]
+    def self.less(value, test_against, negation = false)
+      compare_numeric(value, test_against, negation) { |a, b| a < b }
+    end
+
+    # Less-than-or-equal counterpart of {less} (+comparisons.ts:58-69+).
+    #
+    # @return [Boolean]
+    def self.less_equal(value, test_against, negation = false)
+      compare_numeric(value, test_against, negation) { |a, b| a <= b }
+    end
+
+    # Case-insensitive substring test (+comparisons.ts:71-87+). PRESERVED JS
+    # quirk: an empty or whitespace-only +test_against+ returns +true+
+    # (ts:80-81) — do not "fix" it.
+    #
+    # @return [Boolean]
+    def self.contains(value, test_against, negation = false)
+      value = value.to_s.downcase
+      test_against = test_against.to_s.downcase
+      return negation_check(true, negation) if test_against.gsub(/\A\s*|\s*\z/, "").empty?
+
+      negation_check(value.include?(test_against), negation)
+    end
+
+    # Pipe-split membership (+comparisons.ts:89-115+). BOTH +values+ and a string
+    # +test_against+ are split on the +splitter+. Only the +test_against+ items
+    # are lowercased after splitting; the +values+ items are compared AS-IS
+    # against the lowercased list (so an uppercased value does not match a
+    # lowercased entry — exact JS semantics at ts:106-110).
+    #
+    # @param values [Object] the data value (pipe-joined string or scalar).
+    # @param test_against [Object] an Array, or a pipe-joined string to split.
+    # @param negation [Boolean]
+    # @param splitter [String] the delimiter (default +"|"+).
+    # @return [Boolean]
+    def self.is_in(values, test_against, negation = false, splitter = "|")
+      matched_values = values.to_s.split(splitter, -1).map(&:to_s)
+      test_against = test_against.split(splitter, -1) if test_against.is_a?(String)
+      unless test_against.is_a?(Array)
+        test_against = [] #: Array[untyped]
+      end
+      test_against = test_against.map { |item| item.to_s.downcase }
+      negation_check(matched_values.any? { |item| test_against.include?(item) }, negation)
+    end
+
+    # Case-insensitive prefix test (+comparisons.ts:117-128+ — +indexOf === 0+).
+    #
+    # @return [Boolean]
+    def self.starts_with(value, test_against, negation = false)
+      value = value.to_s.downcase
+      test_against = test_against.to_s.downcase
+      negation_check(value.start_with?(test_against), negation)
+    end
+
+    # Case-insensitive suffix test (+comparisons.ts:130-141+).
+    #
+    # @return [Boolean]
+    def self.ends_with(value, test_against, negation = false)
+      value = value.to_s.downcase
+      test_against = test_against.to_s.downcase
+      negation_check(value.end_with?(test_against), negation)
+    end
+
+    # Case-insensitive regex test (+comparisons.ts:143-152+ — +new RegExp(t, 'i')+).
+    # +value+ is lowercased; the pattern keeps its case but matches
+    # case-insensitively via the +i+ flag.
+    #
+    # @return [Boolean]
+    def self.regex_matches(value, test_against, negation = false)
+      value = value.to_s.downcase
+      pattern = Regexp.new(test_against.to_s, Regexp::IGNORECASE)
+      negation_check(!pattern.match(value).nil?, negation)
+    end
+
+    # Presence test (+comparisons.ts:154-161+): true unless the value is
+    # +UNDEFINED+ (JS +undefined+), +nil+ (JS +null+), or the empty string.
+    #
+    # @return [Boolean]
+    def self.exists(value, _test_against = nil, negation = false)
+      value_exists = !value.equal?(UNDEFINED) && !value.nil? && value != ""
+      negation_check(value_exists, negation)
+    end
+
+    # Absence test — the logical inverse of {exists} (+comparisons.ts:163-170+).
+    #
+    # @return [Boolean]
+    def self.not_exists(value, _test_against = nil, negation = false)
+      value_not_exists = value.equal?(UNDEFINED) || value.nil? || value == ""
+      negation_check(value_not_exists, negation)
+    end
+
+    # Alias of {not_exists} (+comparisons.ts:172+ — +doesNotExist = this.not_exists+).
+    def self.does_not_exist(value, test_against = nil, negation = false)
+      not_exists(value, test_against, negation)
+    end
+
+    # Maps each wire comparison operator name to its implementing method symbol.
+    DISPATCH = {
+      "equals" => :equals,
+      "equalsNumber" => :equals_number,
+      "matches" => :matches,
+      "less" => :less,
+      "lessEqual" => :less_equal,
+      "contains" => :contains,
+      "isIn" => :is_in,
+      "startsWith" => :starts_with,
+      "endsWith" => :ends_with,
+      "regexMatches" => :regex_matches,
+      "exists" => :exists,
+      "not_exists" => :not_exists,
+      "doesNotExist" => :does_not_exist
+    }.freeze
+
+    # The wire-name -> Ruby-method dispatch map (the two-worlds rule for
+    # operators). Keys are byte-identical to the rule JSON +match_type+ strings;
+    # {RuleManager} looks an operator up here and invokes the mapped method.
+    #
+    # @return [Hash{String=>Symbol}] frozen 13-entry map.
+    def self.dispatch
+      DISPATCH
+    end
+
+    # JS +isNumeric+ (+string-utils.ts:68-74+): numbers are numeric when finite;
+    # strings are numeric only when they match {NUMERIC_REGEXP} and parse finite.
+    # @api private
+    def self.numeric?(value)
+      return value.finite? if value.is_a?(Numeric)
+      return false unless value.is_a?(String) && NUMERIC_REGEXP.match?(value)
+
+      Float(value.delete(",")).finite?
+    rescue ArgumentError, TypeError
+      false
+    end
+
+    # JS +toNumber+ (+string-utils.ts:81-91+): numbers pass through; strings with
+    # a leading +"0"+ thousands segment treat commas as decimal points (all commas
+    # replaced with dots via +tr+, matching JS's global +replace(/,/g, '.')+),
+    # otherwise commas are stripped. The result is parsed with +to_f+ (lenient,
+    # never raises) — matching JS +parseFloat()+: the leading numeric portion is
+    # extracted and a trailing-garbage input like +"0.123.456"+ returns +0.123+
+    # rather than raising. This is a verified parity fix: Ruby +Float()+ (strict)
+    # raises on that input while JS +parseFloat+ and Ruby +to_f+ do not.
+    # @api private
+    def self.to_number(value)
+      return value if value.is_a?(Numeric)
+
+      str = value.to_s
+      parts = str.split(",")
+      normalized = parts[0] == "0" ? str.tr(",", ".") : str.delete(",")
+      normalized.to_f
+    end
+
+    # Numeric comparison core shared by {less}/{lessEqual}. Both sides are
+    # numerically normalized when numeric-looking; if the resulting types differ
+    # (one number, one non-number) the comparison is +false+ — JS ts:52-54/65-67.
+    # @api private
+    def self.compare_numeric(value, test_against, negation)
+      value = to_number(value) if numeric?(value)
+      test_against = to_number(test_against) if numeric?(test_against)
+      return negation_check(false, negation) unless same_compare_type?(value, test_against)
+
+      negation_check(yield(value, test_against), negation)
+    end
+
+    # JS +typeof+ parity for the {compare_numeric} guard: a normalized numeric is
+    # type "number"; everything else compares by whether BOTH are Numeric or
+    # NEITHER is (a String stays "string").
+    # @api private
+    def self.same_compare_type?(value, test_against)
+      value.is_a?(Numeric) == test_against.is_a?(Numeric)
+    end
+
+    # JS +_returnNegationCheck+ (+comparisons.ts:174-183+): invert when negated.
+    # @api private
+    def self.negation_check(result, negation)
+      negation ? !result : result
+    end
+
+    private_class_method :compare_numeric, :same_compare_type?, :negation_check
+  end
+end