lex-subliminal 0.1.0

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Subliminal
+      module Runners
+        module Subliminal
+          include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+          def create_subliminal_trace(content:, trace_type: :associative, domain: :general, activation: nil,
+                                      influence_target: :attention, engine: nil, **)
+            eng = engine || @default_engine
+            trace = eng.create_trace(content: content, trace_type: trace_type, domain: domain,
+                                     activation: activation || Helpers::Constants::DEFAULT_ACTIVATION,
+                                     influence_target: influence_target)
+            { success: true, trace: trace.to_h }
+          end
+
+          def boost_trace(trace_id:, amount: nil, engine: nil, **)
+            eng = engine || @default_engine
+            trace = eng.boost_trace(trace_id: trace_id, amount: amount || Helpers::Constants::ACTIVATION_BOOST)
+            return { success: false, error: 'trace not found' } unless trace
+
+            { success: true, trace: trace.to_h }
+          end
+
+          def process_influences(engine: nil, **)
+            eng = engine || @default_engine
+            result = eng.process_influences!
+            { success: true, **result }
+          end
+
+          def decay_all(engine: nil, **)
+            eng = engine || @default_engine
+            result = eng.decay_all!
+            { success: true, **result }
+          end
+
+          def active_traces(engine: nil, **)
+            eng = engine || @default_engine
+            traces = eng.active_traces
+            { success: true, count: traces.size, traces: traces.map(&:to_h) }
+          end
+
+          def near_threshold(engine: nil, **)
+            eng = engine || @default_engine
+            traces = eng.near_threshold_traces
+            { success: true, count: traces.size, traces: traces.map(&:to_h) }
+          end
+
+          def influence_on(target:, engine: nil, **)
+            eng = engine || @default_engine
+            level = eng.influence_on(target: target)
+            label = Helpers::Constants.label_for(Helpers::Constants::INFLUENCE_LABELS, level)
+            { success: true, target: target, influence: level, label: label }
+          end
+
+          def subliminal_status(engine: nil, **)
+            eng = engine || @default_engine
+            report = eng.subliminal_report
+            { success: true, **report }
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/subliminal.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative 'subliminal/version'
+require_relative 'subliminal/helpers/constants'
+require_relative 'subliminal/helpers/subliminal_trace'
+require_relative 'subliminal/helpers/influence_event'
+require_relative 'subliminal/helpers/subliminal_engine'
+require_relative 'subliminal/runners/subliminal'
+require_relative 'subliminal/client'
+
+module Legion
+  module Extensions
+    module Subliminal
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Subliminal::Client do
+  subject(:client) { described_class.new }
+
+  it 'responds to runner methods' do
+    expect(client).to respond_to(:create_subliminal_trace, :process_influences, :subliminal_status)
+  end
+
+  it 'runs a full subliminal lifecycle' do
+    result = client.create_subliminal_trace(content: 'danger signal', domain: :security)
+    trace_id = result[:trace][:id]
+
+    client.boost_trace(trace_id: trace_id)
+    client.process_influences
+    client.decay_all
+
+    status = client.subliminal_status
+    expect(status[:total_traces]).to be >= 1
+  end
+end

