lex-agentic-defense 0.1.0

data/lib/legion/extensions/agentic/defense/phantom/helpers/phantom_limb.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Defense
+        module Phantom
+          module Helpers
+            class PhantomLimb
+              ADAPT_DECAY_MULTIPLIER = 2.5
+
+              attr_reader :id, :capability_name, :capability_domain, :removed_at,
+                          :activation_count, :last_triggered, :trigger_history
+
+              def initialize(capability_name:, capability_domain:)
+                @id                 = SecureRandom.uuid
+                @capability_name    = capability_name
+                @capability_domain  = capability_domain
+                @removed_at         = Time.now.utc
+                @intensity          = Constants::INITIAL_INTENSITY
+                @activation_count   = 0
+                @last_triggered     = nil
+                @trigger_history    = []
+              end
+
+              def intensity
+                @intensity.round(10)
+              end
+
+              def state
+                Constants.state_for(@intensity)
+              end
+
+              def trigger!(stimulus)
+                return false if resolved?
+
+                @activation_count += 1
+                prev_triggered = @last_triggered
+                @last_triggered = Time.now.utc
+                signal = PhantomSignal.new(
+                  phantom_limb_id:      @id,
+                  stimulus:             stimulus,
+                  trigger_type:         classify_trigger(stimulus, prev_triggered),
+                  intensity_at_trigger: @intensity
+                )
+                @trigger_history << signal
+                @trigger_history.shift while @trigger_history.size > 50
+                boost = (@intensity * 0.05).clamp(0.0, 0.1)
+                @intensity = (@intensity + boost).clamp(Constants::MIN_INTENSITY, 1.0)
+                signal
+              end
+
+              def decay!
+                return if resolved?
+
+                @intensity = (@intensity - Constants::INTENSITY_DECAY).clamp(Constants::MIN_INTENSITY, 1.0)
+              end
+
+              def adapt!
+                return if resolved?
+
+                accelerated = Constants::INTENSITY_DECAY * ADAPT_DECAY_MULTIPLIER
+                @intensity  = (@intensity - accelerated).clamp(Constants::MIN_INTENSITY, 1.0)
+              end
+
+              def resolved?
+                @intensity <= Constants::MIN_INTENSITY
+              end
+
+              def to_h
+                {
+                  id:                @id,
+                  capability_name:   @capability_name,
+                  capability_domain: @capability_domain,
+                  removed_at:        @removed_at,
+                  intensity:         intensity,
+                  activation_count:  @activation_count,
+                  last_triggered:    @last_triggered,
+                  state:             state,
+                  resolved:          resolved?
+                }
+              end
+
+              private
+
+              def classify_trigger(stimulus, prev_triggered)
+                return :stimulus_match if stimulus.is_a?(String) && stimulus.include?(@capability_name.to_s)
+
+                return :temporal_pattern if prev_triggered && (Time.now.utc - prev_triggered) < 60
+
+                return :habitual if @activation_count > 10
+
+                :contextual_association
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/defense/phantom/helpers/phantom_signal.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Defense
+        module Phantom
+          module Helpers
+            class PhantomSignal
+              attr_reader :id, :phantom_limb_id, :stimulus, :trigger_type,
+                          :intensity_at_trigger, :timestamp
+
+              def initialize(phantom_limb_id:, stimulus:, trigger_type:, intensity_at_trigger:)
+                @id                  = SecureRandom.uuid
+                @phantom_limb_id     = phantom_limb_id
+                @stimulus            = stimulus
+                @trigger_type        = trigger_type
+                @intensity_at_trigger = intensity_at_trigger.clamp(0.0, 1.0)
+                @timestamp = Time.now.utc
+              end
+
+              def to_h
+                {
+                  id:                   @id,
+                  phantom_limb_id:      @phantom_limb_id,
+                  stimulus:             @stimulus,
+                  trigger_type:         @trigger_type,
+                  intensity_at_trigger: @intensity_at_trigger.round(10),
+                  timestamp:            @timestamp
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/defense/phantom/runners/cognitive_phantom.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Defense
+        module Phantom
+          module Runners
+            module CognitivePhantom
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def register_removal(capability_name:, capability_domain: :general, engine: nil, **)
+                raise ArgumentError, 'capability_name is required' if capability_name.nil? || capability_name.to_s.strip.empty?
+
+                eng  = engine || phantom_engine
+                limb = eng.register_removal(capability_name: capability_name, capability_domain: capability_domain)
+                return { success: false, error: 'MAX_PHANTOMS limit reached' } unless limb
+
+                Legion::Logging.debug "[cognitive_phantom] register_removal capability=#{capability_name}"
+                { success: true, phantom_id: limb.id, capability_name: capability_name, state: limb.state, intensity: limb.intensity }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def process_stimulus(stimulus:, domain: :general, engine: nil, **)
+                raise ArgumentError, 'stimulus is required' if stimulus.nil?
+
+                eng    = engine || phantom_engine
+                fired  = eng.process_stimulus(stimulus: stimulus, domain: domain)
+                Legion::Logging.debug "[cognitive_phantom] process_stimulus domain=#{domain} fired=#{fired.size}"
+                {
+                  success:     true,
+                  fired_count: fired.size,
+                  signals:     fired.map(&:to_h),
+                  domain:      domain
+                }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def acknowledge_phantom(phantom_id:, engine: nil, **)
+                raise ArgumentError, 'phantom_id is required' if phantom_id.nil? || phantom_id.to_s.strip.empty?
+
+                eng    = engine || phantom_engine
+                result = eng.acknowledge(phantom_id: phantom_id)
+                Legion::Logging.debug "[cognitive_phantom] acknowledge phantom_id=#{phantom_id[0..7]}"
+                result.merge(success: result[:acknowledged])
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def phantom_status(engine: nil, **)
+                eng    = engine || phantom_engine
+                report = eng.phantom_activity_report
+                Legion::Logging.debug "[cognitive_phantom] phantom_status total=#{report[:total]} active=#{report[:active]}"
+                { success: true, **report }
+              end
+
+              def decay_all(engine: nil, **)
+                eng = engine || phantom_engine
+                resolved_count = eng.decay_all!
+                report = eng.phantom_activity_report
+                Legion::Logging.debug "[cognitive_phantom] decay_all resolved=#{resolved_count}"
+                { success: true, resolved_this_cycle: resolved_count, **report }
+              end
+
+              private
+
+              def phantom_engine
+                @phantom_engine ||= Helpers::PhantomEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'legion/extensions/agentic/defense/phantom/version'
+require 'legion/extensions/agentic/defense/phantom/helpers/constants'
+require 'legion/extensions/agentic/defense/phantom/helpers/phantom_signal'
+require 'legion/extensions/agentic/defense/phantom/helpers/phantom_limb'
+require 'legion/extensions/agentic/defense/phantom/helpers/phantom_engine'
+require 'legion/extensions/agentic/defense/phantom/runners/cognitive_phantom'
+require 'legion/extensions/agentic/defense/phantom/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Defense
+        module Phantom
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Defense
+        module Quicksand
+          class Client
+            include Runners::CognitiveQuicksand
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Defense
+        module Quicksand
+          module Helpers
+            module Constants
+              TRAP_TYPES = %i[overthinking rumination analysis_paralysis
+                              perfectionism indecision].freeze
+
+              STRUGGLE_MODES = %i[thrash freeze sink float escape].freeze
+
+              MAX_TRAPS     = 200
+              MAX_PITS      = 50
+              SINK_RATE     = 0.08
+              STRUGGLE_PENALTY = 0.12
+              ESCAPE_THRESHOLD = 0.3
+              CALM_RATE = 0.03
+
+              DEPTH_LABELS = [
+                [(0.8..),      :submerged],
+                [(0.6...0.8),  :chest_deep],
+                [(0.4...0.6),  :waist_deep],
+                [(0.2...0.4),  :ankle_deep],
+                [(..0.2),      :surface]
+              ].freeze
+
+              VISCOSITY_LABELS = [
+                [(0.8..),      :concrete],
+                [(0.6...0.8),  :thick],
+                [(0.4...0.6),  :moderate],
+                [(0.2...0.4),  :thin],
+                [(..0.2),      :dry]
+              ].freeze
+
+              def self.label_for(table, value)
+                table.each { |range, label| return label if range.cover?(value) }
+                table.last.last
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/defense/quicksand/helpers/pit.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Defense
+        module Quicksand
+          module Helpers
+            class Pit
+              attr_reader :id, :trap_ids, :created_at
+              attr_accessor :saturation, :danger_level
+
+              def initialize(saturation: nil, danger_level: nil)
+                @id           = SecureRandom.uuid
+                @saturation   = (saturation || 0.5).to_f.clamp(0.0, 1.0).round(10)
+                @danger_level = (danger_level || 0.3).to_f.clamp(0.0, 1.0).round(10)
+                @trap_ids     = []
+                @created_at   = Time.now.utc
+              end
+
+              def add_trap(trap_id)
+                return :already_present if @trap_ids.include?(trap_id)
+
+                @trap_ids << trap_id
+                recalculate_danger!
+                :added
+              end
+
+              def remove_trap(trap_id)
+                return :not_found unless @trap_ids.include?(trap_id)
+
+                @trap_ids.delete(trap_id)
+                recalculate_danger!
+                :removed
+              end
+
+              def saturate!(rate: 0.1)
+                @saturation = (@saturation + rate.abs).clamp(0.0, 1.0).round(10)
+              end
+
+              def drain!(rate: 0.1)
+                @saturation = (@saturation - rate.abs).clamp(0.0, 1.0).round(10)
+                recalculate_danger!
+              end
+
+              def deadly?
+                @danger_level >= 0.8
+              end
+
+              def safe?
+                @danger_level < 0.2
+              end
+
+              def trap_count
+                @trap_ids.size
+              end
+
+              def to_h
+                {
+                  id:           @id,
+                  saturation:   @saturation,
+                  danger_level: @danger_level,
+                  trap_count:   trap_count,
+                  deadly:       deadly?,
+                  safe:         safe?,
+                  created_at:   @created_at
+                }
+              end
+
+              private
+
+              def recalculate_danger!
+                trap_factor = (@trap_ids.size / 10.0).clamp(0.0, 1.0)
+                @danger_level = ((trap_factor + @saturation) / 2.0).clamp(0.0, 1.0).round(10)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/defense/quicksand/helpers/quicksand_engine.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Defense
+        module Quicksand
+          module Helpers
+            class QuicksandEngine
+              def initialize
+                @traps = {}
+                @pits  = {}
+              end
+
+              def create_trap(trap_type:, domain:, content:, depth: nil, viscosity: nil)
+                raise ArgumentError, 'trap limit reached' if @traps.size >= Constants::MAX_TRAPS
+
+                t = Trap.new(trap_type: trap_type, domain: domain, content: content,
+                             depth: depth, viscosity: viscosity)
+                @traps[t.id] = t
+                t
+              end
+
+              def create_pit(saturation: nil, danger_level: nil)
+                raise ArgumentError, 'pit limit reached' if @pits.size >= Constants::MAX_PITS
+
+                p = Pit.new(saturation: saturation, danger_level: danger_level)
+                @pits[p.id] = p
+                p
+              end
+
+              def sink_trap(trap_id:, rate: Constants::SINK_RATE)
+                trap = fetch_trap(trap_id)
+                trap.sink!(rate: rate)
+                trap
+              end
+
+              def struggle(trap_id:)
+                trap = fetch_trap(trap_id)
+                trap.struggle!
+                { trap: trap, depth: trap.depth, struggle_count: trap.struggle_count }
+              end
+
+              def calm(trap_id:, rate: Constants::CALM_RATE)
+                trap = fetch_trap(trap_id)
+                trap.calm!(rate: rate)
+                trap
+              end
+
+              def attempt_escape(trap_id:)
+                trap   = fetch_trap(trap_id)
+                result = trap.escape!
+                { trap: trap, result: result }
+              end
+
+              def add_trap_to_pit(trap_id:, pit_id:)
+                fetch_trap(trap_id)
+                pit = fetch_pit(pit_id)
+                pit.add_trap(trap_id)
+              end
+
+              def sink_all!
+                @traps.each_value(&:sink!)
+              end
+
+              def calm_all!
+                @traps.each_value(&:calm!)
+              end
+
+              def traps_by_type
+                counts = Constants::TRAP_TYPES.to_h { |t| [t, 0] }
+                @traps.each_value { |t| counts[t.trap_type] += 1 }
+                counts
+              end
+
+              def deepest(limit: 5)
+                @traps.values.sort_by { |t| -t.depth }.first(limit)
+              end
+
+              def shallowest(limit: 5)
+                @traps.values.sort_by(&:depth).first(limit)
+              end
+
+              def submerged_traps
+                @traps.values.select(&:submerged?)
+              end
+
+              def stuck_traps
+                @traps.values.select(&:stuck?)
+              end
+
+              def deadliest_pits(limit: 5)
+                @pits.values.sort_by { |p| -p.danger_level }.first(limit)
+              end
+
+              def avg_depth
+                return 0.0 if @traps.empty?
+
+                (@traps.values.sum(&:depth) / @traps.size).round(10)
+              end
+
+              def quicksand_report
+                {
+                  total_traps: @traps.size,
+                  total_pits:  @pits.size,
+                  by_type:     traps_by_type,
+                  submerged:   submerged_traps.size,
+                  stuck:       stuck_traps.size,
+                  avg_depth:   avg_depth,
+                  deadly_pits: @pits.values.count(&:deadly?)
+                }
+              end
+
+              def all_traps
+                @traps.values
+              end
+
+              def all_pits
+                @pits.values
+              end
+
+              private
+
+              def fetch_trap(id)
+                @traps.fetch(id) { raise ArgumentError, "trap not found: #{id}" }
+              end
+
+              def fetch_pit(id)
+                @pits.fetch(id) { raise ArgumentError, "pit not found: #{id}" }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/defense/quicksand/helpers/trap.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Defense
+        module Quicksand
+          module Helpers
+            class Trap
+              attr_reader :id, :trap_type, :domain, :content,
+                          :struggle_count, :created_at
+              attr_accessor :depth, :viscosity
+
+              def initialize(trap_type:, domain:, content:,
+                             depth: nil, viscosity: nil)
+                validate_trap_type!(trap_type)
+                @id             = SecureRandom.uuid
+                @trap_type      = trap_type.to_sym
+                @domain         = domain.to_sym
+                @content        = content.to_s
+                @depth          = (depth || 0.3).to_f.clamp(0.0, 1.0).round(10)
+                @viscosity      = (viscosity || 0.5).to_f.clamp(0.0, 1.0).round(10)
+                @struggle_count = 0
+                @created_at     = Time.now.utc
+              end
+
+              def sink!(rate: Constants::SINK_RATE)
+                @depth = (@depth + rate.abs).clamp(0.0, 1.0).round(10)
+              end
+
+              def struggle!
+                @struggle_count += 1
+                penalty = Constants::STRUGGLE_PENALTY * @viscosity
+                @depth = (@depth + penalty).clamp(0.0, 1.0).round(10)
+              end
+
+              def calm!(rate: Constants::CALM_RATE)
+                @depth = (@depth - rate.abs).clamp(0.0, 1.0).round(10)
+              end
+
+              def escape!
+                return :too_deep if @depth > (1.0 - Constants::ESCAPE_THRESHOLD)
+
+                @depth = 0.0
+                :escaped
+              end
+
+              def submerged?
+                @depth >= 0.8
+              end
+
+              def surface?
+                @depth < 0.2
+              end
+
+              def stuck?
+                @depth >= 0.5 && @viscosity >= 0.5
+              end
+
+              def depth_label
+                Constants.label_for(Constants::DEPTH_LABELS, @depth)
+              end
+
+              def viscosity_label
+                Constants.label_for(Constants::VISCOSITY_LABELS, @viscosity)
+              end
+
+              def to_h
+                {
+                  id:              @id,
+                  trap_type:       @trap_type,
+                  domain:          @domain,
+                  content:         @content,
+                  depth:           @depth,
+                  viscosity:       @viscosity,
+                  depth_label:     depth_label,
+                  viscosity_label: viscosity_label,
+                  struggle_count:  @struggle_count,
+                  submerged:       submerged?,
+                  surface:         surface?,
+                  stuck:           stuck?,
+                  created_at:      @created_at
+                }
+              end
+
+              private
+
+              def validate_trap_type!(val)
+                return if Constants::TRAP_TYPES.include?(val.to_sym)
+
+                raise ArgumentError,
+                      "unknown trap type: #{val.inspect}; " \
+                      "must be one of #{Constants::TRAP_TYPES.inspect}"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end