lex-cognitive-synesthesia 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f5b3932afe6397f2043ffad49ca9d50f526274cf5f6fa1a14b9ee7089570e3f9
+  data.tar.gz: 3498493819add151ac7d8432da16511f09d01b1b762999f75c4f7b10471a0407
+SHA512:
+  metadata.gz: 3c7a1a08186b1fed2821e1c275b1b3b50ddb63e0b0efeb9a26c95046e8d3b3e36020d628eec2edac547701a645e89d4dee9989005fd9381c4caa4eb491943d02
+  data.tar.gz: 69a277b2cd7741a4bfc07bb6aed1d10ed278fe6681daac47bd5aed452010ec55c476ae690d6a8c8f280c32868449f754dd698bab59141f93f4c4fcad77b880bc

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,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.gem
+.rspec_status
+Gemfile.lock

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,64 @@
+AllCops:
+  TargetRubyVersion: 3.4
+  NewCops: enable
+  SuggestExtensions: false
+
+Layout/LineLength:
+  Max: 160
+
+Layout/SpaceAroundEqualsInParameterDefault:
+  EnforcedStyle: space
+
+Layout/HashAlignment:
+  EnforcedHashRocketStyle: table
+  EnforcedColonStyle: table
+
+Metrics/MethodLength:
+  Max: 25
+
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/ModuleLength:
+  Max: 1500
+
+Metrics/BlockLength:
+  Max: 40
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/AbcSize:
+  Max: 25
+
+Metrics/CyclomaticComplexity:
+  Max: 15
+
+Metrics/PerceivedComplexity:
+  Max: 17
+
+Metrics/ParameterLists:
+  Max: 8
+  MaxOptionalParameters: 8
+
+Style/Documentation:
+  Enabled: false
+
+Style/SymbolArray:
+  Enabled: true
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+Style/OneClassPerFile:
+  Exclude:
+    - 'spec/spec_helper.rb'
+
+Naming/FileName:
+  Enabled: false
+
+Naming/PredicateMethod:
+  Enabled: false
+
+Naming/PredicatePrefix:
+  Enabled: false

data/CLAUDE.md

