lex-agentic-learning 0.1.0

data/spec/legion/extensions/agentic/learning/epistemic_curiosity/helpers/curiosity_engine_spec.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Learning::EpistemicCuriosity::Helpers::CuriosityEngine do
+  subject(:engine) { described_class.new }
+
+  let(:basic_gap_args) { { question: 'What is X?', domain: :science, gap_type: :factual } }
+
+  describe '#create_gap' do
+    it 'creates a gap and returns created: true' do
+      result = engine.create_gap(**basic_gap_args)
+      expect(result[:created]).to be true
+    end
+
+    it 'returns the gap hash' do
+      result = engine.create_gap(**basic_gap_args)
+      expect(result[:gap]).to be_a(Hash)
+      expect(result[:gap][:question]).to eq('What is X?')
+    end
+
+    it 'assigns incremental ids' do
+      r1 = engine.create_gap(**basic_gap_args)
+      r2 = engine.create_gap(**basic_gap_args)
+      expect(r1[:gap][:id]).not_to eq(r2[:gap][:id])
+    end
+
+    it 'defaults gap_type to :factual for unknown type' do
+      result = engine.create_gap(question: 'q', domain: :d, gap_type: :unknown_type)
+      expect(result[:gap][:gap_type]).to eq(:factual)
+    end
+
+    it 'accepts custom urgency' do
+      result = engine.create_gap(**basic_gap_args, urgency: 0.9)
+      expect(result[:gap][:urgency]).to eq(0.9)
+    end
+  end
+
+  describe '#explore_gap' do
+    it 'returns found: false for unknown gap' do
+      result = engine.explore_gap(gap_id: :nonexistent)
+      expect(result[:found]).to be false
+    end
+
+    it 'increments explorations' do
+      id = engine.create_gap(**basic_gap_args)[:gap][:id]
+      result = engine.explore_gap(gap_id: id)
+      expect(result[:gap][:explorations]).to eq(1)
+    end
+
+    it 'boosts urgency' do
+      id    = engine.create_gap(**basic_gap_args, urgency: 0.5)[:gap][:id]
+      after = engine.explore_gap(gap_id: id)[:gap][:urgency]
+      expect(after).to be > 0.5
+    end
+  end
+
+  describe '#satisfy_gap' do
+    it 'returns found: false for unknown gap' do
+      expect(engine.satisfy_gap(gap_id: :nope)[:found]).to be false
+    end
+
+    it 'increases satisfaction' do
+      id = engine.create_gap(**basic_gap_args)[:gap][:id]
+      engine.satisfy_gap(gap_id: id, amount: 0.4)
+      result = engine.satisfy_gap(gap_id: id, amount: 0.4)
+      expect(result[:gap][:satisfaction]).to be > 0.4
+    end
+  end
+
+  describe '#resolve_gap' do
+    it 'returns found: false for unknown gap' do
+      expect(engine.resolve_gap(gap_id: :nope)[:found]).to be false
+    end
+
+    it 'sets satisfaction to 1.0' do
+      id = engine.create_gap(**basic_gap_args)[:gap][:id]
+      engine.resolve_gap(gap_id: id)
+      gap = engine.resolved_gaps.first
+      expect(gap.satisfaction).to eq(1.0)
+    end
+
+    it 'moves gap to resolved_gaps' do
+      id = engine.create_gap(**basic_gap_args)[:gap][:id]
+      engine.resolve_gap(gap_id: id)
+      expect(engine.resolved_gaps.size).to eq(1)
+    end
+  end
+
+  describe '#open_gaps / #resolved_gaps' do
+    before do
+      engine.create_gap(**basic_gap_args)
+      id2 = engine.create_gap(**basic_gap_args)[:gap][:id]
+      engine.resolve_gap(gap_id: id2)
+    end
+
+    it 'open_gaps returns unresolved gaps' do
+      expect(engine.open_gaps.size).to eq(1)
+    end
+
+    it 'resolved_gaps returns resolved gaps' do
+      expect(engine.resolved_gaps.size).to eq(1)
+    end
+  end
+
+  describe '#most_urgent' do
+    it 'returns gaps sorted by urgency descending' do
+      engine.create_gap(**basic_gap_args, urgency: 0.3)
+      engine.create_gap(**basic_gap_args, urgency: 0.9)
+      engine.create_gap(**basic_gap_args, urgency: 0.6)
+      urgent = engine.most_urgent(limit: 2)
+      expect(urgent.first.urgency).to be >= urgent.last.urgency
+    end
+
+    it 'respects the limit' do
+      5.times { engine.create_gap(**basic_gap_args) }
+      expect(engine.most_urgent(limit: 2).size).to eq(2)
+    end
+  end
+
+  describe '#by_domain' do
+    it 'filters by domain' do
+      engine.create_gap(question: 'q1', domain: :science, gap_type: :factual)
+      engine.create_gap(question: 'q2', domain: :history, gap_type: :factual)
+      expect(engine.by_domain(:science).size).to eq(1)
+    end
+  end
+
+  describe '#by_type' do
+    it 'filters by gap_type' do
+      engine.create_gap(question: 'q1', domain: :d, gap_type: :causal)
+      engine.create_gap(question: 'q2', domain: :d, gap_type: :factual)
+      expect(engine.by_type(:causal).size).to eq(1)
+    end
+  end
+
+  describe '#information_debt' do
+    it 'sums urgency of open gaps' do
+      engine.create_gap(**basic_gap_args, urgency: 0.4)
+      engine.create_gap(**basic_gap_args, urgency: 0.6)
+      expect(engine.information_debt).to be_within(0.01).of(1.0)
+    end
+
+    it 'excludes resolved gaps' do
+      id = engine.create_gap(**basic_gap_args, urgency: 0.8)[:gap][:id]
+      engine.resolve_gap(gap_id: id)
+      expect(engine.information_debt).to eq(0.0)
+    end
+  end
+
+  describe '#exploration_efficiency' do
+    it 'returns 0.0 with no gaps' do
+      expect(engine.exploration_efficiency).to eq(0.0)
+    end
+
+    it 'returns 1.0 when all gaps resolved' do
+      id = engine.create_gap(**basic_gap_args)[:gap][:id]
+      engine.resolve_gap(gap_id: id)
+      expect(engine.exploration_efficiency).to eq(1.0)
+    end
+
+    it 'returns 0.5 when half resolved' do
+      engine.create_gap(**basic_gap_args)
+      id2 = engine.create_gap(**basic_gap_args)[:gap][:id]
+      engine.resolve_gap(gap_id: id2)
+      expect(engine.exploration_efficiency).to be_within(0.01).of(0.5)
+    end
+  end
+
+  describe '#decay_all' do
+    it 'returns the number of gaps affected' do
+      2.times { engine.create_gap(**basic_gap_args) }
+      expect(engine.decay_all).to eq(2)
+    end
+
+    it 'reduces urgency of open gaps' do
+      id     = engine.create_gap(**basic_gap_args, urgency: 0.5)[:gap][:id]
+      before = engine.open_gaps.find { |g| g.id == id }.urgency
+      engine.decay_all
+      after = engine.open_gaps.find { |g| g.id == id }.urgency
+      expect(after).to be < before
+    end
+  end
+
+  describe '#prune_resolved' do
+    it 'removes resolved gaps' do
+      id = engine.create_gap(**basic_gap_args)[:gap][:id]
+      engine.resolve_gap(gap_id: id)
+      engine.prune_resolved
+      expect(engine.resolved_gaps.size).to eq(0)
+    end
+
+    it 'keeps open gaps' do
+      engine.create_gap(**basic_gap_args)
+      id2 = engine.create_gap(**basic_gap_args)[:gap][:id]
+      engine.resolve_gap(gap_id: id2)
+      engine.prune_resolved
+      expect(engine.open_gaps.size).to eq(1)
+    end
+  end
+
+  describe '#curiosity_report' do
+    it 'returns expected keys' do
+      report = engine.curiosity_report
+      expect(report.keys).to include(:total_gaps, :open_gaps, :resolved_gaps, :information_debt, :exploration_efficiency, :most_urgent)
+    end
+
+    it 'most_urgent is an array of hashes' do
+      engine.create_gap(**basic_gap_args)
+      expect(engine.curiosity_report[:most_urgent]).to be_an(Array)
+      expect(engine.curiosity_report[:most_urgent].first).to be_a(Hash)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with gaps key' do
+      engine.create_gap(**basic_gap_args)
+      result = engine.to_h
+      expect(result).to have_key(:gaps)
+      expect(result[:gaps]).to be_a(Hash)
+    end
+
+    it 'includes information_debt' do
+      expect(engine.to_h).to have_key(:information_debt)
+    end
+
+    it 'includes exploration_efficiency' do
+      expect(engine.to_h).to have_key(:exploration_efficiency)
+    end
+  end
+end

