lex-agentic-executive 0.1.0

data/spec/legion/extensions/agentic/executive/working_memory/client_spec.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Agentic::Executive::WorkingMemory::Client do
+  subject(:client) { described_class.new }
+
+  describe '#initialize' do
+    it 'creates a default buffer' do
+      expect(client.buffer).to be_a(Legion::Extensions::Agentic::Executive::WorkingMemory::Helpers::Buffer)
+    end
+
+    it 'accepts an injected buffer' do
+      custom = Legion::Extensions::Agentic::Executive::WorkingMemory::Helpers::Buffer.new
+      injected = described_class.new(buffer: custom)
+      expect(injected.buffer).to equal(custom)
+    end
+  end
+
+  describe 'full workflow integration' do
+    it 'stores, retrieves, rehearses, and decays items through the cognitive cycle' do
+      # Store items across buffer types
+      verbal = client.store_item(content: 'spoken word', buffer_type: :verbal, priority: :normal, tags: [:conversation])
+      spatial = client.store_item(content: 'map layout', buffer_type: :spatial, priority: :high, tags: [:navigation])
+      episodic = client.store_item(content: 'meeting memory', buffer_type: :episodic, priority: :critical, tags: [:work])
+
+      expect(verbal[:success]).to be true
+      expect(spatial[:success]).to be true
+      expect(episodic[:success]).to be true
+
+      # Check status
+      status = client.buffer_status
+      expect(status[:status][:size]).to eq(3)
+
+      # Retrieve by type
+      verbal_items = client.retrieve_by_type(buffer_type: :verbal)
+      expect(verbal_items[:count]).to eq(1)
+
+      # Retrieve by tag
+      work_items = client.retrieve_by_tag(tag: :work)
+      expect(work_items[:count]).to eq(1)
+
+      # Rehearse the verbal item to prevent decay
+      rehearsed = client.rehearse_item(id: verbal[:item][:id])
+      expect(rehearsed[:item][:rehearsal_count]).to eq(1)
+
+      # Run a tick (decay cycle)
+      tick_result = client.update_working_memory
+      expect(tick_result[:success]).to be true
+
+      # Critical item should be a consolidation candidate
+      candidates = client.consolidation_candidates
+      expect(candidates[:count]).to be >= 1
+
+      # Find interference between same-type same-tag items
+      client.store_item(content: 'another conversation', buffer_type: :verbal, priority: :normal, tags: [:conversation])
+      interference = client.find_interference(id: verbal[:item][:id])
+      expect(interference[:count]).to be >= 1
+
+      # Stats reflect the current state
+      stats = client.working_memory_stats
+      expect(stats[:size]).to eq(4)
+      expect(stats[:load]).to be > 0.0
+
+      # Remove an item
+      client.remove_item(id: spatial[:item][:id])
+      expect(client.working_memory_stats[:size]).to eq(3)
+
+      # Clear everything
+      client.clear_buffer
+      expect(client.working_memory_stats[:size]).to eq(0)
+    end
+
+    it 'models the 7 plus-or-minus 2 capacity limit' do
+      # Fill to base capacity
+      7.times { |i| client.store_item(content: "item #{i}", priority: :normal) }
+      expect(client.buffer.size).to eq(7)
+
+      # Without chunking, adding more evicts lowest activation
+      3.times { |i| client.store_item(content: "overflow #{i}", priority: :high) }
+      expect(client.buffer.size).to be <= client.buffer.capacity
+    end
+
+    it 'demonstrates chunking bonus' do
+      # Add items with shared tags to trigger chunking
+      3.times { |i| client.store_item(content: "group_a_#{i}", tags: [:group_a]) }
+      3.times { |i| client.store_item(content: "group_b_#{i}", tags: [:group_b]) }
+
+      # Capacity should exceed base due to chunking
+      expect(client.buffer.capacity).to be > Legion::Extensions::Agentic::Executive::WorkingMemory::Helpers::Constants::CAPACITY
+    end
+  end
+end

