liteguard 0.4.20260317 → 0.7.20260603

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c5c689f405afe521506111a670b47b74494ed547562a8e083f1c040bcf5b283
-  data.tar.gz: a873c10263763a6700a3fb7ac1ea355d829c927a885cfbc048abf9221d66559a
+  metadata.gz: 674b74c3afa87054d07083210c6f894afad8bc53cb2b6ae8a4e8bd045b30c14c
+  data.tar.gz: 6cf6d9d1fceb2760404e65a0b26faa05ff3687318492d4e124f35eced843e9f5
 SHA512:
-  metadata.gz: 36ffdc869fa486befba275c7a7683879b6ec0014071ba17d6339f28bf173980d4d8d6755f6c19d825b32f215f486cd62f9cbe64887bf1a4fe2c13ddc5401f763
-  data.tar.gz: 44cbf8a627c3edb19bbc1d0152d7670661279a728774dbf72def1e28329a6e6c8a7779b598eb37a23f12bf974bd956a4d778902af9b7d94e078b66efefeda12b
+  metadata.gz: 51eec265fceb91ea7994cf97d64878afb7312ce5bf72abe7732d584da009a8b7ce82efa163144110054254d01ad935cbe22a77ba3ca9f8a01ca5963f5d28d0ef
+  data.tar.gz: d998303a8c1bfa5156aabee64afe9d8b8e174c7da199004491b5cf5e94376a157644d459605fca2c2bbde7d87f9e1381993265f8d2fe0c636057acb60e4d4dc3

data/README.md

@@ -47,16 +47,30 @@ client.shutdown
 - `client.start` fetches the initial bundle and starts refresh and flush workers.
 - `client.create_scope(**properties)` creates an immutable scope.
 - `scope.open?(name, **options)` evaluates locally.
+- `scope.evaluate(name, **options)` returns a `GuardDecision` with the full evaluation result.
 - `scope.execute_if_open(name, **options) { ... }` measures guarded work.
+- `scope.start_execution` creates an execution correlation handle.
 - `scope.bind_protected_context(**protected_context)` derives a protected scope.
+- `scope.properties` returns the current property bag for transport.
 - `client.flush` flushes buffered telemetry.
 - `client.shutdown` flushes and stops background work.
 
+## Convenience helpers
+
+For server applications that want request-scoped context propagation:
+
+- `client.with_scope(scope) { ... }` runs a block with `scope` as the active scope, isolated via `Thread.current`.
+- `client.active_scope` returns the scope bound to the current thread.
+- `client.with_properties(properties) { ... }` derives and activates a scope with additional properties.
+- `client.with_protected_context(protected_context) { ... }` derives and activates a protected scope.
+
 ## Notes
 
 - Evaluation is local after the initial bundle fetch.
+- Protected contexts use `properties`, `signature`, and optional `issued_at` / `expires_at` fields.
 - Prefer explicit client and scope usage.
 - Unadopted guards default open and emit no signals.
