lex-agentic-integration 0.1.0

data/spec/legion/extensions/agentic/integration/map/helpers/location_spec.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Integration::Map::Helpers::Location do
+  subject(:location) { described_class.new(id: 'concept:ruby', domain: :programming) }
+
+  describe '#initialize' do
+    it 'sets id and domain' do
+      expect(location.id).to eq('concept:ruby')
+      expect(location.domain).to eq(:programming)
+    end
+
+    it 'starts with floor familiarity' do
+      expect(location.familiarity).to eq(Legion::Extensions::Agentic::Integration::Map::Helpers::Constants::FAMILIARITY_FLOOR)
+    end
+
+    it 'starts with zero visit count' do
+      expect(location.visit_count).to eq(0)
+    end
+
+    it 'starts with no neighbors' do
+      expect(location.neighbors).to be_empty
+    end
+
+    it 'starts with no last_visited' do
+      expect(location.last_visited).to be_nil
+    end
+  end
+
+  describe '#visit' do
+    it 'increments visit count' do
+      location.visit
+      expect(location.visit_count).to eq(1)
+    end
+
+    it 'sets last_visited' do
+      before = Time.now.utc
+      location.visit
+      expect(location.last_visited).to be >= before
+    end
+
+    it 'boosts familiarity' do
+      before = location.familiarity
+      location.visit
+      expect(location.familiarity).to be > before
+    end
+
+    it 'clamps familiarity at 1.0' do
+      20.times { location.visit }
+      expect(location.familiarity).to be <= 1.0
+    end
+
+    it 'accumulates multiple visits' do
+      3.times { location.visit }
+      expect(location.visit_count).to eq(3)
+    end
+  end
+
+  describe '#add_neighbor' do
+    it 'adds a neighbor with default distance' do
+      location.add_neighbor('concept:python')
+      expect(location.neighbors).to have_key('concept:python')
+      expect(location.neighbors['concept:python']).to eq(Legion::Extensions::Agentic::Integration::Map::Helpers::Constants::DEFAULT_DISTANCE)
+    end
+
+    it 'adds a neighbor with custom distance' do
+      location.add_neighbor('concept:java', distance: 2.5)
+      expect(location.neighbors['concept:java']).to eq(2.5)
+    end
+
+    it 'enforces distance floor' do
+      location.add_neighbor('concept:c', distance: 0.0)
+      expect(location.neighbors['concept:c']).to eq(Legion::Extensions::Agentic::Integration::Map::Helpers::Constants::DISTANCE_FLOOR)
+    end
+
+    it 'updates existing neighbor distance' do
+      location.add_neighbor('concept:python', distance: 1.0)
+      location.add_neighbor('concept:python', distance: 0.5)
+      expect(location.neighbors['concept:python']).to eq(0.5)
+    end
+
+    it 'respects MAX_EDGES_PER_LOCATION limit' do
+      max = Legion::Extensions::Agentic::Integration::Map::Helpers::Constants::MAX_EDGES_PER_LOCATION
+      (max + 5).times { |i| location.add_neighbor("neighbor_#{i}") }
+      expect(location.neighbors.size).to be <= max
+    end
+  end
+
+  describe '#remove_neighbor' do
+    it 'removes an existing neighbor' do
+      location.add_neighbor('concept:python')
+      location.remove_neighbor('concept:python')
+      expect(location.neighbors).not_to have_key('concept:python')
+    end
+
+    it 'is a no-op for unknown neighbors' do
+      expect { location.remove_neighbor('nonexistent') }.not_to raise_error
+    end
+  end
+
+  describe '#decay' do
+    it 'reduces familiarity' do
+      location.visit # raise above floor first
+      before = location.familiarity
+      location.decay
+      expect(location.familiarity).to be < before
+    end
+
+    it 'does not go below FAMILIARITY_FLOOR' do
+      10.times { location.decay }
+      expect(location.familiarity).to be >= Legion::Extensions::Agentic::Integration::Map::Helpers::Constants::FAMILIARITY_FLOOR
+    end
+  end
+
+  describe '#faded?' do
+    it 'is true for a new location at floor familiarity with zero visits' do
+      expect(location.familiarity).to eq(Legion::Extensions::Agentic::Integration::Map::Helpers::Constants::FAMILIARITY_FLOOR)
+      expect(location.visit_count).to eq(0)
+      expect(location.faded?).to be true
+    end
+
+    it 'is false after visiting' do
+      location.visit
+      expect(location.faded?).to be false
+    end
+
+    it 'is false when familiarity is above floor even with zero visits' do
+      # familiarity raised manually above floor
+      2.times { location.visit }
+      # simulate decay back but not below floor — visit_count > 0 so still false
+      10.times { location.decay }
+      expect(location.faded?).to be false
+    end
+  end
+
+  describe '#label' do
+    it 'returns a familiarity level symbol' do
+      expect(location.label).to be_a(Symbol)
+    end
+
+    it 'returns :unknown for low familiarity' do
+      # familiarity_floor is 0.05, which is in the :unknown range (0.0...0.2)
+      expect(location.label).to eq(:unknown)
+    end
+
+    it 'returns :intimate for high familiarity' do
+      10.times { location.visit }
+      expect(location.label).to eq(:intimate)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with expected keys' do
+      h = location.to_h
+      expect(h).to include(:id, :domain, :properties, :familiarity, :label, :visit_count, :neighbor_ids, :edge_count)
+    end
+
+    it 'reflects current state' do
+      location.visit
+      location.add_neighbor('other')
+      h = location.to_h
+      expect(h[:visit_count]).to eq(1)
+      expect(h[:edge_count]).to eq(1)
+    end
+  end
+end