@@ -0,0 +1,119 @@
+# lex-cognitive-synesthesia
+
+**Level 3 Leaf Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/extensions-agentic/CLAUDE.md`
+- **Gem**: `lex-cognitive-synesthesia`
+- **Version**: 0.1.0
+- **Namespace**: `Legion::Extensions::CognitiveSynesthesia`
+
+## Purpose
+
+Models cross-modal cognitive associations inspired by synesthesia — the neurological phenomenon where stimulation of one sense involuntarily triggers another. Sensory mappings link a source modality to a target modality via trigger and response patterns. When a source modality is activated, all active mappings for it fire, producing `SynestheticEvent` records. Mappings strengthen with use and decay over time. This models how cognitive input in one domain (e.g., emotional) automatically invokes representations in another (e.g., spatial or visual).
+
+## Gem Info
+
+- **Gemspec**: `lex-cognitive-synesthesia.gemspec`
+- **Require**: `lex-cognitive-synesthesia`
+- **Ruby**: >= 3.4
+- **License**: MIT
+- **Homepage**: https://github.com/LegionIO/lex-cognitive-synesthesia
+
+## File Structure
+
+```
+lib/legion/extensions/cognitive_synesthesia/
+  version.rb
+  helpers/
+    constants.rb           # Modalities, strength/richness/intensity label tables, thresholds
+    sensory_mapping.rb     # SensoryMapping class — one cross-modal association
+    synesthetic_event.rb   # SynestheticEvent class — one fired cross-modal experience
+    synesthesia_engine.rb  # SynesthesiaEngine — manages mappings and event log
+  runners/
+    cognitive_synesthesia.rb  # Runner module — public API
+  client.rb
+```
+
+## Key Constants
+
+| Constant | Value | Meaning |
+|---|---|---|
+| `MAX_MAPPINGS` | 200 | Hard cap; weakest mappings pruned when exceeded |
+| `MAX_EVENTS` | 500 | Event log ring size |
+| `DEFAULT_STRENGTH` | 0.5 | Starting strength for new mappings |
+| `STRENGTH_BOOST` | 0.1 | Strength increase per `activate!` call |
+| `STRENGTH_DECAY` | 0.02 | Strength decrease per `decay!` call |
+| `TRIGGER_THRESHOLD` | 0.3 | Minimum strength for a mapping to fire |
+
+`MODALITIES`: `[:visual, :auditory, :tactile, :emotional, :semantic, :temporal, :spatial, :abstract]`
+
+Strength labels: `0.8+` = `:dominant`, `0.6..0.8` = `:strong`, `0.4..0.6` = `:moderate`, `0.2..0.4` = `:faint`, `<0.2` = `:trace`
+
+Richness labels (for `cross_modal_richness`): `0.8+` = `:synesthetic`, `0.6..0.8` = `:vivid`, `0.4..0.6` = `:partial`, `0.2..0.4` = `:sparse`, `<0.2` = `:amodal`
+
+Intensity labels (for events): `0.8+` = `:overwhelming`, `0.6..0.8` = `:intense`, `0.4..0.6` = `:moderate`, `0.2..0.4` = `:subtle`, `<0.2` = `:subliminal`
+
+## Key Classes
+
+### `Helpers::SensoryMapping`
+
+One cross-modal association with source/target modalities and pattern descriptors.
+
+- `activate!` — increments `activation_count`, boosts strength by `STRENGTH_BOOST`
+- `decay!` — reduces strength by `STRENGTH_DECAY`
+- `active?` — strength >= `TRIGGER_THRESHOLD`
+- `strength_label` — one of the `STRENGTH_LABELS` values
+- Fields: `id` (UUID), `source_modality`, `target_modality`, `trigger_pattern` (caller-defined), `response_pattern` (caller-defined), `strength`, `activation_count`, `created_at`, `last_activated_at`
+
+### `Helpers::SynestheticEvent`
+
+A single fired cross-modal experience.
+
+- `intensity_label` — one of the `INTENSITY_LABELS` values
+- `involuntary` — always true (default); reflects the automatic nature of synesthetic responses
+- `target_output` — hash with `{ modality:, response_pattern:, source_input:, source_modality: }`
+- Fields: `id` (UUID), `mapping_id`, `source_input`, `target_output`, `intensity`, `triggered_at`
+
+### `Helpers::SynesthesiaEngine`
+
+Registry and event processor for all mappings and events.
+
+- `register_mapping(source_modality:, target_modality:, trigger_pattern:, response_pattern:, strength:)` — validates modalities; prunes weakest mappings if over `MAX_MAPPINGS`
+- `trigger(source_modality:, input:)` — finds all active mappings for source, fires each with `fire_event`, returns event list
+- `decay_mappings!` — decays all mappings; removes those with strength <= 0.0
+- `cross_modal_richness` — active unique pairs / `(8 * 7)` possible pairs; range `[0.0, 1.0]`
+- `dominant_modality_pairs(limit:)` — top pairs by cumulative activation count
+- `event_history(limit:)` — most recent events from ring buffer
+- `modality_coverage` — set of modalities appearing in active mappings
+
+## Runners
+
+Module: `Legion::Extensions::CognitiveSynesthesia::Runners::CognitiveSynesthesia`
+
+| Runner | Key Args | Returns |
+|---|---|---|
+| `register_mapping` | `source_modality:`, `target_modality:`, `trigger_pattern:`, `response_pattern:`, `strength:` | `{ success:, mapping_id:, source_modality:, target_modality: }` or `{ success: false, error: :invalid_modality }` |
+| `trigger` | `source_modality:`, `input:` | `{ success:, events:, triggered_count: }` |
+| `decay_mappings` | — | `{ success:, mappings_removed:, mappings_remaining: }` |
+| `cross_modal_richness` | — | `{ success:, richness:, richness_label: }` |
+| `dominant_modality_pairs` | `limit:` | `{ success:, pairs:, count: }` |
+| `event_history` | `limit:` | `{ success:, events:, count: }` |
+| `modality_coverage` | — | `{ success:, covered_modalities:, coverage_count:, total_modalities: }` |
+| `synesthesia_report` | — | aggregate report with richness, active count, dominant pairs, coverage |
+
+All runners accept optional `engine:` keyword for test injection.
+
+## Integration Points
+
+- No actors defined; `decay_mappings` should be called periodically (e.g., from `lex-tick`)
+- `trigger_pattern` and `response_pattern` are caller-defined — can be strings, symbols, or hashes
+- Can represent cross-extension stimulus linkages: e.g., emotional triggers spatial patterns, or temporal triggers semantic associations
+- `cross_modal_richness` measures the breadth of cross-modal connections — a proxy for cognitive integration
+- All state is in-memory per `SynesthesiaEngine` instance
+
+## Development Notes
+
+- Both `trigger_pattern` and `response_pattern` are stored opaquely; the engine does not parse them
+- `fire_event` uses the mapping's current strength (after `activate!`) as event intensity
+- `prune_mappings!` evicts weakest by strength; `prune_weak_mappings!` removes strength-zero mappings after decay
+- The event log is a ring buffer: `@events.shift while @events.size > MAX_EVENTS`
+- `cross_modal_richness` counts unique source->target pairs (directional), not bidirectional

data/Gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rspec', '~> 3.13'
+gem 'rubocop', '~> 1.75', require: false
+gem 'rubocop-rspec', require: false
+
+gem 'legion-gaia', path: '../../legion-gaia'

data/README.md

@@ -0,0 +1,76 @@
+# lex-cognitive-synesthesia
+
+A LegionIO cognitive architecture extension that models cross-modal cognitive associations inspired by synesthesia. Sensory mappings link one cognitive modality to another, firing automatically when the source modality is stimulated.
+
+## What It Does
+
+Registers **sensory mappings** between eight cognitive modalities:
+
+`visual`, `auditory`, `tactile`, `emotional`, `semantic`, `temporal`, `spatial`, `abstract`
+
+When a source modality is triggered, all active mappings for it fire — generating `SynestheticEvent` records that carry the target response. Mappings strengthen with repeated activation and fade through decay, modeling the learned and habituated nature of associative responses.
+
+## Usage
+
+```ruby
+require 'lex-cognitive-synesthesia'
+
+client = Legion::Extensions::CognitiveSynesthesia::Client.new
+
+# Register a mapping: emotional input evokes spatial response
+client.register_mapping(
+  source_modality:  :emotional,
+  target_modality:  :spatial,
+  trigger_pattern:  'high_arousal',
+  response_pattern: 'open_wide_space'
+)
+# => { success: true, mapping_id: "uuid...", source_modality: :emotional, target_modality: :spatial }
+
+# Register another mapping for the same source
+client.register_mapping(
+  source_modality:  :emotional,
+  target_modality:  :visual,
+  trigger_pattern:  'high_arousal',
+  response_pattern: 'bright_warm_colors'
+)
+
+# Trigger all active mappings for emotional input
+result = client.trigger(source_modality: :emotional, input: { valence: 0.8, arousal: 0.9 })
+# => { success: true, triggered_count: 2, events: [ { intensity: 0.6, target_output: { modality: :spatial, ... } }, ... ] }
+
+# Check cross-modal richness (breadth of coverage)
+client.cross_modal_richness
+# => { success: true, richness: 0.036, richness_label: :amodal }
+
+# Which modality pairs are most activated?
+client.dominant_modality_pairs(limit: 3)
+# => { success: true, pairs: [{ pair: "emotional->spatial", activation_count: 1 }, ...], count: 2 }
+
+# What modalities are covered by active mappings?
+client.modality_coverage
+# => { success: true, covered_modalities: [:emotional, :spatial, :visual], coverage_count: 3, total_modalities: 8 }
+
+# Decay all mappings (removes those that fall to 0)
+client.decay_mappings
+# => { success: true, mappings_removed: 0, mappings_remaining: 2 }
+
+# Recent event history
+client.event_history(limit: 10)
+# => { success: true, events: [...], count: 2 }
+
+# Full report
+client.synesthesia_report
+# => { success: true, mapping_count: 2, active_mapping_count: 2, event_count: 2, cross_modal_richness: 0.036, ... }
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-cognitive-synesthesia.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_synesthesia/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-synesthesia'
+  spec.version       = Legion::Extensions::CognitiveSynesthesia::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Cognitive Synesthesia'
+  spec.description   = 'Cross-modal synesthetic mapping for LegionIO agents — automatic ' \
+                       'cross-domain associations that enrich understanding through sensory translation'
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-synesthesia'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri']          = spec.homepage
+  spec.metadata['source_code_uri']       = 'https://github.com/LegionIO/lex-cognitive-synesthesia'
+  spec.metadata['documentation_uri']     = 'https://github.com/LegionIO/lex-cognitive-synesthesia'
+  spec.metadata['changelog_uri']         = 'https://github.com/LegionIO/lex-cognitive-synesthesia'
+  spec.metadata['bug_tracker_uri']       = 'https://github.com/LegionIO/lex-cognitive-synesthesia/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__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_synesthesia/client.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_synesthesia/helpers/constants'
+require 'legion/extensions/cognitive_synesthesia/helpers/sensory_mapping'
+require 'legion/extensions/cognitive_synesthesia/helpers/synesthetic_event'
+require 'legion/extensions/cognitive_synesthesia/helpers/synesthesia_engine'
+require 'legion/extensions/cognitive_synesthesia/runners/cognitive_synesthesia'
+
+module Legion
+  module Extensions
+    module CognitiveSynesthesia
+      class Client
+        include Runners::CognitiveSynesthesia
+
+        def initialize(engine: nil, **)
+          @synesthesia_engine = engine || Helpers::SynesthesiaEngine.new
+        end
+
+        private
+
+        attr_reader :synesthesia_engine
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveSynesthesia
+      module Helpers
+        module Constants
+          MAX_MAPPINGS     = 200
+          MAX_EVENTS       = 500
+          DEFAULT_STRENGTH = 0.5
+          STRENGTH_BOOST   = 0.1
+          STRENGTH_DECAY   = 0.02
+          TRIGGER_THRESHOLD = 0.3
+
+          MODALITIES = %i[visual auditory tactile emotional semantic temporal spatial abstract].freeze
+
+          STRENGTH_LABELS = {
+            (0.8..)     => :dominant,
+            (0.6...0.8) => :strong,
+            (0.4...0.6) => :moderate,
+            (0.2...0.4) => :faint,
+            (..0.2)     => :trace
+          }.freeze
+
+          RICHNESS_LABELS = {
+            (0.8..)     => :synesthetic,
+            (0.6...0.8) => :vivid,
+            (0.4...0.6) => :partial,
+            (0.2...0.4) => :sparse,
+            (..0.2)     => :amodal
+          }.freeze
+
+          INTENSITY_LABELS = {
+            (0.8..)     => :overwhelming,
+            (0.6...0.8) => :intense,
+            (0.4...0.6) => :moderate,
+            (0.2...0.4) => :subtle,
+            (..0.2)     => :subliminal
+          }.freeze
+
+          def self.label_for(labels_hash, value)
+            labels_hash.find { |range, _| range.cover?(value) }&.last || :unknown
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_synesthesia/helpers/sensory_mapping.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveSynesthesia
+      module Helpers
+        class SensoryMapping
+          include Constants
+
+          attr_reader :id, :source_modality, :target_modality,
+                      :trigger_pattern, :response_pattern,
+                      :strength, :activation_count, :created_at, :last_activated_at
+
+          def initialize(source_modality:, target_modality:, trigger_pattern:, response_pattern:,
+                         strength: DEFAULT_STRENGTH)
+            @id               = SecureRandom.uuid
+            @source_modality  = source_modality
+            @target_modality  = target_modality
+            @trigger_pattern  = trigger_pattern
+            @response_pattern = response_pattern
+            @strength         = strength.clamp(0.0, 1.0)
+            @activation_count = 0
+            @created_at       = Time.now.utc
+            @last_activated_at = nil
+          end
+
+          def activate!
+            @activation_count += 1
+            @last_activated_at = Time.now.utc
+            @strength = (@strength + STRENGTH_BOOST).clamp(0.0, 1.0).round(10)
+          end
+
+          def decay!
+            @strength = (@strength - STRENGTH_DECAY).clamp(0.0, 1.0).round(10)
+          end
+
+          def active?
+            @strength >= TRIGGER_THRESHOLD
+          end
+
+          def strength_label
+            Constants.label_for(STRENGTH_LABELS, @strength)
+          end
+
+          def to_h
+            {
+              id:                @id,
+              source_modality:   @source_modality,
+              target_modality:   @target_modality,
+              trigger_pattern:   @trigger_pattern,
+              response_pattern:  @response_pattern,
+              strength:          @strength,
+              activation_count:  @activation_count,
+              strength_label:    strength_label,
+              active:            active?,
+              created_at:        @created_at,
+              last_activated_at: @last_activated_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_synesthesia/helpers/synesthesia_engine.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveSynesthesia
+      module Helpers
+        class SynesthesiaEngine
+          include Constants
+
+          attr_reader :mappings, :events
+
+          def initialize
+            @mappings = {}
+            @events   = []
+          end
+
+          def register_mapping(source_modality:, target_modality:, trigger_pattern:,
+                               response_pattern:, strength: DEFAULT_STRENGTH, **)
+            return invalid_modality_error(:source_modality) unless MODALITIES.include?(source_modality)
+            return invalid_modality_error(:target_modality) unless MODALITIES.include?(target_modality)
+
+            mapping = SensoryMapping.new(
+              source_modality:  source_modality,
+              target_modality:  target_modality,
+              trigger_pattern:  trigger_pattern,
+              response_pattern: response_pattern,
+              strength:         strength
+            )
+
+            @mappings[mapping.id] = mapping
+            prune_mappings! if @mappings.size > MAX_MAPPINGS
+
+            Legion::Logging.debug "[cognitive_synesthesia] mapping registered id=#{mapping.id[0..7]} " \
+                                  "#{source_modality}->#{target_modality} strength=#{strength.round(2)}"
+
+            { success: true, mapping_id: mapping.id, source_modality: source_modality,
+              target_modality: target_modality }
+          end
+
+          def trigger(source_modality:, input:, **)
+            active = active_mappings_for(source_modality)
+            return { success: true, events: [], triggered_count: 0 } if active.empty?
+
+            triggered_events = active.map do |mapping|
+              fire_event(mapping, input)
+            end
+
+            { success: true, events: triggered_events.map(&:to_h), triggered_count: triggered_events.size }
+          end
+
+          def decay_mappings!(**)
+            @mappings.each_value(&:decay!)
+            removed = prune_weak_mappings!
+
+            Legion::Logging.debug "[cognitive_synesthesia] decay_mappings! removed=#{removed} remaining=#{@mappings.size}"
+            { success: true, mappings_removed: removed, mappings_remaining: @mappings.size }
+          end
+
+          def cross_modal_richness(**)
+            return 0.0 if @mappings.empty?
+
+            pairs = active_mapping_pairs
+            total_possible = (MODALITIES.size * (MODALITIES.size - 1)).to_f
+            return 0.0 if total_possible.zero?
+
+            (pairs.size.to_f / total_possible).clamp(0.0, 1.0).round(10)
+          end
+
+          def dominant_modality_pairs(limit: 5, **)
+            pair_counts = Hash.new(0)
+            @mappings.each_value do |m|
+              next unless m.active?
+
+              pair_counts["#{m.source_modality}->#{m.target_modality}"] += m.activation_count
+            end
+
+            sorted = pair_counts.sort_by { |_, count| -count }.first(limit)
+            sorted.map { |pair, count| { pair: pair, activation_count: count } }
+          end
+
+          def event_history(limit: 20, **)
+            recent = @events.last(limit)
+            { success: true, events: recent.map(&:to_h), count: recent.size }
+          end
+
+          def modality_coverage(**)
+            covered = Set.new
+            @mappings.each_value do |m|
+              next unless m.active?
+
+              covered << m.source_modality
+              covered << m.target_modality
+            end
+            {
+              covered_modalities: covered.to_a.sort,
+              coverage_count:     covered.size,
+              total_modalities:   MODALITIES.size
+            }
+          end
+
+          def synesthesia_report(**)
+            richness = cross_modal_richness
+            {
+              mapping_count:           @mappings.size,
+              active_mapping_count:    @mappings.values.count(&:active?),
+              event_count:             @events.size,
+              cross_modal_richness:    richness,
+              richness_label:          Constants.label_for(RICHNESS_LABELS, richness),
+              dominant_modality_pairs: dominant_modality_pairs,
+              modality_coverage:       modality_coverage
+            }
+          end
+
+          private
+
+          def invalid_modality_error(field)
+            { success: false, error: :invalid_modality, field: field, valid_modalities: MODALITIES }
+          end
+
+          def active_mappings_for(source_modality)
+            @mappings.values.select { |m| m.source_modality == source_modality && m.active? }
+          end
+
+          def fire_event(mapping, input)
+            mapping.activate!
+            intensity = mapping.strength.clamp(0.0, 1.0)
+            event = SynestheticEvent.new(
+              mapping_id:    mapping.id,
+              source_input:  input,
+              target_output: build_target_output(mapping, input),
+              intensity:     intensity
+            )
+            @events << event
+            @events.shift while @events.size > MAX_EVENTS
+
+            Legion::Logging.debug "[cognitive_synesthesia] event fired id=#{event.id[0..7]} " \
+                                  "mapping=#{mapping.id[0..7]} intensity=#{intensity.round(2)}"
+            event
+          end
+
+          def build_target_output(mapping, input)
+            {
+              modality:         mapping.target_modality,
+              response_pattern: mapping.response_pattern,
+              source_input:     input,
+              source_modality:  mapping.source_modality
+            }
+          end
+
+          def active_mapping_pairs
+            @mappings.values.select(&:active?).map do |m|
+              [m.source_modality, m.target_modality]
+            end.uniq
+          end
+
+          def prune_mappings!
+            overflow = @mappings.size - MAX_MAPPINGS
+            return if overflow <= 0
+
+            ids_to_prune = @mappings.min_by(overflow) { |_, m| m.strength }.map(&:first)
+            ids_to_prune.each { |id| @mappings.delete(id) }
+          end
+
+          def prune_weak_mappings!
+            before = @mappings.size
+            @mappings.reject! { |_, m| m.strength <= 0.0 }
+            before - @mappings.size
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_synesthesia/helpers/synesthetic_event.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveSynesthesia
+      module Helpers
+        class SynestheticEvent
+          include Constants
+
+          attr_reader :id, :mapping_id, :source_input, :target_output,
+                      :intensity, :involuntary, :triggered_at
+
+          def initialize(mapping_id:, source_input:, target_output:, intensity:, involuntary: true)
+            @id            = SecureRandom.uuid
+            @mapping_id    = mapping_id
+            @source_input  = source_input
+            @target_output = target_output
+            @intensity     = intensity.clamp(0.0, 1.0)
+            @involuntary   = involuntary
+            @triggered_at  = Time.now.utc
+          end
+
+          def intensity_label
+            Constants.label_for(INTENSITY_LABELS, @intensity)
+          end
+
+          def to_h
+            {
+              id:              @id,
+              mapping_id:      @mapping_id,
+              source_input:    @source_input,
+              target_output:   @target_output,
+              intensity:       @intensity,
+              intensity_label: intensity_label,
+              involuntary:     @involuntary,
+              triggered_at:    @triggered_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveSynesthesia
+      module Runners
+        module CognitiveSynesthesia
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def register_mapping(source_modality:, target_modality:, trigger_pattern:,
+                               response_pattern:, strength: Helpers::Constants::DEFAULT_STRENGTH,
+                               engine: nil, **)
+            target = engine || synesthesia_engine
+            Legion::Logging.debug "[cognitive_synesthesia] runner register_mapping #{source_modality}->#{target_modality}"
+            target.register_mapping(
+              source_modality:  source_modality,
+              target_modality:  target_modality,
+              trigger_pattern:  trigger_pattern,
+              response_pattern: response_pattern,
+              strength:         strength
+            )
+          end
+
+          def trigger(source_modality:, input:, engine: nil, **)
+            target = engine || synesthesia_engine
+            Legion::Logging.debug "[cognitive_synesthesia] runner trigger modality=#{source_modality}"
+            target.trigger(source_modality: source_modality, input: input)
+          end
+
+          def decay_mappings(engine: nil, **)
+            target = engine || synesthesia_engine
+            Legion::Logging.debug '[cognitive_synesthesia] runner decay_mappings'
+            target.decay_mappings!
+          end
+
+          def cross_modal_richness(engine: nil, **)
+            target = engine || synesthesia_engine
+            richness = target.cross_modal_richness
+            label    = Helpers::Constants.label_for(Helpers::Constants::RICHNESS_LABELS, richness)
+            Legion::Logging.debug "[cognitive_synesthesia] runner cross_modal_richness=#{richness.round(4)} label=#{label}"
+            { success: true, richness: richness, richness_label: label }
+          end
+
+          def dominant_modality_pairs(limit: 5, engine: nil, **)
+            target = engine || synesthesia_engine
+            pairs  = target.dominant_modality_pairs(limit: limit)
+            Legion::Logging.debug "[cognitive_synesthesia] runner dominant_modality_pairs limit=#{limit}"
+            { success: true, pairs: pairs, count: pairs.size }
+          end
+
+          def event_history(limit: 20, engine: nil, **)
+            target = engine || synesthesia_engine
+            Legion::Logging.debug "[cognitive_synesthesia] runner event_history limit=#{limit}"
+            target.event_history(limit: limit)
+          end
+
+          def modality_coverage(engine: nil, **)
+            target = engine || synesthesia_engine
+            Legion::Logging.debug '[cognitive_synesthesia] runner modality_coverage'
+            { success: true }.merge(target.modality_coverage)
+          end
+
+          def synesthesia_report(engine: nil, **)
+            target = engine || synesthesia_engine
+            Legion::Logging.debug '[cognitive_synesthesia] runner synesthesia_report'
+            { success: true }.merge(target.synesthesia_report)
+          end
+
+          private
+
+          def synesthesia_engine
+            @synesthesia_engine ||= Helpers::SynesthesiaEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/cognitive_synesthesia.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_synesthesia/version'
+require 'legion/extensions/cognitive_synesthesia/helpers/constants'
+require 'legion/extensions/cognitive_synesthesia/helpers/sensory_mapping'
+require 'legion/extensions/cognitive_synesthesia/helpers/synesthetic_event'
+require 'legion/extensions/cognitive_synesthesia/helpers/synesthesia_engine'
+require 'legion/extensions/cognitive_synesthesia/runners/cognitive_synesthesia'
+
+module Legion
+  module Extensions
+    module CognitiveSynesthesia
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: lex-cognitive-synesthesia
+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: Cross-modal synesthetic mapping for LegionIO agents — automatic cross-domain
+  associations that enrich understanding through sensory translation
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- CLAUDE.md
+- Gemfile
+- README.md
+- lex-cognitive-synesthesia.gemspec
+- lib/legion/extensions/cognitive_synesthesia.rb
+- lib/legion/extensions/cognitive_synesthesia/client.rb
+- lib/legion/extensions/cognitive_synesthesia/helpers/constants.rb
+- lib/legion/extensions/cognitive_synesthesia/helpers/sensory_mapping.rb
+- lib/legion/extensions/cognitive_synesthesia/helpers/synesthesia_engine.rb
+- lib/legion/extensions/cognitive_synesthesia/helpers/synesthetic_event.rb
+- lib/legion/extensions/cognitive_synesthesia/runners/cognitive_synesthesia.rb
+- lib/legion/extensions/cognitive_synesthesia/version.rb
+homepage: https://github.com/LegionIO/lex-cognitive-synesthesia
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-cognitive-synesthesia
+  source_code_uri: https://github.com/LegionIO/lex-cognitive-synesthesia
+  documentation_uri: https://github.com/LegionIO/lex-cognitive-synesthesia
+  changelog_uri: https://github.com/LegionIO/lex-cognitive-synesthesia
+  bug_tracker_uri: https://github.com/LegionIO/lex-cognitive-synesthesia/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: LEX Cognitive Synesthesia
+test_files: []