olyx-guardrails 1.0.0

data/lib/olyx/guardrails/notification/handler_collection.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative 'handler'
+require_relative 'handler_collection_validator'
+
+module Olyx
+  module Guardrails
+    module Notification
+      # Validates and freezes named notification handlers.
+      module HandlerCollection
+        MAXIMUM = 20
+
+        module_function
+
+        def call(handlers)
+          HandlerCollectionValidator.input!(handlers, maximum: MAXIMUM)
+
+          normalized = handlers.map { |name, handler| Handler.call(name, handler) }
+          HandlerCollectionValidator.unique!(normalized)
+          normalized.freeze
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/notification/handler_collection_validator.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Notification
+      # Validates handler collection shape and normalized-name uniqueness.
+      module HandlerCollectionValidator
+        module_function
+
+        def input!(handlers, maximum:)
+          return if handlers.is_a?(Hash) && !handlers.empty? && handlers.length <= maximum
+
+          raise ArgumentError, "handlers must be a non-empty Hash with at most #{maximum} entries"
+        end
+
+        def unique!(handlers)
+          names = handlers.map(&:first)
+          raise ArgumentError, 'handler names must be unique' unless names.uniq.length == names.length
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/notification/key.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Notification
+      # Normalizes a redacted metadata key.
+      module Key
+        LENGTH = 50
+
+        module_function
+
+        def call(value, scrubber)
+          normalized = scrubber.call(value).gsub(/[^A-Za-z0-9_.-]/, '_')[0...LENGTH]
+          normalized.empty? ? 'metadata' : normalized
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/notification/metadata.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Notification
+      # Bounds, sanitizes, and collision-proofs notification metadata.
+      module Metadata
+        MAX_ENTRIES = 20
+        KEY_LENGTH = 50
+
+        module_function
+
+        def call(metadata, sanitizer)
+          metadata.first(MAX_ENTRIES).each_with_object({}) do |(key, value), output|
+            safe_key = unique_key(sanitizer.key(key), output)
+            output[safe_key] = sanitizer.field(value)
+          end
+        end
+
+        def unique_key(base, output)
+          index = 1
+          candidate = base
+          while output.key?(candidate)
+            index += 1
+            suffix = "_#{index}"
+            candidate = "#{base[0...(KEY_LENGTH - suffix.length)]}#{suffix}"
+          end
+          candidate
+        end
+        private_class_method :unique_key
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/notification/notifier_setup.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Notification
+      # Constructs the notifier's validated policy and delivery dispatcher.
+      module NotifierSetup
+        module_function
+
+        def call(policy, handlers)
+          config = NotifierConfiguration.new(policy: policy, handlers: handlers)
+          configured_policy = config.policy
+          sanitizer = NotificationSanitizer.new(configured_policy)
+          [configured_policy, DeliveryDispatcher.new(config.handlers, sanitizer)]
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/notification/preview.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Notification
+      # Produces a bounded redacted preview with a truncation marker.
+      module Preview
+        LENGTH = 300
+
+        module_function
+
+        def call(value, scrubber)
+          source = value.to_s
+          scrubbed = scrubber.call(source)
+          preview = scrubbed[0...LENGTH]
+          preview += '…' if truncated?(source, scrubbed)
+          preview
+        end
+
+        def truncated?(source, scrubbed)
+          scrubbed.length > LENGTH || source.length > Scrubber::WINDOW
+        end
+        private_class_method :truncated?
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/notification/scrubber.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative '../policy_aware_redactor'
+
+module Olyx
+  module Guardrails
+    module Notification
+      # Applies policy-aware redaction to a bounded notification value.
+      class Scrubber
+        WINDOW = 2_000
+
+        def initialize(policy)
+          @policy = policy
+        end
+
+        def call(value)
+          PolicyAwareRedactor.call(value.to_s[0...WINDOW], policy: @policy)[:text]
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/notification/violation_labels.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative '../violation_labels'
+
+module Olyx
+  module Guardrails
+    module Notification
+      # Derives stable machine-readable violation labels from a decision.
+      module ViolationLabels
+        module_function
+
+        def call(result)
+          labels = Guardrails::ViolationLabels.call(result)
+          labels.empty? ? ['policy_violation'] : labels
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/notification_event_builder.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative 'notification/deep_freezer'
+require_relative 'notification/base_event'
+require_relative 'notification/metadata'
+require_relative 'notification/violation_labels'
+require_relative 'notification_sanitizer'
+
+module Olyx
+  # Vendor-neutral AI safety checks and notification events.
+  module Guardrails
+    # Composes the bounded, immutable, vendor-neutral notification event.
+    class NotificationEventBuilder
+      SCHEMA_VERSION = 1
+
+      def self.call(result, input:, metadata:, policy:)
+        new(result, input, metadata, policy).call
+      end
+
+      def initialize(result, input, metadata, policy)
+        @result = result
+        @input = input
+        @metadata = metadata.is_a?(Hash) ? metadata : {}
+        @policy = policy
+        @sanitizer = NotificationSanitizer.new(policy)
+      end
+
+      def call
+        event = Notification::BaseEvent.call(
+          @result, metadata: @metadata, policy: @policy, sanitizer: @sanitizer, schema_version: SCHEMA_VERSION
+        )
+        reason = @result.dig(:ai_analysis, :reason)
+        event[:ai_reason] = @sanitizer.field(reason) if reason
+        event[:input_preview] = @sanitizer.preview(@input) unless @input.nil?
+        Notification::DeepFreezer.call(event)
+      end
+    end
+
+    private_constant :NotificationEventBuilder
+  end
+end

