lex-agentic-defense 0.1.0

data/spec/legion/extensions/agentic/defense/phantom/runners/cognitive_phantom_spec.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/defense/phantom/client'
+
+RSpec.describe Legion::Extensions::Agentic::Defense::Phantom::Runners::CognitivePhantom do
+  let(:client) { Legion::Extensions::Agentic::Defense::Phantom::Client.new }
+
+  describe '#register_removal' do
+    it 'returns success: true with valid params' do
+      result = client.register_removal(capability_name: 'lex-http', capability_domain: :network)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns a phantom_id uuid' do
+      result = client.register_removal(capability_name: 'lex-http')
+      expect(result[:phantom_id]).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'returns capability_name in result' do
+      result = client.register_removal(capability_name: 'lex-redis')
+      expect(result[:capability_name]).to eq('lex-redis')
+    end
+
+    it 'returns state in result' do
+      result = client.register_removal(capability_name: 'lex-vault')
+      expect(Legion::Extensions::Agentic::Defense::Phantom::Helpers::Constants::PHANTOM_STATES).to include(result[:state])
+    end
+
+    it 'returns intensity in result' do
+      result = client.register_removal(capability_name: 'lex-consul')
+      expect(result[:intensity]).to be_a(Float)
+      expect(result[:intensity]).to be_between(0.0, 1.0)
+    end
+
+    it 'returns success: false for empty capability_name' do
+      result = client.register_removal(capability_name: '')
+      expect(result[:success]).to be false
+      expect(result[:error]).to be_a(String)
+    end
+
+    it 'uses injected engine when provided' do
+      eng    = Legion::Extensions::Agentic::Defense::Phantom::Helpers::PhantomEngine.new
+      result = client.register_removal(capability_name: 'lex-ssh', engine: eng)
+      expect(result[:success]).to be true
+      expect(eng.all_phantoms.size).to eq(1)
+    end
+
+    it 'defaults capability_domain to :general' do
+      result = client.register_removal(capability_name: 'lex-smtp')
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#process_stimulus' do
+    before { client.register_removal(capability_name: 'lex-http', capability_domain: :network) }
+
+    it 'returns success: true' do
+      result = client.process_stimulus(stimulus: 'http.get fired')
+      expect(result[:success]).to be true
+    end
+
+    it 'returns fired_count' do
+      result = client.process_stimulus(stimulus: 'event', domain: :any)
+      expect(result[:fired_count]).to be >= 1
+    end
+
+    it 'returns signals array' do
+      result = client.process_stimulus(stimulus: 'event', domain: :any)
+      expect(result[:signals]).to be_an(Array)
+    end
+
+    it 'signals contain expected keys' do
+      result = client.process_stimulus(stimulus: 'event', domain: :any)
+      expect(result[:signals].first).to include(:id, :phantom_limb_id, :trigger_type, :intensity_at_trigger)
+    end
+
+    it 'returns domain in result' do
+      result = client.process_stimulus(stimulus: 'event', domain: :network)
+      expect(result[:domain]).to eq(:network)
+    end
+
+    it 'returns success: false when stimulus is nil' do
+      result = client.process_stimulus(stimulus: nil)
+      expect(result[:success]).to be false
+    end
+
+    it 'uses injected engine' do
+      eng = Legion::Extensions::Agentic::Defense::Phantom::Helpers::PhantomEngine.new
+      eng.register_removal(capability_name: 'injected-cap')
+      result = client.process_stimulus(stimulus: 'event', domain: :any, engine: eng)
+      expect(result[:fired_count]).to eq(1)
+    end
+  end
+
+  describe '#acknowledge_phantom' do
+    let(:phantom_id) do
+      client.register_removal(capability_name: 'lex-github')[:phantom_id]
+    end
+
+    it 'returns success: true for valid phantom_id' do
+      result = client.acknowledge_phantom(phantom_id: phantom_id)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns acknowledged: true for valid phantom_id' do
+      result = client.acknowledge_phantom(phantom_id: phantom_id)
+      expect(result[:acknowledged]).to be true
+    end
+
+    it 'returns success: false for unknown phantom_id' do
+      result = client.acknowledge_phantom(phantom_id: SecureRandom.uuid)
+      expect(result[:success]).to be false
+    end
+
+    it 'returns success: false for empty phantom_id' do
+      result = client.acknowledge_phantom(phantom_id: '')
+      expect(result[:success]).to be false
+      expect(result[:error]).to be_a(String)
+    end
+
+    it 'uses injected engine' do
+      eng  = Legion::Extensions::Agentic::Defense::Phantom::Helpers::PhantomEngine.new
+      limb = eng.register_removal(capability_name: 'injected-cap')
+      result = client.acknowledge_phantom(phantom_id: limb.id, engine: eng)
+      expect(result[:acknowledged]).to be true
+    end
+  end
+
+  describe '#phantom_status' do
+    before do
+      client.register_removal(capability_name: 'lex-http')
+      client.register_removal(capability_name: 'lex-vault')
+    end
+
+    it 'returns success: true' do
+      expect(client.phantom_status[:success]).to be true
+    end
+
+    it 'returns total count' do
+      expect(client.phantom_status[:total]).to eq(2)
+    end
+
+    it 'returns active count' do
+      expect(client.phantom_status[:active]).to be >= 0
+    end
+
+    it 'returns by_state breakdown' do
+      expect(client.phantom_status[:by_state]).to be_a(Hash)
+    end
+
+    it 'returns total_activations' do
+      client.process_stimulus(stimulus: 'event', domain: :any)
+      expect(client.phantom_status[:total_activations]).to be >= 2
+    end
+
+    it 'uses injected engine' do
+      eng = Legion::Extensions::Agentic::Defense::Phantom::Helpers::PhantomEngine.new
+      eng.register_removal(capability_name: 'cap')
+      result = client.phantom_status(engine: eng)
+      expect(result[:total]).to eq(1)
+    end
+  end
+
+  describe '#decay_all' do
+    before { client.register_removal(capability_name: 'lex-redis') }
+
+    it 'returns success: true' do
+      expect(client.decay_all[:success]).to be true
+    end
+
+    it 'returns resolved_this_cycle count' do
+      expect(client.decay_all[:resolved_this_cycle]).to be >= 0
+    end
+
+    it 'includes total in result' do
+      expect(client.decay_all[:total]).to be >= 0
+    end
+
+    it 'decays phantom intensity' do
+      client.phantom_status[:by_state][:acute]
+      client.decay_all
+      after_report = client.phantom_status
+      expect(after_report[:total]).to be >= 0
+    end
+
+    it 'uses injected engine' do
+      eng = Legion::Extensions::Agentic::Defense::Phantom::Helpers::PhantomEngine.new
+      eng.register_removal(capability_name: 'cap')
+      result = client.decay_all(engine: eng)
+      expect(result[:success]).to be true
+    end
+  end
+end

