lex-cognitive-tide 0.1.1

data/spec/legion/extensions/cognitive_tide/actors/tide_cycle_spec.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Actors
+      class Every # rubocop:disable Lint/EmptyClass
+      end
+    end
+  end
+end
+
+$LOADED_FEATURES << 'legion/extensions/actors/every'
+
+require_relative '../../../../../lib/legion/extensions/cognitive_tide/actors/tide_cycle'
+
+RSpec.describe Legion::Extensions::CognitiveTide::Actor::TideCycle do
+  subject(:actor) { described_class.new }
+
+  describe '#runner_class' do
+    it { expect(actor.runner_class).to eq Legion::Extensions::CognitiveTide::Runners::CognitiveTide }
+  end
+
+  describe '#runner_function' do
+    it { expect(actor.runner_function).to eq 'tide_maintenance' }
+  end
+
+  describe '#time' do
+    it { expect(actor.time).to eq 60 }
+  end
+
+  describe '#run_now?' do
+    it { expect(actor.run_now?).to be false }
+  end
+
+  describe '#use_runner?' do
+    it { expect(actor.use_runner?).to be false }
+  end
+
+  describe '#check_subtask?' do
+    it { expect(actor.check_subtask?).to be false }
+  end
+
+  describe '#generate_task?' do
+    it { expect(actor.generate_task?).to be false }
+  end
+end

data/spec/legion/extensions/cognitive_tide/client_spec.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::CognitiveTide::Client do
+  let(:client) { described_class.new }
+
+  describe '#initialize' do
+    it 'creates a new client' do
+      expect(client).to be_a(described_class)
+    end
+
+    it 'responds to runner methods' do
+      expect(client).to respond_to(:add_oscillator)
+      expect(client).to respond_to(:check_tide)
+      expect(client).to respond_to(:deposit_idea)
+      expect(client).to respond_to(:harvest)
+      expect(client).to respond_to(:tide_forecast)
+      expect(client).to respond_to(:tide_status)
+    end
+  end
+
+  describe 'full lifecycle' do
+    it 'adds oscillators, deposits ideas, and harvests on rising tide' do
+      # Add two oscillators
+      r1 = client.add_oscillator(oscillator_type: :primary, period: 86_400, amplitude: 1.0)
+      r2 = client.add_oscillator(oscillator_type: :secondary, period: 43_200, amplitude: 0.5)
+      expect(r1[:success]).to be(true)
+      expect(r2[:success]).to be(true)
+
+      # Deposit ideas
+      d1 = client.deposit_idea(domain: 'architecture', idea: 'refactor auth module')
+      d2 = client.deposit_idea(domain: 'architecture', idea: 'simplify routing layer')
+      d3 = client.deposit_idea(domain: 'testing', idea: 'add integration specs')
+      expect(d1[:success]).to be(true)
+      expect(d2[:success]).to be(true)
+      expect(d3[:success]).to be(true)
+
+      # Check tide
+      tide = client.check_tide
+      expect(tide[:level]).to be_between(0.0, 1.0)
+      expect(tide[:phase]).to be_a(Symbol)
+
+      # Harvest (result depends on rising? state, but should not error)
+      harvest = client.harvest
+      expect(harvest[:success]).to be(true)
+      expect(harvest[:harvested]).to be_a(Hash)
+
+      # Status
+      status = client.tide_status
+      expect(status[:oscillator_count]).to eq(2)
+      expect(status[:success]).to be(true)
+    end
+
+    it 'forecasts the tide for a given duration' do
+      client.add_oscillator(oscillator_type: :lunar, period: 2_551_443, amplitude: 0.8)
+      result = client.tide_forecast(duration: 86_400)
+      expect(result[:success]).to be(true)
+      expect(result[:forecast]).to be_an(Array)
+      expect(result[:forecast]).not_to be_empty
+    end
+
+    it 'tidal pools accumulate ideas independently per domain' do
+      client.add_oscillator(oscillator_type: :primary, period: 86_400)
+      %w[alpha beta gamma].each do |domain|
+        3.times { |i| client.deposit_idea(domain: domain, idea: "idea #{i} in #{domain}") }
+      end
+      status = client.tide_status
+      expect(status[:pool_count]).to eq(3)
+    end
+
+    it 'returns the same engine state across calls' do
+      client.add_oscillator(oscillator_type: :primary, period: 86_400)
+      status_a = client.tide_status
+      status_b = client.tide_status
+      expect(status_a[:oscillator_count]).to eq(status_b[:oscillator_count])
+    end
+  end
+
+  describe 'error handling' do
+    it 'returns success: false for invalid oscillator_type without raising' do
+      result = client.add_oscillator(oscillator_type: :bogus, period: 3600)
+      expect(result[:success]).to be(false)
+      expect(result[:error]).to be_a(String)
+    end
+
+    it 'returns success: false for non-positive period without raising' do
+      result = client.add_oscillator(oscillator_type: :primary, period: -1)
+      expect(result[:success]).to be(false)
+    end
+  end
+end

