lex-agentic-imagination 0.1.0

data/spec/legion/extensions/agentic/imagination/imagery/runners/imagination_spec.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Imagination::Imagery::Runners::Imagination do
+  let(:client) { Legion::Extensions::Agentic::Imagination::Imagery::Client.new }
+
+  describe '#simulate' do
+    it 'simulates multiple actions' do
+      result = client.simulate(actions: %w[deploy rollback wait])
+      expect(result[:scenarios].size).to eq(3)
+      expect(result).to have_key(:recommendation)
+    end
+
+    it 'limits to MAX_SCENARIOS' do
+      actions = (1..10).map { |i| "action_#{i}" }
+      result = client.simulate(actions: actions)
+      expect(result[:scenarios].size).to be <= Legion::Extensions::Agentic::Imagination::Imagery::Helpers::Constants::MAX_SCENARIOS
+    end
+
+    it 'stores simulation in history' do
+      client.simulate(actions: %w[deploy])
+      expect(client.simulation_store.size).to eq(1)
+    end
+
+    it 'recommends the best action' do
+      result = client.simulate(
+        actions:        %w[safe_action risky_action],
+        context:        { familiar: true, alignment: 0.8 },
+        risk_tolerance: :conservative
+      )
+      expect(result[:recommendation]).to have_key(:action)
+      expect(result[:recommendation]).to have_key(:composite)
+    end
+
+    it 'respects risk tolerance' do
+      conservative = client.simulate(actions: %w[deploy], risk_tolerance: :conservative)
+      aggressive = client.simulate(actions: %w[deploy], risk_tolerance: :aggressive)
+      expect(conservative[:recommendation]).not_to be_nil
+      expect(aggressive[:recommendation]).not_to be_nil
+    end
+  end
+
+  describe '#what_if' do
+    it 'returns scenario with consequence chain' do
+      result = client.what_if(action: 'merge_without_tests', depth: 2)
+      expect(result[:consequence_chain].size).to eq(3)
+      expect(result[:depth]).to eq(2)
+    end
+
+    it 'limits depth to MAX_DEPTH' do
+      result = client.what_if(action: 'test', depth: 100)
+      expect(result[:depth]).to eq(Legion::Extensions::Agentic::Imagination::Imagery::Helpers::Constants::MAX_DEPTH)
+    end
+
+    it 'returns overall valence' do
+      result = client.what_if(action: 'safe_deploy', context: { familiar: true })
+      expect(result[:overall_valence]).to be_a(Symbol)
+    end
+  end
+
+  describe '#compare' do
+    it 'compares two actions' do
+      result = client.compare(action_a: 'refactor', action_b: 'ship_now')
+      expect(%i[a b]).to include(result[:winner])
+      expect(result).to have_key(:margin)
+      expect(result).to have_key(:decisive)
+    end
+
+    it 'returns scenario details for both' do
+      result = client.compare(action_a: 'a', action_b: 'b')
+      expect(result[:scenario_a]).to have_key(:expected_value)
+      expect(result[:scenario_b]).to have_key(:expected_value)
+    end
+  end
+
+  describe '#record_actual_outcome' do
+    it 'records outcome for existing simulation' do
+      sim = client.simulate(actions: %w[deploy])
+      result = client.record_actual_outcome(
+        simulation_id:  sim[:simulation_id],
+        actual_outcome: { valence: :positive }
+      )
+      expect(result[:accurate]).not_to be_nil
+    end
+
+    it 'returns error for missing simulation' do
+      result = client.record_actual_outcome(simulation_id: 'nonexistent', actual_outcome: {})
+      expect(result[:error]).to eq(:not_found)
+    end
+  end
+
+  describe '#imagination_stats' do
+    it 'returns stats summary' do
+      client.simulate(actions: %w[deploy])
+      result = client.imagination_stats
+      expect(result[:total_simulations]).to eq(1)
+      expect(result).to have_key(:by_mode)
+    end
+  end
+end

data/spec/legion/extensions/agentic/imagination/liminal/client_spec.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Imagination::Liminal::Client do
+  subject(:client) { described_class.new }
+
+  it 'responds to runner methods' do
+    expect(client).to respond_to(:begin_crossing, :advance_crossing, :liminal_status)
+  end
+
+  it 'runs a full liminal lifecycle' do
+    result = client.begin_crossing(origin: :analytical, destination: :creative, domain: :cognitive)
+    crossing_id = result[:crossing][:id]
+
+    5.times { client.advance_crossing(crossing_id: crossing_id) }
+    client.dissolve_crossing(crossing_id: crossing_id)
+    10.times { client.crystallize_crossing(crossing_id: crossing_id) }
+
+    status = client.liminal_status
+    expect(status[:total_crossings]).to eq(1)
+  end
+end

