lex-agentic-defense 0.1.0

data/spec/legion/extensions/agentic/defense/whirlpool/helpers/captured_thought_spec.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Defense::Whirlpool::Helpers::CapturedThought do
+  let(:thought) { described_class.new(content: 'test thought', domain: :analytical) }
+
+  describe '#initialize' do
+    it 'generates a UUID thought_id' do
+      expect(thought.thought_id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores content and domain' do
+      expect(thought.content).to eq('test thought')
+      expect(thought.domain).to eq(:analytical)
+    end
+
+    it 'defaults spiral_depth to 0.0' do
+      expect(thought.spiral_depth).to eq(0.0)
+    end
+
+    it 'defaults distance_from_core to 1.0' do
+      expect(thought.distance_from_core).to eq(1.0)
+    end
+
+    it 'sets captured_at to a UTC time' do
+      expect(thought.captured_at).to be_a(Time)
+    end
+
+    it 'clamps spiral_depth above maximum' do
+      t = described_class.new(content: 'x', spiral_depth: 5.0)
+      expect(t.spiral_depth).to eq(1.0)
+    end
+
+    it 'clamps spiral_depth below zero' do
+      t = described_class.new(content: 'x', spiral_depth: -1.0)
+      expect(t.spiral_depth).to eq(0.0)
+    end
+
+    it 'clamps distance_from_core above maximum' do
+      t = described_class.new(content: 'x', distance_from_core: 3.0)
+      expect(t.distance_from_core).to eq(1.0)
+    end
+
+    it 'clamps distance_from_core below zero' do
+      t = described_class.new(content: 'x', distance_from_core: -1.0)
+      expect(t.distance_from_core).to eq(0.0)
+    end
+
+    it 'defaults domain to :general' do
+      t = described_class.new(content: 'x')
+      expect(t.domain).to eq(:general)
+    end
+  end
+
+  describe '#spiral!' do
+    it 'increases spiral_depth' do
+      before = thought.spiral_depth
+      thought.spiral!
+      expect(thought.spiral_depth).to be > before
+    end
+
+    it 'decreases distance_from_core' do
+      before = thought.distance_from_core
+      thought.spiral!
+      expect(thought.distance_from_core).to be < before
+    end
+
+    it 'accepts custom rate' do
+      thought.spiral!(rate: 0.2)
+      expect(thought.spiral_depth).to be_within(0.001).of(0.2)
+    end
+
+    it 'does not exceed DEPTH_MAX' do
+      20.times { thought.spiral!(rate: 0.3) }
+      expect(thought.spiral_depth).to eq(1.0)
+    end
+
+    it 'does not go below 0.0 for distance_from_core' do
+      20.times { thought.spiral!(rate: 0.3) }
+      expect(thought.distance_from_core).to eq(0.0)
+    end
+
+    it 'does nothing if thought has escaped' do
+      thought.escape!
+      depth_before    = thought.spiral_depth
+      distance_before = thought.distance_from_core
+      thought.spiral!
+      expect(thought.spiral_depth).to eq(depth_before)
+      expect(thought.distance_from_core).to eq(distance_before)
+    end
+  end
+
+  describe '#at_core?' do
+    it 'returns false when distance_from_core is large' do
+      expect(thought.at_core?).to be false
+    end
+
+    it 'returns true when distance_from_core is near zero' do
+      t = described_class.new(content: 'x', distance_from_core: 0.02)
+      expect(t.at_core?).to be true
+    end
+
+    it 'returns true after spiraling all the way in' do
+      20.times { thought.spiral!(rate: 0.4) }
+      expect(thought.at_core?).to be true
+    end
+  end
+
+  describe '#escaped?' do
+    it 'returns false initially' do
+      expect(thought.escaped?).to be false
+    end
+
+    it 'returns true after escape!' do
+      thought.escape!
+      expect(thought.escaped?).to be true
+    end
+  end
+
+  describe '#depth_label' do
+    it 'returns :surface for depth 0.0' do
+      t = described_class.new(content: 'x', spiral_depth: 0.0)
+      expect(t.depth_label).to eq(:surface)
+    end
+
+    it 'returns :insight_core for depth near 1.0' do
+      t = described_class.new(content: 'x', spiral_depth: 0.95)
+      expect(t.depth_label).to eq(:insight_core)
+    end
+
+    it 'returns :deep for depth 0.7' do
+      t = described_class.new(content: 'x', spiral_depth: 0.7)
+      expect(t.depth_label).to eq(:deep)
+    end
+
+    it 'returns :mid for depth 0.5' do
+      t = described_class.new(content: 'x', spiral_depth: 0.5)
+      expect(t.depth_label).to eq(:mid)
+    end
+
+    it 'returns :shallow for depth 0.3' do
+      t = described_class.new(content: 'x', spiral_depth: 0.3)
+      expect(t.depth_label).to eq(:shallow)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with all fields' do
+      h = thought.to_h
+      expect(h).to have_key(:thought_id)
+      expect(h).to have_key(:content)
+      expect(h).to have_key(:domain)
+      expect(h).to have_key(:spiral_depth)
+      expect(h).to have_key(:distance_from_core)
+      expect(h).to have_key(:depth_label)
+      expect(h).to have_key(:at_core)
+      expect(h).to have_key(:escaped)
+      expect(h).to have_key(:captured_at)
+    end
+
+    it 'rounds spiral_depth to 10 decimal places' do
+      thought.spiral!(rate: 0.1)
+      h = thought.to_h
+      expect(h[:spiral_depth]).to be_a(Float)
+    end
+
+    it 'reflects escaped state' do
+      thought.escape!
+      expect(thought.to_h[:escaped]).to be true
+    end
+  end
+end

data/spec/legion/extensions/agentic/defense/whirlpool/helpers/constants_spec.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Defense::Whirlpool::Helpers::Constants do
+  describe 'VORTEX_TYPES' do
+    it 'is a frozen array of symbols' do
+      expect(described_class::VORTEX_TYPES).to be_a(Array)
+      expect(described_class::VORTEX_TYPES).to be_frozen
+      expect(described_class::VORTEX_TYPES).to all(be_a(Symbol))
+    end
+
+    it 'includes the five cognitive vortex types' do
+      expect(described_class::VORTEX_TYPES).to include(:analytical, :creative, :emotional, :procedural, :associative)
+    end
+  end
+
+  describe 'MAX_VORTICES' do
+    it 'is a positive integer' do
+      expect(described_class::MAX_VORTICES).to be_a(Integer)
+      expect(described_class::MAX_VORTICES).to be > 0
+    end
+  end
+
+  describe 'VELOCITY_DECAY' do
+    it 'is a positive float less than 1' do
+      expect(described_class::VELOCITY_DECAY).to be_a(Float)
+      expect(described_class::VELOCITY_DECAY).to be > 0
+      expect(described_class::VELOCITY_DECAY).to be < 1
+    end
+  end
+
+  describe 'DEPTH_LABELS' do
+    it 'is a frozen array' do
+      expect(described_class::DEPTH_LABELS).to be_a(Array)
+    end
+
+    it 'each entry has a range and label' do
+      described_class::DEPTH_LABELS.each do |entry|
+        expect(entry).to have_key(:range)
+        expect(entry).to have_key(:label)
+        expect(entry[:range]).to be_a(Range)
+        expect(entry[:label]).to be_a(Symbol)
+      end
+    end
+
+    it 'includes insight_core label' do
+      labels = described_class::DEPTH_LABELS.map { |e| e[:label] }
+      expect(labels).to include(:insight_core)
+    end
+
+    it 'covers 0.0 to 1.0' do
+      min = described_class::DEPTH_LABELS.map { |e| e[:range].min }.min
+      expect(min).to eq(0.0)
+    end
+  end
+
+  describe 'thresholds' do
+    it 'POWERFUL_VELOCITY > CALM_VELOCITY' do
+      expect(described_class::POWERFUL_VELOCITY).to be > described_class::CALM_VELOCITY
+    end
+
+    it 'DISSIPATION_THRESHOLD < ANGULAR_VELOCITY_MIN' do
+      expect(described_class::DISSIPATION_THRESHOLD).to be < described_class::ANGULAR_VELOCITY_MIN
+    end
+  end
+end

data/spec/legion/extensions/agentic/defense/whirlpool/helpers/vortex_spec.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Defense::Whirlpool::Helpers::Vortex do
+  let(:vortex) { described_class.new(vortex_type: :analytical, angular_velocity: 0.5, depth: 0.0, capture_radius: 0.5) }
+
+  let(:thought) do
+    Legion::Extensions::Agentic::Defense::Whirlpool::Helpers::CapturedThought.new(
+      content: 'test thought', domain: :analytical
+    )
+  end
+
+  describe '#initialize' do
+    it 'generates a vortex_id' do
+      expect(vortex.vortex_id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores vortex_type' do
+      expect(vortex.vortex_type).to eq(:analytical)
+    end
+
+    it 'clamps angular_velocity within bounds' do
+      v = described_class.new(vortex_type: :creative, angular_velocity: 5.0)
+      expect(v.angular_velocity).to eq(1.0)
+    end
+
+    it 'clamps depth within bounds' do
+      v = described_class.new(vortex_type: :creative, depth: -1.0)
+      expect(v.depth).to eq(0.0)
+    end
+
+    it 'raises ArgumentError for unknown vortex_type' do
+      expect { described_class.new(vortex_type: :unknown) }.to raise_error(ArgumentError)
+    end
+
+    it 'starts with empty captured_thoughts' do
+      expect(vortex.captured_thoughts).to be_empty
+    end
+
+    it 'sets created_at' do
+      expect(vortex.created_at).to be_a(Time)
+    end
+  end
+
+  describe '#capture!' do
+    it 'adds thought to captured_thoughts' do
+      vortex.capture!(thought)
+      expect(vortex.captured_thoughts.size).to eq(1)
+    end
+
+    it 'returns the thought' do
+      result = vortex.capture!(thought)
+      expect(result).to eq(thought)
+    end
+
+    it 'raises ArgumentError for non-CapturedThought' do
+      expect { vortex.capture!('not a thought') }.to raise_error(ArgumentError)
+    end
+  end
+
+  describe '#tick!' do
+    before { vortex.capture!(thought) }
+
+    it 'spirals all captured thoughts deeper' do
+      depth_before = thought.spiral_depth
+      vortex.tick!
+      expect(thought.spiral_depth).to be > depth_before
+    end
+
+    it 'increases the vortex depth' do
+      depth_before = vortex.depth
+      vortex.tick!
+      expect(vortex.depth).to be > depth_before
+    end
+
+    it 'returns self' do
+      expect(vortex.tick!).to eq(vortex)
+    end
+
+    it 'accepts custom spiral_rate' do
+      vortex.tick!(spiral_rate: 0.3)
+      expect(thought.spiral_depth).to be_within(0.001).of(0.3)
+    end
+  end
+
+  describe '#dissipate!' do
+    it 'reduces angular_velocity' do
+      before = vortex.angular_velocity
+      vortex.dissipate!
+      expect(vortex.angular_velocity).to be < before
+    end
+
+    it 'reduces capture_radius' do
+      before = vortex.capture_radius
+      vortex.dissipate!
+      expect(vortex.capture_radius).to be < before
+    end
+
+    it 'returns self' do
+      expect(vortex.dissipate!).to eq(vortex)
+    end
+
+    it 'accepts custom rate' do
+      vortex.dissipate!(rate: 0.4)
+      expect(vortex.angular_velocity).to be < 0.5
+    end
+  end
+
+  describe '#powerful?' do
+    it 'returns true when angular_velocity is above POWERFUL_VELOCITY' do
+      v = described_class.new(vortex_type: :creative, angular_velocity: 0.9)
+      expect(v.powerful?).to be true
+    end
+
+    it 'returns false when angular_velocity is below POWERFUL_VELOCITY' do
+      v = described_class.new(vortex_type: :creative, angular_velocity: 0.4)
+      expect(v.powerful?).to be false
+    end
+  end
+
+  describe '#calm?' do
+    it 'returns true when angular_velocity is at or below CALM_VELOCITY' do
+      v = described_class.new(vortex_type: :creative, angular_velocity: 0.1)
+      expect(v.calm?).to be true
+    end
+
+    it 'returns false when angular_velocity is above CALM_VELOCITY' do
+      expect(vortex.calm?).to be false
+    end
+  end
+
+  describe '#dissipated?' do
+    it 'returns false for a fresh vortex' do
+      expect(vortex.dissipated?).to be false
+    end
+
+    it 'returns true after many dissipation cycles' do
+      50.times { vortex.dissipate!(rate: 0.2) }
+      expect(vortex.dissipated?).to be true
+    end
+  end
+
+  describe '#thoughts_at_core' do
+    it 'returns only thoughts at core distance' do
+      core_thought = Legion::Extensions::Agentic::Defense::Whirlpool::Helpers::CapturedThought.new(
+        content: 'core', distance_from_core: 0.02
+      )
+      vortex.capture!(thought)
+      vortex.capture!(core_thought)
+      expect(vortex.thoughts_at_core.size).to eq(1)
+      expect(vortex.thoughts_at_core.first).to eq(core_thought)
+    end
+  end
+
+  describe '#active_thoughts' do
+    it 'excludes escaped thoughts' do
+      vortex.capture!(thought)
+      escaped = Legion::Extensions::Agentic::Defense::Whirlpool::Helpers::CapturedThought.new(content: 'escaped')
+      escaped.escape!
+      vortex.capture!(escaped)
+      expect(vortex.active_thoughts.size).to eq(1)
+    end
+  end
+
+  describe '#depth_label' do
+    it 'returns :surface for a new vortex' do
+      expect(vortex.depth_label).to eq(:surface)
+    end
+
+    it 'returns :insight_core after deep tick cycles' do
+      50.times { vortex.tick!(spiral_rate: 0.1) }
+      expect(vortex.depth_label).to eq(:insight_core)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with all expected keys' do
+      h = vortex.to_h
+      %i[vortex_id vortex_type angular_velocity depth capture_radius
+         depth_label powerful calm dissipated thought_count core_count created_at].each do |key|
+        expect(h).to have_key(key)
+      end
+    end
+
+    it 'reflects current powerful state' do
+      v = described_class.new(vortex_type: :analytical, angular_velocity: 0.9)
+      expect(v.to_h[:powerful]).to be true
+    end
+  end
+end

data/spec/legion/extensions/agentic/defense/whirlpool/helpers/whirlpool_engine_spec.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Defense::Whirlpool::Helpers::WhirlpoolEngine do
+  let(:engine) { described_class.new }
+
+  describe '#create_vortex' do
+    it 'creates a vortex and adds it to the engine' do
+      vortex = engine.create_vortex(vortex_type: :analytical)
+      expect(engine.vortices.size).to eq(1)
+      expect(vortex).to be_a(Legion::Extensions::Agentic::Defense::Whirlpool::Helpers::Vortex)
+    end
+
+    it 'respects vortex_type' do
+      vortex = engine.create_vortex(vortex_type: :creative)
+      expect(vortex.vortex_type).to eq(:creative)
+    end
+
+    it 'passes angular_velocity' do
+      vortex = engine.create_vortex(vortex_type: :analytical, angular_velocity: 0.8)
+      expect(vortex.angular_velocity).to eq(0.8)
+    end
+
+    it 'passes depth' do
+      vortex = engine.create_vortex(vortex_type: :analytical, depth: 0.3)
+      expect(vortex.depth).to eq(0.3)
+    end
+
+    it 'passes capture_radius' do
+      vortex = engine.create_vortex(vortex_type: :analytical, capture_radius: 0.7)
+      expect(vortex.capture_radius).to eq(0.7)
+    end
+
+    it 'raises ArgumentError at MAX_VORTICES' do
+      max = Legion::Extensions::Agentic::Defense::Whirlpool::Helpers::Constants::MAX_VORTICES
+      max.times { engine.create_vortex(vortex_type: :analytical) }
+      expect { engine.create_vortex(vortex_type: :creative) }.to raise_error(ArgumentError)
+    end
+
+    it 'raises ArgumentError for unknown vortex_type' do
+      expect { engine.create_vortex(vortex_type: :unknown) }.to raise_error(ArgumentError)
+    end
+  end
+
+  describe '#inject_thought' do
+    let(:vortex) { engine.create_vortex(vortex_type: :emotional) }
+
+    it 'adds a thought to the specified vortex' do
+      engine.inject_thought(vortex_id: vortex.vortex_id, content: 'hello')
+      expect(vortex.captured_thoughts.size).to eq(1)
+    end
+
+    it 'returns vortex_id and thought_id' do
+      result = engine.inject_thought(vortex_id: vortex.vortex_id, content: 'hello')
+      expect(result[:vortex_id]).to eq(vortex.vortex_id)
+      expect(result[:thought_id]).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'accepts domain and distance_from_core' do
+      engine.inject_thought(vortex_id: vortex.vortex_id, content: 'thought', domain: :emotional, distance_from_core: 0.5)
+      thought = vortex.captured_thoughts.first
+      expect(thought.domain).to eq(:emotional)
+      expect(thought.distance_from_core).to eq(0.5)
+    end
+
+    it 'raises ArgumentError for unknown vortex_id' do
+      expect { engine.inject_thought(vortex_id: 'nonexistent', content: 'x') }.to raise_error(ArgumentError)
+    end
+  end
+
+  describe '#tick_all!' do
+    before do
+      v = engine.create_vortex(vortex_type: :analytical)
+      engine.inject_thought(vortex_id: v.vortex_id, content: 'thought 1')
+    end
+
+    it 'returns ticked count' do
+      result = engine.tick_all!
+      expect(result[:ticked]).to eq(1)
+    end
+
+    it 'includes results per vortex' do
+      result = engine.tick_all!
+      expect(result[:results]).to be_an(Array)
+      expect(result[:results].first).to have_key(:vortex_id)
+    end
+
+    it 'spirals thoughts deeper' do
+      vortex = engine.vortices.first
+      depth_before = vortex.captured_thoughts.first.spiral_depth
+      engine.tick_all!
+      expect(vortex.captured_thoughts.first.spiral_depth).to be > depth_before
+    end
+
+    it 'accepts custom spiral_rate' do
+      vortex = engine.vortices.first
+      engine.tick_all!(spiral_rate: 0.3)
+      expect(vortex.captured_thoughts.first.spiral_depth).to be_within(0.001).of(0.3)
+    end
+  end
+
+  describe '#dissipate_all!' do
+    before do
+      engine.create_vortex(vortex_type: :analytical)
+      engine.create_vortex(vortex_type: :creative)
+    end
+
+    it 'reduces angular_velocity of all vortices' do
+      before_velocities = engine.vortices.map(&:angular_velocity)
+      engine.dissipate_all!
+      after_velocities = engine.vortices.map(&:angular_velocity)
+      expect(after_velocities.zip(before_velocities).all? { |a, b| a <= b }).to be true
+    end
+
+    it 'removes fully dissipated vortices' do
+      v = engine.create_vortex(vortex_type: :emotional, angular_velocity: 0.1)
+      50.times { engine.dissipate_all!(rate: 0.3) }
+      expect(engine.find_vortex(v.vortex_id)).to be_nil
+    end
+
+    it 'returns dissipated and remaining counts' do
+      result = engine.dissipate_all!
+      expect(result).to have_key(:dissipated)
+      expect(result).to have_key(:remaining)
+    end
+  end
+
+  describe '#deepest_vortices' do
+    before do
+      engine.create_vortex(vortex_type: :analytical, depth: 0.9)
+      engine.create_vortex(vortex_type: :creative, depth: 0.5)
+      engine.create_vortex(vortex_type: :emotional, depth: 0.2)
+    end
+
+    it 'returns vortices sorted by depth descending' do
+      result = engine.deepest_vortices(limit: 3)
+      depths = result.map { |v| v[:depth] }
+      expect(depths).to eq(depths.sort.reverse)
+    end
+
+    it 'respects limit' do
+      result = engine.deepest_vortices(limit: 2)
+      expect(result.size).to eq(2)
+    end
+
+    it 'returns hashes' do
+      result = engine.deepest_vortices
+      expect(result).to all(be_a(Hash))
+    end
+  end
+
+  describe '#vortex_report' do
+    before do
+      v1 = engine.create_vortex(vortex_type: :analytical, angular_velocity: 0.9)
+      v2 = engine.create_vortex(vortex_type: :creative, angular_velocity: 0.1)
+      engine.inject_thought(vortex_id: v1.vortex_id, content: 'thought A')
+      engine.inject_thought(vortex_id: v2.vortex_id, content: 'thought B')
+    end
+
+    it 'returns total_vortices' do
+      expect(engine.vortex_report[:total_vortices]).to eq(2)
+    end
+
+    it 'returns powerful_count' do
+      expect(engine.vortex_report[:powerful_count]).to eq(1)
+    end
+
+    it 'returns calm_count' do
+      expect(engine.vortex_report[:calm_count]).to eq(1)
+    end
+
+    it 'returns total_thoughts' do
+      expect(engine.vortex_report[:total_thoughts]).to eq(2)
+    end
+
+    it 'returns core_thoughts count' do
+      expect(engine.vortex_report[:core_thoughts]).to be_a(Integer)
+    end
+
+    it 'returns deepest_vortices array' do
+      expect(engine.vortex_report[:deepest_vortices]).to be_an(Array)
+    end
+  end
+
+  describe '#find_vortex' do
+    it 'returns the matching vortex' do
+      vortex = engine.create_vortex(vortex_type: :analytical)
+      expect(engine.find_vortex(vortex.vortex_id)).to eq(vortex)
+    end
+
+    it 'returns nil for unknown id' do
+      expect(engine.find_vortex('nonexistent')).to be_nil
+    end
+  end
+
+  describe '#remove_vortex' do
+    it 'removes vortex by id' do
+      vortex = engine.create_vortex(vortex_type: :analytical)
+      engine.remove_vortex(vortex.vortex_id)
+      expect(engine.find_vortex(vortex.vortex_id)).to be_nil
+    end
+
+    it 'returns removed count' do
+      vortex = engine.create_vortex(vortex_type: :analytical)
+      result = engine.remove_vortex(vortex.vortex_id)
+      expect(result[:removed]).to eq(1)
+    end
+
+    it 'returns 0 for unknown id' do
+      result = engine.remove_vortex('nonexistent')
+      expect(result[:removed]).to eq(0)
+    end
+  end
+
+  describe '#clear' do
+    it 'removes all vortices' do
+      engine.create_vortex(vortex_type: :analytical)
+      engine.create_vortex(vortex_type: :creative)
+      engine.clear
+      expect(engine.vortices).to be_empty
+    end
+
+    it 'returns cleared: true' do
+      result = engine.clear
+      expect(result[:cleared]).to be true
+    end
+  end
+end