lex-cognitive-reserve 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 04a0cf12dceaf349aae570d73ec6bcffa44517823ec37a406f7da90382fe2275
+  data.tar.gz: 7b29466016bf0208f477a3c1f318663fa1817780e9b9c39d3aefad12429b6d90
+SHA512:
+  metadata.gz: c3f3c4a34212ebd84030f41a065c2b4bdff31a5d9066c89e4cbe946172a7f08ec285abe5ab83e65c8a250105efaad14f6368ab97665334ac5e54896111cc8dca
+  data.tar.gz: 78c46e884de31a6fbedb45c2fa328e4cd17ad589b656bc67da34a963fcc8d4b2e976450fc760a21a1ac40d593a48e2630948e7cc7b4872bb211a40777f6ad2a5

data/lib/legion/extensions/cognitive_reserve/client.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveReserve
+      class Client
+        include Runners::CognitiveReserve
+
+        def initialize(engine: nil)
+          @engine = engine
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_reserve/helpers/constants.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveReserve
+      module Helpers
+        module Constants
+          # Maximum tracked pathways
+          MAX_PATHWAYS = 100
+
+          # Maximum tracked compensations
+          MAX_COMPENSATIONS = 200
+
+          # Maximum event history
+          MAX_HISTORY = 300
+
+          # Default pathway capacity (0..1)
+          DEFAULT_CAPACITY = 1.0
+
+          # Capacity bounds
+          CAPACITY_FLOOR   = 0.0
+          CAPACITY_CEILING = 1.0
+
+          # Threshold below which a pathway is considered degraded
+          DEGRADED_THRESHOLD = 0.5
+
+          # Threshold below which a pathway is considered failed
+          FAILED_THRESHOLD = 0.1
+
+          # Compensation efficiency — how much of lost capacity a backup restores
+          COMPENSATION_EFFICIENCY = 0.7
+
+          # Recovery rate per tick
+          RECOVERY_RATE = 0.02
+
+          # Decay rate for unused compensatory pathways
+          COMPENSATION_DECAY = 0.01
+
+          # Reserve levels based on overall reserve ratio
+          RESERVE_LABELS = {
+            (0.8..)     => :robust,
+            (0.6...0.8) => :adequate,
+            (0.4...0.6) => :reduced,
+            (0.2...0.4) => :vulnerable,
+            (..0.2)     => :critical
+          }.freeze
+
+          # Pathway states
+          PATHWAY_STATES = %i[healthy degraded compensating failed].freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_reserve/helpers/pathway.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveReserve
+      module Helpers
+        class Pathway
+          include Constants
+
+          attr_reader :id, :domain, :function, :capacity, :backup_ids,
+                      :damage_count, :compensation_count, :created_at, :updated_at
+
+          def initialize(id:, function:, domain: :general, capacity: DEFAULT_CAPACITY)
+            @id                 = id
+            @function           = function
+            @domain             = domain
+            @capacity           = capacity.clamp(CAPACITY_FLOOR, CAPACITY_CEILING)
+            @backup_ids         = []
+            @damage_count       = 0
+            @compensation_count = 0
+            @created_at         = Time.now.utc
+            @updated_at         = @created_at
+          end
+
+          def damage(amount:)
+            @capacity = (@capacity - amount.abs).clamp(CAPACITY_FLOOR, CAPACITY_CEILING)
+            @damage_count += 1
+            @updated_at = Time.now.utc
+            self
+          end
+
+          def recover(amount: RECOVERY_RATE)
+            @capacity = (@capacity + amount.abs).clamp(CAPACITY_FLOOR, CAPACITY_CEILING)
+            @updated_at = Time.now.utc
+            self
+          end
+
+          def add_backup(pathway_id:)
+            return self if @backup_ids.include?(pathway_id)
+
+            @backup_ids << pathway_id
+            @updated_at = Time.now.utc
+            self
+          end
+
+          def remove_backup(pathway_id:)
+            @backup_ids.delete(pathway_id)
+            @updated_at = Time.now.utc
+            self
+          end
+
+          def compensate!
+            @compensation_count += 1
+            @updated_at = Time.now.utc
+          end
+
+          def state
+            return :failed if @capacity <= FAILED_THRESHOLD
+            return :compensating if @capacity <= DEGRADED_THRESHOLD && !@backup_ids.empty?
+            return :degraded if @capacity <= DEGRADED_THRESHOLD
+
+            :healthy
+          end
+
+          def healthy?
+            state == :healthy
+          end
+
+          def degraded?
+            @capacity <= DEGRADED_THRESHOLD
+          end
+
+          def failed?
+            @capacity <= FAILED_THRESHOLD
+          end
+
+          def effective_capacity(backup_capacities: [])
+            return @capacity if @capacity > DEGRADED_THRESHOLD || backup_capacities.empty?
+
+            deficit = DEGRADED_THRESHOLD - @capacity
+            compensation = backup_capacities.sum(0.0) * COMPENSATION_EFFICIENCY
+            (@capacity + [compensation, deficit].min).clamp(CAPACITY_FLOOR, CAPACITY_CEILING)
+          end
+
+          def redundancy
+            @backup_ids.size
+          end
+
+          def to_h
+            {
+              id:                 @id,
+              function:           @function,
+              domain:             @domain,
+              capacity:           @capacity.round(4),
+              state:              state,
+              backup_count:       @backup_ids.size,
+              backup_ids:         @backup_ids.dup,
+              damage_count:       @damage_count,
+              compensation_count: @compensation_count,
+              created_at:         @created_at,
+              updated_at:         @updated_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_reserve/helpers/reserve_engine.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveReserve
+      module Helpers
+        class ReserveEngine
+          include Constants
+
+          attr_reader :pathways, :history
+
+          def initialize
+            @pathways      = {}
+            @pathway_count = 0
+            @history       = []
+          end
+
+          def add_pathway(function:, domain: :general, capacity: DEFAULT_CAPACITY)
+            return nil if @pathways.size >= MAX_PATHWAYS
+
+            @pathway_count += 1
+            pathway = Pathway.new(
+              id:       :"path_#{@pathway_count}",
+              function: function,
+              domain:   domain,
+              capacity: capacity
+            )
+            @pathways[pathway.id] = pathway
+            record_event(:add_pathway, pathway_id: pathway.id)
+            pathway
+          end
+
+          def link_backup(primary_id:, backup_id:)
+            primary = @pathways[primary_id]
+            backup  = @pathways[backup_id]
+            return nil unless primary && backup
+
+            primary.add_backup(pathway_id: backup_id)
+            record_event(:link_backup, primary_id: primary_id, backup_id: backup_id)
+            primary
+          end
+
+          def damage_pathway(pathway_id:, amount:)
+            pathway = @pathways[pathway_id]
+            return nil unless pathway
+
+            pathway.damage(amount: amount)
+            activate_compensation(pathway) if pathway.degraded?
+            record_event(:damage, pathway_id: pathway_id, amount: amount, state: pathway.state)
+            pathway
+          end
+
+          def recover_pathway(pathway_id:, amount: RECOVERY_RATE)
+            pathway = @pathways[pathway_id]
+            return nil unless pathway
+
+            pathway.recover(amount: amount)
+            record_event(:recover, pathway_id: pathway_id)
+            pathway
+          end
+
+          def effective_capacity(pathway_id:)
+            pathway = @pathways[pathway_id]
+            return nil unless pathway
+
+            backup_caps = pathway.backup_ids.filter_map { |bid| @pathways[bid]&.capacity }
+            pathway.effective_capacity(backup_capacities: backup_caps)
+          end
+
+          def overall_reserve
+            return DEFAULT_CAPACITY if @pathways.empty?
+
+            caps = @pathways.values.map do |p|
+              backup_caps = p.backup_ids.filter_map { |bid| @pathways[bid]&.capacity }
+              p.effective_capacity(backup_capacities: backup_caps)
+            end
+            caps.sum / caps.size.to_f
+          end
+
+          def reserve_label
+            ratio = overall_reserve
+            RESERVE_LABELS.find { |range, _| range.cover?(ratio) }&.last || :critical
+          end
+
+          def degraded_pathways
+            @pathways.values.select(&:degraded?).map(&:to_h)
+          end
+
+          def failed_pathways
+            @pathways.values.select(&:failed?).map(&:to_h)
+          end
+
+          def healthy_pathways
+            @pathways.values.select(&:healthy?).map(&:to_h)
+          end
+
+          def domain_reserve(domain:)
+            relevant = @pathways.values.select { |p| p.domain == domain }
+            return DEFAULT_CAPACITY if relevant.empty?
+
+            caps = relevant.map do |p|
+              backup_caps = p.backup_ids.filter_map { |bid| @pathways[bid]&.capacity }
+              p.effective_capacity(backup_capacities: backup_caps)
+            end
+            caps.sum / caps.size.to_f
+          end
+
+          def most_vulnerable(limit: 5)
+            @pathways.values
+                     .sort_by(&:capacity)
+                     .first(limit)
+                     .map(&:to_h)
+          end
+
+          def most_redundant(limit: 5)
+            @pathways.values
+                     .sort_by { |p| -p.redundancy }
+                     .first(limit)
+                     .map(&:to_h)
+          end
+
+          def recover_all
+            @pathways.each_value { |p| p.recover unless p.failed? }
+          end
+
+          def to_h
+            {
+              pathway_count:   @pathways.size,
+              overall_reserve: overall_reserve.round(4),
+              reserve_label:   reserve_label,
+              healthy_count:   @pathways.values.count(&:healthy?),
+              degraded_count:  @pathways.values.count(&:degraded?),
+              failed_count:    @pathways.values.count(&:failed?),
+              history_size:    @history.size
+            }
+          end
+
+          private
+
+          def activate_compensation(pathway)
+            pathway.backup_ids.each do |backup_id|
+              backup = @pathways[backup_id]
+              next unless backup&.healthy?
+
+              pathway.compensate!
+              record_event(:compensate, pathway_id: pathway.id, backup_id: backup_id)
+              break
+            end
+          end
+
+          def record_event(type, **details)
+            @history << { type: type, at: Time.now.utc }.merge(details)
+            @history.shift while @history.size > MAX_HISTORY
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_reserve/runners/cognitive_reserve.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveReserve
+      module Runners
+        module CognitiveReserve
+          include Helpers::Constants
+          include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+          def add_cognitive_pathway(function:, domain: :general, capacity: DEFAULT_CAPACITY, **)
+            pathway = engine.add_pathway(function: function, domain: domain, capacity: capacity)
+            return { success: false, reason: :limit_reached } unless pathway
+
+            { success: true, pathway_id: pathway.id, capacity: pathway.capacity }
+          end
+
+          def link_backup_pathway(primary_id:, backup_id:, **)
+            result = engine.link_backup(primary_id: primary_id, backup_id: backup_id)
+            return { success: false, reason: :not_found } unless result
+
+            { success: true, primary_id: primary_id, backup_id: backup_id, backup_count: result.backup_ids.size }
+          end
+
+          def damage_cognitive_pathway(pathway_id:, amount:, **)
+            pathway = engine.damage_pathway(pathway_id: pathway_id, amount: amount)
+            return { success: false, reason: :not_found } unless pathway
+
+            {
+              success:            true,
+              pathway_id:         pathway_id,
+              capacity:           pathway.capacity.round(4),
+              state:              pathway.state,
+              effective_capacity: engine.effective_capacity(pathway_id: pathway_id)&.round(4)
+            }
+          end
+
+          def recover_cognitive_pathway(pathway_id:, amount: RECOVERY_RATE, **)
+            pathway = engine.recover_pathway(pathway_id: pathway_id, amount: amount)
+            return { success: false, reason: :not_found } unless pathway
+
+            { success: true, pathway_id: pathway_id, capacity: pathway.capacity.round(4), state: pathway.state }
+          end
+
+          def cognitive_reserve_assessment(**)
+            {
+              success:         true,
+              overall_reserve: engine.overall_reserve.round(4),
+              reserve_label:   engine.reserve_label,
+              most_vulnerable: engine.most_vulnerable,
+              degraded:        engine.degraded_pathways,
+              failed:          engine.failed_pathways
+            }
+          end
+
+          def domain_cognitive_reserve(domain:, **)
+            {
+              success:       true,
+              domain:        domain,
+              reserve:       engine.domain_reserve(domain: domain).round(4),
+              pathway_count: engine.pathways.values.count { |p| p.domain == domain }
+            }
+          end
+
+          def most_redundant_pathways(**)
+            pathways = engine.most_redundant
+            { success: true, pathways: pathways, count: pathways.size }
+          end
+
+          def update_cognitive_reserve(**)
+            engine.recover_all
+            { success: true }.merge(engine.to_h)
+          end
+
+          def cognitive_reserve_stats(**)
+            { success: true }.merge(engine.to_h)
+          end
+
+          private
+
+          def engine
+            @engine ||= Helpers::ReserveEngine.new
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_reserve/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveReserve
+      VERSION = '0.1.0'
+    end
+  end
+end

data/lib/legion/extensions/cognitive_reserve.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative 'cognitive_reserve/version'
+require_relative 'cognitive_reserve/helpers/constants'
+require_relative 'cognitive_reserve/helpers/pathway'
+require_relative 'cognitive_reserve/helpers/reserve_engine'
+require_relative 'cognitive_reserve/runners/cognitive_reserve'
+require_relative 'cognitive_reserve/client'
+
+module Legion
+  module Extensions
+    module CognitiveReserve
+      extend Legion::Extensions::Core if defined?(Legion::Extensions::Core)
+    end
+  end
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: lex-cognitive-reserve
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Esity
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: legion-gaia
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Cognitive reserve for LegionIO — resilience through redundant pathways,
+  compensatory mechanisms, and graceful degradation under damage
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/legion/extensions/cognitive_reserve.rb
+- lib/legion/extensions/cognitive_reserve/client.rb
+- lib/legion/extensions/cognitive_reserve/helpers/constants.rb
+- lib/legion/extensions/cognitive_reserve/helpers/pathway.rb
+- lib/legion/extensions/cognitive_reserve/helpers/reserve_engine.rb
+- lib/legion/extensions/cognitive_reserve/runners/cognitive_reserve.rb
+- lib/legion/extensions/cognitive_reserve/version.rb
+homepage: https://github.com/LegionIO/lex-cognitive-reserve
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-cognitive-reserve
+  source_code_uri: https://github.com/LegionIO/lex-cognitive-reserve
+  documentation_uri: https://github.com/LegionIO/lex-cognitive-reserve/blob/master/README.md
+  changelog_uri: https://github.com/LegionIO/lex-cognitive-reserve/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/LegionIO/lex-cognitive-reserve/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: LegionIO cognitive reserve extension
+test_files: []