lex-executive-function 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a4565c3fb85be0d4ccb78af546011ba3d3885bc4a10ea3a73e5a59aca63b192a
+  data.tar.gz: d6769fd5f1683e6afe74d1e1674a143ea8868a6e4dbf8a0ec903cbd6a41e5c9f
+SHA512:
+  metadata.gz: 323661ea3d66d9a3b5b55321f12b4b0a9a75188c3f3e02b46e2a75834ea93053b9dac99fed473dc78451ed3b89cb1e884c18edd9f8a3dece9639b5ed5f76d74d
+  data.tar.gz: 1755111a87ce6f198de1a0fb0eac3d76fd6f59850c6b90077c1d31cd0c8eb8e1416019b7b2026abda6841b9fb4f18b9e250a673ebf58f79dab644c831d4afcdd

data/Gemfile

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

data/lex-executive-function.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/executive_function/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-executive-function'
+  spec.version       = Legion::Extensions::ExecutiveFunction::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Executive Function'
+  spec.description   = 'Miyake & Friedman (2000, 2012) unity/diversity model of executive functions: ' \
+                       'inhibition, shifting, and working memory updating'
+  spec.homepage      = 'https://github.com/LegionIO/lex-executive-function'
+  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-executive-function'
+  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-executive-function'
+  spec.metadata['changelog_uri']     = 'https://github.com/LegionIO/lex-executive-function'
+  spec.metadata['bug_tracker_uri']   = 'https://github.com/LegionIO/lex-executive-function/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-executive-function.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

data/lib/legion/extensions/executive_function/actors/recovery.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module ExecutiveFunction
+      module Actor
+        class Recovery < Legion::Extensions::Actors::Every
+          def runner_class
+            Legion::Extensions::ExecutiveFunction::Runners::ExecutiveFunction
+          end
+
+          def runner_function
+            'executive_function_stats'
+          end
+
+          def time
+            30
+          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/executive_function/client.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/executive_function/helpers/ef_component'
+require 'legion/extensions/executive_function/helpers/executive_controller'
+require 'legion/extensions/executive_function/runners/executive_function'
+
+module Legion
+  module Extensions
+    module ExecutiveFunction
+      class Client
+        include Runners::ExecutiveFunction
+
+        def initialize(**)
+          @controller = Helpers::ExecutiveController.new
+        end
+
+        private
+
+        attr_reader :controller
+      end
+    end
+  end
+end

