decision_agent 0.3.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '095f5b6604126a4288548c648efbfb3f88cc94bf2a51ba84b21f422286c9c0f3'
-  data.tar.gz: 0f5475b14f32d3f7524ba63d21152bda4d088312dc1b154a6c15dd73f8e038e0
+  metadata.gz: c6c760652b22f7cf3e4524aec1757f1fba1fc21c206c960ad3836eed18279f13
+  data.tar.gz: e0c2f21dfac36d7a4ce7935d6ea38375265c64e15eec4c276c514a1bf759dd6e
 SHA512:
-  metadata.gz: 60f10c33779fac9cf26ed698a704b91e4ff65ca200d76870fa593a9074506b10a7791a471ab5cbb0fcdc9603145dc965131508619f0f1356f163cdaf069f49c9
-  data.tar.gz: d60e5eaf6d7350a55047594481c00360fa188e66db11e84cf863c7c734d1210c777e7fb358a689470d84256dd225b22376deb50648443dd0257a5041816086c1
+  metadata.gz: d9a402f62fa86a4cf83d727f048b6de8a8d67ab317cbc3dd2d681cd537a2a1a68a1bbe77b2f34a4c6f4a805babace2e7c6d449435d8fef9831dff884152b441a
+  data.tar.gz: 2b00ae31f1e89caa62c004c6e649296e1c6a193faf90ded7ef2fd6e930b3c5547113d028349de2b6904bfb9e2371fd37335251b6391bac4315cda1ca6407c4e8

data/README.md