data/spec/legion/extensions/agentic/integration/map/runners/cognitive_map_spec.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/integration/map/client'
+
+RSpec.describe Legion::Extensions::Agentic::Integration::Map::Runners::CognitiveMap do
+  let(:client) { Legion::Extensions::Agentic::Integration::Map::Client.new }
+
+  def setup_two_locations
+    client.add_location(id: 'a', domain: :test)
+    client.add_location(id: 'b', domain: :test)
+    client.connect_locations(from: 'a', to: 'b', distance: 1.0)
+  end
+
+  describe '#add_location' do
+    it 'returns success: true for new location' do
+      result = client.add_location(id: 'concept:ruby')
+      expect(result[:success]).to be true
+      expect(result[:id]).to eq('concept:ruby')
+    end
+
+    it 'returns success: true for duplicate (idempotent)' do
+      client.add_location(id: 'concept:ruby')
+      result = client.add_location(id: 'concept:ruby')
+      expect(result[:success]).to be true
+    end
+
+    it 'passes domain through' do
+      result = client.add_location(id: 'loc1', domain: :science)
+      expect(result[:domain]).to eq(:science)
+    end
+  end
+
+  describe '#connect_locations' do
+    before { setup_two_locations }
+
+    it 'returns success: true' do
+      client.add_location(id: 'c')
+      result = client.connect_locations(from: 'a', to: 'c')
+      expect(result[:success]).to be true
+    end
+
+    it 'returns success: false for missing location' do
+      result = client.connect_locations(from: 'a', to: 'ghost')
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:missing_location)
+    end
+
+    it 'passes distance through' do
+      client.add_location(id: 'c')
+      result = client.connect_locations(from: 'a', to: 'c', distance: 2.5)
+      expect(result[:distance]).to eq(2.5)
+    end
+  end
+
+  describe '#visit_location' do
+    it 'returns success: true for existing location' do
+      client.add_location(id: 'loc1')
+      result = client.visit_location(id: 'loc1')
+      expect(result[:success]).to be true
+      expect(result[:visit_count]).to eq(1)
+    end
+
+    it 'returns success: false for missing location' do
+      result = client.visit_location(id: 'ghost')
+      expect(result[:success]).to be false
+    end
+
+    it 'increments visit count on repeated visits' do
+      client.add_location(id: 'loc1')
+      3.times { client.visit_location(id: 'loc1') }
+      result = client.visit_location(id: 'loc1')
+      expect(result[:visit_count]).to eq(4)
+    end
+  end
+
+  describe '#find_path' do
+    before { setup_two_locations }
+
+    it 'finds path between connected locations' do
+      result = client.find_path(from: 'a', to: 'b')
+      expect(result[:success]).to be true
+      expect(result[:path]).to eq(%w[a b])
+    end
+
+    it 'returns success: false for disconnected locations' do
+      client.add_location(id: 'island')
+      result = client.find_path(from: 'a', to: 'island')
+      expect(result[:success]).to be false
+    end
+
+    it 'returns trivial path for same start and end' do
+      result = client.find_path(from: 'a', to: 'a')
+      expect(result[:success]).to be true
+      expect(result[:distance]).to eq(0.0)
+    end
+  end
+
+  describe '#explore_neighborhood' do
+    before { setup_two_locations }
+
+    it 'returns reachable locations' do
+      result = client.explore_neighborhood(id: 'a', max_distance: 2.0)
+      expect(result[:success]).to be true
+      expect(result[:count]).to be >= 1
+    end
+
+    it 'respects max_distance' do
+      result = client.explore_neighborhood(id: 'a', max_distance: 0.5)
+      expect(result[:count]).to eq(0)
+    end
+
+    it 'returns success: true even for isolated location' do
+      client.add_location(id: 'island')
+      result = client.explore_neighborhood(id: 'island', max_distance: 5.0)
+      expect(result[:success]).to be true
+      expect(result[:count]).to eq(0)
+    end
+  end
+
+  describe '#map_clusters' do
+    it 'returns cluster information' do
+      client.add_location(id: 'a')
+      client.add_location(id: 'b')
+      client.connect_locations(from: 'a', to: 'b')
+      result = client.map_clusters
+      expect(result[:success]).to be true
+      expect(result[:count]).to eq(1)
+    end
+
+    it 'returns zero clusters for empty map' do
+      result = client.map_clusters
+      expect(result[:count]).to eq(0)
+    end
+  end
+
+  describe '#familiar_locations' do
+    it 'returns locations sorted by familiarity' do
+      3.times { |i| client.add_location(id: "loc_#{i}") }
+      5.times { client.visit_location(id: 'loc_0') }
+      result = client.familiar_locations(limit: 3)
+      expect(result[:success]).to be true
+      expect(result[:locations].first[:id]).to eq('loc_0')
+    end
+
+    it 'respects limit' do
+      5.times { |i| client.add_location(id: "loc_#{i}") }
+      result = client.familiar_locations(limit: 2)
+      expect(result[:count]).to be <= 2
+    end
+  end
+
+  describe '#switch_context' do
+    it 'switches to a new context' do
+      result = client.switch_context(context_id: :work)
+      expect(result[:success]).to be true
+    end
+
+    it 'new context has empty map' do
+      client.add_location(id: 'loc1')
+      client.switch_context(context_id: :empty_context)
+      stats = client.cognitive_map_stats
+      expect(stats[:location_count]).to eq(0)
+    end
+  end
+
+  describe '#update_cognitive_map' do
+    it 'runs decay cycle and returns counts' do
+      client.add_location(id: 'a')
+      client.visit_location(id: 'a')
+      result = client.update_cognitive_map
+      expect(result[:success]).to be true
+      expect(result).to include(:decayed, :pruned)
+    end
+  end
+
+  describe '#cognitive_map_stats' do
+    it 'returns stats with success: true' do
+      result = client.cognitive_map_stats
+      expect(result[:success]).to be true
+      expect(result).to include(:context, :location_count, :edge_count)
+    end
+
+    it 'reflects added locations' do
+      client.add_location(id: 'a')
+      client.add_location(id: 'b')
+      result = client.cognitive_map_stats
+      expect(result[:location_count]).to eq(2)
+    end
+  end
+end