data/spec/legion/extensions/agentic/learning/epistemic_curiosity/helpers/knowledge_gap_spec.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Learning::EpistemicCuriosity::Helpers::KnowledgeGap do
+  subject(:gap) do
+    described_class.new(
+      id:       :gap_1, # rubocop:disable Naming/VariableNumber
+      question: 'Why does the cache miss?',
+      domain:   :infrastructure,
+      gap_type: :causal,
+      urgency:  0.5
+    )
+  end
+
+  describe '#initialize' do
+    it 'sets id' do
+      expect(gap.id).to eq(:gap_1) # rubocop:disable Naming/VariableNumber
+    end
+
+    it 'sets question' do
+      expect(gap.question).to eq('Why does the cache miss?')
+    end
+
+    it 'sets domain' do
+      expect(gap.domain).to eq(:infrastructure)
+    end
+
+    it 'sets gap_type' do
+      expect(gap.gap_type).to eq(:causal)
+    end
+
+    it 'sets urgency' do
+      expect(gap.urgency).to eq(0.5)
+    end
+
+    it 'starts satisfaction at 0.0' do
+      expect(gap.satisfaction).to eq(0.0)
+    end
+
+    it 'starts explorations at 0' do
+      expect(gap.explorations).to eq(0)
+    end
+
+    it 'sets created_at' do
+      expect(gap.created_at).to be_a(Time)
+    end
+
+    it 'resolved_at is nil initially' do
+      expect(gap.resolved_at).to be_nil
+    end
+
+    it 'clamps urgency above 1.0' do
+      g = described_class.new(id: :x, question: 'q', domain: :d, gap_type: :factual, urgency: 2.0)
+      expect(g.urgency).to eq(1.0)
+    end
+
+    it 'clamps urgency below 0.0' do
+      g = described_class.new(id: :x, question: 'q', domain: :d, gap_type: :factual, urgency: -1.0)
+      expect(g.urgency).to eq(0.0)
+    end
+  end
+
+  describe '#explore!' do
+    it 'increments explorations' do
+      gap.explore!
+      expect(gap.explorations).to eq(1)
+    end
+
+    it 'boosts urgency by URGENCY_BOOST' do
+      before = gap.urgency
+      gap.explore!
+      expect(gap.urgency).to be_within(0.001).of(before + Legion::Extensions::Agentic::Learning::EpistemicCuriosity::Helpers::Constants::URGENCY_BOOST)
+    end
+
+    it 'returns self' do
+      expect(gap.explore!).to eq(gap)
+    end
+
+    it 'does not exceed 1.0 on urgency' do
+      g = described_class.new(id: :x, question: 'q', domain: :d, gap_type: :factual, urgency: 0.99)
+      g.explore!
+      expect(g.urgency).to be <= 1.0
+    end
+  end
+
+  describe '#satisfy!' do
+    it 'increases satisfaction' do
+      gap.satisfy!(amount: 0.3)
+      expect(gap.satisfaction).to be_within(0.001).of(0.3)
+    end
+
+    it 'returns self' do
+      expect(gap.satisfy!).to eq(gap)
+    end
+
+    it 'clamps satisfaction at 1.0' do
+      gap.satisfy!(amount: 0.6)
+      gap.satisfy!(amount: 0.6)
+      expect(gap.satisfaction).to eq(1.0)
+    end
+
+    it 'uses default amount 0.3' do
+      gap.satisfy!
+      expect(gap.satisfaction).to be_within(0.001).of(0.3)
+    end
+  end
+
+  describe '#resolved?' do
+    it 'returns false when satisfaction is low' do
+      expect(gap.resolved?).to be false
+    end
+
+    it 'returns true when satisfaction >= SATISFACTION_THRESHOLD' do
+      gap.satisfy!(amount: 1.0)
+      expect(gap.resolved?).to be true
+    end
+
+    it 'returns true at exactly SATISFACTION_THRESHOLD' do
+      gap.satisfaction = Legion::Extensions::Agentic::Learning::EpistemicCuriosity::Helpers::Constants::SATISFACTION_THRESHOLD
+      expect(gap.resolved?).to be true
+    end
+  end
+
+  describe '#urgency_label' do
+    it 'returns :burning for urgency 0.9' do
+      gap.urgency = 0.9
+      expect(gap.urgency_label).to eq(:burning)
+    end
+
+    it 'returns :intense for urgency 0.7' do
+      gap.urgency = 0.7
+      expect(gap.urgency_label).to eq(:intense)
+    end
+
+    it 'returns :moderate for urgency 0.5' do
+      gap.urgency = 0.5
+      expect(gap.urgency_label).to eq(:moderate)
+    end
+
+    it 'returns :mild for urgency 0.3' do
+      gap.urgency = 0.3
+      expect(gap.urgency_label).to eq(:mild)
+    end
+
+    it 'returns :satisfied for urgency 0.1' do
+      gap.urgency = 0.1
+      expect(gap.urgency_label).to eq(:satisfied)
+    end
+  end
+
+  describe '#decay!' do
+    it 'decreases urgency by URGENCY_DECAY' do
+      before = gap.urgency
+      gap.decay!
+      expect(gap.urgency).to be_within(0.001).of(before - Legion::Extensions::Agentic::Learning::EpistemicCuriosity::Helpers::Constants::URGENCY_DECAY)
+    end
+
+    it 'returns self' do
+      expect(gap.decay!).to eq(gap)
+    end
+
+    it 'does not go below 0.0' do
+      g = described_class.new(id: :x, question: 'q', domain: :d, gap_type: :factual, urgency: 0.01)
+      g.decay!
+      expect(g.urgency).to eq(0.0)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash' do
+      expect(gap.to_h).to be_a(Hash)
+    end
+
+    it 'includes all expected keys' do
+      h = gap.to_h
+      expect(h.keys).to include(:id, :question, :domain, :gap_type, :urgency, :urgency_label, :satisfaction, :explorations, :resolved, :created_at,
+                                :resolved_at)
+    end
+
+    it 'rounds urgency to 4 decimal places' do
+      gap.urgency = 0.123456789
+      expect(gap.to_h[:urgency]).to eq(0.1235)
+    end
+
+    it 'includes resolved status' do
+      expect(gap.to_h[:resolved]).to be false
+    end
+  end
+end

