lex-agentic-memory 0.1.0

data/spec/legion/extensions/agentic/memory/offloading/runners/cognitive_offloading_spec.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/memory/offloading/client'
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Offloading::Runners::CognitiveOffloading do
+  let(:engine) { Legion::Extensions::Agentic::Memory::Offloading::Helpers::OffloadingEngine.new }
+  let(:client) { Legion::Extensions::Agentic::Memory::Offloading::Client.new(engine: engine) }
+
+  let(:store) do
+    client.register_store(name: 'test_store', store_type: :database)
+    engine.stores.values.first
+  end
+
+  before { store }
+
+  describe '#register_store' do
+    it 'returns success: true on valid registration' do
+      result = client.register_store(name: 'another_store', store_type: :file)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns the store hash' do
+      result = client.register_store(name: 'notes', store_type: :notes)
+      expect(result[:store]).to include(:id, :name, :store_type, :trust)
+    end
+
+    it 'returns success: false when limit reached' do
+      stub_const('Legion::Extensions::Agentic::Memory::Offloading::Helpers::Constants::MAX_STORES', 1)
+      fresh = Legion::Extensions::Agentic::Memory::Offloading::Client.new
+      fresh.register_store(name: 'first', store_type: :file)
+      result = fresh.register_store(name: 'overflow', store_type: :file)
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:limit_reached)
+    end
+
+    it 'accepts an injected engine' do
+      injected = Legion::Extensions::Agentic::Memory::Offloading::Helpers::OffloadingEngine.new
+      result = client.register_store(name: 'injected', store_type: :agent, engine: injected)
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#offload_item' do
+    it 'returns success: true on valid offload' do
+      result = client.offload_item(content: 'fact', item_type: :fact, importance: 0.7, store_id: store.id)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns the item hash' do
+      result = client.offload_item(content: 'plan', item_type: :plan, importance: 0.8, store_id: store.id)
+      expect(result[:item]).to include(:id, :content, :item_type, :importance)
+    end
+
+    it 'returns success: false for unknown store_id' do
+      result = client.offload_item(content: 'x', item_type: :fact, importance: 0.5, store_id: 'bogus')
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:offload_failed)
+    end
+
+    it 'returns success: false when item limit reached' do
+      stub_const('Legion::Extensions::Agentic::Memory::Offloading::Helpers::Constants::MAX_ITEMS', 1)
+      client.offload_item(content: 'first', item_type: :fact, importance: 0.5, store_id: store.id)
+      result = client.offload_item(content: 'second', item_type: :fact, importance: 0.5, store_id: store.id)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#retrieve_item' do
+    let!(:offloaded) do
+      client.offload_item(content: 'my fact', item_type: :fact, importance: 0.6, store_id: store.id)[:item]
+    end
+
+    it 'returns success: true for known item' do
+      result = client.retrieve_item(item_id: offloaded[:id])
+      expect(result[:success]).to be true
+    end
+
+    it 'returns the item hash on success' do
+      result = client.retrieve_item(item_id: offloaded[:id])
+      expect(result[:item]).to include(:id, :retrieved_count)
+    end
+
+    it 'increments retrieved_count' do
+      client.retrieve_item(item_id: offloaded[:id])
+      result = client.retrieve_item(item_id: offloaded[:id])
+      expect(result[:item][:retrieved_count]).to eq(2)
+    end
+
+    it 'returns success: false for unknown item_id' do
+      result = client.retrieve_item(item_id: 'no-such-item')
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:not_found)
+    end
+  end
+
+  describe '#report_retrieval_failure' do
+    let!(:offloaded) do
+      client.offload_item(content: 'plan', item_type: :plan, importance: 0.5, store_id: store.id)[:item]
+    end
+
+    it 'returns success: true for known item' do
+      result = client.report_retrieval_failure(item_id: offloaded[:id])
+      expect(result[:success]).to be true
+    end
+
+    it 'returns current store_trust' do
+      result = client.report_retrieval_failure(item_id: offloaded[:id])
+      expect(result[:store_trust]).to be_a(Float)
+    end
+
+    it 'decays trust on the store' do
+      trust_before = store.trust
+      client.report_retrieval_failure(item_id: offloaded[:id])
+      expect(store.trust).to be < trust_before
+    end
+
+    it 'returns success: false for unknown item_id' do
+      result = client.report_retrieval_failure(item_id: 'ghost')
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:not_found)
+    end
+  end
+
+  describe '#items_in_store' do
+    it 'returns items belonging to the store' do
+      client.offload_item(content: 'a', item_type: :fact, importance: 0.5, store_id: store.id)
+      client.offload_item(content: 'b', item_type: :reminder, importance: 0.3, store_id: store.id)
+      result = client.items_in_store(store_id: store.id)
+      expect(result[:success]).to be true
+      expect(result[:count]).to eq(2)
+    end
+
+    it 'returns empty list for store with no items' do
+      result = client.items_in_store(store_id: store.id)
+      expect(result[:items]).to eq([])
+    end
+  end
+
+  describe '#items_by_type' do
+    before do
+      client.offload_item(content: 'a', item_type: :calculation, importance: 0.4, store_id: store.id)
+      client.offload_item(content: 'b', item_type: :calculation, importance: 0.6, store_id: store.id)
+      client.offload_item(content: 'c', item_type: :delegation, importance: 0.8, store_id: store.id)
+    end
+
+    it 'returns items of matching type' do
+      result = client.items_by_type(item_type: :calculation)
+      expect(result[:count]).to eq(2)
+    end
+
+    it 'returns 0 for unused type' do
+      result = client.items_by_type(item_type: :reference)
+      expect(result[:count]).to eq(0)
+    end
+  end
+
+  describe '#most_important_offloaded' do
+    before do
+      client.offload_item(content: 'low',  item_type: :fact, importance: 0.2, store_id: store.id)
+      client.offload_item(content: 'high', item_type: :fact, importance: 0.95, store_id: store.id)
+      client.offload_item(content: 'mid',  item_type: :fact, importance: 0.5, store_id: store.id)
+    end
+
+    it 'returns items in importance-descending order' do
+      result = client.most_important_offloaded(limit: 3)
+      importances = result[:items].map { |i| i[:importance] }
+      expect(importances).to eq(importances.sort.reverse)
+    end
+
+    it 'respects the limit parameter' do
+      result = client.most_important_offloaded(limit: 2)
+      expect(result[:count]).to eq(2)
+    end
+  end
+
+  describe '#offloading_status' do
+    it 'returns success: true' do
+      result = client.offloading_status
+      expect(result[:success]).to be true
+    end
+
+    it 'includes the offloading report' do
+      result = client.offloading_status
+      expect(result[:report]).to include(:total_items, :total_stores, :offloading_ratio,
+                                         :overall_store_trust, :stores_summary)
+    end
+
+    it 'reflects current item count' do
+      client.offload_item(content: 'x', item_type: :context, importance: 0.5, store_id: store.id)
+      result = client.offloading_status
+      expect(result[:report][:total_items]).to eq(1)
+    end
+  end
+end

