lex-agentic-social 0.1.0

data/spec/legion/extensions/agentic/social/symbiosis/helpers/ecosystem_spec.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Social::Symbiosis::Helpers::Ecosystem do
+  subject(:ecosystem) { described_class.new }
+
+  let(:bond_class) { Legion::Extensions::Agentic::Social::Symbiosis::Helpers::SymbioticBond }
+  let(:constants)  { Legion::Extensions::Agentic::Social::Symbiosis::Helpers::Constants }
+
+  def make_bond(sys_a, sys_b, rel_type, strength: 0.5)
+    bond_class.new(subsystem_a: sys_a, subsystem_b: sys_b, relationship_type: rel_type, strength: strength)
+  end
+
+  describe '#register_bond' do
+    it 'registers a bond and returns it' do
+      bond = make_bond('memory', 'emotion', :mutualistic)
+      result = ecosystem.register_bond(bond)
+      expect(result).to be(bond)
+    end
+
+    it 'increments bond_count' do
+      ecosystem.register_bond(make_bond('a', 'b', :mutualistic))
+      expect(ecosystem.bond_count).to eq(1)
+    end
+
+    it 'raises ArgumentError for non-bond object' do
+      expect { ecosystem.register_bond('not_a_bond') }.to raise_error(ArgumentError, /must be a SymbioticBond/)
+    end
+
+    it 'raises ArgumentError when MAX_BONDS exceeded' do
+      constants::MAX_BONDS.times do |i|
+        b = bond_class.new(subsystem_a: "sys#{i}a", subsystem_b: "sys#{i}b", relationship_type: :commensal)
+        ecosystem.register_bond(b)
+      end
+      extra = make_bond('overflow_a', 'overflow_b', :mutualistic)
+      expect { ecosystem.register_bond(extra) }.to raise_error(ArgumentError, /MAX_BONDS/)
+    end
+  end
+
+  describe '#activate_bond' do
+    let(:bond) { make_bond('memory', 'emotion', :mutualistic) }
+
+    before { ecosystem.register_bond(bond) }
+
+    it 'returns found: true for existing bond' do
+      result = ecosystem.activate_bond(bond.bond_id)
+      expect(result[:found]).to be true
+    end
+
+    it 'increases strength on activation' do
+      before = bond.strength
+      ecosystem.activate_bond(bond.bond_id, amount: 0.1)
+      expect(bond.strength).to be > before
+    end
+
+    it 'returns found: false for unknown bond_id' do
+      result = ecosystem.activate_bond('nonexistent')
+      expect(result[:found]).to be false
+    end
+  end
+
+  describe '#measure_health' do
+    it 'returns 0.0 for empty ecosystem' do
+      expect(ecosystem.measure_health).to eq(0.0)
+    end
+
+    it 'returns higher score for more mutualistic bonds' do
+      3.times { |i| ecosystem.register_bond(make_bond("m#{i}a", "m#{i}b", :mutualistic)) }
+      expect(ecosystem.measure_health).to be > 0.5
+    end
+
+    it 'returns lower score when parasitic bonds present' do
+      ecosystem.register_bond(make_bond('a', 'b', :mutualistic))
+      ecosystem.register_bond(make_bond('c', 'd', :parasitic))
+      expect(ecosystem.measure_health).to be < 1.0
+    end
+
+    it 'returns 0.0 when only dormant bonds exist' do
+      dormant = make_bond('a', 'b', :mutualistic, strength: 0.0)
+      ecosystem.register_bond(dormant)
+      expect(ecosystem.measure_health).to eq(0.0)
+    end
+  end
+
+  describe '#health_label' do
+    it 'returns :critical for empty ecosystem' do
+      expect(ecosystem.health_label).to eq(:critical)
+    end
+
+    it 'returns a symbol label' do
+      ecosystem.register_bond(make_bond('a', 'b', :mutualistic))
+      expect(ecosystem.health_label).to be_a(Symbol)
+    end
+  end
+
+  describe '#most_beneficial' do
+    it 'returns nil when no mutualistic bonds' do
+      ecosystem.register_bond(make_bond('a', 'b', :parasitic))
+      expect(ecosystem.most_beneficial).to be_nil
+    end
+
+    it 'returns the mutualistic bond with highest benefit*strength' do
+      low  = bond_class.new(subsystem_a: 'a', subsystem_b: 'b', relationship_type: :mutualistic, strength: 0.3, benefit_ratio: 0.2)
+      high = bond_class.new(subsystem_a: 'c', subsystem_b: 'd', relationship_type: :mutualistic, strength: 0.9, benefit_ratio: 0.9)
+      ecosystem.register_bond(low)
+      ecosystem.register_bond(high)
+      expect(ecosystem.most_beneficial).to be(high)
+    end
+  end
+
+  describe '#most_parasitic' do
+    it 'returns nil when no parasitic bonds' do
+      ecosystem.register_bond(make_bond('a', 'b', :mutualistic))
+      expect(ecosystem.most_parasitic).to be_nil
+    end
+
+    it 'returns parasitic bond' do
+      ecosystem.register_bond(make_bond('x', 'y', :parasitic))
+      expect(ecosystem.most_parasitic).not_to be_nil
+    end
+  end
+
+  describe '#decay_all!' do
+    it 'decays all bonds and returns count' do
+      3.times { |i| ecosystem.register_bond(make_bond("a#{i}", "b#{i}", :mutualistic)) }
+      count = ecosystem.decay_all!
+      expect(count).to eq(3)
+    end
+  end
+
+  describe '#network_density' do
+    it 'returns 0.0 for empty ecosystem' do
+      expect(ecosystem.network_density).to eq(0.0)
+    end
+
+    it 'returns average strength of active bonds' do
+      ecosystem.register_bond(make_bond('a', 'b', :mutualistic, strength: 0.8))
+      ecosystem.register_bond(make_bond('c', 'd', :mutualistic, strength: 0.4))
+      expect(ecosystem.network_density).to be_within(0.01).of(0.6)
+    end
+  end
+
+  describe '#symbiotic_web' do
+    it 'returns all bonds involving a subsystem' do
+      ecosystem.register_bond(make_bond('memory', 'emotion', :mutualistic))
+      ecosystem.register_bond(make_bond('memory', 'prediction', :commensal))
+      ecosystem.register_bond(make_bond('trust', 'consent', :mutualistic))
+      web = ecosystem.symbiotic_web('memory')
+      expect(web.size).to eq(2)
+    end
+
+    it 'returns empty array for unknown subsystem' do
+      expect(ecosystem.symbiotic_web('nobody')).to be_empty
+    end
+  end
+
+  describe '#find_bond' do
+    before { ecosystem.register_bond(make_bond('alpha', 'beta', :mutualistic)) }
+
+    it 'finds bond by exact pair' do
+      expect(ecosystem.find_bond('alpha', 'beta')).not_to be_nil
+    end
+
+    it 'finds bond in reverse order' do
+      expect(ecosystem.find_bond('beta', 'alpha')).not_to be_nil
+    end
+
+    it 'returns nil for unknown pair' do
+      expect(ecosystem.find_bond('x', 'y')).to be_nil
+    end
+  end
+
+  describe '#all_bonds / #active_bonds' do
+    it 'all_bonds returns all including dormant' do
+      ecosystem.register_bond(make_bond('a', 'b', :commensal, strength: 0.0))
+      ecosystem.register_bond(make_bond('c', 'd', :mutualistic, strength: 0.5))
+      expect(ecosystem.all_bonds.size).to eq(2)
+    end
+
+    it 'active_bonds excludes dormant bonds' do
+      ecosystem.register_bond(make_bond('a', 'b', :commensal, strength: 0.0))
+      ecosystem.register_bond(make_bond('c', 'd', :mutualistic, strength: 0.5))
+      expect(ecosystem.active_bonds.size).to eq(1)
+    end
+  end
+end

