olyx-guardrails 1.0.0

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative '../message_source'
+require_relative 'decision_service'
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Evaluates structured messages with Rails telemetry and notifications.
+      MessageEvaluationService = DecisionService.new(:check_messages, notification_input: MessageSource)
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative 'message_evaluation_service'
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Executes configured checks for structured conversation messages.
+      class MessageRuntime
+        def initialize(registry)
+          @registry = registry
+        end
+
+        def check_messages(messages, metadata: {})
+          MessageEvaluationService.call(messages, metadata: metadata, configuration: @registry.ready)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative 'instrumentation'
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Dispatches optional Rails notifications without coupling evaluation.
+      module NotificationDispatcher
+        module_function
+
+        def call(configuration, result, input, metadata)
+          notifier = configuration.notifier
+          return unless notifier
+
+          delivery = notifier.notify(result, input: input, metadata: metadata)
+          Instrumentation.publish_notification(delivery) if delivery
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative 'evaluation_service'
+require_relative 'redaction_service'
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Executes configured checks and redaction for completed model output.
+      class OutputRuntime
+        def initialize(registry)
+          @registry = registry
+        end
+
+        def check_output(output, metadata: {})
+          context = { direction: 'output' }.merge(metadata)
+          EvaluationService.call(output, metadata: context, configuration: @registry.ready)
+        end
+
+        def redact_output(output)
+          RedactionService.call(output, configuration: @registry.ready)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Normalizes an optional path-like configuration value.
+      module PathValue
+        module_function
+
+        def call(value)
+          return nil if value.nil?
+
+          normalized = normalize(value)
+          return normalized.dup.freeze if valid?(normalized)
+
+          raise ArgumentError, 'Rails policy_path must be a path-like value'
+        end
+
+        def normalize(value)
+          value.respond_to?(:to_path) ? value.to_path : value
+        end
+
+        def valid?(value)
+          value.is_a?(String) && !value.empty?
+        end
+        private_class_method :normalize, :valid?
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Owns policy and filtering assignments during Rails boot.
+      module PolicyConfiguration
+        def policy=(value)
+          mutable!
+          @policy = ConfigurationValues.policy(value)
+        end
+
+        def policy_path=(value)
+          mutable!
+          @policy_path = ConfigurationValues.path(value)
+        end
+
+        def filter_parameters=(value)
+          mutable!
+          @filter_parameters = ConfigurationValues.filter_parameters(value)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative 'policy_yaml'
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Parses and selects direct or environment-keyed policy YAML.
+      class PolicyDocument
+        POLICY_KEYS = %w[name max_input_length block_pii block_injections block_secrets ai_failure_mode secret_patterns
+                         rules].freeze
+
+        def initialize(path, environment)
+          @path = path
+          @environment = environment
+        end
+
+        def call
+          document = PolicyYaml.load(@path)
+          return document if direct?(document)
+
+          environment_policy(document)
+        end
+
+        private
+
+        def environment_policy(document)
+          selected = document[@environment] || document[@environment.to_sym]
+          return selected if selected.is_a?(Hash)
+
+          raise ConfigurationError, "guardrail policy file has no #{@environment.inspect} policy: #{@path}"
+        end
+
+        def direct?(document)
+          document.keys.any? { |key| POLICY_KEYS.include?(key.to_s) }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative '../policy'
+require_relative 'policy_document'
+require_relative 'policy_file_error'
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Safely loads direct or environment-keyed policy YAML without ERB.
+      class PolicyFile
+        def self.load(path, environment:)
+          new(path, environment).load
+        end
+
+        def initialize(path, environment)
+          @path = path.to_s
+          @environment = environment.to_s
+        end
+
+        def load
+          Policy.from_h(PolicyDocument.new(@path, @environment).call)
+        rescue Errno::ENOENT, Errno::EACCES, Psych::Exception, ArgumentError => error
+          raise PolicyFileError.call(error, @path)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Translates policy loading failures into stable boot configuration errors.
+      module PolicyFileError
+        module_function
+
+        def call(error, path)
+          ConfigurationError.new(message(error, path))
+        end
+
+        def message(error, path)
+          return "guardrail policy file does not exist: #{path}" if error.is_a?(Errno::ENOENT)
+          return "guardrail policy file is not readable: #{path}" if error.is_a?(Errno::EACCES)
+          return "guardrail policy file contains invalid or unsafe YAML: #{path}" if error.is_a?(Psych::Exception)
+
+          "invalid guardrail policy in #{path}: #{error.message}"
+        end
+        private_class_method :message
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Extracts unique policy rule identifiers for safe telemetry.
+      module PolicyRuleNames
+        module_function
+
+        def call(result)
+          Array(result[:policy_findings]).filter_map { |finding| name(finding) }.uniq.freeze
+        end
+
+        def name(finding) = finding[:rule]&.to_s
+        private_class_method :name
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Safely reads a YAML policy document without aliases or object types.
+      module PolicyYaml
+        module_function
+
+        def load(path)
+          document = YAML.safe_load_file(path, permitted_classes: [], permitted_symbols: [], aliases: false,
+                                               filename: path)
+          return document if document.is_a?(Hash)
+
+          raise ConfigurationError, "guardrail policy file must contain a Hash: #{path}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Normalizes an optional Active Job queue name.
+      module QueueName
+        module_function
+
+        def call(queue)
+          return nil if queue.nil?
+
+          name = queue.to_s
+          return name.freeze if (queue.is_a?(String) || queue.is_a?(Symbol)) && !name.empty?
+
+          raise ArgumentError, 'queue must be a non-empty String or Symbol'
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Builds content-free redaction telemetry.
+      module RedactionPayload
+        module_function
+
+        def call(result, duration)
+          flags(result).merge(evaluation_duration_ms: duration).freeze
+        end
+
+        def flags(result)
+          identity(result).merge(detections(result))
+        end
+
+        def identity(result)
+          {
+            policy_name: result[:policy_name].to_s[0...100],
+            redacted: result[:redacted] == true
+          }
+        end
+
+        def detections(result)
+          {
+            pii_detected: result[:pii_detected] == true,
+            secret_leaked: result[:secret_leaked] == true,
+            policy_violated: result[:policy_violated] == true
+          }
+        end
+        private_class_method :detections, :flags, :identity
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'instrumentation'
+require_relative 'timer'
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Runs one configured transformation and publishes safe telemetry.
+      module RedactionService
+        module_function
+
+        def call(input, configuration:)
+          result, duration = Timer.call { Guardrails.redact(input, policy: configuration.policy) }
+          Instrumentation.publish_redaction(result, duration)
+          result
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative '../violation_labels'
+require_relative '../notification/deep_freezer'
+require_relative 'policy_rule_names'
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Builds the bounded decision payload used by exceptions and telemetry.
+      module ResultSummary
+        module_function
+
+        def call(result)
+          Notification::DeepFreezer.call(decision(result).merge(policy(result)))
+        end
+
+        def decision(result)
+          {
+            policy_name: result[:policy_name].to_s[0...100],
+            allowed: result[:allowed] == true,
+            risk_score: result[:risk_score].to_f
+          }
+        end
+
+        def policy(result)
+          {
+            violations: Guardrails::ViolationLabels.call(result).freeze,
+            policy_rules: PolicyRuleNames.call(result)
+          }
+        end
+        private_class_method :decision, :policy
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+require_relative 'configuration_registry'
+require_relative 'input_runtime'
+require_relative 'message_runtime'
+require_relative 'output_runtime'
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Composes the independent configuration, input, message, and output runtimes.
+      class Runtime
+        extend Forwardable
+
+        def_delegators :@registry, :configuration, :configure, :finalize!
+        def_delegators :@input, :check, :redact
+        def_delegator :@messages, :check_messages
+        def_delegators :@output, :check_output, :redact_output
+
+        def initialize
+          @registry = ConfigurationRegistry.new
+          @input = InputRuntime.new(@registry)
+          @messages = MessageRuntime.new(@registry)
+          @output = OutputRuntime.new(@registry)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Measures adapter operations with a monotonic clock.
+      module Timer
+        module_function
+
+        def call
+          started = clock_time
+          result = yield
+          [result, elapsed_milliseconds(started)]
+        end
+
+        def clock_time
+          Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        end
+
+        def elapsed_milliseconds(started)
+          ((clock_time - started) * 1_000).round(3)
+        end
+        private_class_method :clock_time, :elapsed_milliseconds
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative 'enforcer'
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Checks caller-extracted upload text without owning parsing or storage.
+      module Upload
+        module_function
+
+        def check(upload, extractor:, metadata: {})
+          text = extract(upload, extractor)
+          Guardrails::Rails.check(text, metadata: { ingress: 'upload' }.merge(metadata))
+        end
+
+        def check!(upload, extractor:, metadata: {})
+          text = extract(upload, extractor)
+          Enforcer.check!(text, metadata: { ingress: 'upload' }.merge(metadata))
+        end
+
+        def extract(upload, extractor)
+          raise ArgumentError, 'upload extractor must respond to call' unless extractor.respond_to?(:call)
+
+          text = extractor.call(upload)
+          raise ArgumentError, 'upload extractor must return a String' unless text.is_a?(String)
+
+          text
+        end
+        private_class_method :extract
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/rails.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'active_support/notifications'
+require 'forwardable'
+require_relative '../guardrails'
+require_relative 'rails/active_job_handler'
+require_relative 'rails/action_cable'
+require_relative 'rails/active_model_validator'
+require_relative 'rails/controller'
+require_relative 'rails/enforcer'
+require_relative 'rails/graphql'
+require_relative 'rails/job'
+require_relative 'rails/runtime'
+require_relative 'rails/upload'
+
+module Olyx
+  module Guardrails
+    # Optional Rails-native configuration and enforcement facade.
+    module Rails
+      extend SingleForwardable
+
+      def self.runtime
+        @runtime ||= Runtime.new
+      end
+      private_class_method :runtime
+
+      def_single_delegators :runtime,
+                            :configuration, :configure, :finalize!,
+                            :check, :redact, :check_messages,
+                            :check_output, :redact_output
+    end
+  end
+end
+
+require_relative 'railtie' if defined?(Rails::Railtie)

