lex-agentic-defense 0.1.0

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/defense/phantom/client'
+
+RSpec.describe Legion::Extensions::Agentic::Defense::Phantom::Client do
+  subject(:client) { described_class.new }
+
+  it 'includes the CognitivePhantom runner' do
+    expect(client).to respond_to(:register_removal)
+    expect(client).to respond_to(:process_stimulus)
+    expect(client).to respond_to(:acknowledge_phantom)
+    expect(client).to respond_to(:phantom_status)
+    expect(client).to respond_to(:decay_all)
+  end
+
+  it 'can be instantiated with keyword splat' do
+    expect { described_class.new(foo: :bar) }.not_to raise_error
+  end
+
+  describe 'full lifecycle' do
+    it 'registers, triggers, acknowledges, and decays a phantom' do
+      reg = client.register_removal(capability_name: 'lex-ssh', capability_domain: :remote)
+      expect(reg[:success]).to be true
+
+      stim = client.process_stimulus(stimulus: 'ssh connect attempt', domain: :any)
+      expect(stim[:fired_count]).to be >= 1
+
+      ack = client.acknowledge_phantom(phantom_id: reg[:phantom_id])
+      expect(ack[:acknowledged]).to be true
+
+      decay = client.decay_all
+      expect(decay[:success]).to be true
+    end
+
+    it 'tracks multiple phantom removals independently' do
+      client.register_removal(capability_name: 'lex-http')
+      client.register_removal(capability_name: 'lex-redis')
+      client.register_removal(capability_name: 'lex-vault')
+
+      status = client.phantom_status
+      expect(status[:total]).to eq(3)
+      expect(status[:active]).to eq(3)
+    end
+
+    it 'resolves phantom after many acknowledge calls' do
+      reg = client.register_removal(capability_name: 'short-lived-cap')
+      50.times { client.acknowledge_phantom(phantom_id: reg[:phantom_id]) }
+      status = client.phantom_status
+      resolved = status[:by_state][:resolved]
+      expect(resolved).to be >= 1
+    end
+  end
+end

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

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Defense::Phantom::Helpers::Constants do
+  describe 'constants' do
+    it 'defines MAX_PHANTOMS as 100' do
+      expect(described_class::MAX_PHANTOMS).to eq(100)
+    end
+
+    it 'defines INITIAL_INTENSITY as 0.8' do
+      expect(described_class::INITIAL_INTENSITY).to eq(0.8)
+    end
+
+    it 'defines INTENSITY_DECAY as 0.05' do
+      expect(described_class::INTENSITY_DECAY).to eq(0.05)
+    end
+
+    it 'defines MIN_INTENSITY as 0.01' do
+      expect(described_class::MIN_INTENSITY).to eq(0.01)
+    end
+
+    it 'defines four PHANTOM_STATES' do
+      expect(described_class::PHANTOM_STATES).to eq(%i[acute adapting residual resolved])
+    end
+
+    it 'defines four TRIGGER_TYPES' do
+      expect(described_class::TRIGGER_TYPES).to eq(%i[stimulus_match contextual_association temporal_pattern habitual])
+    end
+
+    it 'PHANTOM_STATES is frozen' do
+      expect(described_class::PHANTOM_STATES).to be_frozen
+    end
+
+    it 'TRIGGER_TYPES is frozen' do
+      expect(described_class::TRIGGER_TYPES).to be_frozen
+    end
+  end
+
+  describe '.label_for' do
+    it 'returns label for :acute' do
+      label = described_class.label_for(:acute)
+      expect(label).to be_a(String)
+      expect(label).not_to be_empty
+    end
+
+    it 'returns label for :adapting' do
+      label = described_class.label_for(:adapting)
+      expect(label).to be_a(String)
+    end
+
+    it 'returns label for :residual' do
+      label = described_class.label_for(:residual)
+      expect(label).to be_a(String)
+    end
+
+    it 'returns label for :resolved' do
+      label = described_class.label_for(:resolved)
+      expect(label).to be_a(String)
+    end
+
+    it 'returns unknown label for unrecognized state' do
+      label = described_class.label_for(:nonexistent)
+      expect(label).to include('Unknown')
+    end
+  end
+
+  describe '.state_for' do
+    it 'returns :acute for intensity >= 0.6' do
+      expect(described_class.state_for(0.8)).to eq(:acute)
+      expect(described_class.state_for(0.6)).to eq(:acute)
+    end
+
+    it 'returns :adapting for intensity in [0.3, 0.6)' do
+      expect(described_class.state_for(0.5)).to eq(:adapting)
+      expect(described_class.state_for(0.3)).to eq(:adapting)
+    end
+
+    it 'returns :residual for intensity in (MIN_INTENSITY, 0.3)' do
+      expect(described_class.state_for(0.15)).to eq(:residual)
+      expect(described_class.state_for(0.02)).to eq(:residual)
+    end
+
+    it 'returns :resolved for intensity at or below MIN_INTENSITY' do
+      expect(described_class.state_for(0.01)).to eq(:resolved)
+      expect(described_class.state_for(0.0)).to eq(:resolved)
+    end
+  end
+end