data/spec/legion/extensions/agentic/integration/mosaic/client_spec.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Integration::Mosaic::Client do
+  subject(:client) { described_class.new }
+
+  it 'includes the runner module' do
+    expect(client).to respond_to(:create_tessera)
+  end
+
+  it 'includes all runner methods' do
+    %i[create_tessera create_mosaic place_tessera
+       list_tesserae list_mosaics mosaic_status].each do |m|
+      expect(client).to respond_to(m)
+    end
+  end
+end

data/spec/legion/extensions/agentic/integration/mosaic/helpers/constants_spec.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Integration::Mosaic::Helpers::Constants do
+  describe 'MATERIAL_TYPES' do
+    it 'has 10 material types' do
+      expect(described_class::MATERIAL_TYPES.size).to eq(10)
+    end
+
+    it 'includes core materials' do
+      %i[glass stone ceramic].each do |m|
+        expect(described_class::MATERIAL_TYPES).to include(m)
+      end
+    end
+  end
+
+  describe 'PATTERN_CATEGORIES' do
+    it 'includes standard categories' do
+      %i[geometric organic abstract narrative].each do |c|
+        expect(described_class::PATTERN_CATEGORIES).to include(c)
+      end
+    end
+  end
+
+  describe '.label_for' do
+    it 'returns masterwork for high completeness' do
+      expect(described_class.label_for(described_class::COMPLETENESS_LABELS, 0.95)).to eq(:masterwork)
+    end
+
+    it 'returns nascent for low completeness' do
+      expect(described_class.label_for(described_class::COMPLETENESS_LABELS, 0.1)).to eq(:nascent)
+    end
+
+    it 'returns harmonious for high coherence' do
+      expect(described_class.label_for(described_class::COHERENCE_LABELS, 0.9)).to eq(:harmonious)
+    end
+  end
+end