data/spec/legion/extensions/agentic/executive/working_memory/helpers/buffer_item_spec.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Agentic::Executive::WorkingMemory::Helpers::BufferItem do
+  subject(:item) { described_class.new(content: 'test content', buffer_type: :verbal, priority: :normal, tags: [:test]) }
+
+  describe '#initialize' do
+    it 'generates a uuid id' do
+      expect(item.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores content' do
+      expect(item.content).to eq('test content')
+    end
+
+    it 'stores buffer_type' do
+      expect(item.buffer_type).to eq(:verbal)
+    end
+
+    it 'stores priority' do
+      expect(item.priority).to eq(:normal)
+    end
+
+    it 'stores tags' do
+      expect(item.tags).to eq([:test])
+    end
+
+    it 'sets activation from priority level' do
+      expect(item.activation).to eq(0.5)
+    end
+
+    it 'sets critical priority to 1.0 activation' do
+      critical = described_class.new(content: 'urgent', priority: :critical)
+      expect(critical.activation).to eq(1.0)
+    end
+
+    it 'sets low priority to 0.25 activation' do
+      low = described_class.new(content: 'low', priority: :low)
+      expect(low.activation).to eq(0.25)
+    end
+
+    it 'starts with zero rehearsal count' do
+      expect(item.rehearsal_count).to eq(0)
+    end
+
+    it 'starts with zero age ticks' do
+      expect(item.age_ticks).to eq(0)
+    end
+
+    it 'records created_at' do
+      expect(item.created_at).to be_a(Time)
+    end
+
+    it 'defaults buffer_type to episodic' do
+      default_item = described_class.new(content: 'x')
+      expect(default_item.buffer_type).to eq(:episodic)
+    end
+
+    it 'defaults tags to empty array' do
+      default_item = described_class.new(content: 'x')
+      expect(default_item.tags).to eq([])
+    end
+  end
+
+  describe '#rehearse' do
+    it 'increments rehearsal count' do
+      item.rehearse
+      expect(item.rehearsal_count).to eq(1)
+    end
+
+    it 'boosts activation' do
+      initial = item.activation
+      item.rehearse
+      expect(item.activation).to eq(initial + Legion::Extensions::Agentic::Executive::WorkingMemory::Helpers::Constants::REHEARSAL_BOOST)
+    end
+
+    it 'caps activation at 1.0' do
+      critical = described_class.new(content: 'urgent', priority: :critical)
+      critical.rehearse
+      expect(critical.activation).to eq(1.0)
+    end
+
+    it 'resets age ticks to zero' do
+      item.decay
+      item.decay
+      expect(item.age_ticks).to eq(2)
+      item.rehearse
+      expect(item.age_ticks).to eq(0)
+    end
+  end
+
+  describe '#decay' do
+    it 'increments age ticks' do
+      item.decay
+      expect(item.age_ticks).to eq(1)
+    end
+
+    it 'reduces activation' do
+      initial = item.activation
+      item.decay
+      expect(item.activation).to eq(initial - Legion::Extensions::Agentic::Executive::WorkingMemory::Helpers::Constants::DECAY_RATE)
+    end
+
+    it 'floors activation at 0.0' do
+      bg = described_class.new(content: 'bg', priority: :background)
+      10.times { bg.decay }
+      expect(bg.activation).to eq(0.0)
+    end
+  end
+
+  describe '#expired?' do
+    it 'is not expired when fresh' do
+      expect(item.expired?).to be false
+    end
+
+    it 'expires when activation reaches zero' do
+      bg = described_class.new(content: 'bg', priority: :background)
+      10.times { bg.decay }
+      expect(bg.expired?).to be true
+    end
+
+    it 'expires when age exceeds MAX_AGE_TICKS' do
+      Legion::Extensions::Agentic::Executive::WorkingMemory::Helpers::Constants::MAX_AGE_TICKS.times { item.decay }
+      expect(item.expired?).to be true
+    end
+  end
+
+  describe '#consolidation_ready?' do
+    it 'returns false for normal priority items' do
+      expect(item.consolidation_ready?).to be false
+    end
+
+    it 'returns true for critical priority items' do
+      critical = described_class.new(content: 'urgent', priority: :critical)
+      expect(critical.consolidation_ready?).to be true
+    end
+
+    it 'returns true after enough rehearsals' do
+      3.times { item.rehearse }
+      expect(item.activation).to be >= Legion::Extensions::Agentic::Executive::WorkingMemory::Helpers::Constants::CONSOLIDATION_THRESHOLD
+      expect(item.consolidation_ready?).to be true
+    end
+  end
+
+  describe '#interferes_with?' do
+    let(:other) { described_class.new(content: 'other', buffer_type: :verbal, priority: :normal, tags: [:test]) }
+
+    it 'detects interference between same-type same-tag items with similar activation' do
+      expect(item.interferes_with?(other)).to be true
+    end
+
+    it 'returns false for different buffer types' do
+      spatial = described_class.new(content: 'spatial', buffer_type: :spatial, priority: :normal, tags: [:test])
+      expect(item.interferes_with?(spatial)).to be false
+    end
+
+    it 'returns false for non-overlapping tags' do
+      no_overlap = described_class.new(content: 'other', buffer_type: :verbal, priority: :normal, tags: [:different])
+      expect(item.interferes_with?(no_overlap)).to be false
+    end
+
+    it 'returns false for non-BufferItem objects' do
+      expect(item.interferes_with?('not an item')).to be false
+    end
+
+    it 'returns false when activation difference exceeds threshold' do
+      critical = described_class.new(content: 'urgent', buffer_type: :verbal, priority: :critical, tags: [:test])
+      low = described_class.new(content: 'low', buffer_type: :verbal, priority: :low, tags: [:test])
+      expect(critical.interferes_with?(low)).to be false
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with all fields' do
+      h = item.to_h
+      expect(h).to include(:id, :content, :buffer_type, :priority, :activation, :rehearsal_count, :age_ticks, :expired, :consolidation_ready)
+    end
+
+    it 'rounds activation to 4 decimal places' do
+      item.decay
+      expect(item.to_h[:activation]).to eq(item.activation.round(4))
+    end
+  end
+end

data/spec/legion/extensions/agentic/executive/working_memory/helpers/buffer_spec.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Agentic::Executive::WorkingMemory::Helpers::Buffer do
+  subject(:buffer) { described_class.new }
+
+  let(:constants) { Legion::Extensions::Agentic::Executive::WorkingMemory::Helpers::Constants }
+
+  describe '#initialize' do
+    it 'starts empty' do
+      expect(buffer.items).to eq([])
+      expect(buffer.size).to eq(0)
+    end
+  end
+
+  describe '#store' do
+    it 'stores an item and returns it' do
+      item = buffer.store(content: 'hello')
+      expect(item).to be_a(Legion::Extensions::Agentic::Executive::WorkingMemory::Helpers::BufferItem)
+      expect(buffer.size).to eq(1)
+    end
+
+    it 'stores with custom buffer_type and priority' do
+      item = buffer.store(content: 'spatial data', buffer_type: :spatial, priority: :high)
+      expect(item.buffer_type).to eq(:spatial)
+      expect(item.priority).to eq(:high)
+    end
+
+    it 'stores with tags' do
+      item = buffer.store(content: 'tagged', tags: %i[important work])
+      expect(item.tags).to eq(%i[important work])
+    end
+
+    it 'evicts lowest-activation items when over capacity' do
+      (constants::CAPACITY + constants::CHUNK_BONUS + 2).times do |i|
+        buffer.store(content: "item #{i}", priority: :normal)
+      end
+      expect(buffer.size).to be <= buffer.capacity
+    end
+  end
+
+  describe '#retrieve' do
+    it 'finds an item by id' do
+      item = buffer.store(content: 'findme')
+      found = buffer.retrieve(item.id)
+      expect(found).to eq(item)
+    end
+
+    it 'returns nil for unknown id' do
+      expect(buffer.retrieve('nonexistent')).to be_nil
+    end
+  end
+
+  describe '#retrieve_by_tag' do
+    it 'returns items matching the tag' do
+      buffer.store(content: 'a', tags: [:work])
+      buffer.store(content: 'b', tags: [:play])
+      buffer.store(content: 'c', tags: %i[work play])
+
+      work_items = buffer.retrieve_by_tag(:work)
+      expect(work_items.size).to eq(2)
+      expect(work_items.map(&:content)).to contain_exactly('a', 'c')
+    end
+
+    it 'returns empty array for unmatched tag' do
+      buffer.store(content: 'a', tags: [:work])
+      expect(buffer.retrieve_by_tag(:missing)).to eq([])
+    end
+  end
+
+  describe '#retrieve_by_type' do
+    it 'returns items of the specified buffer type' do
+      buffer.store(content: 'v1', buffer_type: :verbal)
+      buffer.store(content: 's1', buffer_type: :spatial)
+      buffer.store(content: 'v2', buffer_type: :verbal)
+
+      verbal = buffer.retrieve_by_type(:verbal)
+      expect(verbal.size).to eq(2)
+      expect(verbal.map(&:content)).to contain_exactly('v1', 'v2')
+    end
+  end
+
+  describe '#rehearse' do
+    it 'rehearses an existing item' do
+      item = buffer.store(content: 'rehearse me')
+      initial_activation = item.activation
+      result = buffer.rehearse(item.id)
+      expect(result.activation).to be > initial_activation
+      expect(result.rehearsal_count).to eq(1)
+    end
+
+    it 'returns nil for unknown id' do
+      expect(buffer.rehearse('nonexistent')).to be_nil
+    end
+  end
+
+  describe '#remove' do
+    it 'removes an item by id' do
+      item = buffer.store(content: 'remove me')
+      buffer.remove(item.id)
+      expect(buffer.size).to eq(0)
+      expect(buffer.retrieve(item.id)).to be_nil
+    end
+  end
+
+  describe '#tick_decay' do
+    it 'decays all items' do
+      item = buffer.store(content: 'decaying', priority: :normal)
+      initial = item.activation
+      buffer.tick_decay
+      expect(item.activation).to be < initial
+    end
+
+    it 'removes expired items' do
+      item = buffer.store(content: 'expiring', priority: :background)
+      constants::MAX_AGE_TICKS.times { buffer.tick_decay }
+      expect(buffer.retrieve(item.id)).to be_nil
+    end
+  end
+
+  describe '#consolidation_candidates' do
+    it 'returns items above consolidation threshold' do
+      buffer.store(content: 'critical', priority: :critical)
+      buffer.store(content: 'normal', priority: :normal)
+      candidates = buffer.consolidation_candidates
+      expect(candidates.size).to eq(1)
+      expect(candidates.first.content).to eq('critical')
+    end
+  end
+
+  describe '#current_load' do
+    it 'returns 0.0 when empty' do
+      expect(buffer.current_load).to eq(0.0)
+    end
+
+    it 'increases as items are added' do
+      3.times { |i| buffer.store(content: "item #{i}") }
+      expect(buffer.current_load).to be > 0.0
+    end
+
+    it 'clamps at 1.0' do
+      20.times { |i| buffer.store(content: "item #{i}", priority: :critical) }
+      expect(buffer.current_load).to be <= 1.0
+    end
+  end
+
+  describe '#load_level' do
+    it 'returns :idle when empty' do
+      expect(buffer.load_level).to eq(:idle)
+    end
+
+    it 'returns higher levels as buffer fills' do
+      # Use unique tags to prevent chunk_bonus inflation
+      20.times { |i| buffer.store(content: "item #{i}", priority: :critical, tags: [:"unique_#{i}"]) }
+      expect(buffer.load_level).to eq(:overloaded)
+    end
+  end
+
+  describe '#capacity' do
+    it 'is at least the base CAPACITY' do
+      expect(buffer.capacity).to be >= constants::CAPACITY
+    end
+
+    it 'increases with chunking (items sharing tags)' do
+      buffer.store(content: 'a1', tags: [:group_a])
+      buffer.store(content: 'a2', tags: [:group_a])
+      buffer.store(content: 'b1', tags: [:group_b])
+      buffer.store(content: 'b2', tags: [:group_b])
+      expect(buffer.capacity).to be > constants::CAPACITY
+    end
+
+    it 'caps chunk bonus at CHUNK_BONUS' do
+      10.times { |i| buffer.store(content: "item #{i}", tags: [:"group_#{i / 2}"]) }
+      expect(buffer.capacity).to be <= constants::CAPACITY + constants::CHUNK_BONUS
+    end
+  end
+
+  describe '#available_slots' do
+    it 'equals capacity when empty' do
+      expect(buffer.available_slots).to eq(buffer.capacity)
+    end
+
+    it 'decreases as items are added' do
+      buffer.store(content: 'one')
+      expect(buffer.available_slots).to eq(buffer.capacity - 1)
+    end
+
+    it 'never goes below zero' do
+      20.times { |i| buffer.store(content: "item #{i}", priority: :critical) }
+      expect(buffer.available_slots).to be >= 0
+    end
+  end
+
+  describe '#full?' do
+    it 'is false when empty' do
+      expect(buffer.full?).to be false
+    end
+
+    it 'is true at capacity' do
+      # Use unique tags to prevent chunk_bonus inflation (nil first-tag groups all items)
+      20.times { |i| buffer.store(content: "item #{i}", priority: :critical, tags: [:"unique_#{i}"]) }
+      expect(buffer.full?).to be true
+    end
+  end
+
+  describe '#clear' do
+    it 'removes all items' do
+      3.times { |i| buffer.store(content: "item #{i}") }
+      buffer.clear
+      expect(buffer.size).to eq(0)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a status hash' do
+      buffer.store(content: 'test')
+      h = buffer.to_h
+      expect(h).to include(:size, :capacity, :load, :load_level, :by_type, :available)
+      expect(h[:size]).to eq(1)
+    end
+
+    it 'breaks down items by type' do
+      buffer.store(content: 'v', buffer_type: :verbal)
+      buffer.store(content: 's', buffer_type: :spatial)
+      h = buffer.to_h
+      expect(h[:by_type][:verbal]).to eq(1)
+      expect(h[:by_type][:spatial]).to eq(1)
+      expect(h[:by_type][:episodic]).to eq(0)
+    end
+  end
+end

data/spec/legion/extensions/agentic/executive/working_memory/helpers/constants_spec.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Agentic::Executive::WorkingMemory::Helpers::Constants do
+  describe 'CAPACITY' do
+    it 'is 7 (Miller\'s Law)' do
+      expect(described_class::CAPACITY).to eq(7)
+    end
+  end
+
+  describe 'CHUNK_BONUS' do
+    it 'is a positive integer' do
+      expect(described_class::CHUNK_BONUS).to be_a(Integer)
+      expect(described_class::CHUNK_BONUS).to be > 0
+    end
+  end
+
+  describe 'BUFFER_TYPES' do
+    it 'contains verbal, spatial, and episodic' do
+      expect(described_class::BUFFER_TYPES).to contain_exactly(:verbal, :spatial, :episodic)
+    end
+
+    it 'is frozen' do
+      expect(described_class::BUFFER_TYPES).to be_frozen
+    end
+  end
+
+  describe 'DECAY_RATE' do
+    it 'is a positive float between 0 and 1' do
+      expect(described_class::DECAY_RATE).to be_a(Float)
+      expect(described_class::DECAY_RATE).to be_between(0.0, 1.0).exclusive
+    end
+  end
+
+  describe 'REHEARSAL_BOOST' do
+    it 'is a positive float between 0 and 1' do
+      expect(described_class::REHEARSAL_BOOST).to be_a(Float)
+      expect(described_class::REHEARSAL_BOOST).to be_between(0.0, 1.0).exclusive
+    end
+  end
+
+  describe 'PRIORITY_LEVELS' do
+    it 'has five levels' do
+      expect(described_class::PRIORITY_LEVELS.size).to eq(5)
+    end
+
+    it 'is ordered from highest to lowest activation' do
+      values = described_class::PRIORITY_LEVELS.values
+      expect(values).to eq(values.sort.reverse)
+    end
+
+    it 'has critical at 1.0' do
+      expect(described_class::PRIORITY_LEVELS[:critical]).to eq(1.0)
+    end
+
+    it 'is frozen' do
+      expect(described_class::PRIORITY_LEVELS).to be_frozen
+    end
+  end
+
+  describe 'MAX_AGE_TICKS' do
+    it 'is a positive integer' do
+      expect(described_class::MAX_AGE_TICKS).to be_a(Integer)
+      expect(described_class::MAX_AGE_TICKS).to be > 0
+    end
+  end
+
+  describe 'INTERFERENCE_THRESHOLD' do
+    it 'is a float between 0 and 1' do
+      expect(described_class::INTERFERENCE_THRESHOLD).to be_between(0.0, 1.0)
+    end
+  end
+
+  describe 'CONSOLIDATION_THRESHOLD' do
+    it 'is a float between 0 and 1' do
+      expect(described_class::CONSOLIDATION_THRESHOLD).to be_between(0.0, 1.0)
+    end
+
+    it 'is higher than normal priority activation' do
+      expect(described_class::CONSOLIDATION_THRESHOLD).to be > described_class::PRIORITY_LEVELS[:normal]
+    end
+  end
+
+  describe 'LOAD_LEVELS' do
+    it 'has five levels' do
+      expect(described_class::LOAD_LEVELS.size).to eq(5)
+    end
+
+    it 'is ordered from highest to lowest threshold' do
+      values = described_class::LOAD_LEVELS.values
+      expect(values).to eq(values.sort.reverse)
+    end
+
+    it 'is frozen' do
+      expect(described_class::LOAD_LEVELS).to be_frozen
+    end
+  end
+end