data/spec/legion/extensions/cognitive_tide/helpers/constants_spec.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::CognitiveTide::Helpers::Constants do
+  describe 'TIDE_PHASES' do
+    it 'contains the four expected phases' do
+      expect(described_class::TIDE_PHASES).to eq(%i[rising high_tide falling low_tide])
+    end
+
+    it 'is frozen' do
+      expect(described_class::TIDE_PHASES).to be_frozen
+    end
+  end
+
+  describe 'OSCILLATOR_TYPES' do
+    it 'contains primary, secondary, and lunar' do
+      expect(described_class::OSCILLATOR_TYPES).to eq(%i[primary secondary lunar])
+    end
+
+    it 'is frozen' do
+      expect(described_class::OSCILLATOR_TYPES).to be_frozen
+    end
+  end
+
+  describe 'MAX_POOLS' do
+    it 'is a positive integer' do
+      expect(described_class::MAX_POOLS).to be_a(Integer)
+      expect(described_class::MAX_POOLS).to be > 0
+    end
+
+    it 'equals 50' do
+      expect(described_class::MAX_POOLS).to eq(50)
+    end
+  end
+
+  describe 'POOL_EVAPORATION_RATE' do
+    it 'is a float between 0 and 1' do
+      expect(described_class::POOL_EVAPORATION_RATE).to be_a(Float)
+      expect(described_class::POOL_EVAPORATION_RATE).to be >= 0.0
+      expect(described_class::POOL_EVAPORATION_RATE).to be <= 1.0
+    end
+
+    it 'equals 0.01' do
+      expect(described_class::POOL_EVAPORATION_RATE).to eq(0.01)
+    end
+  end
+
+  describe 'TIDE_LABELS' do
+    it 'is frozen' do
+      expect(described_class::TIDE_LABELS).to be_frozen
+    end
+
+    it 'contains five label entries' do
+      expect(described_class::TIDE_LABELS.size).to eq(5)
+    end
+
+    it 'each entry has a range and a label' do
+      described_class::TIDE_LABELS.each do |entry|
+        expect(entry[:range]).to be_a(Range)
+        expect(entry[:label]).to be_a(String)
+      end
+    end
+
+    it 'covers the full [0, 1] range collectively' do
+      levels = [0.0, 0.1, 0.25, 0.45, 0.65, 0.85, 1.0]
+      levels.each do |level|
+        matched = described_class::TIDE_LABELS.any? { |tl| tl[:range].cover?(level) }
+        expect(matched).to be(true), "No label for level #{level}"
+      end
+    end
+
+    it 'maps 1.0 to peak' do
+      entry = described_class::TIDE_LABELS.find { |tl| tl[:range].cover?(1.0) }
+      expect(entry[:label]).to eq('peak')
+    end
+
+    it 'maps 0.0 to ebb' do
+      entry = described_class::TIDE_LABELS.find { |tl| tl[:range].cover?(0.0) }
+      expect(entry[:label]).to eq('ebb')
+    end
+
+    it 'maps 0.75 to high' do
+      entry = described_class::TIDE_LABELS.find { |tl| tl[:range].cover?(0.75) }
+      expect(entry[:label]).to eq('high')
+    end
+  end
+
+  describe 'HARVEST_RISING_THRESHOLD' do
+    it 'is a float between 0 and 1' do
+      expect(described_class::HARVEST_RISING_THRESHOLD).to be_a(Float)
+      expect(described_class::HARVEST_RISING_THRESHOLD).to be_between(0.0, 1.0)
+    end
+  end
+
+  describe 'FORECAST_RESOLUTION' do
+    it 'is a positive integer (seconds)' do
+      expect(described_class::FORECAST_RESOLUTION).to be_a(Integer)
+      expect(described_class::FORECAST_RESOLUTION).to be > 0
+    end
+  end
+end

