lex-mental-simulation 0.1.0

data/spec/legion/extensions/mental_simulation/helpers/simulation_engine_spec.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::MentalSimulation::Helpers::SimulationEngine do
+  subject(:engine) { described_class.new }
+
+  let(:label)  { 'deploy pipeline' }
+  let(:domain) { :infrastructure }
+
+  def build_favorable_simulation
+    sim = engine.create_simulation(label: label, domain: domain)
+    engine.add_simulation_step(simulation_id: sim.id, action: 'check', confidence: 0.9, risk: 0.05)
+    engine.add_simulation_step(simulation_id: sim.id, action: 'deploy', confidence: 0.85, risk: 0.05)
+    sim
+  end
+
+  def build_risky_simulation
+    sim = engine.create_simulation(label: 'risky plan', domain: :security)
+    engine.add_simulation_step(simulation_id: sim.id, action: 'dangerous op', confidence: 0.9, risk: 0.8)
+    sim
+  end
+
+  describe '#create_simulation' do
+    it 'creates a simulation and returns it' do
+      sim = engine.create_simulation(label: label, domain: domain)
+      expect(sim).to be_a(Legion::Extensions::MentalSimulation::Helpers::Simulation)
+    end
+
+    it 'stores the simulation internally' do
+      sim = engine.create_simulation(label: label, domain: domain)
+      expect(engine.assess_simulation(simulation_id: sim.id)[:label]).to eq(label)
+    end
+  end
+
+  describe '#add_simulation_step' do
+    it 'returns added: true on success' do
+      sim = engine.create_simulation(label: label, domain: domain)
+      result = engine.add_simulation_step(simulation_id: sim.id, action: 'check prereqs')
+      expect(result[:added]).to be true
+    end
+
+    it 'returns step_id' do
+      sim = engine.create_simulation(label: label, domain: domain)
+      result = engine.add_simulation_step(simulation_id: sim.id, action: 'check')
+      expect(result[:step_id]).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'returns error for unknown simulation_id' do
+      result = engine.add_simulation_step(simulation_id: 'no-such-id', action: 'go')
+      expect(result[:error]).to eq(:simulation_not_found)
+    end
+
+    it 'returns error when max steps reached' do
+      sim = engine.create_simulation(label: label, domain: domain)
+      Legion::Extensions::MentalSimulation::Helpers::Constants::MAX_STEPS_PER_SIM.times do |i|
+        engine.add_simulation_step(simulation_id: sim.id, action: "step #{i}")
+      end
+      result = engine.add_simulation_step(simulation_id: sim.id, action: 'one too many')
+      expect(result[:error]).to eq(:max_steps_reached)
+    end
+  end
+
+  describe '#run_simulation' do
+    it 'returns state after running' do
+      sim = build_favorable_simulation
+      result = engine.run_simulation(simulation_id: sim.id)
+      expect(result[:state]).to be_a(Symbol)
+    end
+
+    it 'returns favorable: true for a good plan' do
+      sim = build_favorable_simulation
+      result = engine.run_simulation(simulation_id: sim.id)
+      expect(result[:favorable]).to be true
+    end
+
+    it 'returns error for unknown simulation' do
+      result = engine.run_simulation(simulation_id: 'ghost')
+      expect(result[:error]).to eq(:simulation_not_found)
+    end
+
+    it 'returns overall_confidence in result' do
+      sim = build_favorable_simulation
+      result = engine.run_simulation(simulation_id: sim.id)
+      expect(result[:overall_confidence]).to be > 0
+    end
+
+    it 'returns cumulative_risk in result' do
+      sim = build_favorable_simulation
+      result = engine.run_simulation(simulation_id: sim.id)
+      expect(result[:cumulative_risk]).to be >= 0
+    end
+  end
+
+  describe '#abort_simulation' do
+    it 'aborts a simulation and returns aborted: true' do
+      sim = engine.create_simulation(label: label, domain: domain)
+      result = engine.abort_simulation(simulation_id: sim.id)
+      expect(result[:aborted]).to be true
+      expect(result[:state]).to eq(:aborted)
+    end
+
+    it 'returns error for unknown simulation' do
+      result = engine.abort_simulation(simulation_id: 'ghost')
+      expect(result[:error]).to eq(:simulation_not_found)
+    end
+  end
+
+  describe '#assess_simulation' do
+    it 'returns full assessment without running' do
+      sim = engine.create_simulation(label: label, domain: domain)
+      engine.add_simulation_step(simulation_id: sim.id, action: 'assess me')
+      result = engine.assess_simulation(simulation_id: sim.id)
+      expect(result[:state]).to eq(:pending)
+      expect(result[:steps].size).to eq(1)
+    end
+
+    it 'returns error for unknown simulation' do
+      result = engine.assess_simulation(simulation_id: 'ghost')
+      expect(result[:error]).to eq(:simulation_not_found)
+    end
+
+    it 'includes confidence and risk in assessment' do
+      sim = engine.create_simulation(label: label, domain: domain)
+      engine.add_simulation_step(simulation_id: sim.id, action: 'step', confidence: 0.7, risk: 0.2)
+      result = engine.assess_simulation(simulation_id: sim.id)
+      expect(result[:overall_confidence]).to eq(0.7)
+      expect(result[:cumulative_risk]).to be_within(0.001).of(0.2)
+    end
+  end
+
+  describe '#favorable_simulations' do
+    it 'returns only favorable simulations' do
+      sim = build_favorable_simulation
+      engine.run_simulation(simulation_id: sim.id)
+      favs = engine.favorable_simulations
+      expect(favs).not_to be_empty
+      expect(favs.all?(&:favorable?)).to be true
+    end
+
+    it 'excludes non-favorable simulations' do
+      sim = engine.create_simulation(label: label, domain: domain)
+      engine.add_simulation_step(simulation_id: sim.id, action: 'low conf', confidence: 0.2, risk: 0.1)
+      engine.run_simulation(simulation_id: sim.id)
+      favs = engine.favorable_simulations
+      expect(favs.map(&:id)).not_to include(sim.id)
+    end
+  end
+
+  describe '#failed_simulations' do
+    it 'returns simulations in :failed state' do
+      sim = engine.create_simulation(label: label, domain: domain)
+      engine.add_simulation_step(simulation_id: sim.id, action: 'low conf', confidence: 0.2, risk: 0.1)
+      engine.run_simulation(simulation_id: sim.id)
+      failed = engine.failed_simulations
+      expect(failed.map(&:id)).to include(sim.id)
+    end
+  end
+
+  describe '#simulations_by_domain' do
+    it 'returns simulations for the specified domain' do
+      sim_a = engine.create_simulation(label: 'a', domain: :networking)
+      sim_b = engine.create_simulation(label: 'b', domain: :security)
+      result = engine.simulations_by_domain(domain: :networking)
+      expect(result.map(&:id)).to include(sim_a.id)
+      expect(result.map(&:id)).not_to include(sim_b.id)
+    end
+
+    it 'handles domain as string by converting to symbol' do
+      sim = engine.create_simulation(label: 'str domain', domain: :cloud)
+      result = engine.simulations_by_domain(domain: 'cloud')
+      expect(result.map(&:id)).to include(sim.id)
+    end
+  end
+
+  describe '#riskiest_simulations' do
+    it 'returns simulations sorted by descending cumulative_risk' do
+      low_risk_sim = engine.create_simulation(label: 'safe', domain: :app)
+      engine.add_simulation_step(simulation_id: low_risk_sim.id, action: 'safe', risk: 0.1)
+
+      high_risk_sim = build_risky_simulation
+
+      result = engine.riskiest_simulations(limit: 2)
+      expect(result.first.id).to eq(high_risk_sim.id)
+    end
+
+    it 'respects the limit parameter' do
+      3.times { |i| engine.create_simulation(label: "sim #{i}", domain: :test) }
+      expect(engine.riskiest_simulations(limit: 2).size).to be <= 2
+    end
+  end
+
+  describe '#most_confident' do
+    it 'returns simulations sorted by descending overall_confidence' do
+      low_conf_sim = engine.create_simulation(label: 'uncertain', domain: :app)
+      engine.add_simulation_step(simulation_id: low_conf_sim.id, action: 'maybe', confidence: 0.2)
+
+      high_conf_sim = engine.create_simulation(label: 'sure', domain: :app)
+      engine.add_simulation_step(simulation_id: high_conf_sim.id, action: 'definitely', confidence: 0.95)
+
+      result = engine.most_confident(limit: 2)
+      expect(result.first.id).to eq(high_conf_sim.id)
+    end
+
+    it 'respects the limit parameter' do
+      4.times { |i| engine.create_simulation(label: "sim #{i}", domain: :test) }
+      expect(engine.most_confident(limit: 2).size).to be <= 2
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns engine summary hash' do
+      engine.create_simulation(label: label, domain: domain)
+      h = engine.to_h
+      expect(h).to include(:total_simulations, :history_size, :favorable_count, :failed_count, :simulations)
+      expect(h[:total_simulations]).to eq(1)
+    end
+  end
+end

