lex-agentic-defense 0.1.0

data/spec/legion/extensions/agentic/defense/quicksand/runners/cognitive_quicksand_spec.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Defense::Quicksand::Runners::CognitiveQuicksand do
+  let(:runner) do
+    obj = Object.new
+    obj.extend(described_class)
+    obj
+  end
+
+  let(:engine) { Legion::Extensions::Agentic::Defense::Quicksand::Helpers::QuicksandEngine.new }
+
+  describe '#create_trap' do
+    it 'returns success' do
+      result = runner.create_trap(trap_type: :overthinking, domain: :reasoning,
+                                  content: 'test', engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:trap][:trap_type]).to eq(:overthinking)
+    end
+
+    it 'returns failure for invalid type' do
+      result = runner.create_trap(trap_type: :joy, domain: :t, content: 'x', engine: engine)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#create_pit' do
+    it 'returns success' do
+      result = runner.create_pit(engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:pit]).to be_a(Hash)
+    end
+  end
+
+  describe '#struggle' do
+    it 'returns trap with struggle data' do
+      t = engine.create_trap(trap_type: :overthinking, domain: :t, content: 'x')
+      result = runner.struggle(trap_id: t.id, engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:struggle_count]).to eq(1)
+    end
+
+    it 'returns failure for unknown trap' do
+      result = runner.struggle(trap_id: 'bad', engine: engine)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#calm_down' do
+    it 'decreases depth' do
+      t = engine.create_trap(trap_type: :rumination, domain: :t, content: 'x', depth: 0.5)
+      result = runner.calm_down(trap_id: t.id, engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:trap][:depth]).to be < 0.5
+    end
+  end
+
+  describe '#attempt_escape' do
+    it 'returns escape result' do
+      t = engine.create_trap(trap_type: :indecision, domain: :t, content: 'x', depth: 0.4)
+      result = runner.attempt_escape(trap_id: t.id, engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:result]).to eq(:escaped)
+    end
+  end
+
+  describe '#list_traps' do
+    before do
+      engine.create_trap(trap_type: :overthinking, domain: :t, content: 'a')
+      engine.create_trap(trap_type: :rumination, domain: :t, content: 'b')
+    end
+
+    it 'returns all traps' do
+      result = runner.list_traps(engine: engine)
+      expect(result[:count]).to eq(2)
+    end
+
+    it 'filters by trap_type' do
+      result = runner.list_traps(trap_type: :overthinking, engine: engine)
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#quicksand_status' do
+    it 'returns report' do
+      result = runner.quicksand_status(engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:report]).to include(:total_traps)
+    end
+  end
+end

