lex-anchoring 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 69728f9f687e438684ae064c6d9e4af0143f0c045180b24741fd6411fac09e8f
+  data.tar.gz: 608e3c7a14e1152a712a7071f8cd4ea5fcc0d03b2ed7b3f084b83166cf701b10
+SHA512:
+  metadata.gz: 127782ae3c0c6a546af57e851cb3c70bcf65c222b489066cd85167618dca05eb978988624e3e374c0c765b648b906bcc3be5a0949914cc849b4b1f7a47737682
+  data.tar.gz: 647131ea6bc0ff9c341b2156ee5cd102009a83718991b92397aa074f17350b9422630069bc80f01b8b03e32f20c0416a657b9bb6d7d24be6ac0034f00b2b2301

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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Iverson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,58 @@
+# lex-anchoring
+
+Decision anchoring and reference point effects for brain-modeled agentic AI.
+
+## What It Does
+
+Models the cognitive anchoring bias: initial values exert disproportionate gravitational pull on subsequent estimates. Implements both anchoring (estimates are pulled toward initial values) and prospect theory's reference point framing (outcomes are perceived as gains or losses relative to a reference, with losses weighted 2.25x more than equivalent gains).
+
+## Core Concept: Anchor Pull
+
+An anchor exerts a pull on estimates proportional to its strength:
+
+```ruby
+# anchored_estimate = (strength * DEFAULT_ANCHOR_WEIGHT * anchor_value) +
+#                     ((1 - strength * DEFAULT_ANCHOR_WEIGHT) * raw_estimate)
+```
+
+With default weight 0.6 and full strength, a strong anchor pulls 60% toward itself.
+
+## Usage
+
+```ruby
+client = Legion::Extensions::Anchoring::Client.new
+
+# Record an anchor (e.g., initial budget estimate)
+client.record_anchor(value: 100_000.0, domain: :budget)
+
+# Evaluate a new estimate — it will be pulled toward the anchor
+result = client.evaluate_estimate(estimate: 150_000.0, domain: :budget)
+# => { anchored_estimate: 130_000.0, pull_strength: 0.6, correction: 20_000.0 }
+
+# Frame a value as gain or loss (with 2.25x loss aversion)
+client.reference_frame(value: 80_000.0, domain: :budget)
+# => { gain_or_loss: :loss, magnitude: 45_000.0, reference: 100_000.0 }
+
+# Remove the bias to get the corrected estimate
+client.de_anchor(estimate: 130_000.0, domain: :budget)
+# => { corrected_estimate: 110_000.0, anchor_bias: 20_000.0 }
+
+# Maintenance
+client.update_anchoring
+```
+
+## Integration
+
+Pairs with lex-bias for comprehensive bias detection. `reference_frame` output feeds naturally into lex-emotion for emotional gain/loss responses. Wire into decision phases where the agent evaluates numerical estimates or compares outcomes against baselines.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-anchoring.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/anchoring/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-anchoring'
+  spec.version       = Legion::Extensions::Anchoring::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Anchoring'
+  spec.description   = 'Decision anchoring and reference point effects for brain-modeled agentic AI'
+  spec.homepage      = 'https://github.com/LegionIO/lex-anchoring'
+  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-anchoring'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-anchoring'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-anchoring'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-anchoring/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-anchoring.gemspec Gemfile LICENSE README.md]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/anchoring/helpers/constants'
+require 'legion/extensions/anchoring/helpers/anchor'
+require 'legion/extensions/anchoring/helpers/anchor_store'
+require 'legion/extensions/anchoring/runners/anchoring'
+
+module Legion
+  module Extensions
+    module Anchoring
+      class Client
+        include Runners::Anchoring
+
+        attr_reader :anchor_store
+
+        def initialize(anchor_store: nil, **)
+          @anchor_store = anchor_store || Helpers::AnchorStore.new
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/anchoring/helpers/anchor.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Anchoring
+      module Helpers
+        class Anchor
+          include Constants
+
+          attr_reader :id, :value, :domain, :strength, :created_at, :last_accessed
+
+          def initialize(value:, domain: :general)
+            @id            = SecureRandom.uuid
+            @value         = value.to_f
+            @domain        = domain.to_sym
+            @strength      = 1.0
+            @created_at    = Time.now.utc
+            @last_accessed = Time.now.utc
+          end
+
+          def decay
+            @strength = [(@strength - Constants::ANCHOR_DECAY), 0.0].max
+          end
+
+          def reinforce(observed_value:)
+            @last_accessed = Time.now.utc
+            alpha          = Constants::ADJUSTMENT_RATE
+            @value         = ((1.0 - alpha) * @value) + (alpha * observed_value.to_f)
+            @strength      = [@strength + 0.1, 1.0].min
+          end
+
+          def pull(estimate:)
+            weight = @strength * Constants::DEFAULT_ANCHOR_WEIGHT
+            (weight * @value) + ((1.0 - weight) * estimate.to_f)
+          end
+
+          def label
+            Constants::ANCHOR_LABELS.each do |range, lbl|
+              return lbl if range.cover?(@strength)
+            end
+            :fading
+          end
+
+          def to_h
+            {
+              id:            @id,
+              value:         @value,
+              domain:        @domain,
+              strength:      @strength,
+              label:         label,
+              created_at:    @created_at,
+              last_accessed: @last_accessed
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/anchoring/helpers/anchor_store.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Anchoring
+      module Helpers
+        class AnchorStore
+          include Constants
+
+          def initialize
+            @anchors    = {} # domain (Symbol) -> Array<Anchor>
+            @references = {} # domain (Symbol) -> Float (explicit reference point)
+          end
+
+          def add(value:, domain: :general)
+            domain = domain.to_sym
+            @anchors[domain] ||= []
+
+            anchor = Anchor.new(value: value, domain: domain)
+            @anchors[domain] << anchor
+
+            if @anchors[domain].size > Constants::MAX_ANCHORS_PER_DOMAIN
+              @anchors[domain] = @anchors[domain].sort_by(&:strength).last(Constants::MAX_ANCHORS_PER_DOMAIN)
+            end
+
+            prune_domains
+            anchor
+          end
+
+          def strongest(domain: :general)
+            domain   = domain.to_sym
+            anchors  = @anchors[domain]
+            return nil if anchors.nil? || anchors.empty?
+
+            anchors.max_by(&:strength)
+          end
+
+          def find(id:)
+            @anchors.each_value do |arr|
+              arr.each { |a| return a if a.id == id }
+            end
+            nil
+          end
+
+          def evaluate(estimate:, domain: :general)
+            domain  = domain.to_sym
+            anchor  = strongest(domain: domain)
+            return { anchored_estimate: estimate.to_f, pull_strength: 0.0, anchor_value: nil, correction: 0.0 } if anchor.nil?
+
+            anchored  = anchor.pull(estimate: estimate)
+            pull_str  = anchor.strength * Constants::DEFAULT_ANCHOR_WEIGHT
+            correction = estimate.to_f - anchored
+
+            anchor.reinforce(observed_value: estimate)
+
+            {
+              anchored_estimate: anchored,
+              pull_strength:     pull_str,
+              anchor_value:      anchor.value,
+              correction:        correction
+            }
+          end
+
+          def reference_frame(value:, domain: :general)
+            domain    = domain.to_sym
+            reference = @references[domain] || strongest(domain: domain)&.value
+            return { perceived_value: value.to_f, gain_or_loss: :neutral, magnitude: 0.0 } if reference.nil?
+
+            diff       = value.to_f - reference
+            gain_loss  = diff >= 0 ? :gain : :loss
+            raw_mag    = diff.abs
+            magnitude  = gain_loss == :loss ? raw_mag * Constants::LOSS_AVERSION_FACTOR : raw_mag
+
+            { perceived_value: value.to_f, gain_or_loss: gain_loss, magnitude: magnitude, reference: reference, raw_diff: diff }
+          end
+
+          def decay_all
+            pruned = 0
+            @anchors.each_value do |arr|
+              arr.each(&:decay)
+              before = arr.size
+              arr.reject! { |a| a.strength < Constants::ANCHOR_FLOOR }
+              pruned += (before - arr.size)
+            end
+            @anchors.reject! { |_, arr| arr.empty? }
+            pruned
+          end
+
+          def shift_reference(domain:, new_reference:)
+            domain              = domain.to_sym
+            old                 = @references[domain]
+            @references[domain] = new_reference.to_f
+
+            diff = (new_reference.to_f - old.to_f).abs
+            significant = diff >= Constants::REFERENCE_SHIFT_THRESHOLD
+
+            { domain: domain, old_reference: old, new_reference: new_reference.to_f, significant: significant }
+          end
+
+          def domains
+            @anchors.keys.select { |d| @anchors[d]&.any? }
+          end
+
+          def to_h
+            total_anchors = @anchors.values.flatten.size
+            domain_count  = domains.size
+
+            {
+              total_anchors: total_anchors,
+              domain_count:  domain_count,
+              domains:       domains,
+              references:    @references.dup
+            }
+          end
+
+          private
+
+          def prune_domains
+            return unless @anchors.size > Constants::MAX_DOMAINS
+
+            oldest_domain = @anchors.min_by { |_, arr| arr.map(&:last_accessed).min }&.first
+            @anchors.delete(oldest_domain) if oldest_domain
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Anchoring
+      module Helpers
+        module Constants
+          DEFAULT_ANCHOR_WEIGHT        = 0.6    # How much the anchor pulls toward itself
+          ADJUSTMENT_RATE              = 0.1    # EMA alpha for updating anchors
+          ANCHOR_DECAY                 = 0.02   # Per-tick decay of anchor strength
+          ANCHOR_FLOOR                 = 0.05   # Minimum anchor strength before pruning
+          MAX_ANCHORS_PER_DOMAIN       = 20     # Cap per domain
+          MAX_DOMAINS                  = 50     # Cap total domains
+          REFERENCE_SHIFT_THRESHOLD    = 0.3    # Gap needed to shift reference point
+          LOSS_AVERSION_FACTOR         = 2.25   # Losses weighted 2.25x vs gains (prospect theory)
+
+          ANCHOR_LABELS = {
+            (0.8..)     => :strong,
+            (0.5...0.8) => :moderate,
+            (0.2...0.5) => :weak,
+            (..0.2)     => :fading
+          }.freeze
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Anchoring
+      module Runners
+        module Anchoring
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def record_anchor(value:, domain: :general, **)
+            anchor = anchor_store.add(value: value, domain: domain)
+            Legion::Logging.debug "[anchoring] record_anchor domain=#{domain} value=#{value} id=#{anchor.id}"
+            { success: true, anchor: anchor.to_h }
+          end
+
+          def evaluate_estimate(estimate:, domain: :general, **)
+            result = anchor_store.evaluate(estimate: estimate, domain: domain)
+            Legion::Logging.debug "[anchoring] evaluate_estimate domain=#{domain} estimate=#{estimate} " \
+                                  "anchored=#{result[:anchored_estimate].round(4)} pull=#{result[:pull_strength].round(4)}"
+            { success: true }.merge(result)
+          end
+
+          def reference_frame(value:, domain: :general, **)
+            result = anchor_store.reference_frame(value: value, domain: domain)
+            Legion::Logging.debug "[anchoring] reference_frame domain=#{domain} value=#{value} " \
+                                  "gain_or_loss=#{result[:gain_or_loss]}"
+            { success: true }.merge(result)
+          end
+
+          def de_anchor(estimate:, domain: :general, **)
+            anchor = anchor_store.strongest(domain: domain)
+            if anchor.nil?
+              Legion::Logging.debug "[anchoring] de_anchor domain=#{domain} no anchor found"
+              return { success: true, corrected_estimate: estimate.to_f, anchor_bias: 0.0, domain: domain }
+            end
+
+            biased    = anchor.pull(estimate: estimate)
+            bias      = biased - estimate.to_f
+            corrected = estimate.to_f - bias
+
+            Legion::Logging.debug "[anchoring] de_anchor domain=#{domain} estimate=#{estimate} " \
+                                  "corrected=#{corrected.round(4)} bias=#{bias.round(4)}"
+
+            {
+              success:            true,
+              corrected_estimate: corrected,
+              original_estimate:  estimate.to_f,
+              anchor_bias:        bias,
+              anchor_value:       anchor.value,
+              domain:             domain
+            }
+          end
+
+          def shift_reference(domain:, new_reference:, **)
+            result = anchor_store.shift_reference(domain: domain, new_reference: new_reference)
+            Legion::Logging.info "[anchoring] shift_reference domain=#{domain} new=#{new_reference} significant=#{result[:significant]}"
+            { success: true }.merge(result)
+          end
+
+          def update_anchoring(**)
+            pruned = anchor_store.decay_all
+            Legion::Logging.debug "[anchoring] update_anchoring pruned=#{pruned}"
+            { success: true, pruned: pruned }
+          end
+
+          def domain_anchors(domain:, **)
+            domain   = domain.to_sym
+            anchor   = anchor_store.strongest(domain: domain)
+            all_list = anchor_store.instance_variable_get(:@anchors)[domain] || []
+            Legion::Logging.debug "[anchoring] domain_anchors domain=#{domain} count=#{all_list.size}"
+            {
+              success:   true,
+              domain:    domain,
+              count:     all_list.size,
+              strongest: anchor&.to_h,
+              anchors:   all_list.map(&:to_h)
+            }
+          end
+
+          def anchoring_stats(**)
+            stats = anchor_store.to_h
+            Legion::Logging.debug "[anchoring] stats domains=#{stats[:domain_count]} total=#{stats[:total_anchors]}"
+            { success: true }.merge(stats)
+          end
+
+          private
+
+          def anchor_store
+            @anchor_store ||= Helpers::AnchorStore.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/anchoring.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/anchoring/version'
+require 'legion/extensions/anchoring/helpers/constants'
+require 'legion/extensions/anchoring/helpers/anchor'
+require 'legion/extensions/anchoring/helpers/anchor_store'
+require 'legion/extensions/anchoring/runners/anchoring'
+
+module Legion
+  module Extensions
+    module Anchoring
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/anchoring/client'
+
+RSpec.describe Legion::Extensions::Anchoring::Client do
+  let(:client) { described_class.new }
+
+  it 'responds to all runner methods' do
+    expect(client).to respond_to(:record_anchor)
+    expect(client).to respond_to(:evaluate_estimate)
+    expect(client).to respond_to(:reference_frame)
+    expect(client).to respond_to(:de_anchor)
+    expect(client).to respond_to(:shift_reference)
+    expect(client).to respond_to(:update_anchoring)
+    expect(client).to respond_to(:domain_anchors)
+    expect(client).to respond_to(:anchoring_stats)
+  end
+
+  it 'exposes anchor_store' do
+    expect(client.anchor_store).to be_a(Legion::Extensions::Anchoring::Helpers::AnchorStore)
+  end
+
+  it 'accepts an external anchor_store' do
+    custom_store = Legion::Extensions::Anchoring::Helpers::AnchorStore.new
+    c = described_class.new(anchor_store: custom_store)
+    expect(c.anchor_store).to be(custom_store)
+  end
+
+  it 'accepts keyword splat arguments' do
+    expect { described_class.new(extra: :ignored) }.not_to raise_error
+  end
+end

data/spec/legion/extensions/anchoring/helpers/anchor_spec.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Anchoring::Helpers::Anchor do
+  subject(:anchor) { described_class.new(value: 100.0, domain: :financial) }
+
+  describe '#initialize' do
+    it 'sets value as float' do
+      expect(anchor.value).to eq(100.0)
+    end
+
+    it 'sets domain as symbol' do
+      expect(anchor.domain).to eq(:financial)
+    end
+
+    it 'sets initial strength to 1.0' do
+      expect(anchor.strength).to eq(1.0)
+    end
+
+    it 'generates a uuid id' do
+      expect(anchor.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets created_at' do
+      expect(anchor.created_at).to be_a(Time)
+    end
+
+    it 'sets last_accessed' do
+      expect(anchor.last_accessed).to be_a(Time)
+    end
+
+    it 'accepts integer value and converts to float' do
+      a = described_class.new(value: 50, domain: :general)
+      expect(a.value).to eq(50.0)
+    end
+
+    it 'defaults domain to :general when not specified' do
+      a = described_class.new(value: 10.0)
+      expect(a.domain).to eq(:general)
+    end
+  end
+
+  describe '#decay' do
+    it 'reduces strength by ANCHOR_DECAY' do
+      before = anchor.strength
+      anchor.decay
+      expect(anchor.strength).to be_within(0.001).of(before - Legion::Extensions::Anchoring::Helpers::Constants::ANCHOR_DECAY)
+    end
+
+    it 'does not go below 0.0' do
+      50.times { anchor.decay }
+      expect(anchor.strength).to eq(0.0)
+    end
+  end
+
+  describe '#reinforce' do
+    it 'updates the value toward observed_value via EMA' do
+      anchor.reinforce(observed_value: 200.0)
+      expect(anchor.value).to be > 100.0
+      expect(anchor.value).to be < 200.0
+    end
+
+    it 'bumps strength up (capped at 1.0)' do
+      anchor.decay
+      before = anchor.strength
+      anchor.reinforce(observed_value: 100.0)
+      expect(anchor.strength).to be > before
+    end
+
+    it 'updates last_accessed' do
+      before = anchor.last_accessed
+      sleep 0.001
+      anchor.reinforce(observed_value: 100.0)
+      expect(anchor.last_accessed).to be >= before
+    end
+  end
+
+  describe '#pull' do
+    it 'returns a value between anchor value and estimate' do
+      result = anchor.pull(estimate: 200.0)
+      expect(result).to be > 100.0
+      expect(result).to be < 200.0
+    end
+
+    it 'pulls estimate closer to anchor value' do
+      biased = anchor.pull(estimate: 200.0)
+      expect((biased - 100.0).abs).to be < (200.0 - 100.0).abs
+    end
+
+    it 'returns anchor value when estimate equals anchor value' do
+      result = anchor.pull(estimate: 100.0)
+      expect(result).to be_within(0.001).of(100.0)
+    end
+  end
+
+  describe '#label' do
+    it 'returns :strong at full strength' do
+      expect(anchor.label).to eq(:strong)
+    end
+
+    it 'returns :moderate at moderate strength' do
+      anchor.instance_variable_set(:@strength, 0.6)
+      expect(anchor.label).to eq(:moderate)
+    end
+
+    it 'returns :weak at weak strength' do
+      anchor.instance_variable_set(:@strength, 0.35)
+      expect(anchor.label).to eq(:weak)
+    end
+
+    it 'returns :fading at very low strength' do
+      anchor.instance_variable_set(:@strength, 0.1)
+      expect(anchor.label).to eq(:fading)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with all expected keys' do
+      h = anchor.to_h
+      expect(h).to include(:id, :value, :domain, :strength, :label, :created_at, :last_accessed)
+    end
+
+    it 'includes correct value' do
+      expect(anchor.to_h[:value]).to eq(100.0)
+    end
+
+    it 'includes label' do
+      expect(anchor.to_h[:label]).to eq(:strong)
+    end
+  end
+end

data/spec/legion/extensions/anchoring/helpers/anchor_store_spec.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Anchoring::Helpers::AnchorStore do
+  subject(:store) { described_class.new }
+
+  describe '#add' do
+    it 'creates and returns an Anchor' do
+      anchor = store.add(value: 50.0, domain: :financial)
+      expect(anchor).to be_a(Legion::Extensions::Anchoring::Helpers::Anchor)
+    end
+
+    it 'stores anchors per domain' do
+      store.add(value: 50.0, domain: :financial)
+      store.add(value: 80.0, domain: :financial)
+      store.add(value: 10.0, domain: :temporal)
+      expect(store.domains).to include(:financial, :temporal)
+    end
+
+    it 'enforces MAX_ANCHORS_PER_DOMAIN limit' do
+      max = Legion::Extensions::Anchoring::Helpers::Constants::MAX_ANCHORS_PER_DOMAIN
+      (max + 5).times { |i| store.add(value: i.to_f, domain: :financial) }
+      all = store.instance_variable_get(:@anchors)[:financial]
+      expect(all.size).to be <= max
+    end
+
+    it 'accepts integer value' do
+      anchor = store.add(value: 100, domain: :general)
+      expect(anchor.value).to eq(100.0)
+    end
+  end
+
+  describe '#strongest' do
+    it 'returns nil for unknown domain' do
+      expect(store.strongest(domain: :unknown)).to be_nil
+    end
+
+    it 'returns the anchor with highest strength' do
+      a1 = store.add(value: 10.0, domain: :financial)
+      a2 = store.add(value: 20.0, domain: :financial)
+      a1.instance_variable_set(:@strength, 0.3)
+      a2.instance_variable_set(:@strength, 0.9)
+      expect(store.strongest(domain: :financial).value).to eq(20.0)
+    end
+  end
+
+  describe '#find' do
+    it 'finds anchor by id' do
+      anchor = store.add(value: 42.0, domain: :general)
+      found  = store.find(id: anchor.id)
+      expect(found).to eq(anchor)
+    end
+
+    it 'returns nil for unknown id' do
+      expect(store.find(id: 'nonexistent')).to be_nil
+    end
+  end
+
+  describe '#evaluate' do
+    it 'returns no-pull result when domain has no anchors' do
+      result = store.evaluate(estimate: 100.0, domain: :empty)
+      expect(result[:pull_strength]).to eq(0.0)
+      expect(result[:anchored_estimate]).to eq(100.0)
+      expect(result[:anchor_value]).to be_nil
+    end
+
+    it 'returns biased estimate when anchor exists' do
+      store.add(value: 50.0, domain: :financial)
+      result = store.evaluate(estimate: 100.0, domain: :financial)
+      expect(result[:anchored_estimate]).to be > 50.0
+      expect(result[:anchored_estimate]).to be < 100.0
+    end
+
+    it 'includes pull_strength, anchor_value, correction keys' do
+      store.add(value: 50.0, domain: :financial)
+      result = store.evaluate(estimate: 100.0, domain: :financial)
+      expect(result).to include(:pull_strength, :anchor_value, :correction)
+    end
+
+    it 'correction is estimate minus anchored_estimate' do
+      store.add(value: 50.0, domain: :financial)
+      result = store.evaluate(estimate: 100.0, domain: :financial)
+      expect(result[:correction]).to be_within(0.001).of(100.0 - result[:anchored_estimate])
+    end
+  end
+
+  describe '#reference_frame' do
+    it 'returns neutral when no reference or anchor' do
+      result = store.reference_frame(value: 100.0, domain: :empty)
+      expect(result[:gain_or_loss]).to eq(:neutral)
+      expect(result[:magnitude]).to eq(0.0)
+    end
+
+    it 'detects gain when value above reference' do
+      store.shift_reference(domain: :financial, new_reference: 50.0)
+      result = store.reference_frame(value: 100.0, domain: :financial)
+      expect(result[:gain_or_loss]).to eq(:gain)
+      expect(result[:magnitude]).to be > 0
+    end
+
+    it 'detects loss when value below reference' do
+      store.shift_reference(domain: :financial, new_reference: 100.0)
+      result = store.reference_frame(value: 50.0, domain: :financial)
+      expect(result[:gain_or_loss]).to eq(:loss)
+    end
+
+    it 'applies loss aversion factor to losses' do
+      store.shift_reference(domain: :financial, new_reference: 100.0)
+      result = store.reference_frame(value: 50.0, domain: :financial)
+      raw_diff = 50.0
+      expected_magnitude = raw_diff * Legion::Extensions::Anchoring::Helpers::Constants::LOSS_AVERSION_FACTOR
+      expect(result[:magnitude]).to be_within(0.001).of(expected_magnitude)
+    end
+
+    it 'does not apply loss aversion to gains' do
+      store.shift_reference(domain: :financial, new_reference: 50.0)
+      result = store.reference_frame(value: 100.0, domain: :financial)
+      expect(result[:magnitude]).to be_within(0.001).of(50.0)
+    end
+
+    it 'uses anchor as implicit reference when no explicit reference set' do
+      store.add(value: 50.0, domain: :financial)
+      result = store.reference_frame(value: 100.0, domain: :financial)
+      expect(result[:gain_or_loss]).to eq(:gain)
+    end
+  end
+
+  describe '#decay_all' do
+    it 'decays all anchors and returns pruned count' do
+      store.add(value: 10.0, domain: :financial)
+      pruned = store.decay_all
+      expect(pruned).to be >= 0
+    end
+
+    it 'prunes anchors that fall below ANCHOR_FLOOR' do
+      anchor = store.add(value: 10.0, domain: :financial)
+      anchor.instance_variable_set(:@strength, Legion::Extensions::Anchoring::Helpers::Constants::ANCHOR_FLOOR - 0.001)
+      store.decay_all
+      expect(store.domains).not_to include(:financial)
+    end
+
+    it 'retains anchors above floor' do
+      store.add(value: 10.0, domain: :financial)
+      store.decay_all
+      all = store.instance_variable_get(:@anchors)[:financial]
+      expect(all).not_to be_nil
+    end
+  end
+
+  describe '#shift_reference' do
+    it 'sets new reference point for domain' do
+      store.shift_reference(domain: :financial, new_reference: 100.0)
+      refs = store.instance_variable_get(:@references)
+      expect(refs[:financial]).to eq(100.0)
+    end
+
+    it 'returns old and new reference' do
+      store.shift_reference(domain: :financial, new_reference: 50.0)
+      result = store.shift_reference(domain: :financial, new_reference: 100.0)
+      expect(result[:old_reference]).to eq(50.0)
+      expect(result[:new_reference]).to eq(100.0)
+    end
+
+    it 'marks shift as significant when diff >= REFERENCE_SHIFT_THRESHOLD' do
+      store.shift_reference(domain: :temporal, new_reference: 0.0)
+      result = store.shift_reference(domain: :temporal, new_reference: 1.0)
+      expect(result[:significant]).to be true
+    end
+
+    it 'marks shift as not significant when diff < REFERENCE_SHIFT_THRESHOLD' do
+      store.shift_reference(domain: :temporal, new_reference: 0.0)
+      result = store.shift_reference(domain: :temporal, new_reference: 0.1)
+      expect(result[:significant]).to be false
+    end
+  end
+
+  describe '#domains' do
+    it 'returns empty array when no anchors' do
+      expect(store.domains).to be_empty
+    end
+
+    it 'returns list of active domains' do
+      store.add(value: 1.0, domain: :financial)
+      store.add(value: 2.0, domain: :temporal)
+      expect(store.domains).to match_array(%i[financial temporal])
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns summary hash' do
+      store.add(value: 10.0, domain: :financial)
+      h = store.to_h
+      expect(h).to include(:total_anchors, :domain_count, :domains, :references)
+    end
+
+    it 'reflects correct total_anchors count' do
+      store.add(value: 10.0, domain: :financial)
+      store.add(value: 20.0, domain: :financial)
+      expect(store.to_h[:total_anchors]).to eq(2)
+    end
+  end
+end

data/spec/legion/extensions/anchoring/helpers/constants_spec.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Anchoring::Helpers::Constants do
+  it 'defines DEFAULT_ANCHOR_WEIGHT as 0.6' do
+    expect(described_module::DEFAULT_ANCHOR_WEIGHT).to eq(0.6)
+  end
+
+  it 'defines ADJUSTMENT_RATE as 0.1' do
+    expect(described_module::ADJUSTMENT_RATE).to eq(0.1)
+  end
+
+  it 'defines ANCHOR_DECAY as 0.02' do
+    expect(described_module::ANCHOR_DECAY).to eq(0.02)
+  end
+
+  it 'defines ANCHOR_FLOOR as 0.05' do
+    expect(described_module::ANCHOR_FLOOR).to eq(0.05)
+  end
+
+  it 'defines MAX_ANCHORS_PER_DOMAIN as 20' do
+    expect(described_module::MAX_ANCHORS_PER_DOMAIN).to eq(20)
+  end
+
+  it 'defines MAX_DOMAINS as 50' do
+    expect(described_module::MAX_DOMAINS).to eq(50)
+  end
+
+  it 'defines REFERENCE_SHIFT_THRESHOLD as 0.3' do
+    expect(described_module::REFERENCE_SHIFT_THRESHOLD).to eq(0.3)
+  end
+
+  it 'defines LOSS_AVERSION_FACTOR as 2.25' do
+    expect(described_module::LOSS_AVERSION_FACTOR).to eq(2.25)
+  end
+
+  it 'defines ANCHOR_LABELS with 4 entries' do
+    expect(described_module::ANCHOR_LABELS.size).to eq(4)
+  end
+
+  it 'ANCHOR_LABELS maps high strength to :strong' do
+    label = described_module::ANCHOR_LABELS.find { |range, _| range.cover?(0.9) }&.last
+    expect(label).to eq(:strong)
+  end
+
+  it 'ANCHOR_LABELS maps mid strength to :moderate' do
+    label = described_module::ANCHOR_LABELS.find { |range, _| range.cover?(0.6) }&.last
+    expect(label).to eq(:moderate)
+  end
+
+  it 'ANCHOR_LABELS maps low strength to :weak' do
+    label = described_module::ANCHOR_LABELS.find { |range, _| range.cover?(0.3) }&.last
+    expect(label).to eq(:weak)
+  end
+
+  it 'ANCHOR_LABELS maps very low strength to :fading' do
+    label = described_module::ANCHOR_LABELS.find { |range, _| range.cover?(0.1) }&.last
+    expect(label).to eq(:fading)
+  end
+
+  def described_module
+    Legion::Extensions::Anchoring::Helpers::Constants
+  end
+end

data/spec/legion/extensions/anchoring/runners/anchoring_spec.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/anchoring/client'
+
+RSpec.describe Legion::Extensions::Anchoring::Runners::Anchoring do
+  let(:client) { Legion::Extensions::Anchoring::Client.new }
+
+  describe '#record_anchor' do
+    it 'returns success: true' do
+      result = client.record_anchor(value: 100.0, domain: :financial)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns anchor hash' do
+      result = client.record_anchor(value: 100.0, domain: :financial)
+      expect(result[:anchor]).to include(:id, :value, :domain, :strength)
+    end
+
+    it 'uses :general domain by default' do
+      result = client.record_anchor(value: 50.0)
+      expect(result[:anchor][:domain]).to eq(:general)
+    end
+
+    it 'accepts keyword splat' do
+      expect { client.record_anchor(value: 10.0, extra: :ignored) }.not_to raise_error
+    end
+  end
+
+  describe '#evaluate_estimate' do
+    it 'returns success: true' do
+      result = client.evaluate_estimate(estimate: 100.0, domain: :financial)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns no-pull when domain has no anchors' do
+      result = client.evaluate_estimate(estimate: 100.0, domain: :noanchor)
+      expect(result[:pull_strength]).to eq(0.0)
+      expect(result[:anchored_estimate]).to eq(100.0)
+    end
+
+    it 'biases estimate toward anchor when anchor exists' do
+      client.record_anchor(value: 50.0, domain: :financial)
+      result = client.evaluate_estimate(estimate: 100.0, domain: :financial)
+      expect(result[:anchored_estimate]).to be < 100.0
+      expect(result[:anchored_estimate]).to be > 50.0
+    end
+
+    it 'includes pull_strength, anchor_value, correction' do
+      client.record_anchor(value: 50.0, domain: :financial)
+      result = client.evaluate_estimate(estimate: 100.0, domain: :financial)
+      expect(result).to include(:pull_strength, :anchor_value, :correction)
+    end
+  end
+
+  describe '#reference_frame' do
+    it 'returns success: true' do
+      result = client.reference_frame(value: 100.0, domain: :financial)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns neutral for domain without reference' do
+      result = client.reference_frame(value: 100.0, domain: :empty_domain)
+      expect(result[:gain_or_loss]).to eq(:neutral)
+    end
+
+    it 'detects gain after setting reference' do
+      client.shift_reference(domain: :financial, new_reference: 50.0)
+      result = client.reference_frame(value: 100.0, domain: :financial)
+      expect(result[:gain_or_loss]).to eq(:gain)
+    end
+
+    it 'detects loss after setting reference' do
+      client.shift_reference(domain: :financial, new_reference: 100.0)
+      result = client.reference_frame(value: 50.0, domain: :financial)
+      expect(result[:gain_or_loss]).to eq(:loss)
+    end
+
+    it 'applies loss aversion factor to losses' do
+      client.shift_reference(domain: :financial, new_reference: 100.0)
+      result = client.reference_frame(value: 50.0, domain: :financial)
+      expect(result[:magnitude]).to be_within(0.001).of(50.0 * 2.25)
+    end
+  end
+
+  describe '#de_anchor' do
+    it 'returns success: true' do
+      result = client.de_anchor(estimate: 100.0, domain: :empty_de)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns original estimate with zero bias when no anchor' do
+      result = client.de_anchor(estimate: 100.0, domain: :no_anchor_domain)
+      expect(result[:corrected_estimate]).to eq(100.0)
+      expect(result[:anchor_bias]).to eq(0.0)
+    end
+
+    it 'returns corrected estimate that removes anchor bias' do
+      client.record_anchor(value: 50.0, domain: :financial)
+      result = client.de_anchor(estimate: 100.0, domain: :financial)
+      expect(result[:corrected_estimate]).to be > 100.0
+    end
+
+    it 'returns anchor_value when anchor present' do
+      client.record_anchor(value: 50.0, domain: :financial)
+      result = client.de_anchor(estimate: 100.0, domain: :financial)
+      expect(result[:anchor_value]).to eq(50.0)
+    end
+
+    it 'includes original_estimate' do
+      client.record_anchor(value: 50.0, domain: :financial)
+      result = client.de_anchor(estimate: 100.0, domain: :financial)
+      expect(result[:original_estimate]).to eq(100.0)
+    end
+  end
+
+  describe '#shift_reference' do
+    it 'returns success: true' do
+      result = client.shift_reference(domain: :financial, new_reference: 100.0)
+      expect(result[:success]).to be true
+    end
+
+    it 'includes domain, old_reference, new_reference, significant' do
+      result = client.shift_reference(domain: :financial, new_reference: 100.0)
+      expect(result).to include(:domain, :old_reference, :new_reference, :significant)
+    end
+
+    it 'marks large shift as significant' do
+      client.shift_reference(domain: :financial, new_reference: 0.0)
+      result = client.shift_reference(domain: :financial, new_reference: 1.0)
+      expect(result[:significant]).to be true
+    end
+  end
+
+  describe '#update_anchoring' do
+    it 'returns success: true' do
+      result = client.update_anchoring
+      expect(result[:success]).to be true
+    end
+
+    it 'returns pruned count' do
+      result = client.update_anchoring
+      expect(result).to have_key(:pruned)
+    end
+
+    it 'decays existing anchors' do
+      client.record_anchor(value: 100.0, domain: :financial)
+      anchor = client.anchor_store.strongest(domain: :financial)
+      before_strength = anchor.strength
+      client.update_anchoring
+      expect(anchor.strength).to be < before_strength
+    end
+  end
+
+  describe '#domain_anchors' do
+    it 'returns success: true' do
+      result = client.domain_anchors(domain: :financial)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns empty anchors for unknown domain' do
+      result = client.domain_anchors(domain: :no_such_domain)
+      expect(result[:count]).to eq(0)
+      expect(result[:anchors]).to eq([])
+    end
+
+    it 'returns anchors for known domain' do
+      client.record_anchor(value: 100.0, domain: :financial)
+      result = client.domain_anchors(domain: :financial)
+      expect(result[:count]).to eq(1)
+      expect(result[:anchors].first[:value]).to eq(100.0)
+    end
+
+    it 'includes strongest anchor' do
+      client.record_anchor(value: 100.0, domain: :financial)
+      result = client.domain_anchors(domain: :financial)
+      expect(result[:strongest]).not_to be_nil
+    end
+  end
+
+  describe '#anchoring_stats' do
+    it 'returns success: true' do
+      result = client.anchoring_stats
+      expect(result[:success]).to be true
+    end
+
+    it 'includes total_anchors, domain_count, domains' do
+      result = client.anchoring_stats
+      expect(result).to include(:total_anchors, :domain_count, :domains)
+    end
+
+    it 'reflects anchor counts' do
+      client.record_anchor(value: 10.0, domain: :financial)
+      client.record_anchor(value: 20.0, domain: :temporal)
+      result = client.anchoring_stats
+      expect(result[:total_anchors]).to eq(2)
+      expect(result[:domain_count]).to eq(2)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+module Legion
+  module Logging
+    def self.debug(_msg); end
+    def self.info(_msg); end
+    def self.warn(_msg); end
+    def self.error(_msg); end
+  end
+
+  module Extensions
+    module Helpers
+      module Lex; end
+    end
+  end
+end
+
+require 'legion/extensions/anchoring'
+require 'legion/extensions/anchoring/client'
+
+RSpec.configure do |config|
+  config.example_status_persistence_file_path = '.rspec_status'
+  config.disable_monkey_patching!
+  config.expect_with(:rspec) { |c| c.syntax = :expect }
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: lex-anchoring
+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: Decision anchoring and reference point effects for brain-modeled agentic
+  AI
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENSE
+- README.md
+- lex-anchoring.gemspec
+- lib/legion/extensions/anchoring.rb
+- lib/legion/extensions/anchoring/client.rb
+- lib/legion/extensions/anchoring/helpers/anchor.rb
+- lib/legion/extensions/anchoring/helpers/anchor_store.rb
+- lib/legion/extensions/anchoring/helpers/constants.rb
+- lib/legion/extensions/anchoring/runners/anchoring.rb
+- lib/legion/extensions/anchoring/version.rb
+- spec/legion/extensions/anchoring/client_spec.rb
+- spec/legion/extensions/anchoring/helpers/anchor_spec.rb
+- spec/legion/extensions/anchoring/helpers/anchor_store_spec.rb
+- spec/legion/extensions/anchoring/helpers/constants_spec.rb
+- spec/legion/extensions/anchoring/runners/anchoring_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-anchoring
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-anchoring
+  source_code_uri: https://github.com/LegionIO/lex-anchoring
+  documentation_uri: https://github.com/LegionIO/lex-anchoring
+  changelog_uri: https://github.com/LegionIO/lex-anchoring
+  bug_tracker_uri: https://github.com/LegionIO/lex-anchoring/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 Anchoring
+test_files: []