lex-cognitive-lighthouse 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7f54885694491e600f6aee8f9b1e3457bb8919ee8a8cc6161139038c7997abdb
+  data.tar.gz: f834c005573627c985321c9c27a31853bc124ebf7d354a3dce8a779671536c37
+SHA512:
+  metadata.gz: 860f2ba190a71695e20be6d7583008a7978ccd564bedb4623e81011434b50d8eb20d1ac02367dd2f653ffcee740bb9d3d94a0c94daeab65529cedc1bade4b5aa
+  data.tar.gz: 3e7c288083585b04cb5e3f7ed7be3979d26e76b168c14cf8c79a93ab0e3e9eafe472ea8edeab3e755b5243eb4cb6d1ac62445e848b380f20033495e2adbae157

data/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ci:
+    uses: LegionIO/.github/.github/workflows/ci.yml@main
+
+  release:
+    needs: ci
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    uses: LegionIO/.github/.github/workflows/release.yml@main
+    secrets:
+      rubygems-api-key: ${{ secrets.RUBYGEMS_API_KEY }}

data/.gitignore

@@ -0,0 +1,2 @@
+.rspec_status
+Gemfile.lock

data/.rspec

@@ -0,0 +1,2 @@
+--require spec_helper
+--format documentation

data/.rubocop.yml

@@ -0,0 +1,37 @@
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.4
+
+Style/Documentation:
+  Enabled: false
+
+Naming/PredicateMethod:
+  Enabled: false
+
+Naming/PredicatePrefix:
+  Enabled: false
+
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/MethodLength:
+  Max: 25
+
+Metrics/AbcSize:
+  Max: 25
+
+Metrics/ParameterLists:
+  Max: 8
+  MaxOptionalParameters: 8
+
+Layout/HashAlignment:
+  EnforcedColonStyle: table
+  EnforcedHashRocketStyle: table
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+
+Style/OneClassPerFile:
+  Exclude:
+    - 'spec/spec_helper.rb'

data/CLAUDE.md