+- The convenience helpers above also serve as infrastructure for auto-instrumentation of third-party dependencies. See the [Liteguard CLI](https://github.com/liteguard/liteguard/tree/main/cli) for build-time instrumentation.
 
 ## Development
 

data/lib/liteguard/client.rb

@@ -10,8 +10,8 @@ module Liteguard
   # 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_REFRESH_RATE = 60
+    DEFAULT_FLUSH_RATE = 60
     DEFAULT_FLUSH_SIZE = 500
     DEFAULT_HTTP_TIMEOUT = 4
     DEFAULT_FLUSH_BUFFER_MULTIPLIER = 4
@@ -138,6 +138,25 @@ module Liteguard
       end
     end
 
+    # Start a new execution correlation context and return a handle.
+    #
+    # Returns a lightweight {Execution} handle that groups telemetry signals
+    # under a shared execution ID. Call {Execution#end_execution} when done.
+    # For block-based usage, prefer {#with_execution} instead.
+    #
+    # @return [Execution] a correlation handle
+    def start_execution
+      exec_id = next_signal_id
+      previous = Thread.current[:liteguard_execution_state]
+      Thread.current[:liteguard_execution_state] = {
+        execution_id: exec_id,
+        sequence_number: 0,
+        last_signal_id: nil,
+      }
+      cleanup = -> { Thread.current[:liteguard_execution_state] = previous }
+      Execution.new(exec_id, cleanup: cleanup)
+    end
+
     # ---------------------------------------------------------------------
     # Scope API
     # ---------------------------------------------------------------------
@@ -152,6 +171,13 @@ module Liteguard
 
     # Return the active scope for the current thread.
     #
+    # This method serves two roles:
+    # 1. Developer convenience for retrieving the current request scope.
+    # 2. Required infrastructure for auto-instrumentation. Instrumented
+    #    third-party code calls this method to discover the evaluation
+    #    context established by application-level middleware via
+    #    {#with_scope}.
+    #
     # @return [Scope] the active scope, or the default scope when none is bound
     def active_scope
       scope = Thread.current[@active_scope_key]
@@ -162,6 +188,13 @@ module Liteguard
 
     # Bind a scope for the duration of a block.
     #
+    # This method serves two roles:
+    # 1. Developer convenience for scoping guard evaluation to a request.
+    # 2. Required infrastructure for auto-instrumentation. When application
+    #    middleware activates a scope with this method, instrumented
+    #    third-party code running inside the block can discover the scope
+    #    via {#active_scope}.
+    #
     # @param scope [Scope, nil] scope to bind, or `nil` to reuse the current
     #   scope
     # @yield Runs with the resolved scope bound as active
@@ -209,64 +242,6 @@ module Liteguard
       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
@@ -347,6 +322,73 @@ module Liteguard
       evaluate_guard_in_scope(scope, name.to_s, options, emit_signal: false)[:result]
     end
 
+    # Evaluate a guard and return a {GuardDecision} with full reasoning.
+    #
+    # @param name [String] guard name to evaluate
+    # @param options [Hash, nil] optional per-call overrides
+    # @return [GuardDecision] the evaluation decision
+    def evaluate(name, options = nil, **legacy_options)
+      evaluate_in_scope(active_scope, name, options, **legacy_options)
+    end
+
+    # Evaluate a guard in the provided scope and return a {GuardDecision}.
+    #
+    # @param scope [Scope] scope to evaluate against
+    # @param name [String] guard name to evaluate
+    # @param options [Hash, nil] optional per-call overrides
+    # @return [GuardDecision] the evaluation decision
+    def evaluate_in_scope(scope, name, options = nil, **legacy_options)
+      options = normalize_is_open_options(options, legacy_options)
+      resolved_scope = resolve_scope(scope)
+      bundle = bundle_for_scope(resolved_scope)
+      effective_fallback = options[:fallback].nil? ? @fallback : options[:fallback]
+
+      unless bundle.ready
+        return GuardDecision.new(
+          name: name.to_s, is_open: effective_fallback, adopted: false,
+          reason: "fallback", matched_rule_index: nil, properties: {}
+        )
+      end
+
+      guard = bundle.guards[name.to_s]
+      if guard.nil?
+        record_unadopted_guard(name.to_s)
+        return GuardDecision.new(
+          name: name.to_s, is_open: true, adopted: false,
+          reason: "unadopted", matched_rule_index: nil, properties: {}
+        )
+      end
+      unless guard.adopted
+        record_unadopted_guard(name.to_s)
+        return GuardDecision.new(
+          name: name.to_s, is_open: true, adopted: false,
+          reason: "unadopted", matched_rule_index: nil, properties: {}
+        )
+      end
+
+      props = resolved_scope.properties
+      props = props.merge(options[:properties]) if options[:properties]
+
+      detailed = Evaluation.evaluate_guard_detailed(guard, props)
+      applied_rate_limit = apply_rate_limit(guard, name.to_s, detailed.result, props, emit_signal: true)
+      result = applied_rate_limit[:result]
+
+      reason = detailed.matched_rule_index >= 0 ? "matched_rule" : "default_value"
+      matched_idx = detailed.matched_rule_index >= 0 ? detailed.matched_rule_index : nil
+
+      buffer_signal(
+        name.to_s, result, props,
+        kind: "guard_check",
+        measurement: measurement_enabled?(guard, options) ? capture_guard_check_measurement : nil,
+        rate_limit_decisions: applied_rate_limit[:rate_limit_decisions]
+      )
+
+      GuardDecision.new(
+        name: name.to_s, is_open: result, adopted: guard.adopted,
+        reason: reason, matched_rule_index: matched_idx, properties: props.dup
+      )
+    end
+
     # Evaluate a guard and execute the block only when it resolves open.
     #
     # @param name [String] guard name to evaluate
@@ -432,14 +474,8 @@ module Liteguard
         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
+      applied_rate_limit = apply_rate_limit(guard, name, Evaluation.evaluate_guard(guard, props), props, emit_signal: emit_signal)
+      result = applied_rate_limit[:result]
 
       signal = nil
       if emit_signal
@@ -448,7 +484,8 @@ module Liteguard
           result,
           props,
           kind: "guard_check",
-          measurement: measurement_enabled?(guard, options) ? capture_guard_check_measurement : nil
+          measurement: measurement_enabled?(guard, options) ? capture_guard_check_measurement : nil,
+          rate_limit_decisions: applied_rate_limit[:rate_limit_decisions]
         )
       end
 
