olyx-guardrails 1.0.0

data/lib/olyx/guardrails/rails/configuration.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative '../notifier'
+require_relative '../policy'
+require_relative '../validation'
+require_relative 'policy_file'
+require_relative 'configuration_values'
+require_relative 'configuration_finalizer'
+require_relative 'integration_configuration'
+require_relative 'policy_configuration'
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Mutable-at-boot, immutable-at-runtime Rails adapter configuration.
+      class Configuration
+        include IntegrationConfiguration
+        include PolicyConfiguration
+
+        DEFAULT_FILTER_PARAMETERS = %i[prompt system_prompt ai_input llm_input].freeze
+
+        attr_reader :ai_analyzer, :enabled, :filter_parameters, :notifier,
+                    :notifier_handlers, :policy, :policy_path
+
+        def initialize
+          @enabled = true
+          @filter_parameters = DEFAULT_FILTER_PARAMETERS
+          @notifier_handlers = {}.freeze
+          @policy = nil
+          @policy_path = nil
+          @finalized = false
+        end
+
+        # Resolves and validates the policy and handlers once at boot.
+        def finalize!(environment:)
+          return self if finalized?
+
+          @policy, @notifier = ConfigurationFinalizer.call(
+            policy: @policy,
+            path: @policy_path,
+            handlers: @notifier_handlers,
+            environment: environment
+          )
+          @finalized = true
+          freeze
+        end
+
+        def finalized?
+          @finalized
+        end
+
+        def ensure_enabled!
+          return if @enabled
+
+          raise ConfigurationError, 'Olyx Guardrails Rails integration is disabled'
+        end
+
+        private
+
+        def mutable!
+          return unless finalized?
+
+          raise ConfigurationError, 'Olyx Guardrails Rails configuration is already finalized'
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/rails/configuration_finalizer.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Resolves policy sources and constructs the optional notifier at boot.
+      module ConfigurationFinalizer
+        module_function
+
+        def call(policy:, path:, handlers:, environment:)
+          raise ConfigurationError, 'configure either Rails policy or policy_path, not both' if policy && path
+
+          resolved_policy = policy || load_policy(path, environment)
+          [resolved_policy, build_notifier(resolved_policy, handlers)]
+        end
+
+        def load_policy(path, environment)
+          path ? PolicyFile.load(path, environment: environment) : Policy.default
+        end
+
+        def build_notifier(policy, handlers)
+          Notifier.new(policy: policy, handlers: handlers) unless handlers.empty?
+        rescue ArgumentError => error
+          raise ConfigurationError, "invalid Rails notifier configuration: #{error.message}"
+        end
+        private_class_method :load_policy, :build_notifier
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/rails/configuration_registry.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative 'configuration'
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Owns the Rails adapter's boot configuration lifecycle.
+      class ConfigurationRegistry
+        attr_reader :configuration
+
+        def initialize
+          @configuration = Configuration.new
+        end
+
+        def configure
+          yield configuration
+          configuration
+        end
+
+        def finalize!(environment:)
+          configuration.finalize!(environment: environment)
+        end
+
+        def ready
+          finalize!(environment: current_environment) unless configuration.finalized?
+          configuration.ensure_enabled!
+          configuration
+        end
+
+        private
+
+        def current_environment
+          return ::Rails.env if defined?(::Rails) && ::Rails.respond_to?(:env)
+
+          ENV.fetch('RAILS_ENV', 'development')
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/rails/configuration_values.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative '../policy'
+require_relative 'filter_parameters'
+require_relative 'path_value'
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Normalizes individual Rails configuration values before boot freezes.
+      module ConfigurationValues
+        module_function
+
+        def policy(value)
+          return value if value.is_a?(Policy)
+
+          raise ArgumentError, 'Rails policy must be an Olyx::Guardrails::Policy'
+        end
+
+        def path(value)
+          PathValue.call(value)
+        end
+
+        def filter_parameters(value)
+          FilterParameters.call(value)
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/rails/constant_resolver.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Resolves a namespaced constant without inherited lookup.
+      module ConstantResolver
+        module_function
+
+        def call(name)
+          name.split('::').reduce(Object) { |namespace, constant| namespace.const_get(constant, false) }
+        rescue NameError
+          raise ArgumentError, "configured Active Job class #{name.inspect} is not defined"
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/rails/controller.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative 'result_summary'
+require_relative 'controller_metadata'
+require_relative 'enforcer'
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Explicit Action Controller helpers; no parameters are scanned globally.
+      module Controller
+        private
+
+        def guardrails_check(input, metadata: {})
+          Guardrails::Rails.check(input, metadata: request_metadata(metadata))
+        end
+
+        def guardrails_check!(input, metadata: {})
+          Enforcer.check!(input, metadata: request_metadata(metadata))
+        end
+
+        def guardrails_redact(input)
+          Guardrails::Rails.redact(input)
+        end
+
+        def request_metadata(metadata)
+          raise ArgumentError, 'guardrail metadata must be a Hash' unless metadata.is_a?(Hash)
+
+          ControllerMetadata.call(self).merge(metadata)
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/rails/controller_metadata.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Builds bounded request identity metadata from a controller instance.
+      module ControllerMetadata
+        module_function
+
+        def call(controller)
+          request = controller.request
+          {
+            request_id: request.request_id,
+            controller: controller.controller_name,
+            action: controller.action_name,
+            http_method: request.request_method
+          }
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/rails/decision_service.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative 'evaluation_lifecycle'
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Configures a reusable Rails lifecycle around one public decision operation.
+      class DecisionService
+        def initialize(operation, notification_input: nil)
+          @operation = operation
+          @notification_input = notification_input
+        end
+
+        def call(input, metadata:, configuration:)
+          notification_input = @notification_input ? @notification_input.call(input) : input
+          EvaluationLifecycle.call(notification_input, metadata: metadata, configuration: configuration) do
+            Guardrails.public_send(
+              @operation, input, policy: configuration.policy, ai_analyzer: configuration.ai_analyzer
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/rails/enforcer.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'result_summary'
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Provides reusable exception-driven enforcement for Rails entry points.
+      module Enforcer
+        module_function
+
+        def check!(input, metadata: {})
+          enforce(Guardrails::Rails.check(input, metadata: metadata))
+        end
+
+        def check_messages!(messages, metadata: {})
+          enforce(Guardrails::Rails.check_messages(messages, metadata: metadata))
+        end
+
+        def check_output!(output, metadata: {})
+          enforce(Guardrails::Rails.check_output(output, metadata: metadata))
+        end
+
+        def enforce(result)
+          return result if result[:allowed]
+
+          raise Blocked, ResultSummary.call(result)
+        end
+        private_class_method :enforce
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/rails/evaluation_lifecycle.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative 'check_telemetry'
+require_relative 'notification_dispatcher'
+require_relative 'timer'
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Applies the common telemetry and notification lifecycle to a decision.
+      module EvaluationLifecycle
+        module_function
+
+        def call(notification_input, metadata:, configuration:, &)
+          result, duration = Timer.call(&)
+          CheckTelemetry.call(result, duration)
+          NotificationDispatcher.call(configuration, result, notification_input, metadata)
+          result
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/rails/evaluation_service.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative 'decision_service'
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Runs one configured text decision and its post-decision integrations.
+      EvaluationService = DecisionService.new(:check)
+    end
+  end
+end

data/lib/olyx/guardrails/rails/filter_parameters.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Normalizes Rails parameter-filter names.
+      module FilterParameters
+        module_function
+
+        def call(value)
+          unless valid?(value)
+            raise ArgumentError,
+                  'Rails filter_parameters must be an Array of String or Symbol values'
+          end
+
+          value.map(&:to_sym).uniq.freeze
+        end
+
+        def valid?(value)
+          value.is_a?(Array) && value.all? { |item| item.is_a?(String) || item.is_a?(Symbol) }
+        end
+        private_class_method :valid?
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/rails/graphql.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'ingress'
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Opt-in enforcement helpers for GraphQL resolvers and mutations.
+      module GraphQL
+        include Ingress
+
+        private
+
+        alias guardrails_check_graphql! guardrails_check_ingress!
+        alias guardrails_check_graphql_output! guardrails_check_ingress_output!
+
+        def guardrails_ingress_key = :graphql_resolver
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/rails/ingress.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative 'enforcer'
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Shared enforcement behavior for explicit non-controller ingress concerns.
+      module Ingress
+        private
+
+        def guardrails_check_ingress!(value, metadata: {})
+          Enforcer.check!(value, metadata: guardrails_ingress_metadata(metadata))
+        end
+
+        def guardrails_check_ingress_output!(value, metadata: {})
+          Enforcer.check_output!(value, metadata: guardrails_ingress_metadata(metadata))
+        end
+
+        def guardrails_ingress_metadata(metadata)
+          { guardrails_ingress_key => self.class.name }.merge(metadata)
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/rails/input_runtime.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative 'evaluation_service'
+require_relative 'redaction_service'
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Executes configured checks and redaction for inbound text.
+      class InputRuntime
+        def initialize(registry)
+          @registry = registry
+        end
+
+        def check(input, metadata: {})
+          EvaluationService.call(input, metadata: metadata, configuration: @registry.ready)
+        end
+
+        def redact(input)
+          RedactionService.call(input, configuration: @registry.ready)
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/rails/instrumentation.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'active_support/notifications'
+require_relative 'instrumentation_payloads'
+require_relative 'instrumentation_publisher'
+require_relative 'result_summary'
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Publishes sanitized, content-free Active Support events.
+      module Instrumentation
+        module_function
+
+        def publish_check(result, duration)
+          InstrumentationPublisher.call(
+            'check.olyx_guardrails',
+            ResultSummary.call(result).merge(evaluation_duration_ms: duration)
+          )
+        end
+
+        def publish_violation(result, duration)
+          InstrumentationPublisher.call(
+            'violation.olyx_guardrails',
+            ResultSummary.call(result).merge(evaluation_duration_ms: duration)
+          )
+        end
+
+        def publish_redaction(result, duration)
+          InstrumentationPublisher.call('redact.olyx_guardrails', InstrumentationPayloads.redaction(result, duration))
+        end
+
+        def publish_notification(delivery)
+          InstrumentationPublisher.call('notification.olyx_guardrails', InstrumentationPayloads.notification(delivery))
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/rails/instrumentation_payloads.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative 'redaction_payload'
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Builds content-free redaction and delivery telemetry payloads.
+      module InstrumentationPayloads
+        module_function
+
+        def redaction(result, duration)
+          RedactionPayload.call(result, duration)
+        end
+
+        def notification(delivery)
+          {
+            success: delivery[:success] == true,
+            delivery_count: Array(delivery[:deliveries]).length
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/rails/instrumentation_publisher.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Publishes Active Support events and isolates observability failures.
+      module InstrumentationPublisher
+        module_function
+
+        def call(name, payload)
+          ActiveSupport::Notifications.instrument(name, payload)
+        rescue StandardError => error
+          logger = rails_logger
+          logger&.warn("Olyx Guardrails instrumentation #{name} failed (#{error.class})")
+        end
+
+        def rails_logger
+          ::Rails.logger if defined?(::Rails) && ::Rails.respond_to?(:logger)
+        end
+        private_class_method :rails_logger
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/rails/integration_configuration.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Owns runtime integration assignments during Rails boot.
+      module IntegrationConfiguration
+        def enabled=(value)
+          mutable!
+          @enabled = Validation.boolean!(value, name: 'Rails integration enabled')
+        end
+
+        def ai_analyzer=(value)
+          mutable!
+          @ai_analyzer = Validation.callable_or_nil!(value, name: 'Rails integration ai_analyzer')
+        end
+
+        def notifier_handlers=(value)
+          mutable!
+          raise ArgumentError, 'Rails notifier_handlers must be a Hash' unless value.is_a?(Hash)
+
+          @notifier_handlers = value.dup.freeze
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/rails/job.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative 'enforcer'
+require_relative 'job_argument'
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Opt-in Active Job callback for declared AI-input arguments.
+      module Job
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+
+        # Class-level declaration for protected argument indexes or keyword names.
+        module ClassMethods
+          attr_reader :guardrails_argument_selectors
+
+          def guardrails_input_arguments(*selectors)
+            @guardrails_argument_selectors = selectors.freeze
+            before_perform { |job| job.send(:guardrails_enforce_arguments!) }
+          end
+        end
+
+        private
+
+        def guardrails_enforce_arguments!
+          job_class = self.class
+          job_class.guardrails_argument_selectors.each do |selector|
+            input = JobArgument.call(arguments, selector)
+            Enforcer.check!(input, metadata: { job: job_class.name, argument: selector })
+          end
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/rails/job_argument.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Extracts a declared positional or keyword Active Job argument.
+      module JobArgument
+        module_function
+
+        def call(arguments, selector)
+          return arguments.fetch(selector) if selector.is_a?(Integer)
+
+          keyword(arguments, selector)
+        end
+
+        def keyword(arguments, selector)
+          validate_selector!(selector)
+
+          keywords = keyword_arguments(arguments)
+          raise ArgumentError, "guardrail job keyword #{selector.inspect} is missing" unless keywords
+
+          fetch_keyword(keywords, selector)
+        end
+        private_class_method :keyword
+
+        def fetch_keyword(keywords, selector)
+          keywords.fetch(selector) { keywords.fetch(selector.to_s) }
+        end
+
+        def keyword_arguments(arguments)
+          arguments.reverse.find { |argument| argument.is_a?(Hash) }
+        end
+
+        def validate_selector!(selector)
+          raise ArgumentError, 'job guardrail selectors must be Integer or Symbol' unless selector.is_a?(Symbol)
+        end
+        private_class_method :fetch_keyword, :keyword_arguments, :validate_selector!
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/rails/job_reference.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative 'constant_resolver'
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Validates and resolves an Active Job class reference.
+      class JobReference
+        NAME = /\A[A-Z]\w*(?:::[A-Z]\w*)*\z/
+
+        def initialize(job)
+          @job = normalize(job)
+        end
+
+        def resolve
+          target = @job.is_a?(String) ? ConstantResolver.call(@job) : @job
+          return target if target.respond_to?(:perform_later)
+
+          raise ArgumentError, 'configured job must respond to perform_later'
+        end
+
+        private
+
+        def normalize(job)
+          return job if job.respond_to?(:perform_later)
+
+          name = job.to_s
+          return name.freeze if (job.is_a?(String) || job.is_a?(Symbol)) && name.match?(NAME)
+
+          raise ArgumentError, 'job must be an Active Job class or a constant name'
+        end
+      end
+    end
+  end
+end