@@ -0,0 +1,107 @@
+# lex-cognitive-lighthouse
+
+**Level 3 Leaf Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/extensions-agentic/CLAUDE.md`
+
+## Purpose
+
+Beacon and fog metaphor for navigational clarity in cognitive processing. Beacons represent sources of truth, clarity, warning, guidance, and hope — each with a luminosity level. Fog banks represent confusion, uncertainty, ambiguity, doubt, and overwhelm — each with a density level. The sweep operation actively disperses fog using beacon luminosity, modeling how clarity-producing cognition reduces confusion.
+
+## Gem Info
+
+- **Gem name**: `lex-cognitive-lighthouse`
+- **Module**: `Legion::Extensions::CognitiveLighthouse`
+- **Version**: `0.1.0`
+- **Ruby**: `>= 3.4`
+- **License**: MIT
+
+## File Structure
+
+```
+lib/legion/extensions/cognitive_lighthouse/
+  version.rb
+  client.rb
+  helpers/
+    constants.rb
+    beacon.rb
+    fog.rb
+    lighthouse_engine.rb
+  runners/
+    cognitive_lighthouse.rb
+```
+
+## Key Constants
+
+| Constant | Value | Purpose |
+|---|---|---|
+| `BEACON_TYPES` | `%i[truth clarity warning guidance hope]` | Valid beacon categories |
+| `FOG_TYPES` | `%i[confusion uncertainty ambiguity doubt overwhelm]` | Valid fog categories |
+| `MAX_BEACONS` | `100` | Per-engine beacon capacity |
+| `MAX_FOG_BANKS` | `50` | Per-engine fog capacity |
+| `LUMINOSITY_RATE` | `0.1` | Default brightness change per brighten/dim operation |
+| `FOG_DENSITY_RATE` | `0.05` | Default density change per thicken/disperse operation |
+| `VISIBILITY_LABELS` | range hash | From `:blind` to `:crystal_clear` |
+| `LUMINOSITY_LABELS` | range hash | From `:dark` to `:blazing` |
+
+## Helpers
+
+### `Helpers::Beacon`
+Emits light to cut through cognitive fog. Has `id`, `beacon_type`, `luminosity`, `domain`, `content`, and `created_at`.
+
+- `brighten!(rate)` — increases luminosity
+- `dim!(rate)` — decreases luminosity
+- `extinguished?` — luminosity at or below zero
+- `blazing?` — luminosity at maximum
+- `luminosity_label`
+- `to_h`
+
+### `Helpers::Fog`
+Represents a cloud of cognitive obscuration. Has `id`, `fog_type`, `density`, `domain`, `content`, and `created_at`.
+
+- `thicken!(rate)` — increases density
+- `disperse!(rate)` — decreases density
+- `impenetrable?` — density at maximum
+- `clearing?` — density below a low threshold
+- `visibility_label` — based on inverse of density
+- `to_h`
+
+### `Helpers::LighthouseEngine`
+Manages beacons and fog banks, enforces capacity limits.
+
+- `light_beacon(beacon_type:, luminosity:, domain:, content:)` → beacon or capacity error
+- `create_fog(fog_type:, density:, domain:, content:)` → fog or capacity error
+- `sweep` — for each beacon, disperses fog banks in the same domain; dispersion amount = `beacon.luminosity * 0.5`; extinguished beacons are pruned
+- `dim_all!(rate:)` — dims all beacons, prunes extinguished ones
+- `thicken_all!(rate:)` — thickens all fog banks
+- `brightest_beacons(limit:)` → top N by luminosity
+- `densest_fogs(limit:)` → top N by density
+- `visibility_report` → aggregate stats hash
+
+## Runners
+
+Module: `Runners::CognitiveLighthouse`
+
+| Runner Method | Description |
+|---|---|
+| `light_beacon(beacon_type:, luminosity:, domain:, content:)` | Create a new beacon |
+| `create_fog(fog_type:, density:, domain:, content:)` | Create a new fog bank |
+| `sweep` | Beacons disperse fog in matching domains |
+| `list_beacons(limit:)` | Brightest beacons |
+| `navigation_status` | Full visibility report |
+
+All runners return `{success: true/false, ...}` hashes.
+
+## Integration Points
+
+- No direct dependencies on other agentic LEX gems
+- Can integrate with `lex-tick` phase handlers: low overall visibility → switch to sentinel mode
+- Beacon luminosity can be boosted when `lex-emotion` valence is positive
+- Fog density can be increased on `lex-conflict` escalation events
+- `sweep` is the natural action for the agent's clarification-seeking behavior
+
+## Development Notes
+
+- `Client` instantiates `@lighthouse_engine = Helpers::LighthouseEngine.new`
+- `sweep` prunes beacons that become extinguished after dispersion calculations
+- Beacon and fog domains are matched for targeted dispersion — a `:truth` beacon only disperses fog in its own domain
+- `MAX_BEACONS = 100` and `MAX_FOG_BANKS = 50` are hard engine-level caps

data/Gemfile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+group :development, :test do
+  gem 'rspec', '~> 3.13'
+  gem 'rubocop', '~> 1.75'
+  gem 'rubocop-rspec'
+end
+
+gem 'legion-gaia', path: '../../legion-gaia'

data/Gemfile.lock

@@ -0,0 +1,78 @@
+PATH
+  remote: .
+  specs:
+    lex-cognitive-lighthouse (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.9)
+      public_suffix (>= 2.0.2, < 8.0)
+    ast (2.4.3)
+    bigdecimal (4.0.1)
+    diff-lcs (1.6.2)
+    json (2.19.1)
+    json-schema (6.2.0)
+      addressable (~> 2.8)
+      bigdecimal (>= 3.1, < 5)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    mcp (0.8.0)
+      json-schema (>= 4.1)
+    parallel (1.27.0)
+    parser (3.3.10.2)
+      ast (~> 2.4.1)
+      racc
+    prism (1.9.0)
+    public_suffix (7.0.5)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    regexp_parser (2.11.3)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    rubocop (1.85.1)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      mcp (~> 0.6)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-rspec (3.9.0)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.81)
+    ruby-progressbar (1.13.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+
+PLATFORMS
+  arm64-darwin-25
+  ruby
+
+DEPENDENCIES
+  lex-cognitive-lighthouse!
+  rspec (~> 3.13)
+  rubocop (~> 1.75)
+  rubocop-rspec
+
+BUNDLED WITH
+   2.6.9

data/README.md

@@ -0,0 +1,47 @@
+# lex-cognitive-lighthouse
+
+Beacon and fog navigation model for LegionIO cognitive agents. Beacons (truth, clarity, warning, guidance, hope) actively disperse fog banks (confusion, uncertainty, ambiguity, doubt, overwhelm) through sweep operations.
+
+## What It Does
+
+- Light beacons with luminosity levels to represent sources of cognitive clarity
+- Create fog banks with density levels to represent sources of cognitive obscuration
+- Run `sweep` to have beacons disperse fog in their matching domains
+- Track overall visibility across all fog banks
+- Monitor brightest beacons and densest fog clusters
+- Beacons that dim to zero are pruned automatically during sweep
+
+## Usage
+
+```ruby
+# Light a beacon
+runner.light_beacon(beacon_type: :clarity, luminosity: 0.8,
+                    domain: :reasoning, content: 'Root cause identified')
+
+# Create a fog bank
+runner.create_fog(fog_type: :uncertainty, density: 0.6,
+                  domain: :reasoning, content: 'Multiple conflicting hypotheses')
+
+# Sweep: beacons disperse fog in their domain
+runner.sweep
+# => { success: true, swept: 1, beacons_dimmed: 0, beacons_pruned: 0 }
+
+# Check navigation status
+runner.navigation_status
+# => { success: true, total_beacons: 1, total_fog_banks: 1, avg_luminosity: 0.8, avg_density: ..., ... }
+
+# List brightest beacons
+runner.list_beacons(limit: 5)
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-cognitive-lighthouse.gemspec

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_lighthouse/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-lighthouse'
+  spec.version       = Legion::Extensions::CognitiveLighthouse::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+  spec.license       = 'MIT'
+
+  spec.summary       = 'Cognitive lighthouse LEX — guiding beacons that cut through cognitive fog'
+  spec.description   = 'Models guiding beacons that periodically sweep their beam to illuminate areas ' \
+                       'of uncertainty, helping navigate complex decision spaces. Beacons can be steady ' \
+                       'or rotating, can dim in fog, and can guide other agents through ambiguity.'
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-lighthouse'
+
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri']      = spec.homepage
+  spec.metadata['source_code_uri']   = spec.homepage
+  spec.metadata['documentation_uri'] = "#{spec.homepage}#readme"
+  spec.metadata['changelog_uri']     = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata['bug_tracker_uri']   = "#{spec.homepage}/issues"
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(test|spec|features)/}) }
+  end
+
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