data/spec/legion/extensions/agentic/integration/mosaic/helpers/mosaic_engine_spec.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Integration::Mosaic::Helpers::MosaicEngine do
+  subject(:engine) { described_class.new }
+
+  describe '#create_tessera' do
+    it 'creates and stores a tessera' do
+      t = engine.create_tessera(material: :glass, domain: :reasoning, content: 'test')
+      expect(t).to be_a(Legion::Extensions::Agentic::Integration::Mosaic::Helpers::Tessera)
+    end
+
+    it 'raises when limit reached' do
+      stub_const('Legion::Extensions::Agentic::Integration::Mosaic::Helpers::Constants::MAX_TESSERAE', 1)
+      engine.create_tessera(material: :glass, domain: :x, content: 'a')
+      expect { engine.create_tessera(material: :glass, domain: :x, content: 'b') }
+        .to raise_error(ArgumentError, /tessera limit/)
+    end
+  end
+
+  describe '#create_mosaic' do
+    it 'creates and stores a mosaic' do
+      m = engine.create_mosaic(name: 'test', pattern_category: :geometric)
+      expect(m).to be_a(Legion::Extensions::Agentic::Integration::Mosaic::Helpers::Mosaic)
+    end
+
+    it 'raises when limit reached' do
+      stub_const('Legion::Extensions::Agentic::Integration::Mosaic::Helpers::Constants::MAX_MOSAICS', 1)
+      engine.create_mosaic(name: 'a', pattern_category: :organic)
+      expect { engine.create_mosaic(name: 'b', pattern_category: :organic) }
+        .to raise_error(ArgumentError, /mosaic limit/)
+    end
+  end
+
+  describe '#place_tessera' do
+    it 'places tessera into mosaic' do
+      t = engine.create_tessera(material: :stone, domain: :memory, content: 'piece')
+      m = engine.create_mosaic(name: 'wall', pattern_category: :abstract)
+      engine.place_tessera(tessera_id: t.id, mosaic_id: m.id)
+      expect(t.placed?).to be true
+      expect(m.size).to eq(1)
+    end
+
+    it 'raises for already placed tessera' do
+      t = engine.create_tessera(material: :glass, domain: :x, content: 'a')
+      m = engine.create_mosaic(name: 'x', pattern_category: :geometric)
+      engine.place_tessera(tessera_id: t.id, mosaic_id: m.id)
+      m2 = engine.create_mosaic(name: 'y', pattern_category: :organic)
+      expect { engine.place_tessera(tessera_id: t.id, mosaic_id: m2.id) }
+        .to raise_error(ArgumentError, /already placed/)
+    end
+  end
+
+  describe '#erode_all_grout!' do
+    it 'erodes grout on all mosaics' do
+      m = engine.create_mosaic(name: 'wall', pattern_category: :geometric)
+      old = m.grout_strength
+      engine.erode_all_grout!
+      expect(m.grout_strength).to be < old
+    end
+  end
+
+  describe '#most_complete' do
+    it 'returns mosaics by completeness' do
+      engine.create_mosaic(name: 'empty', pattern_category: :organic, capacity: 10)
+      m2 = engine.create_mosaic(name: 'full', pattern_category: :organic, capacity: 2)
+      t1 = engine.create_tessera(material: :glass, domain: :x, content: 'a')
+      t2 = engine.create_tessera(material: :glass, domain: :x, content: 'b')
+      engine.place_tessera(tessera_id: t1.id, mosaic_id: m2.id)
+      engine.place_tessera(tessera_id: t2.id, mosaic_id: m2.id)
+      expect(engine.most_complete(limit: 1).first).to eq(m2)
+    end
+  end
+
+  describe '#loose_tesserae' do
+    it 'returns unplaced tesserae' do
+      t1 = engine.create_tessera(material: :glass, domain: :x, content: 'loose')
+      t2 = engine.create_tessera(material: :stone, domain: :x, content: 'placed')
+      m = engine.create_mosaic(name: 'wall', pattern_category: :geometric)
+      engine.place_tessera(tessera_id: t2.id, mosaic_id: m.id)
+      expect(engine.loose_tesserae).to eq([t1])
+    end
+  end
+
+  describe '#coherence' do
+    it 'returns 0.0 for empty mosaic' do
+      m = engine.create_mosaic(name: 'empty', pattern_category: :geometric)
+      expect(engine.coherence(mosaic_id: m.id)).to eq(0.0)
+    end
+
+    it 'returns positive for populated mosaic' do
+      m = engine.create_mosaic(name: 'wall', pattern_category: :geometric)
+      t = engine.create_tessera(material: :glass, domain: :x, content: 'a', fit_quality: 0.8)
+      engine.place_tessera(tessera_id: t.id, mosaic_id: m.id)
+      expect(engine.coherence(mosaic_id: m.id)).to be > 0.0
+    end
+  end
+
+  describe '#mosaic_report' do
+    it 'returns comprehensive report' do
+      engine.create_tessera(material: :glass, domain: :x, content: 'a')
+      report = engine.mosaic_report
+      %i[total_tesserae total_mosaics loose_count by_material
+         crumbling_count avg_completeness].each do |k|
+        expect(report).to have_key(k)
+      end
+    end
+  end
+end

