lex-agentic-defense 0.1.0

data/spec/legion/extensions/agentic/defense/avalanche/helpers/avalanche_engine_spec.rb

@@ -0,0 +1,276 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Defense::Avalanche::Helpers::AvalancheEngine do
+  subject(:engine) { described_class.new }
+
+  let(:snowpack_id) do
+    engine.create_snowpack(
+      snowpack_type: :ideas,
+      domain:        :creativity,
+      content:       'divergent thinking spiral',
+      stability:     0.3
+    )[:snowpack_id]
+  end
+
+  let(:stable_snowpack_id) do
+    engine.create_snowpack(
+      snowpack_type: :memories,
+      domain:        :identity,
+      content:       'foundational self-concept',
+      stability:     0.9
+    )[:snowpack_id]
+  end
+
+  describe '#create_snowpack' do
+    it 'creates a snowpack and returns success' do
+      result = engine.create_snowpack(snowpack_type: :emotions, domain: :fear, content: 'anticipatory dread')
+      expect(result[:success]).to be(true)
+      expect(result[:snowpack_id]).not_to be_nil
+    end
+
+    it 'returns a snowpack hash in the result' do
+      result = engine.create_snowpack(snowpack_type: :ideas, domain: :test, content: 'x')
+      expect(result[:snowpack]).to be_a(Hash)
+      expect(result[:snowpack][:domain]).to eq(:test)
+    end
+
+    it 'stores the snowpack in @snowpacks' do
+      result = engine.create_snowpack(snowpack_type: :impulses, domain: :action, content: 'do it now')
+      expect(engine.snowpacks).to have_key(result[:snowpack_id])
+    end
+
+    it 'returns failure for invalid snowpack_type' do
+      result = engine.create_snowpack(snowpack_type: :invalid, domain: :test, content: 'x')
+      expect(result[:success]).to be(false)
+      expect(result[:error]).to match(/unknown snowpack_type/)
+    end
+
+    it 'enforces MAX_SNOWPACKS limit' do
+      100.times { |i| engine.create_snowpack(snowpack_type: :ideas, domain: :test, content: "x#{i}") }
+      result = engine.create_snowpack(snowpack_type: :ideas, domain: :test, content: 'overflow')
+      expect(result[:success]).to be(false)
+      expect(result[:error]).to match(/snowpack limit/)
+    end
+
+    it 'respects custom depth' do
+      result = engine.create_snowpack(snowpack_type: :ideas, domain: :test, content: 'x', depth: 0.5)
+      expect(engine.snowpacks[result[:snowpack_id]].depth).to eq(0.5)
+    end
+
+    it 'respects custom stability' do
+      result = engine.create_snowpack(snowpack_type: :ideas, domain: :test, content: 'x', stability: 0.2)
+      expect(engine.snowpacks[result[:snowpack_id]].stability).to eq(0.2)
+    end
+  end
+
+  describe '#trigger' do
+    it 'triggers a cascade when force + instability >= threshold' do
+      result = engine.trigger(snowpack_id: snowpack_id, force: 0.5)
+      expect(result[:success]).to be(true)
+      expect(result[:triggered]).to be(true)
+      expect(result[:cascade_id]).not_to be_nil
+    end
+
+    it 'returns no trigger when combined force+instability is below threshold' do
+      result = engine.trigger(snowpack_id: stable_snowpack_id, force: 0.01)
+      expect(result[:success]).to be(true)
+      expect(result[:triggered]).to be(false)
+    end
+
+    it 'returns failure for unknown snowpack_id' do
+      result = engine.trigger(snowpack_id: 'ghost-uuid', force: 0.5)
+      expect(result[:success]).to be(false)
+      expect(result[:error]).to match(/snowpack not found/)
+    end
+
+    it 'includes cascade hash in triggered result' do
+      result = engine.trigger(snowpack_id: snowpack_id, force: 0.5)
+      expect(result[:cascade]).to be_a(Hash)
+      expect(result[:cascade][:cascade_type]).not_to be_nil
+    end
+
+    it 'accepts custom cascade_type' do
+      result = engine.trigger(snowpack_id: snowpack_id, force: 0.5, cascade_type: :creative)
+      expect(result[:cascade][:cascade_type]).to eq(:creative)
+    end
+
+    it 'records cascade in cascade_history' do
+      engine.trigger(snowpack_id: snowpack_id, force: 0.5)
+      expect(engine.cascade_history).not_to be_empty
+    end
+
+    it 'destabilizes the snowpack' do
+      pack = engine.snowpacks[snowpack_id]
+      before_stability = pack.stability
+      engine.trigger(snowpack_id: snowpack_id, force: 0.2)
+      expect(pack.stability).to be < before_stability
+    end
+
+    it 'adds snowpack content to cascade debris' do
+      result = engine.trigger(snowpack_id: snowpack_id, force: 0.5)
+      expect(result[:cascade][:debris]).to include('divergent thinking spiral')
+    end
+
+    it 'includes instability in result' do
+      result = engine.trigger(snowpack_id: snowpack_id, force: 0.5)
+      expect(result).to have_key(:instability)
+    end
+  end
+
+  describe '#accumulate_all!' do
+    before { snowpack_id && stable_snowpack_id }
+
+    it 'returns success' do
+      result = engine.accumulate_all!
+      expect(result[:success]).to be(true)
+    end
+
+    it 'reports packs_accumulated count' do
+      result = engine.accumulate_all!
+      expect(result[:packs_accumulated]).to eq(2)
+    end
+
+    it 'increases depth of all snowpacks' do
+      packs = engine.snowpacks.values
+      before_depths = packs.map(&:depth)
+      engine.accumulate_all!
+      packs.each_with_index do |pack, i|
+        expect(pack.depth).to be >= before_depths[i]
+      end
+    end
+
+    it 'uses custom rate when provided' do
+      result = engine.accumulate_all!(rate: 0.1)
+      expect(result[:rate]).to eq(0.1)
+    end
+  end
+
+  describe '#melt_all!' do
+    before do
+      engine.create_snowpack(snowpack_type: :ideas, domain: :test, content: 'x', depth: 0.5)
+      engine.create_snowpack(snowpack_type: :emotions, domain: :test, content: 'y', depth: 0.5)
+    end
+
+    it 'returns success' do
+      result = engine.melt_all!
+      expect(result[:success]).to be(true)
+    end
+
+    it 'reports packs_melted count' do
+      result = engine.melt_all!
+      expect(result[:packs_melted]).to eq(2)
+    end
+
+    it 'decreases depth of all snowpacks' do
+      packs  = engine.snowpacks.values
+      before = packs.map(&:depth)
+      engine.melt_all!
+      packs.each_with_index do |pack, i|
+        expect(pack.depth).to be <= before[i]
+      end
+    end
+  end
+
+  describe '#active_cascades' do
+    it 'returns empty array with no history' do
+      expect(engine.active_cascades).to eq([])
+    end
+
+    it 'returns only active cascades' do
+      engine.trigger(snowpack_id: snowpack_id, force: 0.5)
+      expect(engine.active_cascades).not_to be_empty
+    end
+  end
+
+  describe '#most_unstable' do
+    it 'returns nil when no snowpacks exist' do
+      expect(engine.most_unstable).to be_nil
+    end
+
+    it 'returns the snowpack with lowest stability' do
+      snowpack_id
+      stable_snowpack_id
+      expect(engine.most_unstable.id).to eq(snowpack_id)
+    end
+  end
+
+  describe '#terrain_report' do
+    before { snowpack_id && stable_snowpack_id }
+
+    it 'includes total_snowpacks' do
+      report = engine.terrain_report
+      expect(report[:total_snowpacks]).to eq(2)
+    end
+
+    it 'includes critical_count' do
+      report = engine.terrain_report
+      expect(report).to have_key(:critical_count)
+    end
+
+    it 'includes unstable_count' do
+      report = engine.terrain_report
+      expect(report).to have_key(:unstable_count)
+    end
+
+    it 'includes stable_count' do
+      report = engine.terrain_report
+      expect(report).to have_key(:stable_count)
+    end
+
+    it 'includes active_cascades count' do
+      report = engine.terrain_report
+      expect(report).to have_key(:active_cascades)
+    end
+
+    it 'includes cascade_history count' do
+      engine.trigger(snowpack_id: snowpack_id, force: 0.5)
+      report = engine.terrain_report
+      expect(report[:cascade_history]).to be >= 1
+    end
+
+    it 'includes avg_stability' do
+      report = engine.terrain_report
+      expect(report[:avg_stability]).to be_a(Float)
+    end
+
+    it 'includes avg_depth' do
+      report = engine.terrain_report
+      expect(report[:avg_depth]).to be_a(Float)
+    end
+
+    it 'includes most_unstable_id' do
+      report = engine.terrain_report
+      expect(report[:most_unstable_id]).to eq(snowpack_id)
+    end
+
+    it 'includes recent_cascades array' do
+      report = engine.terrain_report
+      expect(report[:recent_cascades]).to be_an(Array)
+    end
+
+    it 'caps recent_cascades at 5' do
+      10.times { engine.trigger(snowpack_id: snowpack_id, force: 0.5) }
+      report = engine.terrain_report
+      expect(report[:recent_cascades].size).to be <= 5
+    end
+  end
+
+  describe 'cascade_history cap' do
+    it 'caps cascade_history at MAX_CASCADE_HISTORY' do
+      pack_id = engine.create_snowpack(
+        snowpack_type: :impulses, domain: :stress, content: 'persistent trigger', stability: 0.0
+      )[:snowpack_id]
+
+      510.times do
+        engine.send(:record_cascade,
+                    Legion::Extensions::Agentic::Defense::Avalanche::Helpers::Cascade.new(
+                      cascade_type:   :chaotic,
+                      trigger_source: pack_id,
+                      magnitude:      0.5
+                    ))
+      end
+
+      expect(engine.cascade_history.size).to eq(500)
+    end
+  end
+end