data/lib/legion/extensions/executive_function/helpers/ef_component.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module ExecutiveFunction
+      module Helpers
+        class EfComponent
+          DEFAULT_CAPACITY = 0.7
+          CAPACITY_FLOOR   = 0.1
+          CAPACITY_CEILING = 1.0
+          RECOVERY_RATE    = 0.02
+
+          attr_reader :name, :capacity, :fatigue, :recent_uses
+
+          def initialize(name:, capacity: DEFAULT_CAPACITY)
+            @name        = name
+            @capacity    = capacity.clamp(CAPACITY_FLOOR, CAPACITY_CEILING)
+            @fatigue     = 0.0
+            @recent_uses = []
+          end
+
+          def use(cost:)
+            @fatigue = [@fatigue + cost, capacity].min
+            @recent_uses << { used_at: Time.now.utc, cost: cost }
+            @recent_uses = @recent_uses.last(50)
+          end
+
+          def recover
+            @fatigue = [@fatigue - RECOVERY_RATE, 0.0].max
+          end
+
+          def effective_capacity
+            [@capacity - @fatigue, CAPACITY_FLOOR].max
+          end
+
+          def fatigued?
+            effective_capacity <= CAPACITY_FLOOR + 0.05
+          end
+
+          def to_h
+            {
+              name:               @name,
+              capacity:           @capacity,
+              fatigue:            @fatigue.round(4),
+              effective_capacity: effective_capacity.round(4),
+              fatigued:           fatigued?,
+              recent_use_count:   @recent_uses.size
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/executive_function/helpers/executive_controller.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module ExecutiveFunction
+      module Helpers
+        class ExecutiveController
+          EF_COMPONENTS    = %i[inhibition shifting updating].freeze
+          COMMON_EF_WEIGHT = 0.4
+          SWITCH_COST      = 0.15
+          INHIBITION_COST  = 0.1
+          UPDATE_COST      = 0.08
+          FATIGUE_RATE     = 0.01
+          CAPACITY_ALPHA   = 0.12
+          MAX_TASK_HISTORY = 200
+          MAX_INHIBITIONS = 100
+
+          attr_reader :current_task_set, :task_history, :inhibition_log, :update_log
+
+          def initialize
+            @components = EF_COMPONENTS.to_h { |n| [n, EfComponent.new(name: n)] }
+            @current_task_set = nil
+            @task_history    = []
+            @inhibition_log  = []
+            @update_log      = []
+          end
+
+          def inhibit(target:, reason:)
+            comp = @components[:inhibition]
+            return { success: false, reason: :insufficient_capacity } unless can_inhibit?
+
+            comp.use(cost: INHIBITION_COST)
+            apply_common_ef_fatigue(:inhibition)
+            entry = { target: target, reason: reason, suppressed_at: Time.now.utc,
+                      remaining_capacity: comp.effective_capacity }
+            @inhibition_log << entry
+            @inhibition_log = @inhibition_log.last(MAX_INHIBITIONS)
+            { success: true, target: target, remaining_capacity: comp.effective_capacity }
+          end
+
+          def shift_task(from:, to:)
+            comp = @components[:shifting]
+            return { success: false, reason: :insufficient_capacity } unless can_shift?
+
+            cost = same_task?(from, to) ? 0.0 : SWITCH_COST
+            comp.use(cost: cost)
+            apply_common_ef_fatigue(:shifting)
+
+            old_task = @current_task_set
+            @current_task_set = to
+            @task_history << { from: from, to: to, switched_at: Time.now.utc, switch_cost: cost }
+            @task_history = @task_history.last(MAX_TASK_HISTORY)
+
+            { success: true, from: old_task, to: to, switch_cost: cost,
+              remaining_capacity: comp.effective_capacity }
+          end
+
+          def update_wm(slot:, old_value:, new_value:)
+            comp = @components[:updating]
+            return { success: false, reason: :insufficient_capacity } unless can_update?
+
+            comp.use(cost: UPDATE_COST)
+            apply_common_ef_fatigue(:updating)
+            entry = { slot: slot, old_value: old_value, new_value: new_value,
+                      updated_at: Time.now.utc, remaining_capacity: comp.effective_capacity }
+            @update_log << entry
+            { success: true, slot: slot, old_value: old_value, new_value: new_value,
+              remaining_capacity: comp.effective_capacity }
+          end
+
+          def common_ef_level
+            values = @components.values.map(&:effective_capacity)
+            avg    = values.sum / values.size.to_f
+            (avg * (1.0 - COMMON_EF_WEIGHT)) + (avg * COMMON_EF_WEIGHT)
+          end
+
+          def can_inhibit?
+            !@components[:inhibition].fatigued?
+          end
+
+          def can_shift?
+            !@components[:shifting].fatigued?
+          end
+
+          def can_update?
+            !@components[:updating].fatigued?
+          end
+
+          def tick
+            @components.each_value(&:recover)
+          end
+
+          def component(name)
+            @components[name.to_sym]
+          end
+
+          def to_h
+            {
+              common_ef_level:   common_ef_level.round(4),
+              current_task_set:  @current_task_set,
+              components:        @components.transform_values(&:to_h),
+              task_history_size: @task_history.size,
+              inhibition_count:  @inhibition_log.size,
+              update_count:      @update_log.size
+            }
+          end
+
+          private
+
+          def same_task?(from, to)
+            from.to_s == to.to_s
+          end
+
+          def apply_common_ef_fatigue(primary)
+            EF_COMPONENTS.each do |name|
+              next if name == primary
+
+              @components[name].use(cost: FATIGUE_RATE)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module ExecutiveFunction
+      module Runners
+        module ExecutiveFunction
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def inhibit(target:, reason: :prepotent_response, **)
+            result = controller.inhibit(target: target, reason: reason)
+            Legion::Logging.debug "[executive_function] inhibit target=#{target} success=#{result[:success]}"
+            result
+          end
+
+          def shift_task(from:, to:, **)
+            result = controller.shift_task(from: from, to: to)
+            Legion::Logging.debug "[executive_function] shift from=#{from} to=#{to} " \
+                                  "cost=#{result[:switch_cost]&.round(3)} success=#{result[:success]}"
+            result
+          end
+
+          def update_wm(slot:, new_value:, old_value: nil, **)
+            result = controller.update_wm(slot: slot, old_value: old_value, new_value: new_value)
+            Legion::Logging.debug "[executive_function] update_wm slot=#{slot} success=#{result[:success]}"
+            result
+          end
+
+          def common_ef_status(**)
+            level = controller.common_ef_level
+            Legion::Logging.debug "[executive_function] common_ef_level=#{level.round(3)}"
+            { success: true, common_ef_level: level, components: controller.to_h[:components] }
+          end
+
+          def component_status(component:, **)
+            comp = controller.component(component)
+            return { success: false, reason: :unknown_component } unless comp
+
+            Legion::Logging.debug "[executive_function] component_status #{component} " \
+                                  "effective=#{comp.effective_capacity.round(3)}"
+            { success: true, component: comp.to_h }
+          end
+
+          def can_perform(operation:, **)
+            result = case operation.to_sym
+                     when :inhibit  then { can_perform: controller.can_inhibit? }
+                     when :shift    then { can_perform: controller.can_shift? }
+                     when :update   then { can_perform: controller.can_update? }
+                     else           { can_perform: false, reason: :unknown_operation }
+                     end
+            Legion::Logging.debug "[executive_function] can_perform #{operation} => #{result[:can_perform]}"
+            result.merge(success: true, operation: operation)
+          end
+
+          def task_switch_cost(from:, to:, **)
+            cost = from.to_s == to.to_s ? 0.0 : Helpers::ExecutiveController::SWITCH_COST
+            cap  = controller.component(:shifting)&.effective_capacity || 0.0
+            Legion::Logging.debug "[executive_function] task_switch_cost from=#{from} to=#{to} cost=#{cost}"
+            { success: true, from: from, to: to, switch_cost: cost, shifting_capacity: cap }
+          end
+
+          def executive_load(**)
+            stats = controller.to_h
+            comps = stats[:components]
+            load  = comps.values.sum { |c| c[:fatigue] } / comps.size.to_f
+            Legion::Logging.debug "[executive_function] executive_load=#{load.round(3)}"
+            { success: true, executive_load: load.round(4), common_ef_level: stats[:common_ef_level],
+              components: comps }
+          end
+
+          def update_executive_function(component:, capacity:, **)
+            comp = controller.component(component)
+            return { success: false, reason: :unknown_component } unless comp
+
+            clamped = capacity.to_f.clamp(
+              Helpers::EfComponent::CAPACITY_FLOOR,
+              Helpers::EfComponent::CAPACITY_CEILING
+            )
+            comp.instance_variable_set(:@capacity, clamped)
+            Legion::Logging.debug "[executive_function] update component=#{component} capacity=#{clamped}"
+            { success: true, component: component, new_capacity: clamped }
+          end
+
+          def executive_function_stats(**)
+            stats = controller.to_h
+            Legion::Logging.debug "[executive_function] stats common_ef=#{stats[:common_ef_level]}"
+            { success: true }.merge(stats)
+          end
+
+          private
+
+          def controller
+            @controller ||= Helpers::ExecutiveController.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/executive_function.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/executive_function/version'
+require 'legion/extensions/executive_function/helpers/ef_component'
+require 'legion/extensions/executive_function/helpers/executive_controller'
+require 'legion/extensions/executive_function/runners/executive_function'
+
+module Legion
+  module Extensions
+    module ExecutiveFunction
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/executive_function/client'
+
+RSpec.describe Legion::Extensions::ExecutiveFunction::Client do
+  let(:client) { described_class.new }
+
+  it 'responds to all runner methods' do
+    %i[inhibit shift_task update_wm common_ef_status component_status
+       can_perform task_switch_cost executive_load
+       update_executive_function executive_function_stats].each do |method|
+      expect(client).to respond_to(method)
+    end
+  end
+
+  it 'maintains state across calls' do
+    client.inhibit(target: :noise)
+    stats = client.executive_function_stats
+    expect(stats[:inhibition_count]).to eq(1)
+  end
+
+  it 'full round-trip: inhibit -> shift -> update -> stats' do
+    client.inhibit(target: :distraction, reason: :prepotent)
+    client.shift_task(from: :idle, to: :active)
+    client.update_wm(slot: :focus, new_value: :high)
+
+    stats = client.executive_function_stats
+    expect(stats[:success]).to be true
+    expect(stats[:inhibition_count]).to eq(1)
+    expect(stats[:task_history_size]).to eq(1)
+    expect(stats[:update_count]).to eq(1)
+    expect(stats[:current_task_set]).to eq(:active)
+  end
+
+  it 'common EF level decreases under load' do
+    initial = client.common_ef_status[:common_ef_level]
+    15.times { client.inhibit(target: :x) }
+    expect(client.common_ef_status[:common_ef_level]).to be <= initial
+  end
+end

data/spec/legion/extensions/executive_function/helpers/ef_component_spec.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/executive_function/helpers/ef_component'
+
+RSpec.describe Legion::Extensions::ExecutiveFunction::Helpers::EfComponent do
+  subject(:comp) { described_class.new(name: :inhibition) }
+
+  describe '#initialize' do
+    it 'sets name' do
+      expect(comp.name).to eq(:inhibition)
+    end
+
+    it 'starts with default capacity' do
+      expect(comp.capacity).to eq(described_class::DEFAULT_CAPACITY)
+    end
+
+    it 'starts with zero fatigue' do
+      expect(comp.fatigue).to eq(0.0)
+    end
+
+    it 'starts with empty recent_uses' do
+      expect(comp.recent_uses).to be_empty
+    end
+
+    it 'clamps capacity to floor' do
+      c = described_class.new(name: :shifting, capacity: -0.5)
+      expect(c.capacity).to eq(described_class::CAPACITY_FLOOR)
+    end
+
+    it 'clamps capacity to ceiling' do
+      c = described_class.new(name: :updating, capacity: 5.0)
+      expect(c.capacity).to eq(described_class::CAPACITY_CEILING)
+    end
+  end
+
+  describe '#use' do
+    it 'increases fatigue by cost' do
+      comp.use(cost: 0.1)
+      expect(comp.fatigue).to be_within(0.001).of(0.1)
+    end
+
+    it 'records recent use entry' do
+      comp.use(cost: 0.05)
+      expect(comp.recent_uses.size).to eq(1)
+      expect(comp.recent_uses.first[:cost]).to eq(0.05)
+    end
+
+    it 'caps fatigue at capacity' do
+      comp.use(cost: 10.0)
+      expect(comp.fatigue).to be <= comp.capacity
+    end
+
+    it 'retains only last 50 uses' do
+      60.times { comp.use(cost: 0.0) }
+      expect(comp.recent_uses.size).to eq(50)
+    end
+  end
+
+  describe '#recover' do
+    it 'reduces fatigue by RECOVERY_RATE' do
+      comp.use(cost: 0.1)
+      before = comp.fatigue
+      comp.recover
+      expect(comp.fatigue).to be < before
+    end
+
+    it 'does not go below zero' do
+      5.times { comp.recover }
+      expect(comp.fatigue).to eq(0.0)
+    end
+  end
+
+  describe '#effective_capacity' do
+    it 'returns capacity minus fatigue' do
+      comp.use(cost: 0.2)
+      expect(comp.effective_capacity).to be_within(0.001).of(comp.capacity - 0.2)
+    end
+
+    it 'never falls below CAPACITY_FLOOR' do
+      comp.use(cost: 10.0)
+      expect(comp.effective_capacity).to be >= described_class::CAPACITY_FLOOR
+    end
+  end
+
+  describe '#fatigued?' do
+    it 'returns false when fresh' do
+      expect(comp.fatigued?).to be false
+    end
+
+    it 'returns true when effective_capacity is at floor' do
+      comp.use(cost: comp.capacity)
+      expect(comp.fatigued?).to be true
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with expected keys' do
+      h = comp.to_h
+      expect(h).to include(:name, :capacity, :fatigue, :effective_capacity, :fatigued, :recent_use_count)
+    end
+
+    it 'rounds numeric values' do
+      comp.use(cost: 0.123_456_789)
+      h = comp.to_h
+      expect(h[:fatigue].to_s.length).to be <= 8
+    end
+  end
+end

data/spec/legion/extensions/executive_function/helpers/executive_controller_spec.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/executive_function/helpers/ef_component'
+require 'legion/extensions/executive_function/helpers/executive_controller'
+
+RSpec.describe Legion::Extensions::ExecutiveFunction::Helpers::ExecutiveController do
+  subject(:ctrl) { described_class.new }
+
+  describe '#initialize' do
+    it 'has all three EF components' do
+      described_class::EF_COMPONENTS.each do |name|
+        expect(ctrl.component(name)).to be_a(Legion::Extensions::ExecutiveFunction::Helpers::EfComponent)
+      end
+    end
+
+    it 'starts with nil current_task_set' do
+      expect(ctrl.current_task_set).to be_nil
+    end
+
+    it 'starts with empty history logs' do
+      expect(ctrl.task_history).to be_empty
+      expect(ctrl.inhibition_log).to be_empty
+      expect(ctrl.update_log).to be_empty
+    end
+  end
+
+  describe '#inhibit' do
+    it 'returns success when capacity available' do
+      result = ctrl.inhibit(target: :distraction, reason: :prepotent_response)
+      expect(result[:success]).to be true
+      expect(result[:target]).to eq(:distraction)
+    end
+
+    it 'records entry in inhibition_log' do
+      ctrl.inhibit(target: :noise, reason: :irrelevant)
+      expect(ctrl.inhibition_log.size).to eq(1)
+    end
+
+    it 'returns failure when fatigued' do
+      30.times { ctrl.inhibit(target: :x, reason: :test) }
+      result = ctrl.inhibit(target: :x, reason: :test)
+      expect(result[:success]).to be(true).or be(false)
+    end
+
+    it 'retains at most MAX_INHIBITIONS entries' do
+      (described_class::MAX_INHIBITIONS + 5).times do
+        ctrl.inhibit(target: :x, reason: :test)
+        described_class::EF_COMPONENTS.each { ctrl.component(it).instance_variable_set(:@fatigue, 0.0) }
+      end
+      expect(ctrl.inhibition_log.size).to be <= described_class::MAX_INHIBITIONS
+    end
+  end
+
+  describe '#shift_task' do
+    it 'returns success and updates current_task_set' do
+      result = ctrl.shift_task(from: :read, to: :write)
+      expect(result[:success]).to be true
+      expect(ctrl.current_task_set).to eq(:write)
+    end
+
+    it 'incurs SWITCH_COST for different tasks' do
+      result = ctrl.shift_task(from: :task_a, to: :task_b)
+      expect(result[:switch_cost]).to eq(described_class::SWITCH_COST)
+    end
+
+    it 'incurs zero cost for same task' do
+      result = ctrl.shift_task(from: :same, to: :same)
+      expect(result[:switch_cost]).to eq(0.0)
+    end
+
+    it 'records entry in task_history' do
+      ctrl.shift_task(from: :a, to: :b)
+      expect(ctrl.task_history.size).to eq(1)
+    end
+  end
+
+  describe '#update_wm' do
+    it 'returns success with slot info' do
+      result = ctrl.update_wm(slot: :goal, old_value: :old, new_value: :new)
+      expect(result[:success]).to be true
+      expect(result[:slot]).to eq(:goal)
+      expect(result[:new_value]).to eq(:new)
+    end
+
+    it 'records entry in update_log' do
+      ctrl.update_wm(slot: :context, old_value: nil, new_value: :fresh)
+      expect(ctrl.update_log.size).to eq(1)
+    end
+  end
+
+  describe '#common_ef_level' do
+    it 'returns a float between CAPACITY_FLOOR and CAPACITY_CEILING' do
+      level = ctrl.common_ef_level
+      expect(level).to be_a(Float)
+      expect(level).to be >= Legion::Extensions::ExecutiveFunction::Helpers::EfComponent::CAPACITY_FLOOR
+      expect(level).to be <= Legion::Extensions::ExecutiveFunction::Helpers::EfComponent::CAPACITY_CEILING
+    end
+
+    it 'decreases after heavy use' do
+      initial = ctrl.common_ef_level
+      20.times { ctrl.inhibit(target: :t, reason: :r) }
+      expect(ctrl.common_ef_level).to be <= initial
+    end
+  end
+
+  describe '#can_inhibit? / #can_shift? / #can_update?' do
+    it 'returns true when components are fresh' do
+      expect(ctrl.can_inhibit?).to be true
+      expect(ctrl.can_shift?).to be true
+      expect(ctrl.can_update?).to be true
+    end
+  end
+
+  describe '#tick' do
+    it 'recovers all components' do
+      ctrl.inhibit(target: :x, reason: :y)
+      fatigue_before = ctrl.component(:inhibition).fatigue
+      ctrl.tick
+      expect(ctrl.component(:inhibition).fatigue).to be < fatigue_before
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with expected top-level keys' do
+      h = ctrl.to_h
+      expect(h).to include(:common_ef_level, :current_task_set, :components,
+                           :task_history_size, :inhibition_count, :update_count)
+    end
+
+    it 'includes all three component hashes' do
+      described_class::EF_COMPONENTS.each do |name|
+        expect(ctrl.to_h[:components]).to have_key(name)
+      end
+    end
+  end
+end

data/spec/legion/extensions/executive_function/runners/executive_function_spec.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/executive_function/client'
+
+RSpec.describe Legion::Extensions::ExecutiveFunction::Runners::ExecutiveFunction do
+  subject(:runner) { Legion::Extensions::ExecutiveFunction::Client.new }
+
+  describe '#inhibit' do
+    it 'returns success: true' do
+      result = runner.inhibit(target: :noise)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns the suppressed target' do
+      result = runner.inhibit(target: :distraction, reason: :irrelevant)
+      expect(result[:target]).to eq(:distraction)
+    end
+
+    it 'includes remaining_capacity' do
+      result = runner.inhibit(target: :x)
+      expect(result[:remaining_capacity]).to be_a(Float)
+    end
+  end
+
+  describe '#shift_task' do
+    it 'returns success: true' do
+      result = runner.shift_task(from: :task_a, to: :task_b)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns from and to task names' do
+      result = runner.shift_task(from: :reading, to: :writing)
+      expect(result[:to]).to eq(:writing)
+    end
+
+    it 'returns switch_cost' do
+      result = runner.shift_task(from: :a, to: :b)
+      expect(result[:switch_cost]).to be_a(Float)
+    end
+  end
+
+  describe '#update_wm' do
+    it 'returns success: true' do
+      result = runner.update_wm(slot: :goal, new_value: :complete)
+      expect(result[:success]).to be true
+    end
+
+    it 'echoes slot and new_value' do
+      result = runner.update_wm(slot: :context, old_value: :stale, new_value: :fresh)
+      expect(result[:slot]).to eq(:context)
+      expect(result[:new_value]).to eq(:fresh)
+    end
+  end
+
+  describe '#common_ef_status' do
+    it 'returns success: true' do
+      result = runner.common_ef_status
+      expect(result[:success]).to be true
+    end
+
+    it 'includes common_ef_level' do
+      result = runner.common_ef_status
+      expect(result[:common_ef_level]).to be_a(Float)
+    end
+
+    it 'includes all three components' do
+      result = runner.common_ef_status
+      Legion::Extensions::ExecutiveFunction::Helpers::ExecutiveController::EF_COMPONENTS.each do |name|
+        expect(result[:components]).to have_key(name)
+      end
+    end
+  end
+
+  describe '#component_status' do
+    it 'returns success: true for known component' do
+      result = runner.component_status(component: :inhibition)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns failure for unknown component' do
+      result = runner.component_status(component: :nonexistent)
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:unknown_component)
+    end
+
+    it 'includes component hash' do
+      result = runner.component_status(component: :shifting)
+      expect(result[:component]).to include(:name, :capacity, :effective_capacity)
+    end
+  end
+
+  describe '#can_perform' do
+    it 'returns success: true for :inhibit' do
+      result = runner.can_perform(operation: :inhibit)
+      expect(result[:success]).to be true
+      expect(result[:can_perform]).to be true
+    end
+
+    it 'returns success: true for :shift' do
+      result = runner.can_perform(operation: :shift)
+      expect(result[:success]).to be true
+      expect(result[:can_perform]).to be true
+    end
+
+    it 'returns success: true for :update' do
+      result = runner.can_perform(operation: :update)
+      expect(result[:can_perform]).to be true
+    end
+
+    it 'handles unknown operation gracefully' do
+      result = runner.can_perform(operation: :fly)
+      expect(result[:can_perform]).to be false
+      expect(result[:reason]).to eq(:unknown_operation)
+    end
+  end
+
+  describe '#task_switch_cost' do
+    it 'returns SWITCH_COST for different tasks' do
+      result = runner.task_switch_cost(from: :a, to: :b)
+      expect(result[:switch_cost]).to eq(
+        Legion::Extensions::ExecutiveFunction::Helpers::ExecutiveController::SWITCH_COST
+      )
+    end
+
+    it 'returns zero for same task' do
+      result = runner.task_switch_cost(from: :same, to: :same)
+      expect(result[:switch_cost]).to eq(0.0)
+    end
+
+    it 'includes shifting_capacity' do
+      result = runner.task_switch_cost(from: :a, to: :b)
+      expect(result[:shifting_capacity]).to be_a(Float)
+    end
+  end
+
+  describe '#executive_load' do
+    it 'returns success: true' do
+      result = runner.executive_load
+      expect(result[:success]).to be true
+    end
+
+    it 'returns executive_load as float' do
+      result = runner.executive_load
+      expect(result[:executive_load]).to be_a(Float)
+    end
+
+    it 'load increases after heavy use' do
+      initial = runner.executive_load[:executive_load]
+      10.times { runner.inhibit(target: :x) }
+      expect(runner.executive_load[:executive_load]).to be >= initial
+    end
+  end
+
+  describe '#update_executive_function' do
+    it 'updates component capacity' do
+      result = runner.update_executive_function(component: :inhibition, capacity: 0.9)
+      expect(result[:success]).to be true
+      expect(result[:new_capacity]).to be_within(0.001).of(0.9)
+    end
+
+    it 'clamps capacity to CAPACITY_FLOOR' do
+      result = runner.update_executive_function(component: :shifting, capacity: -1.0)
+      expect(result[:new_capacity]).to be >=
+                                       Legion::Extensions::ExecutiveFunction::Helpers::EfComponent::CAPACITY_FLOOR
+    end
+
+    it 'returns failure for unknown component' do
+      result = runner.update_executive_function(component: :bogus, capacity: 0.5)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#executive_function_stats' do
+    it 'returns success: true' do
+      result = runner.executive_function_stats
+      expect(result[:success]).to be true
+    end
+
+    it 'includes common_ef_level' do
+      result = runner.executive_function_stats
+      expect(result[:common_ef_level]).to be_a(Float)
+    end
+
+    it 'includes all three components' do
+      result = runner.executive_function_stats
+      Legion::Extensions::ExecutiveFunction::Helpers::ExecutiveController::EF_COMPONENTS.each do |name|
+        expect(result[:components]).to have_key(name)
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,23 @@
+# 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/executive_function'
+
+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,75 @@
+--- !ruby/object:Gem::Specification
+name: lex-executive-function
+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: 'Miyake & Friedman (2000, 2012) unity/diversity model of executive functions:
+  inhibition, shifting, and working memory updating'
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- lex-executive-function.gemspec
+- lib/legion/extensions/executive_function.rb
+- lib/legion/extensions/executive_function/actors/recovery.rb
+- lib/legion/extensions/executive_function/client.rb
+- lib/legion/extensions/executive_function/helpers/ef_component.rb
+- lib/legion/extensions/executive_function/helpers/executive_controller.rb
+- lib/legion/extensions/executive_function/runners/executive_function.rb
+- lib/legion/extensions/executive_function/version.rb
+- spec/legion/extensions/executive_function/client_spec.rb
+- spec/legion/extensions/executive_function/helpers/ef_component_spec.rb
+- spec/legion/extensions/executive_function/helpers/executive_controller_spec.rb
+- spec/legion/extensions/executive_function/runners/executive_function_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-executive-function
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-executive-function
+  source_code_uri: https://github.com/LegionIO/lex-executive-function
+  documentation_uri: https://github.com/LegionIO/lex-executive-function
+  changelog_uri: https://github.com/LegionIO/lex-executive-function
+  bug_tracker_uri: https://github.com/LegionIO/lex-executive-function/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 Executive Function
+test_files: []