data/spec/legion/extensions/agentic/defense/quicksilver/client_spec.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/defense/quicksilver/client'
+
+RSpec.describe Legion::Extensions::Agentic::Defense::Quicksilver::Client do
+  let(:client) { described_class.new }
+
+  it 'responds to all runner methods' do
+    %i[create_droplet create_pool shift_form merge split capture release add_to_pool
+       list_droplets quicksilver_status].each do |method|
+      expect(client).to respond_to(method)
+    end
+  end
+
+  it 'maintains isolated state per instance' do
+    client_a = described_class.new
+    client_b = described_class.new
+
+    client_a.create_droplet(form: :liquid, content: 'exclusive to a')
+    expect(client_a.quicksilver_status[:total_droplets]).to eq(1)
+    expect(client_b.quicksilver_status[:total_droplets]).to eq(0)
+  end
+
+  it 'round-trips a full quicksilver cycle' do
+    # Create droplet
+    d_result = client.create_droplet(form: :droplet, content: 'round trip idea')
+    expect(d_result[:success]).to be true
+    droplet_id = d_result[:droplet][:id]
+
+    # Create pool
+    p_result = client.create_pool(surface_type: :glass)
+    expect(p_result[:success]).to be true
+    pool_id = p_result[:pool][:id]
+
+    # Shift form
+    shift_result = client.shift_form(droplet_id: droplet_id, new_form: :liquid)
+    expect(shift_result[:droplet][:form]).to eq(:liquid)
+
+    # Add to pool
+    add_result = client.add_to_pool(droplet_id: droplet_id, pool_id: pool_id)
+    expect(add_result[:pool][:droplet_count]).to eq(1)
+
+    # Capture
+    cap_result = client.capture(droplet_id: droplet_id)
+    expect(cap_result[:droplet][:captured]).to be true
+
+    # Release
+    rel_result = client.release(droplet_id: droplet_id)
+    expect(rel_result[:droplet][:captured]).to be false
+
+    # Status report
+    status = client.quicksilver_status
+    expect(status[:total_droplets]).to eq(1)
+    expect(status[:total_pools]).to eq(1)
+  end
+
+  it 'handles merge and split lifecycle' do
+    a = client.create_droplet(form: :stream, content: 'stream a', mass: 0.4)
+    b = client.create_droplet(form: :stream, content: 'stream b', mass: 0.3)
+    a_id = a[:droplet][:id]
+    b_id = b[:droplet][:id]
+
+    merged = client.merge(droplet_a_id: a_id, droplet_b_id: b_id)
+    expect(merged[:success]).to be true
+    merged_mass = merged[:droplet][:mass]
+    expect(merged_mass).to be > 0.4
+
+    split = client.split(droplet_id: a_id)
+    expect(split[:success]).to be true
+    expect(split[:twin][:id]).not_to eq(a_id)
+  end
+end

data/spec/legion/extensions/agentic/defense/quicksilver/helpers/constants_spec.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Defense::Quicksilver::Helpers::Constants do
+  describe 'FORM_TYPES' do
+    it 'contains expected forms' do
+      expect(described_class::FORM_TYPES).to contain_exactly(:liquid, :droplet, :bead, :stream, :pool)
+    end
+
+    it 'is frozen' do
+      expect(described_class::FORM_TYPES).to be_frozen
+    end
+  end
+
+  describe 'SURFACE_TYPES' do
+    it 'contains expected surfaces' do
+      expect(described_class::SURFACE_TYPES).to contain_exactly(:glass, :metal, :wood, :stone, :fabric)
+    end
+
+    it 'is frozen' do
+      expect(described_class::SURFACE_TYPES).to be_frozen
+    end
+  end
+
+  describe 'numeric constants' do
+    it 'MAX_DROPLETS is 500' do
+      expect(described_class::MAX_DROPLETS).to eq(500)
+    end
+
+    it 'MAX_POOLS is 50' do
+      expect(described_class::MAX_POOLS).to eq(50)
+    end
+
+    it 'FLUIDITY_BASE is 0.8' do
+      expect(described_class::FLUIDITY_BASE).to eq(0.8)
+    end
+
+    it 'SURFACE_TENSION is 0.3' do
+      expect(described_class::SURFACE_TENSION).to eq(0.3)
+    end
+
+    it 'EVAPORATION_RATE is 0.02' do
+      expect(described_class::EVAPORATION_RATE).to eq(0.02)
+    end
+
+    it 'COALESCENCE_BONUS is 0.1' do
+      expect(described_class::COALESCENCE_BONUS).to eq(0.1)
+    end
+  end
+
+  describe '.label_for' do
+    context 'with COHESION_LABELS' do
+      it 'returns :unified for mass near 1.0' do
+        expect(described_class.label_for(described_class::COHESION_LABELS, 0.95)).to eq(:unified)
+      end
+
+      it 'returns :cohesive for mid-high mass' do
+        expect(described_class.label_for(described_class::COHESION_LABELS, 0.7)).to eq(:cohesive)
+      end
+
+      it 'returns :scattered for mid mass' do
+        expect(described_class.label_for(described_class::COHESION_LABELS, 0.5)).to eq(:scattered)
+      end
+
+      it 'returns :dispersed for lower mass' do
+        expect(described_class.label_for(described_class::COHESION_LABELS, 0.3)).to eq(:dispersed)
+      end
+
+      it 'returns :atomized for very low mass' do
+        expect(described_class.label_for(described_class::COHESION_LABELS, 0.05)).to eq(:atomized)
+      end
+    end
+
+    context 'with FLUIDITY_LABELS' do
+      it 'returns :liquid for high fluidity' do
+        expect(described_class.label_for(described_class::FLUIDITY_LABELS, 0.9)).to eq(:liquid)
+      end
+
+      it 'returns :flowing for upper-mid fluidity' do
+        expect(described_class.label_for(described_class::FLUIDITY_LABELS, 0.65)).to eq(:flowing)
+      end
+
+      it 'returns :viscous for mid fluidity' do
+        expect(described_class.label_for(described_class::FLUIDITY_LABELS, 0.5)).to eq(:viscous)
+      end
+
+      it 'returns :sluggish for lower-mid fluidity' do
+        expect(described_class.label_for(described_class::FLUIDITY_LABELS, 0.25)).to eq(:sluggish)
+      end
+
+      it 'returns :solid for very low fluidity' do
+        expect(described_class.label_for(described_class::FLUIDITY_LABELS, 0.05)).to eq(:solid)
+      end
+    end
+
+    it 'clamps values above 1.0' do
+      result = described_class.label_for(described_class::FLUIDITY_LABELS, 1.5)
+      expect(result).to eq(:liquid)
+    end
+
+    it 'clamps values below 0.0' do
+      result = described_class.label_for(described_class::FLUIDITY_LABELS, -0.5)
+      expect(result).to eq(:solid)
+    end
+  end
+end