data/spec/legion/extensions/agentic/social/symbiosis/helpers/symbiosis_engine_spec.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Social::Symbiosis::Helpers::SymbiosisEngine do
+  subject(:engine) { described_class.new }
+
+  describe '#create_bond' do
+    it 'creates a mutualistic bond and returns created: true' do
+      result = engine.create_bond(subsystem_a: 'memory', subsystem_b: 'emotion', relationship_type: :mutualistic)
+      expect(result[:created]).to be true
+      expect(result[:bond][:relationship_type]).to eq(:mutualistic)
+    end
+
+    it 'creates a parasitic bond' do
+      result = engine.create_bond(subsystem_a: 'cortex', subsystem_b: 'tick', relationship_type: :parasitic)
+      expect(result[:created]).to be true
+    end
+
+    it 'creates a commensal bond' do
+      result = engine.create_bond(subsystem_a: 'trust', subsystem_b: 'identity', relationship_type: :commensal)
+      expect(result[:created]).to be true
+    end
+
+    it 'returns created: false when bond already exists' do
+      engine.create_bond(subsystem_a: 'memory', subsystem_b: 'emotion', relationship_type: :mutualistic)
+      result = engine.create_bond(subsystem_a: 'memory', subsystem_b: 'emotion', relationship_type: :commensal)
+      expect(result[:created]).to be false
+      expect(result[:reason]).to eq(:already_exists)
+    end
+
+    it 'returns created: false for invalid relationship_type' do
+      result = engine.create_bond(subsystem_a: 'a', subsystem_b: 'b', relationship_type: :bogus)
+      expect(result[:created]).to be false
+      expect(result[:reason]).to eq(:invalid_arguments)
+    end
+
+    it 'accepts explicit strength' do
+      result = engine.create_bond(subsystem_a: 'a', subsystem_b: 'b', relationship_type: :mutualistic, strength: 0.9)
+      expect(result[:bond][:strength]).to eq(0.9)
+    end
+
+    it 'accepts explicit benefit_ratio' do
+      result = engine.create_bond(subsystem_a: 'a', subsystem_b: 'b', relationship_type: :mutualistic, benefit_ratio: 0.75)
+      expect(result[:bond][:benefit_ratio]).to eq(0.75)
+    end
+  end
+
+  describe '#activate_interaction' do
+    before { engine.create_bond(subsystem_a: 'memory', subsystem_b: 'emotion', relationship_type: :mutualistic) }
+
+    it 'activates an existing bond' do
+      result = engine.activate_interaction(subsystem_a: 'memory', subsystem_b: 'emotion')
+      expect(result[:found]).to be true
+    end
+
+    it 'returns relationship_type in result' do
+      result = engine.activate_interaction(subsystem_a: 'memory', subsystem_b: 'emotion')
+      expect(result[:relationship_type]).to eq(:mutualistic)
+    end
+
+    it 'returns found: false for unknown pair' do
+      result = engine.activate_interaction(subsystem_a: 'x', subsystem_b: 'y')
+      expect(result[:found]).to be false
+    end
+
+    it 'works in reverse order' do
+      result = engine.activate_interaction(subsystem_a: 'emotion', subsystem_b: 'memory')
+      expect(result[:found]).to be true
+    end
+  end
+
+  describe '#measure_ecosystem_health' do
+    it 'returns a hash with score, label, bond_count, active_bonds, network_density' do
+      result = engine.measure_ecosystem_health
+      expect(result).to include(:score, :label, :bond_count, :active_bonds, :network_density)
+    end
+
+    it 'returns score 0.0 for fresh engine' do
+      expect(engine.measure_ecosystem_health[:score]).to eq(0.0)
+    end
+
+    it 'returns higher score after adding mutualistic bonds' do
+      engine.create_bond(subsystem_a: 'a', subsystem_b: 'b', relationship_type: :mutualistic)
+      expect(engine.measure_ecosystem_health[:score]).to be > 0
+    end
+  end
+
+  describe '#find_partners' do
+    before do
+      engine.create_bond(subsystem_a: 'memory', subsystem_b: 'emotion', relationship_type: :mutualistic, strength: 0.7)
+      engine.create_bond(subsystem_a: 'memory', subsystem_b: 'prediction', relationship_type: :parasitic, strength: 0.5)
+      engine.create_bond(subsystem_a: 'trust', subsystem_b: 'consent', relationship_type: :mutualistic, strength: 0.6)
+    end
+
+    it 'returns partners of a subsystem with positive benefit_ratio by default' do
+      partners = engine.find_partners('memory')
+      subsystems = partners.map { |p| p[:partner] }
+      expect(subsystems).to include('emotion')
+    end
+
+    it 'includes parasitic partners when min_benefit_ratio allows negatives' do
+      partners = engine.find_partners('memory', min_benefit_ratio: -1.0)
+      subsystems = partners.map { |p| p[:partner] }
+      expect(subsystems).to include('emotion', 'prediction')
+    end
+
+    it 'filters by min_benefit_ratio to exclude parasitic' do
+      partners = engine.find_partners('memory', min_benefit_ratio: 0.0)
+      types = partners.map { |p| p[:relationship_type] }
+      expect(types).not_to include(:parasitic)
+    end
+
+    it 'returns empty array for unknown subsystem' do
+      expect(engine.find_partners('nobody')).to be_empty
+    end
+
+    it 'sorts by strength descending' do
+      partners = engine.find_partners('memory', min_benefit_ratio: -1.0)
+      strengths = partners.map { |p| p[:strength] }
+      expect(strengths).to eq(strengths.sort.reverse)
+    end
+  end
+
+  describe '#detect_parasites' do
+    before do
+      engine.create_bond(subsystem_a: 'cortex', subsystem_b: 'emotion', relationship_type: :parasitic, strength: 0.6)
+      engine.create_bond(subsystem_a: 'memory', subsystem_b: 'trust', relationship_type: :mutualistic, strength: 0.5)
+    end
+
+    it 'returns only parasitic bonds' do
+      result = engine.detect_parasites
+      types = result.map { |b| b[:relationship_type] }
+      expect(types).to all(eq(:parasitic))
+    end
+
+    it 'excludes bonds below strength_threshold' do
+      result = engine.detect_parasites(strength_threshold: 0.8)
+      expect(result).to be_empty
+    end
+
+    it 'returns dormant parasitic bonds when threshold is 0' do
+      engine.create_bond(subsystem_a: 'a', subsystem_b: 'b', relationship_type: :parasitic, strength: 0.4)
+      result = engine.detect_parasites
+      expect(result.size).to be >= 1
+    end
+  end
+
+  describe '#ecosystem_report' do
+    before do
+      engine.create_bond(subsystem_a: 'memory', subsystem_b: 'emotion', relationship_type: :mutualistic, strength: 0.5)
+      engine.create_bond(subsystem_a: 'cortex', subsystem_b: 'tick', relationship_type: :parasitic, strength: 0.4)
+    end
+
+    it 'returns expected keys' do
+      report = engine.ecosystem_report
+      expect(report).to include(:health, :bonds_by_type, :most_beneficial, :most_parasitic, :total_bonds, :dormant_bonds)
+    end
+
+    it 'bonds_by_type contains all three relationship types' do
+      report = engine.ecosystem_report
+      expect(report[:bonds_by_type].keys).to include(:mutualistic, :parasitic, :commensal)
+    end
+
+    it 'total_bonds matches registered count' do
+      report = engine.ecosystem_report
+      expect(report[:total_bonds]).to eq(2)
+    end
+
+    it 'most_beneficial refers to mutualistic bond' do
+      report = engine.ecosystem_report
+      expect(report[:most_beneficial][:relationship_type]).to eq(:mutualistic)
+    end
+  end
+
+  describe '#decay_all' do
+    it 'returns decayed count and health_after' do
+      engine.create_bond(subsystem_a: 'a', subsystem_b: 'b', relationship_type: :mutualistic)
+      result = engine.decay_all
+      expect(result).to include(:decayed, :health_after)
+      expect(result[:decayed]).to eq(1)
+    end
+  end
+end

