lex-agentic-attention 0.1.0

data/spec/legion/extensions/agentic/attention/lighthouse/helpers/constants_spec.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Lighthouse::Helpers::Constants do
+  describe 'BEACON_TYPES' do
+    it 'contains expected types' do
+      expect(described_class::BEACON_TYPES).to include(:truth, :clarity, :warning, :guidance, :hope)
+    end
+
+    it 'is frozen' do
+      expect(described_class::BEACON_TYPES).to be_frozen
+    end
+  end
+
+  describe 'FOG_TYPES' do
+    it 'contains expected types' do
+      expect(described_class::FOG_TYPES).to include(:confusion, :uncertainty, :ambiguity, :doubt, :overwhelm)
+    end
+
+    it 'is frozen' do
+      expect(described_class::FOG_TYPES).to be_frozen
+    end
+  end
+
+  describe 'capacity constants' do
+    it 'MAX_BEACONS is positive' do
+      expect(described_class::MAX_BEACONS).to be > 0
+    end
+
+    it 'MAX_FOG_BANKS is positive' do
+      expect(described_class::MAX_FOG_BANKS).to be > 0
+    end
+  end
+
+  describe 'rate constants' do
+    it 'LUMINOSITY_RATE is between 0 and 1' do
+      expect(described_class::LUMINOSITY_RATE).to be > 0
+      expect(described_class::LUMINOSITY_RATE).to be < 1
+    end
+
+    it 'FOG_DENSITY_RATE is between 0 and 1' do
+      expect(described_class::FOG_DENSITY_RATE).to be > 0
+      expect(described_class::FOG_DENSITY_RATE).to be < 1
+    end
+  end
+
+  describe 'VISIBILITY_LABELS' do
+    it 'covers full [0, 1] range' do
+      expect(described_class::VISIBILITY_LABELS).not_to be_empty
+    end
+
+    it 'includes :crystal_clear and :blind' do
+      labels = described_class::VISIBILITY_LABELS.map(&:last)
+      expect(labels).to include(:crystal_clear, :blind)
+    end
+  end
+
+  describe 'LUMINOSITY_LABELS' do
+    it 'includes :blazing and :dark' do
+      labels = described_class::LUMINOSITY_LABELS.map(&:last)
+      expect(labels).to include(:blazing, :dark)
+    end
+  end
+
+  describe '.label_for' do
+    it 'returns crystal_clear for density 0.0' do
+      expect(described_class.label_for(described_class::VISIBILITY_LABELS, 0.0)).to eq(:crystal_clear)
+    end
+
+    it 'returns blind for density 1.0' do
+      expect(described_class.label_for(described_class::VISIBILITY_LABELS, 1.0)).to eq(:blind)
+    end
+
+    it 'returns blazing for luminosity 1.0' do
+      expect(described_class.label_for(described_class::LUMINOSITY_LABELS, 1.0)).to eq(:blazing)
+    end
+
+    it 'returns dark for luminosity 0.0' do
+      expect(described_class.label_for(described_class::LUMINOSITY_LABELS, 0.0)).to eq(:dark)
+    end
+
+    it 'returns steady for mid-range luminosity' do
+      expect(described_class.label_for(described_class::LUMINOSITY_LABELS, 0.6)).to eq(:steady)
+    end
+
+    it 'returns foggy for mid-range density' do
+      expect(described_class.label_for(described_class::VISIBILITY_LABELS, 0.6)).to eq(:foggy)
+    end
+
+    it 'falls back to last label for out-of-range values' do
+      result = described_class.label_for(described_class::LUMINOSITY_LABELS, 2.0)
+      expect(result).to be_a(Symbol)
+    end
+  end
+end

