lex-agentic-inference 0.1.0

data/spec/legion/extensions/agentic/inference/counterfactual/helpers/scenario_spec.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Inference::Counterfactual::Helpers::Scenario do
+  let(:base_params) do
+    {
+      scenario_type:          :upward,
+      mutation_type:          :action,
+      actual_outcome:         'project failed',
+      counterfactual_outcome: 'project succeeded',
+      antecedent:             'had reviewed code',
+      domain:                 :engineering,
+      plausibility:           0.8,
+      regret_magnitude:       0.6
+    }
+  end
+
+  subject(:scenario) { described_class.new(**base_params) }
+
+  describe '#initialize' do
+    it 'assigns a UUID id' do
+      expect(scenario.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'assigns scenario_type' do
+      expect(scenario.scenario_type).to eq(:upward)
+    end
+
+    it 'assigns mutation_type' do
+      expect(scenario.mutation_type).to eq(:action)
+    end
+
+    it 'assigns actual_outcome' do
+      expect(scenario.actual_outcome).to eq('project failed')
+    end
+
+    it 'assigns counterfactual_outcome' do
+      expect(scenario.counterfactual_outcome).to eq('project succeeded')
+    end
+
+    it 'assigns antecedent' do
+      expect(scenario.antecedent).to eq('had reviewed code')
+    end
+
+    it 'assigns domain' do
+      expect(scenario.domain).to eq(:engineering)
+    end
+
+    it 'clamps plausibility to [0, 1]' do
+      s = described_class.new(**base_params, plausibility: 1.5)
+      expect(s.plausibility).to eq(1.0)
+    end
+
+    it 'clamps regret_magnitude to [0, 1]' do
+      s = described_class.new(**base_params, regret_magnitude: -0.5)
+      expect(s.regret_magnitude).to eq(0.0)
+    end
+
+    it 'starts unresolved' do
+      expect(scenario.resolved).to be false
+    end
+
+    it 'sets created_at' do
+      expect(scenario.created_at).to be_a(Time)
+    end
+
+    it 'has nil lesson initially' do
+      expect(scenario.lesson).to be_nil
+    end
+
+    it 'has nil resolved_at initially' do
+      expect(scenario.resolved_at).to be_nil
+    end
+  end
+
+  describe '#upward?' do
+    it 'returns true for upward type' do
+      expect(scenario.upward?).to be true
+    end
+
+    it 'returns false for non-upward type' do
+      s = described_class.new(**base_params, scenario_type: :downward)
+      expect(s.upward?).to be false
+    end
+  end
+
+  describe '#downward?' do
+    it 'returns true for downward type' do
+      s = described_class.new(**base_params, scenario_type: :downward)
+      expect(s.downward?).to be true
+    end
+
+    it 'returns false for upward type' do
+      expect(scenario.downward?).to be false
+    end
+  end
+
+  describe '#prefactual?' do
+    it 'returns true for prefactual type' do
+      s = described_class.new(**base_params, scenario_type: :prefactual)
+      expect(s.prefactual?).to be true
+    end
+
+    it 'returns false for upward type' do
+      expect(scenario.prefactual?).to be false
+    end
+  end
+
+  describe '#emotional_response' do
+    it 'returns :regret for upward' do
+      expect(scenario.emotional_response).to eq(:regret)
+    end
+
+    it 'returns :relief for downward' do
+      s = described_class.new(**base_params, scenario_type: :downward)
+      expect(s.emotional_response).to eq(:relief)
+    end
+
+    it 'returns :acceptance for semifactual' do
+      s = described_class.new(**base_params, scenario_type: :semifactual)
+      expect(s.emotional_response).to eq(:acceptance)
+    end
+
+    it 'returns :anxiety for prefactual' do
+      s = described_class.new(**base_params, scenario_type: :prefactual)
+      expect(s.emotional_response).to eq(:anxiety)
+    end
+
+    it 'returns :neutral for unmapped types' do
+      s = described_class.new(**base_params, scenario_type: :additive)
+      expect(s.emotional_response).to eq(:neutral)
+    end
+  end
+
+  describe '#emotional_valence' do
+    it 'is negative for upward (regret)' do
+      expect(scenario.emotional_valence).to be < 0
+    end
+
+    it 'is positive for downward (relief)' do
+      s = described_class.new(**base_params, scenario_type: :downward)
+      expect(s.emotional_valence).to be > 0
+    end
+
+    it 'is -0.2 for prefactual' do
+      s = described_class.new(**base_params, scenario_type: :prefactual)
+      expect(s.emotional_valence).to eq(-0.2)
+    end
+
+    it 'is 0.0 for additive (unmapped)' do
+      s = described_class.new(**base_params, scenario_type: :additive)
+      expect(s.emotional_valence).to eq(0.0)
+    end
+  end
+
+  describe '#resolve' do
+    it 'marks scenario as resolved' do
+      scenario.resolve(lesson: 'always review code')
+      expect(scenario.resolved).to be true
+    end
+
+    it 'sets the lesson' do
+      scenario.resolve(lesson: 'always review code')
+      expect(scenario.lesson).to eq('always review code')
+    end
+
+    it 'sets resolved_at' do
+      scenario.resolve(lesson: 'lesson')
+      expect(scenario.resolved_at).to be_a(Time)
+    end
+
+    it 'returns self' do
+      result = scenario.resolve(lesson: 'lesson')
+      expect(result).to eq(scenario)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with all key fields' do
+      h = scenario.to_h
+      expect(h[:id]).to eq(scenario.id)
+      expect(h[:scenario_type]).to eq(:upward)
+      expect(h[:mutation_type]).to eq(:action)
+      expect(h[:actual_outcome]).to eq('project failed')
+      expect(h[:counterfactual_outcome]).to eq('project succeeded')
+      expect(h[:antecedent]).to eq('had reviewed code')
+      expect(h[:domain]).to eq(:engineering)
+      expect(h[:plausibility]).to eq(0.8)
+      expect(h[:regret_magnitude]).to eq(0.6)
+      expect(h[:emotional_response]).to eq(:regret)
+      expect(h[:resolved]).to be false
+    end
+  end
+end

data/spec/legion/extensions/agentic/inference/counterfactual/runners/counterfactual_spec.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Inference::Counterfactual::Runners::Counterfactual do
+  let(:client) { Legion::Extensions::Agentic::Inference::Counterfactual::Client.new }
+
+  let(:valid_imagine_params) do
+    {
+      actual_outcome:         'deployment failed',
+      counterfactual_outcome: 'deployment succeeded',
+      antecedent:             'had run staging first',
+      scenario_type:          :upward,
+      mutation_type:          :action,
+      domain:                 :ops,
+      plausibility:           0.8
+    }
+  end
+
+  describe '#imagine_counterfactual' do
+    it 'returns success: true with a scenario hash' do
+      result = client.imagine_counterfactual(**valid_imagine_params)
+      expect(result[:success]).to be true
+      expect(result[:scenario]).to be_a(Hash)
+    end
+
+    it 'scenario hash includes expected keys' do
+      result = client.imagine_counterfactual(**valid_imagine_params)
+      s = result[:scenario]
+      expect(s[:id]).not_to be_nil
+      expect(s[:scenario_type]).to eq(:upward)
+      expect(s[:domain]).to eq(:ops)
+    end
+
+    it 'returns success: false for invalid scenario_type' do
+      result = client.imagine_counterfactual(**valid_imagine_params, scenario_type: :invalid)
+      expect(result[:success]).to be false
+      expect(result[:error]).to eq(:invalid_scenario_type)
+    end
+
+    it 'returns success: false for invalid mutation_type' do
+      result = client.imagine_counterfactual(**valid_imagine_params, mutation_type: :bogus)
+      expect(result[:success]).to be false
+      expect(result[:error]).to eq(:invalid_mutation_type)
+    end
+
+    it 'accepts all valid counterfactual types' do
+      Legion::Extensions::Agentic::Inference::Counterfactual::Helpers::Constants::COUNTERFACTUAL_TYPES.each do |type|
+        result = client.imagine_counterfactual(**valid_imagine_params, scenario_type: type)
+        expect(result[:success]).to be true
+      end
+    end
+
+    it 'accepts all valid mutation types' do
+      Legion::Extensions::Agentic::Inference::Counterfactual::Helpers::Constants::MUTATION_TYPES.each do |mutation|
+        result = client.imagine_counterfactual(**valid_imagine_params, mutation_type: mutation)
+        expect(result[:success]).to be true
+      end
+    end
+
+    it 'ignores extra keyword arguments' do
+      result = client.imagine_counterfactual(**valid_imagine_params, extra_key: 'ignored')
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#generate_alternatives' do
+    it 'returns success: true with alternatives array' do
+      result = client.generate_alternatives(actual_outcome: 'outcome', domain: :testing)
+      expect(result[:success]).to be true
+      expect(result[:alternatives]).to be_an(Array)
+      expect(result[:count]).to be > 0
+    end
+
+    it 'count matches alternatives length' do
+      result = client.generate_alternatives(actual_outcome: 'outcome', domain: :testing)
+      expect(result[:count]).to eq(result[:alternatives].size)
+    end
+  end
+
+  describe '#resolve_counterfactual' do
+    it 'resolves an existing scenario' do
+      imagine_result = client.imagine_counterfactual(**valid_imagine_params)
+      scenario_id = imagine_result[:scenario][:id]
+
+      result = client.resolve_counterfactual(scenario_id: scenario_id, lesson: 'always use staging')
+      expect(result[:success]).to be true
+      expect(result[:scenario][:lesson]).to eq('always use staging')
+      expect(result[:scenario][:resolved]).to be true
+    end
+
+    it 'returns success: false for unknown scenario_id' do
+      result = client.resolve_counterfactual(scenario_id: 'does-not-exist', lesson: 'lesson')
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:not_found)
+    end
+  end
+
+  describe '#compute_regret' do
+    it 'returns success: true with regret value' do
+      imagine_result = client.imagine_counterfactual(**valid_imagine_params)
+      scenario_id = imagine_result[:scenario][:id]
+
+      result = client.compute_regret(scenario_id: scenario_id)
+      expect(result[:success]).to be true
+      expect(result[:regret]).to be_a(Float)
+    end
+
+    it 'returns 0.0 for unknown scenario' do
+      result = client.compute_regret(scenario_id: 'ghost')
+      expect(result[:success]).to be true
+      expect(result[:regret]).to eq(0.0)
+    end
+  end
+
+  describe '#net_regret_level' do
+    it 'returns success: true with net_regret float' do
+      result = client.net_regret_level
+      expect(result[:success]).to be true
+      expect(result[:net_regret]).to be_a(Float)
+    end
+
+    it 'increases after adding upward scenarios' do
+      before = client.net_regret_level[:net_regret]
+      client.imagine_counterfactual(**valid_imagine_params, scenario_type: :upward, plausibility: 1.0)
+      after = client.net_regret_level[:net_regret]
+      expect(after).to be > before
+    end
+  end
+
+  describe '#domain_regret' do
+    it 'returns success: true with domain-specific regret' do
+      result = client.domain_regret(domain: :ops)
+      expect(result[:success]).to be true
+      expect(result[:domain]).to eq(:ops)
+      expect(result[:regret]).to be_a(Float)
+    end
+  end
+
+  describe '#lessons_learned' do
+    it 'returns empty lessons array when none resolved' do
+      result = client.lessons_learned
+      expect(result[:success]).to be true
+      expect(result[:lessons]).to be_an(Array)
+      expect(result[:count]).to eq(0)
+    end
+
+    it 'returns lessons after resolving scenarios' do
+      imagine_result = client.imagine_counterfactual(**valid_imagine_params)
+      client.resolve_counterfactual(
+        scenario_id: imagine_result[:scenario][:id],
+        lesson:      'test everything'
+      )
+      result = client.lessons_learned
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#update_counterfactual' do
+    it 'returns success: true with action: :regret_decay' do
+      result = client.update_counterfactual
+      expect(result[:success]).to be true
+      expect(result[:action]).to eq(:regret_decay)
+    end
+  end
+
+  describe '#counterfactual_stats' do
+    it 'returns success: true with stats hash' do
+      result = client.counterfactual_stats
+      expect(result[:success]).to be true
+      expect(result[:stats]).to be_a(Hash)
+      expect(result[:stats][:total]).to be_a(Integer)
+    end
+
+    it 'tracks total after adding scenarios' do
+      client.imagine_counterfactual(**valid_imagine_params)
+      result = client.counterfactual_stats
+      expect(result[:stats][:total]).to eq(1)
+    end
+  end
+end