data/spec/legion/extensions/agentic/defense/phantom/helpers/phantom_engine_spec.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Defense::Phantom::Helpers::PhantomEngine do
+  subject(:engine) { described_class.new }
+
+  describe '#register_removal' do
+    it 'returns a PhantomLimb' do
+      limb = engine.register_removal(capability_name: 'lex-http', capability_domain: :network)
+      expect(limb).to be_a(Legion::Extensions::Agentic::Defense::Phantom::Helpers::PhantomLimb)
+    end
+
+    it 'assigns a uuid id' do
+      limb = engine.register_removal(capability_name: 'lex-redis')
+      expect(limb.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'defaults capability_domain to :general' do
+      limb = engine.register_removal(capability_name: 'lex-vault')
+      expect(limb.capability_domain).to eq(:general)
+    end
+
+    it 'adds limb to all_phantoms' do
+      engine.register_removal(capability_name: 'lex-http')
+      expect(engine.all_phantoms.size).to eq(1)
+    end
+
+    it 'returns nil when MAX_PHANTOMS is reached' do
+      stub_const('Legion::Extensions::Agentic::Defense::Phantom::Helpers::Constants::MAX_PHANTOMS', 2)
+      engine.register_removal(capability_name: 'cap1')
+      engine.register_removal(capability_name: 'cap2')
+      result = engine.register_removal(capability_name: 'cap3')
+      expect(result).to be_nil
+    end
+
+    it 'allows up to MAX_PHANTOMS registrations' do
+      stub_const('Legion::Extensions::Agentic::Defense::Phantom::Helpers::Constants::MAX_PHANTOMS', 3)
+      3.times { |i| engine.register_removal(capability_name: "cap_#{i}") }
+      expect(engine.all_phantoms.size).to eq(3)
+    end
+  end
+
+  describe '#process_stimulus' do
+    before do
+      engine.register_removal(capability_name: 'lex-http', capability_domain: :network)
+      engine.register_removal(capability_name: 'lex-redis', capability_domain: :cache)
+    end
+
+    it 'returns an array of PhantomSignals' do
+      signals = engine.process_stimulus(stimulus: 'test', domain: :any)
+      expect(signals).to all(be_a(Legion::Extensions::Agentic::Defense::Phantom::Helpers::PhantomSignal))
+    end
+
+    it 'fires all active phantoms when domain is :any' do
+      signals = engine.process_stimulus(stimulus: 'event', domain: :any)
+      expect(signals.size).to eq(2)
+    end
+
+    it 'only fires phantoms matching domain' do
+      signals = engine.process_stimulus(stimulus: 'cache miss', domain: :cache)
+      expect(signals.size).to eq(1)
+      expect(signals.first.phantom_limb_id).to be_a(String)
+    end
+
+    it 'returns empty array when no matching domain' do
+      signals = engine.process_stimulus(stimulus: 'event', domain: :storage)
+      expect(signals).to be_empty
+    end
+
+    it 'does not fire resolved phantoms' do
+      limb = engine.all_phantoms.first
+      160.times { limb.decay! }
+      signals = engine.process_stimulus(stimulus: 'lex-http request', domain: :network)
+      expect(signals).to be_empty
+    end
+  end
+
+  describe '#decay_all!' do
+    before { engine.register_removal(capability_name: 'lex-http') }
+
+    it 'reduces intensity of all active phantoms' do
+      before_intensity = engine.active_phantoms.first.intensity
+      engine.decay_all!
+      expect(engine.active_phantoms.first.intensity).to be < before_intensity
+    end
+
+    it 'returns count of newly resolved phantoms' do
+      stub_const('Legion::Extensions::Agentic::Defense::Phantom::Helpers::Constants::INITIAL_INTENSITY', Legion::Extensions::Agentic::Defense::Phantom::Helpers::Constants::MIN_INTENSITY)
+      engine2 = described_class.new
+      engine2.register_removal(capability_name: 'cap_at_min')
+      count = engine2.decay_all!
+      expect(count).to be >= 0
+    end
+  end
+
+  describe '#acknowledge' do
+    let!(:limb) { engine.register_removal(capability_name: 'lex-vault') }
+
+    it 'returns acknowledged: true for valid phantom_id' do
+      result = engine.acknowledge(phantom_id: limb.id)
+      expect(result[:acknowledged]).to be true
+    end
+
+    it 'returns phantom_id in result' do
+      result = engine.acknowledge(phantom_id: limb.id)
+      expect(result[:phantom_id]).to eq(limb.id)
+    end
+
+    it 'returns state in result' do
+      result = engine.acknowledge(phantom_id: limb.id)
+      expect(Legion::Extensions::Agentic::Defense::Phantom::Helpers::Constants::PHANTOM_STATES).to include(result[:state])
+    end
+
+    it 'accelerates decay on acknowledgment' do
+      before_intensity = limb.intensity
+      engine.acknowledge(phantom_id: limb.id)
+      expect(limb.intensity).to be < before_intensity
+    end
+
+    it 'returns acknowledged: false for unknown phantom_id' do
+      result = engine.acknowledge(phantom_id: 'nonexistent-uuid')
+      expect(result[:acknowledged]).to be false
+      expect(result[:reason]).to eq(:not_found)
+    end
+  end
+
+  describe '#all_phantoms' do
+    it 'returns all registered phantoms including resolved' do
+      engine.register_removal(capability_name: 'cap1')
+      engine.register_removal(capability_name: 'cap2')
+      expect(engine.all_phantoms.size).to eq(2)
+    end
+  end
+
+  describe '#active_phantoms' do
+    it 'excludes resolved phantoms' do
+      engine.register_removal(capability_name: 'cap1')
+      limb = engine.register_removal(capability_name: 'cap2')
+      160.times { limb.decay! }
+      expect(engine.active_phantoms.size).to eq(1)
+    end
+  end
+
+  describe '#phantom_activity_report' do
+    before do
+      engine.register_removal(capability_name: 'cap1', capability_domain: :network)
+      engine.register_removal(capability_name: 'cap2', capability_domain: :cache)
+    end
+
+    it 'returns total count' do
+      expect(engine.phantom_activity_report[:total]).to eq(2)
+    end
+
+    it 'returns active count' do
+      expect(engine.phantom_activity_report[:active]).to eq(2)
+    end
+
+    it 'returns by_state breakdown' do
+      report = engine.phantom_activity_report
+      expect(report[:by_state]).to be_a(Hash)
+      expect(report[:by_state].keys).to match_array(%i[acute adapting residual resolved])
+    end
+
+    it 'returns total_activations' do
+      engine.process_stimulus(stimulus: 'event', domain: :any)
+      expect(engine.phantom_activity_report[:total_activations]).to eq(2)
+    end
+  end
+
+  describe '#most_persistent' do
+    before do
+      3.times do |i|
+        limb = engine.register_removal(capability_name: "cap_#{i}")
+        i.times { limb.trigger!("stimulus_#{i}") }
+      end
+    end
+
+    it 'returns active phantoms sorted by activation_count descending' do
+      result = engine.most_persistent(limit: 3)
+      counts = result.map(&:activation_count)
+      expect(counts).to eq(counts.sort.reverse)
+    end
+
+    it 'respects limit' do
+      result = engine.most_persistent(limit: 2)
+      expect(result.size).to be <= 2
+    end
+  end
+
+  describe '#recently_triggered' do
+    before do
+      2.times do |i|
+        limb = engine.register_removal(capability_name: "cap_#{i}")
+        limb.trigger!("stimulus_#{i}")
+      end
+    end
+
+    it 'returns recently triggered phantoms' do
+      result = engine.recently_triggered(limit: 5)
+      expect(result).not_to be_empty
+      result.each { |p| expect(p.last_triggered).not_to be_nil }
+    end
+
+    it 'respects limit' do
+      result = engine.recently_triggered(limit: 1)
+      expect(result.size).to be <= 1
+    end
+  end
+
+  describe '#resolve_check!' do
+    it 'returns count of resolved phantoms' do
+      limb = engine.register_removal(capability_name: 'cap_near_zero')
+      160.times { limb.decay! }
+      count = engine.resolve_check!
+      expect(count).to be >= 1
+    end
+
+    it 'returns 0 when no phantoms are resolved' do
+      engine.register_removal(capability_name: 'fresh_cap')
+      expect(engine.resolve_check!).to eq(0)
+    end
+  end
+end

data/spec/legion/extensions/agentic/defense/phantom/helpers/phantom_limb_spec.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Defense::Phantom::Helpers::PhantomLimb do
+  subject(:limb) do
+    described_class.new(capability_name: 'lex-http', capability_domain: :network)
+  end
+
+  describe '#initialize' do
+    it 'assigns a uuid id' do
+      expect(limb.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores capability_name' do
+      expect(limb.capability_name).to eq('lex-http')
+    end
+
+    it 'stores capability_domain' do
+      expect(limb.capability_domain).to eq(:network)
+    end
+
+    it 'sets removed_at to now' do
+      expect(limb.removed_at).to be_a(Time)
+    end
+
+    it 'starts at INITIAL_INTENSITY' do
+      expect(limb.intensity).to be_within(0.001).of(Legion::Extensions::Agentic::Defense::Phantom::Helpers::Constants::INITIAL_INTENSITY)
+    end
+
+    it 'starts with zero activation_count' do
+      expect(limb.activation_count).to eq(0)
+    end
+
+    it 'has nil last_triggered initially' do
+      expect(limb.last_triggered).to be_nil
+    end
+
+    it 'has empty trigger_history' do
+      expect(limb.trigger_history).to be_empty
+    end
+  end
+
+  describe '#state' do
+    it 'returns :acute at initial intensity' do
+      expect(limb.state).to eq(:acute)
+    end
+
+    it 'transitions to :adapting as intensity drops' do
+      7.times { limb.decay! }
+      expect(%i[adapting acute residual]).to include(limb.state)
+    end
+  end
+
+  describe '#resolved?' do
+    it 'returns false at initial intensity' do
+      expect(limb.resolved?).to be false
+    end
+
+    it 'returns true when intensity is at MIN_INTENSITY' do
+      160.times { limb.decay! }
+      expect(limb.resolved?).to be true
+    end
+  end
+
+  describe '#trigger!' do
+    it 'returns a PhantomSignal' do
+      result = limb.trigger!('http.get request')
+      expect(result).to be_a(Legion::Extensions::Agentic::Defense::Phantom::Helpers::PhantomSignal)
+    end
+
+    it 'increments activation_count' do
+      limb.trigger!('test')
+      expect(limb.activation_count).to eq(1)
+    end
+
+    it 'sets last_triggered' do
+      limb.trigger!('test')
+      expect(limb.last_triggered).to be_a(Time)
+    end
+
+    it 'adds signal to trigger_history' do
+      limb.trigger!('test')
+      expect(limb.trigger_history.size).to eq(1)
+    end
+
+    it 'caps trigger_history at 50 entries' do
+      55.times { |i| limb.trigger!("stimulus_#{i}") }
+      expect(limb.trigger_history.size).to eq(50)
+    end
+
+    it 'returns false when resolved' do
+      160.times { limb.decay! }
+      expect(limb.trigger!('test')).to be false
+    end
+
+    it 'classifies trigger as :stimulus_match when stimulus contains capability name' do
+      signal = limb.trigger!('lex-http request fired')
+      expect(signal.trigger_type).to eq(:stimulus_match)
+    end
+
+    it 'classifies as :contextual_association for a fresh limb with generic stimulus' do
+      fresh = described_class.new(capability_name: 'lex-redis', capability_domain: :cache)
+      signal = fresh.trigger!('some unrelated event')
+      expect(signal.trigger_type).to eq(:contextual_association)
+    end
+
+    it 'classifies repeated rapid activations as :temporal_pattern' do
+      2.times { limb.trigger!('something') }
+      signal = limb.trigger!('something')
+      expect(signal.trigger_type).to eq(:temporal_pattern)
+    end
+
+    it 'classifies as :habitual when activation_count > 10 and last trigger was long ago' do
+      fresh = described_class.new(capability_name: 'lex-vault', capability_domain: :secrets)
+      11.times { fresh.trigger!('some event') }
+      fresh.instance_variable_set(:@last_triggered, Time.now.utc - 120)
+      signal = fresh.trigger!('some event')
+      expect(signal.trigger_type).to eq(:habitual)
+    end
+
+    it 'classifies signal with a valid trigger type' do
+      fresh = described_class.new(capability_name: 'lex-vault', capability_domain: :secrets)
+      15.times { fresh.trigger!('some event') }
+      signal = fresh.trigger!('some event')
+      expect(Legion::Extensions::Agentic::Defense::Phantom::Helpers::Constants::TRIGGER_TYPES).to include(signal.trigger_type)
+    end
+  end
+
+  describe '#decay!' do
+    it 'reduces intensity by INTENSITY_DECAY' do
+      before = limb.intensity
+      limb.decay!
+      expect(limb.intensity).to be_within(0.001).of(before - Legion::Extensions::Agentic::Defense::Phantom::Helpers::Constants::INTENSITY_DECAY)
+    end
+
+    it 'does not drop below MIN_INTENSITY' do
+      200.times { limb.decay! }
+      expect(limb.intensity).to eq(Legion::Extensions::Agentic::Defense::Phantom::Helpers::Constants::MIN_INTENSITY)
+    end
+
+    it 'does nothing when already resolved' do
+      160.times { limb.decay! }
+      resolved_intensity = limb.intensity
+      limb.decay!
+      expect(limb.intensity).to eq(resolved_intensity)
+    end
+  end
+
+  describe '#adapt!' do
+    it 'reduces intensity faster than decay!' do
+      limb2 = described_class.new(capability_name: 'lex-http', capability_domain: :network)
+      limb.adapt!
+      limb2.decay!
+      expect(limb.intensity).to be < limb2.intensity
+    end
+
+    it 'does not drop below MIN_INTENSITY' do
+      100.times { limb.adapt! }
+      expect(limb.intensity).to eq(Legion::Extensions::Agentic::Defense::Phantom::Helpers::Constants::MIN_INTENSITY)
+    end
+
+    it 'does nothing when already resolved' do
+      100.times { limb.adapt! }
+      resolved_intensity = limb.intensity
+      limb.adapt!
+      expect(limb.intensity).to eq(resolved_intensity)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with expected keys' do
+      h = limb.to_h
+      expect(h).to include(:id, :capability_name, :capability_domain, :removed_at, :intensity, :activation_count, :state, :resolved)
+    end
+
+    it 'reflects resolved status' do
+      160.times { limb.decay! }
+      expect(limb.to_h[:resolved]).to be true
+    end
+  end
+end

data/spec/legion/extensions/agentic/defense/phantom/helpers/phantom_signal_spec.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Defense::Phantom::Helpers::PhantomSignal do
+  let(:phantom_id) { SecureRandom.uuid }
+
+  subject(:signal) do
+    described_class.new(
+      phantom_limb_id:      phantom_id,
+      stimulus:             'http.get request',
+      trigger_type:         :stimulus_match,
+      intensity_at_trigger: 0.75
+    )
+  end
+
+  describe '#initialize' do
+    it 'assigns a uuid id' do
+      expect(signal.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores phantom_limb_id' do
+      expect(signal.phantom_limb_id).to eq(phantom_id)
+    end
+
+    it 'stores stimulus' do
+      expect(signal.stimulus).to eq('http.get request')
+    end
+
+    it 'stores trigger_type' do
+      expect(signal.trigger_type).to eq(:stimulus_match)
+    end
+
+    it 'stores intensity_at_trigger' do
+      expect(signal.intensity_at_trigger).to be_within(0.001).of(0.75)
+    end
+
+    it 'clamps intensity_at_trigger to [0, 1]' do
+      over = described_class.new(phantom_limb_id: phantom_id, stimulus: 's', trigger_type: :habitual, intensity_at_trigger: 2.0)
+      under = described_class.new(phantom_limb_id: phantom_id, stimulus: 's', trigger_type: :habitual, intensity_at_trigger: -0.5)
+      expect(over.intensity_at_trigger).to eq(1.0)
+      expect(under.intensity_at_trigger).to eq(0.0)
+    end
+
+    it 'sets timestamp to current utc time' do
+      expect(signal.timestamp).to be_a(Time)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with expected keys' do
+      h = signal.to_h
+      expect(h).to include(:id, :phantom_limb_id, :stimulus, :trigger_type, :intensity_at_trigger, :timestamp)
+    end
+
+    it 'intensity_at_trigger is rounded to 10 decimal places' do
+      h = signal.to_h
+      expect(h[:intensity_at_trigger]).to eq(signal.intensity_at_trigger.round(10))
+    end
+  end
+end