data/spec/legion/extensions/agentic/integration/mosaic/helpers/mosaic_spec.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Integration::Mosaic::Helpers::Mosaic do
+  subject(:mosaic) do
+    described_class.new(name: 'Decision Map', pattern_category: :geometric)
+  end
+
+  describe '#initialize' do
+    it 'sets name' do
+      expect(mosaic.name).to eq('Decision Map')
+    end
+
+    it 'sets pattern category' do
+      expect(mosaic.pattern_category).to eq(:geometric)
+    end
+
+    it 'defaults capacity to 50' do
+      expect(mosaic.capacity).to eq(50)
+    end
+
+    it 'defaults grout_strength to 0.8' do
+      expect(mosaic.grout_strength).to eq(0.8)
+    end
+
+    it 'starts empty' do
+      expect(mosaic.empty?).to be true
+    end
+
+    it 'rejects unknown pattern categories' do
+      expect { described_class.new(name: 'x', pattern_category: :random) }
+        .to raise_error(ArgumentError, /unknown pattern category/)
+    end
+  end
+
+  describe '#add_tessera' do
+    it 'adds tessera id' do
+      expect(mosaic.add_tessera('t1')).to be true
+      expect(mosaic.size).to eq(1)
+    end
+
+    it 'rejects duplicates' do
+      mosaic.add_tessera('t1')
+      expect(mosaic.add_tessera('t1')).to be false
+    end
+
+    it 'rejects when full' do
+      m = described_class.new(name: 'tiny', pattern_category: :organic, capacity: 1)
+      m.add_tessera('t1')
+      expect(m.add_tessera('t2')).to be false
+    end
+  end
+
+  describe '#remove_tessera' do
+    it 'removes existing tessera' do
+      mosaic.add_tessera('t1')
+      expect(mosaic.remove_tessera('t1')).to be true
+      expect(mosaic.size).to eq(0)
+    end
+
+    it 'returns false for missing tessera' do
+      expect(mosaic.remove_tessera('nope')).to be false
+    end
+  end
+
+  describe '#completeness' do
+    it 'returns 0.0 when empty' do
+      expect(mosaic.completeness).to eq(0.0)
+    end
+
+    it 'increases with tesserae' do
+      5.times { |i| mosaic.add_tessera("t#{i}") }
+      expect(mosaic.completeness).to eq(0.1)
+    end
+  end
+
+  describe '#erode_grout!' do
+    it 'reduces grout strength' do
+      old = mosaic.grout_strength
+      mosaic.erode_grout!
+      expect(mosaic.grout_strength).to be < old
+    end
+  end
+
+  describe '#reinforce_grout!' do
+    it 'increases grout strength' do
+      mosaic.erode_grout!(rate: 0.3)
+      old = mosaic.grout_strength
+      mosaic.reinforce_grout!
+      expect(mosaic.grout_strength).to be > old
+    end
+  end
+
+  describe '#crumbling?' do
+    it 'returns false at default strength' do
+      expect(mosaic.crumbling?).to be false
+    end
+
+    it 'returns true when grout decays heavily' do
+      20.times { mosaic.erode_grout!(rate: 0.1) }
+      expect(mosaic.crumbling?).to be true
+    end
+  end
+
+  describe '#gap_count' do
+    it 'equals capacity when empty' do
+      expect(mosaic.gap_count).to eq(50)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns all keys' do
+      h = mosaic.to_h
+      %i[id name pattern_category tessera_ids size capacity
+         completeness completeness_label grout_strength gap_count
+         full empty crumbling created_at].each do |k|
+        expect(h).to have_key(k)
+      end
+    end
+  end
+end