data/lib/olyx/guardrails/notification_sanitizer.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'notification/key'
+require_relative 'notification/preview'
+require_relative 'notification/scrubber'
+
+module Olyx
+  # Guardrail policy types and evaluation services.
+  module Guardrails
+    # Applies the configured confidentiality policy to notification text.
+    class NotificationSanitizer
+      FIELD_LENGTH = 300
+
+      def initialize(policy)
+        @scrubber = Notification::Scrubber.new(policy)
+      end
+
+      def field(value, max_length: FIELD_LENGTH)
+        @scrubber.call(value).gsub(/[\r\n\t]+/, ' ')[0...max_length]
+      end
+
+      def preview(value)
+        Notification::Preview.call(value, @scrubber)
+      end
+
+      def key(value)
+        Notification::Key.call(value, @scrubber)
+      end
+    end
+
+    private_constant :NotificationSanitizer
+  end
+end

data/lib/olyx/guardrails/notifier.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative 'notification_event_builder'
+require_relative 'notification/delivery_dispatcher'
+require_relative 'notification/delivery_summary'
+require_relative 'notification/notifier_setup'
+require_relative 'notification_sanitizer'
+require_relative 'notifier_configuration'
+
+module Olyx
+  # Guardrail policy types and evaluation services.
+  module Guardrails
+    # Dispatches one sanitized guardrail event to named application callables.
+    # Handlers run synchronously and independently; applications can enqueue
+    # asynchronous work from a handler when required.
+    class Notifier
+      # @param policy [Policy] the policy used to produce and sanitize results.
+      # @param handlers [Hash<String, #call>, Hash<Symbol, #call>] one to 20
+      #   named callables accepting the immutable event Hash.
+      # @raise [ArgumentError] when policy or handler configuration is invalid.
+      def initialize(policy:, handlers:)
+        @policy, @dispatcher = Notification::NotifierSetup.call(policy, handlers)
+      end
+
+      # Dispatches a sanitized event when the result has non-zero risk.
+      # Handler and event-building failures are returned and never raised.
+      #
+      # @param result [Hash] a result from {Guardrails.check}.
+      # @param input [#to_s, nil] original input for a redacted preview.
+      # @param metadata [Hash] caller context, capped and policy-redacted.
+      # @return [Hash, nil] delivery summary, or nil for zero-risk results.
+      def notify(result, input: nil, metadata: {})
+        return nil unless deliverable?(result)
+
+        event = build_event(result, input, metadata)
+        deliveries = @dispatcher.call(event)
+        Notification::DeliverySummary.call(event, deliveries)
+      rescue StandardError => error
+        @dispatcher.failure(error)
+      end
+
+      private
+
+      def build_event(result, input, metadata)
+        NotificationEventBuilder.call(result, input: input, metadata: metadata, policy: @policy)
+      end
+
+      def deliverable?(result)
+        result.is_a?(Hash) && result[:risk_score].to_f.positive?
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/notifier_configuration.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'policy'
+require_relative 'notification/handler_collection'
+
+module Olyx
+  # Guardrail policy types and evaluation services.
+  module Guardrails
+    # Validates and freezes the generic notifier's policy and named handlers.
+    class NotifierConfiguration
+      attr_reader :policy, :handlers
+
+      def initialize(policy:, handlers:)
+        @policy = validate_policy(policy)
+        @handlers = Notification::HandlerCollection.call(handlers)
+        freeze
+      end
+
+      private
+
+      def validate_policy(policy)
+        return policy if policy.is_a?(Policy)
+
+        raise ArgumentError, 'policy must be an Olyx::Guardrails::Policy'
+      end
+    end
+
+    private_constant :NotifierConfiguration
+  end
+end