data/spec/legion/extensions/agentic/defense/quicksand/client_spec.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Defense::Quicksand::Client do
+  subject(:client) { described_class.new }
+
+  it 'includes the runner module' do
+    expect(described_class.ancestors).to include(
+      Legion::Extensions::Agentic::Defense::Quicksand::Runners::CognitiveQuicksand
+    )
+  end
+
+  it 'responds to create_trap' do
+    expect(client).to respond_to(:create_trap)
+  end
+
+  it 'responds to struggle' do
+    expect(client).to respond_to(:struggle)
+  end
+
+  it 'responds to attempt_escape' do
+    expect(client).to respond_to(:attempt_escape)
+  end
+
+  it 'responds to quicksand_status' do
+    expect(client).to respond_to(:quicksand_status)
+  end
+
+  it 'can create and struggle through client' do
+    result = client.create_trap(trap_type: :overthinking, domain: :test, content: 'loop')
+    expect(result[:success]).to be true
+    trap_id = result[:trap][:id]
+    struggle_result = client.struggle(trap_id: trap_id)
+    expect(struggle_result[:success]).to be true
+  end
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Defense::Quicksand::Helpers::Constants do
+  described_class = Legion::Extensions::Agentic::Defense::Quicksand::Helpers::Constants
+
+  describe 'TRAP_TYPES' do
+    it 'contains expected types' do
+      expect(described_class::TRAP_TYPES).to eq(%i[overthinking rumination analysis_paralysis
+                                                   perfectionism indecision])
+    end
+
+    it 'is frozen' do
+      expect(described_class::TRAP_TYPES).to be_frozen
+    end
+  end
+
+  describe 'STRUGGLE_MODES' do
+    it 'contains expected modes' do
+      expect(described_class::STRUGGLE_MODES).to eq(%i[thrash freeze sink float escape])
+    end
+  end
+
+  describe 'numeric constants' do
+    it 'defines MAX_TRAPS' do
+      expect(described_class::MAX_TRAPS).to eq(200)
+    end
+
+    it 'defines SINK_RATE' do
+      expect(described_class::SINK_RATE).to eq(0.08)
+    end
+
+    it 'defines STRUGGLE_PENALTY' do
+      expect(described_class::STRUGGLE_PENALTY).to eq(0.12)
+    end
+
+    it 'defines ESCAPE_THRESHOLD' do
+      expect(described_class::ESCAPE_THRESHOLD).to eq(0.3)
+    end
+  end
+
+  describe '.label_for' do
+    it 'returns :submerged for high depth' do
+      expect(described_class.label_for(described_class::DEPTH_LABELS, 0.9)).to eq(:submerged)
+    end
+
+    it 'returns :surface for low depth' do
+      expect(described_class.label_for(described_class::DEPTH_LABELS, 0.1)).to eq(:surface)
+    end
+
+    it 'returns :concrete for high viscosity' do
+      expect(described_class.label_for(described_class::VISCOSITY_LABELS, 0.9)).to eq(:concrete)
+    end
+
+    it 'returns :dry for low viscosity' do
+      expect(described_class.label_for(described_class::VISCOSITY_LABELS, 0.1)).to eq(:dry)
+    end
+  end
+end