data/lib/legion/extensions/cognitive_lighthouse/client.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveLighthouse
+      class Client
+        include Runners::CognitiveLighthouse
+
+        def initialize(engine: nil, **)
+          @engine = engine || Helpers::LighthouseEngine.new
+        end
+
+        private
+
+        def default_engine
+          @engine
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_lighthouse/helpers/beacon.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveLighthouse
+      module Helpers
+        class Beacon
+          attr_reader :id, :beacon_type, :domain, :content, :sweep_angle, :lit_at
+          attr_accessor :luminosity
+
+          def initialize(beacon_type:, domain:, content:, luminosity: nil, sweep_angle: nil)
+            validate_beacon_type!(beacon_type)
+            @id          = SecureRandom.uuid
+            @beacon_type = beacon_type.to_sym
+            @domain      = domain.to_s
+            @content     = content.to_s
+            @luminosity  = (luminosity || 0.7).to_f.clamp(0.0, 1.0).round(10)
+            @sweep_angle = (sweep_angle || 0.0).to_f.clamp(0.0, 360.0).round(10)
+            @lit_at      = Time.now.utc
+          end
+
+          def brighten!(rate: Constants::LUMINOSITY_RATE)
+            @luminosity = (@luminosity + rate).clamp(0.0, 1.0).round(10)
+            self
+          end
+
+          def dim!(rate: Constants::LUMINOSITY_RATE)
+            @luminosity = (@luminosity - rate).clamp(0.0, 1.0).round(10)
+            self
+          end
+
+          def extinguished?
+            @luminosity <= 0.0
+          end
+
+          def blazing?
+            @luminosity >= 0.9
+          end
+
+          def luminosity_label
+            Constants.label_for(Constants::LUMINOSITY_LABELS, @luminosity)
+          end
+
+          def to_h
+            {
+              id:               @id,
+              beacon_type:      @beacon_type,
+              domain:           @domain,
+              content:          @content,
+              luminosity:       @luminosity,
+              sweep_angle:      @sweep_angle,
+              luminosity_label: luminosity_label,
+              extinguished:     extinguished?,
+              blazing:          blazing?,
+              lit_at:           @lit_at
+            }
+          end
+
+          private
+
+          def validate_beacon_type!(type)
+            sym = type.to_sym
+            return if Constants::BEACON_TYPES.include?(sym)
+
+            raise ArgumentError,
+                  "unknown beacon_type: #{type.inspect}; must be one of #{Constants::BEACON_TYPES.inspect}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_lighthouse/helpers/constants.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveLighthouse
+      module Helpers
+        module Constants
+          BEACON_TYPES = %i[truth clarity warning guidance hope].freeze
+          FOG_TYPES    = %i[confusion uncertainty ambiguity doubt overwhelm].freeze
+
+          MAX_BEACONS   = 100
+          MAX_FOG_BANKS = 50
+
+          LUMINOSITY_RATE   = 0.1
+          FOG_DENSITY_RATE  = 0.05
+
+          # Visibility labels (fog density: high density = low visibility)
+          VISIBILITY_LABELS = [
+            [(0.0...0.1), :crystal_clear],
+            [(0.1...0.3), :clear],
+            [(0.3...0.5), :hazy],
+            [(0.5...0.7), :foggy],
+            [(0.7...0.9), :dense_fog],
+            [(0.9..),     :blind]
+          ].freeze
+
+          # Luminosity labels (beacon luminosity: high = bright)
+          LUMINOSITY_LABELS = [
+            [(0.9..),      :blazing],
+            [(0.7...0.9),  :bright],
+            [(0.5...0.7),  :steady],
+            [(0.3...0.5),  :dim],
+            [(0.1...0.3),  :faint],
+            [(..0.1),      :dark]
+          ].freeze
+
+          def self.label_for(table, value)
+            table.each { |range, label| return label if range.cover?(value) }
+            table.last.last
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_lighthouse/helpers/fog.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveLighthouse
+      module Helpers
+        class Fog
+          attr_reader :id, :fog_type, :domain, :extent, :formed_at
+          attr_accessor :density
+
+          def initialize(fog_type:, domain:, density: nil, extent: nil)
+            validate_fog_type!(fog_type)
+            @id       = SecureRandom.uuid
+            @fog_type = fog_type.to_sym
+            @domain   = domain.to_s
+            @density  = (density || 0.5).to_f.clamp(0.0, 1.0).round(10)
+            @extent   = (extent || 1.0).to_f.clamp(0.0, 1.0).round(10)
+            @formed_at = Time.now.utc
+          end
+
+          def thicken!(rate: Constants::FOG_DENSITY_RATE)
+            @density = (@density + rate).clamp(0.0, 1.0).round(10)
+            self
+          end
+
+          def disperse!(rate: Constants::FOG_DENSITY_RATE)
+            @density = (@density - rate).clamp(0.0, 1.0).round(10)
+            self
+          end
+
+          def impenetrable?
+            @density >= 1.0
+          end
+
+          def clearing?
+            @density < 0.2
+          end
+
+          def visibility_label
+            Constants.label_for(Constants::VISIBILITY_LABELS, @density)
+          end
+
+          def to_h
+            {
+              id:               @id,
+              fog_type:         @fog_type,
+              domain:           @domain,
+              density:          @density,
+              extent:           @extent,
+              visibility_label: visibility_label,
+              impenetrable:     impenetrable?,
+              clearing:         clearing?,
+              formed_at:        @formed_at
+            }
+          end
+
+          private
+
+          def validate_fog_type!(type)
+            sym = type.to_sym
+            return if Constants::FOG_TYPES.include?(sym)
+
+            raise ArgumentError,
+                  "unknown fog_type: #{type.inspect}; must be one of #{Constants::FOG_TYPES.inspect}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_lighthouse/helpers/lighthouse_engine.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveLighthouse
+      module Helpers
+        class LighthouseEngine
+          def initialize
+            @beacons   = {}
+            @fog_banks = {}
+          end
+
+          def light_beacon(beacon_type:, domain:, content:, luminosity: nil, sweep_angle: nil)
+            raise ArgumentError, 'too many beacons' if @beacons.size >= Constants::MAX_BEACONS
+
+            beacon = Beacon.new(
+              beacon_type: beacon_type,
+              domain:      domain,
+              content:     content,
+              luminosity:  luminosity,
+              sweep_angle: sweep_angle
+            )
+            @beacons[beacon.id] = beacon
+            beacon
+          end
+
+          def create_fog(fog_type:, domain:, density: nil, extent: nil)
+            raise ArgumentError, 'too many fog banks' if @fog_banks.size >= Constants::MAX_FOG_BANKS
+
+            fog = Fog.new(fog_type: fog_type, domain: domain, density: density, extent: extent)
+            @fog_banks[fog.id] = fog
+            fog
+          end
+
+          def sweep(beacon_id:, fog_id:)
+            beacon = fetch_beacon(beacon_id)
+            fog    = fetch_fog(fog_id)
+
+            reduction = (beacon.luminosity * 0.5).round(10)
+            fog.disperse!(rate: reduction)
+
+            { beacon: beacon.to_h, fog: fog.to_h, reduction: reduction }
+          end
+
+          def dim_all!(rate: Constants::LUMINOSITY_RATE)
+            @beacons.each_value { |b| b.dim!(rate: rate) }
+            pruned = @beacons.select { |_, b| b.extinguished? }.keys
+            pruned.each { |id| @beacons.delete(id) }
+            { remaining: @beacons.size, pruned: pruned.size }
+          end
+
+          def thicken_all!(rate: Constants::FOG_DENSITY_RATE)
+            @fog_banks.each_value { |f| f.thicken!(rate: rate) }
+            { fog_banks: @fog_banks.size }
+          end
+
+          def brightest_beacons(limit: 5)
+            @beacons.values
+                    .reject(&:extinguished?)
+                    .sort_by { |b| -b.luminosity }
+                    .first(limit)
+          end
+
+          def densest_fogs(limit: 5)
+            @fog_banks.values
+                      .sort_by { |f| -f.density }
+                      .first(limit)
+          end
+
+          def visibility_report
+            avg_luminosity = compute_average_luminosity
+            avg_density    = compute_average_density
+            net_visibility = (avg_luminosity - avg_density).clamp(0.0, 1.0).round(10)
+
+            {
+              total_beacons:    @beacons.size,
+              total_fog_banks:  @fog_banks.size,
+              avg_luminosity:   avg_luminosity,
+              avg_density:      avg_density,
+              net_visibility:   net_visibility,
+              blazing_beacons:  @beacons.count { |_, b| b.blazing? },
+              extinguished:     @beacons.count { |_, b| b.extinguished? },
+              impenetrable_fog: @fog_banks.count { |_, f| f.impenetrable? },
+              clearing_fog:     @fog_banks.count { |_, f| f.clearing? }
+            }
+          end
+
+          def all_beacons
+            @beacons.values
+          end
+
+          def all_fog_banks
+            @fog_banks.values
+          end
+
+          private
+
+          def fetch_beacon(id)
+            @beacons.fetch(id) { raise ArgumentError, "beacon not found: #{id}" }
+          end
+
+          def fetch_fog(id)
+            @fog_banks.fetch(id) { raise ArgumentError, "fog bank not found: #{id}" }
+          end
+
+          def compute_average_luminosity
+            return 0.0 if @beacons.empty?
+
+            total = @beacons.values.sum(&:luminosity)
+            (total / @beacons.size).round(10)
+          end
+
+          def compute_average_density
+            return 0.0 if @fog_banks.empty?
+
+            total = @fog_banks.values.sum(&:density)
+            (total / @fog_banks.size).round(10)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_lighthouse/runners/cognitive_lighthouse.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveLighthouse
+      module Runners
+        module CognitiveLighthouse
+          extend self
+
+          include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+          def light_beacon(beacon_type:, domain:, content:, luminosity: nil,
+                           sweep_angle: nil, engine: nil, **)
+            eng    = resolve_engine(engine)
+            beacon = eng.light_beacon(
+              beacon_type: beacon_type,
+              domain:      domain,
+              content:     content,
+              luminosity:  luminosity,
+              sweep_angle: sweep_angle
+            )
+            Legion::Logging.debug "[lighthouse] lit beacon: type=#{beacon_type} domain=#{domain} " \
+                                  "luminosity=#{beacon.luminosity}"
+            { success: true, beacon: beacon.to_h }
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def create_fog(fog_type:, domain:, density: nil, extent: nil, engine: nil, **)
+            eng = resolve_engine(engine)
+            fog = eng.create_fog(fog_type: fog_type, domain: domain,
+                                 density: density, extent: extent)
+            Legion::Logging.debug "[lighthouse] created fog: type=#{fog_type} domain=#{domain} " \
+                                  "density=#{fog.density}"
+            { success: true, fog: fog.to_h }
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def sweep(beacon_id:, fog_id:, engine: nil, **)
+            eng    = resolve_engine(engine)
+            result = eng.sweep(beacon_id: beacon_id, fog_id: fog_id)
+            Legion::Logging.debug "[lighthouse] sweep: beacon=#{beacon_id} fog=#{fog_id} " \
+                                  "reduction=#{result[:reduction]}"
+            { success: true, **result }
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def list_beacons(engine: nil, domain: nil, beacon_type: nil, **)
+            eng     = resolve_engine(engine)
+            results = eng.all_beacons
+            results = results.select { |b| b.domain == domain.to_s } if domain
+            results = results.select { |b| b.beacon_type == beacon_type.to_sym } if beacon_type
+            { success: true, beacons: results.map(&:to_h), count: results.size }
+          end
+
+          def navigation_status(engine: nil, **)
+            eng = resolve_engine(engine)
+            { success: true, report: eng.visibility_report }
+          end
+
+          private
+
+          def resolve_engine(engine)
+            engine || default_engine
+          end
+
+          def default_engine
+            @default_engine ||= Helpers::LighthouseEngine.new
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_lighthouse/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveLighthouse
+      VERSION = '0.1.0'
+    end
+  end
+end