@@ -490,6 +527,12 @@ module Liteguard
         projectClientToken: @project_client_token,
         environment: @environment,
         signals: batch.map do |signal|
+          rate_limit_decisions_payload = if signal.rate_limit_decisions&.any?
+            { rateLimitDecisions: signal.rate_limit_decisions.map { |decision| rate_limit_decision_payload(decision) } }
+          else
+            {}
+          end
+
           {
             guardName: signal.guard_name,
             result: signal.result,
@@ -502,7 +545,8 @@ module Liteguard
             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) } : {})
+            **(signal.measurement ? { measurement: signal_measurement_payload(signal.measurement) } : {}),
+            **rate_limit_decisions_payload
           }
         end
       )
@@ -555,7 +599,7 @@ module Liteguard
     # @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)
+    def buffer_signal(guard_name, result, props, kind:, measurement: nil, parent_signal_id_override: nil, rate_limit_decisions: nil)
       metadata = next_signal_metadata(parent_signal_id_override)
       signal = Signal.new(
         guard_name: guard_name,
@@ -570,7 +614,8 @@ module Liteguard
         callsite_id: capture_callsite_id,
         kind: kind,
         dropped_signals_since_last: take_dropped_signals,
-        measurement: measurement
+        measurement: measurement,
+        rate_limit_decisions: Array(rate_limit_decisions).dup
       )
       should_flush = false
       @monitor.synchronize do
@@ -729,10 +774,13 @@ module Liteguard
       return PUBLIC_BUNDLE_KEY if protected_context.nil?
 
       keys = protected_context.properties.keys.sort
-      parts = [protected_context.signature, ""]
+      parts = [protected_context.signature, "properties"]
       keys.each do |key|
         parts << "#{key}=#{protected_context.properties[key]}"
       end
+      parts << ""
+      parts << "issuedAt=#{protected_context.issued_at || ''}"
+      parts << "expiresAt=#{protected_context.expires_at || ''}"
       parts.join("\x00")
     end
 
@@ -763,6 +811,8 @@ module Liteguard
           properties: protected_context.properties,
           signature: protected_context.signature
         }
+        payload[:protectedContext][:issuedAt] = protected_context.issued_at unless protected_context.issued_at.nil?
+        payload[:protectedContext][:expiresAt] = protected_context.expires_at unless protected_context.expires_at.nil?
       end
 
       uri = URI("#{@backend_url}/api/v1/guards")
@@ -899,12 +949,31 @@ module Liteguard
         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"]),
+        rate_limit: parse_rate_limit(raw["rateLimit"]),
+        dry_run_rate_limit: parse_dry_run_rate_limit(raw["dryRunRateLimit"]),
         disable_measurement: raw.key?("disableMeasurement") ? raw["disableMeasurement"] : nil
       )
     end
 
