lex-agentic-inference 0.1.0

data/spec/legion/extensions/agentic/inference/debugging/runners/cognitive_debugging_spec.rb

@@ -0,0 +1,301 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/inference/debugging/client'
+
+RSpec.describe Legion::Extensions::Agentic::Inference::Debugging::Runners::CognitiveDebugging do
+  subject(:client) { Legion::Extensions::Agentic::Inference::Debugging::Client.new }
+
+  let(:base_error_kwargs) do
+    {
+      error_type:              :inconsistency,
+      description:             'Claim X contradicts Claim Y',
+      severity:                0.6,
+      source_phase:            :prediction_engine,
+      confidence_at_detection: 0.85
+    }
+  end
+
+  def detect_one(overrides = {})
+    client.detect_error(**base_error_kwargs, **overrides)
+  end
+
+  describe '#detect_error' do
+    it 'returns success: true with an error_id' do
+      result = detect_one
+      expect(result[:success]).to be true
+      expect(result[:error_id]).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'returns the error_type' do
+      result = detect_one
+      expect(result[:error_type]).to eq(:inconsistency)
+    end
+
+    it 'includes severity_label' do
+      result = detect_one
+      expect(result[:severity_label]).to be_a(Symbol)
+    end
+
+    it 'returns success: false for invalid error_type' do
+      result = client.detect_error(**base_error_kwargs, error_type: :not_real)
+      expect(result[:success]).to be false
+      expect(result[:error]).to eq(:invalid_error_type)
+    end
+
+    it 'returns valid error types on failure' do
+      result = client.detect_error(**base_error_kwargs, error_type: :bogus)
+      expect(result[:valid]).to include(:inconsistency)
+    end
+
+    it 'uses default confidence_at_detection of 0.5 when omitted' do
+      result = client.detect_error(error_type: :overconfidence, description: 'x',
+                                   severity: 0.5, source_phase: :tick)
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#trace_error' do
+    let(:error_id) { detect_one[:error_id] }
+    let(:steps) do
+      [
+        { phase: :emotional_evaluation, description: 'Urgency spike' },
+        { phase: :prediction_engine,    description: 'Premature conclusion' }
+      ]
+    end
+
+    it 'returns success: true with trace_id and depth' do
+      result = client.trace_error(error_id: error_id, steps: steps, root_cause: :bad_prior, confidence: 0.7)
+      expect(result[:success]).to be true
+      expect(result[:trace_id]).to match(/\A[0-9a-f-]{36}\z/)
+      expect(result[:depth]).to eq(2)
+    end
+
+    it 'returns root_cause in response' do
+      result = client.trace_error(error_id: error_id, steps: steps, root_cause: :bad_prior, confidence: 0.7)
+      expect(result[:root_cause]).to eq(:bad_prior)
+    end
+
+    it 'returns success: false for unknown error_id' do
+      result = client.trace_error(error_id: 'nope', steps: steps, root_cause: :x, confidence: 0.5)
+      expect(result[:success]).to be false
+      expect(result[:error]).to eq(:not_found_or_cap)
+    end
+
+    it 'uses default confidence of 0.5 when omitted' do
+      result = client.trace_error(error_id: error_id, steps: steps, root_cause: :x)
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#propose_correction' do
+    let(:error_id) { detect_one[:error_id] }
+
+    it 'returns success: true with correction_id and strategy' do
+      result = client.propose_correction(error_id: error_id, strategy: :retrace,
+                                         description: 'Re-examine from start')
+      expect(result[:success]).to be true
+      expect(result[:correction_id]).to match(/\A[0-9a-f-]{36}\z/)
+      expect(result[:strategy]).to eq(:retrace)
+    end
+
+    it 'returns success: false for invalid strategy' do
+      result = client.propose_correction(error_id: error_id, strategy: :invalid_strat, description: 'x')
+      expect(result[:success]).to be false
+      expect(result[:error]).to eq(:invalid_strategy)
+    end
+
+    it 'returns valid strategies on failure' do
+      result = client.propose_correction(error_id: error_id, strategy: :bad, description: 'x')
+      expect(result[:valid]).to include(:retrace, :devil_advocate)
+    end
+
+    it 'returns success: false for unknown error_id' do
+      result = client.propose_correction(error_id: 'nope', strategy: :retrace, description: 'x')
+      expect(result[:success]).to be false
+      expect(result[:error]).to eq(:not_found)
+    end
+  end
+
+  describe '#apply_correction' do
+    let(:correction_id) do
+      error_id = detect_one[:error_id]
+      client.propose_correction(error_id: error_id, strategy: :retrace, description: 'x')[:correction_id]
+    end
+
+    it 'returns success: true and applied: true' do
+      result = client.apply_correction(correction_id: correction_id)
+      expect(result[:success]).to be true
+      expect(result[:applied]).to be true
+    end
+
+    it 'returns success: false for unknown correction_id' do
+      result = client.apply_correction(correction_id: 'nope')
+      expect(result[:success]).to be false
+      expect(result[:error]).to eq(:not_found)
+    end
+  end
+
+  describe '#measure_correction' do
+    let(:correction_id) do
+      error_id = detect_one[:error_id]
+      client.propose_correction(error_id: error_id, strategy: :reframe, description: 'x')[:correction_id]
+    end
+
+    it 'returns effectiveness and effective flag' do
+      result = client.measure_correction(correction_id: correction_id, effectiveness: 0.8)
+      expect(result[:success]).to be true
+      expect(result[:effectiveness]).to eq(0.8)
+      expect(result[:effective]).to be true
+    end
+
+    it 'returns effective: false for low score' do
+      result = client.measure_correction(correction_id: correction_id, effectiveness: 0.4)
+      expect(result[:effective]).to be false
+    end
+
+    it 'returns success: false for unknown correction_id' do
+      result = client.measure_correction(correction_id: 'nope', effectiveness: 0.5)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#resolve_error' do
+    let(:error_id) { detect_one[:error_id] }
+
+    it 'returns success: true and resolved: true' do
+      result = client.resolve_error(error_id: error_id)
+      expect(result[:success]).to be true
+      expect(result[:resolved]).to be true
+    end
+
+    it 'returns success: false for unknown error_id' do
+      result = client.resolve_error(error_id: 'nope')
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#active_errors' do
+    it 'returns a list of active errors' do
+      detect_one
+      result = client.active_errors
+      expect(result[:success]).to be true
+      expect(result[:count]).to be >= 1
+      expect(result[:errors]).to be_an(Array)
+    end
+
+    it 'does not include resolved errors' do
+      eid = detect_one[:error_id]
+      client.resolve_error(error_id: eid)
+      result = client.active_errors
+      ids = result[:errors].map { |e| e[:id] }
+      expect(ids).not_to include(eid)
+    end
+  end
+
+  describe '#resolved_errors' do
+    it 'returns empty list when nothing resolved' do
+      result = client.resolved_errors
+      expect(result[:success]).to be true
+      expect(result[:count]).to eq(0)
+    end
+
+    it 'includes resolved errors' do
+      eid = detect_one[:error_id]
+      client.resolve_error(error_id: eid)
+      result = client.resolved_errors
+      ids = result[:errors].map { |e| e[:id] }
+      expect(ids).to include(eid)
+    end
+  end
+
+  describe '#errors_by_type' do
+    it 'returns a tally hash' do
+      detect_one(error_type: :overconfidence)
+      detect_one(error_type: :overconfidence)
+      result = client.errors_by_type
+      expect(result[:success]).to be true
+      expect(result[:tally][:overconfidence]).to eq(2)
+    end
+  end
+
+  describe '#errors_by_phase' do
+    it 'returns a tally by source_phase' do
+      detect_one(source_phase: :emotional_evaluation)
+      result = client.errors_by_phase
+      expect(result[:success]).to be true
+      expect(result[:tally][:emotional_evaluation]).to be >= 1
+    end
+  end
+
+  describe '#most_common_error_type' do
+    it 'returns nil when no errors' do
+      result = client.most_common_error_type
+      expect(result[:success]).to be true
+      expect(result[:error_type]).to be_nil
+    end
+
+    it 'returns the most frequent type' do
+      detect_one(error_type: :circular_logic)
+      detect_one(error_type: :circular_logic)
+      detect_one(error_type: :missing_evidence)
+      result = client.most_common_error_type
+      expect(result[:error_type]).to eq(:circular_logic)
+    end
+  end
+
+  describe '#most_effective_strategy' do
+    it 'returns nil when no measured corrections' do
+      result = client.most_effective_strategy
+      expect(result[:success]).to be true
+      expect(result[:strategy]).to be_nil
+    end
+
+    it 'returns the best-performing strategy' do
+      eid = detect_one[:error_id]
+      c1 = client.propose_correction(error_id: eid, strategy: :retrace, description: 'x')
+      c2 = client.propose_correction(error_id: eid, strategy: :seek_evidence, description: 'y')
+      client.measure_correction(correction_id: c1[:correction_id], effectiveness: 0.3)
+      client.measure_correction(correction_id: c2[:correction_id], effectiveness: 0.95)
+      result = client.most_effective_strategy
+      expect(result[:strategy]).to eq(:seek_evidence)
+    end
+  end
+
+  describe '#correction_success_rate' do
+    it 'returns 0.0 when no corrections' do
+      result = client.correction_success_rate
+      expect(result[:success]).to be true
+      expect(result[:rate]).to eq(0.0)
+    end
+
+    it 'calculates correct rate after measuring' do
+      eid = detect_one[:error_id]
+      c1 = client.propose_correction(error_id: eid, strategy: :retrace, description: 'a')
+      c2 = client.propose_correction(error_id: eid, strategy: :reframe, description: 'b')
+      client.apply_correction(correction_id: c1[:correction_id])
+      client.apply_correction(correction_id: c2[:correction_id])
+      client.measure_correction(correction_id: c1[:correction_id], effectiveness: 0.9)
+      client.measure_correction(correction_id: c2[:correction_id], effectiveness: 0.9)
+      result = client.correction_success_rate
+      expect(result[:rate]).to eq(1.0)
+    end
+  end
+
+  describe '#debugging_report' do
+    it 'returns success: true with a complete report' do
+      detect_one
+      result = client.debugging_report
+      expect(result[:success]).to be true
+      expect(result[:report]).to include(:total_errors, :active_errors, :correction_success_rate)
+    end
+  end
+
+  describe '#snapshot' do
+    it 'returns success: true with snapshot data' do
+      detect_one
+      result = client.snapshot
+      expect(result[:success]).to be true
+      expect(result[:snapshot]).to include(:errors, :traces, :corrections)
+    end
+  end
+end