data/spec/legion/extensions/mental_simulation/helpers/simulation_spec.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::MentalSimulation::Helpers::Simulation do
+  subject(:sim) { described_class.new(label: 'test plan', domain: :infrastructure) }
+
+  describe '#initialize' do
+    it 'generates a UUID id' do
+      expect(sim.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores the label' do
+      expect(sim.label).to eq('test plan')
+    end
+
+    it 'stores the domain as a symbol' do
+      expect(sim.domain).to eq(:infrastructure)
+    end
+
+    it 'starts with no steps' do
+      expect(sim.steps).to be_empty
+    end
+
+    it 'starts in :pending state' do
+      expect(sim.state).to eq(:pending)
+    end
+
+    it 'records created_at' do
+      expect(sim.created_at).to be_a(Time)
+    end
+
+    it 'has nil completed_at initially' do
+      expect(sim.completed_at).to be_nil
+    end
+  end
+
+  describe '#add_step' do
+    it 'adds a SimulationStep and returns it' do
+      step = sim.add_step(action: 'check health')
+      expect(step).to be_a(Legion::Extensions::MentalSimulation::Helpers::SimulationStep)
+    end
+
+    it 'increments step_count' do
+      sim.add_step(action: 'step one')
+      sim.add_step(action: 'step two')
+      expect(sim.step_count).to eq(2)
+    end
+
+    it 'passes parameters through to the step' do
+      step = sim.add_step(action: 'deploy', predicted_outcome: :failure, confidence: 0.3, risk: 0.8)
+      expect(step.predicted_outcome).to eq(:failure)
+      expect(step.confidence).to eq(0.3)
+      expect(step.risk).to eq(0.8)
+    end
+  end
+
+  describe '#overall_confidence' do
+    it 'returns 0.0 when no steps' do
+      expect(sim.overall_confidence).to eq(0.0)
+    end
+
+    it 'returns product of step confidences' do
+      sim.add_step(action: 'a', confidence: 0.8)
+      sim.add_step(action: 'b', confidence: 0.5)
+      expect(sim.overall_confidence).to be_within(0.001).of(0.4)
+    end
+
+    it 'returns single step confidence when only one step' do
+      sim.add_step(action: 'a', confidence: 0.75)
+      expect(sim.overall_confidence).to eq(0.75)
+    end
+  end
+
+  describe '#cumulative_risk' do
+    it 'returns 0.0 when no steps' do
+      expect(sim.cumulative_risk).to eq(0.0)
+    end
+
+    it 'computes combined risk correctly' do
+      sim.add_step(action: 'a', risk: 0.2)
+      sim.add_step(action: 'b', risk: 0.3)
+      # 1 - (0.8 * 0.7) = 1 - 0.56 = 0.44
+      expect(sim.cumulative_risk).to be_within(0.001).of(0.44)
+    end
+
+    it 'returns high risk when steps have high individual risk' do
+      sim.add_step(action: 'a', risk: 0.9)
+      sim.add_step(action: 'b', risk: 0.9)
+      expect(sim.cumulative_risk).to be > 0.9
+    end
+  end
+
+  describe '#run!' do
+    context 'with favorable steps' do
+      before do
+        sim.add_step(action: 'check prereqs', confidence: 0.9, risk: 0.1)
+        sim.add_step(action: 'deploy', confidence: 0.8, risk: 0.1)
+      end
+
+      it 'sets state to :completed' do
+        sim.run!
+        expect(sim.state).to eq(:completed)
+      end
+
+      it 'sets completed_at' do
+        sim.run!
+        expect(sim.completed_at).to be_a(Time)
+      end
+    end
+
+    context 'when a step predicts failure with high confidence' do
+      before do
+        sim.add_step(action: 'safe step', confidence: 0.9, risk: 0.1)
+        sim.add_step(action: 'dangerous step', predicted_outcome: :failure, confidence: 0.8, risk: 0.5)
+      end
+
+      it 'aborts the simulation' do
+        sim.run!
+        expect(sim.state).to eq(:aborted)
+      end
+    end
+
+    context 'with low overall confidence' do
+      before do
+        sim.add_step(action: 'a', confidence: 0.3, risk: 0.1)
+        sim.add_step(action: 'b', confidence: 0.3, risk: 0.1)
+      end
+
+      it 'sets state to :failed' do
+        sim.run!
+        expect(sim.state).to eq(:failed)
+      end
+    end
+
+    context 'with high cumulative risk' do
+      before do
+        sim.add_step(action: 'a', confidence: 0.9, risk: 0.7)
+        sim.add_step(action: 'b', confidence: 0.9, risk: 0.7)
+      end
+
+      it 'sets state to :failed when cumulative risk >= 0.6' do
+        sim.run!
+        expect(sim.state).to eq(:failed)
+      end
+    end
+
+    it 'sets state to :running briefly and transitions' do
+      sim.add_step(action: 'a', confidence: 0.9, risk: 0.1)
+      sim.run!
+      expect(%i[completed failed aborted]).to include(sim.state)
+    end
+  end
+
+  describe '#abort!' do
+    it 'sets state to :aborted' do
+      sim.abort!
+      expect(sim.state).to eq(:aborted)
+    end
+
+    it 'sets completed_at' do
+      sim.abort!
+      expect(sim.completed_at).to be_a(Time)
+    end
+  end
+
+  describe '#favorable?' do
+    it 'returns false for pending simulation' do
+      sim.add_step(action: 'a', confidence: 0.9, risk: 0.1)
+      expect(sim.favorable?).to be false
+    end
+
+    it 'returns true for completed simulation with good confidence and low risk' do
+      sim.add_step(action: 'a', confidence: 0.9, risk: 0.1)
+      sim.add_step(action: 'b', confidence: 0.9, risk: 0.1)
+      sim.run!
+      expect(sim.favorable?).to be true
+    end
+
+    it 'returns false for aborted simulation' do
+      sim.add_step(action: 'a', predicted_outcome: :failure, confidence: 0.9, risk: 0.5)
+      sim.run!
+      expect(sim.favorable?).to be false
+    end
+  end
+
+  describe '#confidence_label' do
+    it 'returns :very_confident for high overall confidence' do
+      sim.add_step(action: 'a', confidence: 0.95)
+      expect(sim.confidence_label).to eq(:very_confident)
+    end
+
+    it 'returns :very_doubtful when no steps' do
+      expect(sim.confidence_label).to eq(:very_doubtful)
+    end
+  end
+
+  describe '#risk_label' do
+    it 'returns :negligible for low risk' do
+      sim.add_step(action: 'a', risk: 0.1)
+      expect(sim.risk_label).to eq(:negligible)
+    end
+
+    it 'returns :critical for very high risk' do
+      sim.add_step(action: 'a', risk: 0.95)
+      sim.add_step(action: 'b', risk: 0.95)
+      expect(sim.risk_label).to eq(:critical)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a complete hash' do
+      sim.add_step(action: 'test step')
+      h = sim.to_h
+      expect(h).to include(:id, :label, :domain, :state, :step_count, :overall_confidence,
+                           :cumulative_risk, :confidence_label, :risk_label, :favorable, :steps)
+    end
+
+    it 'includes step hashes' do
+      sim.add_step(action: 'step one')
+      h = sim.to_h
+      expect(h[:steps].first[:action]).to eq('step one')
+    end
+  end
+end

data/spec/legion/extensions/mental_simulation/helpers/simulation_step_spec.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::MentalSimulation::Helpers::SimulationStep do
+  subject(:step) { described_class.new(action: 'deploy service') }
+
+  describe '#initialize' do
+    it 'generates a UUID id' do
+      expect(step.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores the action' do
+      expect(step.action).to eq('deploy service')
+    end
+
+    it 'defaults predicted_outcome to :success' do
+      expect(step.predicted_outcome).to eq(:success)
+    end
+
+    it 'defaults confidence to 0.5' do
+      expect(step.confidence).to eq(0.5)
+    end
+
+    it 'defaults risk to 0.1' do
+      expect(step.risk).to eq(0.1)
+    end
+
+    it 'defaults preconditions to empty array' do
+      expect(step.preconditions).to eq([])
+    end
+
+    it 'defaults postconditions to empty array' do
+      expect(step.postconditions).to eq([])
+    end
+
+    it 'records created_at' do
+      expect(step.created_at).to be_a(Time)
+    end
+
+    it 'clamps confidence above 1.0 to 1.0' do
+      s = described_class.new(action: 'test', confidence: 1.5)
+      expect(s.confidence).to eq(1.0)
+    end
+
+    it 'clamps confidence below 0.0 to 0.0' do
+      s = described_class.new(action: 'test', confidence: -0.5)
+      expect(s.confidence).to eq(0.0)
+    end
+
+    it 'clamps risk above 1.0 to 1.0' do
+      s = described_class.new(action: 'test', risk: 2.0)
+      expect(s.risk).to eq(1.0)
+    end
+  end
+
+  describe '#favorable?' do
+    it 'returns true for success with sufficient confidence' do
+      s = described_class.new(action: 'go', predicted_outcome: :success, confidence: 0.8)
+      expect(s.favorable?).to be true
+    end
+
+    it 'returns true for partial_success with sufficient confidence' do
+      s = described_class.new(action: 'go', predicted_outcome: :partial_success, confidence: 0.6)
+      expect(s.favorable?).to be true
+    end
+
+    it 'returns false for success with low confidence' do
+      s = described_class.new(action: 'go', predicted_outcome: :success, confidence: 0.4)
+      expect(s.favorable?).to be false
+    end
+
+    it 'returns false for failure regardless of confidence' do
+      s = described_class.new(action: 'go', predicted_outcome: :failure, confidence: 0.9)
+      expect(s.favorable?).to be false
+    end
+
+    it 'returns false for unknown outcome' do
+      s = described_class.new(action: 'go', predicted_outcome: :unknown, confidence: 0.9)
+      expect(s.favorable?).to be false
+    end
+  end
+
+  describe '#risky?' do
+    it 'returns true when risk >= 0.6' do
+      s = described_class.new(action: 'go', risk: 0.7)
+      expect(s.risky?).to be true
+    end
+
+    it 'returns false when risk < 0.6' do
+      s = described_class.new(action: 'go', risk: 0.4)
+      expect(s.risky?).to be false
+    end
+
+    it 'returns true at exactly 0.6' do
+      s = described_class.new(action: 'go', risk: 0.6)
+      expect(s.risky?).to be true
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with all fields' do
+      h = step.to_h
+      expect(h).to include(:id, :action, :predicted_outcome, :confidence, :risk,
+                           :preconditions, :postconditions, :created_at)
+    end
+
+    it 'includes stored preconditions' do
+      s = described_class.new(action: 'go', preconditions: ['service_up'])
+      expect(s.to_h[:preconditions]).to eq(['service_up'])
+    end
+  end
+end