+    def parse_rate_limit(raw)
+      return nil unless raw.is_a?(Hash)
+
+      GuardRateLimitConfig.new(
+        requests_per_minute: (raw["requestsPerMinute"] || 0).to_i,
+        partition_properties: Array(raw["partitionProperties"])
+      )
+    end
+
+    def parse_dry_run_rate_limit(raw)
+      return nil unless raw.is_a?(Hash)
+
+      GuardDryRunRateLimit.new(
+        dry_run_id: raw["dryRunId"].to_s,
+        requests_per_minute: (raw["requestsPerMinute"] || 0).to_i,
+        partition_properties: Array(raw["partitionProperties"])
+      )
+    end
+
     # Parse a rule payload returned by the backend.
     #
     # @param raw [Hash] decoded rule payload
@@ -927,19 +996,118 @@ module Liteguard
     #   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)
+    def evaluate_rate_limit(slot_key, limit_per_minute, rate_limit_properties, props, consume:)
       now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      key = rate_limit_bucket_key(name, rate_limit_properties, props)
+      key = rate_limit_bucket_key(slot_key, 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
+        count_in_window = entry[:count] + 1
+        allowed = entry[:count] < limit_per_minute
+        if consume
+          entry = { window_start: entry[:window_start], count: count_in_window } if allowed
           @rate_limit_state[key] = entry
-          return false
         end
-        @rate_limit_state[key] = { window_start: entry[:window_start], count: entry[:count] + 1 }
+        { allowed: allowed, count_in_window: count_in_window }
       end
-      true
+    end
+
+    def consume_rate_limit(name, evaluation_target, dry_run_id, limit_per_minute, rate_limit_properties, props)
+      evaluate_rate_limit(
+        rate_limit_slot_key(name, evaluation_target, dry_run_id),
+        limit_per_minute,
+        rate_limit_properties,
+        props,
+        consume: true
+      )
+    end
+
+    def peek_rate_limit(name, evaluation_target, dry_run_id, limit_per_minute, rate_limit_properties, props)
+      evaluate_rate_limit(
+        rate_limit_slot_key(name, evaluation_target, dry_run_id),
+        limit_per_minute,
+        rate_limit_properties,
+        props,
+        consume: false
+      )
+    end
+
+    def rate_limit_slot_key(name, evaluation_target, dry_run_id)
+      return "#{name}\x00active" if evaluation_target == :active
+
+      "#{name}\x00dry_run=#{dry_run_id}"
+    end
+
+    def partition_values(rate_limit_properties, props)
+      Array(rate_limit_properties).each_with_object({}) do |property, values|
+        values[property] = props[property] if props.key?(property)
+      end
+    end
+
+    def build_rate_limit_decision(evaluation_target, dry_run_id, outcome, requests_per_minute, rate_limit_properties, props, count_in_window)
+      RateLimitDecision.new(
+        evaluation_target: evaluation_target,
+        dry_run_id: dry_run_id,
+        outcome: outcome,
+        requests_per_minute: requests_per_minute,
+        partition_properties: Array(rate_limit_properties).dup,
+        partition_values: partition_values(rate_limit_properties, props),
+        count_in_window: count_in_window
+      )
+    end
+
+    def apply_rate_limit(guard, name, initial_result, props, emit_signal:)
+      rate_limit_decisions = []
+      return { result: initial_result, rate_limit_decisions: rate_limit_decisions } unless initial_result
+
+      result = initial_result
+      rate_limit = guard.rate_limit
+      if rate_limit && rate_limit.requests_per_minute.to_i > 0
+        evaluation = if emit_signal
+          consume_rate_limit(name, :active, nil, rate_limit.requests_per_minute, rate_limit.partition_properties, props)
+        else
+          peek_rate_limit(name, :active, nil, rate_limit.requests_per_minute, rate_limit.partition_properties, props)
+        end
+        result = evaluation[:allowed]
+        if emit_signal
+          rate_limit_decisions << build_rate_limit_decision(
+            :active,
+            nil,
+            evaluation[:allowed] ? :within_limit : :limited,
+            rate_limit.requests_per_minute,
+            rate_limit.partition_properties,
+            props,
+            evaluation[:count_in_window]
+          )
+        end
+      end
+
+      dry_run_rate_limit = guard.dry_run_rate_limit
+      if emit_signal && dry_run_rate_limit && dry_run_rate_limit.requests_per_minute.to_i > 0
+        evaluation = consume_rate_limit(
+          name,
+          :dry_run,
+          dry_run_rate_limit.dry_run_id,
+          dry_run_rate_limit.requests_per_minute,
+          dry_run_rate_limit.partition_properties,
+          props
+        )
+        rate_limit_decisions << build_rate_limit_decision(
+          :dry_run,
+          dry_run_rate_limit.dry_run_id,
+          evaluation[:allowed] ? :within_limit : :would_limit,
+          dry_run_rate_limit.requests_per_minute,
+          dry_run_rate_limit.partition_properties,
+          props,
+          evaluation[:count_in_window]
+        )
+      end
+
+      { result: result, rate_limit_decisions: rate_limit_decisions }
+    end
+
+    def check_rate_limit(name, limit_per_minute, rate_limit_properties, props)
+      consume_rate_limit(name, :active, nil, limit_per_minute, rate_limit_properties, props)[:allowed]
     end
 
     # Check whether an evaluation would pass rate limiting without consuming a
@@ -952,15 +1120,7 @@ module Liteguard
     # @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
+      peek_rate_limit(name, :active, nil, limit_per_minute, rate_limit_properties, props)[:allowed]
     end
 
     # Build the cache key used for rate-limit buckets.
@@ -1023,19 +1183,51 @@ module Liteguard
       properties.each_with_object({}) { |(key, value), acc| acc[key.to_s] = value }
     end
 
+    # Normalize protected-context property keys and values to strings.
+    #
+    # @param properties [Hash, nil] raw protected property hash
+    # @return [Hash] normalized protected property hash
+    def normalize_protected_context_properties(properties)
+      return {} if properties.nil?
+
+      properties.each_with_object({}) { |(key, value), acc| acc[key.to_s] = value.to_s }
+    end
+
+    # Normalize an optional integer field from symbol or string keyed hashes.
+    #
+    # @param raw [Hash] source payload
+    # @param snake_key [Symbol] snake_case key
+    # @param camel_key [String] camelCase key
+    # @return [Integer, nil] normalized integer value
+    def normalize_optional_integer(raw, snake_key, camel_key)
+      value = raw[snake_key] || raw[camel_key]
+      return nil if value.nil?
+
+      Integer(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 }
+        {
+          properties: protected_context.properties,
+          signature: protected_context.signature,
+          issued_at: protected_context.issued_at,
+          expires_at: protected_context.expires_at
+        }
       else
         protected_context
       end
       ProtectedContext.new(
-        properties: normalize_properties(raw[:properties] || raw["properties"] || {}),
-        signature: (raw[:signature] || raw["signature"]).to_s
+        properties: normalize_protected_context_properties(
+          raw[:properties] || raw["properties"] || {}
+        ),
+        signature: (raw[:signature] || raw["signature"]).to_s,
+        issued_at: normalize_optional_integer(raw, :issued_at, "issuedAt"),
+        expires_at: normalize_optional_integer(raw, :expires_at, "expiresAt")
       )
     end
 
@@ -1048,7 +1240,9 @@ module Liteguard
 
       ProtectedContext.new(
         properties: protected_context.properties.dup,
-        signature: protected_context.signature.dup
+        signature: protected_context.signature.dup,
+        issued_at: protected_context.issued_at,
+        expires_at: protected_context.expires_at
       )
     end
 
@@ -1173,6 +1367,18 @@ module Liteguard
       payload
     end
 
+    def rate_limit_decision_payload(decision)
+      {
+        evaluationTarget: decision.evaluation_target.to_s,
+        **(decision.dry_run_id ? { dryRunId: decision.dry_run_id } : {}),
+        outcome: decision.outcome.to_s,
+        requestsPerMinute: decision.requests_per_minute,
+        partitionProperties: decision.partition_properties,
+        partitionValues: decision.partition_values,
+        countInWindow: decision.count_in_window,
+      }
+    end
+
     # Track an unadopted guard so it can be reported with observation metadata.
     #
     # @param name [String] guard name to record

data/lib/liteguard/decision.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Liteguard
+  # Internal result from {Evaluation.evaluate_guard_detailed}.
+  DetailedEvalResult = Data.define(:result, :matched_rule_index)
+
+  # A lightweight execution correlation handle.
+  #
+  # Groups telemetry signals under a shared execution ID. Created by
+  # {Scope#start_execution} or {Client#start_execution}.
+  # Call {#end_execution} when the logical execution boundary is complete.
+  class Execution
+    # @return [String] the unique identifier for this execution
+    attr_reader :execution_id
+
+    # @api private
+    def initialize(execution_id, cleanup: nil)
+      @execution_id = execution_id
+      @cleanup = cleanup
+    end
+
+    # End this execution.
+    #
+    # After calling +end_execution+, subsequent guard checks will no longer be
+    # correlated with this execution.
+    # @return [void]
+    def end_execution
+      if @cleanup
+        @cleanup.call
+        @cleanup = nil
+      end
+    end
+  end
+end

data/lib/liteguard/evaluation.rb

@@ -18,6 +18,21 @@ module Liteguard
       guard.default_value
     end
 
+    # Evaluate a guard and return both the result and the matched rule index.
+    #
+    # @param guard [Guard] guard definition to evaluate
+    # @param properties [Hash{String => Object}] normalized evaluation properties
+    # @return [DetailedEvalResult] result with the matched rule index (-1 when default)
+    def self.evaluate_guard_detailed(guard, properties)
+      guard.rules.each_with_index do |rule, i|
+        next unless rule.enabled
+        if matches_rule?(rule, properties)
+          return DetailedEvalResult.new(result: rule.result, matched_rule_index: i)
+        end
+      end
+      DetailedEvalResult.new(result: guard.default_value, matched_rule_index: -1)
+    end
+
     # Determine whether a single rule matches the provided properties.
     #
     # @param rule [Rule] rule to evaluate

data/lib/liteguard/scope.rb

@@ -21,7 +21,9 @@ module Liteguard
       @bundle_key = bundle_key
       @protected_context = protected_context ? ProtectedContext.new(
         properties: protected_context.properties.dup,
-        signature: protected_context.signature.dup
+        signature: protected_context.signature.dup,
+        issued_at: protected_context.issued_at,
+        expires_at: protected_context.expires_at
       ) : nil
     end
 
@@ -105,6 +107,30 @@ module Liteguard
       @client.execute_if_open_in_scope(self, name, options, **legacy_options, &block)
     end
 
+    # Evaluate a guard and return a {GuardDecision} with full reasoning.
+    #
+    # Like {#is_open} but returns the full decision context including the
+    # reason, matched rule index, and the merged properties used. A
+    # +guard_check+ telemetry signal is buffered.
+    #
+    # @param name [String] guard name to evaluate
+    # @param options [Hash, nil] optional per-call overrides
+    # @return [GuardDecision] the evaluation decision
+    def evaluate(name, options = nil, **legacy_options)
+      @client.evaluate_in_scope(self, name, options, **legacy_options)
+    end
+
+    # Start a new execution correlation context.
+    #
+    # Returns a lightweight {Execution} handle that groups telemetry signals
+    # under a shared execution ID. Call {Execution#end_execution} when the
+    # logical execution boundary is complete.
+    #
+    # @return [Execution] a correlation handle
+    def start_execution
+      @client.start_execution
+    end
+
     # Bind this scope as the active scope for the duration of a block.
     #
     # @yield Runs with this scope bound as active
@@ -136,7 +162,9 @@ module Liteguard
 
       ProtectedContext.new(
         properties: @protected_context.properties.dup,
-        signature: @protected_context.signature.dup
+        signature: @protected_context.signature.dup,
+        issued_at: @protected_context.issued_at,
+        expires_at: @protected_context.expires_at
       )
     end
 

data/lib/liteguard/types.rb

@@ -6,6 +6,12 @@ module Liteguard
 
   OPERATORS = %i[equals not_equals in not_in regex gt gte lt lte].freeze
 
+  GUARD_DECISION_REASONS = %i[matched_rule default_value unadopted fallback].freeze
+
+  RATE_LIMIT_EVALUATION_TARGETS = %i[active dry_run].freeze
+
+  RATE_LIMIT_DECISION_OUTCOMES = %i[within_limit limited would_limit].freeze
+
   # A single rule condition within a Guard.
   Rule = Data.define(
     :property_name,
@@ -15,24 +21,49 @@ module Liteguard
     :enabled
   )
 
+  # GuardRateLimitConfig (mirrors proto message).
+  GuardRateLimitConfig = Data.define(
+    :requests_per_minute,
+    :partition_properties
+  )
+
+  # GuardDryRunRateLimit (mirrors proto message).
+  GuardDryRunRateLimit = Data.define(
+    :dry_run_id,
+    :requests_per_minute,
+    :partition_properties
+  )
+
   # A named feature guard with an ordered rule set.
   Guard = Data.define(
     :name,
     :rules,
     :default_value,
     :adopted,
-    :rate_limit_per_minute,
-    :rate_limit_properties,
+    :rate_limit,
+    :dry_run_rate_limit,
     :disable_measurement
   )
 
+  # The detailed result of evaluating a guard.
+  GuardDecision = Data.define(
+    :name,
+    :is_open,
+    :adopted,
+    :reason,
+    :matched_rule_index,
+    :properties
+  )
+
   # Keys accepted by the options hash passed to {Liteguard::Client#is_open}.
   CHECK_OPTION_KEYS = %i[properties fallback disable_measurement].freeze
 
   # ProtectedContext (mirrors proto message).
   ProtectedContext = Data.define(
     :properties,
-    :signature
+    :signature,
+    :issued_at,
+    :expires_at
   )
 
   # GetGuardsRequest (mirrors proto message).
@@ -45,6 +76,7 @@ module Liteguard
   # Parsed response from the guards endpoint.
   GuardsResponse = Data.define(
     :guards,
+    :omitted_protected_property_names,
     :refresh_rate_seconds,
     :etag
   )
@@ -85,6 +117,17 @@ module Liteguard
     :guard_execution
   )
 