data/spec/legion/extensions/agentic/imagination/liminal/cognitive_liminal_spec.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Imagination::Liminal do
+  it 'has a version number' do
+    expect(Legion::Extensions::Agentic::Imagination::Liminal::VERSION).to eq('0.1.0')
+  end
+end

data/spec/legion/extensions/agentic/imagination/liminal/helpers/liminal_engine_spec.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Imagination::Liminal::Helpers::LiminalEngine do
+  subject(:engine) { described_class.new }
+
+  describe '#begin_crossing' do
+    it 'creates a threshold crossing' do
+      crossing = engine.begin_crossing(origin: :analytical, destination: :creative)
+      expect(crossing.origin).to eq(:analytical)
+    end
+  end
+
+  describe '#advance_crossing' do
+    it 'advances known crossing' do
+      crossing = engine.begin_crossing(origin: :analytical, destination: :creative)
+      engine.advance_crossing(crossing_id: crossing.id)
+      expect(crossing.ticks_in_liminal).to eq(1)
+    end
+
+    it 'returns nil for unknown crossing' do
+      expect(engine.advance_crossing(crossing_id: 'bad')).to be_nil
+    end
+  end
+
+  describe '#dissolve_crossing' do
+    it 'dissolves known crossing' do
+      crossing = engine.begin_crossing(origin: :focused, destination: :diffuse)
+      original = crossing.ambiguity
+      engine.dissolve_crossing(crossing_id: crossing.id)
+      expect(crossing.ambiguity).to be > original
+    end
+  end
+
+  describe '#crystallize_crossing' do
+    it 'crystallizes known crossing' do
+      crossing = engine.begin_crossing(origin: :intuitive, destination: :deliberate)
+      original = crossing.ambiguity
+      engine.crystallize_crossing(crossing_id: crossing.id)
+      expect(crossing.ambiguity).to be < original
+    end
+  end
+
+  describe '#active_crossings' do
+    it 'returns active crossings' do
+      engine.begin_crossing(origin: :analytical, destination: :creative)
+      expect(engine.active_crossings.size).to eq(1)
+    end
+  end
+
+  describe '#completed_crossings' do
+    it 'returns completed crossings' do
+      crossing = engine.begin_crossing(origin: :analytical, destination: :creative)
+      20.times { crossing.advance! }
+      expect(engine.completed_crossings.size).to eq(1)
+    end
+  end
+
+  describe '#liminal_crossings' do
+    it 'returns crossings in margin phase' do
+      crossing = engine.begin_crossing(origin: :analytical, destination: :creative)
+      5.times { crossing.advance! }
+      expect(engine.liminal_crossings.size).to eq(1)
+    end
+  end
+
+  describe '#fertile_crossings' do
+    it 'returns fertile crossings' do
+      engine.begin_crossing(origin: :analytical, destination: :creative)
+      expect(engine.fertile_crossings.size).to eq(1)
+    end
+  end
+
+  describe '#crossings_by_domain' do
+    it 'filters by domain' do
+      engine.begin_crossing(origin: :analytical, destination: :creative, domain: :cognitive)
+      engine.begin_crossing(origin: :focused, destination: :diffuse, domain: :emotional)
+      expect(engine.crossings_by_domain(domain: :cognitive).size).to eq(1)
+    end
+  end
+
+  describe '#average_ambiguity' do
+    it 'returns 0.0 with no active crossings' do
+      expect(engine.average_ambiguity).to eq(0.0)
+    end
+
+    it 'returns average for active crossings' do
+      engine.begin_crossing(origin: :analytical, destination: :creative, ambiguity: 0.4)
+      engine.begin_crossing(origin: :focused, destination: :diffuse, ambiguity: 0.6)
+      expect(engine.average_ambiguity).to eq(0.5)
+    end
+  end
+
+  describe '#average_creative_potential' do
+    it 'returns 0.0 with no active crossings' do
+      expect(engine.average_creative_potential).to eq(0.0)
+    end
+  end
+
+  describe '#liminal_density' do
+    it 'returns 0.0 with no crossings' do
+      expect(engine.liminal_density).to eq(0.0)
+    end
+  end
+
+  describe '#most_liminal' do
+    it 'returns sorted by ambiguity descending' do
+      engine.begin_crossing(origin: :analytical, destination: :creative, ambiguity: 0.3)
+      high = engine.begin_crossing(origin: :focused, destination: :diffuse, ambiguity: 0.8)
+      expect(engine.most_liminal(limit: 1).first.id).to eq(high.id)
+    end
+  end
+
+  describe '#liminal_report' do
+    it 'includes all report fields' do
+      report = engine.liminal_report
+      expect(report).to include(
+        :total_crossings, :active_count, :liminal_count, :completed_count,
+        :fertile_count, :peak_count, :average_ambiguity, :average_potential,
+        :liminal_density, :most_liminal
+      )
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes summary fields' do
+      hash = engine.to_h
+      expect(hash).to include(:total_crossings, :active, :liminal, :avg_ambiguity, :avg_potential)
+    end
+  end
+end