data/spec/legion/extensions/agentic/defense/quicksilver/helpers/droplet_spec.rb

@@ -0,0 +1,310 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Defense::Quicksilver::Helpers::Droplet do
+  let(:droplet) { described_class.new(form: :droplet, content: 'test idea') }
+
+  describe '#initialize' do
+    it 'assigns a uuid id' do
+      expect(droplet.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets form' do
+      expect(droplet.form).to eq(:droplet)
+    end
+
+    it 'sets content' do
+      expect(droplet.content).to eq('test idea')
+    end
+
+    it 'defaults mass to 0.3' do
+      expect(droplet.mass).to eq(0.3)
+    end
+
+    it 'defaults fluidity to FLUIDITY_BASE' do
+      expect(droplet.fluidity).to eq(Legion::Extensions::Agentic::Defense::Quicksilver::Helpers::Constants::FLUIDITY_BASE)
+    end
+
+    it 'defaults surface to :glass' do
+      expect(droplet.surface).to eq(:glass)
+    end
+
+    it 'defaults captured to false' do
+      expect(droplet.captured).to be false
+    end
+
+    it 'clamps mass above 1.0' do
+      d = described_class.new(form: :liquid, content: 'x', mass: 1.5)
+      expect(d.mass).to eq(1.0)
+    end
+
+    it 'clamps mass below 0.0' do
+      d = described_class.new(form: :liquid, content: 'x', mass: -0.5)
+      expect(d.mass).to eq(0.0)
+    end
+
+    it 'raises ArgumentError for invalid form' do
+      expect { described_class.new(form: :vapor, content: 'x') }.to raise_error(ArgumentError, /invalid form/)
+    end
+
+    it 'raises ArgumentError for invalid surface' do
+      expect do
+        described_class.new(form: :droplet, content: 'x', surface: :air)
+      end.to raise_error(ArgumentError, /invalid surface/)
+    end
+
+    it 'sets created_at' do
+      expect(droplet.created_at).to be_a(Time)
+    end
+  end
+
+  describe '#shift_form!' do
+    it 'changes the form' do
+      droplet.shift_form!(:liquid)
+      expect(droplet.form).to eq(:liquid)
+    end
+
+    it 'adjusts fluidity based on form' do
+      droplet.shift_form!(:liquid)
+      expect(droplet.fluidity).to eq(0.9)
+    end
+
+    it 'sets low fluidity for pool form' do
+      droplet.shift_form!(:pool)
+      expect(droplet.fluidity).to eq(0.3)
+    end
+
+    it 'returns self for chaining' do
+      expect(droplet.shift_form!(:bead)).to be(droplet)
+    end
+
+    it 'raises ArgumentError for invalid form' do
+      expect { droplet.shift_form!(:fog) }.to raise_error(ArgumentError, /invalid form/)
+    end
+  end
+
+  describe '#merge!' do
+    let(:other) { described_class.new(form: :liquid, content: 'other', mass: 0.4) }
+
+    it 'combines mass with coalescence bonus' do
+      bonus         = Legion::Extensions::Agentic::Defense::Quicksilver::Helpers::Constants::COALESCENCE_BONUS
+      original_mass = droplet.mass
+      droplet.merge!(other)
+      expected = [original_mass + other.mass + bonus, 1.0].min
+      expect(droplet.mass).to be_within(0.001).of(expected)
+    end
+
+    it 'clamps merged mass to 1.0' do
+      heavy_a = described_class.new(form: :pool, content: 'a', mass: 0.7)
+      heavy_b = described_class.new(form: :pool, content: 'b', mass: 0.7)
+      heavy_a.merge!(heavy_b)
+      expect(heavy_a.mass).to eq(1.0)
+    end
+
+    it 'returns self for chaining' do
+      expect(droplet.merge!(other)).to be(droplet)
+    end
+
+    it 'averages fluidity' do
+      original_fluidity = droplet.fluidity
+      expected_fluidity = (original_fluidity + other.fluidity) / 2.0
+      droplet.merge!(other)
+      expect(droplet.fluidity).to be_within(0.001).of(expected_fluidity)
+    end
+  end
+
+  describe '#split!' do
+    context 'when mass is sufficient (> 0.2)' do
+      let(:heavy_droplet) { described_class.new(form: :droplet, content: 'big idea', mass: 0.6) }
+
+      it 'returns a twin droplet' do
+        twin = heavy_droplet.split!
+        expect(twin).to be_a(described_class)
+      end
+
+      it 'halves the original mass' do
+        heavy_droplet.split!
+        expect(heavy_droplet.mass).to be_within(0.001).of(0.3)
+      end
+
+      it 'twin has half the original mass' do
+        original_mass = heavy_droplet.mass
+        twin = heavy_droplet.split!
+        expect(twin.mass).to be_within(0.001).of(original_mass / 2.0)
+      end
+
+      it 'twin has a different id' do
+        twin = heavy_droplet.split!
+        expect(twin.id).not_to eq(heavy_droplet.id)
+      end
+
+      it 'twin inherits form and surface' do
+        twin = heavy_droplet.split!
+        expect(twin.form).to eq(heavy_droplet.form)
+        expect(twin.surface).to eq(heavy_droplet.surface)
+      end
+    end
+
+    context 'when mass is too small (<= 0.2)' do
+      let(:tiny_droplet) { described_class.new(form: :bead, content: 'tiny', mass: 0.15) }
+
+      it 'returns nil' do
+        expect(tiny_droplet.split!).to be_nil
+      end
+
+      it 'does not change the mass' do
+        original = tiny_droplet.mass
+        tiny_droplet.split!
+        expect(tiny_droplet.mass).to eq(original)
+      end
+    end
+  end
+
+  describe '#capture!' do
+    it 'sets captured to true' do
+      droplet.capture!
+      expect(droplet.captured).to be true
+    end
+
+    it 'halves the fluidity' do
+      original_fluidity = droplet.fluidity
+      droplet.capture!
+      expect(droplet.fluidity).to be_within(0.001).of(original_fluidity / 2.0)
+    end
+
+    it 'returns self' do
+      expect(droplet.capture!).to be(droplet)
+    end
+  end
+
+  describe '#release!' do
+    before { droplet.capture! }
+
+    it 'sets captured to false' do
+      droplet.release!
+      expect(droplet.captured).to be false
+    end
+
+    it 'restores fluidity (doubles it, clamped)' do
+      fluidity_after_capture = droplet.fluidity
+      droplet.release!
+      expect(droplet.fluidity).to be_within(0.001).of([fluidity_after_capture * 2.0, 1.0].min)
+    end
+
+    it 'returns self' do
+      expect(droplet.release!).to be(droplet)
+    end
+  end
+
+  describe '#evaporate!' do
+    it 'reduces mass by EVAPORATION_RATE' do
+      original_mass = droplet.mass
+      droplet.evaporate!
+      expected = original_mass - Legion::Extensions::Agentic::Defense::Quicksilver::Helpers::Constants::EVAPORATION_RATE
+      expect(droplet.mass).to be_within(0.001).of(expected)
+    end
+
+    it 'does not go below 0.0' do
+      tiny = described_class.new(form: :bead, content: 'x', mass: 0.01)
+      tiny.evaporate!
+      expect(tiny.mass).to be >= 0.0
+    end
+
+    it 'returns self' do
+      expect(droplet.evaporate!).to be(droplet)
+    end
+  end
+
+  describe '#elusive?' do
+    it 'returns true when fluidity >= 0.7 and not captured' do
+      d = described_class.new(form: :liquid, content: 'elusive', fluidity: 0.8)
+      expect(d.elusive?).to be true
+    end
+
+    it 'returns false when captured' do
+      droplet.capture!
+      expect(droplet.elusive?).to be false
+    end
+
+    it 'returns false when fluidity < 0.7' do
+      d = described_class.new(form: :pool, content: 'slow', fluidity: 0.3)
+      expect(d.elusive?).to be false
+    end
+  end
+
+  describe '#stable?' do
+    it 'returns true when captured' do
+      droplet.capture!
+      expect(droplet.stable?).to be true
+    end
+
+    it 'returns true when fluidity < 0.4' do
+      d = described_class.new(form: :pool, content: 'stable', fluidity: 0.2)
+      expect(d.stable?).to be true
+    end
+
+    it 'returns false for default high-fluidity uncaptured droplet' do
+      d = described_class.new(form: :liquid, content: 'free', fluidity: 0.8)
+      expect(d.stable?).to be false
+    end
+  end
+
+  describe '#vanishing?' do
+    it 'returns true when mass < 0.1' do
+      d = described_class.new(form: :bead, content: 'fading', mass: 0.05)
+      expect(d.vanishing?).to be true
+    end
+
+    it 'returns false for normal mass' do
+      expect(droplet.vanishing?).to be false
+    end
+  end
+
+  describe '#cohesion_label' do
+    it 'returns a symbol' do
+      expect(droplet.cohesion_label).to be_a(Symbol)
+    end
+
+    it 'returns :unified for mass 1.0' do
+      d = described_class.new(form: :pool, content: 'x', mass: 1.0)
+      expect(d.cohesion_label).to eq(:unified)
+    end
+
+    it 'returns :atomized for mass near 0.0' do
+      d = described_class.new(form: :bead, content: 'x', mass: 0.05)
+      expect(d.cohesion_label).to eq(:atomized)
+    end
+  end
+
+  describe '#fluidity_label' do
+    it 'returns a symbol' do
+      expect(droplet.fluidity_label).to be_a(Symbol)
+    end
+
+    it 'returns :liquid for fluidity 0.9' do
+      d = described_class.new(form: :liquid, content: 'x', fluidity: 0.9)
+      expect(d.fluidity_label).to eq(:liquid)
+    end
+
+    it 'returns :solid for fluidity 0.1' do
+      d = described_class.new(form: :bead, content: 'x', fluidity: 0.1)
+      expect(d.fluidity_label).to eq(:solid)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with all expected keys' do
+      h = droplet.to_h
+      expect(h.keys).to include(:id, :form, :content, :mass, :fluidity, :surface, :captured,
+                                :elusive, :stable, :vanishing, :cohesion, :fluidity_lbl, :created_at)
+    end
+
+    it 'id matches droplet id' do
+      expect(droplet.to_h[:id]).to eq(droplet.id)
+    end
+
+    it 'reflects captured state' do
+      droplet.capture!
+      expect(droplet.to_h[:captured]).to be true
+    end
+  end
+end