data/lib/legion/extensions/cognitive_lighthouse.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+require_relative 'cognitive_lighthouse/version'
+require_relative 'cognitive_lighthouse/helpers/constants'
+require_relative 'cognitive_lighthouse/helpers/beacon'
+require_relative 'cognitive_lighthouse/helpers/fog'
+require_relative 'cognitive_lighthouse/helpers/lighthouse_engine'
+require_relative 'cognitive_lighthouse/runners/cognitive_lighthouse'
+require_relative 'cognitive_lighthouse/client'
+
+module Legion
+  module Extensions
+    module CognitiveLighthouse
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: lex-cognitive-lighthouse
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Esity
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: legion-gaia
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Models guiding beacons that periodically sweep their beam to illuminate
+  areas of uncertainty, helping navigate complex decision spaces. Beacons can be steady
+  or rotating, can dim in fog, and can guide other agents through ambiguity.
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- CLAUDE.md
+- Gemfile
+- Gemfile.lock
+- README.md
+- lex-cognitive-lighthouse.gemspec
+- lib/legion/extensions/cognitive_lighthouse.rb
+- lib/legion/extensions/cognitive_lighthouse/client.rb
+- lib/legion/extensions/cognitive_lighthouse/helpers/beacon.rb
+- lib/legion/extensions/cognitive_lighthouse/helpers/constants.rb
+- lib/legion/extensions/cognitive_lighthouse/helpers/fog.rb
+- lib/legion/extensions/cognitive_lighthouse/helpers/lighthouse_engine.rb
+- lib/legion/extensions/cognitive_lighthouse/runners/cognitive_lighthouse.rb
+- lib/legion/extensions/cognitive_lighthouse/version.rb
+homepage: https://github.com/LegionIO/lex-cognitive-lighthouse
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-cognitive-lighthouse
+  source_code_uri: https://github.com/LegionIO/lex-cognitive-lighthouse
+  documentation_uri: https://github.com/LegionIO/lex-cognitive-lighthouse#readme
+  changelog_uri: https://github.com/LegionIO/lex-cognitive-lighthouse/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/LegionIO/lex-cognitive-lighthouse/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Cognitive lighthouse LEX — guiding beacons that cut through cognitive fog
+test_files: []