data/spec/legion/extensions/agentic/learning/epistemic_curiosity/runners/epistemic_curiosity_spec.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/learning/epistemic_curiosity/client'
+
+RSpec.describe Legion::Extensions::Agentic::Learning::EpistemicCuriosity::Runners::EpistemicCuriosity do
+  let(:client) { Legion::Extensions::Agentic::Learning::EpistemicCuriosity::Client.new }
+
+  let(:gap_args) { { question: 'What causes latency spikes?', domain: :infrastructure, gap_type: :causal } }
+
+  describe '#create_gap' do
+    it 'creates a gap with created: true' do
+      result = client.create_gap(**gap_args)
+      expect(result[:created]).to be true
+    end
+
+    it 'returns gap data with question' do
+      result = client.create_gap(**gap_args)
+      expect(result[:gap][:question]).to eq('What causes latency spikes?')
+    end
+
+    it 'uses default urgency when not specified' do
+      result = client.create_gap(**gap_args)
+      expect(result[:gap][:urgency]).to eq(Legion::Extensions::Agentic::Learning::EpistemicCuriosity::Helpers::Constants::DEFAULT_URGENCY)
+    end
+
+    it 'accepts custom urgency' do
+      result = client.create_gap(**gap_args, urgency: 0.9)
+      expect(result[:gap][:urgency]).to eq(0.9)
+    end
+  end
+
+  describe '#explore_gap' do
+    it 'returns found: false for unknown gap_id' do
+      result = client.explore_gap(gap_id: :nonexistent)
+      expect(result[:found]).to be false
+    end
+
+    it 'increments explorations for known gap' do
+      id = client.create_gap(**gap_args)[:gap][:id]
+      result = client.explore_gap(gap_id: id)
+      expect(result[:gap][:explorations]).to eq(1)
+    end
+
+    it 'boosts urgency on explore' do
+      id     = client.create_gap(**gap_args, urgency: 0.4)[:gap][:id]
+      result = client.explore_gap(gap_id: id)
+      expect(result[:gap][:urgency]).to be > 0.4
+    end
+  end
+
+  describe '#satisfy_gap' do
+    it 'returns found: false for unknown gap_id' do
+      result = client.satisfy_gap(gap_id: :ghost)
+      expect(result[:found]).to be false
+    end
+
+    it 'increases satisfaction' do
+      id = client.create_gap(**gap_args)[:gap][:id]
+      result = client.satisfy_gap(gap_id: id, amount: 0.5)
+      expect(result[:gap][:satisfaction]).to be_within(0.001).of(0.5)
+    end
+
+    it 'shows resolved: true when satisfaction crosses threshold' do
+      id = client.create_gap(**gap_args)[:gap][:id]
+      result = client.satisfy_gap(gap_id: id, amount: 1.0)
+      expect(result[:gap][:resolved]).to be true
+    end
+  end
+
+  describe '#resolve_gap' do
+    it 'returns found: false for unknown gap_id' do
+      result = client.resolve_gap(gap_id: :ghost)
+      expect(result[:found]).to be false
+    end
+
+    it 'marks gap as resolved' do
+      id     = client.create_gap(**gap_args)[:gap][:id]
+      result = client.resolve_gap(gap_id: id)
+      expect(result[:resolved]).to be true
+    end
+
+    it 'sets satisfaction to 1.0' do
+      id = client.create_gap(**gap_args)[:gap][:id]
+      client.resolve_gap(gap_id: id)
+      expect(client.curiosity_status[:resolved_gaps]).to eq(1)
+    end
+  end
+
+  describe '#most_urgent_gaps' do
+    it 'returns gaps and count' do
+      client.create_gap(**gap_args, urgency: 0.9)
+      result = client.most_urgent_gaps(limit: 5)
+      expect(result).to have_key(:gaps)
+      expect(result).to have_key(:count)
+    end
+
+    it 'respects limit' do
+      3.times { client.create_gap(**gap_args) }
+      result = client.most_urgent_gaps(limit: 2)
+      expect(result[:count]).to eq(2)
+    end
+
+    it 'returns sorted by urgency descending' do
+      client.create_gap(**gap_args, urgency: 0.2)
+      client.create_gap(**gap_args, urgency: 0.8)
+      gaps = client.most_urgent_gaps[:gaps]
+      expect(gaps.first[:urgency]).to be >= gaps.last[:urgency]
+    end
+  end
+
+  describe '#gaps_by_domain' do
+    it 'returns gaps matching domain' do
+      client.create_gap(question: 'q1', domain: :infra, gap_type: :factual)
+      client.create_gap(question: 'q2', domain: :finance, gap_type: :factual)
+      result = client.gaps_by_domain(domain: :infra)
+      expect(result[:count]).to eq(1)
+      expect(result[:domain]).to eq(:infra)
+    end
+  end
+
+  describe '#gaps_by_type' do
+    it 'returns gaps matching type' do
+      client.create_gap(question: 'q1', domain: :d, gap_type: :causal)
+      client.create_gap(question: 'q2', domain: :d, gap_type: :relational)
+      result = client.gaps_by_type(gap_type: :causal)
+      expect(result[:count]).to eq(1)
+      expect(result[:gap_type]).to eq(:causal)
+    end
+  end
+
+  describe '#decay_gaps' do
+    it 'returns count of decayed gaps' do
+      client.create_gap(**gap_args)
+      result = client.decay_gaps
+      expect(result[:decayed]).to eq(1)
+    end
+
+    it 'reduces urgency of gaps' do
+      id     = client.create_gap(**gap_args, urgency: 0.5)[:gap][:id]
+      before = client.most_urgent_gaps[:gaps].find { |g| g[:id] == id }[:urgency]
+      client.decay_gaps
+      after = client.most_urgent_gaps[:gaps].find { |g| g[:id] == id }[:urgency]
+      expect(after).to be < before
+    end
+  end
+
+  describe '#curiosity_report' do
+    it 'returns a report hash with expected keys' do
+      result = client.curiosity_report
+      expect(result.keys).to include(:total_gaps, :open_gaps, :resolved_gaps, :information_debt, :exploration_efficiency, :most_urgent)
+    end
+
+    it 'reflects current state' do
+      client.create_gap(**gap_args)
+      expect(client.curiosity_report[:open_gaps]).to eq(1)
+    end
+  end
+
+  describe '#curiosity_status' do
+    it 'returns status hash' do
+      result = client.curiosity_status
+      expect(result.keys).to include(:total_gaps, :open_gaps, :resolved_gaps, :information_debt, :exploration_efficiency)
+    end
+
+    it 'total_gaps reflects all gaps' do
+      2.times { client.create_gap(**gap_args) }
+      expect(client.curiosity_status[:total_gaps]).to eq(2)
+    end
+
+    it 'information_debt is non-negative' do
+      client.create_gap(**gap_args, urgency: 0.7)
+      expect(client.curiosity_status[:information_debt]).to be >= 0.0
+    end
+  end
+end