data/spec/legion/extensions/agentic/imagination/liminal/helpers/threshold_crossing_spec.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Imagination::Liminal::Helpers::ThresholdCrossing do
+  subject(:crossing) { described_class.new(origin: :analytical, destination: :creative) }
+
+  describe '#initialize' do
+    it 'assigns a UUID id' do
+      expect(crossing.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores origin' do
+      expect(crossing.origin).to eq(:analytical)
+    end
+
+    it 'stores destination' do
+      expect(crossing.destination).to eq(:creative)
+    end
+
+    it 'defaults to separation phase' do
+      expect(crossing.phase).to eq(:separation)
+    end
+
+    it 'defaults ambiguity' do
+      expect(crossing.ambiguity).to eq(0.5)
+    end
+
+    it 'starts with active status' do
+      expect(crossing.status).to eq(:active)
+    end
+
+    it 'starts with 0 ticks' do
+      expect(crossing.ticks_in_liminal).to eq(0)
+    end
+
+    it 'validates origin state' do
+      bad = described_class.new(origin: :nonexistent, destination: :creative)
+      expect(bad.origin).to eq(:analytical)
+    end
+  end
+
+  describe '#advance!' do
+    it 'increments ticks' do
+      crossing.advance!
+      expect(crossing.ticks_in_liminal).to eq(1)
+    end
+
+    it 'increases progress' do
+      original = crossing.progress
+      crossing.advance!
+      expect(crossing.progress).to be > original
+    end
+
+    it 'transitions to margin phase' do
+      5.times { crossing.advance! }
+      expect(crossing.phase).to eq(:margin)
+    end
+
+    it 'eventually completes' do
+      20.times { crossing.advance! }
+      expect(crossing.incorporated?).to be true
+    end
+
+    it 'does not advance completed crossings' do
+      20.times { crossing.advance! }
+      ticks = crossing.ticks_in_liminal
+      crossing.advance!
+      expect(crossing.ticks_in_liminal).to eq(ticks)
+    end
+  end
+
+  describe '#dissolve!' do
+    it 'increases ambiguity' do
+      original = crossing.ambiguity
+      crossing.dissolve!
+      expect(crossing.ambiguity).to be > original
+    end
+
+    it 'sets quality to dissolving' do
+      crossing.dissolve!
+      expect(crossing.quality).to eq(:dissolving)
+    end
+  end
+
+  describe '#crystallize!' do
+    it 'decreases ambiguity' do
+      original = crossing.ambiguity
+      crossing.crystallize!
+      expect(crossing.ambiguity).to be < original
+    end
+
+    it 'increases progress' do
+      original = crossing.progress
+      crossing.crystallize!
+      expect(crossing.progress).to be > original
+    end
+
+    it 'sets quality to crystallizing' do
+      crossing.crystallize!
+      expect(crossing.quality).to eq(:crystallizing)
+    end
+  end
+
+  describe '#complete!' do
+    it 'sets status to completed' do
+      crossing.complete!
+      expect(crossing.status).to eq(:completed)
+    end
+
+    it 'sets progress to 1.0' do
+      crossing.complete!
+      expect(crossing.progress).to eq(1.0)
+    end
+
+    it 'clears ambiguity' do
+      crossing.complete!
+      expect(crossing.ambiguity).to eq(0.0)
+    end
+  end
+
+  describe '#liminal?' do
+    it 'is false in separation' do
+      expect(crossing.liminal?).to be false
+    end
+
+    it 'is true in margin phase' do
+      5.times { crossing.advance! }
+      expect(crossing.liminal?).to be true
+    end
+  end
+
+  describe '#peak_liminality?' do
+    it 'is true when ambiguity is high' do
+      5.times { crossing.dissolve! }
+      expect(crossing.peak_liminality?).to be true
+    end
+  end
+
+  describe '#fertile?' do
+    it 'detects creative potential peak' do
+      expect(crossing.fertile?).to be true
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all fields' do
+      hash = crossing.to_h
+      expect(hash).to include(
+        :id, :origin, :destination, :domain, :phase, :ambiguity,
+        :creative_potential, :progress, :quality, :status,
+        :ticks_in_liminal, :liminal, :peak_liminality, :fertile,
+        :ambiguity_label, :potential_label, :progress_label, :created_at
+      )
+    end
+  end
+end

data/spec/legion/extensions/agentic/imagination/liminal/runners_spec.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Imagination::Liminal::Runners::CognitiveLiminal do
+  let(:engine) { Legion::Extensions::Agentic::Imagination::Liminal::Helpers::LiminalEngine.new }
+  let(:runner) do
+    obj = Object.new
+    obj.extend(described_class)
+    obj.instance_variable_set(:@default_engine, engine)
+    obj
+  end
+
+  describe '#begin_crossing' do
+    it 'returns success with crossing hash' do
+      result = runner.begin_crossing(origin: :analytical, destination: :creative, engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:crossing][:origin]).to eq(:analytical)
+    end
+  end
+
+  describe '#advance_crossing' do
+    it 'returns success for known crossing' do
+      crossing = engine.begin_crossing(origin: :analytical, destination: :creative)
+      result = runner.advance_crossing(crossing_id: crossing.id, engine: engine)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns failure for unknown crossing' do
+      result = runner.advance_crossing(crossing_id: 'bad', engine: engine)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#dissolve_crossing' do
+    it 'returns success for known crossing' do
+      crossing = engine.begin_crossing(origin: :analytical, destination: :creative)
+      result = runner.dissolve_crossing(crossing_id: crossing.id, engine: engine)
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#crystallize_crossing' do
+    it 'returns success for known crossing' do
+      crossing = engine.begin_crossing(origin: :analytical, destination: :creative)
+      result = runner.crystallize_crossing(crossing_id: crossing.id, engine: engine)
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#active_crossings' do
+    it 'returns active list' do
+      engine.begin_crossing(origin: :analytical, destination: :creative)
+      result = runner.active_crossings(engine: engine)
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#liminal_crossings' do
+    it 'returns liminal list' do
+      crossing = engine.begin_crossing(origin: :analytical, destination: :creative)
+      5.times { crossing.advance! }
+      result = runner.liminal_crossings(engine: engine)
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#fertile_crossings' do
+    it 'returns fertile list' do
+      engine.begin_crossing(origin: :analytical, destination: :creative)
+      result = runner.fertile_crossings(engine: engine)
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#liminal_status' do
+    it 'returns comprehensive status' do
+      result = runner.liminal_status(engine: engine)
+      expect(result[:success]).to be true
+      expect(result).to include(:total_crossings, :liminal_density)
+    end
+  end
+end