data/spec/legion/extensions/cognitive_tide/helpers/oscillator_spec.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::CognitiveTide::Helpers::Oscillator do
+  let(:primary) { described_class.new(oscillator_type: :primary, period: 86_400, amplitude: 1.0, phase_offset: 0.0) }
+  let(:secondary) { described_class.new(oscillator_type: :secondary, period: 43_200, amplitude: 0.5, phase_offset: 1.5) }
+
+  describe '#initialize' do
+    it 'assigns oscillator_type' do
+      expect(primary.oscillator_type).to eq(:primary)
+    end
+
+    it 'assigns period as float' do
+      expect(primary.period).to eq(86_400.0)
+    end
+
+    it 'assigns amplitude clamped to [0, 1]' do
+      osc = described_class.new(oscillator_type: :lunar, period: 2_551_443, amplitude: 1.5)
+      expect(osc.amplitude).to eq(1.0)
+    end
+
+    it 'clamps amplitude at 0' do
+      osc = described_class.new(oscillator_type: :primary, period: 3600, amplitude: -0.5)
+      expect(osc.amplitude).to eq(0.0)
+    end
+
+    it 'assigns phase_offset as float' do
+      expect(secondary.phase_offset).to eq(1.5)
+    end
+
+    it 'generates a unique uuid id' do
+      o1 = described_class.new(oscillator_type: :primary, period: 3600)
+      o2 = described_class.new(oscillator_type: :primary, period: 3600)
+      expect(o1.id).not_to eq(o2.id)
+      expect(o1.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'raises ArgumentError for unknown oscillator_type' do
+      expect { described_class.new(oscillator_type: :unknown, period: 3600) }
+        .to raise_error(ArgumentError, /unknown oscillator_type/)
+    end
+
+    it 'raises ArgumentError when period is not positive' do
+      expect { described_class.new(oscillator_type: :primary, period: 0) }
+        .to raise_error(ArgumentError, /period must be positive/)
+    end
+
+    it 'raises ArgumentError for negative period' do
+      expect { described_class.new(oscillator_type: :primary, period: -100) }
+        .to raise_error(ArgumentError, /period must be positive/)
+    end
+  end
+
+  describe '#value_at' do
+    it 'returns a value between 0 and amplitude' do
+      val = primary.value_at(Time.now.utc)
+      expect(val).to be >= 0.0
+      expect(val).to be <= primary.amplitude
+    end
+
+    it 'returns 0.0 when amplitude is 0' do
+      osc = described_class.new(oscillator_type: :primary, period: 3600, amplitude: 0.0)
+      expect(osc.value_at(Time.now.utc)).to eq(0.0)
+    end
+
+    it 'varies over time within a period' do
+      t = Time.now.utc
+      values = (0...10).map { |i| primary.value_at(t + (i * 8640)) }
+      expect(values.uniq.size).to be > 1
+    end
+
+    it 'is deterministic for the same time' do
+      t = Time.now.utc
+      expect(primary.value_at(t)).to eq(primary.value_at(t))
+    end
+
+    it 'returns rounded value (10 decimal places)' do
+      val = primary.value_at(Time.now.utc)
+      expect(val).to eq(val.round(10))
+    end
+
+    it 'respects phase_offset — same period different offset yields different values' do
+      # Use t = period/4 so that sin(PI/2 + 0) = 1.0 and sin(PI/2 + PI/2) = 0.0
+      period = 3600
+      t = Time.at(period / 4.0).utc
+      o1 = described_class.new(oscillator_type: :primary, period: period, amplitude: 1.0, phase_offset: 0.0)
+      o2 = described_class.new(oscillator_type: :primary, period: period, amplitude: 1.0, phase_offset: Math::PI / 2.0)
+      expect(o1.value_at(t)).not_to be_within(0.05).of(o2.value_at(t))
+    end
+  end
+
+  describe '#current_value' do
+    it 'returns a numeric in [0, amplitude]' do
+      val = primary.current_value
+      expect(val).to be_a(Float)
+      expect(val).to be >= 0.0
+      expect(val).to be <= 1.0
+    end
+  end
+
+  describe '#tick!' do
+    it 'returns a numeric value' do
+      expect(primary.tick!).to be_a(Float)
+    end
+
+    it 'updates last_ticked_at' do
+      before = Time.now.utc
+      primary.tick!
+      expect(primary.to_h[:last_ticked_at]).to be >= before
+    end
+  end
+
+  describe '#in_phase_with?' do
+    it 'returns true when two identical oscillators are compared' do
+      o1 = described_class.new(oscillator_type: :primary, period: 86_400, amplitude: 1.0, phase_offset: 0.0)
+      o2 = described_class.new(oscillator_type: :primary, period: 86_400, amplitude: 1.0, phase_offset: 0.0)
+      expect(o1.in_phase_with?(o2)).to be(true)
+    end
+
+    it 'returns false when oscillators are 180 degrees out of phase' do
+      # At t = period/4: sin(PI/2 + 0) = 1.0 -> value = 1.0; sin(PI/2 + PI) = -1.0 -> value = 0.0
+      # Difference = 1.0, tolerance = 0.15 * (1+1) = 0.30 — NOT in phase
+      period = 3600
+      t = Time.at(period / 4.0).utc
+      allow(Time).to receive(:now).and_return(t)
+      o1 = described_class.new(oscillator_type: :primary, period: period, amplitude: 1.0, phase_offset: 0.0)
+      o2 = described_class.new(oscillator_type: :secondary, period: period, amplitude: 1.0, phase_offset: Math::PI)
+      expect(o1.in_phase_with?(o2)).to be(false)
+    end
+
+    it 'returns false when combined amplitude is zero' do
+      o1 = described_class.new(oscillator_type: :primary, period: 3600, amplitude: 0.0)
+      o2 = described_class.new(oscillator_type: :secondary, period: 3600, amplitude: 0.0)
+      expect(o1.in_phase_with?(o2)).to be(false)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with expected keys' do
+      h = primary.to_h
+      expect(h.keys).to include(:id, :oscillator_type, :period, :amplitude, :phase_offset,
+                                :current_value, :last_ticked_at)
+    end
+
+    it 'reflects the correct oscillator_type' do
+      expect(primary.to_h[:oscillator_type]).to eq(:primary)
+    end
+
+    it 'last_ticked_at is nil before first tick' do
+      osc = described_class.new(oscillator_type: :primary, period: 3600)
+      expect(osc.to_h[:last_ticked_at]).to be_nil
+    end
+  end
+end

data/spec/legion/extensions/cognitive_tide/helpers/tidal_pool_spec.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::CognitiveTide::Helpers::TidalPool do
+  let(:pool) { described_class.new(domain: 'architecture', capacity: 5) }
+
+  describe '#initialize' do
+    it 'assigns domain as string' do
+      expect(pool.domain).to eq('architecture')
+    end
+
+    it 'accepts symbol domain and converts to string' do
+      p = described_class.new(domain: :philosophy)
+      expect(p.domain).to eq('philosophy')
+    end
+
+    it 'assigns capacity' do
+      expect(pool.capacity).to eq(5)
+    end
+
+    it 'starts empty' do
+      expect(pool.size).to eq(0)
+    end
+
+    it 'starts with zero evaporation_count' do
+      expect(pool.evaporation_count).to eq(0)
+    end
+
+    it 'generates a uuid id' do
+      expect(pool.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'raises ArgumentError for non-positive capacity' do
+      expect { described_class.new(domain: 'test', capacity: 0) }
+        .to raise_error(ArgumentError, /capacity must be positive/)
+    end
+
+    it 'raises ArgumentError for negative capacity' do
+      expect { described_class.new(domain: 'test', capacity: -1) }
+        .to raise_error(ArgumentError, /capacity must be positive/)
+    end
+  end
+
+  describe '#deposit' do
+    it 'deposits an item and returns true' do
+      result = pool.deposit('refactor auth layer')
+      expect(result).to be(true)
+      expect(pool.size).to eq(1)
+    end
+
+    it 'stores items with metadata' do
+      pool.deposit('idea one')
+      item = pool.items.first
+      expect(item[:content]).to eq('idea one')
+      expect(item[:deposited_at]).to be_a(Time)
+      expect(item[:id]).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'returns false when pool is full' do
+      5.times { |i| pool.deposit("idea #{i}") }
+      expect(pool.deposit('overflow')).to be(false)
+    end
+
+    it 'does not add item when full' do
+      5.times { |i| pool.deposit("idea #{i}") }
+      pool.deposit('overflow')
+      expect(pool.size).to eq(5)
+    end
+
+    it 'accepts any object as item' do
+      pool.deposit({ key: 'value' })
+      pool.deposit(42)
+      pool.deposit(:symbol)
+      expect(pool.size).to eq(3)
+    end
+  end
+
+  describe '#harvest!' do
+    it 'returns all items' do
+      pool.deposit('alpha')
+      pool.deposit('beta')
+      harvested = pool.harvest!
+      expect(harvested.size).to eq(2)
+      expect(harvested.map { |i| i[:content] }).to contain_exactly('alpha', 'beta')
+    end
+
+    it 'clears the pool after harvest' do
+      pool.deposit('alpha')
+      pool.harvest!
+      expect(pool.size).to eq(0)
+    end
+
+    it 'returns empty array when pool is empty' do
+      expect(pool.harvest!).to eq([])
+    end
+  end
+
+  describe '#evaporate!' do
+    let(:large_pool) { described_class.new(domain: 'test', capacity: 20) }
+
+    before { 10.times { |i| large_pool.deposit("item #{i}") } }
+
+    it 'removes a proportion of items (oldest first)' do
+      large_pool.evaporate!(0.2)
+      # ceil(10 * 0.2) = 2 removed
+      expect(large_pool.size).to eq(8)
+    end
+
+    it 'increments evaporation_count' do
+      large_pool.evaporate!(0.3)
+      expect(large_pool.evaporation_count).to be > 0
+    end
+
+    it 'returns the number of items removed' do
+      removed = large_pool.evaporate!(0.1)
+      expect(removed).to eq(1)
+    end
+
+    it 'clamps rate at 1.0 and removes all items' do
+      large_pool.evaporate!(2.0)
+      expect(large_pool.size).to eq(0)
+    end
+
+    it 'clamps rate at 0.0 and removes nothing' do
+      large_pool.evaporate!(-0.5)
+      expect(large_pool.size).to eq(10)
+    end
+
+    it 'uses POOL_EVAPORATION_RATE when no argument given' do
+      # 0.01 rate on 10 items: ceil(0.1) = 1 removed
+      removed = large_pool.evaporate!
+      expect(removed).to eq(1)
+      expect(large_pool.size).to eq(9)
+    end
+  end
+
+  describe '#full?' do
+    it 'returns false when below capacity' do
+      expect(pool.full?).to be(false)
+    end
+
+    it 'returns true when at capacity' do
+      5.times { |i| pool.deposit("item #{i}") }
+      expect(pool.full?).to be(true)
+    end
+  end
+
+  describe '#depth' do
+    it 'returns 0.0 when empty' do
+      expect(pool.depth).to eq(0.0)
+    end
+
+    it 'returns 1.0 when full' do
+      5.times { |i| pool.deposit("item #{i}") }
+      expect(pool.depth).to eq(1.0)
+    end
+
+    it 'returns fractional depth' do
+      pool.deposit('one')
+      pool.deposit('two')
+      expect(pool.depth).to be_within(0.001).of(0.4)
+    end
+
+    it 'rounds to 10 decimal places' do
+      pool.deposit('one')
+      expect(pool.depth).to eq(pool.depth.round(10))
+    end
+  end
+
+  describe '#items' do
+    it 'returns a copy of items (not the internal array)' do
+      pool.deposit('item')
+      items = pool.items
+      items.clear
+      expect(pool.size).to eq(1)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns expected keys' do
+      h = pool.to_h
+      expect(h.keys).to include(:id, :domain, :capacity, :size, :depth, :evaporation_count, :created_at)
+    end
+
+    it 'size reflects current item count' do
+      pool.deposit('x')
+      expect(pool.to_h[:size]).to eq(1)
+    end
+
+    it 'created_at is a Time' do
+      expect(pool.to_h[:created_at]).to be_a(Time)
+    end
+  end
+end