data/lib/olyx/guardrails/pii/ambiguous_numeric_date.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'date'
+
+module Olyx
+  module Guardrails
+    module Pii
+      # Accepts valid day-first or month-first numeric dates.
+      module AmbiguousNumericDate
+        module_function
+
+        def call(parts)
+          first, second, raw_year = parts.map(&:to_i)
+          valid?(first, second, year(raw_year, parts.last))
+        end
+
+        def valid?(first, second, year)
+          candidates(first, second).any? { |month, day| Date.valid_date?(year, month, day) }
+        end
+
+        def candidates(first, second)
+          [[second, first], [first, second]]
+        end
+
+        def year(value, source)
+          source.length == 2 ? value + 2_000 : value
+        end
+        private_class_method :candidates, :valid?, :year
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/pii/block_scrubber.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'hash_key'
+require_relative 'text_scrubber'
+
+module Olyx
+  module Guardrails
+    module Pii
+      # Redacts a text content block while preserving its Hash shape.
+      module BlockScrubber
+        module_function
+
+        def call(block)
+          return [block, false] unless block.is_a?(Hash)
+
+          key = HashKey.call(block, 'text')
+          text = block[key] if key
+          return [block, false] unless text.is_a?(String)
+
+          result(block, key, text, TextScrubber.call(text))
+        end
+
+        def result(block, key, text, redacted)
+          changed = redacted != text
+          [changed ? block.merge(key => redacted) : block, changed]
+        end
+        private_class_method :result
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/pii/content_scrubber.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'block_scrubber'
+require_relative 'text_scrubber'
+
+module Olyx
+  module Guardrails
+    module Pii
+      # Redacts String or array-style message content.
+      module ContentScrubber
+        module_function
+
+        def call(content)
+          return scrub_text(content) if content.is_a?(String)
+          return scrub_blocks(content) if content.is_a?(Array)
+
+          [content, false]
+        end
+
+        def scrub_text(text)
+          redacted = TextScrubber.call(text)
+          [redacted, redacted != text]
+        end
+
+        def scrub_blocks(blocks)
+          results = blocks.map { |block| BlockScrubber.call(block) }
+          [results.map(&:first), results.any?(&:last)]
+        end
+        private_class_method :scrub_text, :scrub_blocks
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/pii/date_validator.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'date'
+require_relative 'named_date_validator'
+require_relative 'numeric_date_validator'
+
+module Olyx
+  module Guardrails
+    module Pii
+      # Validates labeled date-of-birth candidates as real calendar dates.
+      module DateValidator
+        DATE = %r{(?:\d{1,4}[/-]\d{1,2}[/-]\d{1,4}|[A-Za-z]+\.?\s+\d{1,2},?\s+\d{4})}
+
+        module_function
+
+        def call(value)
+          candidate = value[DATE]
+          return false unless candidate
+
+          candidate.match?(/\A\d/) ? NumericDateValidator.call(candidate) : NamedDateValidator.call(candidate)
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/pii/hash_key.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Pii
+      # Finds String or Symbol variants of a Hash key.
+      module HashKey
+        module_function
+
+        def call(hash, name)
+          return name if hash.key?(name)
+
+          symbol = name.to_sym
+          symbol if hash.key?(symbol)
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/pii/iban_remainder.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Pii
+      # Calculates ISO 13616's streaming mod-97 remainder.
+      module IbanRemainder
+        module_function
+
+        def call(value)
+          value.each_char.reduce(0) { |current, character| append(current, digits(character)) }
+        end
+
+        def append(current, characters)
+          characters.each_char.reduce(current) { |memo, digit| ((memo * 10) + digit.to_i) % 97 }
+        end
+
+        def digits(character)
+          character.match?(/[A-Z]/) ? (character.ord - 55).to_s : character
+        end
+        private_class_method :append, :digits
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/pii/iban_validator.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative 'iban_remainder'
+
+module Olyx
+  module Guardrails
+    module Pii
+      # Applies ISO 13616 mod-97 validation to IBAN candidates.
+      module IbanValidator
+        FORMAT = /\A[A-Z]{2}\d{2}[A-Z0-9]{11,30}\z/
+
+        module_function
+
+        def call(iban)
+          compact = compact(iban)
+          return false unless valid_format?(compact)
+
+          valid_checksum?(compact)
+        end
+
+        def compact(iban) = iban.delete(' ').upcase
+
+        def valid_format?(compact)
+          compact.length.between?(15, 34) && compact.match?(FORMAT)
+        end
+
+        def valid_checksum?(compact)
+          IbanRemainder.call(compact[4..] + compact[0, 4]) == 1
+        end
+        private_class_method :compact, :valid_checksum?, :valid_format?
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/pii/ipv4_validator.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Pii
+      # Validates the structure and range of every IPv4 octet.
+      module Ipv4Validator
+        module_function
+
+        def call(address)
+          octets = address.split('.')
+          octets.length == 4 && octets.all? { |octet| octet.to_i.between?(0, 255) }
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/pii/ipv6_validator.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'ipaddr'
+
+module Olyx
+  module Guardrails
+    module Pii
+      # Validates IPv6 candidates with Ruby's address parser.
+      module Ipv6Validator
+        module_function
+
+        def call(address)
+          IPAddr.new(address).ipv6?
+        rescue IPAddr::InvalidAddressError
+          false
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/pii/luhn_checksum.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Pii
+      # Shared Luhn digit-parsing and checksum validity, reused by every
+      # format that applies the Luhn algorithm at its own fixed or minimum
+      # length (cards, Canadian SIN) so that length rule is the only thing
+      # each caller needs to own.
+      module LuhnChecksum
+        module_function
+
+        def digits(number) = number.gsub(/\D/, '').chars.map(&:to_i)
+
+        def valid?(digits) = (checksum(digits) % 10).zero?
+
+        def checksum(digits)
+          digits.reverse.each_with_index.sum { |digit, index| index.even? ? digit : doubled(digit) }
+        end
+
+        def doubled(digit)
+          value = digit * 2
+          value > 9 ? value - 9 : value
+        end
+        private_class_method :doubled
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/pii/luhn_validator.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'luhn_checksum'
+
+module Olyx
+  module Guardrails
+    module Pii
+      # Validates card-like digit sequences with the Luhn checksum.
+      module LuhnValidator
+        MINIMUM_LENGTH = 13
+
+        module_function
+
+        def call(number)
+          digits = LuhnChecksum.digits(number)
+          digits.length >= MINIMUM_LENGTH && LuhnChecksum.valid?(digits)
+        end
+      end
+    end
+  end
+end