data/spec/legion/extensions/agentic/inference/enactive_cognition/client_spec.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/inference/enactive_cognition/client'
+
+RSpec.describe Legion::Extensions::Agentic::Inference::EnactiveCognition::Client do
+  it 'responds to all runner methods' do
+    client = described_class.new
+    expect(client).to respond_to(:create_sensorimotor_coupling)
+    expect(client).to respond_to(:execute_enactive_action)
+    expect(client).to respond_to(:adapt_sensorimotor_coupling)
+    expect(client).to respond_to(:find_action_for_perception)
+    expect(client).to respond_to(:coupled_sensorimotor_loops)
+    expect(client).to respond_to(:domain_couplings)
+    expect(client).to respond_to(:strongest_couplings)
+    expect(client).to respond_to(:overall_enactive_coupling)
+    expect(client).to respond_to(:update_enactive_cognition)
+    expect(client).to respond_to(:enactive_cognition_stats)
+  end
+end

data/spec/legion/extensions/agentic/inference/enactive_cognition/helpers/enaction_engine_spec.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/inference/enactive_cognition/helpers/sensorimotor_loop'
+require 'legion/extensions/agentic/inference/enactive_cognition/helpers/enaction_engine'
+
+RSpec.describe Legion::Extensions::Agentic::Inference::EnactiveCognition::Helpers::EnactionEngine do
+  subject(:engine) { described_class.new }
+
+  let(:coupling) do
+    engine.create_coupling(action: 'grasp', perception: 'grip', domain: 'motor')
+  end
+
+  describe '#create_coupling' do
+    it 'returns a SensorimotorLoop instance' do
+      expect(coupling).to be_a(Legion::Extensions::Agentic::Inference::EnactiveCognition::Helpers::SensorimotorLoop)
+    end
+
+    it 'stores the coupling by id' do
+      expect(engine.couplings[coupling.id]).to eq(coupling)
+    end
+
+    it 'increments coupling count' do
+      engine.create_coupling(action: 'push', perception: 'moved', domain: 'motor')
+      expect(engine.count).to eq(1)
+    end
+
+    it 'defaults loop_type to :sensorimotor' do
+      expect(coupling.loop_type).to eq(:sensorimotor)
+    end
+
+    it 'accepts explicit loop_type' do
+      lp = engine.create_coupling(action: 'think', perception: 'clarity', domain: 'cog', loop_type: :cognitive)
+      expect(lp.loop_type).to eq(:cognitive)
+    end
+  end
+
+  describe '#execute_action' do
+    it 'returns success: true on match' do
+      result = engine.execute_action(coupling_id: coupling.id, actual_perception: 'grip')
+      expect(result[:success]).to be true
+      expect(result[:match]).to be true
+    end
+
+    it 'returns success: true on mismatch' do
+      result = engine.execute_action(coupling_id: coupling.id, actual_perception: 'slip')
+      expect(result[:success]).to be true
+      expect(result[:match]).to be false
+    end
+
+    it 'returns success: false for missing coupling' do
+      result = engine.execute_action(coupling_id: 'nonexistent', actual_perception: 'grip')
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:not_found)
+    end
+
+    it 'includes coupling_label in result' do
+      result = engine.execute_action(coupling_id: coupling.id, actual_perception: 'grip')
+      expect(result[:coupling_label]).to be_a(Symbol)
+    end
+  end
+
+  describe '#adapt_coupling' do
+    it 'updates the coupling perception' do
+      engine.adapt_coupling(coupling_id: coupling.id, new_perception: 'firm_grip')
+      expect(engine.couplings[coupling.id].perception).to eq('firm_grip')
+    end
+
+    it 'returns success: true' do
+      result = engine.adapt_coupling(coupling_id: coupling.id, new_perception: 'firm_grip')
+      expect(result[:success]).to be true
+    end
+
+    it 'returns success: false for missing coupling' do
+      result = engine.adapt_coupling(coupling_id: 'bad', new_perception: 'x')
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#find_action_for' do
+    before do
+      5.times { engine.execute_action(coupling_id: coupling.id, actual_perception: 'grip') }
+    end
+
+    it 'returns the loop when it is coupled and perception matches' do
+      result = engine.find_action_for(perception: 'grip')
+      if coupling.coupled?
+        expect(result).not_to be_nil
+        expect(result.action).to eq('grasp')
+      else
+        expect(result).to be_nil
+      end
+    end
+
+    it 'returns nil when perception does not match any coupled loop' do
+      result = engine.find_action_for(perception: 'unknown_perception')
+      expect(result).to be_nil
+    end
+  end
+
+  describe '#coupled_loops' do
+    it 'returns empty when nothing is coupled' do
+      engine.create_coupling(action: 'act', perception: 'per', domain: 'dom')
+      expect(engine.coupled_loops).to be_empty
+    end
+
+    it 'returns loops above coupling threshold' do
+      c2 = engine.create_coupling(action: 'act2', perception: 'per2', domain: 'dom2')
+      allow(c2).to receive(:coupled?).and_return(true)
+      expect(engine.coupled_loops).to include(c2)
+    end
+  end
+
+  describe '#by_domain' do
+    it 'returns loops in the specified domain' do
+      engine.create_coupling(action: 'act', perception: 'per', domain: 'motor')
+      engine.create_coupling(action: 'speak', perception: 'heard', domain: 'social')
+      expect(engine.by_domain(domain: 'motor').size).to eq(1)
+    end
+  end
+
+  describe '#by_type' do
+    it 'returns loops of the specified type' do
+      engine.create_coupling(action: 'act', perception: 'per', domain: 'dom', loop_type: :cognitive)
+      engine.create_coupling(action: 'act2', perception: 'per2', domain: 'dom2', loop_type: :social)
+      expect(engine.by_type(loop_type: :cognitive).size).to eq(1)
+    end
+  end
+
+  describe '#strongest_couplings' do
+    it 'returns at most limit couplings sorted by strength desc' do
+      3.times { |i| engine.create_coupling(action: "a#{i}", perception: "p#{i}", domain: 'dom') }
+      result = engine.strongest_couplings(limit: 2)
+      expect(result.size).to be <= 2
+    end
+  end
+
+  describe '#overall_coupling' do
+    it 'returns 0.0 when no couplings exist' do
+      expect(engine.overall_coupling).to eq(0.0)
+    end
+
+    it 'returns mean coupling strength' do
+      engine.create_coupling(action: 'a', perception: 'p', domain: 'd')
+      expect(engine.overall_coupling).to eq(
+        Legion::Extensions::Agentic::Inference::EnactiveCognition::Helpers::SensorimotorLoop::DEFAULT_COUPLING_STRENGTH
+      )
+    end
+  end
+
+  describe '#decay_all' do
+    it 'reduces coupling strength of all loops' do
+      lp = engine.create_coupling(action: 'a', perception: 'p', domain: 'd')
+      before = lp.coupling_strength
+      engine.decay_all
+      expect(lp.coupling_strength).to be < before
+    end
+  end
+
+  describe '#prune_decoupled' do
+    it 'removes very weak couplings' do
+      lp = engine.create_coupling(action: 'a', perception: 'p', domain: 'd')
+      100.times { lp.execute!(actual_perception: 'miss') }
+      count_before = engine.count
+      engine.prune_decoupled
+      expect(engine.count).to be <= count_before
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes expected keys' do
+      result = engine.to_h
+      expect(result).to include(:coupling_count, :coupled_count, :overall_coupling, :strongest)
+    end
+
+    it 'rounds overall_coupling to 4 decimal places' do
+      engine.create_coupling(action: 'a', perception: 'p', domain: 'd')
+      result = engine.to_h
+      expect(result[:overall_coupling]).to be_a(Float)
+    end
+  end
+end

