lex-cognitive-weathering 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: db91ee5a95c7738bea4c0f2f8c81a941e27277376864e4981340b12bee855604
+  data.tar.gz: 3872c8f28774524bcdda173da925369949b08337b17a729efb9758cf1f2ff8e7
+SHA512:
+  metadata.gz: d01d7ab9af6ad5db0f289c88b57f5d34fa862c032442d202b581eb0915590da52515191501a95d8afdf95ed1a84e508882475c61cd538af518197129f59c6cf7
+  data.tar.gz: b259fc75e57095227014081979a61f5d748ff2d3567af1a627f8ee5653cc2a99625df072a4627405a55dd6d0ca3b659d877e64886bf5f758febe4542abfaa39c

data/Gemfile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+gemspec
+
+group :test do
+  gem 'rake'
+  gem 'rspec', '~> 3.13'
+  gem 'rspec_junit_formatter'
+  gem 'rubocop', '~> 1.75', require: false
+  gem 'rubocop-rspec', require: false
+  gem 'simplecov'
+end
+
+gem 'legion-gaia', path: '../../legion-gaia'

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Esity
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,73 @@
+# lex-cognitive-weathering
+
+A LegionIO cognitive architecture extension that models long-term cumulative cognitive wear. Based on allostatic load theory: sustained demands erode integrity, but manageable challenges also build tempering — a resilience multiplier that allows tempered agents to exceed their baseline capacity.
+
+## What It Does
+
+Tracks cognitive **integrity** (0.0–1.0) and **tempering level** (0.0–1.0) through stressor events and recovery.
+
+Each stressor has:
+- A type (`:cognitive_overload`, `:emotional_strain`, `:decision_fatigue`, `:conflict_exposure`, `:uncertainty`, `:time_pressure`, `:monotony`, `:complexity`)
+- Intensity (0.0–1.0) and duration (seconds)
+- `cumulative_impact` = `intensity * (duration / 3600.0)`
+
+Stressors with intensity <= 0.4 are **manageable** — they wear down integrity *and* build tempering. Overwhelming stressors (intensity >= 0.8) erode without building resilience.
+
+**Effective capacity** = `integrity * (1 + tempering * 0.2)` — a tempered agent can exceed 1.0 base capacity (up to 1.2).
+
+## Usage
+
+```ruby
+require 'lex-cognitive-weathering'
+
+client = Legion::Extensions::CognitiveWeathering::Client.new
+
+# Apply an overwhelming stressor (erodes integrity, no tempering)
+client.apply_stressor(
+  description:   'Sprint deadline pressure',
+  stressor_type: :time_pressure,
+  intensity:     0.8,
+  duration:      7200,
+  domain:        'engineering'
+)
+# => { integrity: 0.9984, tempering_level: 0.0, effective_capacity: 0.9984, fragile: false, ... }
+
+# Apply a manageable stressor (erodes slightly, builds tempering)
+client.apply_stressor(
+  description:   'Steady background complexity',
+  stressor_type: :complexity,
+  intensity:     0.3,
+  duration:      3600
+)
+# => { integrity: 0.9980, tempering_level: 0.0009, effective_capacity: 0.9982, ... }
+
+# Check current state
+client.integrity_status
+# => { integrity: 0.9980, integrity_label: "pristine", tempering_level: 0.0009, weathering_label: "eroded", ... }
+
+# Recover from wear (small increment)
+client.recover(amount: 1.0)
+# => { integrity: 0.9990, ... }
+
+# Full rest (5x recovery rate)
+client.rest(amount: 1.0)
+# => { integrity: 0.9995, ... }
+
+# Full weathering report
+client.weathering_report
+# => { integrity: 0.9995, integrity_label: "pristine", tempering_level: 0.0009, weathering_label: "eroded",
+#      effective_capacity: 0.9997, total_wear: 0.0021, total_recovery: 0.0015,
+#      stressor_count: 2, fragile: false, breaking: false, recent_stressors: [...] }
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-cognitive-weathering.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_weathering/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-weathering'
+  spec.version       = Legion::Extensions::CognitiveWeathering::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Cognitive Weathering'
+  spec.description   = 'Models long-term cognitive wear from sustained workloads based on allostatic load theory'
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-weathering'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri']      = spec.homepage
+  spec.metadata['source_code_uri']   = 'https://github.com/LegionIO/lex-cognitive-weathering'
+  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-cognitive-weathering'
+  spec.metadata['changelog_uri']     = 'https://github.com/LegionIO/lex-cognitive-weathering'
+  spec.metadata['bug_tracker_uri']   = 'https://github.com/LegionIO/lex-cognitive-weathering/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-cognitive-weathering.gemspec Gemfile LICENSE README.md]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_weathering/helpers/constants'
+require 'legion/extensions/cognitive_weathering/helpers/stressor'
+require 'legion/extensions/cognitive_weathering/helpers/weathering_engine'
+require 'legion/extensions/cognitive_weathering/runners/cognitive_weathering'
+
+module Legion
+  module Extensions
+    module CognitiveWeathering
+      class Client
+        include Runners::CognitiveWeathering
+
+        def initialize(**)
+          @weathering_engine = Helpers::WeatheringEngine.new
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveWeathering
+      module Helpers
+        module Constants
+          MAX_STRESSORS         = 200
+          MAX_EVENTS            = 500
+
+          DEFAULT_INTEGRITY     = 1.0
+          WEAR_RATE             = 0.02
+          RECOVERY_RATE         = 0.01
+          TEMPERING_RATE        = 0.03
+
+          TEMPERING_THRESHOLD   = 0.4
+          CRITICAL_INTEGRITY    = 0.3
+          BREAKDOWN_INTEGRITY   = 0.1
+
+          STRESSOR_TYPES = %i[
+            cognitive_overload
+            emotional_strain
+            decision_fatigue
+            conflict_exposure
+            uncertainty
+            time_pressure
+            monotony
+            complexity
+          ].freeze
+
+          INTEGRITY_LABELS = [
+            { range: (0.8..1.0),  label: 'pristine' },
+            { range: (0.6...0.8), label: 'strong'   },
+            { range: (0.4...0.6), label: 'worn'     },
+            { range: (0.2...0.4), label: 'fragile'  },
+            { range: (0.0...0.2), label: 'breaking' }
+          ].freeze
+
+          WEATHERING_LABELS = [
+            { range: (0.7..1.0),  label: 'tempered' },
+            { range: (0.5...0.7), label: 'resilient'  },
+            { range: (0.3...0.5), label: 'stable'     },
+            { range: (0.1...0.3), label: 'weathered'  },
+            { range: (0.0...0.1), label: 'eroded'     }
+          ].freeze
+
+          module_function
+
+          def integrity_label(integrity)
+            entry = INTEGRITY_LABELS.find { |e| e[:range].cover?(integrity) }
+            entry ? entry[:label] : 'breaking'
+          end
+
+          def weathering_label(tempering_level)
+            entry = WEATHERING_LABELS.find { |e| e[:range].cover?(tempering_level) }
+            entry ? entry[:label] : 'eroded'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_weathering/helpers/stressor.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveWeathering
+      module Helpers
+        class Stressor
+          include Constants
+
+          attr_reader :id, :description, :stressor_type, :intensity, :duration, :domain, :recorded_at
+
+          def initialize(description:, stressor_type:, intensity:, duration:, domain: nil)
+            @id           = SecureRandom.uuid
+            @description  = description
+            @stressor_type = validate_type(stressor_type)
+            @intensity    = intensity.clamp(0.0, 1.0)
+            @duration     = [duration.to_f, 0.0].max
+            @domain       = domain
+            @recorded_at  = Time.now.utc
+          end
+
+          def cumulative_impact
+            (intensity * (duration / 3600.0)).clamp(0.0, 1.0).round(10)
+          end
+
+          def manageable?
+            intensity <= Constants::TEMPERING_THRESHOLD
+          end
+
+          def overwhelming?
+            intensity >= 0.8
+          end
+
+          def to_h
+            {
+              id:                id,
+              description:       description,
+              stressor_type:     stressor_type,
+              intensity:         intensity,
+              duration:          duration,
+              domain:            domain,
+              cumulative_impact: cumulative_impact,
+              manageable:        manageable?,
+              overwhelming:      overwhelming?,
+              recorded_at:       recorded_at.iso8601
+            }
+          end
+
+          private
+
+          def validate_type(type)
+            sym = type.to_sym
+            Constants::STRESSOR_TYPES.include?(sym) ? sym : :cognitive_overload
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_weathering/helpers/weathering_engine.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveWeathering
+      module Helpers
+        class WeatheringEngine
+          include Constants
+
+          attr_reader :integrity, :tempering_level, :total_wear, :total_recovery
+
+          def initialize
+            @stressors      = []
+            @events         = []
+            @integrity      = Constants::DEFAULT_INTEGRITY
+            @tempering_level = 0.0
+            @total_wear     = 0.0
+            @total_recovery = 0.0
+          end
+
+          def apply_stressor(stressor)
+            prune_stressors
+            @stressors << stressor
+
+            record_event(:stressor_applied, stressor.to_h)
+            wear!(stressor.cumulative_impact)
+            temper!(stressor.cumulative_impact * Constants::TEMPERING_RATE) if stressor.manageable?
+
+            to_h
+          end
+
+          def recover!(amount)
+            amount = amount.clamp(0.0, 1.0)
+            delta  = [amount * Constants::RECOVERY_RATE, 1.0 - @integrity].min
+            @integrity      = (@integrity + delta).clamp(0.0, 1.0).round(10)
+            @total_recovery = (@total_recovery + delta).round(10)
+            record_event(:recovery, { amount: amount, delta: delta, integrity: @integrity })
+            to_h
+          end
+
+          def rest!(amount = 1.0)
+            amount = amount.clamp(0.0, 1.0)
+            delta  = [amount * (Constants::RECOVERY_RATE * 5.0), 1.0 - @integrity].min
+            @integrity      = (@integrity + delta).clamp(0.0, 1.0).round(10)
+            @total_recovery = (@total_recovery + delta).round(10)
+            record_event(:rest, { amount: amount, delta: delta, integrity: @integrity })
+            to_h
+          end
+
+          def effective_capacity
+            (@integrity * (1.0 + (@tempering_level * 0.2))).clamp(0.0, 1.2).round(10)
+          end
+
+          def fragile?
+            @integrity <= Constants::CRITICAL_INTEGRITY
+          end
+
+          def breaking?
+            @integrity <= Constants::BREAKDOWN_INTEGRITY
+          end
+
+          def stressor_count
+            @stressors.size
+          end
+
+          def weathering_report
+            {
+              integrity:          @integrity.round(10),
+              integrity_label:    Constants.integrity_label(@integrity),
+              tempering_level:    @tempering_level.round(10),
+              weathering_label:   Constants.weathering_label(@tempering_level),
+              effective_capacity: effective_capacity,
+              total_wear:         @total_wear.round(10),
+              total_recovery:     @total_recovery.round(10),
+              stressor_count:     @stressors.size,
+              fragile:            fragile?,
+              breaking:           breaking?,
+              recent_stressors:   @stressors.last(5).map(&:to_h)
+            }
+          end
+
+          def to_h
+            {
+              integrity:          @integrity.round(10),
+              tempering_level:    @tempering_level.round(10),
+              effective_capacity: effective_capacity,
+              fragile:            fragile?,
+              breaking:           breaking?
+            }
+          end
+
+          private
+
+          def wear!(amount)
+            delta = (amount * Constants::WEAR_RATE).clamp(0.0, @integrity)
+            @integrity      = (@integrity - delta).clamp(0.0, 1.0).round(10)
+            @total_wear     = (@total_wear + delta).round(10)
+          end
+
+          def temper!(amount)
+            delta            = amount.clamp(0.0, 1.0 - @tempering_level)
+            @tempering_level = (@tempering_level + delta).clamp(0.0, 1.0).round(10)
+          end
+
+          def record_event(type, data)
+            prune_events
+            @events << { type: type, data: data, timestamp: Time.now.utc.iso8601 }
+          end
+
+          def prune_stressors
+            @stressors.shift while @stressors.size >= Constants::MAX_STRESSORS
+          end
+
+          def prune_events
+            @events.shift while @events.size >= Constants::MAX_EVENTS
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveWeathering
+      module Runners
+        module CognitiveWeathering
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def apply_stressor(description:, stressor_type: :cognitive_overload, intensity: 0.5,
+                             duration: 3600, domain: nil, **)
+            stressor = Helpers::Stressor.new(
+              description:   description,
+              stressor_type: stressor_type,
+              intensity:     intensity,
+              duration:      duration,
+              domain:        domain
+            )
+
+            result = weathering_engine.apply_stressor(stressor)
+            Legion::Logging.debug "[cognitive_weathering] stressor applied: type=#{stressor_type} " \
+                                  "intensity=#{intensity} impact=#{stressor.cumulative_impact.round(4)} " \
+                                  "integrity=#{result[:integrity].round(4)} fragile=#{result[:fragile]}"
+            result.merge(stressor: stressor.to_h)
+          end
+
+          def recover(amount: 1.0, **)
+            result = weathering_engine.recover!(amount)
+            Legion::Logging.debug "[cognitive_weathering] recovery: amount=#{amount} integrity=#{result[:integrity].round(4)}"
+            result
+          end
+
+          def rest(amount: 1.0, **)
+            result = weathering_engine.rest!(amount)
+            Legion::Logging.debug "[cognitive_weathering] rest: amount=#{amount} integrity=#{result[:integrity].round(4)}"
+            result
+          end
+
+          def weathering_report(**)
+            report = weathering_engine.weathering_report
+            Legion::Logging.debug "[cognitive_weathering] report: integrity=#{report[:integrity_label]} " \
+                                  "capacity=#{report[:effective_capacity].round(4)} " \
+                                  "stressors=#{report[:stressor_count]}"
+            report
+          end
+
+          def integrity_status(**)
+            engine = weathering_engine
+            {
+              integrity:          engine.integrity.round(10),
+              integrity_label:    Helpers::Constants.integrity_label(engine.integrity),
+              tempering_level:    engine.tempering_level.round(10),
+              weathering_label:   Helpers::Constants.weathering_label(engine.tempering_level),
+              effective_capacity: engine.effective_capacity,
+              fragile:            engine.fragile?,
+              breaking:           engine.breaking?
+            }
+          end
+
+          private
+
+          def weathering_engine
+            @weathering_engine ||= Helpers::WeatheringEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/cognitive_weathering.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_weathering/version'
+require 'legion/extensions/cognitive_weathering/helpers/constants'
+require 'legion/extensions/cognitive_weathering/helpers/stressor'
+require 'legion/extensions/cognitive_weathering/helpers/weathering_engine'
+require 'legion/extensions/cognitive_weathering/runners/cognitive_weathering'
+
+module Legion
+  module Extensions
+    module CognitiveWeathering
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

data/spec/legion/extensions/cognitive_weathering/client_spec.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_weathering/client'
+
+RSpec.describe Legion::Extensions::CognitiveWeathering::Client do
+  let(:client) { described_class.new }
+
+  it 'responds to apply_stressor' do
+    expect(client).to respond_to(:apply_stressor)
+  end
+
+  it 'responds to recover' do
+    expect(client).to respond_to(:recover)
+  end
+
+  it 'responds to rest' do
+    expect(client).to respond_to(:rest)
+  end
+
+  it 'responds to weathering_report' do
+    expect(client).to respond_to(:weathering_report)
+  end
+
+  it 'responds to integrity_status' do
+    expect(client).to respond_to(:integrity_status)
+  end
+
+  it 'starts with pristine integrity' do
+    status = client.integrity_status
+    expect(status[:integrity_label]).to eq('pristine')
+  end
+
+  it 'round-trips a full weathering cycle' do
+    client.apply_stressor(description: 'Sprint overload', stressor_type: :time_pressure,
+                          intensity: 0.85, duration: 7200)
+    client.apply_stressor(description: 'Repeated decisions', stressor_type: :decision_fatigue,
+                          intensity: 0.7, duration: 3600)
+    client.apply_stressor(description: 'Mild task', stressor_type: :monotony,
+                          intensity: 0.2, duration: 1800)
+
+    report = client.weathering_report
+    expect(report[:stressor_count]).to eq(3)
+    expect(report[:integrity]).to be < 1.0
+    expect(report[:tempering_level]).to be > 0.0
+
+    client.rest(amount: 1.0)
+    after_rest = client.integrity_status
+    expect(after_rest[:integrity]).to be > report[:integrity]
+  end
+
+  it 'effective_capacity increases with tempering' do
+    20.times do
+      client.apply_stressor(description: 'Manageable', stressor_type: :complexity,
+                            intensity: 0.3, duration: 1800)
+    end
+    status = client.integrity_status
+    expect(status[:tempering_level]).to be > 0.0
+    expect(status[:effective_capacity]).to be > 0.0
+  end
+
+  it 'each client instance has independent state' do
+    client_a = described_class.new
+    client_b = described_class.new
+
+    client_a.apply_stressor(description: 'only a', intensity: 0.9, duration: 7200)
+
+    expect(client_a.integrity_status[:integrity]).to be < 1.0
+    expect(client_b.integrity_status[:integrity]).to eq(1.0)
+  end
+end

data/spec/legion/extensions/cognitive_weathering/helpers/constants_spec.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::CognitiveWeathering::Helpers::Constants do
+  describe 'numeric constants' do
+    it 'defines MAX_STRESSORS' do
+      expect(described_class::MAX_STRESSORS).to eq(200)
+    end
+
+    it 'defines MAX_EVENTS' do
+      expect(described_class::MAX_EVENTS).to eq(500)
+    end
+
+    it 'defines DEFAULT_INTEGRITY as 1.0' do
+      expect(described_class::DEFAULT_INTEGRITY).to eq(1.0)
+    end
+
+    it 'defines WEAR_RATE' do
+      expect(described_class::WEAR_RATE).to eq(0.02)
+    end
+
+    it 'defines RECOVERY_RATE' do
+      expect(described_class::RECOVERY_RATE).to eq(0.01)
+    end
+
+    it 'defines TEMPERING_RATE' do
+      expect(described_class::TEMPERING_RATE).to eq(0.03)
+    end
+
+    it 'defines TEMPERING_THRESHOLD' do
+      expect(described_class::TEMPERING_THRESHOLD).to eq(0.4)
+    end
+
+    it 'defines CRITICAL_INTEGRITY' do
+      expect(described_class::CRITICAL_INTEGRITY).to eq(0.3)
+    end
+
+    it 'defines BREAKDOWN_INTEGRITY' do
+      expect(described_class::BREAKDOWN_INTEGRITY).to eq(0.1)
+    end
+  end
+
+  describe 'STRESSOR_TYPES' do
+    it 'contains all 8 stressor types' do
+      expect(described_class::STRESSOR_TYPES.size).to eq(8)
+    end
+
+    it 'includes :cognitive_overload' do
+      expect(described_class::STRESSOR_TYPES).to include(:cognitive_overload)
+    end
+
+    it 'includes :emotional_strain' do
+      expect(described_class::STRESSOR_TYPES).to include(:emotional_strain)
+    end
+
+    it 'includes :decision_fatigue' do
+      expect(described_class::STRESSOR_TYPES).to include(:decision_fatigue)
+    end
+
+    it 'includes :conflict_exposure' do
+      expect(described_class::STRESSOR_TYPES).to include(:conflict_exposure)
+    end
+
+    it 'includes :uncertainty' do
+      expect(described_class::STRESSOR_TYPES).to include(:uncertainty)
+    end
+
+    it 'includes :time_pressure' do
+      expect(described_class::STRESSOR_TYPES).to include(:time_pressure)
+    end
+
+    it 'includes :monotony' do
+      expect(described_class::STRESSOR_TYPES).to include(:monotony)
+    end
+
+    it 'includes :complexity' do
+      expect(described_class::STRESSOR_TYPES).to include(:complexity)
+    end
+
+    it 'is frozen' do
+      expect(described_class::STRESSOR_TYPES).to be_frozen
+    end
+  end
+
+  describe '.integrity_label' do
+    it 'returns pristine for 1.0' do
+      expect(described_class.integrity_label(1.0)).to eq('pristine')
+    end
+
+    it 'returns pristine for 0.8' do
+      expect(described_class.integrity_label(0.8)).to eq('pristine')
+    end
+
+    it 'returns strong for 0.7' do
+      expect(described_class.integrity_label(0.7)).to eq('strong')
+    end
+
+    it 'returns strong for 0.6' do
+      expect(described_class.integrity_label(0.6)).to eq('strong')
+    end
+
+    it 'returns worn for 0.5' do
+      expect(described_class.integrity_label(0.5)).to eq('worn')
+    end
+
+    it 'returns fragile for 0.25' do
+      expect(described_class.integrity_label(0.25)).to eq('fragile')
+    end
+
+    it 'returns breaking for 0.1' do
+      expect(described_class.integrity_label(0.1)).to eq('breaking')
+    end
+
+    it 'returns breaking for 0.0' do
+      expect(described_class.integrity_label(0.0)).to eq('breaking')
+    end
+  end
+
+  describe '.weathering_label' do
+    it 'returns tempered for 0.9' do
+      expect(described_class.weathering_label(0.9)).to eq('tempered')
+    end
+
+    it 'returns tempered for 0.7' do
+      expect(described_class.weathering_label(0.7)).to eq('tempered')
+    end
+
+    it 'returns resilient for 0.6' do
+      expect(described_class.weathering_label(0.6)).to eq('resilient')
+    end
+
+    it 'returns stable for 0.4' do
+      expect(described_class.weathering_label(0.4)).to eq('stable')
+    end
+
+    it 'returns weathered for 0.2' do
+      expect(described_class.weathering_label(0.2)).to eq('weathered')
+    end
+
+    it 'returns eroded for 0.05' do
+      expect(described_class.weathering_label(0.05)).to eq('eroded')
+    end
+
+    it 'returns eroded for 0.0' do
+      expect(described_class.weathering_label(0.0)).to eq('eroded')
+    end
+  end
+end

data/spec/legion/extensions/cognitive_weathering/helpers/stressor_spec.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::CognitiveWeathering::Helpers::Stressor do
+  let(:stressor) do
+    described_class.new(
+      description:   'Heavy parallel task load',
+      stressor_type: :cognitive_overload,
+      intensity:     0.7,
+      duration:      3600,
+      domain:        'work'
+    )
+  end
+
+  describe '#initialize' do
+    it 'assigns a UUID id' do
+      expect(stressor.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'assigns description' do
+      expect(stressor.description).to eq('Heavy parallel task load')
+    end
+
+    it 'assigns stressor_type' do
+      expect(stressor.stressor_type).to eq(:cognitive_overload)
+    end
+
+    it 'assigns intensity' do
+      expect(stressor.intensity).to eq(0.7)
+    end
+
+    it 'assigns duration' do
+      expect(stressor.duration).to eq(3600)
+    end
+
+    it 'assigns domain' do
+      expect(stressor.domain).to eq('work')
+    end
+
+    it 'records a timestamp' do
+      expect(stressor.recorded_at).to be_a(Time)
+    end
+
+    it 'clamps intensity above 1.0 to 1.0' do
+      s = described_class.new(description: 'test', stressor_type: :monotony, intensity: 1.5, duration: 60)
+      expect(s.intensity).to eq(1.0)
+    end
+
+    it 'clamps intensity below 0.0 to 0.0' do
+      s = described_class.new(description: 'test', stressor_type: :monotony, intensity: -0.3, duration: 60)
+      expect(s.intensity).to eq(0.0)
+    end
+
+    it 'defaults domain to nil when not provided' do
+      s = described_class.new(description: 'test', stressor_type: :complexity, intensity: 0.5, duration: 60)
+      expect(s.domain).to be_nil
+    end
+
+    it 'falls back to :cognitive_overload for unknown stressor type' do
+      s = described_class.new(description: 'test', stressor_type: :banana, intensity: 0.5, duration: 60)
+      expect(s.stressor_type).to eq(:cognitive_overload)
+    end
+
+    it 'accepts string stressor type and converts to symbol' do
+      s = described_class.new(description: 'test', stressor_type: 'monotony', intensity: 0.5, duration: 60)
+      expect(s.stressor_type).to eq(:monotony)
+    end
+
+    it 'floors negative duration to 0' do
+      s = described_class.new(description: 'test', stressor_type: :uncertainty, intensity: 0.3, duration: -100)
+      expect(s.duration).to eq(0.0)
+    end
+  end
+
+  describe '#cumulative_impact' do
+    it 'computes intensity * (duration / 3600)' do
+      expect(stressor.cumulative_impact).to be_within(0.0001).of(0.7)
+    end
+
+    it 'rounds to 10 decimal places' do
+      expect(stressor.cumulative_impact.to_s).to match(/\A\d+\.\d+\z/)
+    end
+
+    it 'clamps at 1.0 for very long durations' do
+      s = described_class.new(description: 'long', stressor_type: :time_pressure, intensity: 1.0, duration: 100_000)
+      expect(s.cumulative_impact).to eq(1.0)
+    end
+
+    it 'returns 0 for zero duration' do
+      s = described_class.new(description: 'instant', stressor_type: :uncertainty, intensity: 0.9, duration: 0)
+      expect(s.cumulative_impact).to eq(0.0)
+    end
+  end
+
+  describe '#manageable?' do
+    it 'returns true when intensity is at or below TEMPERING_THRESHOLD' do
+      s = described_class.new(description: 'mild', stressor_type: :monotony, intensity: 0.4, duration: 60)
+      expect(s.manageable?).to be(true)
+    end
+
+    it 'returns false when intensity exceeds TEMPERING_THRESHOLD' do
+      s = described_class.new(description: 'heavy', stressor_type: :cognitive_overload, intensity: 0.6, duration: 60)
+      expect(s.manageable?).to be(false)
+    end
+  end
+
+  describe '#overwhelming?' do
+    it 'returns true when intensity >= 0.8' do
+      s = described_class.new(description: 'extreme', stressor_type: :conflict_exposure, intensity: 0.9, duration: 60)
+      expect(s.overwhelming?).to be(true)
+    end
+
+    it 'returns false when intensity < 0.8' do
+      s = described_class.new(description: 'moderate', stressor_type: :complexity, intensity: 0.7, duration: 60)
+      expect(s.overwhelming?).to be(false)
+    end
+  end
+
+  describe '#to_h' do
+    subject(:hash) { stressor.to_h }
+
+    it 'includes id' do
+      expect(hash[:id]).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'includes description' do
+      expect(hash[:description]).to eq('Heavy parallel task load')
+    end
+
+    it 'includes stressor_type' do
+      expect(hash[:stressor_type]).to eq(:cognitive_overload)
+    end
+
+    it 'includes intensity' do
+      expect(hash[:intensity]).to eq(0.7)
+    end
+
+    it 'includes duration' do
+      expect(hash[:duration]).to eq(3600)
+    end
+
+    it 'includes domain' do
+      expect(hash[:domain]).to eq('work')
+    end
+
+    it 'includes cumulative_impact' do
+      expect(hash[:cumulative_impact]).to be_a(Float)
+    end
+
+    it 'includes manageable flag' do
+      expect(hash[:manageable]).to be(false)
+    end
+
+    it 'includes overwhelming flag' do
+      expect(hash[:overwhelming]).to be(false)
+    end
+
+    it 'includes recorded_at as ISO8601 string' do
+      expect(hash[:recorded_at]).to match(/\d{4}-\d{2}-\d{2}T/)
+    end
+  end
+end

data/spec/legion/extensions/cognitive_weathering/helpers/weathering_engine_spec.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::CognitiveWeathering::Helpers::WeatheringEngine do
+  subject(:engine) { described_class.new }
+
+  let(:mild_stressor) do
+    Legion::Extensions::CognitiveWeathering::Helpers::Stressor.new(
+      description:   'Mild task',
+      stressor_type: :monotony,
+      intensity:     0.3,
+      duration:      1800
+    )
+  end
+
+  let(:heavy_stressor) do
+    Legion::Extensions::CognitiveWeathering::Helpers::Stressor.new(
+      description:   'Extreme overload',
+      stressor_type: :cognitive_overload,
+      intensity:     0.9,
+      duration:      7200
+    )
+  end
+
+  describe '#initialize' do
+    it 'starts with full integrity' do
+      expect(engine.integrity).to eq(1.0)
+    end
+
+    it 'starts with zero tempering_level' do
+      expect(engine.tempering_level).to eq(0.0)
+    end
+
+    it 'starts with zero total_wear' do
+      expect(engine.total_wear).to eq(0.0)
+    end
+
+    it 'starts with zero total_recovery' do
+      expect(engine.total_recovery).to eq(0.0)
+    end
+  end
+
+  describe '#apply_stressor' do
+    it 'reduces integrity after a heavy stressor' do
+      engine.apply_stressor(heavy_stressor)
+      expect(engine.integrity).to be < 1.0
+    end
+
+    it 'increases total_wear' do
+      engine.apply_stressor(heavy_stressor)
+      expect(engine.total_wear).to be > 0.0
+    end
+
+    it 'does not increase tempering for overwhelming stressor' do
+      engine.apply_stressor(heavy_stressor)
+      expect(engine.tempering_level).to eq(0.0)
+    end
+
+    it 'increases tempering for manageable stressor' do
+      engine.apply_stressor(mild_stressor)
+      expect(engine.tempering_level).to be > 0.0
+    end
+
+    it 'returns a hash with integrity key' do
+      result = engine.apply_stressor(heavy_stressor)
+      expect(result).to have_key(:integrity)
+    end
+
+    it 'returns a hash with breaking key' do
+      result = engine.apply_stressor(heavy_stressor)
+      expect(result).to have_key(:breaking)
+    end
+
+    it 'increments stressor_count' do
+      engine.apply_stressor(mild_stressor)
+      expect(engine.stressor_count).to eq(1)
+    end
+
+    it 'wear scales with cumulative impact' do
+      small = Legion::Extensions::CognitiveWeathering::Helpers::Stressor.new(
+        description: 'tiny', stressor_type: :monotony, intensity: 0.1, duration: 60
+      )
+      large = Legion::Extensions::CognitiveWeathering::Helpers::Stressor.new(
+        description: 'large', stressor_type: :cognitive_overload, intensity: 0.9, duration: 7200
+      )
+      engine_a = described_class.new
+      engine_b = described_class.new
+      engine_a.apply_stressor(small)
+      engine_b.apply_stressor(large)
+      expect(engine_b.total_wear).to be > engine_a.total_wear
+    end
+  end
+
+  describe '#recover!' do
+    before { engine.apply_stressor(heavy_stressor) }
+
+    it 'increases integrity' do
+      before = engine.integrity
+      engine.recover!(1.0)
+      expect(engine.integrity).to be > before
+    end
+
+    it 'increases total_recovery' do
+      engine.recover!(1.0)
+      expect(engine.total_recovery).to be > 0.0
+    end
+
+    it 'returns a hash with integrity' do
+      result = engine.recover!(1.0)
+      expect(result).to have_key(:integrity)
+    end
+
+    it 'clamps amount above 1.0' do
+      expect { engine.recover!(5.0) }.not_to raise_error
+    end
+
+    it 'does not exceed 1.0 integrity' do
+      10.times { engine.recover!(1.0) }
+      expect(engine.integrity).to be <= 1.0
+    end
+  end
+
+  describe '#rest!' do
+    before { 5.times { engine.apply_stressor(heavy_stressor) } }
+
+    it 'increases integrity more than recover' do
+      engine_a = described_class.new
+      engine_b = described_class.new
+      5.times { engine_a.apply_stressor(heavy_stressor) }
+      5.times { engine_b.apply_stressor(heavy_stressor) }
+      integrity_before = engine_a.integrity
+
+      engine_a.recover!(1.0)
+      engine_b.rest!(1.0)
+
+      recovery_delta = engine_a.integrity - integrity_before
+      rest_delta = engine_b.integrity - integrity_before
+      expect(rest_delta).to be > recovery_delta
+    end
+
+    it 'does not exceed 1.0 integrity' do
+      10.times { engine.rest!(1.0) }
+      expect(engine.integrity).to be <= 1.0
+    end
+
+    it 'increases total_recovery' do
+      engine.rest!(1.0)
+      expect(engine.total_recovery).to be > 0.0
+    end
+  end
+
+  describe '#effective_capacity' do
+    it 'starts at 1.0 with no tempering' do
+      expect(engine.effective_capacity).to be_within(0.001).of(1.0)
+    end
+
+    it 'increases above base when tempering is present' do
+      20.times { engine.apply_stressor(mild_stressor) }
+      expect(engine.tempering_level).to be > 0.0
+      expect(engine.effective_capacity).to be > (engine.integrity * 1.0)
+    end
+
+    it 'is capped at 1.2' do
+      100.times { engine.apply_stressor(mild_stressor) }
+      expect(engine.effective_capacity).to be <= 1.2
+    end
+
+    it 'decreases as integrity drops' do
+      base = engine.effective_capacity
+      10.times { engine.apply_stressor(heavy_stressor) }
+      expect(engine.effective_capacity).to be < base
+    end
+  end
+
+  describe '#fragile?' do
+    it 'returns false at full integrity' do
+      expect(engine.fragile?).to be(false)
+    end
+
+    it 'returns true when integrity is at or below CRITICAL_INTEGRITY' do
+      100.times { engine.apply_stressor(heavy_stressor) }
+      expect(engine.fragile?).to be(true)
+    end
+  end
+
+  describe '#breaking?' do
+    it 'returns false at full integrity' do
+      expect(engine.breaking?).to be(false)
+    end
+
+    it 'returns true when integrity is at or below BREAKDOWN_INTEGRITY' do
+      500.times { engine.apply_stressor(heavy_stressor) }
+      expect(engine.breaking?).to be(true)
+    end
+  end
+
+  describe '#weathering_report' do
+    it 'returns all expected keys' do
+      report = engine.weathering_report
+      expect(report).to have_key(:integrity)
+      expect(report).to have_key(:integrity_label)
+      expect(report).to have_key(:tempering_level)
+      expect(report).to have_key(:weathering_label)
+      expect(report).to have_key(:effective_capacity)
+      expect(report).to have_key(:total_wear)
+      expect(report).to have_key(:total_recovery)
+      expect(report).to have_key(:stressor_count)
+      expect(report).to have_key(:fragile)
+      expect(report).to have_key(:breaking)
+      expect(report).to have_key(:recent_stressors)
+    end
+
+    it 'includes integrity_label as a string' do
+      expect(engine.weathering_report[:integrity_label]).to eq('pristine')
+    end
+
+    it 'caps recent_stressors at 5' do
+      10.times { engine.apply_stressor(mild_stressor) }
+      expect(engine.weathering_report[:recent_stressors].size).to eq(5)
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes integrity, tempering_level, effective_capacity, fragile, breaking' do
+      h = engine.to_h
+      expect(h).to have_key(:integrity)
+      expect(h).to have_key(:tempering_level)
+      expect(h).to have_key(:effective_capacity)
+      expect(h).to have_key(:fragile)
+      expect(h).to have_key(:breaking)
+    end
+  end
+
+  describe 'MAX_STRESSORS pruning' do
+    it 'does not exceed MAX_STRESSORS in memory' do
+      constants = Legion::Extensions::CognitiveWeathering::Helpers::Constants
+      (constants::MAX_STRESSORS + 10).times do
+        engine.apply_stressor(mild_stressor)
+      end
+      expect(engine.stressor_count).to be <= constants::MAX_STRESSORS
+    end
+  end
+end

data/spec/legion/extensions/cognitive_weathering/runners/cognitive_weathering_spec.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_weathering/client'
+
+RSpec.describe Legion::Extensions::CognitiveWeathering::Runners::CognitiveWeathering do
+  let(:client) { Legion::Extensions::CognitiveWeathering::Client.new }
+
+  describe '#apply_stressor' do
+    it 'returns a hash with integrity' do
+      result = client.apply_stressor(description: 'Heavy load', stressor_type: :cognitive_overload,
+                                     intensity: 0.8, duration: 3600)
+      expect(result).to have_key(:integrity)
+    end
+
+    it 'includes stressor details in result' do
+      result = client.apply_stressor(description: 'Test stressor', stressor_type: :monotony,
+                                     intensity: 0.3, duration: 1800)
+      expect(result[:stressor][:description]).to eq('Test stressor')
+    end
+
+    it 'uses defaults when optional params omitted' do
+      result = client.apply_stressor(description: 'minimal')
+      expect(result).to have_key(:integrity)
+    end
+
+    it 'reduces integrity for high-intensity stressor' do
+      client.apply_stressor(description: 'overload', intensity: 0.9, duration: 7200)
+      status = client.integrity_status
+      expect(status[:integrity]).to be < 1.0
+    end
+
+    it 'includes breaking flag' do
+      result = client.apply_stressor(description: 'test', intensity: 0.5, duration: 3600)
+      expect(result).to have_key(:breaking)
+    end
+  end
+
+  describe '#recover' do
+    before { client.apply_stressor(description: 'stress', intensity: 0.9, duration: 7200) }
+
+    it 'increases integrity after recovery' do
+      before = client.integrity_status[:integrity]
+      client.recover(amount: 1.0)
+      after = client.integrity_status[:integrity]
+      expect(after).to be >= before
+    end
+
+    it 'returns a hash with integrity' do
+      result = client.recover(amount: 1.0)
+      expect(result).to have_key(:integrity)
+    end
+
+    it 'uses default amount of 1.0' do
+      expect { client.recover }.not_to raise_error
+    end
+  end
+
+  describe '#rest' do
+    before { client.apply_stressor(description: 'stress', intensity: 0.9, duration: 7200) }
+
+    it 'increases integrity' do
+      before = client.integrity_status[:integrity]
+      client.rest(amount: 1.0)
+      after = client.integrity_status[:integrity]
+      expect(after).to be >= before
+    end
+
+    it 'returns a hash with integrity' do
+      result = client.rest(amount: 1.0)
+      expect(result).to have_key(:integrity)
+    end
+  end
+
+  describe '#weathering_report' do
+    it 'returns a comprehensive report' do
+      report = client.weathering_report
+      expect(report).to have_key(:integrity)
+      expect(report).to have_key(:integrity_label)
+      expect(report).to have_key(:effective_capacity)
+    end
+
+    it 'reflects stressor history' do
+      client.apply_stressor(description: 'first', intensity: 0.5, duration: 3600)
+      report = client.weathering_report
+      expect(report[:stressor_count]).to eq(1)
+    end
+  end
+
+  describe '#integrity_status' do
+    it 'returns all status keys' do
+      status = client.integrity_status
+      expect(status).to have_key(:integrity)
+      expect(status).to have_key(:integrity_label)
+      expect(status).to have_key(:tempering_level)
+      expect(status).to have_key(:weathering_label)
+      expect(status).to have_key(:effective_capacity)
+      expect(status).to have_key(:fragile)
+      expect(status).to have_key(:breaking)
+    end
+
+    it 'starts at pristine with full integrity' do
+      status = client.integrity_status
+      expect(status[:integrity_label]).to eq('pristine')
+      expect(status[:integrity]).to eq(1.0)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+module Legion
+  module Logging
+    def self.debug(_msg); end
+    def self.info(_msg); end
+    def self.warn(_msg); end
+    def self.error(_msg); end
+  end
+end
+
+require 'legion/extensions/cognitive_weathering'
+
+RSpec.configure do |config|
+  config.example_status_persistence_file_path = '.rspec_status'
+  config.disable_monkey_patching!
+  config.expect_with(:rspec) { |c| c.syntax = :expect }
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: lex-cognitive-weathering
+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: Models long-term cognitive wear from sustained workloads based on allostatic
+  load theory
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENSE
+- README.md
+- lex-cognitive-weathering.gemspec
+- lib/legion/extensions/cognitive_weathering.rb
+- lib/legion/extensions/cognitive_weathering/client.rb
+- lib/legion/extensions/cognitive_weathering/helpers/constants.rb
+- lib/legion/extensions/cognitive_weathering/helpers/stressor.rb
+- lib/legion/extensions/cognitive_weathering/helpers/weathering_engine.rb
+- lib/legion/extensions/cognitive_weathering/runners/cognitive_weathering.rb
+- lib/legion/extensions/cognitive_weathering/version.rb
+- spec/legion/extensions/cognitive_weathering/client_spec.rb
+- spec/legion/extensions/cognitive_weathering/helpers/constants_spec.rb
+- spec/legion/extensions/cognitive_weathering/helpers/stressor_spec.rb
+- spec/legion/extensions/cognitive_weathering/helpers/weathering_engine_spec.rb
+- spec/legion/extensions/cognitive_weathering/runners/cognitive_weathering_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-cognitive-weathering
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-cognitive-weathering
+  source_code_uri: https://github.com/LegionIO/lex-cognitive-weathering
+  documentation_uri: https://github.com/LegionIO/lex-cognitive-weathering
+  changelog_uri: https://github.com/LegionIO/lex-cognitive-weathering
+  bug_tracker_uri: https://github.com/LegionIO/lex-cognitive-weathering/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: LEX Cognitive Weathering
+test_files: []