data/spec/legion/extensions/agentic/defense/quicksand/helpers/pit_spec.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Defense::Quicksand::Helpers::Pit do
+  subject(:pit) { described_class.new }
+
+  describe '#initialize' do
+    it 'assigns a UUID id' do
+      expect(pit.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'defaults saturation to 0.5' do
+      expect(pit.saturation).to eq(0.5)
+    end
+
+    it 'defaults danger_level to 0.3' do
+      expect(pit.danger_level).to eq(0.3)
+    end
+
+    it 'starts with empty trap_ids' do
+      expect(pit.trap_ids).to be_empty
+    end
+  end
+
+  describe '#add_trap' do
+    it 'adds a trap id' do
+      expect(pit.add_trap('t-1')).to eq(:added)
+      expect(pit.trap_ids).to include('t-1')
+    end
+
+    it 'returns :already_present for duplicates' do
+      pit.add_trap('t-1')
+      expect(pit.add_trap('t-1')).to eq(:already_present)
+    end
+
+    it 'recalculates danger level' do
+      initial = pit.danger_level
+      5.times { |i| pit.add_trap("t-#{i}") }
+      expect(pit.danger_level).not_to eq(initial)
+    end
+  end
+
+  describe '#remove_trap' do
+    it 'removes a trap id' do
+      pit.add_trap('t-1')
+      expect(pit.remove_trap('t-1')).to eq(:removed)
+    end
+
+    it 'returns :not_found for missing' do
+      expect(pit.remove_trap('nope')).to eq(:not_found)
+    end
+  end
+
+  describe '#saturate!' do
+    it 'increases saturation' do
+      initial = pit.saturation
+      pit.saturate!(rate: 0.1)
+      expect(pit.saturation).to eq((initial + 0.1).round(10))
+    end
+  end
+
+  describe '#drain!' do
+    it 'decreases saturation' do
+      initial = pit.saturation
+      pit.drain!(rate: 0.1)
+      expect(pit.saturation).to eq((initial - 0.1).round(10))
+    end
+  end
+
+  describe '#deadly?' do
+    it 'returns false at default' do
+      expect(pit).not_to be_deadly
+    end
+
+    it 'returns true when danger_level >= 0.8' do
+      pit.danger_level = 0.9
+      expect(pit).to be_deadly
+    end
+  end
+
+  describe '#safe?' do
+    it 'returns false at default' do
+      expect(pit).not_to be_safe
+    end
+
+    it 'returns true when danger_level < 0.2' do
+      pit.danger_level = 0.1
+      expect(pit).to be_safe
+    end
+  end
+
+  describe '#trap_count' do
+    it 'returns 0 initially' do
+      expect(pit.trap_count).to eq(0)
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all expected keys' do
+      expected = %i[id saturation danger_level trap_count deadly safe created_at]
+      expect(pit.to_h.keys).to match_array(expected)
+    end
+  end
+end

data/spec/legion/extensions/agentic/defense/quicksand/helpers/quicksand_engine_spec.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Defense::Quicksand::Helpers::QuicksandEngine do
+  subject(:engine) { described_class.new }
+
+  let(:default_attrs) { { trap_type: :overthinking, domain: :reasoning, content: 'loop' } }
+
+  describe '#create_trap' do
+    it 'creates and stores a trap' do
+      t = engine.create_trap(**default_attrs)
+      expect(t).to be_a(Legion::Extensions::Agentic::Defense::Quicksand::Helpers::Trap)
+      expect(engine.all_traps.size).to eq(1)
+    end
+
+    it 'raises when limit reached' do
+      stub_const('Legion::Extensions::Agentic::Defense::Quicksand::Helpers::Constants::MAX_TRAPS', 1)
+      engine.create_trap(**default_attrs)
+      expect do
+        engine.create_trap(trap_type: :rumination, domain: :t, content: 'x')
+      end.to raise_error(ArgumentError, /trap limit/)
+    end
+  end
+
+  describe '#create_pit' do
+    it 'creates and stores a pit' do
+      p = engine.create_pit
+      expect(p).to be_a(Legion::Extensions::Agentic::Defense::Quicksand::Helpers::Pit)
+      expect(engine.all_pits.size).to eq(1)
+    end
+  end
+
+  describe '#sink_trap' do
+    it 'increases trap depth' do
+      t = engine.create_trap(**default_attrs)
+      initial = t.depth
+      engine.sink_trap(trap_id: t.id)
+      expect(t.depth).to be > initial
+    end
+
+    it 'raises for unknown trap' do
+      expect do
+        engine.sink_trap(trap_id: 'bad')
+      end.to raise_error(ArgumentError, /trap not found/)
+    end
+  end
+
+  describe '#struggle' do
+    it 'returns trap data with depth and count' do
+      t = engine.create_trap(**default_attrs)
+      result = engine.struggle(trap_id: t.id)
+      expect(result[:struggle_count]).to eq(1)
+      expect(result[:depth]).to be > 0.3
+    end
+  end
+
+  describe '#calm' do
+    it 'decreases trap depth' do
+      t = engine.create_trap(**default_attrs)
+      initial = t.depth
+      engine.calm(trap_id: t.id)
+      expect(t.depth).to be < initial
+    end
+  end
+
+  describe '#attempt_escape' do
+    it 'escapes when shallow' do
+      t = engine.create_trap(**default_attrs, depth: 0.5)
+      result = engine.attempt_escape(trap_id: t.id)
+      expect(result[:result]).to eq(:escaped)
+    end
+
+    it 'fails when deep' do
+      t = engine.create_trap(**default_attrs, depth: 0.9)
+      result = engine.attempt_escape(trap_id: t.id)
+      expect(result[:result]).to eq(:too_deep)
+    end
+  end
+
+  describe '#add_trap_to_pit' do
+    it 'links trap to pit' do
+      t = engine.create_trap(**default_attrs)
+      p = engine.create_pit
+      expect(engine.add_trap_to_pit(trap_id: t.id, pit_id: p.id)).to eq(:added)
+    end
+  end
+
+  describe '#sink_all!' do
+    it 'sinks all traps' do
+      t1 = engine.create_trap(**default_attrs)
+      t2 = engine.create_trap(trap_type: :rumination, domain: :t, content: 'x')
+      engine.sink_all!
+      expect(t1.depth).to be > 0.3
+      expect(t2.depth).to be > 0.3
+    end
+  end
+
+  describe '#calm_all!' do
+    it 'calms all traps' do
+      t = engine.create_trap(**default_attrs, depth: 0.5)
+      engine.calm_all!
+      expect(t.depth).to be < 0.5
+    end
+  end
+
+  describe '#traps_by_type' do
+    it 'returns counts' do
+      engine.create_trap(**default_attrs)
+      engine.create_trap(trap_type: :rumination, domain: :t, content: 'x')
+      counts = engine.traps_by_type
+      expect(counts[:overthinking]).to eq(1)
+      expect(counts[:rumination]).to eq(1)
+    end
+  end
+
+  describe '#deepest' do
+    it 'returns traps sorted by depth descending' do
+      engine.create_trap(**default_attrs, depth: 0.2)
+      t2 = engine.create_trap(trap_type: :rumination, domain: :t, content: 'x', depth: 0.9)
+      expect(engine.deepest(limit: 1).first).to eq(t2)
+    end
+  end
+
+  describe '#submerged_traps' do
+    it 'returns only submerged' do
+      engine.create_trap(**default_attrs, depth: 0.9)
+      engine.create_trap(trap_type: :rumination, domain: :t, content: 'x', depth: 0.3)
+      expect(engine.submerged_traps.size).to eq(1)
+    end
+  end
+
+  describe '#stuck_traps' do
+    it 'returns stuck traps' do
+      engine.create_trap(**default_attrs, depth: 0.6, viscosity: 0.7)
+      engine.create_trap(trap_type: :rumination, domain: :t, content: 'x', depth: 0.1)
+      expect(engine.stuck_traps.size).to eq(1)
+    end
+  end
+
+  describe '#quicksand_report' do
+    it 'returns comprehensive hash' do
+      engine.create_trap(**default_attrs)
+      report = engine.quicksand_report
+      expect(report).to include(:total_traps, :total_pits, :by_type,
+                                :submerged, :stuck, :avg_depth, :deadly_pits)
+    end
+
+    it 'handles empty engine' do
+      report = engine.quicksand_report
+      expect(report[:total_traps]).to eq(0)
+      expect(report[:avg_depth]).to eq(0.0)
+    end
+  end
+end

data/spec/legion/extensions/agentic/defense/quicksand/helpers/trap_spec.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Defense::Quicksand::Helpers::Trap do
+  subject(:trap) do
+    described_class.new(trap_type: :overthinking, domain: :reasoning, content: 'recursive loop')
+  end
+
+  describe '#initialize' do
+    it 'assigns a UUID id' do
+      expect(trap.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets trap_type as symbol' do
+      expect(trap.trap_type).to eq(:overthinking)
+    end
+
+    it 'defaults depth to 0.3' do
+      expect(trap.depth).to eq(0.3)
+    end
+
+    it 'defaults viscosity to 0.5' do
+      expect(trap.viscosity).to eq(0.5)
+    end
+
+    it 'starts with 0 struggle_count' do
+      expect(trap.struggle_count).to eq(0)
+    end
+
+    it 'accepts custom depth' do
+      t = described_class.new(trap_type: :rumination, domain: :t, content: 'x', depth: 0.7)
+      expect(t.depth).to eq(0.7)
+    end
+
+    it 'clamps depth to 0..1' do
+      t = described_class.new(trap_type: :indecision, domain: :t, content: 'x', depth: 5.0)
+      expect(t.depth).to eq(1.0)
+    end
+
+    it 'raises on unknown trap type' do
+      expect do
+        described_class.new(trap_type: :happiness, domain: :t, content: 'x')
+      end.to raise_error(ArgumentError, /unknown trap type/)
+    end
+  end
+
+  describe '#sink!' do
+    it 'increases depth' do
+      initial = trap.depth
+      trap.sink!
+      expect(trap.depth).to eq((initial + 0.08).round(10))
+    end
+
+    it 'accepts custom rate' do
+      trap.sink!(rate: 0.2)
+      expect(trap.depth).to eq(0.5)
+    end
+
+    it 'clamps at 1.0' do
+      trap.depth = 0.95
+      trap.sink!(rate: 0.2)
+      expect(trap.depth).to eq(1.0)
+    end
+  end
+
+  describe '#struggle!' do
+    it 'increases depth based on viscosity' do
+      initial = trap.depth
+      trap.struggle!
+      penalty = 0.12 * 0.5
+      expect(trap.depth).to eq((initial + penalty).round(10))
+    end
+
+    it 'increments struggle_count' do
+      trap.struggle!
+      expect(trap.struggle_count).to eq(1)
+    end
+
+    it 'sinks faster with high viscosity' do
+      trap.viscosity = 0.9
+      initial = trap.depth
+      trap.struggle!
+      expect(trap.depth).to be > (initial + 0.1)
+    end
+  end
+
+  describe '#calm!' do
+    it 'decreases depth' do
+      initial = trap.depth
+      trap.calm!
+      expect(trap.depth).to eq((initial - 0.03).round(10))
+    end
+
+    it 'clamps at 0' do
+      trap.depth = 0.01
+      trap.calm!(rate: 0.1)
+      expect(trap.depth).to eq(0.0)
+    end
+  end
+
+  describe '#escape!' do
+    it 'returns :escaped when shallow enough' do
+      trap.depth = 0.5
+      expect(trap.escape!).to eq(:escaped)
+      expect(trap.depth).to eq(0.0)
+    end
+
+    it 'returns :too_deep when too deep' do
+      trap.depth = 0.8
+      expect(trap.escape!).to eq(:too_deep)
+    end
+  end
+
+  describe '#submerged?' do
+    it 'returns false at default depth' do
+      expect(trap).not_to be_submerged
+    end
+
+    it 'returns true at 0.8+' do
+      trap.depth = 0.85
+      expect(trap).to be_submerged
+    end
+  end
+
+  describe '#surface?' do
+    it 'returns false at default depth' do
+      expect(trap).not_to be_surface
+    end
+
+    it 'returns true below 0.2' do
+      trap.depth = 0.1
+      expect(trap).to be_surface
+    end
+  end
+
+  describe '#stuck?' do
+    it 'returns false at default' do
+      expect(trap).not_to be_stuck
+    end
+
+    it 'returns true when deep and viscous' do
+      trap.depth = 0.6
+      trap.viscosity = 0.7
+      expect(trap).to be_stuck
+    end
+  end
+
+  describe '#depth_label' do
+    it 'returns :ankle_deep at default' do
+      expect(trap.depth_label).to eq(:ankle_deep)
+    end
+  end
+
+  describe '#viscosity_label' do
+    it 'returns :moderate at default' do
+      expect(trap.viscosity_label).to eq(:moderate)
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all expected keys' do
+      expected = %i[id trap_type domain content depth viscosity depth_label
+                    viscosity_label struggle_count submerged surface stuck created_at]
+      expect(trap.to_h.keys).to match_array(expected)
+    end
+  end
+end