data/spec/legion/extensions/agentic/learning/fermentation/client_spec.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Learning::Fermentation::Client do
+  subject(:client) { described_class.new }
+
+  it 'responds to runner methods' do
+    expect(client).to respond_to(:create_substrate, :ferment, :catalyze, :fermentation_status)
+  end
+
+  it 'runs a full fermentation lifecycle' do
+    result = client.create_substrate(substrate_type: :raw_idea, domain: :cognitive, content: 'test')
+    sub_id = result[:substrate][:id]
+
+    client.catalyze(substrate_id: sub_id, catalyst_type: :analogy)
+    10.times { client.ferment(substrate_id: sub_id) }
+
+    status = client.fermentation_status
+    expect(status[:total_substrates]).to eq(1)
+    expect(status[:success]).to be true
+  end
+
+  it 'lists ripe substrates' do
+    result = client.create_substrate(substrate_type: :raw_idea, domain: :cognitive, potency: 0.8)
+    sub_id = result[:substrate][:id]
+    15.times { client.ferment(substrate_id: sub_id, rate: 0.05) }
+    ripe = client.list_ripe
+    expect(ripe[:success]).to be true
+  end
+
+  it 'ferments all substrates' do
+    client.create_substrate(substrate_type: :raw_idea, domain: :cognitive)
+    client.create_substrate(substrate_type: :raw_idea, domain: :emotional)
+    result = client.ferment_all
+    expect(result[:success]).to be true
+  end
+end