data/spec/legion/extensions/agentic/attention/lighthouse/helpers/fog_spec.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Lighthouse::Helpers::Fog do
+  subject(:fog) { described_class.new(fog_type: :confusion, domain: 'decision', density: 0.5) }
+
+  describe '#initialize' do
+    it 'sets fog_type as symbol' do
+      expect(fog.fog_type).to eq(:confusion)
+    end
+
+    it 'sets domain as string' do
+      expect(fog.domain).to eq('decision')
+    end
+
+    it 'sets density' do
+      expect(fog.density).to be_within(0.001).of(0.5)
+    end
+
+    it 'defaults density to 0.5' do
+      f = described_class.new(fog_type: :doubt, domain: 'x')
+      expect(f.density).to be_within(0.001).of(0.5)
+    end
+
+    it 'defaults extent to 1.0' do
+      f = described_class.new(fog_type: :doubt, domain: 'x')
+      expect(f.extent).to be_within(0.001).of(1.0)
+    end
+
+    it 'assigns a UUID id' do
+      expect(fog.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets formed_at timestamp' do
+      expect(fog.formed_at).to be_a(Time)
+    end
+
+    it 'clamps density to [0, 1]' do
+      f = described_class.new(fog_type: :doubt, domain: 'x', density: 1.5)
+      expect(f.density).to eq(1.0)
+    end
+
+    it 'raises for unknown fog_type' do
+      expect do
+        described_class.new(fog_type: :sunshine, domain: 'x')
+      end.to raise_error(ArgumentError, /unknown fog_type/)
+    end
+
+    it 'accepts all valid fog types' do
+      Legion::Extensions::Agentic::Attention::Lighthouse::Helpers::Constants::FOG_TYPES.each do |type|
+        expect do
+          described_class.new(fog_type: type, domain: 'test')
+        end.not_to raise_error
+      end
+    end
+  end
+
+  describe '#thicken!' do
+    it 'increases density by default rate' do
+      fog.density = 0.5
+      fog.thicken!
+      expect(fog.density).to be_within(0.001).of(0.55)
+    end
+
+    it 'accepts custom rate' do
+      fog.density = 0.5
+      fog.thicken!(rate: 0.2)
+      expect(fog.density).to be_within(0.001).of(0.7)
+    end
+
+    it 'clamps at 1.0' do
+      fog.density = 0.98
+      fog.thicken!(rate: 0.05)
+      expect(fog.density).to eq(1.0)
+    end
+
+    it 'returns self for chaining' do
+      expect(fog.thicken!).to eq(fog)
+    end
+  end
+
+  describe '#disperse!' do
+    it 'decreases density by default rate' do
+      fog.density = 0.5
+      fog.disperse!
+      expect(fog.density).to be_within(0.001).of(0.45)
+    end
+
+    it 'accepts custom rate' do
+      fog.density = 0.5
+      fog.disperse!(rate: 0.3)
+      expect(fog.density).to be_within(0.001).of(0.2)
+    end
+
+    it 'clamps at 0.0' do
+      fog.density = 0.03
+      fog.disperse!(rate: 0.05)
+      expect(fog.density).to eq(0.0)
+    end
+
+    it 'returns self for chaining' do
+      expect(fog.disperse!).to eq(fog)
+    end
+  end
+
+  describe '#impenetrable?' do
+    it 'returns false when density < 1.0' do
+      fog.density = 0.9
+      expect(fog.impenetrable?).to be false
+    end
+
+    it 'returns true when density is 1.0' do
+      fog.density = 1.0
+      expect(fog.impenetrable?).to be true
+    end
+  end
+
+  describe '#clearing?' do
+    it 'returns false when density >= 0.2' do
+      fog.density = 0.5
+      expect(fog.clearing?).to be false
+    end
+
+    it 'returns true when density < 0.2' do
+      fog.density = 0.1
+      expect(fog.clearing?).to be true
+    end
+  end
+
+  describe '#visibility_label' do
+    it 'returns a symbol' do
+      expect(fog.visibility_label).to be_a(Symbol)
+    end
+
+    it 'returns :blind for max density' do
+      fog.density = 1.0
+      expect(fog.visibility_label).to eq(:blind)
+    end
+
+    it 'returns :crystal_clear for zero density' do
+      fog.density = 0.0
+      expect(fog.visibility_label).to eq(:crystal_clear)
+    end
+
+    it 'returns :foggy for mid-range density' do
+      fog.density = 0.6
+      expect(fog.visibility_label).to eq(:foggy)
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes expected keys' do
+      h = fog.to_h
+      %i[id fog_type domain density extent visibility_label impenetrable clearing formed_at].each do |k|
+        expect(h).to have_key(k)
+      end
+    end
+
+    it 'fog_type matches' do
+      expect(fog.to_h[:fog_type]).to eq(:confusion)
+    end
+
+    it 'clearing is boolean' do
+      expect(fog.to_h[:clearing]).to be(false).or be(true)
+    end
+  end
+end

data/spec/legion/extensions/agentic/attention/lighthouse/helpers/lighthouse_engine_spec.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Lighthouse::Helpers::LighthouseEngine do
+  subject(:engine) { described_class.new }
+
+  let(:mod) { Legion::Extensions::Agentic::Attention::Lighthouse }
+
+  describe '#light_beacon' do
+    it 'creates and returns a beacon' do
+      b = engine.light_beacon(beacon_type: :truth, domain: 'logic', content: 'clarity first')
+      expect(b).to be_a(mod::Helpers::Beacon)
+    end
+
+    it 'stores the beacon internally' do
+      engine.light_beacon(beacon_type: :hope, domain: 'x', content: 'y')
+      expect(engine.all_beacons.size).to eq(1)
+    end
+
+    it 'accepts luminosity override' do
+      b = engine.light_beacon(beacon_type: :truth, domain: 'x', content: 'y', luminosity: 0.9)
+      expect(b.luminosity).to be_within(0.001).of(0.9)
+    end
+
+    it 'accepts sweep_angle override' do
+      b = engine.light_beacon(beacon_type: :clarity, domain: 'x', content: 'y', sweep_angle: 180.0)
+      expect(b.sweep_angle).to be_within(0.001).of(180.0)
+    end
+
+    it 'raises when too many beacons' do
+      stub_const('Legion::Extensions::Agentic::Attention::Lighthouse::Helpers::Constants::MAX_BEACONS', 1)
+      engine.light_beacon(beacon_type: :truth, domain: 'a', content: 'first')
+      expect do
+        engine.light_beacon(beacon_type: :hope, domain: 'b', content: 'second')
+      end.to raise_error(ArgumentError, /too many beacons/)
+    end
+
+    it 'raises for invalid beacon_type' do
+      expect do
+        engine.light_beacon(beacon_type: :mirage, domain: 'x', content: 'y')
+      end.to raise_error(ArgumentError)
+    end
+  end
+
+  describe '#create_fog' do
+    it 'creates and returns a fog bank' do
+      f = engine.create_fog(fog_type: :confusion, domain: 'planning')
+      expect(f).to be_a(mod::Helpers::Fog)
+    end
+
+    it 'stores the fog bank internally' do
+      engine.create_fog(fog_type: :doubt, domain: 'x')
+      expect(engine.all_fog_banks.size).to eq(1)
+    end
+
+    it 'accepts density override' do
+      f = engine.create_fog(fog_type: :ambiguity, domain: 'x', density: 0.8)
+      expect(f.density).to be_within(0.001).of(0.8)
+    end
+
+    it 'raises when too many fog banks' do
+      stub_const('Legion::Extensions::Agentic::Attention::Lighthouse::Helpers::Constants::MAX_FOG_BANKS', 1)
+      engine.create_fog(fog_type: :confusion, domain: 'a')
+      expect do
+        engine.create_fog(fog_type: :doubt, domain: 'b')
+      end.to raise_error(ArgumentError, /too many fog banks/)
+    end
+
+    it 'raises for invalid fog_type' do
+      expect do
+        engine.create_fog(fog_type: :sunshine, domain: 'x')
+      end.to raise_error(ArgumentError)
+    end
+  end
+
+  describe '#sweep' do
+    let(:beacon) { engine.light_beacon(beacon_type: :truth, domain: 'x', content: 'y', luminosity: 0.8) }
+    let(:fog)    { engine.create_fog(fog_type: :confusion, domain: 'x', density: 0.8) }
+
+    it 'reduces fog density' do
+      old_density = fog.density
+      engine.sweep(beacon_id: beacon.id, fog_id: fog.id)
+      expect(fog.density).to be < old_density
+    end
+
+    it 'returns reduction amount' do
+      result = engine.sweep(beacon_id: beacon.id, fog_id: fog.id)
+      expect(result[:reduction]).to be > 0
+    end
+
+    it 'returns beacon and fog hashes' do
+      result = engine.sweep(beacon_id: beacon.id, fog_id: fog.id)
+      expect(result[:beacon]).to have_key(:id)
+      expect(result[:fog]).to have_key(:id)
+    end
+
+    it 'raises for unknown beacon' do
+      engine.create_fog(fog_type: :doubt, domain: 'x')
+      expect { engine.sweep(beacon_id: 'nope', fog_id: fog.id) }
+        .to raise_error(ArgumentError, /beacon not found/)
+    end
+
+    it 'raises for unknown fog' do
+      expect { engine.sweep(beacon_id: beacon.id, fog_id: 'nope') }
+        .to raise_error(ArgumentError, /fog bank not found/)
+    end
+
+    it 'brighter beacons cause larger reductions' do
+      bright = engine.light_beacon(beacon_type: :truth, domain: 'x', content: 'y', luminosity: 1.0)
+      dim    = engine.light_beacon(beacon_type: :truth, domain: 'x', content: 'y', luminosity: 0.2)
+      fog1   = engine.create_fog(fog_type: :confusion, domain: 'a', density: 0.8)
+      fog2   = engine.create_fog(fog_type: :confusion, domain: 'b', density: 0.8)
+
+      result_bright = engine.sweep(beacon_id: bright.id, fog_id: fog1.id)
+      result_dim    = engine.sweep(beacon_id: dim.id, fog_id: fog2.id)
+      expect(result_bright[:reduction]).to be > result_dim[:reduction]
+    end
+  end
+
+  describe '#dim_all!' do
+    it 'dims all beacons' do
+      b = engine.light_beacon(beacon_type: :truth, domain: 'x', content: 'y', luminosity: 0.5)
+      old_lum = b.luminosity
+      engine.dim_all!
+      expect(b.luminosity).to be < old_lum
+    end
+
+    it 'prunes extinguished beacons' do
+      engine.light_beacon(beacon_type: :truth, domain: 'x', content: 'y', luminosity: 0.05)
+      result = engine.dim_all!(rate: 0.1)
+      expect(result[:pruned]).to be >= 1
+    end
+
+    it 'returns remaining and pruned counts' do
+      engine.light_beacon(beacon_type: :hope, domain: 'x', content: 'y', luminosity: 0.8)
+      result = engine.dim_all!
+      expect(result).to have_key(:remaining)
+      expect(result).to have_key(:pruned)
+    end
+  end
+
+  describe '#thicken_all!' do
+    it 'thickens all fog banks' do
+      f = engine.create_fog(fog_type: :doubt, domain: 'x', density: 0.3)
+      old_density = f.density
+      engine.thicken_all!
+      expect(f.density).to be > old_density
+    end
+
+    it 'returns fog bank count' do
+      engine.create_fog(fog_type: :confusion, domain: 'x')
+      result = engine.thicken_all!
+      expect(result[:fog_banks]).to eq(1)
+    end
+  end
+
+  describe '#brightest_beacons' do
+    it 'returns sorted by luminosity descending' do
+      engine.light_beacon(beacon_type: :truth, domain: 'x', content: 'a', luminosity: 0.3)
+      engine.light_beacon(beacon_type: :hope, domain: 'y', content: 'b', luminosity: 0.9)
+      engine.light_beacon(beacon_type: :clarity, domain: 'z', content: 'c', luminosity: 0.6)
+      result = engine.brightest_beacons
+      expect(result.first.luminosity).to be >= result.last.luminosity
+    end
+
+    it 'respects limit' do
+      3.times { |i| engine.light_beacon(beacon_type: :truth, domain: "d#{i}", content: "c#{i}") }
+      expect(engine.brightest_beacons(limit: 2).size).to eq(2)
+    end
+
+    it 'excludes extinguished beacons' do
+      b = engine.light_beacon(beacon_type: :truth, domain: 'x', content: 'y', luminosity: 0.0)
+      results = engine.brightest_beacons
+      expect(results).not_to include(b)
+    end
+  end
+
+  describe '#densest_fogs' do
+    it 'returns sorted by density descending' do
+      engine.create_fog(fog_type: :confusion, domain: 'a', density: 0.2)
+      engine.create_fog(fog_type: :doubt, domain: 'b', density: 0.9)
+      result = engine.densest_fogs
+      expect(result.first.density).to be >= result.last.density
+    end
+
+    it 'respects limit' do
+      3.times { |i| engine.create_fog(fog_type: :ambiguity, domain: "d#{i}") }
+      expect(engine.densest_fogs(limit: 2).size).to eq(2)
+    end
+  end
+
+  describe '#visibility_report' do
+    it 'returns comprehensive report hash' do
+      engine.light_beacon(beacon_type: :truth, domain: 'x', content: 'y')
+      engine.create_fog(fog_type: :confusion, domain: 'x')
+      report = engine.visibility_report
+      %i[total_beacons total_fog_banks avg_luminosity avg_density
+         net_visibility blazing_beacons extinguished impenetrable_fog clearing_fog].each do |k|
+        expect(report).to have_key(k)
+      end
+    end
+
+    it 'returns zeros with empty engine' do
+      report = engine.visibility_report
+      expect(report[:total_beacons]).to eq(0)
+      expect(report[:total_fog_banks]).to eq(0)
+      expect(report[:avg_luminosity]).to eq(0.0)
+      expect(report[:avg_density]).to eq(0.0)
+    end
+
+    it 'net_visibility is clamped to [0, 1]' do
+      engine.light_beacon(beacon_type: :hope, domain: 'x', content: 'y', luminosity: 1.0)
+      report = engine.visibility_report
+      expect(report[:net_visibility]).to be >= 0.0
+      expect(report[:net_visibility]).to be <= 1.0
+    end
+
+    it 'counts blazing beacons' do
+      engine.light_beacon(beacon_type: :truth, domain: 'x', content: 'y', luminosity: 0.95)
+      expect(engine.visibility_report[:blazing_beacons]).to eq(1)
+    end
+  end
+
+  describe '#all_beacons' do
+    it 'returns all beacon objects' do
+      engine.light_beacon(beacon_type: :truth, domain: 'a', content: 'x')
+      engine.light_beacon(beacon_type: :hope, domain: 'b', content: 'y')
+      expect(engine.all_beacons.size).to eq(2)
+    end
+  end
+
+  describe '#all_fog_banks' do
+    it 'returns all fog bank objects' do
+      engine.create_fog(fog_type: :confusion, domain: 'a')
+      engine.create_fog(fog_type: :doubt, domain: 'b')
+      expect(engine.all_fog_banks.size).to eq(2)
+    end
+  end
+end

data/spec/legion/extensions/agentic/attention/lighthouse/runners/cognitive_lighthouse_spec.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Lighthouse::Runners::CognitiveLighthouse do
+  let(:engine) { Legion::Extensions::Agentic::Attention::Lighthouse::Helpers::LighthouseEngine.new }
+
+  describe '.light_beacon' do
+    it 'returns success with beacon hash' do
+      result = described_class.light_beacon(
+        beacon_type: :truth, domain: 'logic', content: 'north star', engine: engine
+      )
+      expect(result[:success]).to be true
+      expect(result[:beacon][:beacon_type]).to eq(:truth)
+    end
+
+    it 'returns failure for invalid beacon_type' do
+      result = described_class.light_beacon(
+        beacon_type: :mirage, domain: 'x', content: 'y', engine: engine
+      )
+      expect(result[:success]).to be false
+      expect(result[:error]).to be_a(String)
+    end
+
+    it 'passes luminosity to engine' do
+      result = described_class.light_beacon(
+        beacon_type: :hope, domain: 'x', content: 'y', luminosity: 0.9, engine: engine
+      )
+      expect(result[:beacon][:luminosity]).to be_within(0.001).of(0.9)
+    end
+
+    it 'passes sweep_angle to engine' do
+      result = described_class.light_beacon(
+        beacon_type: :clarity, domain: 'x', content: 'y', sweep_angle: 90.0, engine: engine
+      )
+      expect(result[:beacon][:sweep_angle]).to be_within(0.001).of(90.0)
+    end
+
+    it 'ignores extra kwargs via ** splat' do
+      expect do
+        described_class.light_beacon(
+          beacon_type: :truth, domain: 'x', content: 'y',
+          engine: engine, extra_key: 'ignored'
+        )
+      end.not_to raise_error
+    end
+  end
+
+  describe '.create_fog' do
+    it 'returns success with fog hash' do
+      result = described_class.create_fog(
+        fog_type: :confusion, domain: 'decision', engine: engine
+      )
+      expect(result[:success]).to be true
+      expect(result[:fog][:fog_type]).to eq(:confusion)
+    end
+
+    it 'returns failure for invalid fog_type' do
+      result = described_class.create_fog(
+        fog_type: :sunshine, domain: 'x', engine: engine
+      )
+      expect(result[:success]).to be false
+    end
+
+    it 'passes density to engine' do
+      result = described_class.create_fog(
+        fog_type: :doubt, domain: 'x', density: 0.3, engine: engine
+      )
+      expect(result[:fog][:density]).to be_within(0.001).of(0.3)
+    end
+
+    it 'passes extent to engine' do
+      result = described_class.create_fog(
+        fog_type: :ambiguity, domain: 'x', extent: 0.7, engine: engine
+      )
+      expect(result[:fog][:extent]).to be_within(0.001).of(0.7)
+    end
+
+    it 'ignores extra kwargs via ** splat' do
+      expect do
+        described_class.create_fog(
+          fog_type: :confusion, domain: 'x', engine: engine, unexpected: true
+        )
+      end.not_to raise_error
+    end
+  end
+
+  describe '.sweep' do
+    let(:beacon) do
+      engine.light_beacon(beacon_type: :truth, domain: 'x', content: 'y', luminosity: 0.8)
+    end
+    let(:fog) { engine.create_fog(fog_type: :confusion, domain: 'x', density: 0.8) }
+
+    it 'returns success with beacon, fog, and reduction' do
+      result = described_class.sweep(beacon_id: beacon.id, fog_id: fog.id, engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:beacon]).to have_key(:id)
+      expect(result[:fog]).to have_key(:id)
+      expect(result[:reduction]).to be > 0
+    end
+
+    it 'returns failure for unknown beacon' do
+      result = described_class.sweep(beacon_id: 'nope', fog_id: fog.id, engine: engine)
+      expect(result[:success]).to be false
+    end
+
+    it 'returns failure for unknown fog' do
+      result = described_class.sweep(beacon_id: beacon.id, fog_id: 'nope', engine: engine)
+      expect(result[:success]).to be false
+    end
+
+    it 'ignores extra kwargs' do
+      expect do
+        described_class.sweep(beacon_id: beacon.id, fog_id: fog.id,
+                              engine: engine, extra: true)
+      end.not_to raise_error
+    end
+  end
+
+  describe '.list_beacons' do
+    before do
+      engine.light_beacon(beacon_type: :truth, domain: 'alpha', content: 'a')
+      engine.light_beacon(beacon_type: :hope, domain: 'beta', content: 'b')
+      engine.light_beacon(beacon_type: :truth, domain: 'gamma', content: 'c')
+    end
+
+    it 'returns all beacons when no filters' do
+      result = described_class.list_beacons(engine: engine)
+      expect(result[:count]).to eq(3)
+    end
+
+    it 'filters by domain' do
+      result = described_class.list_beacons(engine: engine, domain: 'alpha')
+      expect(result[:count]).to eq(1)
+      expect(result[:beacons].first[:domain]).to eq('alpha')
+    end
+
+    it 'filters by beacon_type' do
+      result = described_class.list_beacons(engine: engine, beacon_type: :truth)
+      expect(result[:count]).to eq(2)
+    end
+
+    it 'returns success' do
+      result = described_class.list_beacons(engine: engine)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns beacons as array of hashes' do
+      result = described_class.list_beacons(engine: engine)
+      expect(result[:beacons]).to be_an(Array)
+      expect(result[:beacons].first).to have_key(:id)
+    end
+  end
+
+  describe '.navigation_status' do
+    it 'returns success with report' do
+      result = described_class.navigation_status(engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:report]).to have_key(:net_visibility)
+    end
+
+    it 'includes all report keys' do
+      engine.light_beacon(beacon_type: :truth, domain: 'x', content: 'y')
+      engine.create_fog(fog_type: :confusion, domain: 'x')
+      result = described_class.navigation_status(engine: engine)
+      %i[total_beacons total_fog_banks avg_luminosity avg_density net_visibility].each do |k|
+        expect(result[:report]).to have_key(k)
+      end
+    end
+
+    it 'ignores extra kwargs' do
+      expect do
+        described_class.navigation_status(engine: engine, extra_param: 'x')
+      end.not_to raise_error
+    end
+  end
+
+  describe 'default engine (module-level state)' do
+    it 'uses a default engine when none provided' do
+      result = described_class.navigation_status
+      expect(result[:success]).to be true
+    end
+  end
+end