lex-cognitive-surplus 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4d1218ba7a84db0e3fce82ba7d687bc72d748be64f25685f533ac917bb2f2d7e
+  data.tar.gz: 54e81c8dbf7544966cbb68a8d9bcd0452743cb65692ae2ba49c5a15937ba9193
+SHA512:
+  metadata.gz: 23b974597e6d8e95cf1a41542be23b73f381c886d4093b04b320e24f63be5aa610247e70d044d34de0e1799cd39c194a1d4f0aa8c094d2c50f168daafab48ef0
+  data.tar.gz: a644352549a5675bdaf311ad9e7e695ce1b3a96ffbdc639e456c8d6703466518d9b957e1dee3edc7f70d41f78460f0e369ad7a5e919316c35654332fff6e361e

data/Gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rspec', '~> 3.13'
+gem 'rubocop', '~> 1.75', require: false
+gem 'rubocop-rspec', require: false
+
+gem 'legion-gaia', path: '../../legion-gaia'

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Iverson
+
+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,65 @@
+# lex-cognitive-surplus
+
+A LegionIO cognitive architecture extension that models cognitive surplus — the available mental bandwidth beyond what is committed to current tasks. Capacity can be committed, allocated to named activities, and automatically replenished over time.
+
+## What It Does
+
+Tracks a single cognitive capacity pool (total = 1.0) divided into three layers:
+
+- **Committed**: capacity actively consumed by ongoing work
+- **Reserved**: baseline always held back (0.1) — never allocatable
+- **Active allocations**: named reservations for specific activity types
+
+Available surplus is what remains after all three. When surplus falls below 0.15 (the threshold), no new allocations are accepted. The built-in actor replenishes capacity automatically every 60 seconds by reducing committed load.
+
+## Usage
+
+```ruby
+require 'lex-cognitive-surplus'
+
+client = Legion::Extensions::CognitiveSurplus::Client.new
+
+# Check current surplus
+client.surplus_status
+# => { available_surplus: 0.9, surplus_label: :abundant, quality: 1.0, quality_label: :peak, ... }
+
+# Commit capacity to a task
+client.commit_capacity(amount: 0.4)
+# => { committed: 0.4, available_surplus: 0.5 }
+
+# Allocate some surplus for exploration
+result = client.allocate_surplus(activity_type: :exploration, amount: 0.2)
+# => { allocated: true, allocation_id: "uuid...", amount: 0.2, quality: 0.6, activity_type: :exploration }
+
+# Release the allocation when done
+client.release_surplus(allocation_id: result[:allocation_id])
+# => { released: true, allocation_id: "uuid...", amount: 0.2 }
+
+# Uncommit task capacity when work is finished
+client.uncommit_capacity(amount: 0.4)
+# => { committed: 0.0, available_surplus: 0.9 }
+
+# Simulate a demanding event depleting surplus
+client.deplete_surplus(amount: 0.3)
+# => { depleted: true, amount: 0.3, available_surplus: 0.6 }
+
+# Manually trigger replenishment (also fires automatically every 60s)
+client.replenish_surplus
+# => { replenished: true, gained: 0.05, available_surplus: 0.65 }
+
+# List active allocations
+client.surplus_allocations
+# => { allocations: [...], count: 0 }
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-cognitive-surplus.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_surplus/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-surplus'
+  spec.version       = Legion::Extensions::CognitiveSurplus::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Cognitive Surplus'
+  spec.description   = 'Cognitive surplus capacity modeling for brain-modeled agentic AI'
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-surplus'
+  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-surplus'
+  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-cognitive-surplus'
+  spec.metadata['changelog_uri']     = 'https://github.com/LegionIO/lex-cognitive-surplus'
+  spec.metadata['bug_tracker_uri']   = 'https://github.com/LegionIO/lex-cognitive-surplus/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-cognitive-surplus.gemspec Gemfile LICENSE README.md]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

data/lib/legion/extensions/cognitive_surplus/actors/replenish.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module CognitiveSurplus
+      module Actor
+        class Replenish < Legion::Extensions::Actors::Every
+          def runner_class
+            Legion::Extensions::CognitiveSurplus::Runners::Surplus
+          end
+
+          def runner_function
+            'replenish_surplus'
+          end
+
+          def time
+            60
+          end
+
+          def run_now?
+            false
+          end
+
+          def use_runner?
+            false
+          end
+
+          def check_subtask?
+            false
+          end
+
+          def generate_task?
+            false
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_surplus/helpers/constants'
+require 'legion/extensions/cognitive_surplus/helpers/allocation'
+require 'legion/extensions/cognitive_surplus/helpers/surplus_engine'
+require 'legion/extensions/cognitive_surplus/runners/surplus'
+
+module Legion
+  module Extensions
+    module CognitiveSurplus
+      class Client
+        include Runners::Surplus
+
+        def initialize(**)
+          @surplus_engine = Helpers::SurplusEngine.new
+        end
+
+        private
+
+        attr_reader :surplus_engine
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_surplus/helpers/allocation.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveSurplus
+      module Helpers
+        class Allocation
+          attr_reader :id, :activity_type, :amount, :quality, :created_at
+
+          def initialize(activity_type:, amount:, quality:)
+            @id            = SecureRandom.uuid
+            @activity_type = activity_type
+            @amount        = amount.round(10)
+            @quality       = quality.round(10)
+            @created_at    = Time.now.utc
+            @released      = false
+          end
+
+          def release!
+            @released = true
+          end
+
+          def active?
+            !@released
+          end
+
+          def to_h
+            {
+              id:            @id,
+              activity_type: @activity_type,
+              amount:        @amount,
+              quality:       @quality,
+              active:        active?,
+              created_at:    @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveSurplus
+      module Helpers
+        module Constants
+          TOTAL_CAPACITY   = 1.0
+          MIN_RESERVE      = 0.1
+          SURPLUS_THRESHOLD = 0.15
+          REPLENISH_RATE   = 0.05
+          DEPLETION_RATE   = 0.08
+
+          SURPLUS_LABELS = {
+            abundant: (0.6..1.0),
+            moderate: (0.3...0.6),
+            scarce:   (0.15...0.3),
+            depleted: (0.0...0.15)
+          }.freeze
+
+          QUALITY_LABELS = {
+            peak:     (0.8..1.0),
+            rested:   (0.6...0.8),
+            residual: (0.3...0.6),
+            degraded: (0.0...0.3)
+          }.freeze
+
+          ALLOCATION_TYPES = %i[exploration consolidation speculation maintenance creative].freeze
+
+          module_function
+
+          def surplus_label(amount)
+            SURPLUS_LABELS.find { |_label, range| range.cover?(amount) }&.first || :none
+          end
+
+          def quality_label(quality)
+            QUALITY_LABELS.find { |_label, range| range.cover?(quality) }&.first || :unknown
+          end
+
+          def valid_allocation_type?(type)
+            ALLOCATION_TYPES.include?(type)
+          end
+
+          def clamp(value, min = 0.0, max = 1.0)
+            value.clamp(min, max)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_surplus/helpers/surplus_engine.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveSurplus
+      module Helpers
+        class SurplusEngine
+          include Constants
+
+          attr_reader :committed, :reserved, :allocations
+
+          def initialize
+            @committed   = 0.0
+            @reserved    = Constants::MIN_RESERVE
+            @allocations = {}
+          end
+
+          def available_surplus
+            used = @committed + @reserved + active_allocated
+            Constants.clamp(Constants::TOTAL_CAPACITY - used).round(10)
+          end
+
+          def surplus_quality
+            idle = Constants::TOTAL_CAPACITY - @committed
+            raw = idle / Constants::TOTAL_CAPACITY
+            Constants.clamp(raw).round(10)
+          end
+
+          def allocate!(activity_type:, amount:)
+            return { allocated: false, reason: :invalid_type } unless Constants.valid_allocation_type?(activity_type)
+            return { allocated: false, reason: :below_threshold } if available_surplus < Constants::SURPLUS_THRESHOLD
+
+            clamped = Constants.clamp(amount, 0.0, available_surplus).round(10)
+            return { allocated: false, reason: :insufficient_surplus } if clamped <= 0.0
+
+            quality = surplus_quality
+            allocation = Allocation.new(activity_type: activity_type, amount: clamped, quality: quality)
+            @allocations[allocation.id] = allocation
+
+            {
+              allocated:     true,
+              allocation_id: allocation.id,
+              amount:        clamped,
+              quality:       quality,
+              activity_type: activity_type
+            }
+          end
+
+          def release!(allocation_id:)
+            allocation = @allocations[allocation_id]
+            return { released: false, reason: :not_found } unless allocation
+            return { released: false, reason: :already_released } unless allocation.active?
+
+            allocation.release!
+            { released: true, allocation_id: allocation_id, amount: allocation.amount }
+          end
+
+          def commit!(amount:)
+            clamped = Constants.clamp(amount.round(10), 0.0, Constants::TOTAL_CAPACITY - @reserved)
+            @committed = Constants.clamp((@committed + clamped).round(10))
+            { committed: @committed, available_surplus: available_surplus }
+          end
+
+          def uncommit!(amount:)
+            clamped = Constants.clamp(amount.round(10), 0.0, @committed)
+            @committed = Constants.clamp((@committed - clamped).round(10))
+            { committed: @committed, available_surplus: available_surplus }
+          end
+
+          def replenish!
+            old_committed = @committed
+            @committed = Constants.clamp((@committed - Constants::REPLENISH_RATE).round(10))
+            gained = (old_committed - @committed).round(10)
+            { replenished: true, gained: gained, available_surplus: available_surplus }
+          end
+
+          def deplete!(amount:)
+            delta = Constants.clamp(amount.round(10), 0.0, available_surplus)
+            @committed = Constants.clamp((@committed + delta).round(10))
+            { depleted: true, amount: delta, available_surplus: available_surplus }
+          end
+
+          def surplus_report
+            surplus = available_surplus
+            {
+              total_capacity:    Constants::TOTAL_CAPACITY,
+              committed:         @committed.round(10),
+              reserved:          @reserved.round(10),
+              active_allocated:  active_allocated.round(10),
+              available_surplus: surplus,
+              surplus_label:     Constants.surplus_label(surplus),
+              quality:           surplus_quality,
+              quality_label:     Constants.quality_label(surplus_quality),
+              allocation_count:  active_allocations.size
+            }
+          end
+
+          def to_h
+            surplus_report.merge(allocations: @allocations.transform_values(&:to_h))
+          end
+
+          private
+
+          def active_allocations
+            @allocations.values.select(&:active?)
+          end
+
+          def active_allocated
+            active_allocations.sum(&:amount)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_surplus/runners/surplus.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveSurplus
+      module Runners
+        module Surplus
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def surplus_status(**)
+            report = surplus_engine.surplus_report
+            Legion::Logging.debug "[cognitive_surplus] status surplus=#{report[:available_surplus].round(2)} " \
+                                  "label=#{report[:surplus_label]} quality=#{report[:quality_label]}"
+            report
+          end
+
+          def allocate_surplus(activity_type:, amount: Helpers::Constants::SURPLUS_THRESHOLD, **)
+            result = surplus_engine.allocate!(activity_type: activity_type, amount: amount)
+            if result[:allocated]
+              Legion::Logging.info "[cognitive_surplus] allocated #{amount.round(2)} to " \
+                                   "#{activity_type} quality=#{result[:quality].round(2)} id=#{result[:allocation_id][0..7]}"
+            else
+              Legion::Logging.debug "[cognitive_surplus] allocate failed: #{result[:reason]}"
+            end
+            result
+          end
+
+          def release_surplus(allocation_id:, **)
+            result = surplus_engine.release!(allocation_id: allocation_id)
+            if result[:released]
+              Legion::Logging.info "[cognitive_surplus] released allocation #{allocation_id[0..7]} amount=#{result[:amount].round(2)}"
+            else
+              Legion::Logging.debug "[cognitive_surplus] release failed: #{result[:reason]} id=#{allocation_id[0..7]}"
+            end
+            result
+          end
+
+          def commit_capacity(amount:, **)
+            result = surplus_engine.commit!(amount: amount)
+            Legion::Logging.debug "[cognitive_surplus] committed #{amount.round(2)} committed=#{result[:committed].round(2)} " \
+                                  "surplus=#{result[:available_surplus].round(2)}"
+            result
+          end
+
+          def uncommit_capacity(amount:, **)
+            result = surplus_engine.uncommit!(amount: amount)
+            Legion::Logging.debug "[cognitive_surplus] uncommitted #{amount.round(2)} committed=#{result[:committed].round(2)} " \
+                                  "surplus=#{result[:available_surplus].round(2)}"
+            result
+          end
+
+          def replenish_surplus(**)
+            result = surplus_engine.replenish!
+            Legion::Logging.debug "[cognitive_surplus] replenished gained=#{result[:gained].round(2)} " \
+                                  "surplus=#{result[:available_surplus].round(2)}"
+            result
+          end
+
+          def deplete_surplus(amount:, **)
+            result = surplus_engine.deplete!(amount: amount)
+            Legion::Logging.debug "[cognitive_surplus] depleted amount=#{result[:amount].round(2)} " \
+                                  "surplus=#{result[:available_surplus].round(2)}"
+            result
+          end
+
+          def surplus_allocations(**)
+            allocations = surplus_engine.allocations.values.select(&:active?).map(&:to_h)
+            Legion::Logging.debug "[cognitive_surplus] allocations count=#{allocations.size}"
+            { allocations: allocations, count: allocations.size }
+          end
+
+          private
+
+          def surplus_engine
+            @surplus_engine ||= Helpers::SurplusEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/cognitive_surplus.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_surplus/version'
+require 'legion/extensions/cognitive_surplus/helpers/constants'
+require 'legion/extensions/cognitive_surplus/helpers/allocation'
+require 'legion/extensions/cognitive_surplus/helpers/surplus_engine'
+require 'legion/extensions/cognitive_surplus/runners/surplus'
+
+module Legion
+  module Extensions
+    module CognitiveSurplus
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_surplus/client'
+
+RSpec.describe Legion::Extensions::CognitiveSurplus::Client do
+  it 'responds to surplus runner methods' do
+    client = described_class.new
+    expect(client).to respond_to(:surplus_status)
+    expect(client).to respond_to(:allocate_surplus)
+    expect(client).to respond_to(:release_surplus)
+    expect(client).to respond_to(:commit_capacity)
+    expect(client).to respond_to(:uncommit_capacity)
+    expect(client).to respond_to(:replenish_surplus)
+    expect(client).to respond_to(:deplete_surplus)
+    expect(client).to respond_to(:surplus_allocations)
+  end
+end

data/spec/legion/extensions/cognitive_surplus/helpers/allocation_spec.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::CognitiveSurplus::Helpers::Allocation do
+  subject(:allocation) { described_class.new(activity_type: :exploration, amount: 0.2, quality: 0.75) }
+
+  describe '#initialize' do
+    it 'assigns a uuid id' do
+      expect(allocation.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores activity_type' do
+      expect(allocation.activity_type).to eq(:exploration)
+    end
+
+    it 'rounds amount to 10 decimal places' do
+      expect(allocation.amount).to eq(0.2)
+    end
+
+    it 'rounds quality to 10 decimal places' do
+      expect(allocation.quality).to eq(0.75)
+    end
+
+    it 'sets created_at' do
+      expect(allocation.created_at).to be_a(Time)
+    end
+
+    it 'starts active' do
+      expect(allocation.active?).to be true
+    end
+  end
+
+  describe '#release!' do
+    it 'deactivates the allocation' do
+      allocation.release!
+      expect(allocation.active?).to be false
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with expected keys' do
+      h = allocation.to_h
+      expect(h).to include(:id, :activity_type, :amount, :quality, :active, :created_at)
+    end
+
+    it 'reflects active state' do
+      expect(allocation.to_h[:active]).to be true
+      allocation.release!
+      expect(allocation.to_h[:active]).to be false
+    end
+  end
+end

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

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::CognitiveSurplus::Helpers::Constants do
+  describe 'constants' do
+    it 'defines TOTAL_CAPACITY as 1.0' do
+      expect(described_class::TOTAL_CAPACITY).to eq(1.0)
+    end
+
+    it 'defines MIN_RESERVE as 0.1' do
+      expect(described_class::MIN_RESERVE).to eq(0.1)
+    end
+
+    it 'defines SURPLUS_THRESHOLD as 0.15' do
+      expect(described_class::SURPLUS_THRESHOLD).to eq(0.15)
+    end
+
+    it 'defines REPLENISH_RATE as 0.05' do
+      expect(described_class::REPLENISH_RATE).to eq(0.05)
+    end
+
+    it 'defines DEPLETION_RATE as 0.08' do
+      expect(described_class::DEPLETION_RATE).to eq(0.08)
+    end
+
+    it 'defines all ALLOCATION_TYPES' do
+      expect(described_class::ALLOCATION_TYPES).to include(:exploration, :consolidation, :speculation, :maintenance, :creative)
+    end
+  end
+
+  describe '.surplus_label' do
+    it 'returns :abundant for high surplus' do
+      expect(described_class.surplus_label(0.8)).to eq(:abundant)
+    end
+
+    it 'returns :moderate for moderate surplus' do
+      expect(described_class.surplus_label(0.4)).to eq(:moderate)
+    end
+
+    it 'returns :scarce for scarce surplus' do
+      expect(described_class.surplus_label(0.2)).to eq(:scarce)
+    end
+
+    it 'returns :depleted for very low surplus' do
+      expect(described_class.surplus_label(0.05)).to eq(:depleted)
+    end
+
+    it 'returns :none for zero surplus' do
+      expect(described_class.surplus_label(0.0)).to eq(:depleted)
+    end
+  end
+
+  describe '.quality_label' do
+    it 'returns :peak for high quality' do
+      expect(described_class.quality_label(0.9)).to eq(:peak)
+    end
+
+    it 'returns :rested for good quality' do
+      expect(described_class.quality_label(0.7)).to eq(:rested)
+    end
+
+    it 'returns :residual for moderate quality' do
+      expect(described_class.quality_label(0.4)).to eq(:residual)
+    end
+
+    it 'returns :degraded for low quality' do
+      expect(described_class.quality_label(0.1)).to eq(:degraded)
+    end
+  end
+
+  describe '.valid_allocation_type?' do
+    it 'returns true for valid types' do
+      expect(described_class.valid_allocation_type?(:exploration)).to be true
+      expect(described_class.valid_allocation_type?(:creative)).to be true
+    end
+
+    it 'returns false for invalid types' do
+      expect(described_class.valid_allocation_type?(:unknown)).to be false
+    end
+  end
+
+  describe '.clamp' do
+    it 'clamps to [0.0, 1.0] by default' do
+      expect(described_class.clamp(1.5)).to eq(1.0)
+      expect(described_class.clamp(-0.5)).to eq(0.0)
+      expect(described_class.clamp(0.5)).to eq(0.5)
+    end
+  end
+end

data/spec/legion/extensions/cognitive_surplus/helpers/surplus_engine_spec.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::CognitiveSurplus::Helpers::SurplusEngine do
+  subject(:engine) { described_class.new }
+
+  describe '#available_surplus' do
+    it 'starts at TOTAL_CAPACITY minus MIN_RESERVE' do
+      expected = (Legion::Extensions::CognitiveSurplus::Helpers::Constants::TOTAL_CAPACITY -
+                  Legion::Extensions::CognitiveSurplus::Helpers::Constants::MIN_RESERVE).round(10)
+      expect(engine.available_surplus).to eq(expected)
+    end
+
+    it 'decreases after commit' do
+      before = engine.available_surplus
+      engine.commit!(amount: 0.2)
+      expect(engine.available_surplus).to be < before
+    end
+  end
+
+  describe '#surplus_quality' do
+    it 'returns 1.0 when nothing is committed' do
+      expect(engine.surplus_quality).to eq(1.0)
+    end
+
+    it 'decreases as committed increases' do
+      engine.commit!(amount: 0.5)
+      expect(engine.surplus_quality).to be < 1.0
+    end
+  end
+
+  describe '#allocate!' do
+    it 'returns allocated: true for valid type with sufficient surplus' do
+      result = engine.allocate!(activity_type: :exploration, amount: 0.1)
+      expect(result[:allocated]).to be true
+      expect(result[:allocation_id]).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'returns error for invalid allocation type' do
+      result = engine.allocate!(activity_type: :invalid, amount: 0.1)
+      expect(result[:allocated]).to be false
+      expect(result[:reason]).to eq(:invalid_type)
+    end
+
+    it 'returns below_threshold when surplus is too low' do
+      engine.commit!(amount: 0.9)
+      result = engine.allocate!(activity_type: :exploration, amount: 0.05)
+      expect(result[:allocated]).to be false
+      expect(result[:reason]).to eq(:below_threshold)
+    end
+
+    it 'includes quality in result' do
+      result = engine.allocate!(activity_type: :creative, amount: 0.1)
+      expect(result[:quality]).to be_between(0.0, 1.0)
+    end
+  end
+
+  describe '#release!' do
+    it 'releases an active allocation' do
+      alloc = engine.allocate!(activity_type: :consolidation, amount: 0.1)
+      result = engine.release!(allocation_id: alloc[:allocation_id])
+      expect(result[:released]).to be true
+    end
+
+    it 'returns not_found for unknown id' do
+      result = engine.release!(allocation_id: 'nonexistent')
+      expect(result[:released]).to be false
+      expect(result[:reason]).to eq(:not_found)
+    end
+
+    it 'returns already_released for double release' do
+      alloc = engine.allocate!(activity_type: :speculation, amount: 0.1)
+      engine.release!(allocation_id: alloc[:allocation_id])
+      result = engine.release!(allocation_id: alloc[:allocation_id])
+      expect(result[:released]).to be false
+      expect(result[:reason]).to eq(:already_released)
+    end
+  end
+
+  describe '#commit!' do
+    it 'increases committed and decreases surplus' do
+      surplus_before = engine.available_surplus
+      result = engine.commit!(amount: 0.3)
+      expect(result[:committed]).to eq(0.3)
+      expect(result[:available_surplus]).to be < surplus_before
+    end
+  end
+
+  describe '#uncommit!' do
+    it 'decreases committed and increases surplus' do
+      engine.commit!(amount: 0.4)
+      committed_before = engine.committed
+      result = engine.uncommit!(amount: 0.2)
+      expect(result[:committed]).to be < committed_before
+    end
+
+    it 'does not go below zero' do
+      result = engine.uncommit!(amount: 1.0)
+      expect(result[:committed]).to eq(0.0)
+    end
+  end
+
+  describe '#replenish!' do
+    it 'reduces committed by REPLENISH_RATE' do
+      engine.commit!(amount: 0.5)
+      before = engine.committed
+      engine.replenish!
+      expect(engine.committed).to be < before
+    end
+
+    it 'returns gained amount' do
+      engine.commit!(amount: 0.3)
+      result = engine.replenish!
+      expect(result[:gained]).to eq(Legion::Extensions::CognitiveSurplus::Helpers::Constants::REPLENISH_RATE)
+    end
+
+    it 'does not go below zero committed' do
+      engine.replenish!
+      expect(engine.committed).to eq(0.0)
+    end
+  end
+
+  describe '#deplete!' do
+    it 'increases committed by amount' do
+      before = engine.committed
+      engine.deplete!(amount: 0.1)
+      expect(engine.committed).to be > before
+    end
+
+    it 'does not exceed available surplus' do
+      result = engine.deplete!(amount: 2.0)
+      expect(engine.available_surplus).to be >= 0.0
+      expect(result[:depleted]).to be true
+    end
+  end
+
+  describe '#surplus_report' do
+    it 'returns all required fields' do
+      report = engine.surplus_report
+      expect(report).to include(
+        :total_capacity, :committed, :reserved, :active_allocated,
+        :available_surplus, :surplus_label, :quality, :quality_label, :allocation_count
+      )
+    end
+
+    it 'surplus_label reflects current amount' do
+      report = engine.surplus_report
+      expect(report[:surplus_label]).to be_a(Symbol)
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes allocations hash' do
+      engine.allocate!(activity_type: :maintenance, amount: 0.1)
+      h = engine.to_h
+      expect(h[:allocations]).to be_a(Hash)
+      expect(h[:allocations].size).to eq(1)
+    end
+  end
+end

data/spec/legion/extensions/cognitive_surplus/runners/surplus_spec.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_surplus/client'
+
+RSpec.describe Legion::Extensions::CognitiveSurplus::Runners::Surplus do
+  let(:client) { Legion::Extensions::CognitiveSurplus::Client.new }
+
+  describe '#surplus_status' do
+    it 'returns a surplus report hash' do
+      result = client.surplus_status
+      expect(result).to include(:available_surplus, :surplus_label, :quality, :quality_label)
+    end
+
+    it 'available_surplus is between 0 and 1' do
+      result = client.surplus_status
+      expect(result[:available_surplus]).to be_between(0.0, 1.0)
+    end
+  end
+
+  describe '#allocate_surplus' do
+    it 'allocates surplus for a valid activity type' do
+      result = client.allocate_surplus(activity_type: :exploration, amount: 0.1)
+      expect(result[:allocated]).to be true
+      expect(result[:allocation_id]).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'returns error for invalid activity type' do
+      result = client.allocate_surplus(activity_type: :bogus, amount: 0.1)
+      expect(result[:allocated]).to be false
+    end
+
+    it 'uses default amount of SURPLUS_THRESHOLD' do
+      result = client.allocate_surplus(activity_type: :creative)
+      expect(result[:allocated]).to be true
+    end
+  end
+
+  describe '#release_surplus' do
+    it 'releases an active allocation' do
+      alloc = client.allocate_surplus(activity_type: :consolidation, amount: 0.1)
+      result = client.release_surplus(allocation_id: alloc[:allocation_id])
+      expect(result[:released]).to be true
+    end
+
+    it 'returns not_found for unknown allocation id' do
+      result = client.release_surplus(allocation_id: 'no-such-id')
+      expect(result[:released]).to be false
+      expect(result[:reason]).to eq(:not_found)
+    end
+  end
+
+  describe '#commit_capacity' do
+    it 'commits capacity and reduces available surplus' do
+      before = client.surplus_status[:available_surplus]
+      client.commit_capacity(amount: 0.2)
+      after = client.surplus_status[:available_surplus]
+      expect(after).to be < before
+    end
+  end
+
+  describe '#uncommit_capacity' do
+    it 'uncommits capacity and increases available surplus' do
+      client.commit_capacity(amount: 0.3)
+      before = client.surplus_status[:available_surplus]
+      client.uncommit_capacity(amount: 0.15)
+      after = client.surplus_status[:available_surplus]
+      expect(after).to be > before
+    end
+  end
+
+  describe '#replenish_surplus' do
+    it 'returns replenished: true' do
+      result = client.replenish_surplus
+      expect(result[:replenished]).to be true
+    end
+
+    it 'includes gained amount' do
+      client.commit_capacity(amount: 0.3)
+      result = client.replenish_surplus
+      expect(result[:gained]).to be >= 0.0
+    end
+  end
+
+  describe '#deplete_surplus' do
+    it 'reduces available surplus' do
+      before = client.surplus_status[:available_surplus]
+      client.deplete_surplus(amount: 0.1)
+      after = client.surplus_status[:available_surplus]
+      expect(after).to be < before
+    end
+
+    it 'returns depleted: true' do
+      result = client.deplete_surplus(amount: 0.05)
+      expect(result[:depleted]).to be true
+    end
+  end
+
+  describe '#surplus_allocations' do
+    it 'returns empty allocations initially' do
+      result = client.surplus_allocations
+      expect(result[:count]).to eq(0)
+      expect(result[:allocations]).to eq([])
+    end
+
+    it 'lists active allocations' do
+      client.allocate_surplus(activity_type: :speculation, amount: 0.1)
+      client.allocate_surplus(activity_type: :maintenance, amount: 0.1)
+      result = client.surplus_allocations
+      expect(result[:count]).to eq(2)
+    end
+
+    it 'excludes released allocations' do
+      alloc = client.allocate_surplus(activity_type: :exploration, amount: 0.1)
+      client.release_surplus(allocation_id: alloc[:allocation_id])
+      result = client.surplus_allocations
+      expect(result[:count]).to eq(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_surplus'
+
+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-surplus
+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 surplus capacity modeling for brain-modeled agentic AI
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENSE
+- README.md
+- lex-cognitive-surplus.gemspec
+- lib/legion/extensions/cognitive_surplus.rb
+- lib/legion/extensions/cognitive_surplus/actors/replenish.rb
+- lib/legion/extensions/cognitive_surplus/client.rb
+- lib/legion/extensions/cognitive_surplus/helpers/allocation.rb
+- lib/legion/extensions/cognitive_surplus/helpers/constants.rb
+- lib/legion/extensions/cognitive_surplus/helpers/surplus_engine.rb
+- lib/legion/extensions/cognitive_surplus/runners/surplus.rb
+- lib/legion/extensions/cognitive_surplus/version.rb
+- spec/legion/extensions/cognitive_surplus/client_spec.rb
+- spec/legion/extensions/cognitive_surplus/helpers/allocation_spec.rb
+- spec/legion/extensions/cognitive_surplus/helpers/constants_spec.rb
+- spec/legion/extensions/cognitive_surplus/helpers/surplus_engine_spec.rb
+- spec/legion/extensions/cognitive_surplus/runners/surplus_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-cognitive-surplus
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-cognitive-surplus
+  source_code_uri: https://github.com/LegionIO/lex-cognitive-surplus
+  documentation_uri: https://github.com/LegionIO/lex-cognitive-surplus
+  changelog_uri: https://github.com/LegionIO/lex-cognitive-surplus
+  bug_tracker_uri: https://github.com/LegionIO/lex-cognitive-surplus/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 Surplus
+test_files: []