data/lib/olyx/guardrails/railtie.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'rails/railtie'
+
+module Olyx
+  module Guardrails
+    # Boots and validates the optional Rails adapter.
+    class Railtie < ::Rails::Railtie
+      initializer 'olyx_guardrails.filter_parameters', after: :load_config_initializers do |app|
+        filters = Guardrails::Rails.configuration.filter_parameters
+        app.config.filter_parameters.concat(filters).uniq!
+      end
+
+      config.after_initialize do
+        Guardrails::Rails.finalize!(environment: ::Rails.env)
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/redaction/content_result.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Redaction
+      # Builds the stable internal redaction content contract.
+      module ContentResult
+        module_function
+
+        def call(source, text:, secret_scan:, policy_redaction:)
+          findings = secret_scan[:findings]
+          detection(source, secret_scan, policy_redaction).merge(content(text, findings))
+        end
+
+        def content(text, findings)
+          output = '[REDACTED]' if findings.any? { |finding| finding[:category] == 'confidentiality_marker' }
+          { text: output || text, findings: findings }
+        end
+
+        def detection(source, secret_scan, policy_redaction)
+          {
+            pii_detected: PiiScrubber.scrub(source) != source,
+            secret_leaked: secret_scan[:leaked],
+            policy_violated: policy_redaction[:violated],
+            policy_findings: policy_redaction[:findings]
+          }
+        end
+        private_class_method :content, :detection
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/redaction/input_validator.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Redaction
+      # Validates redaction policy type and configured length limit.
+      module InputValidator
+        module_function
+
+        def call(source, policy)
+          raise ArgumentError, 'policy must be an Olyx::Guardrails::Policy' unless policy.is_a?(Policy)
+          raise ArgumentError, 'input exceeds max_input_length' if source.length > policy.max_input_length
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/redaction/public_result.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Redaction
+      # Presents the stable public redaction result contract.
+      module PublicResult
+        CONTENT_FIELDS = %i[pii_detected secret_leaked policy_violated policy_findings findings].freeze
+
+        module_function
+
+        def call(source, content, policy)
+          text = content[:text]
+          content.slice(*CONTENT_FIELDS).merge(
+            text: text,
+            redacted: text != source,
+            policy_name: policy.name
+          )
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/redaction/unrestricted_text.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Redaction
+      # Applies secret and PII transforms outside policy-owned spans.
+      module UnrestrictedText
+        module_function
+
+        def call(text, policy)
+          secret_safe = SecretScanner.redact(text, custom_patterns: policy.secret_patterns)[:text]
+          PiiScrubber.scrub(secret_safe)
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/redactor.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'policy'
+require_relative 'policy_aware_redactor'
+require_relative 'redaction/input_validator'
+require_relative 'redaction/public_result'
+
+module Olyx
+  module Guardrails
+    # Applies the explicit PII, secret, and restricted-policy transformation
+    # used by {Guardrails.redact}.
+    class Redactor
+      def self.call(input, policy:)
+        new(input, policy).call
+      end
+
+      def initialize(input, policy)
+        @source = input.to_s
+        @policy = policy
+      end
+
+      def call
+        Redaction::InputValidator.call(@source, @policy)
+        content = PolicyAwareRedactor.call(@source, policy: @policy)
+        Redaction::PublicResult.call(@source, content, @policy)
+      end
+    end
+  end
+end