data/spec/legion/extensions/agentic/inference/debugging/client_spec.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/inference/debugging/client'
+
+RSpec.describe Legion::Extensions::Agentic::Inference::Debugging::Client do
+  it 'responds to all runner methods' do
+    client = described_class.new
+    expect(client).to respond_to(:detect_error)
+    expect(client).to respond_to(:trace_error)
+    expect(client).to respond_to(:propose_correction)
+    expect(client).to respond_to(:apply_correction)
+    expect(client).to respond_to(:measure_correction)
+    expect(client).to respond_to(:resolve_error)
+    expect(client).to respond_to(:active_errors)
+    expect(client).to respond_to(:resolved_errors)
+    expect(client).to respond_to(:errors_by_type)
+    expect(client).to respond_to(:errors_by_phase)
+    expect(client).to respond_to(:most_common_error_type)
+    expect(client).to respond_to(:most_effective_strategy)
+    expect(client).to respond_to(:correction_success_rate)
+    expect(client).to respond_to(:debugging_report)
+    expect(client).to respond_to(:snapshot)
+  end
+
+  it 'accepts an injected engine' do
+    engine = Legion::Extensions::Agentic::Inference::Debugging::Helpers::DebuggingEngine.new
+    client = described_class.new(engine: engine)
+    result = client.detect_error(
+      error_type:              :overconfidence,
+      description:             'Test injection',
+      severity:                0.5,
+      source_phase:            :tick,
+      confidence_at_detection: 0.8
+    )
+    expect(result[:success]).to be true
+    expect(engine.errors.size).to eq(1)
+  end
+
+  it 'creates a fresh engine when none injected' do
+    c1 = described_class.new
+    c2 = described_class.new
+    c1.detect_error(error_type: :inconsistency, description: 'x', severity: 0.5,
+                    source_phase: :tick, confidence_at_detection: 0.5)
+    expect(c2.active_errors[:count]).to eq(0)
+  end
+end