data/spec/legion/extensions/agentic/imagination/lucidity/client_spec.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Imagination::Lucidity::Client do
+  subject(:client) { described_class.new }
+
+  describe '#initialize' do
+    it 'creates a LucidityEngine by default' do
+      expect(client.send(:default_engine)).to be_a(
+        Legion::Extensions::Agentic::Imagination::Lucidity::Helpers::LucidityEngine
+      )
+    end
+
+    it 'accepts an injected engine' do
+      custom = Legion::Extensions::Agentic::Imagination::Lucidity::Helpers::LucidityEngine.new
+      c      = described_class.new(engine: custom)
+      expect(c.send(:default_engine)).to be(custom)
+    end
+  end
+
+  describe 'runner inclusion' do
+    it 'responds to begin_dream' do
+      expect(client).to respond_to(:begin_dream)
+    end
+
+    it 'responds to reality_test' do
+      expect(client).to respond_to(:reality_test)
+    end
+
+    it 'responds to steer_dream' do
+      expect(client).to respond_to(:steer_dream)
+    end
+
+    it 'responds to end_dream' do
+      expect(client).to respond_to(:end_dream)
+    end
+
+    it 'responds to lucidity_status' do
+      expect(client).to respond_to(:lucidity_status)
+    end
+
+    it 'responds to journal_entries' do
+      expect(client).to respond_to(:journal_entries)
+    end
+  end
+
+  describe 'full workflow' do
+    it 'begins a dream, runs a reality test, steers it, and ends it' do
+      begin_result  = client.begin_dream(theme: :underwater, content: 'coral reef')
+      dream_id      = begin_result[:dream_id]
+
+      expect(begin_result[:success]).to be true
+
+      status = client.lucidity_status
+      expect(status[:active_dream]).not_to be_nil
+
+      engine = client.send(:default_engine)
+      state  = engine.all_dreams.find { |d| d.id == dream_id }
+
+      # Force enough lucidity to steer
+      10.times do
+        allow(state).to receive(:rand).and_return(0.5)
+        state.reality_test!(:hand_check)
+      end
+
+      steer_result = client.steer_dream(dream_id: dream_id, direction: :transform_into_forest)
+      expect(steer_result[:success]).to be true
+
+      end_result = client.end_dream(dream_id: dream_id, insights: ['became aware in dream'])
+      expect(end_result[:success]).to be true
+
+      journal = client.journal_entries
+      expect(journal[:count]).to eq(1)
+      expect(journal[:entries].first[:insights]).to include('became aware in dream')
+    end
+  end
+end