data/spec/legion/extensions/agentic/learning/fermentation/helpers/batch_spec.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Learning::Fermentation::Helpers::Batch do
+  subject(:batch) { described_class.new(domain: :cognitive) }
+
+  let(:substrate_class) { Legion::Extensions::Agentic::Learning::Fermentation::Helpers::Substrate }
+
+  describe '#initialize' do
+    it 'assigns a uuid id' do
+      expect(batch.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores domain' do
+      expect(batch.domain).to eq(:cognitive)
+    end
+
+    it 'starts with empty substrates' do
+      expect(batch.substrates).to be_empty
+    end
+  end
+
+  describe '#add_substrate' do
+    it 'adds substrate to batch' do
+      sub = substrate_class.new(substrate_type: :raw_idea, domain: :cognitive)
+      batch.add_substrate(sub)
+      expect(batch.substrates.size).to eq(1)
+    end
+  end
+
+  describe '#ferment_all!' do
+    it 'ferments all substrates' do
+      sub = substrate_class.new(substrate_type: :raw_idea, domain: :cognitive)
+      batch.add_substrate(sub)
+      batch.ferment_all!
+      expect(sub.maturity).to be > 0.0
+    end
+  end
+
+  describe '#average_potency' do
+    it 'returns 0.0 for empty batch' do
+      expect(batch.average_potency).to eq(0.0)
+    end
+
+    it 'computes average' do
+      s1 = substrate_class.new(substrate_type: :raw_idea, domain: :cognitive, potency: 0.6)
+      s2 = substrate_class.new(substrate_type: :raw_idea, domain: :cognitive, potency: 0.4)
+      batch.add_substrate(s1)
+      batch.add_substrate(s2)
+      expect(batch.average_potency).to eq(0.5)
+    end
+  end
+
+  describe '#yield_rate' do
+    it 'returns 0.0 for empty batch' do
+      expect(batch.yield_rate).to eq(0.0)
+    end
+  end
+
+  describe '#ready_to_harvest?' do
+    it 'returns false when no ripe substrates' do
+      expect(batch).not_to be_ready_to_harvest
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns hash with batch stats' do
+      h = batch.to_h
+      expect(h).to include(:id, :domain, :substrate_count, :average_potency,
+                           :average_maturity, :ripe_count, :yield_rate)
+    end
+  end
+end