lex-agentic-defense 0.1.0

data/lib/legion/extensions/agentic/defense/quicksand/runners/cognitive_quicksand.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Defense
+        module Quicksand
+          module Runners
+            module CognitiveQuicksand
+              extend self
+
+              def create_trap(trap_type:, domain:, content:,
+                              depth: nil, viscosity: nil, engine: nil, **)
+                eng = resolve_engine(engine)
+                t   = eng.create_trap(trap_type: trap_type, domain: domain, content: content,
+                                      depth: depth, viscosity: viscosity)
+                { success: true, trap: t.to_h }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def create_pit(saturation: nil, danger_level: nil, engine: nil, **)
+                eng = resolve_engine(engine)
+                p   = eng.create_pit(saturation: saturation, danger_level: danger_level)
+                { success: true, pit: p.to_h }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def struggle(trap_id:, engine: nil, **)
+                eng    = resolve_engine(engine)
+                result = eng.struggle(trap_id: trap_id)
+                { success: true, trap: result[:trap].to_h,
+                  depth: result[:depth], struggle_count: result[:struggle_count] }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def calm_down(trap_id:, rate: nil, engine: nil, **)
+                eng  = resolve_engine(engine)
+                trap = eng.calm(trap_id: trap_id, rate: rate || Helpers::Constants::CALM_RATE)
+                { success: true, trap: trap.to_h }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def attempt_escape(trap_id:, engine: nil, **)
+                eng    = resolve_engine(engine)
+                result = eng.attempt_escape(trap_id: trap_id)
+                { success: true, trap: result[:trap].to_h, result: result[:result] }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def list_traps(engine: nil, trap_type: nil, **)
+                eng     = resolve_engine(engine)
+                results = eng.all_traps
+                results = results.select { |t| t.trap_type == trap_type.to_sym } if trap_type
+                { success: true, traps: results.map(&:to_h), count: results.size }
+              end
+
+              def quicksand_status(engine: nil, **)
+                eng = resolve_engine(engine)
+                { success: true, report: eng.quicksand_report }
+              end
+
+              include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+              private
+
+              def resolve_engine(engine)
+                engine || default_engine
+              end
+
+              def default_engine
+                @default_engine ||= Helpers::QuicksandEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+require_relative 'quicksand/version'
+require_relative 'quicksand/helpers/constants'
+require_relative 'quicksand/helpers/trap'
+require_relative 'quicksand/helpers/pit'
+require_relative 'quicksand/helpers/quicksand_engine'
+require_relative 'quicksand/runners/cognitive_quicksand'
+require_relative 'quicksand/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Defense
+        module Quicksand
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+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'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Defense
+        module Quicksilver
+          class Client
+            include Runners::CognitiveQuicksilver
+
+            def initialize
+              @quicksilver_engine = Helpers::QuicksilverEngine.new
+            end
+
+            private
+
+            attr_reader :quicksilver_engine
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Defense
+        module Quicksilver
+          module Helpers
+            module Constants
+              FORM_TYPES    = %i[liquid droplet bead stream pool].freeze
+              SURFACE_TYPES = %i[glass metal wood stone fabric].freeze
+
+              MAX_DROPLETS = 500
+              MAX_POOLS    = 50
+
+              FLUIDITY_BASE    = 0.8
+              SURFACE_TENSION  = 0.3
+              EVAPORATION_RATE = 0.02
+              COALESCENCE_BONUS = 0.1
+
+              COHESION_LABELS = [
+                { range: (0.8..1.0), label: :unified },
+                { range: (0.6...0.8), label: :cohesive },
+                { range: (0.4...0.6), label: :scattered },
+                { range: (0.2...0.4), label: :dispersed },
+                { range: (0.0...0.2), label: :atomized }
+              ].freeze
+
+              FLUIDITY_LABELS = [
+                { range: (0.8..1.0), label: :liquid },
+                { range: (0.6...0.8), label: :flowing },
+                { range: (0.4...0.6), label: :viscous },
+                { range: (0.2...0.4), label: :sluggish },
+                { range: (0.0...0.2), label: :solid }
+              ].freeze
+
+              module_function
+
+              def label_for(table, value)
+                clamped = value.clamp(0.0, 1.0)
+                entry = table.find { |row| row[:range].include?(clamped) }
+                entry ? entry[:label] : table.last[:label]
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Defense
+        module Quicksilver
+          module Helpers
+            class Droplet
+              attr_reader :id, :form, :content, :mass, :fluidity, :surface, :captured, :created_at
+
+              FORM_FLUIDITY = {
+                liquid:  0.9,
+                droplet: 0.8,
+                bead:    0.7,
+                stream:  0.6,
+                pool:    0.3
+              }.freeze
+
+              def initialize(form:, content:, mass: 0.3, fluidity: Constants::FLUIDITY_BASE, surface: :glass)
+                raise ArgumentError, "invalid form: #{form}" unless Constants::FORM_TYPES.include?(form)
+                raise ArgumentError, "invalid surface: #{surface}" unless Constants::SURFACE_TYPES.include?(surface)
+
+                @id         = SecureRandom.uuid
+                @form       = form
+                @content    = content
+                @mass       = mass.clamp(0.0, 1.0)
+                @fluidity   = fluidity.clamp(0.0, 1.0)
+                @surface    = surface
+                @captured   = false
+                @created_at = Time.now.utc
+              end
+
+              def shift_form!(new_form)
+                raise ArgumentError, "invalid form: #{new_form}" unless Constants::FORM_TYPES.include?(new_form)
+
+                @form     = new_form
+                @fluidity = FORM_FLUIDITY.fetch(new_form, Constants::FLUIDITY_BASE).clamp(0.0, 1.0)
+                self
+              end
+
+              def merge!(other_droplet)
+                @mass     = (@mass + other_droplet.mass + Constants::COALESCENCE_BONUS).clamp(0.0, 1.0)
+                @form     = @mass >= other_droplet.mass ? @form : other_droplet.form
+                @fluidity = ((@fluidity + other_droplet.fluidity) / 2.0).round(10)
+                self
+              end
+
+              def split!
+                return nil if @mass <= 0.2
+
+                half_mass = (@mass / 2.0).round(10)
+                @mass     = half_mass
+
+                self.class.new(
+                  form:     @form,
+                  content:  @content,
+                  mass:     half_mass,
+                  fluidity: @fluidity,
+                  surface:  @surface
+                )
+              end
+
+              def capture!
+                @captured  = true
+                @fluidity  = (@fluidity / 2.0).round(10)
+                self
+              end
+
+              def release!
+                @captured  = false
+                @fluidity  = (@fluidity * 2.0).clamp(0.0, 1.0)
+                self
+              end
+
+              def evaporate!
+                @mass = (@mass - Constants::EVAPORATION_RATE).clamp(0.0, 1.0).round(10)
+                self
+              end
+
+              def elusive?
+                @fluidity >= 0.7 && !@captured
+              end
+
+              def stable?
+                @fluidity < 0.4 || @captured
+              end
+
+              def vanishing?
+                @mass < 0.1
+              end
+
+              def cohesion_label
+                Constants.label_for(Constants::COHESION_LABELS, @mass)
+              end
+
+              def fluidity_label
+                Constants.label_for(Constants::FLUIDITY_LABELS, @fluidity)
+              end
+
+              def to_h
+                {
+                  id:           @id,
+                  form:         @form,
+                  content:      @content,
+                  mass:         @mass.round(10),
+                  fluidity:     @fluidity.round(10),
+                  surface:      @surface,
+                  captured:     @captured,
+                  elusive:      elusive?,
+                  stable:       stable?,
+                  vanishing:    vanishing?,
+                  cohesion:     cohesion_label,
+                  fluidity_lbl: fluidity_label,
+                  created_at:   @created_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Defense
+        module Quicksilver
+          module Helpers
+            class Pool
+              attr_reader :id, :surface_type, :depth, :droplet_ids, :surface_tension, :created_at
+
+              DEPTH_CHANGE     = 0.05
+              TENSION_DECREASE = 0.1
+              TENSION_INCREASE = 0.05
+
+              def initialize(surface_type:, depth: 0.5, surface_tension: Constants::SURFACE_TENSION)
+                raise ArgumentError, "invalid surface_type: #{surface_type}" unless Constants::SURFACE_TYPES.include?(surface_type)
+
+                @id              = SecureRandom.uuid
+                @surface_type    = surface_type
+                @depth           = depth.clamp(0.0, 1.0)
+                @droplet_ids     = []
+                @surface_tension = surface_tension.clamp(0.0, 1.0)
+                @created_at      = Time.now.utc
+              end
+
+              def add_droplet(droplet_id)
+                @droplet_ids << droplet_id unless @droplet_ids.include?(droplet_id)
+                @depth = (@depth + DEPTH_CHANGE).clamp(0.0, 1.0).round(10)
+                self
+              end
+
+              def remove_droplet(droplet_id)
+                @droplet_ids.delete(droplet_id)
+                @depth = (@depth - DEPTH_CHANGE).clamp(0.0, 1.0).round(10)
+                self
+              end
+
+              def agitate!
+                @surface_tension = (@surface_tension - TENSION_DECREASE).clamp(0.0, 1.0).round(10)
+                released = []
+                @droplet_ids.each do |did|
+                  released << did if rand > @surface_tension
+                end
+                released.each { |did| remove_droplet(did) }
+                released
+              end
+
+              def settle!
+                @surface_tension = (@surface_tension + TENSION_INCREASE).clamp(0.0, 1.0).round(10)
+                self
+              end
+
+              def reflective?
+                @depth >= 0.7 && @surface_tension >= 0.5
+              end
+
+              def shallow?
+                @depth < 0.2
+              end
+
+              def to_h
+                {
+                  id:              @id,
+                  surface_type:    @surface_type,
+                  depth:           @depth.round(10),
+                  droplet_ids:     @droplet_ids.dup,
+                  droplet_count:   @droplet_ids.size,
+                  surface_tension: @surface_tension.round(10),
+                  reflective:      reflective?,
+                  shallow:         shallow?,
+                  created_at:      @created_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Defense
+        module Quicksilver
+          module Helpers
+            class QuicksilverEngine
+              def initialize
+                @droplets = {}
+                @pools    = {}
+              end
+
+              def create_droplet(form:, content:, **)
+                raise ArgumentError, 'droplet limit reached' if @droplets.size >= Constants::MAX_DROPLETS
+
+                droplet = Droplet.new(form: form, content: content, **)
+                @droplets[droplet.id] = droplet
+                droplet
+              end
+
+              def create_pool(surface_type:, **)
+                raise ArgumentError, 'pool limit reached' if @pools.size >= Constants::MAX_POOLS
+
+                pool = Pool.new(surface_type: surface_type, **)
+                @pools[pool.id] = pool
+                pool
+              end
+
+              def shift_form(droplet_id:, new_form:)
+                droplet = fetch_droplet!(droplet_id)
+                droplet.shift_form!(new_form)
+                droplet
+              end
+
+              def merge_droplets(droplet_a_id:, droplet_b_id:)
+                a = fetch_droplet!(droplet_a_id)
+                b = fetch_droplet!(droplet_b_id)
+                a.merge!(b)
+                @droplets.delete(droplet_b_id)
+                a
+              end
+
+              def split_droplet(droplet_id:)
+                droplet = fetch_droplet!(droplet_id)
+                twin = droplet.split!
+                return nil unless twin
+
+                @droplets[twin.id] = twin
+                [droplet, twin]
+              end
+
+              def capture_droplet(droplet_id:)
+                fetch_droplet!(droplet_id).capture!
+              end
+
+              def release_droplet(droplet_id:)
+                fetch_droplet!(droplet_id).release!
+              end
+
+              def add_to_pool(droplet_id:, pool_id:)
+                fetch_droplet!(droplet_id)
+                pool = fetch_pool!(pool_id)
+                pool.add_droplet(droplet_id)
+                pool
+              end
+
+              def agitate_pool(pool_id:)
+                fetch_pool!(pool_id).agitate!
+              end
+
+              def evaporate_all!
+                vanished = []
+                @droplets.each_value(&:evaporate!)
+                @droplets.each { |id, d| vanished << id if d.vanishing? }
+                vanished.each { |id| @droplets.delete(id) }
+                vanished
+              end
+
+              def quicksilver_report
+                droplets = @droplets.values
+                total    = droplets.size
+                {
+                  total_droplets:  total,
+                  total_pools:     @pools.size,
+                  captured_count:  droplets.count(&:captured),
+                  elusive_count:   droplets.count(&:elusive?),
+                  vanishing_count: droplets.count(&:vanishing?),
+                  avg_mass:        avg_metric(droplets, total, :mass),
+                  avg_fluidity:    avg_metric(droplets, total, :fluidity)
+                }
+              end
+
+              def droplets
+                @droplets.values.map(&:to_h)
+              end
+
+              def pools
+                @pools.values.map(&:to_h)
+              end
+
+              private
+
+              def avg_metric(droplets, total, method)
+                return 0.0 if total.zero?
+
+                (droplets.sum(&method) / total.to_f).round(10)
+              end
+
+              def fetch_droplet!(id)
+                @droplets.fetch(id) { raise ArgumentError, "droplet not found: #{id}" }
+              end
+
+              def fetch_pool!(id)
+                @pools.fetch(id) { raise ArgumentError, "pool not found: #{id}" }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Defense
+        module Quicksilver
+          module Runners
+            module CognitiveQuicksilver
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def create_droplet(form: :droplet, content: '', engine: nil, **)
+                raise ArgumentError, "invalid form: #{form}" unless Helpers::Constants::FORM_TYPES.include?(form)
+
+                eng = engine || quicksilver_engine
+                droplet = eng.create_droplet(form: form, content: content.to_s)
+                Legion::Logging.debug "[cognitive_quicksilver] create_droplet id=#{droplet.id} form=#{droplet.form}"
+                { success: true, droplet: droplet.to_h }
+              rescue ArgumentError => e
+                Legion::Logging.debug "[cognitive_quicksilver] create_droplet failed: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def create_pool(surface_type: :glass, engine: nil, **)
+                raise ArgumentError, "invalid surface_type: #{surface_type}" unless Helpers::Constants::SURFACE_TYPES.include?(surface_type)
+
+                eng = engine || quicksilver_engine
+                pool = eng.create_pool(surface_type: surface_type)
+                Legion::Logging.debug "[cognitive_quicksilver] create_pool id=#{pool.id} surface=#{pool.surface_type}"
+                { success: true, pool: pool.to_h }
+              rescue ArgumentError => e
+                Legion::Logging.debug "[cognitive_quicksilver] create_pool failed: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def shift_form(droplet_id:, new_form:, engine: nil, **)
+                raise ArgumentError, "invalid form: #{new_form}" unless Helpers::Constants::FORM_TYPES.include?(new_form)
+
+                eng = engine || quicksilver_engine
+                droplet = eng.shift_form(droplet_id: droplet_id, new_form: new_form)
+                Legion::Logging.debug "[cognitive_quicksilver] shift_form id=#{droplet_id} new_form=#{new_form}"
+                { success: true, droplet: droplet.to_h }
+              rescue ArgumentError => e
+                Legion::Logging.debug "[cognitive_quicksilver] shift_form failed: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def merge(droplet_a_id:, droplet_b_id:, engine: nil, **)
+                eng = engine || quicksilver_engine
+                droplet = eng.merge_droplets(droplet_a_id: droplet_a_id, droplet_b_id: droplet_b_id)
+                Legion::Logging.debug "[cognitive_quicksilver] merge a=#{droplet_a_id} b=#{droplet_b_id} result_mass=#{droplet.mass.round(2)}"
+                { success: true, droplet: droplet.to_h }
+              rescue ArgumentError => e
+                Legion::Logging.debug "[cognitive_quicksilver] merge failed: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def split(droplet_id:, engine: nil, **)
+                eng = engine || quicksilver_engine
+                result = eng.split_droplet(droplet_id: droplet_id)
+                if result.nil?
+                  Legion::Logging.debug "[cognitive_quicksilver] split id=#{droplet_id} too_small"
+                  return { success: false, error: 'droplet mass too small to split' }
+                end
+
+                original, twin = result
+                Legion::Logging.debug "[cognitive_quicksilver] split id=#{droplet_id} twin_id=#{twin.id}"
+                { success: true, original: original.to_h, twin: twin.to_h }
+              rescue ArgumentError => e
+                Legion::Logging.debug "[cognitive_quicksilver] split failed: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def capture(droplet_id:, engine: nil, **)
+                eng = engine || quicksilver_engine
+                droplet = eng.capture_droplet(droplet_id: droplet_id)
+                Legion::Logging.debug "[cognitive_quicksilver] capture id=#{droplet_id} fluidity=#{droplet.fluidity.round(2)}"
+                { success: true, droplet: droplet.to_h }
+              rescue ArgumentError => e
+                Legion::Logging.debug "[cognitive_quicksilver] capture failed: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def release(droplet_id:, engine: nil, **)
+                eng = engine || quicksilver_engine
+                droplet = eng.release_droplet(droplet_id: droplet_id)
+                Legion::Logging.debug "[cognitive_quicksilver] release id=#{droplet_id} fluidity=#{droplet.fluidity.round(2)}"
+                { success: true, droplet: droplet.to_h }
+              rescue ArgumentError => e
+                Legion::Logging.debug "[cognitive_quicksilver] release failed: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def add_to_pool(droplet_id:, pool_id:, engine: nil, **)
+                eng = engine || quicksilver_engine
+                pool = eng.add_to_pool(droplet_id: droplet_id, pool_id: pool_id)
+                Legion::Logging.debug "[cognitive_quicksilver] add_to_pool droplet=#{droplet_id} pool=#{pool_id}"
+                { success: true, pool: pool.to_h }
+              rescue ArgumentError => e
+                Legion::Logging.debug "[cognitive_quicksilver] add_to_pool failed: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def list_droplets(engine: nil, **)
+                eng = engine || quicksilver_engine
+                items = eng.droplets
+                Legion::Logging.debug "[cognitive_quicksilver] list_droplets count=#{items.size}"
+                { success: true, droplets: items, count: items.size }
+              end
+
+              def quicksilver_status(engine: nil, **)
+                eng = engine || quicksilver_engine
+                report = eng.quicksilver_report
+                Legion::Logging.debug "[cognitive_quicksilver] status droplets=#{report[:total_droplets]} pools=#{report[:total_pools]}"
+                { success: true, **report }
+              end
+
+              private
+
+              def quicksilver_engine
+                @quicksilver_engine ||= Helpers::QuicksilverEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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