data/spec/legion/extensions/agentic/memory/paleontology/client_spec.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Paleontology::Client do
+  let(:client) { described_class.new }
+
+  it 'responds to runner methods' do
+    expect(client).to respond_to(:record_extinction, :begin_excavation,
+                                 :list_fossils, :paleontology_status)
+  end
+
+  describe '#record_extinction' do
+    it 'delegates' do
+      result = client.record_extinction(
+        fossil_type: :strategy, domain: :cognitive, content: 'old',
+        extinction_cause: :obsolescence
+      )
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#paleontology_status' do
+    it 'returns report' do
+      result = client.paleontology_status
+      expect(result[:report]).to be_a Hash
+    end
+  end
+end

data/spec/legion/extensions/agentic/memory/paleontology/cognitive_paleontology_spec.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Paleontology do
+  it 'has a version number' do
+    expect(described_class::VERSION).to eq '0.1.0'
+  end
+end

data/spec/legion/extensions/agentic/memory/paleontology/helpers/constants_spec.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Paleontology::Helpers::Constants do
+  let(:c) { described_class }
+
+  it 'defines MAX_FOSSILS' do
+    expect(c::MAX_FOSSILS).to eq 500
+  end
+
+  it 'has 8 fossil types' do
+    expect(c::FOSSIL_TYPES.size).to eq 8
+  end
+
+  it 'has 6 extinction causes' do
+    expect(c::EXTINCTION_CAUSES.size).to eq 6
+  end
+
+  it 'has 8 era names' do
+    expect(c::ERA_NAMES.size).to eq 8
+  end
+
+  describe '.label_for' do
+    it 'returns matching preservation label' do
+      expect(c.label_for(c::PRESERVATION_LABELS, 0.9)).to eq :pristine
+      expect(c.label_for(c::PRESERVATION_LABELS, 0.1)).to eq :imprint
+    end
+
+    it 'returns matching significance label' do
+      expect(c.label_for(c::SIGNIFICANCE_LABELS, 0.9)).to eq :keystone
+      expect(c.label_for(c::SIGNIFICANCE_LABELS, 0.1)).to eq :trivial
+    end
+  end
+end

