liteguard 0.2.20260314

data/lib/liteguard/client.rb

@@ -0,0 +1,1282 @@
+require "json"
+require "net/http"
+require "objspace"
+require "uri"
+require "monitor"
+
+module Liteguard
+  # Core Liteguard SDK client.
+  #
+  # This class is the primary Ruby SDK entrypoint.
+  class Client
+    DEFAULT_BACKEND_URL = "https://api.liteguard.io"
+    DEFAULT_REFRESH_RATE = 30
+    DEFAULT_FLUSH_RATE = 10
+    DEFAULT_FLUSH_SIZE = 500
+    DEFAULT_HTTP_TIMEOUT = 4
+    DEFAULT_FLUSH_BUFFER_MULTIPLIER = 4
+    PUBLIC_BUNDLE_KEY = "".freeze
+
+    GuardBundle = Struct.new(
+      :key,
+      :guards,
+      :ready,
+      :etag,
+      :protected_context,
+      :refresh_rate_seconds,
+      keyword_init: true
+    )
+
+    # Create a client instance.
+    #
+    # The client remains idle until {#start} is called.
+    #
+    # @param project_client_key_id [String] project client key identifier from
+    #   the Liteguard control plane
+    # @param opts [Hash] initialization options
+    # @option opts [String, nil] :environment environment slug to send with API
+    #   requests
+    # @option opts [Boolean] :fallback result returned when a bundle is not yet
+    #   ready
+    # @option opts [Integer] :refresh_rate_seconds minimum refresh interval for
+    #   guard bundles
+    # @option opts [Integer] :flush_rate_seconds telemetry flush interval
+    # @option opts [Integer] :flush_size number of signals buffered before an
+    #   eager flush
+    # @option opts [Integer] :http_timeout_seconds connect and read timeout for
+    #   API calls
+    # @option opts [Integer] :flush_buffer_multiplier multiplier used to cap the
+    #   in-memory signal queue size
+    # @option opts [String] :backend_url base Liteguard API URL
+    # @option opts [Boolean] :quiet suppress warning output when `true`
+    # @option opts [Boolean] :disable_measurement disable telemetry measurements
+    # @return [void]
+    def initialize(project_client_key_id, opts = {})
+      @project_client_key_id = project_client_key_id
+      @environment = opts.fetch(:environment, "").to_s
+      @fallback = opts.fetch(:fallback, false)
+      @refresh_rate = normalize_positive_option(opts[:refresh_rate_seconds], DEFAULT_REFRESH_RATE)
+      @flush_rate = normalize_positive_option(opts[:flush_rate_seconds], DEFAULT_FLUSH_RATE)
+      @flush_size = normalize_positive_option(opts[:flush_size], DEFAULT_FLUSH_SIZE)
+      @http_timeout_seconds = normalize_positive_option(opts[:http_timeout_seconds], DEFAULT_HTTP_TIMEOUT)
+      @flush_buffer_multiplier = normalize_positive_option(
+        opts[:flush_buffer_multiplier],
+        DEFAULT_FLUSH_BUFFER_MULTIPLIER
+      )
+      @backend_url = opts.fetch(:backend_url, DEFAULT_BACKEND_URL).to_s.chomp("/")
+      @backend_url = DEFAULT_BACKEND_URL if @backend_url.empty?
+      @quiet = opts.fetch(:quiet, true)
+      @disable_measurement = opts.fetch(:disable_measurement, false)
+
+      @monitor = Monitor.new
+      @refresh_cond = @monitor.new_cond
+      @flush_cond = @monitor.new_cond
+      @stopped = false
+      @refresh_wakeup_requested = false
+      @flush_requested = false
+      @async_flush_scheduled = false
+      @current_refresh_rate = @refresh_rate
+
+      @bundles = { PUBLIC_BUNDLE_KEY => create_empty_bundle(PUBLIC_BUNDLE_KEY, nil) }
+      @default_scope = Scope.new(self, {}, PUBLIC_BUNDLE_KEY, nil)
+      @active_scope_key = "liteguard_active_scope_#{object_id}"
+
+      @signal_buffer = []
+      @dropped_signals_pending = 0
+      @reported_unadopted_guards = {}
+      @pending_unadopted_guards = {}
+      @rate_limit_state = {}
+    end
+
+    # Perform the initial bundle fetch and start background worker threads.
+    #
+    # @return [void]
+    def start
+      fetch_guards_for_bundle(PUBLIC_BUNDLE_KEY)
+      @refresh_thread = Thread.new { refresh_loop }
+      @flush_thread = Thread.new { flush_loop }
+      @refresh_thread.abort_on_exception = false
+      @flush_thread.abort_on_exception = false
+    end
+
+    # Stop background workers and flush remaining telemetry.
+    #
+    # @return [void]
+    def shutdown
+      @monitor.synchronize do
+        @stopped = true
+        @flush_requested = true
+        @refresh_cond.broadcast
+        @flush_cond.broadcast
+      end
+      shutdown_timeout = @http_timeout_seconds
+      @refresh_thread&.join(shutdown_timeout)
+      @flush_thread&.join(shutdown_timeout)
+      flush_signals
+    end
+
+    # Run a block in a correlated execution scope.
+    #
+    # Signals emitted inside the block share an execution identifier and parent
+    # relationships so that related checks and executions can be stitched
+    # together server-side.
+    #
+    # @yield Runs inside a correlated execution scope
+    # @return [Object] the block return value
+    def with_execution
+      existing = Thread.current[:liteguard_execution_state]
+      return yield if existing
+
+      Thread.current[:liteguard_execution_state] = {
+        execution_id: next_signal_id,
+        sequence_number: 0,
+        last_signal_id: nil,
+      }
+      begin
+        yield
+      ensure
+        Thread.current[:liteguard_execution_state] = nil
+      end
+    end
+
+    # ---------------------------------------------------------------------
+    # Scope API
+    # ---------------------------------------------------------------------
+
+    # Create an immutable request scope for explicit evaluation.
+    #
+    # @param properties [Hash] request-scoped properties to attach
+    # @return [Scope] a new immutable scope
+    def create_scope(properties = {})
+      Scope.new(self, normalize_properties(properties), PUBLIC_BUNDLE_KEY, nil)
+    end
+
+    # Return the active scope for the current thread.
+    #
+    # @return [Scope] the active scope, or the default scope when none is bound
+    def active_scope
+      scope = Thread.current[@active_scope_key]
+      return scope if scope.is_a?(Scope) && scope.belongs_to?(self)
+
+      @default_scope
+    end
+
+    # Bind a scope for the duration of a block.
+    #
+    # @param scope [Scope, nil] scope to bind, or `nil` to reuse the current
+    #   scope
+    # @yield Runs with the resolved scope bound as active
+    # @return [Object] the block return value
+    # @raise [ArgumentError] if no block is given or the scope belongs to a
+    #   different client
+    def with_scope(scope)
+      raise ArgumentError, "with_scope requires a block" unless block_given?
+
+      resolved = resolve_scope(scope)
+      previous = Thread.current[@active_scope_key]
+      Thread.current[@active_scope_key] = resolved
+      begin
+        yield
+      ensure
+        if previous.nil?
+          Thread.current[@active_scope_key] = nil
+        else
+          Thread.current[@active_scope_key] = previous
+        end
+      end
+    end
+
+    # Merge properties over the current scope for the duration of a block.
+    #
+    # @param properties [Hash] properties to merge
+    # @yield Runs with a derived scope bound as active
+    # @return [Object] the block return value
+    # @raise [ArgumentError] if no block is given
+    def with_properties(properties)
+      raise ArgumentError, "with_properties requires a block" unless block_given?
+
+      with_scope(active_scope.with_properties(properties)) { yield }
+    end
+
+    # Bind a protected context for the duration of a block.
+    #
+    # @param protected_context [ProtectedContext, Hash] signed protected context
+    # @yield Runs with a derived protected-context scope bound as active
+    # @return [Object] the block return value
+    # @raise [ArgumentError] if no block is given
+    def with_protected_context(protected_context)
+      raise ArgumentError, "with_protected_context requires a block" unless block_given?
+
+      with_scope(active_scope.bind_protected_context(protected_context)) { yield }
+    end
+
+    # Replace the active scope with one that includes merged properties.
+    #
+    # @param properties [Hash] properties to merge into the active scope
+    # @return [Scope] the derived active scope
+    def add_properties(properties)
+      replace_current_scope(active_scope.with_properties(properties))
+    end
+
+    # Replace the active scope with one that omits the named properties.
+    #
+    # @param names [Array<String, Symbol>] property names to remove
+    # @return [Scope] the derived active scope
+    def clear_properties(names)
+      replace_current_scope(active_scope.clear_properties(Array(names).map(&:to_s)))
+    end
+
+    # Replace the active scope with an empty property scope.
+    #
+    # @return [Scope] the derived active scope
+    def reset_properties
+      replace_current_scope(active_scope.reset_properties)
+    end
+
+    # Replace the active scope with a protected-context-derived scope.
+    #
+    # @param protected_context [ProtectedContext, Hash] signed protected context
+    # @return [Scope] the derived active scope
+    def bind_protected_context(protected_context)
+      replace_current_scope(active_scope.bind_protected_context(protected_context))
+    end
+
+    # Replace the active scope with one using the public bundle.
+    #
+    # @return [Scope] the derived active scope
+    def clear_protected_context
+      replace_current_scope(active_scope.clear_protected_context)
+    end
+
+    # Return the current thread's evaluation properties.
+    #
+    # @return [Hash] active scope properties
+    def context
+      active_scope.properties
+    end
+
+    # Replace the current thread's active scope.
+    #
+    # Mutation helpers are intentionally thread-local so request-scoped data
+    # cannot leak through the process-wide default scope.
+    #
+    # @param scope [Scope] scope to install
+    # @return [Scope] the resolved scope
+    def replace_current_scope(scope)
+      resolved = resolve_scope(scope)
+      Thread.current[@active_scope_key] = resolved
+      resolved
+    end
+
+    # Resolve a scope argument and verify that it belongs to this client.
+    #
+    # @param scope [Scope, nil] candidate scope
+    # @return [Scope] resolved scope
+    # @raise [ArgumentError] if the scope belongs to a different client
+    def resolve_scope(scope)
+      resolved = scope || active_scope
+      raise ArgumentError, "[liteguard] scope belongs to a different client" unless resolved.belongs_to?(self)
+
+      resolved
+    end
+
+    # Derive a scope bound to the bundle for the given protected context.
+    #
+    # @param scope [Scope] base scope
+    # @param protected_context [ProtectedContext, Hash] signed protected context
+    # @return [Scope] a derived scope
+    def bind_protected_context_to_scope(scope, protected_context)
+      resolve_scope(scope)
+      normalized = normalize_protected_context(protected_context)
+      bundle_key = ensure_bundle_for_protected_context(normalized)
+      Scope.new(self, scope.properties, bundle_key, normalized)
+    end
+
+    # Ensure the public bundle is available before returning.
+    #
+    # @return [void]
+    def ensure_public_bundle_ready
+      bundle = @monitor.synchronize { @bundles[PUBLIC_BUNDLE_KEY] }
+      return if bundle&.ready
+
+      fetch_guards_for_bundle(PUBLIC_BUNDLE_KEY)
+    end
+
+    # ---------------------------------------------------------------------
+    # Core API
+    # ---------------------------------------------------------------------
+
+    # Evaluate a guard in the active scope and emit telemetry.
+    #
+    # @param name [String] guard name to evaluate
+    # @param options [Hash, nil] optional per-call overrides
+    # @return [Boolean] `true` when the guard resolves open
+    def is_open(name, options = nil, **legacy_options)
+      options = normalize_is_open_options(options, legacy_options)
+      evaluate_guard_in_scope(active_scope, name.to_s, options, emit_signal: true)[:result]
+    end
+
+    # Evaluate a guard in the provided scope and emit telemetry.
+    #
+    # @param scope [Scope] scope to evaluate against
+    # @param name [String] guard name to evaluate
+    # @param options [Hash, nil] optional per-call overrides
+    # @return [Boolean] `true` when the guard resolves open
+    def is_open_in_scope(scope, name, options = nil, **legacy_options)
+      options = normalize_is_open_options(options, legacy_options)
+      evaluate_guard_in_scope(scope, name.to_s, options, emit_signal: true)[:result]
+    end
+
+    # Evaluate a guard in the active scope without emitting telemetry.
+    #
+    # @param name [String] guard name to evaluate
+    # @param options [Hash, nil] optional per-call overrides
+    # @return [Boolean] `true` when the guard resolves open
+    def peek_is_open(name, options = nil, **legacy_options)
+      options = normalize_is_open_options(options, legacy_options)
+      evaluate_guard_in_scope(active_scope, name.to_s, options, emit_signal: false)[:result]
+    end
+
+    # Evaluate a guard in the provided scope without emitting telemetry.
+    #
+    # @param scope [Scope] scope to evaluate against
+    # @param name [String] guard name to evaluate
+    # @param options [Hash, nil] optional per-call overrides
+    # @return [Boolean] `true` when the guard resolves open
+    def peek_is_open_in_scope(scope, name, options = nil, **legacy_options)
+      options = normalize_is_open_options(options, legacy_options)
+      evaluate_guard_in_scope(scope, name.to_s, options, emit_signal: false)[:result]
+    end
+
+    # Evaluate a guard and execute the block only when it resolves open.
+    #
+    # @param name [String] guard name to evaluate
+    # @param options [Hash, nil] optional per-call overrides
+    # @yield Runs only when the guard resolves open
+    # @return [Object, nil] the block return value, or `nil` when the guard is
+    #   closed
+    # @raise [ArgumentError] if no block is given
+    def execute_if_open(name, options = nil, **legacy_options)
+      raise ArgumentError, "execute_if_open requires a block" unless block_given?
+
+      with_execution do
+        normalized_options = normalize_is_open_options(options, legacy_options)
+        evaluation = evaluate_guard_in_scope(active_scope, name.to_s, normalized_options, emit_signal: true)
+        return nil unless evaluation[:result]
+        return yield if evaluation[:signal].nil?
+
+        measurement_enabled = measurement_enabled?(evaluation[:guard], normalized_options)
+        started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)
+        begin
+          value = yield
+          buffer_signal(
+            name.to_s,
+            true,
+            evaluation[:props],
+            kind: "guard_execution",
+            measurement: measurement_enabled ? capture_guard_execution_measurement(started_at, true) : nil,
+            parent_signal_id_override: evaluation[:signal].signal_id
+          )
+          value
+        rescue Exception => e # rubocop:disable Lint/RescueException
+          buffer_signal(
+            name.to_s,
+            true,
+            evaluation[:props],
+            kind: "guard_execution",
+            measurement: measurement_enabled ? capture_guard_execution_measurement(started_at, false, e) : nil,
+            parent_signal_id_override: evaluation[:signal].signal_id
+          )
+          raise
+        end
+      end
+    end
+
+    # Scope-aware wrapper for {#execute_if_open}.
+    #
+    # @param scope [Scope] scope to evaluate against
+    # @param name [String] guard name to evaluate
+    # @param options [Hash, nil] optional per-call overrides
+    # @yield Runs only when the guard resolves open
+    # @return [Object, nil] the block return value, or `nil` when the guard is
+    #   closed
+    def execute_if_open_in_scope(scope, name, options = nil, **legacy_options, &block)
+      with_scope(scope) { execute_if_open(name, options, **legacy_options, &block) }
+    end
+
+    # Evaluate a guard within a resolved scope and optionally emit telemetry.
+    #
+    # @param scope [Scope] scope to evaluate against
+    # @param name [String] guard name to evaluate
+    # @param options [Hash] normalized evaluation options
+    # @param emit_signal [Boolean] whether to buffer a `guard_check` signal
+    # @return [Hash] evaluation result metadata including `:result`, `:guard`,
+    #   `:props`, and `:signal`
+    def evaluate_guard_in_scope(scope, name, options, emit_signal:)
+      resolved_scope = resolve_scope(scope)
+      bundle = bundle_for_scope(resolved_scope)
+      effective_fallback = options[:fallback].nil? ? @fallback : options[:fallback]
+      return { result: effective_fallback, guard: nil, props: nil, signal: nil } unless bundle.ready
+
+      guard = bundle.guards[name]
+      if guard.nil?
+        record_unadopted_guard(name)
+        return { result: true, guard: nil, props: nil, signal: nil }
+      end
+      unless guard.adopted
+        record_unadopted_guard(name)
+        return { result: true, guard: guard, props: nil, signal: nil }
+      end
+
+      props = resolved_scope.properties
+      if options[:properties]
+        props = props.merge(options[:properties])
+      end
+
+      result = Evaluation.evaluate_guard(guard, props)
+      if result && guard.rate_limit_per_minute.to_i > 0
+        result = if emit_signal
+          check_rate_limit(name, guard.rate_limit_per_minute, guard.rate_limit_properties, props)
+        else
+          would_pass_rate_limit(name, guard.rate_limit_per_minute, guard.rate_limit_properties, props)
+        end
+      end
+
+      signal = nil
+      if emit_signal
+        signal = buffer_signal(
+          name,
+          result,
+          props,
+          kind: "guard_check",
+          measurement: measurement_enabled?(guard, options) ? capture_guard_check_measurement : nil
+        )
+      end
+
+      { result: result, guard: guard, props: props, signal: signal }
+    end
+
+    # ---------------------------------------------------------------------
+    # Signals
+    # ---------------------------------------------------------------------
+
+    # Flush all buffered telemetry and unadopted guard reports.
+    #
+    # @return [void]
+    def flush_signals
+      batch, unadopted_guard_names = @monitor.synchronize do
+        buffered = @signal_buffer.dup
+        @signal_buffer.clear
+        names = @pending_unadopted_guards.keys.sort
+        @pending_unadopted_guards.clear
+        [buffered, names]
+      end
+      return if batch.empty? && unadopted_guard_names.empty?
+
+      flush_signal_batch(batch) unless batch.empty?
+      flush_unadopted_guards(unadopted_guard_names) unless unadopted_guard_names.empty?
+    end
+
+    # Upload a batch of buffered signals.
+    #
+    # Failed uploads are returned to the in-memory queue subject to buffer
+    # limits.
+    #
+    # @param batch [Array<Signal>] signal batch to upload
+    # @return [void]
+    def flush_signal_batch(batch)
+      payload = JSON.generate(
+        projectClientKeyId: @project_client_key_id,
+        environment: @environment,
+        signals: batch.map do |signal|
+          {
+            guardName: signal.guard_name,
+            result: signal.result,
+            properties: signal.properties,
+            timestampMs: signal.timestamp_ms,
+            signalId: signal.signal_id,
+            executionId: signal.execution_id,
+            sequenceNumber: signal.sequence_number,
+            callsiteId: signal.callsite_id,
+            kind: signal.kind,
+            droppedSignalsSinceLast: signal.dropped_signals_since_last,
+            **(signal.parent_signal_id ? { parentSignalId: signal.parent_signal_id } : {}),
+            **(signal.measurement ? { measurement: signal_measurement_payload(signal.measurement) } : {})
+          }
+        end
+      )
+      post_json("/api/v1/signals", payload)
+    rescue => e
+      log "[liteguard] signal flush failed: #{e}"
+      @monitor.synchronize do
+        @signal_buffer.unshift(*batch)
+        max_buf = max_buffer_size
+        if @signal_buffer.size > max_buf
+          @dropped_signals_pending += @signal_buffer.size - max_buf
+          @signal_buffer.pop(@signal_buffer.size - max_buf)
+        end
+      end
+    end
+
+    # Upload unadopted guard names discovered during evaluation.
+    #
+    # @param unadopted_guard_names [Array<String>] guard names to report
+    # @return [void]
+    def flush_unadopted_guards(unadopted_guard_names)
+      payload = JSON.generate(
+        projectClientKeyId: @project_client_key_id,
+        environment: @environment,
+        guardNames: unadopted_guard_names
+      )
+      post_json("/api/v1/unadopted-guards", payload)
+    rescue => e
+      log "[liteguard] unadopted guard flush failed: #{e}"
+      @monitor.synchronize do
+        unadopted_guard_names.each { |name| @pending_unadopted_guards[name] = true }
+      end
+    end
+
+    # Buffer a signal for asynchronous upload.
+    #
+    # @param guard_name [String] guard name associated with the signal
+    # @param result [Boolean] guard result associated with the signal
+    # @param props [Hash] evaluation properties snapshot
+    # @param kind [String] signal kind such as `guard_check` or
+    #   `guard_execution`
+    # @param measurement [SignalPerformance, nil] optional measurement payload
+    # @param parent_signal_id_override [String, nil] explicit parent signal ID
+    # @return [Signal] buffered signal instance
+    def buffer_signal(guard_name, result, props, kind:, measurement: nil, parent_signal_id_override: nil)
+      metadata = next_signal_metadata(parent_signal_id_override)
+      signal = Signal.new(
+        guard_name: guard_name,
+        result: result,
+        properties: props.dup,
+        timestamp_ms: (Time.now.to_f * 1000).to_i,
+        trace: nil,
+        signal_id: metadata[:signal_id],
+        execution_id: metadata[:execution_id],
+        parent_signal_id: metadata[:parent_signal_id],
+        sequence_number: metadata[:sequence_number],
+        callsite_id: capture_callsite_id,
+        kind: kind,
+        dropped_signals_since_last: take_dropped_signals,
+        measurement: measurement
+      )
+      should_flush = false
+      @monitor.synchronize do
+        if @signal_buffer.size >= max_buffer_size
+          @signal_buffer.shift
+          @dropped_signals_pending += 1
+        end
+        @signal_buffer << signal
+        should_flush = @signal_buffer.size >= @flush_size
+      end
+      schedule_async_flush if should_flush
+      signal
+    end
+
+    # Request a background flush without doing network I/O on the caller path.
+    #
+    # @return [void]
+    def schedule_async_flush
+      spawn_worker = false
+
+      @monitor.synchronize do
+        if @flush_thread&.alive?
+          @flush_requested = true
+          @flush_cond.broadcast
+        elsif !@async_flush_scheduled
+          @async_flush_scheduled = true
+          spawn_worker = true
+        end
+      end
+
+      return unless spawn_worker
+
+      worker = Thread.new do
+        begin
+          flush_signals
+        ensure
+          reschedule = false
+          @monitor.synchronize do
+            @async_flush_scheduled = false
+            reschedule = !@stopped && @signal_buffer.size >= @flush_size
+          end
+          schedule_async_flush if reschedule
+        end
+      end
+      worker.abort_on_exception = false
+      worker.report_on_exception = false if worker.respond_to?(:report_on_exception=)
+    end
+
+    # Build correlation metadata for the next signal.
+    #
+    # @param parent_signal_id_override [String, nil] explicit parent signal ID
+    # @return [Hash] signal correlation metadata
+    def next_signal_metadata(parent_signal_id_override = nil)
+      signal_id = next_signal_id
+      state = Thread.current[:liteguard_execution_state]
+      unless state
+        return {
+          signal_id: signal_id,
+          execution_id: next_signal_id,
+          parent_signal_id: nil,
+          sequence_number: 1
+        }
+      end
+
+      state[:sequence_number] += 1
+      parent_signal_id = parent_signal_id_override || state[:last_signal_id]
+      state[:last_signal_id] = signal_id
+      {
+        signal_id: signal_id,
+        execution_id: state[:execution_id],
+        parent_signal_id: parent_signal_id,
+        sequence_number: state[:sequence_number]
+      }
+    end
+
+    # Generate a unique signal identifier.
+    #
+    # @return [String] unique signal ID
+    def next_signal_id
+      @signal_counter ||= 0
+      @signal_counter += 1
+      "#{Process.clock_gettime(Process::CLOCK_REALTIME, :nanosecond).to_s(16)}-#{@signal_counter.to_s(16)}"
+    end
+
+    # Consume and reset the dropped-signal counter.
+    #
+    # @return [Integer] number of dropped signals since the last emitted signal
+    def take_dropped_signals
+      @monitor.synchronize do
+        dropped = @dropped_signals_pending
+        @dropped_signals_pending = 0
+        dropped
+      end
+    end
+
+    # Return the maximum in-memory signal buffer size.
+    #
+    # @return [Integer] maximum signal count retained before dropping oldest
+    def max_buffer_size
+      @flush_size * @flush_buffer_multiplier
+    end
+
+    # ---------------------------------------------------------------------
+    # Guard refresh
+    # ---------------------------------------------------------------------
+
+    # Create a placeholder bundle entry before the first fetch completes.
+    #
+    # @param bundle_key [String] cache key for the bundle
+    # @param protected_context [ProtectedContext, nil] protected context backing
+    #   the bundle
+    # @return [GuardBundle] empty bundle record
+    def create_empty_bundle(bundle_key, protected_context)
+      GuardBundle.new(
+        key: bundle_key,
+        guards: {},
+        ready: false,
+        etag: "",
+        protected_context: protected_context ? copy_protected_context(protected_context) : nil,
+        refresh_rate_seconds: @refresh_rate
+      )
+    end
+
+    # Look up the bundle associated with a scope.
+    #
+    # @param scope [Scope] scope whose bundle should be resolved
+    # @return [GuardBundle] resolved bundle, or the public bundle fallback
+    def bundle_for_scope(scope)
+      @monitor.synchronize do
+        @bundles[scope.bundle_key] || @bundles[PUBLIC_BUNDLE_KEY]
+      end
+    end
+
+    # Ensure a bundle exists for the given protected context and fetch it if
+    # needed.
+    #
+    # @param protected_context [ProtectedContext] normalized protected context
+    # @return [String] cache key for the bundle
+    def ensure_bundle_for_protected_context(protected_context)
+      bundle_key = protected_context_cache_key(protected_context)
+      ready = @monitor.synchronize do
+        @bundles[bundle_key] ||= create_empty_bundle(bundle_key, protected_context)
+        @bundles[bundle_key].ready
+      end
+      return bundle_key if ready
+
+      fetch_guards_for_bundle(bundle_key)
+      bundle_key
+    end
+
+    # Build a stable cache key for a protected context.
+    #
+    # @param protected_context [ProtectedContext, nil] protected context to hash
+    # @return [String] bundle cache key
+    def protected_context_cache_key(protected_context)
+      return PUBLIC_BUNDLE_KEY if protected_context.nil?
+
+      keys = protected_context.properties.keys.sort
+      parts = [protected_context.signature, ""]
+      keys.each do |key|
+        parts << "#{key}=#{protected_context.properties[key]}"
+      end
+      parts.join("\x00")
+    end
+
+    # Wake the refresh loop so it can recompute its next wait interval.
+    #
+    # @return [void]
+    def request_refresh_reschedule
+      @monitor.synchronize do
+        @refresh_wakeup_requested = true
+        @refresh_cond.signal
+      end
+    end
+
+    # Fetch guard data for a bundle from the Liteguard backend.
+    #
+    # @param bundle_key [String] bundle cache key to refresh
+    # @return [void]
+    def fetch_guards_for_bundle(bundle_key)
+      bundle = @monitor.synchronize { @bundles[bundle_key] ||= create_empty_bundle(bundle_key, nil) }
+      protected_context = bundle.protected_context ? copy_protected_context(bundle.protected_context) : nil
+
+      payload = {
+        projectClientKeyId: @project_client_key_id,
+        environment: @environment
+      }
+      if protected_context
+        payload[:protectedContext] = {
+          properties: protected_context.properties,
+          signature: protected_context.signature
+        }
+      end
+
+      uri = URI("#{@backend_url}/api/v1/guards")
+      req = Net::HTTP::Post.new(uri)
+      req["Authorization"] = "Bearer #{@project_client_key_id}"
+      req["Content-Type"] = "application/json"
+      req["If-None-Match"] = bundle.etag unless bundle.etag.to_s.empty?
+      req.body = JSON.generate(payload)
+
+      response = Net::HTTP.start(
+        uri.host,
+        uri.port,
+        use_ssl: uri.scheme == "https",
+        open_timeout: @http_timeout_seconds,
+        read_timeout: @http_timeout_seconds
+      ) { |http| http.request(req) }
+
+      return if response.code == "304"
+      return log("[liteguard] guard fetch returned #{response.code}") unless response.code == "200"
+
+      body = JSON.parse(response.body)
+      server_refresh_rate = body["refreshRateSeconds"].to_i
+      effective_refresh_rate = if server_refresh_rate.positive?
+        [@refresh_rate, server_refresh_rate].max
+      else
+        @refresh_rate
+      end
+      guards = (body["guards"] || []).map { |raw_guard| parse_guard(raw_guard) }
+      refresh_rate_changed = false
+      @monitor.synchronize do
+        previous_refresh_rate = @current_refresh_rate
+        @bundles[bundle_key] = GuardBundle.new(
+          key: bundle_key,
+          guards: guards.each_with_object({}) { |guard, acc| acc[guard.name] = guard },
+          ready: true,
+          etag: body["etag"] || "",
+          protected_context: protected_context,
+          refresh_rate_seconds: effective_refresh_rate
+        )
+        recompute_refresh_interval_locked
+        refresh_rate_changed = @current_refresh_rate != previous_refresh_rate
+      end
+      request_refresh_reschedule if refresh_rate_changed
+    rescue => e
+      log "[liteguard] guard fetch error: #{e}"
+    end
+
+    # Recompute the shortest refresh interval across all known bundles.
+    #
+    # @return [void]
+    def recompute_refresh_interval_locked
+      next_refresh_rate = @bundles.values.map(&:refresh_rate_seconds).select(&:positive?).min
+      @current_refresh_rate = next_refresh_rate || @refresh_rate
+    end
+
+    # Background loop that periodically refreshes guard bundles.
+    #
+    # @return [void]
+    def refresh_loop
+      @monitor.synchronize do
+        until @stopped
+          @refresh_cond.wait(@current_refresh_rate)
+          break if @stopped
+          if @refresh_wakeup_requested
+            @refresh_wakeup_requested = false
+            next
+          end
+          bundle_keys = @bundles.keys.sort
+          @monitor.mon_exit
+          begin
+            bundle_keys.each { |bundle_key| fetch_guards_for_bundle(bundle_key) }
+          ensure
+            @monitor.mon_enter
+          end
+        end
+      end
+    end
+
+    # Background loop that periodically flushes buffered telemetry.
+    #
+    # @return [void]
+    def flush_loop
+      @monitor.synchronize do
+        until @stopped
+          @flush_cond.wait(@flush_rate)
+          break if @stopped
+          @flush_requested = false
+          @monitor.mon_exit
+          begin
+            flush_signals
+          ensure
+            @monitor.mon_enter
+          end
+        end
+      end
+    end
+
+    # ---------------------------------------------------------------------
+    # Helpers
+    # ---------------------------------------------------------------------
+
+    # POST a JSON payload to the Liteguard backend.
+    #
+    # @param path [String] request path relative to `backend_url`
+    # @param payload [String] pre-encoded JSON payload
+    # @return [void]
+    # @raise [RuntimeError] when the response is not successful
+    def post_json(path, payload)
+      uri = URI("#{@backend_url}#{path}")
+      req = Net::HTTP::Post.new(uri)
+      req["Authorization"] = "Bearer #{@project_client_key_id}"
+      req["Content-Type"] = "application/json"
+      req["X-Liteguard-Environment"] = @environment unless @environment.empty?
+      req.body = payload
+
+      response = Net::HTTP.start(
+        uri.host,
+        uri.port,
+        use_ssl: uri.scheme == "https",
+        open_timeout: @http_timeout_seconds,
+        read_timeout: @http_timeout_seconds
+      ) { |http| http.request(req) }
+      raise "request returned #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+    end
+
+    # Parse a guard payload returned by the backend.
+    #
+    # @param raw [Hash] decoded guard payload
+    # @return [Guard] parsed guard record
+    def parse_guard(raw)
+      Guard.new(
+        name: raw["name"],
+        rules: (raw["rules"] || []).map { |rule| parse_rule(rule) },
+        default_value: !!raw["defaultValue"],
+        adopted: !!raw["adopted"],
+        rate_limit_per_minute: (raw["rateLimitPerMinute"] || 0).to_i,
+        rate_limit_properties: Array(raw["rateLimitProperties"]),
+        disable_measurement: raw.key?("disableMeasurement") ? raw["disableMeasurement"] : nil
+      )
+    end
+
+    # Parse a rule payload returned by the backend.
+    #
+    # @param raw [Hash] decoded rule payload
+    # @return [Rule] parsed rule record
+    def parse_rule(raw)
+      Rule.new(
+        property_name: raw["propertyName"],
+        operator: raw["operator"].downcase.to_sym,
+        values: raw["values"] || [],
+        result: !!raw["result"],
+        enabled: raw.fetch("enabled", true)
+      )
+    end
+
+    # Consume a rate-limit slot for an open guard evaluation.
+    #
+    # @param name [String] guard name
+    # @param limit_per_minute [Integer] allowed evaluations per minute
+    # @param rate_limit_properties [Array<String>] properties contributing to
+    #   the bucket key
+    # @param props [Hash] evaluation properties
+    # @return [Boolean] `true` when the evaluation is within the limit
+    def check_rate_limit(name, limit_per_minute, rate_limit_properties, props)
+      now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      key = rate_limit_bucket_key(name, rate_limit_properties, props)
+      @monitor.synchronize do
+        entry = @rate_limit_state[key] || { window_start: now, count: 0 }
+        entry = { window_start: now, count: 0 } if now - entry[:window_start] >= 60.0
+        if entry[:count] >= limit_per_minute
+          @rate_limit_state[key] = entry
+          return false
+        end
+        @rate_limit_state[key] = { window_start: entry[:window_start], count: entry[:count] + 1 }
+      end
+      true
+    end
+
+    # Check whether an evaluation would pass rate limiting without consuming a
+    # slot.
+    #
+    # @param name [String] guard name
+    # @param limit_per_minute [Integer] allowed evaluations per minute
+    # @param rate_limit_properties [Array<String>] properties contributing to
+    #   the bucket key
+    # @param props [Hash] evaluation properties
+    # @return [Boolean] `true` when the evaluation would pass the limit
+    def would_pass_rate_limit(name, limit_per_minute, rate_limit_properties, props)
+      now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      key = rate_limit_bucket_key(name, rate_limit_properties, props)
+      @monitor.synchronize do
+        entry = @rate_limit_state[key]
+        return true if entry.nil?
+        return true if now - entry[:window_start] >= 60.0
+
+        entry[:count] < limit_per_minute
+      end
+    end
+
+    # Build the cache key used for rate-limit buckets.
+    #
+    # @param name [String] guard name
+    # @param rate_limit_properties [Array<String>, nil] bucket property names
+    # @param props [Hash] evaluation properties
+    # @return [String] rate-limit bucket key
+    def rate_limit_bucket_key(name, rate_limit_properties, props)
+      return name if rate_limit_properties.nil? || rate_limit_properties.empty?
+
+      parts = rate_limit_properties.map { |property| "#{property}=#{props[property] || ''}" }
+      "#{name}\x00#{parts.join("\x00")}"
+    end
+
+    # Normalize a positive integer option, falling back to a default when the
+    # provided value is blank, zero, or negative.
+    #
+    # @param value [Object] raw option value
+    # @param default [Integer] default to use when normalization fails
+    # @return [Integer] normalized positive integer
+    def normalize_positive_option(value, default)
+      normalized = value.nil? ? default : value.to_i
+      normalized.positive? ? normalized : default
+    end
+
+    # Normalize guard-evaluation options into a canonical hash.
+    #
+    # @param options [Hash, nil] primary options hash
+    # @param legacy_options [Hash] keyword arguments merged on top
+    # @return [Hash] normalized option hash
+    # @raise [ArgumentError] when options are invalid or contain unknown keys
+    def normalize_is_open_options(options, legacy_options = {})
+      raw = if options.nil?
+        legacy_options
+      elsif options.is_a?(Hash)
+        options.merge(legacy_options)
+      else
+        raise ArgumentError, "is_open options must be a Hash"
+      end
+
+      unknown_keys = raw.keys.map(&:to_sym) - CHECK_OPTION_KEYS
+      raise ArgumentError, "unknown is_open option(s): #{unknown_keys.join(', ')}" unless unknown_keys.empty?
+
+      properties = raw[:properties] || raw["properties"]
+      {
+        properties: properties ? normalize_properties(properties) : nil,
+        fallback: raw.key?(:fallback) ? raw[:fallback] : raw["fallback"],
+        disable_measurement: raw.key?(:disable_measurement) ? raw[:disable_measurement] : raw["disable_measurement"] || false
+      }
+    end
+
+    # Normalize property keys to strings.
+    #
+    # @param properties [Hash, nil] raw property hash
+    # @return [Hash] normalized property hash
+    def normalize_properties(properties)
+      return {} if properties.nil?
+
+      properties.each_with_object({}) { |(key, value), acc| acc[key.to_s] = value }
+    end
+
+    # Normalize a protected-context payload into a `ProtectedContext` object.
+    #
+    # @param protected_context [ProtectedContext, Hash] raw protected context
+    # @return [ProtectedContext] normalized protected context
+    def normalize_protected_context(protected_context)
+      raw = if protected_context.is_a?(ProtectedContext)
+        { properties: protected_context.properties, signature: protected_context.signature }
+      else
+        protected_context
+      end
+      ProtectedContext.new(
+        properties: normalize_properties(raw[:properties] || raw["properties"] || {}),
+        signature: (raw[:signature] || raw["signature"]).to_s
+      )
+    end
+
+    # Return a defensive copy of a protected context.
+    #
+    # @param protected_context [ProtectedContext, nil] protected context to copy
+    # @return [ProtectedContext, nil] copied protected context or `nil`
+    def copy_protected_context(protected_context)
+      return nil if protected_context.nil?
+
+      ProtectedContext.new(
+        properties: protected_context.properties.dup,
+        signature: protected_context.signature.dup
+      )
+    end
+
+    # Determine whether measurement capture is enabled for an evaluation.
+    #
+    # @param guard [Guard, nil] guard being evaluated
+    # @param options [Hash] normalized evaluation options
+    # @return [Boolean] `true` when measurements should be captured
+    def measurement_enabled?(guard, options)
+      return false if @disable_measurement
+      return false if options[:disable_measurement]
+      return false if guard&.disable_measurement
+
+      true
+    end
+
+    # Capture process metrics for a guard-check signal.
+    #
+    # @return [SignalPerformance] measurement payload for a guard check
+    def capture_guard_check_measurement
+      gc_stats = GC.stat
+      SignalPerformance.new(
+        guard_check: GuardCheckPerformance.new(
+          rss_bytes: nil,
+          heap_used_bytes: gc_slot_bytes(gc_stats, :heap_live_slots),
+          heap_total_bytes: gc_slot_bytes(gc_stats, :heap_available_slots),
+          cpu_time_ns: Process.clock_gettime(Process::CLOCK_PROCESS_CPUTIME_ID, :nanosecond),
+          gc_count: gc_stat_value(gc_stats, :count),
+          thread_count: Thread.list.length
+        ),
+        guard_execution: nil
+      )
+    end
+
+    # Capture process metrics for a guard-execution signal.
+    #
+    # @param started_at [Integer] monotonic start time in nanoseconds
+    # @param completed [Boolean] whether the guarded block completed normally
+    # @param error [Exception, nil] exception raised by the guarded block
+    # @return [SignalPerformance] measurement payload for a guard execution
+    def capture_guard_execution_measurement(started_at, completed, error = nil)
+      gc_stats = GC.stat
+      SignalPerformance.new(
+        guard_check: nil,
+        guard_execution: GuardExecutionPerformance.new(
+          duration_ns: Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond) - started_at,
+          rss_end_bytes: nil,
+          heap_used_end_bytes: gc_slot_bytes(gc_stats, :heap_live_slots),
+          heap_total_end_bytes: gc_slot_bytes(gc_stats, :heap_available_slots),
+          cpu_time_end_ns: Process.clock_gettime(Process::CLOCK_PROCESS_CPUTIME_ID, :nanosecond),
+          gc_count_end: gc_stat_value(gc_stats, :count),
+          thread_count_end: Thread.list.length,
+          completed: completed,
+          error_class: error&.class&.name
+        )
+      )
+    end
+
+    # Safely extract an integer GC stat from the current runtime.
+    #
+    # @param stats [Hash] GC statistics hash
+    # @param key [Symbol] desired stat key
+    # @return [Integer, nil] integer stat value or `nil`
+    def gc_stat_value(stats, key)
+      value = stats[key]
+      value.is_a?(Numeric) ? value.to_i : nil
+    end
+
+    # Convert a GC slot count into bytes using the current Ruby slot size.
+    #
+    # @param stats [Hash] GC statistics hash
+    # @param key [Symbol] desired slot-count stat key
+    # @return [Integer, nil] byte count or `nil` when unavailable
+    def gc_slot_bytes(stats, key)
+      slots = gc_stat_value(stats, key)
+      slot_size = ruby_internal_constant(:RVALUE_SIZE)
+      return nil if slots.nil? || slot_size.nil?
+
+      slots * slot_size
+    end
+
+    # Safely read a Ruby VM internal constant.
+    #
+    # @param key [Symbol] desired constant name
+    # @return [Integer, nil] integer constant or `nil`
+    def ruby_internal_constant(key)
+      return nil unless defined?(GC::INTERNAL_CONSTANTS)
+
+      value = GC::INTERNAL_CONSTANTS[key]
+      value.is_a?(Numeric) ? value.to_i : nil
+    end
+
+    # Convert an internal measurement struct into the API payload shape.
+    #
+    # @param measurement [SignalPerformance] measurement to serialize
+    # @return [Hash] JSON-ready measurement payload
+    def signal_measurement_payload(measurement)
+      payload = {}
+      if measurement.guard_check
+        payload[:guardCheck] = {
+          rssBytes: measurement.guard_check.rss_bytes,
+          heapUsedBytes: measurement.guard_check.heap_used_bytes,
+          heapTotalBytes: measurement.guard_check.heap_total_bytes,
+          cpuTimeNs: measurement.guard_check.cpu_time_ns,
+          gcCount: measurement.guard_check.gc_count,
+          threadCount: measurement.guard_check.thread_count,
+        }
+      end
+      if measurement.guard_execution
+        payload[:guardExecution] = {
+          durationNs: measurement.guard_execution.duration_ns,
+          rssEndBytes: measurement.guard_execution.rss_end_bytes,
+          heapUsedEndBytes: measurement.guard_execution.heap_used_end_bytes,
+          heapTotalEndBytes: measurement.guard_execution.heap_total_end_bytes,
+          cpuTimeEndNs: measurement.guard_execution.cpu_time_end_ns,
+          gcCountEnd: measurement.guard_execution.gc_count_end,
+          threadCountEnd: measurement.guard_execution.thread_count_end,
+          completed: measurement.guard_execution.completed,
+          errorClass: measurement.guard_execution.error_class,
+        }
+      end
+      payload
+    end
+
+    # Track an unadopted guard so it can be reported once.
+    #
+    # @param name [String] guard name to record
+    # @return [void]
+    def record_unadopted_guard(name)
+      @monitor.synchronize do
+        return if @reported_unadopted_guards[name]
+
+        @reported_unadopted_guards[name] = true
+        @pending_unadopted_guards[name] = true
+      end
+    end
+
+    # Capture a stable callsite identifier outside of Liteguard internals.
+    #
+    # @return [String] `path:line` identifier, or `unknown`
+    def capture_callsite_id
+      frame = caller_locations.find do |location|
+        path = location.absolute_path.to_s.tr("\\", "/")
+        !path.end_with?("/sdk/ruby/lib/liteguard/client.rb") &&
+          !path.end_with?("/sdk/ruby/lib/liteguard/scope.rb") &&
+          !path.end_with?("/sdk/ruby/lib/liteguard.rb")
+      end
+      return "unknown" unless frame
+
+      "#{frame.absolute_path || frame.path}:#{frame.lineno}"
+    end
+
+    # Emit a warning message unless quiet mode is enabled.
+    #
+    # @param message [String] log message
+    # @return [void]
+    def log(message)
+      warn message unless @quiet
+    end
+
+    # ---------------------------------------------------------------------
+    # Test helpers
+    # ---------------------------------------------------------------------
+
+    # Replace the public bundle with test data.
+    #
+    # @param guards [Array<Guard>] guards to install in the public bundle
+    # @return [void]
+    def set_guards(guards)
+      @monitor.synchronize do
+        @bundles[PUBLIC_BUNDLE_KEY] = GuardBundle.new(
+          key: PUBLIC_BUNDLE_KEY,
+          guards: guards.each_with_object({}) { |guard, acc| acc[guard.name] = guard },
+          ready: true,
+          etag: "",
+          protected_context: nil,
+          refresh_rate_seconds: @refresh_rate
+        )
+        recompute_refresh_interval_locked
+      end
+    end
+
+    # Install a protected bundle for testing.
+    #
+    # @param protected_context [ProtectedContext, Hash] protected context key
+    # @param guards [Array<Guard>] guards to install for that bundle
+    # @return [void]
+    def set_protected_guards(protected_context, guards)
+      normalized = normalize_protected_context(protected_context)
+      bundle_key = protected_context_cache_key(normalized)
+      @monitor.synchronize do
+        @bundles[bundle_key] = GuardBundle.new(
+          key: bundle_key,
+          guards: guards.each_with_object({}) { |guard, acc| acc[guard.name] = guard },
+          ready: true,
+          etag: "",
+          protected_context: normalized,
+          refresh_rate_seconds: @refresh_rate
+        )
+        recompute_refresh_interval_locked
+      end
+    end
+
+    # Clear rate-limit state for one guard or for all guards.
+    #
+    # @param name [String, nil] optional guard name to clear
+    # @return [void]
+    def reset_rate_limit_state(name = nil)
+      @monitor.synchronize do
+        if name
+          @rate_limit_state.delete(name)
+          prefix = "#{name}\x00"
+          @rate_limit_state.delete_if { |key, _| key.start_with?(prefix) }
+        else
+          @rate_limit_state.clear
+        end
+      end
+    end
+
+    # Return pending unadopted-guard names for tests.
+    #
+    # @return [Array<String>] pending unadopted guard names
+    def pending_unadopted_guards_for_testing
+      @monitor.synchronize { @pending_unadopted_guards.keys.sort }
+    end
+
+    # Return the number of cached bundles for tests.
+    #
+    # @return [Integer] number of known bundles
+    def known_bundle_count_for_testing
+      @monitor.synchronize { @bundles.size }
+    end
+
+    # Return the current refresh rate for tests.
+    #
+    # @return [Integer] current refresh interval in seconds
+    def current_refresh_rate_for_testing
+      @monitor.synchronize { @current_refresh_rate }
+    end
+  end
+end