data/spec/legion/extensions/agentic/defense/avalanche/helpers/cascade_spec.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Defense::Avalanche::Helpers::Cascade do
+  subject(:cascade) do
+    described_class.new(cascade_type: :creative, trigger_source: 'sp-abc', magnitude: 0.5)
+  end
+
+  describe '#initialize' do
+    it 'assigns a uuid id' do
+      expect(cascade.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets cascade_type' do
+      expect(cascade.cascade_type).to eq(:creative)
+    end
+
+    it 'sets trigger_source' do
+      expect(cascade.trigger_source).to eq('sp-abc')
+    end
+
+    it 'sets magnitude' do
+      expect(cascade.magnitude).to eq(0.5)
+    end
+
+    it 'defaults propagation_speed to 0.5' do
+      expect(cascade.propagation_speed).to eq(0.5)
+    end
+
+    it 'defaults debris to empty array' do
+      expect(cascade.debris).to eq([])
+    end
+
+    it 'records started_at timestamp' do
+      expect(cascade.started_at).to be_a(Time)
+    end
+
+    it 'starts as active' do
+      expect(cascade.active?).to be(true)
+    end
+
+    it 'clamps magnitude above 1.0 to 1.0' do
+      c = described_class.new(cascade_type: :emotional, trigger_source: 'x', magnitude: 2.0)
+      expect(c.magnitude).to eq(1.0)
+    end
+
+    it 'clamps magnitude below 0.0 to 0.0' do
+      c = described_class.new(cascade_type: :emotional, trigger_source: 'x', magnitude: -0.5)
+      expect(c.magnitude).to eq(0.0)
+    end
+
+    it 'raises ArgumentError for unknown cascade_type' do
+      expect do
+        described_class.new(cascade_type: :volcanic, trigger_source: 'x', magnitude: 0.5)
+      end.to raise_error(ArgumentError, /unknown cascade_type/)
+    end
+
+    it 'accepts all valid cascade_types' do
+      %i[creative emotional analytical chaotic convergent].each do |type|
+        expect do
+          described_class.new(cascade_type: type, trigger_source: 'x', magnitude: 0.5)
+        end.not_to raise_error
+      end
+    end
+
+    it 'accepts pre-populated debris' do
+      c = described_class.new(cascade_type: :chaotic, trigger_source: 'x', magnitude: 0.5, debris: ['idea1'])
+      expect(c.debris).to include('idea1')
+    end
+  end
+
+  describe '#propagate!' do
+    it 'increases magnitude by default 0.1' do
+      before = cascade.magnitude
+      cascade.propagate!
+      expect(cascade.magnitude).to be_within(0.0001).of(before + 0.1)
+    end
+
+    it 'increases magnitude by given rate' do
+      before = cascade.magnitude
+      cascade.propagate!(0.2)
+      expect(cascade.magnitude).to be_within(0.0001).of(before + 0.2)
+    end
+
+    it 'clamps magnitude at 1.0' do
+      c = described_class.new(cascade_type: :chaotic, trigger_source: 'x', magnitude: 0.95)
+      c.propagate!(0.5)
+      expect(c.magnitude).to eq(1.0)
+    end
+
+    it 'does nothing when spent' do
+      c = described_class.new(cascade_type: :chaotic, trigger_source: 'x', magnitude: 0.5)
+      c.dissipate!(1.0)
+      before = c.magnitude
+      c.propagate!(0.1)
+      expect(c.magnitude).to eq(before)
+    end
+  end
+
+  describe '#dissipate!' do
+    it 'decreases magnitude by default 0.08' do
+      before = cascade.magnitude
+      cascade.dissipate!
+      expect(cascade.magnitude).to be_within(0.0001).of(before - 0.08)
+    end
+
+    it 'decreases magnitude by given rate' do
+      before = cascade.magnitude
+      cascade.dissipate!(0.1)
+      expect(cascade.magnitude).to be_within(0.0001).of(before - 0.1)
+    end
+
+    it 'clamps magnitude at 0.0' do
+      c = described_class.new(cascade_type: :chaotic, trigger_source: 'x', magnitude: 0.05)
+      c.dissipate!(0.5)
+      expect(c.magnitude).to eq(0.0)
+    end
+
+    it 'marks cascade as spent when magnitude reaches 0.0' do
+      c = described_class.new(cascade_type: :chaotic, trigger_source: 'x', magnitude: 0.05)
+      c.dissipate!(0.5)
+      expect(c.spent?).to be(true)
+    end
+  end
+
+  describe '#active?' do
+    it 'returns true when active and magnitude > 0.0' do
+      expect(cascade.active?).to be(true)
+    end
+
+    it 'returns false when fully dissipated' do
+      cascade.dissipate!(1.0)
+      expect(cascade.active?).to be(false)
+    end
+  end
+
+  describe '#spent?' do
+    it 'returns false for new cascade' do
+      expect(cascade.spent?).to be(false)
+    end
+
+    it 'returns true after full dissipation' do
+      cascade.dissipate!(1.0)
+      expect(cascade.spent?).to be(true)
+    end
+  end
+
+  describe '#magnitude_label' do
+    it 'returns :minor for magnitude 0.1' do
+      c = described_class.new(cascade_type: :chaotic, trigger_source: 'x', magnitude: 0.1)
+      expect(c.magnitude_label).to eq(:minor)
+    end
+
+    it 'returns :devastating for magnitude 0.9' do
+      c = described_class.new(cascade_type: :chaotic, trigger_source: 'x', magnitude: 0.9)
+      expect(c.magnitude_label).to eq(:devastating)
+    end
+  end
+
+  describe '#add_debris' do
+    it 'appends to debris array' do
+      cascade.add_debris('new thought fragment')
+      expect(cascade.debris).to include('new thought fragment')
+    end
+
+    it 'supports multiple debris items' do
+      cascade.add_debris('item1')
+      cascade.add_debris('item2')
+      expect(cascade.debris.size).to eq(2)
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all expected keys' do
+      h = cascade.to_h
+      expect(h.keys).to include(:id, :cascade_type, :trigger_source, :magnitude, :magnitude_label,
+                                :propagation_speed, :debris, :active, :started_at)
+    end
+
+    it 'reflects current active state' do
+      cascade.dissipate!(1.0)
+      expect(cascade.to_h[:active]).to be(false)
+    end
+
+    it 'returns a duplicate of debris' do
+      h = cascade.to_h
+      h[:debris] << 'mutant'
+      expect(cascade.debris).not_to include('mutant')
+    end
+  end
+end

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

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Defense::Avalanche::Helpers::Constants do
+  def described_module
+    Legion::Extensions::Agentic::Defense::Avalanche::Helpers::Constants
+  end
+
+  describe 'MAX_SNOWPACKS' do
+    it 'is 100' do
+      expect(described_module::MAX_SNOWPACKS).to eq(100)
+    end
+  end
+
+  describe 'MAX_CASCADE_HISTORY' do
+    it 'is 500' do
+      expect(described_module::MAX_CASCADE_HISTORY).to eq(500)
+    end
+  end
+
+  describe 'TRIGGER_THRESHOLD' do
+    it 'is 0.75' do
+      expect(described_module::TRIGGER_THRESHOLD).to eq(0.75)
+    end
+  end
+
+  describe 'ACCUMULATION_RATE' do
+    it 'is 0.06' do
+      expect(described_module::ACCUMULATION_RATE).to eq(0.06)
+    end
+  end
+
+  describe 'MELT_RATE' do
+    it 'is 0.02' do
+      expect(described_module::MELT_RATE).to eq(0.02)
+    end
+  end
+
+  describe 'SNOWPACK_TYPES' do
+    it 'contains all five types' do
+      expect(described_module::SNOWPACK_TYPES).to eq(%i[ideas emotions memories associations impulses])
+    end
+
+    it 'is frozen' do
+      expect(described_module::SNOWPACK_TYPES).to be_frozen
+    end
+  end
+
+  describe 'CASCADE_TYPES' do
+    it 'contains all five types' do
+      expect(described_module::CASCADE_TYPES).to eq(%i[creative emotional analytical chaotic convergent])
+    end
+
+    it 'is frozen' do
+      expect(described_module::CASCADE_TYPES).to be_frozen
+    end
+  end
+
+  describe 'STABILITY_LABELS' do
+    it 'is a hash' do
+      expect(described_module::STABILITY_LABELS).to be_a(Hash)
+    end
+
+    it 'covers catastrophic through bedrock' do
+      labels = described_module::STABILITY_LABELS.values
+      expect(labels).to include(:catastrophic, :critical, :unstable, :moderate, :bedrock)
+    end
+  end
+
+  describe 'MAGNITUDE_LABELS' do
+    it 'is a hash' do
+      expect(described_module::MAGNITUDE_LABELS).to be_a(Hash)
+    end
+
+    it 'covers minor through devastating' do
+      labels = described_module::MAGNITUDE_LABELS.values
+      expect(labels).to include(:minor, :moderate, :significant, :major, :devastating)
+    end
+  end
+
+  describe '.label_for' do
+    it 'returns :catastrophic for stability 0.1' do
+      expect(described_module.label_for(:STABILITY_LABELS, 0.1)).to eq(:catastrophic)
+    end
+
+    it 'returns :critical for stability 0.3' do
+      expect(described_module.label_for(:STABILITY_LABELS, 0.3)).to eq(:critical)
+    end
+
+    it 'returns :unstable for stability 0.5' do
+      expect(described_module.label_for(:STABILITY_LABELS, 0.5)).to eq(:unstable)
+    end
+
+    it 'returns :moderate for stability 0.7' do
+      expect(described_module.label_for(:STABILITY_LABELS, 0.7)).to eq(:moderate)
+    end
+
+    it 'returns :bedrock for stability 0.9' do
+      expect(described_module.label_for(:STABILITY_LABELS, 0.9)).to eq(:bedrock)
+    end
+
+    it 'returns :minor for magnitude 0.1' do
+      expect(described_module.label_for(:MAGNITUDE_LABELS, 0.1)).to eq(:minor)
+    end
+
+    it 'returns :moderate for magnitude 0.3' do
+      expect(described_module.label_for(:MAGNITUDE_LABELS, 0.3)).to eq(:moderate)
+    end
+
+    it 'returns :significant for magnitude 0.5' do
+      expect(described_module.label_for(:MAGNITUDE_LABELS, 0.5)).to eq(:significant)
+    end
+
+    it 'returns :major for magnitude 0.7' do
+      expect(described_module.label_for(:MAGNITUDE_LABELS, 0.7)).to eq(:major)
+    end
+
+    it 'returns :devastating for magnitude 0.9' do
+      expect(described_module.label_for(:MAGNITUDE_LABELS, 0.9)).to eq(:devastating)
+    end
+
+    it 'clamps values above 1.0 to 1.0' do
+      expect(described_module.label_for(:MAGNITUDE_LABELS, 1.5)).not_to eq(:unknown)
+    end
+
+    it 'clamps values below 0.0 to 0.0' do
+      expect(described_module.label_for(:MAGNITUDE_LABELS, -0.5)).not_to eq(:unknown)
+    end
+  end
+end