lex-cognitive-gravity 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3b5fd5b947f6fdcf87b9a1ea06d1ea1c7d4751b0374710f1a31dbdd776415992
+  data.tar.gz: 79e9aa02e8a16d53fc050806e2f2a12b4a8f6fc46a23eaa6be6ad136ae9a21e4
+SHA512:
+  metadata.gz: 2f0efb7bc240c78ce18cf5f2db4ce2821cadcdc19af7b16850e5170b896abebe3dd68826a69bd1b1be2d6271de5e67e4c04c2b89dd9d08de3c635786a673da61
+  data.tar.gz: 0311d5bec4510aa19a4fdfe49c3cd4a0ba6b8c9d3aef9e31bde14ea9f70de7e39e7bf7f1a6206f7963205c751f05099e8a50dadb23daff8df0ae00c9ab66f5aa

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,3 @@
+--format documentation
+--color
+--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/ParameterLists:
+  Max: 8
+  MaxOptionalParameters: 8
+
+Metrics/CyclomaticComplexity:
+  Max: 15
+
+Metrics/PerceivedComplexity:
+  Max: 17
+
+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,123 @@
+# lex-cognitive-gravity
+
+**Level 3 Leaf Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/extensions-agentic/CLAUDE.md`
+- **Gem**: `lex-cognitive-gravity`
+
+## Purpose
+
+Models attractor dynamics in cognition. Attractors are high-mass cognitive concepts that exert gravitational pull on orbiting thoughts. Thoughts within an attractor's capture radius are pulled in; those too distant escape. Each simulation tick determines captures and escapes based on mass and orbital distance. Attractors gain mass through accretion (reinforcement) and lose mass through erosion (decay). Collapsed attractors (mass < COLLAPSE_THRESHOLD) can no longer capture thoughts. Supermassive attractors (mass >= SUPERMASSIVE_THRESHOLD) have extended capture radius.
+
+## Gem Info
+
+| Field | Value |
+|---|---|
+| Gem name | `lex-cognitive-gravity` |
+| Version | `0.1.0` |
+| Namespace | `Legion::Extensions::CognitiveGravity` |
+| Ruby | `>= 3.4` |
+| License | MIT |
+| GitHub | https://github.com/LegionIO/lex-cognitive-gravity |
+
+## File Structure
+
+```
+lib/legion/extensions/cognitive_gravity/
+  cognitive_gravity.rb              # Top-level require
+  version.rb                        # VERSION = '0.1.0'
+  client.rb                         # Client class
+  helpers/
+    constants.rb                    # Attractor domains, mass/density/orbit labels, thresholds
+    attractor.rb                    # Attractor value object
+    orbiting_thought.rb             # OrbitingThought value object
+    gravity_engine.rb               # Engine: attractors, thoughts, tick, accretion, erosion
+  runners/
+    gravity.rb                      # Runner module
+```
+
+## Key Constants
+
+| Constant | Value | Meaning |
+|---|---|---|
+| `MAX_ATTRACTORS` | 200 | Attractor cap |
+| `MAX_ORBITING` | 500 | Orbiting thought cap |
+| `DEFAULT_MASS` | 1.0 | Starting attractor mass |
+| `MASS_ACCRETION` | 0.15 | Mass increase per accretion call |
+| `MASS_EROSION` | 0.05 | Mass decrease per erosion call |
+| `CAPTURE_RADIUS` | 0.2 | Default orbital radius within which thoughts are captured |
+| `COLLAPSE_THRESHOLD` | 0.1 | Mass below this = collapsed; cannot capture |
+| `SUPERMASSIVE_THRESHOLD` | 3.0 | Mass above this = supermassive; extended capture radius |
+| `ATTRACTOR_DOMAINS` | array | `[:fear, :desire, :belief, :habit, :memory, :identity, :goal, :trauma]` |
+| `MASS_LABELS` | hash | `supermassive` (3.0+) through `collapsed` |
+| `DENSITY_LABELS` | hash | `dense` (0.8+) through `sparse` |
+| `ORBIT_LABELS` | hash | `captured` through `escaped` |
+
+## Helpers
+
+### `Attractor`
+
+A dominant cognitive concept with gravitational mass.
+
+- `initialize(domain:, content:, mass: DEFAULT_MASS, attractor_id: nil)`
+- `accrete!(rate)` — increases mass by `MASS_ACCRETION`
+- `erode!(rate)` — decreases mass by `MASS_EROSION`, floor 0.0
+- `collapsed?` — mass < `COLLAPSE_THRESHOLD`
+- `supermassive?` — mass >= `SUPERMASSIVE_THRESHOLD`
+- `capture_radius` — extended if supermassive
+- `mass_label`
+- `to_h`
+
+### `OrbitingThought`
+
+A cognitive element in orbital relationship with an attractor.
+
+- `initialize(content:, domain:, orbital_distance: 0.5, thought_id: nil)`
+- `captured?` — orbital_distance <= attractor's capture_radius
+- `escaped?` — orbital_distance > 1.0
+- `to_h`
+
+### `GravityEngine`
+
+- `add_attractor(domain:, content:, mass: DEFAULT_MASS)` — returns `{ added:, attractor_id:, attractor: }` or capacity error
+- `add_orbiting_thought(content:, domain:, orbital_distance: 0.5)` — returns `{ added:, thought_id:, thought: }` or capacity error
+- `simulate_tick` — for each non-collapsed attractor, evaluates all thoughts within capture radius (captures) and marks distant thoughts (escapes); returns capture/escape counts
+- `accrete_attractor(attractor_id:)` — increases mass
+- `erode_attractor(attractor_id:)` — decreases mass
+- `strongest_attractors(limit: 10)` — sorted by mass descending
+- `cognitive_density_map` — domain -> mean mass map
+- `gravity_report` — full stats
+
+## Runners
+
+**Module**: `Legion::Extensions::CognitiveGravity::Runners::Gravity`
+
+| Method | Key Args | Returns |
+|---|---|---|
+| `create_attractor` | `domain:`, `content:`, `mass: DEFAULT_MASS` | `{ success:, attractor_id:, attractor: }` |
+| `add_thought` | `content:`, `domain:`, `orbital_distance: 0.5` | `{ success:, thought_id:, thought: }` |
+| `tick_gravity` | — | `{ success:, captures:, escapes: }` |
+| `accrete` | `attractor_id:` | `{ success:, mass:, label: }` |
+| `erode` | `attractor_id:` | `{ success:, mass:, label: }` |
+| `strongest_attractors` | `limit: 10` | `{ success:, attractors: }` |
+| `thought_distribution` | — | `{ success:, distribution: }` |
+| `cognitive_density_map` | — | `{ success:, density_map: }` |
+| `gravity_report` | — | Full report hash |
+
+Private: `gravity_engine` — memoized `GravityEngine`. Logs via `log_debug` helper.
+
+## Integration Points
+
+- **`lex-memory`**: High-mass attractors correspond to high-strength memory traces. `simulate_tick` results (captured thoughts) can reinforce corresponding memory traces.
+- **`lex-emotion`**: Attractor domains map to emotional categories (`:fear`, `:desire`). Strong emotional valence from `lex-emotion` can trigger accretion of matching domain attractors.
+- **`lex-cognitive-inertia`**: Entrenched beliefs in `lex-cognitive-inertia` correspond to high-mass attractors in gravity. Both model resistance to change in different metaphors.
+
+## Development Notes
+
+- `simulate_tick` is an O(attractors × thoughts) operation. With MAX_ATTRACTORS=200 and MAX_ORBITING=500, the worst case is 100,000 comparisons per tick. Keep attractor and thought counts reasonable for performance.
+- Collapsed attractors (`mass < 0.1`) are skipped during tick but remain in the store. Callers should prune collapsed attractors periodically.
+- `add_orbiting_thought` assigns a random orbital distance if none is provided; callers can provide explicit distance for deterministic behavior.
+- In-memory only.
+
+---
+
+**Maintained By**: Matthew Iverson (@Esity)

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,47 @@
+# lex-cognitive-gravity
+
+Cognitive attractor dynamics engine for brain-modeled agentic AI in the LegionIO ecosystem.
+
+## What It Does
+
+Models gravitational attraction in thought space. Attractors are dominant cognitive concepts (fears, desires, beliefs, habits, goals) with mass that exerts pull on orbiting thoughts. Each simulation tick evaluates which thoughts fall within an attractor's capture radius (pulled in) and which escape. Attractors gain mass through accretion (reinforcement) and lose mass through erosion (decay). Collapsed attractors (mass below 0.1) can no longer capture thoughts. Supermassive attractors (mass >= 3.0) have extended capture radius.
+
+## Usage
+
+```ruby
+require 'legion/extensions/cognitive_gravity'
+
+client = Legion::Extensions::CognitiveGravity::Client.new
+
+# Create a dominant attractor concept
+result = client.create_attractor(domain: :goal, content: 'build reliable distributed system', mass: 2.0)
+attractor_id = result[:attractor_id]
+
+# Add orbiting thoughts
+client.add_thought(content: 'consider retry backoff strategy', domain: :goal, orbital_distance: 0.15)
+client.add_thought(content: 'unrelated distraction', domain: :habit, orbital_distance: 0.8)
+
+# Simulate gravitational tick
+client.tick_gravity
+# => { success: true, captures: 1, escapes: 0 }
+
+# Strengthen an attractor
+client.accrete(attractor_id: attractor_id)
+# => { success: true, mass: 2.15, label: :heavy }
+
+# See strongest attractors
+client.strongest_attractors(limit: 5)
+# => { success: true, attractors: [...] }
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-cognitive-gravity.gemspec

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_gravity/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-gravity'
+  spec.version       = Legion::Extensions::CognitiveGravity::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Cognitive Gravity'
+  spec.description   = 'Attractor basins in thought space — cognitive gravity wells for LegionIO agentic AI'
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-gravity'
+  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-gravity'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-cognitive-gravity'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-cognitive-gravity'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-cognitive-gravity/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = `git ls-files -z`.split("\x0").reject { |f| f.start_with?('spec/') }
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_gravity/helpers/constants'
+require 'legion/extensions/cognitive_gravity/helpers/attractor'
+require 'legion/extensions/cognitive_gravity/helpers/orbiting_thought'
+require 'legion/extensions/cognitive_gravity/helpers/gravity_engine'
+require 'legion/extensions/cognitive_gravity/runners/gravity'
+
+module Legion
+  module Extensions
+    module CognitiveGravity
+      class Client
+        include Runners::Gravity
+
+        def initialize(**)
+          @gravity_engine = Helpers::GravityEngine.new
+        end
+
+        private
+
+        attr_reader :gravity_engine
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_gravity/helpers/attractor.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveGravity
+      module Helpers
+        class Attractor
+          attr_reader :id, :content, :domain, :mass, :pull_radius, :decay_rate, :created_at, :reinforcement_count
+
+          def initialize(content:, domain: :unknown, mass: Constants::DEFAULT_MASS,
+                         pull_radius: 1.0, decay_rate: 0.01)
+            @id                  = SecureRandom.uuid
+            @content             = content
+            @domain              = domain
+            @mass                = mass.to_f.round(10)
+            @pull_radius         = pull_radius.clamp(0.01, Float::INFINITY)
+            @decay_rate          = decay_rate.clamp(0.0, 1.0)
+            @created_at          = Time.now.utc
+            @reinforcement_count = 0
+          end
+
+          def accrete!(amount = Constants::MASS_ACCRETION)
+            @mass = (@mass + amount.to_f).round(10)
+            @reinforcement_count += 1
+            self
+          end
+
+          def erode!(amount = Constants::MASS_EROSION)
+            @mass = [(@mass - amount.to_f).round(10), 0.0].max
+            self
+          end
+
+          def pull_strength_at(distance:)
+            return 0.0 if distance <= 0 || distance > @pull_radius
+
+            raw = (Constants::PULL_CONSTANT * @mass) / (distance**2)
+            raw.clamp(0.0, @mass)
+          end
+
+          def collapsed?
+            @mass < Constants::COLLAPSE_THRESHOLD
+          end
+
+          def supermassive?
+            @mass >= Constants::SUPERMASSIVE_THRESHOLD
+          end
+
+          def mass_label
+            Constants.label_for(Constants::MASS_LABELS, @mass)
+          end
+
+          def to_h
+            {
+              id:                  @id,
+              content:             @content,
+              domain:              @domain,
+              mass:                @mass,
+              pull_radius:         @pull_radius,
+              decay_rate:          @decay_rate,
+              reinforcement_count: @reinforcement_count,
+              collapsed:           collapsed?,
+              supermassive:        supermassive?,
+              mass_label:          mass_label,
+              created_at:          @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveGravity
+      module Helpers
+        module Constants
+          MAX_ATTRACTORS   = 200
+          MAX_ORBITING     = 500
+          DEFAULT_MASS     = 1.0
+          MASS_ACCRETION   = 0.15
+          MASS_EROSION     = 0.05
+          CAPTURE_RADIUS   = 0.2
+          ESCAPE_RADIUS    = 1.5
+          PULL_CONSTANT    = 0.1
+          COLLAPSE_THRESHOLD     = 0.1
+          SUPERMASSIVE_THRESHOLD = 3.0
+
+          ATTRACTOR_DOMAINS = %i[
+            problem
+            curiosity
+            anxiety
+            obsession
+            interest
+            fear
+            desire
+            unknown
+          ].freeze
+
+          MASS_LABELS = {
+            (0.0..0.1)             => :collapsing,
+            (0.1..0.5)             => :weak,
+            (0.5..1.0)             => :nascent,
+            (1.0..2.0)             => :moderate,
+            (2.0..3.0)             => :strong,
+            (3.0..Float::INFINITY) => :supermassive
+          }.freeze
+
+          DENSITY_LABELS = {
+            (0..0)                => :empty,
+            (1..2)                => :sparse,
+            (3..5)                => :light,
+            (6..10)               => :moderate,
+            (11..20)              => :dense,
+            (21..Float::INFINITY) => :crowded
+          }.freeze
+
+          ORBIT_LABELS = {
+            (0.0..0.2)             => :captured,
+            (0.2..0.5)             => :tight,
+            (0.5..1.0)             => :stable,
+            (1.0..1.5)             => :loose,
+            (1.5..Float::INFINITY) => :escaped
+          }.freeze
+
+          module_function
+
+          def label_for(labels_hash, value)
+            labels_hash.each do |range, label|
+              return label if range.cover?(value)
+            end
+            :unknown
+          end
+
+          def valid_domain?(domain)
+            ATTRACTOR_DOMAINS.include?(domain)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_gravity/helpers/gravity_engine.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveGravity
+      module Helpers
+        class GravityEngine
+          attr_reader :attractors, :orbiting_thoughts, :capture_events, :escape_events
+
+          def initialize
+            @attractors = {}
+            @orbiting_thoughts = {}
+            @capture_events   = []
+            @escape_events    = []
+          end
+
+          def add_attractor(content:, domain: :unknown, mass: Constants::DEFAULT_MASS,
+                            pull_radius: 1.0, decay_rate: 0.01)
+            return { error: :capacity_exceeded, max: Constants::MAX_ATTRACTORS } if at_attractor_capacity?
+
+            attractor = Attractor.new(
+              content:     content,
+              domain:      domain,
+              mass:        mass,
+              pull_radius: pull_radius,
+              decay_rate:  decay_rate
+            )
+            @attractors[attractor.id] = attractor
+            attractor
+          end
+
+          def add_orbiting_thought(content:, attractor_id:, orbital_distance: 1.0, velocity: 0.0)
+            return { error: :attractor_not_found } unless @attractors.key?(attractor_id)
+            return { error: :capacity_exceeded, max: Constants::MAX_ORBITING } if at_orbiting_capacity?
+
+            thought = OrbitingThought.new(
+              content:          content,
+              attractor_id:     attractor_id,
+              orbital_distance: orbital_distance,
+              velocity:         velocity
+            )
+            @orbiting_thoughts[thought.id] = thought
+            thought
+          end
+
+          def simulate_tick
+            captures = []
+            escapes  = []
+
+            @attractors.each_value do |attractor|
+              next if attractor.collapsed?
+
+              thoughts_for(attractor.id).each do |thought|
+                pull = attractor.pull_strength_at(distance: thought.orbital_distance)
+                next unless pull.positive?
+
+                was_captured = thought.captured?
+                was_escaped  = thought.escaped?
+
+                thought.approach!(pull)
+
+                if !was_captured && thought.captured?
+                  event = build_event(:capture, attractor, thought)
+                  captures << event
+                  @capture_events << event
+                end
+
+                next unless !was_escaped && thought.escaped?
+
+                event = build_event(:escape, attractor, thought)
+                escapes << event
+                @escape_events << event
+              end
+            end
+
+            { captures: captures, escapes: escapes, tick_processed: true }
+          end
+
+          def accrete_attractor(attractor_id, amount: Constants::MASS_ACCRETION)
+            attractor = @attractors[attractor_id]
+            return { error: :not_found } unless attractor
+
+            attractor.accrete!(amount)
+            { accreted: true, id: attractor_id, mass: attractor.mass }
+          end
+
+          def erode_attractor(attractor_id, amount: Constants::MASS_EROSION)
+            attractor = @attractors[attractor_id]
+            return { error: :not_found } unless attractor
+
+            attractor.erode!(amount)
+            { eroded: true, id: attractor_id, mass: attractor.mass, collapsed: attractor.collapsed? }
+          end
+
+          def strongest_attractors(limit: 5)
+            @attractors.values
+                       .reject(&:collapsed?)
+                       .sort_by { |a| -a.mass }
+                       .first(limit)
+          end
+
+          def thought_distribution
+            @attractors.transform_values { |a| thoughts_for(a.id).size }
+          end
+
+          def cognitive_density_map
+            thought_distribution.transform_values do |count|
+              Constants.label_for(Constants::DENSITY_LABELS, count)
+            end
+          end
+
+          def gravity_report
+            collapsed, active = @attractors.values.partition(&:collapsed?)
+            supermass = @attractors.values.select(&:supermassive?)
+            captured  = @orbiting_thoughts.values.select(&:captured?)
+            escaped   = @orbiting_thoughts.values.select(&:escaped?)
+
+            {
+              total_attractors:     @attractors.size,
+              active_attractors:    active.size,
+              collapsed_attractors: collapsed.size,
+              supermassive_count:   supermass.size,
+              total_orbiting:       @orbiting_thoughts.size,
+              captured_count:       captured.size,
+              escaped_count:        escaped.size,
+              total_captures:       @capture_events.size,
+              total_escapes:        @escape_events.size,
+              strongest:            strongest_attractors(limit: 3).map(&:to_h)
+            }
+          end
+
+          private
+
+          def thoughts_for(attractor_id)
+            @orbiting_thoughts.values.select { |t| t.attractor_id == attractor_id }
+          end
+
+          def at_attractor_capacity?
+            @attractors.size >= Constants::MAX_ATTRACTORS
+          end
+
+          def at_orbiting_capacity?
+            @orbiting_thoughts.size >= Constants::MAX_ORBITING
+          end
+
+          def build_event(type, attractor, thought)
+            {
+              type:         type,
+              attractor_id: attractor.id,
+              thought_id:   thought.id,
+              mass:         attractor.mass,
+              distance:     thought.orbital_distance,
+              at:           Time.now.utc
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_gravity/helpers/orbiting_thought.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveGravity
+      module Helpers
+        class OrbitingThought
+          attr_reader :id, :content, :attractor_id, :orbital_distance, :velocity, :created_at
+
+          def initialize(content:, attractor_id:, orbital_distance: 1.0, velocity: 0.0)
+            @id               = SecureRandom.uuid
+            @content          = content
+            @attractor_id     = attractor_id
+            @orbital_distance = orbital_distance.clamp(0.0, Float::INFINITY).round(10)
+            @velocity         = velocity.to_f.round(10)
+            @created_at       = Time.now.utc
+          end
+
+          def approach!(delta)
+            @orbital_distance = [(@orbital_distance - delta.abs).round(10), 0.0].max
+            self
+          end
+
+          def escape!(delta)
+            @orbital_distance = (@orbital_distance + delta.abs).round(10)
+            self
+          end
+
+          def captured?
+            @orbital_distance < Constants::CAPTURE_RADIUS
+          end
+
+          def escaped?
+            @orbital_distance > Constants::ESCAPE_RADIUS
+          end
+
+          def orbit_label
+            Constants.label_for(Constants::ORBIT_LABELS, @orbital_distance)
+          end
+
+          def to_h
+            {
+              id:               @id,
+              content:          @content,
+              attractor_id:     @attractor_id,
+              orbital_distance: @orbital_distance,
+              velocity:         @velocity,
+              captured:         captured?,
+              escaped:          escaped?,
+              orbit_label:      orbit_label,
+              created_at:       @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_gravity/runners/gravity.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveGravity
+      module Runners
+        module Gravity
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def create_attractor(content:, domain: :unknown, mass: Helpers::Constants::DEFAULT_MASS,
+                               pull_radius: 1.0, decay_rate: 0.01, engine: nil, **)
+            eng = engine || gravity_engine
+            unless Helpers::Constants.valid_domain?(domain)
+              return { success: false, error: :invalid_domain,
+                       valid_domains: Helpers::Constants::ATTRACTOR_DOMAINS }
+            end
+
+            result = eng.add_attractor(
+              content:     content,
+              domain:      domain,
+              mass:        mass,
+              pull_radius: pull_radius,
+              decay_rate:  decay_rate
+            )
+
+            if result.is_a?(Hash) && result[:error]
+              Legion::Logging.warn "[cognitive_gravity] create_attractor failed: #{result[:error]}"
+              return { success: false, **result }
+            end
+
+            Legion::Logging.debug "[cognitive_gravity] attractor created id=#{result.id[0..7]} " \
+                                  "domain=#{domain} mass=#{mass}"
+            { success: true, attractor: result.to_h }
+          end
+
+          def add_thought(content:, attractor_id:, orbital_distance: 1.0, velocity: 0.0,
+                          engine: nil, **)
+            eng = engine || gravity_engine
+            result = eng.add_orbiting_thought(
+              content:          content,
+              attractor_id:     attractor_id,
+              orbital_distance: orbital_distance,
+              velocity:         velocity
+            )
+
+            if result.is_a?(Hash) && result[:error]
+              Legion::Logging.warn "[cognitive_gravity] add_thought failed: #{result[:error]}"
+              return { success: false, **result }
+            end
+
+            Legion::Logging.debug "[cognitive_gravity] thought added id=#{result.id[0..7]} " \
+                                  "attractor=#{attractor_id[0..7]} distance=#{orbital_distance}"
+            { success: true, thought: result.to_h }
+          end
+
+          def tick_gravity(engine: nil, **)
+            eng = engine || gravity_engine
+            result = eng.simulate_tick
+            Legion::Logging.debug "[cognitive_gravity] tick: captures=#{result[:captures].size} " \
+                                  "escapes=#{result[:escapes].size}"
+            { success: true, **result }
+          end
+
+          def accrete(attractor_id:, amount: Helpers::Constants::MASS_ACCRETION, engine: nil, **)
+            eng = engine || gravity_engine
+            result = eng.accrete_attractor(attractor_id, amount: amount)
+
+            if result[:error]
+              Legion::Logging.warn "[cognitive_gravity] accrete failed: #{result[:error]}"
+              return { success: false, **result }
+            end
+
+            Legion::Logging.debug "[cognitive_gravity] accreted id=#{attractor_id[0..7]} mass=#{result[:mass]}"
+            { success: true, **result }
+          end
+
+          def erode(attractor_id:, amount: Helpers::Constants::MASS_EROSION, engine: nil, **)
+            eng = engine || gravity_engine
+            result = eng.erode_attractor(attractor_id, amount: amount)
+
+            if result[:error]
+              Legion::Logging.warn "[cognitive_gravity] erode failed: #{result[:error]}"
+              return { success: false, **result }
+            end
+
+            Legion::Logging.debug "[cognitive_gravity] eroded id=#{attractor_id[0..7]} " \
+                                  "mass=#{result[:mass]} collapsed=#{result[:collapsed]}"
+            { success: true, **result }
+          end
+
+          def strongest_attractors(limit: 5, engine: nil, **)
+            eng = engine || gravity_engine
+            attractors = eng.strongest_attractors(limit: limit)
+            Legion::Logging.debug "[cognitive_gravity] strongest_attractors count=#{attractors.size}"
+            { success: true, attractors: attractors.map(&:to_h), count: attractors.size }
+          end
+
+          def thought_distribution(engine: nil, **)
+            eng = engine || gravity_engine
+            distribution = eng.thought_distribution
+            { success: true, distribution: distribution }
+          end
+
+          def cognitive_density_map(engine: nil, **)
+            eng = engine || gravity_engine
+            density_map = eng.cognitive_density_map
+            { success: true, density_map: density_map }
+          end
+
+          def gravity_report(engine: nil, **)
+            eng = engine || gravity_engine
+            report = eng.gravity_report
+            Legion::Logging.debug "[cognitive_gravity] report: attractors=#{report[:total_attractors]} " \
+                                  "orbiting=#{report[:total_orbiting]} supermassive=#{report[:supermassive_count]}"
+            { success: true, report: report }
+          end
+
+          private
+
+          def gravity_engine
+            @gravity_engine ||= Helpers::GravityEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/cognitive_gravity.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_gravity/version'
+require 'legion/extensions/cognitive_gravity/helpers/constants'
+require 'legion/extensions/cognitive_gravity/helpers/attractor'
+require 'legion/extensions/cognitive_gravity/helpers/orbiting_thought'
+require 'legion/extensions/cognitive_gravity/helpers/gravity_engine'
+require 'legion/extensions/cognitive_gravity/runners/gravity'
+
+module Legion
+  module Extensions
+    module CognitiveGravity
+      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-gravity
+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: Attractor basins in thought space — cognitive gravity wells for LegionIO
+  agentic AI
+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-gravity.gemspec
+- lib/legion/extensions/cognitive_gravity.rb
+- lib/legion/extensions/cognitive_gravity/client.rb
+- lib/legion/extensions/cognitive_gravity/helpers/attractor.rb
+- lib/legion/extensions/cognitive_gravity/helpers/constants.rb
+- lib/legion/extensions/cognitive_gravity/helpers/gravity_engine.rb
+- lib/legion/extensions/cognitive_gravity/helpers/orbiting_thought.rb
+- lib/legion/extensions/cognitive_gravity/runners/gravity.rb
+- lib/legion/extensions/cognitive_gravity/version.rb
+homepage: https://github.com/LegionIO/lex-cognitive-gravity
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-cognitive-gravity
+  source_code_uri: https://github.com/LegionIO/lex-cognitive-gravity
+  documentation_uri: https://github.com/LegionIO/lex-cognitive-gravity
+  changelog_uri: https://github.com/LegionIO/lex-cognitive-gravity
+  bug_tracker_uri: https://github.com/LegionIO/lex-cognitive-gravity/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 Gravity
+test_files: []