@@ -3,7 +3,7 @@
 [![Gem Version](https://badge.fury.io/rb/decision_agent.svg)](https://badge.fury.io/rb/decision_agent)
 [![CI](https://github.com/samaswin/decision_agent/actions/workflows/ci.yml/badge.svg)](https://github.com/samaswin/decision_agent/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
-[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%202.7.0-red.svg)](https://www.ruby-lang.org)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.0.0-red.svg)](https://www.ruby-lang.org)
 
 A production-grade, deterministic, explainable, and auditable decision engine for Ruby.
 
@@ -14,8 +14,8 @@ A production-grade, deterministic, explainable, and auditable decision engine fo
 DecisionAgent is designed for applications that require **deterministic, explainable, and auditable** decision-making:
 
 - ✅ **Deterministic** - Same input always produces same output
-- ✅ **Explainable** - Every decision includes human-readable reasoning
-- ✅ **Auditable** - Reproduce any historical decision exactly
+- ✅ **Explainable** - Every decision includes human-readable reasoning and machine-readable condition traces
+- ✅ **Auditable** - Reproduce any historical decision exactly with complete explainability
 - ✅ **Framework-agnostic** - Pure Ruby, works anywhere
 - ✅ **Production-ready** - Comprehensive testing ([Coverage Report](coverage.md)), error handling, and versioning
 
@@ -55,9 +55,12 @@ agent = DecisionAgent::Agent.new(evaluators: [evaluator])
 # Make decision
 result = agent.decide(context: { amount: 1500 })
 
-puts result.decision      # => "approve"
-puts result.confidence    # => 0.9
-puts result.explanations  # => ["High value transaction"]
+puts result.decision           # => "approve"
+puts result.confidence         # => 0.9
+puts result.explanations       # => ["High value transaction"]
+puts result.because            # => ["amount > 1000"]
+puts result.failed_conditions  # => []
+puts result.explainability     # => { decision: "approve", because: [...], failed_conditions: [] }
 ```
 
 See [Code Examples](docs/CODE_EXAMPLES.md) for more comprehensive examples.
@@ -72,23 +75,48 @@ See [Code Examples](docs/CODE_EXAMPLES.md) for more comprehensive examples.
 
 ### Auditability & Compliance
 - **Complete Audit Trails** - Every decision fully logged
+- **Explainability Layer** - Machine-readable condition traces for every decision
+  - `result.because` - Conditions that led to the decision
+  - `result.failed_conditions` - Conditions that failed
+  - `result.explainability` - Complete machine-readable explainability data
 - **Deterministic Replay** - Reproduce historical decisions exactly
 - **RFC 8785 Canonical JSON** - Industry-standard deterministic hashing
 - **Compliance Ready** - HIPAA, SOX, regulatory compliance support
 
+### Testing & Simulation
+- **Simulation & What-If Analysis** - Test rule changes before deployment
+  - **Historical Replay / Backtesting** - Replay past decisions with new rules (CSV, JSON, database import)
+  - **What-If Analysis** - Simulate scenarios and sensitivity analysis with decision boundary visualization
+  - **Impact Analysis** - Quantify rule change effects (decision distribution, confidence shifts, performance impact)
+  - **Shadow Testing** - Compare new rules against production without affecting outcomes
+  - **Monte Carlo Simulation** - Model probabilistic inputs and understand decision outcome probabilities
+- **Batch Testing** - Test rules against large datasets with CSV/Excel import, coverage analysis, and resume capability
+- **A/B Testing** - Champion/Challenger testing with statistical significance analysis
+
+### Security & Access Control
+- **Role-Based Access Control (RBAC)** - Enterprise-grade authentication and authorization
+  - Built-in user/role system with bcrypt password hashing
+  - Configurable adapters for Devise, CanCanCan, Pundit, or custom auth systems
+  - 5 default roles (Admin, Editor, Viewer, Auditor, Approver) with 7 permissions
+  - Password reset functionality with secure token management
+  - Comprehensive access audit logging for compliance
+  - Web UI integration with login and user management pages
+
 ### Developer Experience
 - **Pluggable Architecture** - Custom evaluators, scoring, audit adapters
-- **Framework Agnostic** - Works with Rails, Sinatra, or standalone
+- **Framework Agnostic** - Works with Rails, Rack, or standalone
 - **JSON Rule DSL** - Non-technical users can write rules
 - **DMN 1.3 Support** - Industry-standard Decision Model and Notation with full FEEL expression language
 - **Visual Rule Builder** - Web UI for rule management and DMN modeler
+- **CLI Tools** - Command-line interface for DMN import/export and web server
 
 ### Production Features
 - **Real-time Monitoring** - Live dashboard with WebSocket updates
+- **Persistent Monitoring** - Database storage for long-term analytics (PostgreSQL, MySQL, SQLite)
 - **Prometheus Export** - Industry-standard metrics format
 - **Intelligent Alerting** - Anomaly detection with customizable rules
 - **Grafana Integration** - Pre-built dashboards and alert rules
-- **Version Control** - Full rule version control and rollback
+- **Version Control** - Full rule version control, rollback, and history ([Versioning Guide](docs/VERSIONING.md))
 - **Thread-Safe** - Safe for multi-threaded servers and background jobs
 - **High Performance** - 10,000+ decisions/second, ~0.1ms latency
 
@@ -102,6 +130,8 @@ decision_agent web
 
 Open [http://localhost:4567](http://localhost:4567) in your browser.
 
+The Web UI includes a **DMN visual modeler** at `/dmn/editor` for building and editing decision tables.
+
 ### Integration
 
 **Rails:**
@@ -112,7 +142,7 @@ Rails.application.routes.draw do
 end
 ```
 
-**Rack/Sinatra:**
+**Rack:**
 ```ruby
 require 'decision_agent/web/server'
 map '/decision_agent' do
@@ -120,7 +150,7 @@ map '/decision_agent' do
 end
 ```
 
-See [Web UI Integration Guide](docs/WEB_UI_RAILS_INTEGRATION.md) for detailed setup.
+See [Web UI Integration Guide](docs/WEB_UI_INTEGRATION.md) for detailed setup with Rails, Sinatra, Hanami, and other frameworks.
 
 ## DMN (Decision Model and Notation) Support
 
@@ -175,11 +205,159 @@ Open [http://localhost:4568](http://localhost:4568) for the monitoring dashboard
 
 **Features:**
 - Real-time dashboard with WebSocket updates
+- **Persistent Storage** - Database storage for long-term analytics (PostgreSQL, MySQL, SQLite)
 - Prometheus metrics export
 - Intelligent alerting with anomaly detection
 - Grafana integration with pre-built dashboards
 
-See [Monitoring & Analytics Guide](docs/MONITORING_AND_ANALYTICS.md) for complete documentation.
+See [Monitoring & Analytics Guide](docs/MONITORING_AND_ANALYTICS.md) and [Persistent Monitoring Guide](docs/PERSISTENT_MONITORING.md) for complete documentation.
+
+## Simulation & What-If Analysis
+
+DecisionAgent provides comprehensive simulation capabilities to test rule changes before deployment:
+
+```ruby
+require 'decision_agent/simulation/replay_engine'
+require 'decision_agent/simulation/what_if_analyzer'
+require 'decision_agent/simulation/impact_analyzer'
+
+# Replay historical decisions with new rules
+replay_engine = DecisionAgent::Simulation::ReplayEngine.new(
+  agent: agent,
+  version_manager: version_manager
+)
+results = replay_engine.replay(historical_data: "decisions.csv")
+
+# What-if analysis (scenarios = array of context hashes)
+whatif = DecisionAgent::Simulation::WhatIfAnalyzer.new(agent: agent)
+analysis = whatif.analyze(
+  scenarios: [
+    { credit_score: 700, amount: 50000 },
+    { credit_score: 750, amount: 50000 },
+    { credit_score: 650, amount: 50000 }
+  ]
+)
+
+# Impact analysis (compare two rule versions on test data)
+impact = DecisionAgent::Simulation::ImpactAnalyzer.new(version_manager: version_manager)
+comparison = impact.analyze(
+  baseline_version: baseline_version_id,
+  proposed_version: proposed_version_id,
+  test_data: test_contexts
+)
+```
+
+**Features:**
+- **Historical Replay** - Replay past decisions with CSV/JSON/database import
+- **What-If Analysis** - Scenario simulation with decision boundary visualization
+- **Impact Analysis** - Quantify rule change effects (decisions, confidence, performance)
+- **Shadow Testing** - Test new rules in production without affecting outcomes
+- **Monte Carlo Simulation** - Probabilistic decision modeling
+- **Web UI** - Complete simulation dashboard at `/simulation`
+
+See [Simulation Guide](docs/SIMULATION.md) for complete documentation and [Simulation Example](examples/simulation_example.rb) for working examples.
+
+## Role-Based Access Control (RBAC)
+
+Enterprise-grade authentication and authorization system:
+
+```ruby
+require 'decision_agent'
+
+# Configure RBAC (works with any auth system)
+DecisionAgent.configure_rbac(:devise_cancan, ability_class: Ability)
+
+# Or use built-in RBAC
+authenticator = DecisionAgent::Auth::Authenticator.new
+admin = authenticator.create_user(
+  email: "admin@example.com",
+  password: "secure_password",
+  roles: [:admin]
+)
+
+session = authenticator.login("admin@example.com", "secure_password")
+
+# Permission checks
+checker = DecisionAgent.permission_checker
+checker.can?(admin, :write)  # => true
+checker.can?(admin, :approve)  # => true
+```
+
+**Features:**
+- **Built-in User System** - User management with bcrypt password hashing
+- **5 Default Roles** - Admin, Editor, Viewer, Auditor, Approver
+- **Configurable Adapters** - Devise, CanCanCan, Pundit, or custom
+- **Password Reset** - Secure token-based password reset
+- **Access Audit Logging** - Comprehensive audit trail for compliance
+- **Web UI Integration** - Login page and user management interface
+
+See [RBAC Configuration Guide](docs/RBAC_CONFIGURATION.md) for complete documentation and [RBAC Examples](examples/rbac_configuration_examples.rb) for integration examples.
+
+## Batch Testing
+
+Test rules against large datasets with comprehensive analysis:
+
+```ruby
+require 'decision_agent/testing/batch_test_runner'
+require 'decision_agent/testing/batch_test_importer'
+
+runner = DecisionAgent::Testing::BatchTestRunner.new(agent)
+
+# Import from CSV or Excel (context columns default to all except id/expected_*)
+importer = DecisionAgent::Testing::BatchTestImporter.new
+scenarios = importer.import_csv("test_data.csv")
+
+# Run batch test
+results = runner.run(scenarios)
+
+stats = runner.statistics
+puts "Total: #{stats[:total]}"
+puts "Passed: #{stats[:successful]}"
+puts "Failed: #{stats[:failed]}"
+puts "Success rate: #{(stats[:success_rate] * 100).round(2)}%"
+```
+
+**Features:**
+- **CSV/Excel Import** - Import test scenarios from files
+- **Database Import** - Load test data from databases
+- **Coverage Analysis** - Identify untested rule combinations
+- **Resume Capability** - Continue interrupted tests from checkpoint
+- **Progress Tracking** - Real-time progress updates for large imports
+- **Web UI** - Complete batch testing interface with file upload
+
+See [Batch Testing Guide](docs/BATCH_TESTING.md) for complete documentation.
+
+## A/B Testing
+
+Compare rule versions with statistical analysis:
+
+```ruby
+require 'decision_agent/ab_testing/ab_test_manager'
+
+ab_manager = DecisionAgent::ABTesting::ABTestManager.new(version_manager: version_manager)
+
+test = ab_manager.create_test(
+  name: "loan_approval_v2",
+  champion_version_id: champion_version_id,
+  challenger_version_id: challenger_version_id,
+  traffic_split: { champion: 90, challenger: 10 }
+)
+
+# Assign variant per request, then record decisions; when done, get results
+assignment = ab_manager.assign_variant(test_id: test.id, user_id: "user_123")
+# ... run agent with assignment[:version_id], then:
+ab_manager.record_decision(assignment_id: assignment[:assignment_id], decision: "approve", confidence: 0.9)
+
+results = ab_manager.get_results(test.id)
+```
+
+**Features:**
+- **Champion/Challenger Testing** - Compare baseline vs proposed rules
+- **Statistical Significance** - P-value calculation and confidence intervals
+- **Traffic Splitting** - Configurable split ratios
+- **Decision Distribution Comparison** - Visualize differences in outcomes
+
+See [A/B Testing Guide](docs/AB_TESTING.md) for complete documentation.
 
 ## When to Use DecisionAgent
 
@@ -204,6 +382,7 @@ See [Monitoring & Analytics Guide](docs/MONITORING_AND_ANALYTICS.md) for complet
 - [Examples Directory](examples/README.md) - Working examples with explanations
 
 ### Core Features
+- [Explainability Layer](docs/EXPLAINABILITY.md) - Machine-readable decision explanations with condition-level tracing
 - [Advanced Operators](docs/ADVANCED_OPERATORS.md) - String, numeric, date/time, collection, and geospatial operators
 - [DMN Guide](docs/DMN_GUIDE.md) - Complete DMN 1.3 support guide
 - [DMN API Reference](docs/DMN_API.md) - DMN API documentation
@@ -211,16 +390,25 @@ See [Monitoring & Analytics Guide](docs/MONITORING_AND_ANALYTICS.md) for complet
 - [DMN Migration Guide](docs/DMN_MIGRATION_GUIDE.md) - Migrating from JSON to DMN
 - [DMN Best Practices](docs/DMN_BEST_PRACTICES.md) - DMN modeling best practices
 - [Versioning System](docs/VERSIONING.md) - Version control for rules
+- [Simulation & What-If Analysis](docs/SIMULATION.md) - Historical replay, what-if analysis, impact analysis, and shadow testing
 - [A/B Testing](docs/AB_TESTING.md) - Compare rule versions with statistical analysis
+- [Batch Testing](docs/BATCH_TESTING.md) - Test rules against large datasets with CSV/Excel import
+- [RBAC Configuration](docs/RBAC_CONFIGURATION.md) - Role-based access control setup and integration
+- [RBAC Quick Reference](docs/RBAC_QUICK_REFERENCE.md) - Quick reference for RBAC configuration
 - [Web UI](docs/WEB_UI.md) - Visual rule builder
 - [Web UI Setup](docs/WEB_UI_SETUP.md) - Setup guide
-- [Web UI Rails Integration](docs/WEB_UI_RAILS_INTEGRATION.md) - Mount in Rails/Rack apps
+- [Web UI Integration](docs/WEB_UI_INTEGRATION.md) - Mount in Rails, Sinatra, Hanami, and other Rack frameworks
 - [Monitoring & Analytics](docs/MONITORING_AND_ANALYTICS.md) - Real-time monitoring, metrics, and alerting
 - [Monitoring Architecture](docs/MONITORING_ARCHITECTURE.md) - System architecture and design
+- [Persistent Monitoring](docs/PERSISTENT_MONITORING.md) - Database storage for long-term analytics
 
 ### Performance & Thread-Safety
 - [Performance & Thread-Safety Summary](docs/PERFORMANCE_AND_THREAD_SAFETY.md) - Benchmarks and production readiness
 - [Thread-Safety Implementation](docs/THREAD_SAFETY.md) - Technical implementation guide
+- [Benchmarks](benchmarks/README.md) - Comprehensive benchmark suite and performance testing
+
+### Development
+- [Development Setup](docs/DEVELOPMENT_SETUP.md) - Development environment setup, testing, and tools
 
 ### Reference
 - [API Contract](docs/API_CONTRACT.md) - Full API reference
@@ -244,12 +432,44 @@ All data structures are deeply frozen to prevent mutation, ensuring safe concurr
 
 See [Thread-Safety Guide](docs/THREAD_SAFETY.md) and [Performance Analysis](docs/PERFORMANCE_AND_THREAD_SAFETY.md) for details.
 
+**Run Benchmarks:**
+```bash
+# Run all benchmarks (single Ruby version)
+rake benchmark:all
+
+# Run specific benchmarks
+rake benchmark:basic      # Basic decision performance
+rake benchmark:threads    # Thread-safety and scalability
+rake benchmark:regression # Compare against baseline
+
+# Run benchmarks across all Ruby versions (3.0.7, 3.1.6, 3.2.5, 3.3.5)
+./scripts/benchmark_all_ruby_versions.sh
+
+# See [Benchmarks Guide](benchmarks/README.md) for complete documentation
+```
+
+### Latest Benchmark Results
+
+Run `rake benchmark:regression` to generate results for your environment. Example (Ruby 3.3, typical hardware):
+
+| Metric | Typical range |
+|--------|----------------|
+| Basic throughput | ~9,000+ decisions/sec |
+| Basic latency | ~0.1 ms |
+| Multi-threaded (50 threads) | ~8,500+ decisions/sec |
+
+> 💡 **Note:** See [Benchmarks Guide](benchmarks/README.md) and run `rake benchmark:all` or `rake benchmark:regression` for current numbers.
 ## Contributing
 
 1. Fork the repository
 2. Create a feature branch
-3. Add tests (maintain 90%+ coverage)
-4. Submit a pull request
+3. Set up development environment (see [Development Setup](docs/DEVELOPMENT_SETUP.md))
+4. Add tests (maintain 90%+ coverage)
+5. Run tests across all Ruby versions: `./scripts/test_all_ruby_versions.sh`
+6. Run benchmarks across all Ruby versions: `./scripts/benchmark_all_ruby_versions.sh`
+7. Submit a pull request
+
+See [Development Setup Guide](docs/DEVELOPMENT_SETUP.md) for detailed setup instructions, testing workflows, and development best practices.
 
 ## Support
 

data/lib/decision_agent/ab_testing/ab_test.rb

@@ -1,3 +1,7 @@
+# frozen_string_literal: true
+
+require "openssl"
+
 module DecisionAgent
   module ABTesting
     # Represents an A/B test configuration for comparing rule versions
@@ -41,7 +45,7 @@ module DecisionAgent
 
         if user_id
           # Consistent hashing: same user always gets same variant
-          hash_value = Digest::SHA256.hexdigest("#{@id}:#{user_id}").to_i(16)
+          hash_value = OpenSSL::Digest::SHA256.hexdigest("#{@id}:#{user_id}").to_i(16)
           percentage = hash_value % 100
         else
           # Random assignment

data/lib/decision_agent/ab_testing/ab_test_assignment.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module DecisionAgent
   module ABTesting
     # Tracks individual assignments of users/requests to A/B test variants

data/lib/decision_agent/ab_testing/ab_test_manager.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "monitor"
 
 module DecisionAgent

data/lib/decision_agent/ab_testing/ab_testing_agent.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module DecisionAgent
   module ABTesting
     # Agent wrapper that adds A/B testing capabilities to the standard Agent

data/lib/decision_agent/ab_testing/storage/activerecord_adapter.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "active_record"
 
 module DecisionAgent
@@ -86,19 +88,6 @@ module DecisionAgent
         end
         # rubocop:enable Naming/PredicateMethod
 
-        # Get statistics from database
-        def get_test_statistics(test_id)
-          assignments = ::ABTestAssignmentModel.where(ab_test_id: test_id)
-
-          {
-            total_assignments: assignments.count,
-            champion_count: assignments.where(variant: "champion").count,
-            challenger_count: assignments.where(variant: "challenger").count,
-            with_decisions: assignments.where.not(decision_result: nil).count,
-            avg_confidence: assignments.where.not(confidence: nil).average(:confidence)&.to_f
-          }
-        end
-
         private
 
         def to_ab_test(record)

data/lib/decision_agent/ab_testing/storage/adapter.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module DecisionAgent
   module ABTesting
     module Storage

data/lib/decision_agent/ab_testing/storage/memory_adapter.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "monitor"
 
 module DecisionAgent

data/lib/decision_agent/agent.rb

@@ -1,11 +1,30 @@
-require "digest"
+# frozen_string_literal: true
+
 require "json"
 require "json/canonicalization"
+require "openssl"
 
 module DecisionAgent
+  # Agent runs multiple evaluators over a context, scores their evaluations,
+  # and returns a single {Decision} with the chosen outcome and confidence.
   class Agent
     attr_reader :evaluators, :scoring_strategy, :audit_adapter
 
+    # Thread-safe cache for deterministic hash computation
+    # This significantly improves performance when the same context/evaluations
+    # are processed multiple times (common in benchmarks and high-throughput scenarios)
+    @hash_cache = {}
+    @hash_cache_mutex = Mutex.new
+    @hash_cache_max_size = 1000 # Limit cache size to prevent memory bloat
+
+    class << self
+      attr_reader :hash_cache, :hash_cache_mutex, :hash_cache_max_size
+    end
+
+    # @param evaluators [Array<#evaluate>] Objects that respond to #evaluate(context, feedback:)
+    # @param scoring_strategy [Scoring::Base, nil] Strategy to score evaluations (default: WeightedAverage)
+    # @param audit_adapter [Audit::Base, nil] Adapter for recording decisions (default: NullAdapter)
+    # @param validate_evaluations [Boolean, nil] If true, validate evaluations; nil = validate unless production
     def initialize(evaluators:, scoring_strategy: nil, audit_adapter: nil, validate_evaluations: nil)
       @evaluators = Array(evaluators)
       @scoring_strategy = scoring_strategy || Scoring::WeightedAverage.new
@@ -19,6 +38,12 @@ module DecisionAgent
       @evaluators.freeze
     end
 
+    # Runs all evaluators on the context, scores results, and returns a single decision.
+    #
+    # @param context [Context, Hash] Input data; converted to {Context} if a Hash
+    # @param feedback [Hash] Optional feedback passed to each evaluator
+    # @return [Decision] The chosen decision with confidence, explanations, and audit payload
+    # @raise [NoEvaluationsError] when no evaluator returns a valid evaluation
     def decide(context:, feedback: {})
       ctx = context.is_a?(Context) ? context : Context.new(context)
 
@@ -76,7 +101,8 @@ module DecisionAgent
     def collect_evaluations(context, feedback)
       @evaluators.map do |evaluator|
         evaluator.evaluate(context, feedback: feedback)
-      rescue StandardError
+      rescue StandardError => e
+        warn "[DecisionAgent] Evaluator #{evaluator.class} failed: #{e.message}"
         nil
       end.compact
     end
@@ -89,20 +115,20 @@ module DecisionAgent
       explanations << "Decision: #{final_decision} (confidence: #{confidence.round(2)})"
 
       if matching_evals.size == 1
-        eval = matching_evals.first
-        explanations << "#{eval.evaluator_name}: #{eval.reason} (weight: #{eval.weight})"
+        evaluation = matching_evals.first
+        explanations << "#{evaluation.evaluator_name}: #{evaluation.reason} (weight: #{evaluation.weight})"
       elsif matching_evals.size > 1
         explanations << "Based on #{matching_evals.size} evaluators:"
-        matching_evals.each do |eval|
-          explanations << "  - #{eval.evaluator_name}: #{eval.reason} (weight: #{eval.weight})"
+        matching_evals.each do |evaluation|
+          explanations << "  - #{evaluation.evaluator_name}: #{evaluation.reason} (weight: #{evaluation.weight})"
         end
       end
 
       conflicting_evals = evaluations.reject { |e| e.decision == final_decision }
       if conflicting_evals.any?
         explanations << "Conflicting evaluations resolved by #{@scoring_strategy.class.name.split('::').last}:"
-        conflicting_evals.each do |eval|
-          explanations << "  - #{eval.evaluator_name}: suggested '#{eval.decision}' (weight: #{eval.weight})"
+        conflicting_evals.each do |evaluation|
+          explanations << "  - #{evaluation.evaluator_name}: suggested '#{evaluation.decision}' (weight: #{evaluation.weight})"
         end
       end
 
@@ -129,8 +155,51 @@ module DecisionAgent
 
     def compute_deterministic_hash(payload)
       hashable = payload.slice(:context, :evaluations, :decision, :confidence, :scoring_strategy)
+
+      # Use fast hash (MD5) as cache key to avoid expensive canonicalization on cache hits
+      # The cache key doesn't need perfect determinism, just good enough to catch duplicates
+      # Use OpenSSL::Digest to avoid "Digest::Base cannot be directly inherited" on some Ruby/digest setups
+      json_str = hashable.to_json
+      fast_key = OpenSSL::Digest::MD5.hexdigest(json_str)
+
+      # Fast path: check cache without lock first (unsafe read, but acceptable for cache)
+      cached_hash = lookup_cached_hash(fast_key)
+      return cached_hash if cached_hash
+
+      # Cache miss - compute canonical JSON and hash
+      computed_hash = compute_canonical_hash(hashable)
+
+      # Store in cache (thread-safe, with size limit)
+      cache_hash(fast_key, computed_hash)
+
+      computed_hash
+    end
+
+    def lookup_cached_hash(fast_key)
+      self.class.hash_cache[fast_key]
+    end
+
+    def compute_canonical_hash(hashable)
       canonical = canonical_json(hashable)
-      Digest::SHA256.hexdigest(canonical)
+      OpenSSL::Digest::SHA256.hexdigest(canonical)
+    end
+
+    def cache_hash(fast_key, computed_hash)
+      self.class.hash_cache_mutex.synchronize do
+        # Double-check after acquiring lock (another thread may have added it)
+        return self.class.hash_cache[fast_key] if self.class.hash_cache[fast_key]
+
+        evict_cache_if_needed
+        self.class.hash_cache[fast_key] = computed_hash
+      end
+    end
+
+    def evict_cache_if_needed
+      return unless self.class.hash_cache.size >= self.class.hash_cache_max_size
+
+      # Remove oldest 10% of entries (simple FIFO eviction)
+      keys_to_remove = self.class.hash_cache.keys.first(self.class.hash_cache_max_size / 10)
+      keys_to_remove.each { |key| self.class.hash_cache.delete(key) }
     end
 
     # Uses RFC 8785 (JSON Canonicalization Scheme) for deterministic JSON serialization

data/lib/decision_agent/audit/adapter.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module DecisionAgent
   module Audit
     class Adapter

data/lib/decision_agent/audit/logger_adapter.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "logger"
 require "json"
 

data/lib/decision_agent/audit/null_adapter.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module DecisionAgent
   module Audit
     class NullAdapter < Adapter

data/lib/decision_agent/auth/access_audit_logger.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "json"
 require_relative "../audit/adapter"
 

data/lib/decision_agent/auth/authenticator.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module DecisionAgent
   module Auth
     class Authenticator

data/lib/decision_agent/auth/password_reset_manager.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module DecisionAgent
   module Auth
     class PasswordResetManager

data/lib/decision_agent/auth/password_reset_token.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "securerandom"
 
 module DecisionAgent

data/lib/decision_agent/auth/permission.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module DecisionAgent
   module Auth
     class Permission

data/lib/decision_agent/auth/permission_checker.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module DecisionAgent
   module Auth
     class PermissionChecker

data/lib/decision_agent/auth/rbac_adapter.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module DecisionAgent
   module Auth
     # Base adapter interface for RBAC integration

data/lib/decision_agent/auth/rbac_config.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module DecisionAgent
   module Auth
     # Configuration class for RBAC adapter

data/lib/decision_agent/auth/role.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module DecisionAgent
   module Auth
     class Role