data/spec/legion/extensions/subliminal/helpers/influence_event_spec.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Subliminal::Helpers::InfluenceEvent do
+  subject(:event) do
+    described_class.new(trace_id: 'abc-123', target: :attention, magnitude: 0.08, domain: :security)
+  end
+
+  describe '#initialize' do
+    it 'assigns a UUID id' do
+      expect(event.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores trace_id' do
+      expect(event.trace_id).to eq('abc-123')
+    end
+
+    it 'stores target' do
+      expect(event.target).to eq(:attention)
+    end
+
+    it 'stores magnitude' do
+      expect(event.magnitude).to eq(0.08)
+    end
+
+    it 'stores domain' do
+      expect(event.domain).to eq(:security)
+    end
+  end
+
+  describe '#significant?' do
+    it 'is true for magnitude >= 0.05' do
+      expect(event.significant?).to be true
+    end
+
+    it 'is false for small magnitude' do
+      small = described_class.new(trace_id: 'x', target: :emotion, magnitude: 0.03)
+      expect(small.significant?).to be false
+    end
+  end
+
+  describe '#subtle?' do
+    it 'is true for small positive magnitude' do
+      small = described_class.new(trace_id: 'x', target: :emotion, magnitude: 0.03)
+      expect(small.subtle?).to be true
+    end
+
+    it 'is false for significant magnitude' do
+      expect(event.subtle?).to be false
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all fields' do
+      hash = event.to_h
+      expect(hash).to include(:id, :trace_id, :target, :magnitude, :domain, :created_at)
+    end
+  end
+end

data/spec/legion/extensions/subliminal/helpers/subliminal_engine_spec.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Subliminal::Helpers::SubliminalEngine do
+  subject(:engine) { described_class.new }
+
+  describe '#create_trace' do
+    it 'creates and stores a trace' do
+      trace = engine.create_trace(content: 'faint memory')
+      expect(trace.content).to eq('faint memory')
+    end
+  end
+
+  describe '#boost_trace' do
+    it 'boosts activation' do
+      trace = engine.create_trace(content: 'test')
+      original = trace.activation
+      engine.boost_trace(trace_id: trace.id)
+      expect(trace.activation).to be > original
+    end
+
+    it 'returns nil for unknown trace' do
+      expect(engine.boost_trace(trace_id: 'bad')).to be_nil
+    end
+  end
+
+  describe '#process_influences!' do
+    it 'generates influence events from active traces' do
+      engine.create_trace(content: 'a', activation: 0.3)
+      result = engine.process_influences!
+      expect(result[:influences_generated]).to be >= 1
+    end
+
+    it 'returns empty when no active traces' do
+      result = engine.process_influences!
+      expect(result[:influences_generated]).to eq(0)
+    end
+  end
+
+  describe '#decay_all!' do
+    it 'decays all traces' do
+      trace = engine.create_trace(content: 'test')
+      original = trace.activation
+      engine.decay_all!
+      expect(trace.activation).to be < original
+    end
+  end
+
+  describe '#active_traces' do
+    it 'returns non-extinct traces' do
+      engine.create_trace(content: 'active', activation: 0.2)
+      expect(engine.active_traces.size).to eq(1)
+    end
+  end
+
+  describe '#near_threshold_traces' do
+    it 'returns traces near conscious threshold' do
+      engine.create_trace(content: 'near', activation: 0.35)
+      engine.create_trace(content: 'far', activation: 0.1)
+      expect(engine.near_threshold_traces.size).to eq(1)
+    end
+  end
+
+  describe '#potent_traces' do
+    it 'returns traces with activation >= 0.2' do
+      engine.create_trace(content: 'potent', activation: 0.25)
+      engine.create_trace(content: 'weak', activation: 0.05)
+      expect(engine.potent_traces.size).to eq(1)
+    end
+  end
+
+  describe '#traces_by_domain' do
+    it 'filters by domain' do
+      engine.create_trace(content: 'a', domain: :security)
+      engine.create_trace(content: 'b', domain: :memory)
+      expect(engine.traces_by_domain(domain: :security).size).to eq(1)
+    end
+  end
+
+  describe '#traces_by_type' do
+    it 'filters by trace type' do
+      engine.create_trace(content: 'a', trace_type: :emotional)
+      engine.create_trace(content: 'b', trace_type: :procedural)
+      expect(engine.traces_by_type(trace_type: :emotional).size).to eq(1)
+    end
+  end
+
+  describe '#traces_by_target' do
+    it 'filters by influence target' do
+      engine.create_trace(content: 'a', influence_target: :emotion)
+      engine.create_trace(content: 'b', influence_target: :decision)
+      expect(engine.traces_by_target(target: :emotion).size).to eq(1)
+    end
+  end
+
+  describe '#influence_on' do
+    it 'returns 0.0 with no influences' do
+      expect(engine.influence_on(target: :attention)).to eq(0.0)
+    end
+
+    it 'returns accumulated influence after processing' do
+      engine.create_trace(content: 'a', activation: 0.3, influence_target: :attention)
+      engine.process_influences!
+      expect(engine.influence_on(target: :attention)).to be > 0.0
+    end
+  end
+
+  describe '#domain_saturation' do
+    it 'returns 0.0 for empty domain' do
+      expect(engine.domain_saturation(domain: :security)).to eq(0.0)
+    end
+
+    it 'returns positive for populated domain' do
+      engine.create_trace(content: 'a', domain: :security, activation: 0.3)
+      expect(engine.domain_saturation(domain: :security)).to be > 0.0
+    end
+  end
+
+  describe '#overall_subliminal_load' do
+    it 'returns 0.0 with no traces' do
+      expect(engine.overall_subliminal_load).to eq(0.0)
+    end
+
+    it 'returns positive with active traces' do
+      engine.create_trace(content: 'a', activation: 0.3)
+      expect(engine.overall_subliminal_load).to be > 0.0
+    end
+  end
+
+  describe '#strongest_traces' do
+    it 'returns sorted by activation descending' do
+      engine.create_trace(content: 'weak', activation: 0.1)
+      strong = engine.create_trace(content: 'strong', activation: 0.35)
+      expect(engine.strongest_traces(limit: 1).first.id).to eq(strong.id)
+    end
+  end
+
+  describe '#breached_traces' do
+    it 'returns empty when all below threshold' do
+      engine.create_trace(content: 'below', activation: 0.3)
+      expect(engine.breached_traces).to be_empty
+    end
+  end
+
+  describe '#subliminal_report' do
+    it 'includes all report fields' do
+      report = engine.subliminal_report
+      expect(report).to include(
+        :total_traces, :active_count, :near_threshold, :potent_count,
+        :total_influences, :subliminal_load, :saturation_label,
+        :breached_count, :strongest
+      )
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes summary fields' do
+      hash = engine.to_h
+      expect(hash).to include(:total_traces, :active, :subliminal_load, :total_influences)
+    end
+  end
+end

data/spec/legion/extensions/subliminal/helpers/subliminal_trace_spec.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Subliminal::Helpers::SubliminalTrace do
+  subject(:trace) { described_class.new(content: 'faint memory of danger') }
+
+  describe '#initialize' do
+    it 'assigns a UUID id' do
+      expect(trace.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores content' do
+      expect(trace.content).to eq('faint memory of danger')
+    end
+
+    it 'defaults trace_type to :associative' do
+      expect(trace.trace_type).to eq(:associative)
+    end
+
+    it 'defaults domain to :general' do
+      expect(trace.domain).to eq(:general)
+    end
+
+    it 'defaults activation to DEFAULT_ACTIVATION' do
+      expect(trace.activation).to eq(0.2)
+    end
+
+    it 'clamps activation to subliminal ceiling' do
+      high = described_class.new(content: 'x', activation: 0.9)
+      expect(high.activation).to eq(0.39)
+    end
+
+    it 'clamps activation to subliminal floor' do
+      low = described_class.new(content: 'x', activation: 0.001)
+      expect(low.activation).to eq(0.02)
+    end
+
+    it 'defaults influence_target to :attention' do
+      expect(trace.influence_target).to eq(:attention)
+    end
+
+    it 'validates trace_type' do
+      bad = described_class.new(content: 'x', trace_type: :nonexistent)
+      expect(bad.trace_type).to eq(:associative)
+    end
+
+    it 'validates influence_target' do
+      bad = described_class.new(content: 'x', influence_target: :nonexistent)
+      expect(bad.influence_target).to eq(:attention)
+    end
+  end
+
+  describe '#boost!' do
+    it 'increases activation' do
+      original = trace.activation
+      trace.boost!
+      expect(trace.activation).to be > original
+    end
+
+    it 'clamps at subliminal ceiling' do
+      10.times { trace.boost! }
+      expect(trace.activation).to eq(0.39)
+    end
+  end
+
+  describe '#decay!' do
+    it 'decreases activation' do
+      original = trace.activation
+      trace.decay!
+      expect(trace.activation).to be < original
+    end
+
+    it 'clamps at 0.0' do
+      50.times { trace.decay! }
+      expect(trace.activation).to eq(0.0)
+    end
+  end
+
+  describe '#exert_influence!' do
+    it 'returns influence magnitude' do
+      mag = trace.exert_influence!
+      expect(mag).to be > 0.0
+    end
+
+    it 'increments influence_count' do
+      trace.exert_influence!
+      expect(trace.influence_count).to eq(1)
+    end
+
+    it 'slightly decreases activation' do
+      original = trace.activation
+      trace.exert_influence!
+      expect(trace.activation).to be < original
+    end
+  end
+
+  describe '#near_threshold?' do
+    it 'is false at default activation' do
+      expect(trace.near_threshold?).to be false
+    end
+
+    it 'is true when near conscious threshold' do
+      near = described_class.new(content: 'x', activation: 0.35)
+      expect(near.near_threshold?).to be true
+    end
+  end
+
+  describe '#active?' do
+    it 'is true at default activation' do
+      expect(trace.active?).to be true
+    end
+
+    it 'is false when fully decayed' do
+      50.times { trace.decay! }
+      expect(trace.active?).to be false
+    end
+  end
+
+  describe '#extinct?' do
+    it 'is false at default activation' do
+      expect(trace.extinct?).to be false
+    end
+
+    it 'is true when nearly zero' do
+      50.times { trace.decay! }
+      expect(trace.extinct?).to be true
+    end
+  end
+
+  describe '#potent?' do
+    it 'is true at default activation' do
+      expect(trace.potent?).to be true
+    end
+
+    it 'is false when low' do
+      faint = described_class.new(content: 'x', activation: 0.1)
+      expect(faint.potent?).to be false
+    end
+  end
+
+  describe '#breached_threshold?' do
+    it 'is false by default' do
+      expect(trace.breached_threshold?).to be false
+    end
+  end
+
+  describe '#persistence' do
+    it 'is 1.0 initially' do
+      expect(trace.persistence).to eq(1.0)
+    end
+
+    it 'decreases after decay' do
+      trace.decay!
+      expect(trace.persistence).to be < 1.0
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all fields' do
+      hash = trace.to_h
+      expect(hash).to include(
+        :id, :content, :trace_type, :domain, :activation,
+        :original_activation, :influence_target, :influence_count,
+        :influence_magnitude, :near_threshold, :active, :extinct,
+        :activation_label, :persistence, :created_at
+      )
+    end
+  end
+end

data/spec/legion/extensions/subliminal/runners_spec.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Subliminal::Runners::Subliminal do
+  let(:engine) { Legion::Extensions::Subliminal::Helpers::SubliminalEngine.new }
+  let(:runner) do
+    obj = Object.new
+    obj.extend(described_class)
+    obj.instance_variable_set(:@default_engine, engine)
+    obj
+  end
+
+  describe '#create_subliminal_trace' do
+    it 'returns success with trace hash' do
+      result = runner.create_subliminal_trace(content: 'test', engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:trace][:content]).to eq('test')
+    end
+  end
+
+  describe '#boost_trace' do
+    it 'returns success for known trace' do
+      trace = engine.create_trace(content: 'test')
+      result = runner.boost_trace(trace_id: trace.id, engine: engine)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns failure for unknown trace' do
+      result = runner.boost_trace(trace_id: 'bad', engine: engine)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#process_influences' do
+    it 'returns success' do
+      result = runner.process_influences(engine: engine)
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#decay_all' do
+    it 'returns success' do
+      result = runner.decay_all(engine: engine)
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#active_traces' do
+    it 'returns active list' do
+      engine.create_trace(content: 'test')
+      result = runner.active_traces(engine: engine)
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#near_threshold' do
+    it 'returns near-threshold list' do
+      engine.create_trace(content: 'near', activation: 0.35)
+      result = runner.near_threshold(engine: engine)
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#influence_on' do
+    it 'returns influence level' do
+      result = runner.influence_on(target: :attention, engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:influence]).to eq(0.0)
+    end
+  end
+
+  describe '#subliminal_status' do
+    it 'returns comprehensive status' do
+      result = runner.subliminal_status(engine: engine)
+      expect(result[:success]).to be true
+      expect(result).to include(:total_traces, :subliminal_load)
+    end
+  end
+end

data/spec/legion/extensions/subliminal_spec.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Subliminal do
+  it 'has a version number' do
+    expect(Legion::Extensions::Subliminal::VERSION).to eq('0.1.0')
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/subliminal'
+
+module Legion
+  module Extensions
+    module Helpers
+      module Lex; end
+    end
+  end
+
+  module Logging
+    def self.method_missing(_, *) = nil
+    def self.respond_to_missing?(_, _ = false) = true
+  end
+end
+
+RSpec.configure do |config|
+  config.expect_with :rspec do |expectations|
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+  config.mock_with :rspec do |mocks|
+    mocks.verify_partial_doubles = true
+  end
+  config.shared_context_metadata_behavior = :apply_to_host_groups
+  config.order = :random
+  Kernel.srand config.seed
+end