+  # RateLimitDecision (mirrors proto message).
+  RateLimitDecision = Data.define(
+    :evaluation_target,
+    :dry_run_id,
+    :outcome,
+    :requests_per_minute,
+    :partition_properties,
+    :partition_values,
+    :count_in_window
+  )
+
   # A buffered guard-check record for upload to the data plane.
   Signal = Data.define(
     :guard_name,
@@ -99,7 +142,8 @@ module Liteguard
     :callsite_id,
     :kind,
     :dropped_signals_since_last,
-    :measurement
+    :measurement,
+    :rate_limit_decisions
   )
 
   # UnadoptedGuardObservation (mirrors proto message).
@@ -128,8 +172,8 @@ module Liteguard
     project_client_token:   nil,
     environment:            nil,
     fallback:               false,
-    refresh_rate_seconds:   30,
-    flush_rate_seconds:     10,
+    refresh_rate_seconds:   60,
+    flush_rate_seconds:     60,
     flush_size:             500,
     backend_url:            "https://api.liteguard.io",
     quiet:                  true,

data/lib/liteguard.rb

@@ -1,4 +1,5 @@
 require_relative "liteguard/types"
+require_relative "liteguard/decision"
 require_relative "liteguard/evaluation"
 require_relative "liteguard/scope"
 require_relative "liteguard/client"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: liteguard
 version: !ruby/object:Gem::Version
-  version: 0.4.20260317
+  version: 0.7.20260603
 platform: ruby
 authors:
 - Liteguard
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-18 00:00:00.000000000 Z
+date: 2026-06-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -16,28 +16,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.13'
+        version: 3.13.2
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.13'
+        version: 3.13.2
 - !ruby/object:Gem::Dependency
   name: webmock
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.23'
+        version: 3.26.2
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.23'
+        version: 3.26.2
 description: Liteguard gives you feature guards, observability, and CVE auto-disable
   in one gem. Guards are evaluated entirely in-process against rules fetched once
   at startup. Every open? check is sub-millisecond with no network round-trip.
@@ -50,6 +50,7 @@ files:
 - README.md
 - lib/liteguard.rb
 - lib/liteguard/client.rb
+- lib/liteguard/decision.rb
 - lib/liteguard/evaluation.rb
 - lib/liteguard/scope.rb
 - lib/liteguard/types.rb