lex-agentic-learning 0.1.0

data/spec/legion/extensions/agentic/learning/chrysalis/helpers/chrysalis_spec.rb

@@ -0,0 +1,305 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Learning::Chrysalis::Helpers::Chrysalis do
+  subject(:chrysalis) { described_class.new(chrysalis_type: :silk, content: 'a new idea') }
+
+  describe '#initialize' do
+    it 'assigns a uuid id' do
+      expect(chrysalis.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets chrysalis_type to the given symbol' do
+      expect(chrysalis.chrysalis_type).to eq(:silk)
+    end
+
+    it 'sets content to the given string' do
+      expect(chrysalis.content).to eq('a new idea')
+    end
+
+    it 'starts in :larva stage' do
+      expect(chrysalis.stage).to eq(:larva)
+    end
+
+    it 'starts with transformation_progress 0.0' do
+      expect(chrysalis.transformation_progress).to eq(0.0)
+    end
+
+    it 'starts with protection 0.8' do
+      expect(chrysalis.protection).to eq(0.8)
+    end
+
+    it 'starts with beauty 0.0' do
+      expect(chrysalis.beauty).to eq(0.0)
+    end
+
+    it 'records created_at as a Time' do
+      expect(chrysalis.created_at).to be_a(Time)
+    end
+  end
+
+  describe '#spin!' do
+    it 'transitions stage from :larva to :spinning' do
+      chrysalis.spin!
+      expect(chrysalis.stage).to eq(:spinning)
+    end
+
+    it 'returns true' do
+      expect(chrysalis.spin!).to be true
+    end
+
+    it 'raises ArgumentError when not in :larva stage' do
+      chrysalis.spin!
+      expect { chrysalis.spin! }.to raise_error(ArgumentError)
+    end
+  end
+
+  describe '#cocoon!' do
+    before { chrysalis.spin! }
+
+    it 'transitions stage from :spinning to :cocooned' do
+      chrysalis.cocoon!
+      expect(chrysalis.stage).to eq(:cocooned)
+    end
+
+    it 'returns true' do
+      expect(chrysalis.cocoon!).to be true
+    end
+
+    it 'raises ArgumentError when not in :spinning stage' do
+      chrysalis.cocoon!
+      expect { chrysalis.cocoon! }.to raise_error(ArgumentError)
+    end
+  end
+
+  describe '#transform!' do
+    it 'increments transformation_progress by TRANSFORMATION_RATE by default' do
+      chrysalis.transform!
+      expect(chrysalis.transformation_progress).to be_within(0.0001).of(0.08)
+    end
+
+    it 'accepts a custom rate' do
+      chrysalis.transform!(0.2)
+      expect(chrysalis.transformation_progress).to be_within(0.0001).of(0.2)
+    end
+
+    it 'increases beauty proportionally' do
+      chrysalis.transform!(0.5)
+      expect(chrysalis.beauty).to be > 0.0
+    end
+
+    it 'clamps transformation_progress to 1.0' do
+      15.times { chrysalis.transform! }
+      expect(chrysalis.transformation_progress).to eq(1.0)
+    end
+
+    it 'returns false when already a butterfly' do
+      chrysalis.transform!(1.0)
+      chrysalis.emerge!
+      expect(chrysalis.transform!).to be false
+    end
+
+    it 'updates stage when progress crosses 0.6 threshold' do
+      chrysalis.transform!(0.65)
+      expect(chrysalis.stage).to eq(:transforming)
+    end
+
+    it 'updates stage to :emerging when progress crosses 0.8 threshold' do
+      chrysalis.transform!(0.85)
+      expect(chrysalis.stage).to eq(:emerging)
+    end
+  end
+
+  describe '#emerge!' do
+    context 'when transformation_progress >= EMERGENCE_THRESHOLD' do
+      before { chrysalis.transform!(0.95) }
+
+      it 'transitions to :butterfly' do
+        chrysalis.emerge!
+        expect(chrysalis.stage).to eq(:butterfly)
+      end
+
+      it 'sets beauty to 1.0' do
+        chrysalis.emerge!
+        expect(chrysalis.beauty).to eq(1.0)
+      end
+
+      it 'returns true' do
+        expect(chrysalis.emerge!).to be true
+      end
+    end
+
+    context 'when transformation_progress < EMERGENCE_THRESHOLD' do
+      it 'returns false without forcing' do
+        chrysalis.transform!(0.5)
+        expect(chrysalis.emerge!).to be false
+      end
+
+      it 'stage remains unchanged' do
+        chrysalis.transform!(0.5)
+        stage_before = chrysalis.stage
+        chrysalis.emerge!
+        expect(chrysalis.stage).to eq(stage_before)
+      end
+    end
+
+    context 'when forced early' do
+      before { chrysalis.transform!(0.3) }
+
+      it 'transitions to :butterfly' do
+        chrysalis.emerge!(force: true)
+        expect(chrysalis.stage).to eq(:butterfly)
+      end
+
+      it 'applies PREMATURE_PENALTY to beauty' do
+        beauty_before = chrysalis.beauty
+        chrysalis.emerge!(force: true)
+        expect(chrysalis.beauty).to be <= beauty_before
+      end
+
+      it 'returns true' do
+        expect(chrysalis.emerge!(force: true)).to be true
+      end
+    end
+  end
+
+  describe '#decay_protection!' do
+    it 'reduces protection by PROTECTION_DECAY' do
+      original = chrysalis.protection
+      chrysalis.decay_protection!
+      expected = (original - Legion::Extensions::Agentic::Learning::Chrysalis::Helpers::Constants::PROTECTION_DECAY).round(10)
+      expect(chrysalis.protection).to be_within(0.0001).of(expected)
+    end
+
+    it 'does not go below 0.0' do
+      30.times { chrysalis.decay_protection! }
+      expect(chrysalis.protection).to eq(0.0)
+    end
+  end
+
+  describe '#disturb!' do
+    it 'reduces protection by the given force' do
+      chrysalis.disturb!(0.2)
+      expect(chrysalis.protection).to be_within(0.0001).of(0.6)
+    end
+
+    it 'forces premature emergence when protection drops to zero for a cocooned chrysalis' do
+      chrysalis.spin!
+      chrysalis.cocoon!
+      chrysalis.disturb!(1.0)
+      expect(chrysalis.stage).to eq(:butterfly)
+    end
+
+    it 'does not force-emerge a larva when protection hits zero' do
+      chrysalis.disturb!(1.0)
+      expect(chrysalis.stage).to eq(:larva)
+    end
+  end
+
+  describe '#butterfly?' do
+    it 'returns false before emergence' do
+      expect(chrysalis.butterfly?).to be false
+    end
+
+    it 'returns true after natural emergence' do
+      chrysalis.transform!(1.0)
+      chrysalis.emerge!
+      expect(chrysalis.butterfly?).to be true
+    end
+  end
+
+  describe '#cocooned?' do
+    it 'returns false initially' do
+      expect(chrysalis.cocooned?).to be false
+    end
+
+    it 'returns true after cocooning' do
+      chrysalis.spin!
+      chrysalis.cocoon!
+      expect(chrysalis.cocooned?).to be true
+    end
+  end
+
+  describe '#transforming?' do
+    it 'returns false initially' do
+      expect(chrysalis.transforming?).to be false
+    end
+
+    it 'returns true after sufficient progress' do
+      chrysalis.transform!(0.65)
+      expect(chrysalis.transforming?).to be true
+    end
+  end
+
+  describe '#premature?' do
+    it 'returns false for a non-butterfly' do
+      expect(chrysalis.premature?).to be false
+    end
+
+    it 'returns false for a naturally emerged butterfly' do
+      chrysalis.transform!(1.0)
+      chrysalis.emerge!
+      expect(chrysalis.premature?).to be false
+    end
+
+    it 'returns true for a forcibly emerged butterfly with low beauty' do
+      chrysalis.transform!(0.05)
+      chrysalis.emerge!(force: true)
+      expect(chrysalis.premature?).to be true
+    end
+  end
+
+  describe '#stage_label' do
+    it 'returns a symbol' do
+      expect(chrysalis.stage_label).to be_a(Symbol)
+    end
+
+    it 'returns :larva for a fresh chrysalis' do
+      expect(chrysalis.stage_label).to eq(:larva)
+    end
+  end
+
+  describe '#beauty_label' do
+    it 'returns :dull for beauty 0.0' do
+      expect(chrysalis.beauty_label).to eq(:dull)
+    end
+
+    it 'returns :magnificent after natural emergence' do
+      chrysalis.transform!(1.0)
+      chrysalis.emerge!
+      expect(chrysalis.beauty_label).to eq(:magnificent)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash' do
+      expect(chrysalis.to_h).to be_a(Hash)
+    end
+
+    it 'includes id, stage, content, chrysalis_type' do
+      h = chrysalis.to_h
+      expect(h[:id]).to eq(chrysalis.id)
+      expect(h[:stage]).to eq(:larva)
+      expect(h[:content]).to eq('a new idea')
+      expect(h[:chrysalis_type]).to eq(:silk)
+    end
+
+    it 'includes transformation_progress and protection and beauty' do
+      h = chrysalis.to_h
+      expect(h).to have_key(:transformation_progress)
+      expect(h).to have_key(:protection)
+      expect(h).to have_key(:beauty)
+    end
+
+    it 'includes stage_label and beauty_label' do
+      h = chrysalis.to_h
+      expect(h).to have_key(:stage_label)
+      expect(h).to have_key(:beauty_label)
+    end
+
+    it 'includes premature and created_at' do
+      h = chrysalis.to_h
+      expect(h).to have_key(:premature)
+      expect(h).to have_key(:created_at)
+    end
+  end
+end

data/spec/legion/extensions/agentic/learning/chrysalis/helpers/cocoon_spec.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Learning::Chrysalis::Helpers::Cocoon do
+  subject(:cocoon) { described_class.new(environment: 'forest_floor') }
+
+  describe '#initialize' do
+    it 'assigns a uuid id' do
+      expect(cocoon.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets environment' do
+      expect(cocoon.environment).to eq('forest_floor')
+    end
+
+    it 'defaults temperature to 0.5' do
+      expect(cocoon.temperature).to eq(0.5)
+    end
+
+    it 'defaults humidity to 0.5' do
+      expect(cocoon.humidity).to eq(0.5)
+    end
+
+    it 'starts with empty chrysalis_ids' do
+      expect(cocoon.chrysalis_ids).to eq([])
+    end
+
+    it 'records created_at as a Time' do
+      expect(cocoon.created_at).to be_a(Time)
+    end
+
+    it 'accepts custom temperature and humidity' do
+      c = described_class.new(environment: 'sunny', temperature: 0.7, humidity: 0.3)
+      expect(c.temperature).to eq(0.7)
+      expect(c.humidity).to eq(0.3)
+    end
+  end
+
+  describe '#shelter' do
+    it 'adds a chrysalis_id to the list' do
+      cocoon.shelter('abc-123')
+      expect(cocoon.chrysalis_ids).to include('abc-123')
+    end
+
+    it 'returns true' do
+      expect(cocoon.shelter('abc-123')).to be true
+    end
+
+    it 'does not duplicate existing ids' do
+      cocoon.shelter('abc-123')
+      cocoon.shelter('abc-123')
+      expect(cocoon.chrysalis_ids.count('abc-123')).to eq(1)
+    end
+  end
+
+  describe '#expose' do
+    before { cocoon.shelter('abc-123') }
+
+    it 'removes a chrysalis_id from the list' do
+      cocoon.expose('abc-123')
+      expect(cocoon.chrysalis_ids).not_to include('abc-123')
+    end
+
+    it 'returns true' do
+      expect(cocoon.expose('abc-123')).to be true
+    end
+
+    it 'is idempotent for non-existent ids' do
+      expect { cocoon.expose('non-existent') }.not_to raise_error
+    end
+  end
+
+  describe '#warm!' do
+    it 'increases temperature by TEMP_ADJUST' do
+      before_temp = cocoon.temperature
+      cocoon.warm!
+      expect(cocoon.temperature).to be > before_temp
+    end
+
+    it 'clamps temperature at 1.0' do
+      25.times { cocoon.warm! }
+      expect(cocoon.temperature).to eq(1.0)
+    end
+  end
+
+  describe '#cool!' do
+    it 'decreases temperature by TEMP_ADJUST' do
+      before_temp = cocoon.temperature
+      cocoon.cool!
+      expect(cocoon.temperature).to be < before_temp
+    end
+
+    it 'clamps temperature at 0.0' do
+      25.times { cocoon.cool! }
+      expect(cocoon.temperature).to eq(0.0)
+    end
+  end
+
+  describe '#moisten!' do
+    it 'increases humidity by HUMID_ADJUST' do
+      before_humid = cocoon.humidity
+      cocoon.moisten!
+      expect(cocoon.humidity).to be > before_humid
+    end
+
+    it 'clamps humidity at 1.0' do
+      25.times { cocoon.moisten! }
+      expect(cocoon.humidity).to eq(1.0)
+    end
+  end
+
+  describe '#dry!' do
+    it 'decreases humidity by HUMID_ADJUST' do
+      before_humid = cocoon.humidity
+      cocoon.dry!
+      expect(cocoon.humidity).to be < before_humid
+    end
+
+    it 'clamps humidity at 0.0' do
+      25.times { cocoon.dry! }
+      expect(cocoon.humidity).to eq(0.0)
+    end
+  end
+
+  describe '#ideal?' do
+    it 'returns true when temperature and humidity are both in 0.4-0.7 range' do
+      ideal = described_class.new(environment: 'ideal', temperature: 0.55, humidity: 0.55)
+      expect(ideal.ideal?).to be true
+    end
+
+    it 'returns false when temperature is out of ideal range' do
+      c = described_class.new(environment: 'hot', temperature: 0.8, humidity: 0.5)
+      expect(c.ideal?).to be false
+    end
+
+    it 'returns false when humidity is out of ideal range' do
+      c = described_class.new(environment: 'dry', temperature: 0.5, humidity: 0.2)
+      expect(c.ideal?).to be false
+    end
+  end
+
+  describe '#hostile?' do
+    it 'returns true when temperature > 0.9' do
+      c = described_class.new(environment: 'furnace', temperature: 0.95, humidity: 0.5)
+      expect(c.hostile?).to be true
+    end
+
+    it 'returns true when humidity < 0.1' do
+      c = described_class.new(environment: 'desert', temperature: 0.5, humidity: 0.05)
+      expect(c.hostile?).to be true
+    end
+
+    it 'returns false for normal conditions' do
+      expect(cocoon.hostile?).to be false
+    end
+  end
+
+  describe '#growth_modifier' do
+    it 'returns 0.1 for ideal conditions' do
+      ideal = described_class.new(environment: 'ideal', temperature: 0.55, humidity: 0.55)
+      expect(ideal.growth_modifier).to eq(0.1)
+    end
+
+    it 'returns -0.05 for hostile conditions' do
+      hostile = described_class.new(environment: 'hostile', temperature: 0.95, humidity: 0.5)
+      expect(hostile.growth_modifier).to eq(-0.05)
+    end
+
+    it 'returns 0.0 for neutral conditions' do
+      neutral = described_class.new(environment: 'neutral', temperature: 0.2, humidity: 0.5)
+      expect(neutral.growth_modifier).to eq(0.0)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a Hash' do
+      expect(cocoon.to_h).to be_a(Hash)
+    end
+
+    it 'includes all key fields' do
+      h = cocoon.to_h
+      expect(h[:id]).to eq(cocoon.id)
+      expect(h[:environment]).to eq('forest_floor')
+      expect(h[:temperature]).to eq(0.5)
+      expect(h[:humidity]).to eq(0.5)
+      expect(h[:chrysalis_ids]).to eq([])
+    end
+
+    it 'includes ideal and hostile booleans' do
+      h = cocoon.to_h
+      expect(h).to have_key(:ideal)
+      expect(h).to have_key(:hostile)
+    end
+
+    it 'includes growth_modifier' do
+      h = cocoon.to_h
+      expect(h).to have_key(:growth_modifier)
+    end
+
+    it 'returns a dup of chrysalis_ids (not the original array)' do
+      cocoon.shelter('id-1')
+      h = cocoon.to_h
+      h[:chrysalis_ids] << 'injected'
+      expect(cocoon.chrysalis_ids).not_to include('injected')
+    end
+  end
+end

data/spec/legion/extensions/agentic/learning/chrysalis/helpers/constants_spec.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Learning::Chrysalis::Helpers::Constants do
+  subject(:constants) { described_class }
+
+  describe 'LIFE_STAGES' do
+    it 'contains the six metamorphic stages' do
+      expect(constants::LIFE_STAGES).to eq(%i[larva spinning cocooned transforming emerging butterfly])
+    end
+
+    it 'is frozen' do
+      expect(constants::LIFE_STAGES).to be_frozen
+    end
+  end
+
+  describe 'CHRYSALIS_TYPES' do
+    it 'contains the five chrysalis types' do
+      expect(constants::CHRYSALIS_TYPES).to eq(%i[silk paper bark leaf underground])
+    end
+
+    it 'is frozen' do
+      expect(constants::CHRYSALIS_TYPES).to be_frozen
+    end
+  end
+
+  describe 'numeric constants' do
+    it 'has MAX_CHRYSALISES = 200' do
+      expect(constants::MAX_CHRYSALISES).to eq(200)
+    end
+
+    it 'has MAX_BUTTERFLIES = 500' do
+      expect(constants::MAX_BUTTERFLIES).to eq(500)
+    end
+
+    it 'has TRANSFORMATION_RATE = 0.08' do
+      expect(constants::TRANSFORMATION_RATE).to eq(0.08)
+    end
+
+    it 'has PROTECTION_DECAY = 0.03' do
+      expect(constants::PROTECTION_DECAY).to eq(0.03)
+    end
+
+    it 'has EMERGENCE_THRESHOLD = 0.9' do
+      expect(constants::EMERGENCE_THRESHOLD).to eq(0.9)
+    end
+
+    it 'has PREMATURE_PENALTY = 0.4' do
+      expect(constants::PREMATURE_PENALTY).to eq(0.4)
+    end
+  end
+
+  describe 'STAGE_LABELS' do
+    it 'is a hash' do
+      expect(constants::STAGE_LABELS).to be_a(Hash)
+    end
+
+    it 'is frozen' do
+      expect(constants::STAGE_LABELS).to be_frozen
+    end
+  end
+
+  describe 'BEAUTY_LABELS' do
+    it 'is a hash' do
+      expect(constants::BEAUTY_LABELS).to be_a(Hash)
+    end
+
+    it 'is frozen' do
+      expect(constants::BEAUTY_LABELS).to be_frozen
+    end
+  end
+
+  describe '.label_for' do
+    it 'returns :larva for progress 0.0' do
+      expect(constants.label_for(constants::STAGE_LABELS, 0.0)).to eq(:larva)
+    end
+
+    it 'returns :butterfly for progress 0.95' do
+      expect(constants.label_for(constants::STAGE_LABELS, 0.95)).to eq(:butterfly)
+    end
+
+    it 'returns :transforming for progress 0.7' do
+      expect(constants.label_for(constants::STAGE_LABELS, 0.7)).to eq(:transforming)
+    end
+
+    it 'returns :dull for beauty 0.0' do
+      expect(constants.label_for(constants::BEAUTY_LABELS, 0.0)).to eq(:dull)
+    end
+
+    it 'returns :magnificent for beauty 0.95' do
+      expect(constants.label_for(constants::BEAUTY_LABELS, 0.95)).to eq(:magnificent)
+    end
+
+    it 'returns :beautiful for beauty 0.75' do
+      expect(constants.label_for(constants::BEAUTY_LABELS, 0.75)).to eq(:beautiful)
+    end
+
+    it 'returns :striking for beauty 0.5' do
+      expect(constants.label_for(constants::BEAUTY_LABELS, 0.5)).to eq(:striking)
+    end
+
+    it 'returns :plain for beauty 0.25' do
+      expect(constants.label_for(constants::BEAUTY_LABELS, 0.25)).to eq(:plain)
+    end
+
+    it 'returns the last label when value exceeds all ranges' do
+      expect(constants.label_for(constants::STAGE_LABELS, 1.1)).to eq(:butterfly)
+    end
+  end
+end

data/spec/legion/extensions/agentic/learning/chrysalis/helpers/metamorphic_cycle_spec.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+# Tests focused on Chrysalis stage progression through repeated transform! calls
+RSpec.describe 'Chrysalis stage progression' do
+  let(:chrysalis) { Legion::Extensions::Agentic::Learning::Chrysalis::Helpers::Chrysalis.new(chrysalis_type: :silk, content: 'journey') }
+  let(:rate) { Legion::Extensions::Agentic::Learning::Chrysalis::Helpers::Constants::TRANSFORMATION_RATE }
+
+  it 'progresses through larva -> spinning -> cocooned -> transforming -> emerging over time' do
+    # 0.0 = larva
+    expect(chrysalis.stage).to eq(:larva)
+
+    # Cross 0.2 = spinning
+    3.times { chrysalis.transform! }
+    expect(chrysalis.stage).to eq(:spinning)
+
+    # Cross 0.4 = cocooned
+    3.times { chrysalis.transform! }
+    expect(chrysalis.stage).to eq(:cocooned)
+
+    # Cross 0.6 = transforming
+    3.times { chrysalis.transform! }
+    expect(chrysalis.stage).to eq(:transforming)
+
+    # Cross 0.8 = emerging
+    3.times { chrysalis.transform! }
+    expect(chrysalis.stage).to eq(:emerging)
+  end
+
+  it 'can emerge after crossing the threshold' do
+    12.times { chrysalis.transform! }
+    result = chrysalis.emerge!
+    expect(result).to be true
+    expect(chrysalis.butterfly?).to be true
+  end
+
+  it 'beauty grows with each transform step' do
+    beauty_before = chrysalis.beauty
+    chrysalis.transform!
+    expect(chrysalis.beauty).to be > beauty_before
+  end
+
+  it 'stage_label matches transformation_progress' do
+    chrysalis.transform!(0.25)
+    label = Legion::Extensions::Agentic::Learning::Chrysalis::Helpers::Constants.label_for(
+      Legion::Extensions::Agentic::Learning::Chrysalis::Helpers::Constants::STAGE_LABELS,
+      chrysalis.transformation_progress
+    )
+    expect(chrysalis.stage_label).to eq(label)
+  end
+
+  it 'beauty_label matches beauty' do
+    chrysalis.transform!(0.7)
+    label = Legion::Extensions::Agentic::Learning::Chrysalis::Helpers::Constants.label_for(
+      Legion::Extensions::Agentic::Learning::Chrysalis::Helpers::Constants::BEAUTY_LABELS,
+      chrysalis.beauty
+    )
+    expect(chrysalis.beauty_label).to eq(label)
+  end
+
+  it 'multiple chrysalises have unique ids' do
+    a = Legion::Extensions::Agentic::Learning::Chrysalis::Helpers::Chrysalis.new(chrysalis_type: :bark, content: 'a')
+    b = Legion::Extensions::Agentic::Learning::Chrysalis::Helpers::Chrysalis.new(chrysalis_type: :bark, content: 'b')
+    expect(a.id).not_to eq(b.id)
+  end
+
+  it 'premature? is false after natural emergence' do
+    12.times { chrysalis.transform! }
+    chrysalis.emerge!
+    expect(chrysalis.premature?).to be false
+  end
+
+  it 'premature? is true after forced emergence from larva stage' do
+    chrysalis.emerge!(force: true)
+    expect(chrysalis.premature?).to be true
+  end
+end