lex-agentic-defense 0.1.0

data/lib/legion/extensions/agentic/defense/quicksilver.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'legion/extensions/agentic/defense/quicksilver/version'
+require 'legion/extensions/agentic/defense/quicksilver/helpers/constants'
+require 'legion/extensions/agentic/defense/quicksilver/helpers/droplet'
+require 'legion/extensions/agentic/defense/quicksilver/helpers/pool'
+require 'legion/extensions/agentic/defense/quicksilver/helpers/quicksilver_engine'
+require 'legion/extensions/agentic/defense/quicksilver/runners/cognitive_quicksilver'
+require 'legion/extensions/agentic/defense/quicksilver/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Defense
+        module Quicksilver
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/defense/version.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Defense
+        VERSION = '0.1.0'
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/defense/whirlpool/client.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Defense
+        module Whirlpool
+          class Client
+            include Runners::CognitiveWhirlpool
+
+            attr_reader :engine
+
+            def initialize
+              @engine = Helpers::WhirlpoolEngine.new
+            end
+
+            def create_vortex(vortex_type:, angular_velocity: 0.5, depth: 0.0, capture_radius: 0.5, **)
+              super(
+                vortex_type:      vortex_type,
+                angular_velocity: angular_velocity,
+                depth:            depth,
+                capture_radius:   capture_radius,
+                engine:           @engine
+              )
+            end
+
+            def inject_thought(vortex_id:, content:, domain: :general, distance_from_core: 1.0, **)
+              super(
+                vortex_id:          vortex_id,
+                content:            content,
+                domain:             domain,
+                distance_from_core: distance_from_core,
+                engine:             @engine
+              )
+            end
+
+            def tick_all(spiral_rate: nil, **)
+              super(spiral_rate: spiral_rate, engine: @engine)
+            end
+
+            def dissipate_all(rate: Helpers::Constants::VELOCITY_DECAY, **)
+              super(rate: rate, engine: @engine)
+            end
+
+            def vortex_report(**)
+              super(engine: @engine)
+            end
+
+            def deepest_vortices(limit: 3, **)
+              super(limit: limit, engine: @engine)
+            end
+
+            def remove_vortex(vortex_id:, **)
+              super(vortex_id: vortex_id, engine: @engine)
+            end
+
+            def clear_engine(**)
+              super(engine: @engine)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/defense/whirlpool/helpers/captured_thought.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Defense
+        module Whirlpool
+          module Helpers
+            class CapturedThought
+              attr_reader :thought_id, :content, :domain, :spiral_depth, :distance_from_core, :captured_at
+
+              ESCAPE_DISTANCE = 1.0
+              CORE_DISTANCE   = 0.05
+
+              def initialize(content:, domain: :general, spiral_depth: 0.0, distance_from_core: 1.0)
+                @thought_id        = SecureRandom.uuid
+                @content           = content
+                @domain            = domain
+                @spiral_depth      = spiral_depth.clamp(0.0, Constants::DEPTH_MAX)
+                @distance_from_core = distance_from_core.clamp(0.0, Constants::CAPTURE_RADIUS_MAX)
+                @captured_at       = Time.now.utc
+                @escaped           = false
+              end
+
+              def spiral!(rate: Constants::SPIRAL_RATE_DEFAULT)
+                return if @escaped
+
+                @spiral_depth       = (@spiral_depth + rate).clamp(0.0, Constants::DEPTH_MAX)
+                @distance_from_core = (@distance_from_core - rate).clamp(0.0, Constants::CAPTURE_RADIUS_MAX)
+              end
+
+              def at_core?
+                @distance_from_core <= CORE_DISTANCE
+              end
+
+              def escaped?
+                @escaped
+              end
+
+              def escape!
+                @escaped = true
+              end
+
+              def depth_label
+                Constants::DEPTH_LABELS.find { |entry| entry[:range].cover?(@spiral_depth) }&.fetch(:label, :surface) || :surface
+              end
+
+              def to_h
+                {
+                  thought_id:         @thought_id,
+                  content:            @content,
+                  domain:             @domain,
+                  spiral_depth:       @spiral_depth.round(10),
+                  distance_from_core: @distance_from_core.round(10),
+                  depth_label:        depth_label,
+                  at_core:            at_core?,
+                  escaped:            @escaped,
+                  captured_at:        @captured_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/defense/whirlpool/helpers/constants.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Defense
+        module Whirlpool
+          module Helpers
+            module Constants
+              VORTEX_TYPES = %i[
+                analytical
+                creative
+                emotional
+                procedural
+                associative
+              ].freeze
+
+              MAX_VORTICES = 12
+
+              VELOCITY_DECAY = 0.05
+
+              DEPTH_LABELS = [
+                { range: (0.0...0.2),   label: :surface },
+                { range: (0.2...0.4),   label: :shallow },
+                { range: (0.4...0.6),   label: :mid },
+                { range: (0.6...0.8),   label: :deep },
+                { range: (0.8..1.0),    label: :insight_core }
+              ].freeze
+
+              CAPTURE_DECAY_RATE     = 0.03
+              ANGULAR_VELOCITY_MIN   = 0.1
+              ANGULAR_VELOCITY_MAX   = 1.0
+              DEPTH_MAX              = 1.0
+              CAPTURE_RADIUS_MAX     = 1.0
+              SPIRAL_RATE_DEFAULT    = 0.08
+              DISSIPATION_THRESHOLD  = 0.05
+              POWERFUL_VELOCITY      = 0.7
+              CALM_VELOCITY          = 0.2
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/defense/whirlpool/helpers/vortex.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Defense
+        module Whirlpool
+          module Helpers
+            class Vortex
+              attr_reader :vortex_id, :vortex_type, :angular_velocity, :depth, :capture_radius, :captured_thoughts,
+                          :created_at
+
+              def initialize(vortex_type:, angular_velocity: 0.5, depth: 0.0, capture_radius: 0.5)
+                raise ArgumentError, "unknown vortex_type: #{vortex_type}" unless Constants::VORTEX_TYPES.include?(vortex_type)
+
+                @vortex_id        = SecureRandom.uuid
+                @vortex_type      = vortex_type
+                @angular_velocity = angular_velocity.clamp(Constants::ANGULAR_VELOCITY_MIN, Constants::ANGULAR_VELOCITY_MAX)
+                @depth            = depth.clamp(0.0, Constants::DEPTH_MAX)
+                @capture_radius   = capture_radius.clamp(0.0, Constants::CAPTURE_RADIUS_MAX)
+                @captured_thoughts = []
+                @created_at = Time.now.utc
+              end
+
+              def capture!(thought)
+                raise ArgumentError, 'thought must be a CapturedThought' unless thought.is_a?(CapturedThought)
+
+                @captured_thoughts << thought
+                thought
+              end
+
+              def tick!(spiral_rate: nil)
+                rate = spiral_rate || (Constants::SPIRAL_RATE_DEFAULT * @angular_velocity)
+                @captured_thoughts.each { |t| t.spiral!(rate: rate) }
+                @depth = (@depth + (rate * 0.5)).clamp(0.0, Constants::DEPTH_MAX)
+                self
+              end
+
+              def dissipate!(rate: Constants::VELOCITY_DECAY)
+                @angular_velocity = (@angular_velocity - rate).clamp(0.0, Constants::ANGULAR_VELOCITY_MAX)
+                @capture_radius   = (@capture_radius - (rate * 0.5)).clamp(0.0, Constants::CAPTURE_RADIUS_MAX)
+                self
+              end
+
+              def powerful?
+                @angular_velocity >= Constants::POWERFUL_VELOCITY
+              end
+
+              def calm?
+                @angular_velocity <= Constants::CALM_VELOCITY
+              end
+
+              def dissipated?
+                @angular_velocity <= Constants::DISSIPATION_THRESHOLD
+              end
+
+              def thoughts_at_core
+                @captured_thoughts.select(&:at_core?)
+              end
+
+              def active_thoughts
+                @captured_thoughts.reject(&:escaped?)
+              end
+
+              def depth_label
+                Constants::DEPTH_LABELS.find { |entry| entry[:range].cover?(@depth) }&.fetch(:label, :surface) || :surface
+              end
+
+              def to_h
+                {
+                  vortex_id:        @vortex_id,
+                  vortex_type:      @vortex_type,
+                  angular_velocity: @angular_velocity.round(10),
+                  depth:            @depth.round(10),
+                  capture_radius:   @capture_radius.round(10),
+                  depth_label:      depth_label,
+                  powerful:         powerful?,
+                  calm:             calm?,
+                  dissipated:       dissipated?,
+                  thought_count:    @captured_thoughts.size,
+                  core_count:       thoughts_at_core.size,
+                  created_at:       @created_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/defense/whirlpool/helpers/whirlpool_engine.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Defense
+        module Whirlpool
+          module Helpers
+            class WhirlpoolEngine
+              attr_reader :vortices
+
+              def initialize
+                @vortices = []
+              end
+
+              def create_vortex(vortex_type:, angular_velocity: 0.5, depth: 0.0, capture_radius: 0.5)
+                raise ArgumentError, "MAX_VORTICES (#{Constants::MAX_VORTICES}) reached" if @vortices.size >= Constants::MAX_VORTICES
+
+                vortex = Vortex.new(
+                  vortex_type:      vortex_type,
+                  angular_velocity: angular_velocity,
+                  depth:            depth,
+                  capture_radius:   capture_radius
+                )
+                @vortices << vortex
+                vortex
+              end
+
+              def inject_thought(vortex_id:, content:, domain: :general, distance_from_core: 1.0)
+                vortex = find_vortex(vortex_id)
+                raise ArgumentError, "vortex not found: #{vortex_id}" unless vortex
+
+                thought = CapturedThought.new(
+                  content:            content,
+                  domain:             domain,
+                  distance_from_core: distance_from_core
+                )
+                vortex.capture!(thought)
+                { vortex_id: vortex_id, thought_id: thought.thought_id, domain: domain }
+              end
+
+              def tick_all!(spiral_rate: nil)
+                results = @vortices.map do |v|
+                  v.tick!(spiral_rate: spiral_rate)
+                  { vortex_id: v.vortex_id, depth: v.depth.round(10), active_thoughts: v.active_thoughts.size }
+                end
+                { ticked: @vortices.size, results: results }
+              end
+
+              def dissipate_all!(rate: Constants::VELOCITY_DECAY)
+                before = @vortices.size
+                @vortices.each { |v| v.dissipate!(rate: rate) }
+                @vortices.reject!(&:dissipated?)
+                { dissipated: before - @vortices.size, remaining: @vortices.size }
+              end
+
+              def deepest_vortices(limit: 3)
+                @vortices.sort_by { |v| -v.depth }.first(limit).map(&:to_h)
+              end
+
+              def vortex_report
+                {
+                  total_vortices:   @vortices.size,
+                  powerful_count:   @vortices.count(&:powerful?),
+                  calm_count:       @vortices.count(&:calm?),
+                  total_thoughts:   @vortices.sum { |v| v.captured_thoughts.size },
+                  core_thoughts:    @vortices.sum { |v| v.thoughts_at_core.size },
+                  deepest_vortices: deepest_vortices
+                }
+              end
+
+              def find_vortex(vortex_id)
+                @vortices.find { |v| v.vortex_id == vortex_id }
+              end
+
+              def remove_vortex(vortex_id)
+                before = @vortices.size
+                @vortices.reject! { |v| v.vortex_id == vortex_id }
+                { removed: before - @vortices.size }
+              end
+
+              def clear
+                @vortices = []
+                { cleared: true }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/defense/whirlpool/runners/cognitive_whirlpool.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Defense
+        module Whirlpool
+          module Runners
+            module CognitiveWhirlpool
+              extend self
+
+              include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+              def create_vortex(vortex_type:, angular_velocity: 0.5, depth: 0.0, capture_radius: 0.5,
+                                engine: nil, **)
+                eng = engine || default_engine
+                vortex = eng.create_vortex(
+                  vortex_type:      vortex_type,
+                  angular_velocity: angular_velocity,
+                  depth:            depth,
+                  capture_radius:   capture_radius
+                )
+                Legion::Logging.info "[cognitive_whirlpool] created vortex id=#{vortex.vortex_id} type=#{vortex_type}"
+                { success: true, vortex: vortex.to_h }
+              rescue ArgumentError => e
+                Legion::Logging.warn "[cognitive_whirlpool] create_vortex failed: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def inject_thought(vortex_id:, content:, domain: :general, distance_from_core: 1.0,
+                                 engine: nil, **)
+                eng = engine || default_engine
+                result = eng.inject_thought(
+                  vortex_id:          vortex_id,
+                  content:            content,
+                  domain:             domain,
+                  distance_from_core: distance_from_core
+                )
+                Legion::Logging.info "[cognitive_whirlpool] injected thought=#{result[:thought_id]} into vortex=#{vortex_id}"
+                result.merge(success: true)
+              rescue ArgumentError => e
+                Legion::Logging.warn "[cognitive_whirlpool] inject_thought failed: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def tick_all(spiral_rate: nil, engine: nil, **)
+                eng = engine || default_engine
+                result = eng.tick_all!(spiral_rate: spiral_rate)
+                Legion::Logging.debug "[cognitive_whirlpool] tick: vortices=#{result[:ticked]}"
+                result.merge(success: true)
+              rescue ArgumentError => e
+                Legion::Logging.warn "[cognitive_whirlpool] tick_all failed: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def dissipate_all(rate: Helpers::Constants::VELOCITY_DECAY, engine: nil, **)
+                eng = engine || default_engine
+                result = eng.dissipate_all!(rate: rate)
+                Legion::Logging.debug "[cognitive_whirlpool] dissipate: removed=#{result[:dissipated]} remaining=#{result[:remaining]}"
+                result.merge(success: true)
+              rescue ArgumentError => e
+                Legion::Logging.warn "[cognitive_whirlpool] dissipate_all failed: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def vortex_report(engine: nil, **)
+                eng = engine || default_engine
+                report = eng.vortex_report
+                Legion::Logging.debug "[cognitive_whirlpool] report: vortices=#{report[:total_vortices]}"
+                report.merge(success: true)
+              rescue ArgumentError => e
+                Legion::Logging.warn "[cognitive_whirlpool] vortex_report failed: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def deepest_vortices(limit: 3, engine: nil, **)
+                eng = engine || default_engine
+                vortices = eng.deepest_vortices(limit: limit)
+                Legion::Logging.debug "[cognitive_whirlpool] deepest: count=#{vortices.size}"
+                { success: true, vortices: vortices }
+              rescue ArgumentError => e
+                Legion::Logging.warn "[cognitive_whirlpool] deepest_vortices failed: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def remove_vortex(vortex_id:, engine: nil, **)
+                eng = engine || default_engine
+                result = eng.remove_vortex(vortex_id)
+                Legion::Logging.debug "[cognitive_whirlpool] removed vortex=#{vortex_id}"
+                result.merge(success: true)
+              rescue ArgumentError => e
+                Legion::Logging.warn "[cognitive_whirlpool] remove_vortex failed: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def clear_engine(engine: nil, **)
+                eng = engine || default_engine
+                result = eng.clear
+                Legion::Logging.info '[cognitive_whirlpool] engine cleared'
+                result.merge(success: true)
+              rescue ArgumentError => e
+                Legion::Logging.warn "[cognitive_whirlpool] clear_engine failed: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              private
+
+              def default_engine
+                @default_engine ||= Helpers::WhirlpoolEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/defense/whirlpool/version.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Defense
+        module Whirlpool
+          VERSION = '0.1.0'
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/defense/whirlpool.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+require_relative 'whirlpool/version'
+require_relative 'whirlpool/helpers/constants'
+require_relative 'whirlpool/helpers/captured_thought'
+require_relative 'whirlpool/helpers/vortex'
+require_relative 'whirlpool/helpers/whirlpool_engine'
+require_relative 'whirlpool/runners/cognitive_whirlpool'
+require_relative 'whirlpool/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Defense
+        module Whirlpool
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/defense.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative 'defense/version'
+require_relative 'defense/immune_response'
+require_relative 'defense/immunology'
+require_relative 'defense/erosion'
+require_relative 'defense/friction'
+require_relative 'defense/quicksand'
+require_relative 'defense/quicksilver'
+require_relative 'defense/phantom'
+require_relative 'defense/epistemic_vigilance'
+require_relative 'defense/bias'
+require_relative 'defense/confabulation'
+require_relative 'defense/dissonance'
+require_relative 'defense/error_monitoring'
+require_relative 'defense/extinction'
+require_relative 'defense/avalanche'
+require_relative 'defense/whirlpool'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Defense
+        extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+
+        def remote_invocable?
+          false
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Defense::Avalanche::Client do
+  subject(:client) { described_class.new }
+
+  describe '#initialize' do
+    it 'creates an AvalancheEngine by default' do
+      expect(client.engine).to be_a(Legion::Extensions::Agentic::Defense::Avalanche::Helpers::AvalancheEngine)
+    end
+
+    it 'accepts an injected engine' do
+      custom_engine = Legion::Extensions::Agentic::Defense::Avalanche::Helpers::AvalancheEngine.new
+      c = described_class.new(engine: custom_engine)
+      expect(c.engine).to be(custom_engine)
+    end
+  end
+
+  describe '#create_snowpack' do
+    it 'creates a snowpack via the client' do
+      result = client.create_snowpack(snowpack_type: :ideas, domain: :creativity, content: 'spark')
+      expect(result[:success]).to be(true)
+    end
+
+    it 'persists the snowpack in the engine' do
+      result = client.create_snowpack(snowpack_type: :emotions, domain: :fear, content: 'dread')
+      expect(client.engine.snowpacks).to have_key(result[:snowpack_id])
+    end
+  end
+
+  describe '#trigger' do
+    let(:pack_id) do
+      client.create_snowpack(
+        snowpack_type: :impulses, domain: :action, content: 'urgent impulse', stability: 0.05
+      )[:snowpack_id]
+    end
+
+    it 'triggers a cascade for unstable snowpack' do
+      result = client.trigger(snowpack_id: pack_id, force: 0.8)
+      expect(result[:success]).to be(true)
+      expect(result[:triggered]).to be(true)
+    end
+
+    it 'returns failure for unknown id' do
+      result = client.trigger(snowpack_id: 'nonexistent', force: 0.5)
+      expect(result[:success]).to be(false)
+    end
+  end
+
+  describe '#accumulate' do
+    before { client.create_snowpack(snowpack_type: :associations, domain: :network, content: 'linked nodes') }
+
+    it 'accumulates all snowpacks' do
+      result = client.accumulate
+      expect(result[:success]).to be(true)
+      expect(result[:packs_accumulated]).to eq(1)
+    end
+  end
+
+  describe '#list_snowpacks' do
+    it 'returns empty list on fresh client' do
+      result = client.list_snowpacks
+      expect(result[:success]).to be(true)
+      expect(result[:count]).to eq(0)
+    end
+
+    it 'lists created snowpacks' do
+      client.create_snowpack(snowpack_type: :ideas, domain: :test, content: 'a')
+      client.create_snowpack(snowpack_type: :ideas, domain: :test, content: 'b')
+      result = client.list_snowpacks
+      expect(result[:count]).to eq(2)
+    end
+  end
+
+  describe '#terrain_status' do
+    it 'returns success with stats' do
+      result = client.terrain_status
+      expect(result[:success]).to be(true)
+      expect(result[:total_snowpacks]).to eq(0)
+    end
+
+    it 'reflects created snowpacks' do
+      client.create_snowpack(snowpack_type: :memories, domain: :past, content: 'childhood')
+      result = client.terrain_status
+      expect(result[:total_snowpacks]).to eq(1)
+    end
+  end
+
+  describe 'client isolation' do
+    it 'two clients do not share state' do
+      c1 = described_class.new
+      c2 = described_class.new
+      c1.create_snowpack(snowpack_type: :ideas, domain: :test, content: 'isolated idea')
+      expect(c2.terrain_status[:total_snowpacks]).to eq(0)
+    end
+  end
+end