data/spec/legion/extensions/agentic/inference/enactive_cognition/helpers/sensorimotor_loop_spec.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/inference/enactive_cognition/helpers/sensorimotor_loop'
+
+RSpec.describe Legion::Extensions::Agentic::Inference::EnactiveCognition::Helpers::SensorimotorLoop do
+  subject(:loop_obj) do
+    described_class.new(action: 'reach', perception: 'contact', domain: 'motor')
+  end
+
+  describe '#initialize' do
+    it 'assigns a uuid id' do
+      expect(loop_obj.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets default coupling strength' do
+      expect(loop_obj.coupling_strength).to eq(described_class::DEFAULT_COUPLING_STRENGTH)
+    end
+
+    it 'defaults loop_type to :sensorimotor' do
+      expect(loop_obj.loop_type).to eq(:sensorimotor)
+    end
+
+    it 'accepts valid loop types' do
+      cognitive = described_class.new(action: 'think', perception: 'insight', domain: 'cog', loop_type: :cognitive)
+      expect(cognitive.loop_type).to eq(:cognitive)
+    end
+
+    it 'falls back to :sensorimotor for invalid loop_type' do
+      bad = described_class.new(action: 'x', perception: 'y', domain: 'z', loop_type: :invalid)
+      expect(bad.loop_type).to eq(:sensorimotor)
+    end
+
+    it 'starts with zero execution count' do
+      expect(loop_obj.execution_count).to eq(0)
+    end
+
+    it 'starts with zero accurate_predictions' do
+      expect(loop_obj.accurate_predictions).to eq(0)
+    end
+  end
+
+  describe '#execute!' do
+    context 'when actual matches expected perception' do
+      it 'increments execution_count' do
+        loop_obj.execute!(actual_perception: 'contact')
+        expect(loop_obj.execution_count).to eq(1)
+      end
+
+      it 'increments accurate_predictions' do
+        loop_obj.execute!(actual_perception: 'contact')
+        expect(loop_obj.accurate_predictions).to eq(1)
+      end
+
+      it 'strengthens coupling' do
+        before = loop_obj.coupling_strength
+        loop_obj.execute!(actual_perception: 'contact')
+        expect(loop_obj.coupling_strength).to be > before
+      end
+
+      it 'returns match: true' do
+        result = loop_obj.execute!(actual_perception: 'contact')
+        expect(result[:match]).to be true
+      end
+
+      it 'does not exceed COUPLING_CEILING' do
+        20.times { loop_obj.execute!(actual_perception: 'contact') }
+        expect(loop_obj.coupling_strength).to be <= described_class::COUPLING_CEILING
+      end
+    end
+
+    context 'when actual does not match expected perception' do
+      it 'weakens coupling' do
+        before = loop_obj.coupling_strength
+        loop_obj.execute!(actual_perception: 'no_contact')
+        expect(loop_obj.coupling_strength).to be < before
+      end
+
+      it 'returns match: false' do
+        result = loop_obj.execute!(actual_perception: 'no_contact')
+        expect(result[:match]).to be false
+      end
+
+      it 'does not fall below COUPLING_FLOOR' do
+        20.times { loop_obj.execute!(actual_perception: 'no_contact') }
+        expect(loop_obj.coupling_strength).to be >= described_class::COUPLING_FLOOR
+      end
+
+      it 'does not increment accurate_predictions' do
+        loop_obj.execute!(actual_perception: 'no_contact')
+        expect(loop_obj.accurate_predictions).to eq(0)
+      end
+    end
+
+    it 'updates prediction_accuracy' do
+      3.times { loop_obj.execute!(actual_perception: 'contact') }
+      loop_obj.execute!(actual_perception: 'miss')
+      expect(loop_obj.prediction_accuracy).to eq(0.75)
+    end
+
+    it 'sets last_executed_at' do
+      loop_obj.execute!(actual_perception: 'contact')
+      expect(loop_obj.last_executed_at).not_to be_nil
+    end
+  end
+
+  describe '#coupled?' do
+    it 'returns false at default strength (0.5)' do
+      expect(loop_obj.coupled?).to be false
+    end
+
+    it 'returns true when strength reaches 0.6' do
+      loop_obj.execute!(actual_perception: 'contact')
+      loop_obj.execute!(actual_perception: 'contact')
+      if loop_obj.coupling_strength >= 0.6
+        expect(loop_obj.coupled?).to be true
+      else
+        expect(loop_obj.coupled?).to be false
+      end
+    end
+  end
+
+  describe '#coupling_label' do
+    it 'returns :forming at default strength 0.5' do
+      expect(loop_obj.coupling_label).to eq(:forming)
+    end
+
+    it 'returns :entrained at strength 0.9' do
+      allow(loop_obj).to receive(:coupling_strength).and_return(0.9)
+      expect(loop_obj.coupling_label).to eq(:entrained)
+    end
+
+    it 'returns :decoupled at strength 0.1' do
+      allow(loop_obj).to receive(:coupling_strength).and_return(0.1)
+      expect(loop_obj.coupling_label).to eq(:decoupled)
+    end
+
+    it 'returns :weak at strength 0.25' do
+      allow(loop_obj).to receive(:coupling_strength).and_return(0.25)
+      expect(loop_obj.coupling_label).to eq(:weak)
+    end
+
+    it 'returns :coupled at strength 0.7' do
+      allow(loop_obj).to receive(:coupling_strength).and_return(0.7)
+      expect(loop_obj.coupling_label).to eq(:coupled)
+    end
+  end
+
+  describe '#adapt_perception!' do
+    it 'updates the expected perception' do
+      loop_obj.adapt_perception!(new_perception: 'soft_contact')
+      expect(loop_obj.perception).to eq('soft_contact')
+    end
+  end
+
+  describe '#decay!' do
+    it 'reduces coupling_strength by COUPLING_DECAY' do
+      before = loop_obj.coupling_strength
+      loop_obj.decay!
+      expect(loop_obj.coupling_strength).to eq((before - described_class::COUPLING_DECAY).clamp(0.0, 1.0))
+    end
+
+    it 'does not fall below COUPLING_FLOOR' do
+      100.times { loop_obj.decay! }
+      expect(loop_obj.coupling_strength).to be >= described_class::COUPLING_FLOOR
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all expected keys' do
+      hash = loop_obj.to_h
+      expect(hash).to include(
+        :id, :action, :perception, :domain, :loop_type,
+        :coupling_strength, :coupling_label, :prediction_accuracy,
+        :execution_count, :accurate_predictions, :coupled,
+        :created_at, :last_executed_at
+      )
+    end
+
+    it 'reflects current coupling_label' do
+      hash = loop_obj.to_h
+      expect(hash[:coupling_label]).to eq(loop_obj.coupling_label)
+    end
+  end
+end