data/spec/legion/extensions/agentic/imagination/lucidity/cognitive_lucidity_spec.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Imagination::Lucidity do
+  it 'has a VERSION constant' do
+    expect(described_class::VERSION).to match(/\d+\.\d+\.\d+/)
+  end
+
+  it 'loads the helpers namespace' do
+    expect(defined?(Legion::Extensions::Agentic::Imagination::Lucidity::Helpers)).to be_truthy
+  end
+
+  it 'loads the runners namespace' do
+    expect(defined?(Legion::Extensions::Agentic::Imagination::Lucidity::Runners)).to be_truthy
+  end
+
+  it 'loads the Client class' do
+    expect(defined?(Legion::Extensions::Agentic::Imagination::Lucidity::Client)).to be_truthy
+  end
+end

data/spec/legion/extensions/agentic/imagination/lucidity/helpers/constants_spec.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Imagination::Lucidity::Helpers::Constants do
+  describe 'MAX_JOURNAL_ENTRIES' do
+    it 'is 500' do
+      expect(described_class::MAX_JOURNAL_ENTRIES).to eq(500)
+    end
+  end
+
+  describe 'MAX_DREAMS' do
+    it 'is 100' do
+      expect(described_class::MAX_DREAMS).to eq(100)
+    end
+  end
+
+  describe 'LUCIDITY_LEVELS' do
+    it 'contains five levels in order' do
+      expect(described_class::LUCIDITY_LEVELS).to eq(%i[non_lucid pre_lucid semi_lucid lucid fully_lucid])
+    end
+
+    it 'is frozen' do
+      expect(described_class::LUCIDITY_LEVELS).to be_frozen
+    end
+  end
+
+  describe 'REALITY_TEST_TYPES' do
+    it 'contains the expected test types' do
+      expect(described_class::REALITY_TEST_TYPES).to include(
+        :text_stability, :hand_check, :time_check, :memory_check, :logic_check
+      )
+    end
+
+    it 'is frozen' do
+      expect(described_class::REALITY_TEST_TYPES).to be_frozen
+    end
+  end
+
+  describe 'LUCIDITY_DECAY' do
+    it 'is 0.05' do
+      expect(described_class::LUCIDITY_DECAY).to eq(0.05)
+    end
+  end
+
+  describe 'FALSE_AWAKENING_CHANCE' do
+    it 'is 0.1' do
+      expect(described_class::FALSE_AWAKENING_CHANCE).to eq(0.1)
+    end
+  end
+
+  describe 'DREAM_QUALITY_LABELS' do
+    it 'maps ranges to quality labels' do
+      expect(described_class::DREAM_QUALITY_LABELS.values).to include(:poor, :ordinary, :vivid, :hyper_vivid)
+    end
+
+    it 'is frozen' do
+      expect(described_class::DREAM_QUALITY_LABELS).to be_frozen
+    end
+  end
+
+  describe '.label_for' do
+    it 'returns :poor for value 0.1' do
+      expect(described_class.label_for(0.1)).to eq(:poor)
+    end
+
+    it 'returns :fragmented for value 0.3' do
+      expect(described_class.label_for(0.3)).to eq(:fragmented)
+    end
+
+    it 'returns :ordinary for value 0.5' do
+      expect(described_class.label_for(0.5)).to eq(:ordinary)
+    end
+
+    it 'returns :vivid for value 0.7' do
+      expect(described_class.label_for(0.7)).to eq(:vivid)
+    end
+
+    it 'returns :hyper_vivid for value 0.9' do
+      expect(described_class.label_for(0.9)).to eq(:hyper_vivid)
+    end
+
+    it 'clamps values above 1.0' do
+      expect(described_class.label_for(1.5)).to eq(:hyper_vivid)
+    end
+
+    it 'clamps values below 0.0' do
+      expect(described_class.label_for(-0.5)).to eq(:poor)
+    end
+  end
+end