data/spec/legion/extensions/agentic/inference/debugging/helpers/causal_trace_spec.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Inference::Debugging::Helpers::CausalTrace do
+  let(:trace) do
+    described_class.new(error_id: 'error-uuid', root_cause: :faulty_premise, confidence: 0.8)
+  end
+
+  describe '#initialize' do
+    it 'assigns a UUID id' do
+      expect(trace.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets error_id' do
+      expect(trace.error_id).to eq('error-uuid')
+    end
+
+    it 'sets root_cause' do
+      expect(trace.root_cause).to eq(:faulty_premise)
+    end
+
+    it 'clamps confidence to [0, 1]' do
+      t = described_class.new(error_id: 'x', root_cause: :y, confidence: 1.5)
+      expect(t.confidence).to eq(1.0)
+    end
+
+    it 'initializes empty steps' do
+      expect(trace.steps).to be_empty
+    end
+  end
+
+  describe '#add_step!' do
+    it 'appends a step with phase, description, and timestamp' do
+      trace.add_step!(phase: :emotional_evaluation, description: 'Urgency spike caused premature conclusion')
+      expect(trace.steps.size).to eq(1)
+      step = trace.steps.first
+      expect(step[:phase]).to eq(:emotional_evaluation)
+      expect(step[:description]).to eq('Urgency spike caused premature conclusion')
+      expect(step[:timestamp]).to be_a(Time)
+    end
+
+    it 'returns self for chaining' do
+      result = trace.add_step!(phase: :tick, description: 'step 1')
+      expect(result).to be(trace)
+    end
+
+    it 'accumulates multiple steps' do
+      trace.add_step!(phase: :tick, description: 'step 1')
+      trace.add_step!(phase: :memory_retrieval, description: 'step 2')
+      trace.add_step!(phase: :prediction_engine, description: 'step 3')
+      expect(trace.steps.size).to eq(3)
+    end
+  end
+
+  describe '#depth' do
+    it 'returns 0 for empty trace' do
+      expect(trace.depth).to eq(0)
+    end
+
+    it 'returns step count' do
+      trace.add_step!(phase: :tick, description: 'a')
+      trace.add_step!(phase: :tick, description: 'b')
+      expect(trace.depth).to eq(2)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with expected keys' do
+      trace.add_step!(phase: :tick, description: 'step')
+      h = trace.to_h
+      expect(h).to include(:id, :error_id, :steps, :root_cause, :confidence, :depth)
+    end
+
+    it 'includes depth in hash' do
+      trace.add_step!(phase: :tick, description: 'step')
+      expect(trace.to_h[:depth]).to eq(1)
+    end
+
+    it 'returns dup of steps' do
+      trace.add_step!(phase: :tick, description: 'step')
+      h = trace.to_h
+      expect(h[:steps]).not_to be(trace.steps)
+    end
+  end
+end

data/spec/legion/extensions/agentic/inference/debugging/helpers/constants_spec.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Inference::Debugging::Helpers::Constants do
+  describe 'ERROR_TYPES' do
+    it 'contains 8 error types' do
+      expect(described_class::ERROR_TYPES.size).to eq(8)
+    end
+
+    it 'includes :inconsistency' do
+      expect(described_class::ERROR_TYPES).to include(:inconsistency)
+    end
+
+    it 'includes :circular_logic' do
+      expect(described_class::ERROR_TYPES).to include(:circular_logic)
+    end
+
+    it 'includes :overconfidence' do
+      expect(described_class::ERROR_TYPES).to include(:overconfidence)
+    end
+
+    it 'includes :confirmation_bias' do
+      expect(described_class::ERROR_TYPES).to include(:confirmation_bias)
+    end
+
+    it 'is frozen' do
+      expect(described_class::ERROR_TYPES).to be_frozen
+    end
+  end
+
+  describe 'CORRECTION_STRATEGIES' do
+    it 'contains 7 strategies' do
+      expect(described_class::CORRECTION_STRATEGIES.size).to eq(7)
+    end
+
+    it 'includes :retrace' do
+      expect(described_class::CORRECTION_STRATEGIES).to include(:retrace)
+    end
+
+    it 'includes :devil_advocate' do
+      expect(described_class::CORRECTION_STRATEGIES).to include(:devil_advocate)
+    end
+
+    it 'is frozen' do
+      expect(described_class::CORRECTION_STRATEGIES).to be_frozen
+    end
+  end
+
+  describe 'capacity limits' do
+    it 'sets MAX_ERRORS to 300' do
+      expect(described_class::MAX_ERRORS).to eq(300)
+    end
+
+    it 'sets MAX_TRACES to 500' do
+      expect(described_class::MAX_TRACES).to eq(500)
+    end
+
+    it 'sets MAX_CORRECTIONS to 200' do
+      expect(described_class::MAX_CORRECTIONS).to eq(200)
+    end
+  end
+
+  describe '.severity_label' do
+    it 'returns :trivial for 0.0' do
+      expect(described_class.severity_label(0.0)).to eq(:trivial)
+    end
+
+    it 'returns :trivial for 0.1' do
+      expect(described_class.severity_label(0.1)).to eq(:trivial)
+    end
+
+    it 'returns :minor for 0.2' do
+      expect(described_class.severity_label(0.2)).to eq(:minor)
+    end
+
+    it 'returns :moderate for 0.4' do
+      expect(described_class.severity_label(0.4)).to eq(:moderate)
+    end
+
+    it 'returns :major for 0.6' do
+      expect(described_class.severity_label(0.6)).to eq(:major)
+    end
+
+    it 'returns :critical for 0.8' do
+      expect(described_class.severity_label(0.8)).to eq(:critical)
+    end
+
+    it 'returns :critical for 1.0' do
+      expect(described_class.severity_label(1.0)).to eq(:critical)
+    end
+  end
+
+  describe 'STATUS_LABELS' do
+    it 'contains expected statuses' do
+      expect(described_class::STATUS_LABELS).to include(:detected, :traced, :correcting, :resolved, :unresolvable)
+    end
+  end
+end

data/spec/legion/extensions/agentic/inference/debugging/helpers/correction_spec.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Inference::Debugging::Helpers::Correction do
+  let(:correction) do
+    described_class.new(error_id: 'error-uuid', strategy: :retrace, description: 'Re-examine assumptions')
+  end
+
+  describe '#initialize' do
+    it 'assigns a UUID id' do
+      expect(correction.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets error_id' do
+      expect(correction.error_id).to eq('error-uuid')
+    end
+
+    it 'sets strategy' do
+      expect(correction.strategy).to eq(:retrace)
+    end
+
+    it 'sets description' do
+      expect(correction.description).to eq('Re-examine assumptions')
+    end
+
+    it 'initializes applied as false' do
+      expect(correction.applied).to be false
+    end
+
+    it 'initializes effectiveness as nil' do
+      expect(correction.effectiveness).to be_nil
+    end
+  end
+
+  describe '#apply!' do
+    it 'sets applied to true' do
+      correction.apply!
+      expect(correction.applied).to be true
+    end
+
+    it 'returns self for chaining' do
+      expect(correction.apply!).to be(correction)
+    end
+  end
+
+  describe '#measure_effectiveness!' do
+    it 'sets effectiveness' do
+      correction.measure_effectiveness!(0.8)
+      expect(correction.effectiveness).to eq(0.8)
+    end
+
+    it 'clamps effectiveness to [0, 1]' do
+      correction.measure_effectiveness!(1.5)
+      expect(correction.effectiveness).to eq(1.0)
+    end
+
+    it 'clamps negative values to 0.0' do
+      correction.measure_effectiveness!(-0.2)
+      expect(correction.effectiveness).to eq(0.0)
+    end
+
+    it 'returns self for chaining' do
+      expect(correction.measure_effectiveness!(0.7)).to be(correction)
+    end
+  end
+
+  describe '#effective?' do
+    it 'returns false when effectiveness is nil' do
+      expect(correction.effective?).to be false
+    end
+
+    it 'returns true when effectiveness >= 0.6' do
+      correction.measure_effectiveness!(0.6)
+      expect(correction.effective?).to be true
+    end
+
+    it 'returns true for high effectiveness' do
+      correction.measure_effectiveness!(0.9)
+      expect(correction.effective?).to be true
+    end
+
+    it 'returns false when effectiveness < 0.6' do
+      correction.measure_effectiveness!(0.5)
+      expect(correction.effective?).to be false
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes expected keys' do
+      h = correction.to_h
+      expect(h).to include(:id, :error_id, :strategy, :description, :applied, :effectiveness, :effective)
+    end
+
+    it 'reflects effective? result' do
+      correction.measure_effectiveness!(0.7)
+      expect(correction.to_h[:effective]).to be true
+    end
+  end
+end