data/spec/legion/extensions/agentic/memory/paleontology/helpers/excavation_spec.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Paleontology::Helpers::Excavation do
+  let(:excavation) { described_class.new(target_stratum: 2) }
+
+  describe '#initialize' do
+    it 'assigns a UUID' do
+      expect(excavation.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets target_stratum' do
+      expect(excavation.target_stratum).to eq 2
+    end
+
+    it 'starts in_progress' do
+      expect(excavation.status).to eq :in_progress
+    end
+
+    it 'starts with no fossils' do
+      expect(excavation.fossils_found).to be_empty
+    end
+
+    it 'clamps stratum to 0..4' do
+      e = described_class.new(target_stratum: 99)
+      expect(e.target_stratum).to eq 4
+    end
+  end
+
+  describe '#record_find!' do
+    it 'adds fossil to finds' do
+      fossil = Legion::Extensions::Agentic::Memory::Paleontology::Helpers::Fossil.new(
+        fossil_type: :strategy, domain: :cognitive, content: 'x',
+        extinction_cause: :obsolescence
+      )
+      excavation.record_find!(fossil)
+      expect(excavation.fossils_found.size).to eq 1
+    end
+  end
+
+  describe '#complete!' do
+    it 'marks as completed' do
+      excavation.complete!
+      expect(excavation).to be_completed
+    end
+
+    it 'returns false if already completed' do
+      excavation.complete!
+      expect(excavation.complete!).to be false
+    end
+
+    it 'sets completed_at' do
+      excavation.complete!
+      expect(excavation.completed_at).to be_a Time
+    end
+  end
+
+  describe '#yield_rate' do
+    it 'returns 0.0 when empty' do
+      expect(excavation.yield_rate).to eq 0.0
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes expected keys' do
+      %i[id target_stratum stratum_label fossils_count yield_rate
+         status started_at completed_at].each do |key|
+        expect(excavation.to_h).to have_key(key)
+      end
+    end
+  end
+end

data/spec/legion/extensions/agentic/memory/paleontology/helpers/fossil_spec.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Paleontology::Helpers::Fossil do
+  let(:fossil) do
+    described_class.new(fossil_type: :strategy, domain: :cognitive,
+                        content: 'old approach', extinction_cause: :obsolescence)
+  end
+
+  describe '#initialize' do
+    it 'assigns a UUID' do
+      expect(fossil.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets fossil_type' do
+      expect(fossil.fossil_type).to eq :strategy
+    end
+
+    it 'sets domain' do
+      expect(fossil.domain).to eq :cognitive
+    end
+
+    it 'sets extinction_cause' do
+      expect(fossil.extinction_cause).to eq :obsolescence
+    end
+
+    it 'defaults preservation to 0.8' do
+      expect(fossil.preservation).to eq 0.8
+    end
+
+    it 'defaults significance to 0.5' do
+      expect(fossil.significance).to eq 0.5
+    end
+
+    it 'assigns an era' do
+      expect(fossil.era).to be_a Symbol
+    end
+
+    it 'raises on invalid fossil_type' do
+      expect do
+        described_class.new(fossil_type: :bogus, domain: :cognitive,
+                            content: 'x', extinction_cause: :obsolescence)
+      end.to raise_error(ArgumentError, /unknown fossil type/)
+    end
+
+    it 'raises on invalid extinction_cause' do
+      expect do
+        described_class.new(fossil_type: :strategy, domain: :cognitive,
+                            content: 'x', extinction_cause: :bogus)
+      end.to raise_error(ArgumentError, /unknown extinction cause/)
+    end
+
+    it 'clamps stratum_depth to 0..4' do
+      f = described_class.new(fossil_type: :pattern, domain: :semantic,
+                              content: 'x', extinction_cause: :irrelevance,
+                              stratum_depth: 99)
+      expect(f.stratum_depth).to eq 4
+    end
+  end
+
+  describe '#erode!' do
+    it 'reduces preservation' do
+      original = fossil.preservation
+      fossil.erode!
+      expect(fossil.preservation).to be < original
+    end
+
+    it 'clamps at 0.0' do
+      50.times { fossil.erode!(rate: 0.1) }
+      expect(fossil.preservation).to eq 0.0
+    end
+
+    it 'returns self' do
+      expect(fossil.erode!).to eq fossil
+    end
+  end
+
+  describe '#reinforce!' do
+    it 'increases significance' do
+      original = fossil.significance
+      fossil.reinforce!(boost: 0.2)
+      expect(fossil.significance).to be > original
+    end
+
+    it 'clamps at 1.0' do
+      fossil.reinforce!(boost: 5.0)
+      expect(fossil.significance).to eq 1.0
+    end
+  end
+
+  describe '#imprint?' do
+    it 'returns true when preservation < 0.2' do
+      fossil.instance_variable_set(:@preservation, 0.1)
+      expect(fossil.imprint?).to be true
+    end
+
+    it 'returns false otherwise' do
+      expect(fossil.imprint?).to be false
+    end
+  end
+
+  describe '#keystone?' do
+    it 'returns true when significance >= 0.8' do
+      fossil.instance_variable_set(:@significance, 0.9)
+      expect(fossil.keystone?).to be true
+    end
+
+    it 'returns false otherwise' do
+      expect(fossil.keystone?).to be false
+    end
+  end
+
+  describe '#link_lineage' do
+    it 'adds ancestor' do
+      fossil.link_lineage('ancestor-id')
+      expect(fossil.lineage_ids).to include('ancestor-id')
+    end
+
+    it 'does not duplicate' do
+      fossil.link_lineage('same')
+      fossil.link_lineage('same')
+      expect(fossil.lineage_ids.count('same')).to eq 1
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all fields' do
+      %i[id fossil_type domain content extinction_cause era stratum_depth
+         preservation significance discovered_at extinct_at lineage_ids
+         imprint keystone ancient].each do |key|
+        expect(fossil.to_h).to have_key(key)
+      end
+    end
+  end
+end

data/spec/legion/extensions/agentic/memory/paleontology/helpers/paleontology_engine_spec.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Paleontology::Helpers::PaleontologyEngine do
+  let(:engine) { described_class.new }
+  let(:fossil_args) do
+    { fossil_type: :strategy, domain: :cognitive, content: 'old way',
+      extinction_cause: :obsolescence }
+  end
+
+  describe '#record_extinction' do
+    it 'creates a fossil' do
+      f = engine.record_extinction(**fossil_args)
+      expect(f.fossil_type).to eq :strategy
+    end
+
+    it 'tracks fossil in all_fossils' do
+      engine.record_extinction(**fossil_args)
+      expect(engine.all_fossils.size).to eq 1
+    end
+
+    it 'raises on invalid type' do
+      expect do
+        engine.record_extinction(fossil_type: :bogus, domain: :x,
+                                 content: 'x', extinction_cause: :obsolescence)
+      end.to raise_error(ArgumentError)
+    end
+  end
+
+  describe '#begin_excavation' do
+    it 'creates an excavation' do
+      exc = engine.begin_excavation(target_stratum: 1)
+      expect(exc.target_stratum).to eq 1
+    end
+
+    it 'tracks in all_excavations' do
+      engine.begin_excavation(target_stratum: 0)
+      expect(engine.all_excavations.size).to eq 1
+    end
+  end
+
+  describe '#excavate!' do
+    it 'returns fossil from matching stratum' do
+      engine.record_extinction(**fossil_args, stratum_depth: 1)
+      exc = engine.begin_excavation(target_stratum: 1)
+      result = engine.excavate!(excavation_id: exc.id)
+      expect(result).to be_a(
+        Legion::Extensions::Agentic::Memory::Paleontology::Helpers::Fossil
+      )
+    end
+
+    it 'returns nil when no fossils at stratum' do
+      exc = engine.begin_excavation(target_stratum: 3)
+      expect(engine.excavate!(excavation_id: exc.id)).to be_nil
+    end
+
+    it 'raises when excavation is completed' do
+      exc = engine.begin_excavation(target_stratum: 0)
+      exc.complete!
+      expect do
+        engine.excavate!(excavation_id: exc.id)
+      end.to raise_error(ArgumentError, /already completed/)
+    end
+  end
+
+  describe '#complete_excavation' do
+    it 'completes the excavation' do
+      exc = engine.begin_excavation(target_stratum: 0)
+      result = engine.complete_excavation(excavation_id: exc.id)
+      expect(result).to be_completed
+    end
+  end
+
+  describe '#erode_all!' do
+    it 'reduces preservation' do
+      f = engine.record_extinction(**fossil_args)
+      original = f.preservation
+      engine.erode_all!
+      expect(f.preservation).to be < original
+    end
+
+    it 'prunes fossils at 0.0' do
+      f = engine.record_extinction(**fossil_args)
+      f.instance_variable_set(:@preservation, 0.01)
+      engine.erode_all!(rate: 0.5)
+      expect(engine.all_fossils).not_to include(f)
+    end
+  end
+
+  describe '#link_lineage' do
+    it 'links two fossils' do
+      f1 = engine.record_extinction(**fossil_args, content: 'child')
+      f2 = engine.record_extinction(**fossil_args, content: 'parent')
+      engine.link_lineage(fossil_id: f1.id, ancestor_id: f2.id)
+      expect(f1.lineage_ids).to include(f2.id)
+    end
+  end
+
+  describe '#fossils_by_type' do
+    it 'filters correctly' do
+      engine.record_extinction(**fossil_args)
+      expect(engine.fossils_by_type(:strategy).size).to eq 1
+      expect(engine.fossils_by_type(:pattern)).to be_empty
+    end
+  end
+
+  describe '#fossils_by_cause' do
+    it 'filters correctly' do
+      engine.record_extinction(**fossil_args)
+      expect(engine.fossils_by_cause(:obsolescence).size).to eq 1
+    end
+  end
+
+  describe '#keystone_fossils' do
+    it 'returns only keystones' do
+      f = engine.record_extinction(**fossil_args, significance: 0.9)
+      expect(engine.keystone_fossils).to include(f)
+    end
+  end
+
+  describe '#mass_extinction?' do
+    it 'returns false normally' do
+      expect(engine.mass_extinction?).to be false
+    end
+
+    it 'returns true after many rapid extinctions' do
+      6.times do
+        engine.record_extinction(**fossil_args, content: SecureRandom.hex(4))
+      end
+      expect(engine.mass_extinction?(threshold: 5)).to be true
+    end
+  end
+
+  describe '#paleontology_report' do
+    it 'returns comprehensive report' do
+      engine.record_extinction(**fossil_args)
+      report = engine.paleontology_report
+      %i[total_fossils total_excavations type_breakdown cause_breakdown
+         era_breakdown avg_preservation avg_significance keystone_count
+         imprint_count ancient_count mass_extinction].each do |key|
+        expect(report).to have_key(key)
+      end
+    end
+
+    it 'works empty' do
+      expect(engine.paleontology_report[:total_fossils]).to eq 0
+    end
+  end
+end