data/spec/legion/extensions/agentic/social/symbiosis/helpers/symbiotic_bond_spec.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Social::Symbiosis::Helpers::SymbioticBond do
+  let(:bond) do
+    described_class.new(
+      subsystem_a:       'memory',
+      subsystem_b:       'emotion',
+      relationship_type: :mutualistic
+    )
+  end
+
+  describe '#initialize' do
+    it 'assigns subsystem_a and subsystem_b' do
+      expect(bond.subsystem_a).to eq('memory')
+      expect(bond.subsystem_b).to eq('emotion')
+    end
+
+    it 'assigns relationship_type' do
+      expect(bond.relationship_type).to eq(:mutualistic)
+    end
+
+    it 'assigns a uuid bond_id' do
+      expect(bond.bond_id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets default strength when not provided' do
+      expect(bond.strength).to eq(
+        Legion::Extensions::Agentic::Social::Symbiosis::Helpers::Constants::DEFAULT_STRENGTH
+      )
+    end
+
+    it 'clamps strength to 0.0..1.0' do
+      b = described_class.new(subsystem_a: 'a', subsystem_b: 'b', relationship_type: :mutualistic, strength: 5.0)
+      expect(b.strength).to eq(1.0)
+    end
+
+    it 'clamps negative strength to 0.0' do
+      b = described_class.new(subsystem_a: 'a', subsystem_b: 'b', relationship_type: :mutualistic, strength: -1.0)
+      expect(b.strength).to eq(0.0)
+    end
+
+    it 'assigns a positive benefit_ratio for mutualistic by default' do
+      expect(bond.benefit_ratio).to be > 0
+    end
+
+    it 'assigns a negative benefit_ratio for parasitic by default' do
+      b = described_class.new(subsystem_a: 'a', subsystem_b: 'b', relationship_type: :parasitic)
+      expect(b.benefit_ratio).to be < 0
+    end
+
+    it 'accepts explicit benefit_ratio' do
+      b = described_class.new(subsystem_a: 'a', subsystem_b: 'b', relationship_type: :mutualistic, benefit_ratio: 0.8)
+      expect(b.benefit_ratio).to eq(0.8)
+    end
+
+    it 'sets activation_count to 0' do
+      expect(bond.activation_count).to eq(0)
+    end
+
+    it 'sets last_activated_at to nil' do
+      expect(bond.last_activated_at).to be_nil
+    end
+
+    it 'raises ArgumentError for unknown relationship_type' do
+      expect do
+        described_class.new(subsystem_a: 'a', subsystem_b: 'b', relationship_type: :unknown)
+      end.to raise_error(ArgumentError, /unknown relationship_type/)
+    end
+  end
+
+  describe '#activate!' do
+    it 'increases strength' do
+      before = bond.strength
+      bond.activate!(amount: 0.1)
+      expect(bond.strength).to be > before
+    end
+
+    it 'increments activation_count' do
+      bond.activate!
+      expect(bond.activation_count).to eq(1)
+    end
+
+    it 'sets last_activated_at' do
+      bond.activate!
+      expect(bond.last_activated_at).not_to be_nil
+    end
+
+    it 'does not exceed MAX_STRENGTH' do
+      bond.activate!(amount: 10.0)
+      expect(bond.strength).to eq(1.0)
+    end
+
+    it 'clamps amount to 1.0 max' do
+      bond.activate!(amount: 99.0)
+      expect(bond.strength).to eq(1.0)
+    end
+
+    it 'returns self for chaining' do
+      expect(bond.activate!).to be(bond)
+    end
+  end
+
+  describe '#decay!' do
+    it 'decreases strength' do
+      bond.activate!(amount: 0.5)
+      before = bond.strength
+      bond.decay!
+      expect(bond.strength).to be < before
+    end
+
+    it 'does not go below MIN_STRENGTH' do
+      50.times { bond.decay! }
+      expect(bond.strength).to eq(0.0)
+    end
+
+    it 'returns self for chaining' do
+      expect(bond.decay!).to be(bond)
+    end
+  end
+
+  describe '#dormant?' do
+    it 'returns true when strength is at or below DORMANT_THRESHOLD' do
+      b = described_class.new(
+        subsystem_a: 'a', subsystem_b: 'b', relationship_type: :commensal,
+        strength: Legion::Extensions::Agentic::Social::Symbiosis::Helpers::Constants::DORMANT_THRESHOLD
+      )
+      expect(b.dormant?).to be true
+    end
+
+    it 'returns false for active bond' do
+      bond.activate!(amount: 0.5)
+      expect(bond.dormant?).to be false
+    end
+  end
+
+  describe '#strong?' do
+    it 'returns false by default' do
+      expect(bond.strong?).to be false
+    end
+
+    it 'returns true when strength meets STRONG_THRESHOLD' do
+      b = described_class.new(
+        subsystem_a: 'a', subsystem_b: 'b', relationship_type: :mutualistic,
+        strength: Legion::Extensions::Agentic::Social::Symbiosis::Helpers::Constants::STRONG_THRESHOLD
+      )
+      expect(b.strong?).to be true
+    end
+  end
+
+  describe '#strength_label' do
+    it 'returns :dormant for very low strength' do
+      b = described_class.new(subsystem_a: 'a', subsystem_b: 'b', relationship_type: :commensal, strength: 0.01)
+      expect(b.strength_label).to eq(:dormant)
+    end
+
+    it 'returns :dominant for very high strength' do
+      b = described_class.new(subsystem_a: 'a', subsystem_b: 'b', relationship_type: :mutualistic, strength: 0.95)
+      expect(b.strength_label).to eq(:dominant)
+    end
+  end
+
+  describe '#involves?' do
+    it 'returns true when subsystem_a matches' do
+      expect(bond.involves?('memory')).to be true
+    end
+
+    it 'returns true when subsystem_b matches' do
+      expect(bond.involves?('emotion')).to be true
+    end
+
+    it 'returns false for unrelated subsystem' do
+      expect(bond.involves?('prediction')).to be false
+    end
+  end
+
+  describe '#partner_of' do
+    it 'returns subsystem_b when given subsystem_a' do
+      expect(bond.partner_of('memory')).to eq('emotion')
+    end
+
+    it 'returns subsystem_a when given subsystem_b' do
+      expect(bond.partner_of('emotion')).to eq('memory')
+    end
+
+    it 'returns nil for unknown subsystem' do
+      expect(bond.partner_of('unknown')).to be_nil
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all required keys' do
+      h = bond.to_h
+      expect(h).to include(
+        :bond_id, :subsystem_a, :subsystem_b, :relationship_type,
+        :strength, :strength_label, :benefit_ratio, :activation_count,
+        :dormant, :strong, :created_at, :last_activated_at
+      )
+    end
+
+    it 'last_activated_at is nil before first activation' do
+      expect(bond.to_h[:last_activated_at]).to be_nil
+    end
+
+    it 'last_activated_at is an ISO8601 string after activation' do
+      bond.activate!
+      expect(bond.to_h[:last_activated_at]).to match(/\d{4}-\d{2}-\d{2}T/)
+    end
+  end
+end