lex-distributed-cognition 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: de4b8ad54804ba25b1f565e8e1e3362f46ca3ada01425b0991f87c0ddc54ef3c
+  data.tar.gz: 03ea79bc086c9b67e3b80a35da37a894751cd7fccf2e62512564c033db10bb7c
+SHA512:
+  metadata.gz: a72cc5623782cb85f4b46762dcd5980759cdc250c0ef39eac4880dc01e0061a1b92bc0e6876f31a3772f9a7dcc6265dfee7c4b7d9af9712671e8b431a9f034ff
+  data.tar.gz: f284c3521ffa9995aa6594738613e3d441f731a50188b2328da3e140ac511c62317cb31de1eb60db1b2deb7d7ae158ebd14c65a78517ba0818c05e037979494e

data/Gemfile

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

data/lex-distributed-cognition.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/distributed_cognition/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-distributed-cognition'
+  spec.version       = Legion::Extensions::DistributedCognition::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Distributed Cognition'
+  spec.description   = "Hutchins' distributed cognition — cognitive processes spread across " \
+                       'agents, artifacts, and environment for brain-modeled agentic AI'
+  spec.homepage      = 'https://github.com/LegionIO/lex-distributed-cognition'
+  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-distributed-cognition'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-distributed-cognition'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-distributed-cognition'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-distributed-cognition/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-distributed-cognition.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module DistributedCognition
+      class Client
+        include Runners::DistributedCognition
+
+        def initialize(engine: nil)
+          @engine = engine || Helpers::DistributionEngine.new
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module DistributedCognition
+      module Helpers
+        module Constants
+          MAX_PARTICIPANTS = 100
+          MAX_ARTIFACTS = 200
+          MAX_CONTRIBUTIONS = 1000
+          MAX_HISTORY = 300
+
+          DEFAULT_RELIABILITY = 0.5
+          RELIABILITY_FLOOR = 0.0
+          RELIABILITY_CEILING = 1.0
+
+          REINFORCEMENT_RATE = 0.1
+          PENALTY_RATE = 0.15
+          DECAY_RATE = 0.02
+          STALE_THRESHOLD = 120
+
+          PARTICIPANT_TYPES = %i[agent artifact environment].freeze
+
+          CONTRIBUTION_TYPES = %i[
+            computation storage retrieval transformation communication
+          ].freeze
+
+          RELIABILITY_LABELS = {
+            (0.8..)     => :highly_reliable,
+            (0.6...0.8) => :reliable,
+            (0.4...0.6) => :moderate,
+            (0.2...0.4) => :unreliable,
+            (..0.2)     => :failing
+          }.freeze
+
+          DISTRIBUTION_LABELS = {
+            (0.8..)     => :fully_distributed,
+            (0.6...0.8) => :well_distributed,
+            (0.4...0.6) => :partially_distributed,
+            (0.2...0.4) => :concentrated,
+            (..0.2)     => :centralized
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/distributed_cognition/helpers/distribution_engine.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module DistributedCognition
+      module Helpers
+        class DistributionEngine
+          include Constants
+
+          attr_reader :history
+
+          def initialize
+            @participants = {}
+            @contributions = []
+            @history = []
+          end
+
+          def register_participant(name:, participant_type:, domain:, capabilities: [])
+            unless PARTICIPANT_TYPES.include?(participant_type)
+              return { success: false, reason: :invalid_participant_type }
+            end
+
+            evict_oldest if @participants.size >= MAX_PARTICIPANTS
+
+            participant = Participant.new(
+              name:             name,
+              participant_type: participant_type,
+              domain:           domain,
+              capabilities:     capabilities
+            )
+            @participants[participant.id] = participant
+            record_history(:registered, participant.id)
+            participant
+          end
+
+          def record_contribution(participant_id:, contribution_type:, success:, context: {})
+            participant = @participants[participant_id]
+            return { success: false, reason: :not_found } unless participant
+
+            unless CONTRIBUTION_TYPES.include?(contribution_type)
+              return { success: false, reason: :invalid_contribution_type }
+            end
+
+            participant.contribute!(success: success)
+            store_contribution(participant_id, contribution_type, success, context)
+            record_history(:contributed, participant_id)
+            build_contribution_result(participant, contribution_type)
+          end
+
+          def find_capable(capability:)
+            @participants.values.select { |p| p.capable_of?(capability) }
+                                .sort_by { |p| -p.reliability }
+          end
+
+          def by_type(participant_type:)
+            @participants.values.select { |p| p.participant_type == participant_type }
+          end
+
+          def by_domain(domain:)
+            @participants.values.select { |p| p.domain == domain }
+          end
+
+          def most_reliable(limit: 5)
+            @participants.values.sort_by { |p| -p.reliability }.first(limit)
+          end
+
+          def distribution_score
+            return 0.0 if @contributions.empty? || @participants.size <= 1
+
+            counts = @contributions.each_with_object(Hash.new(0)) do |contrib, hash|
+              hash[contrib[:participant_id]] += 1
+            end
+            compute_evenness(counts.values)
+          end
+
+          def distribution_label
+            score = distribution_score
+            DISTRIBUTION_LABELS.find { |range, _| range.cover?(score) }&.last || :unknown
+          end
+
+          def cognitive_load_balance
+            return {} if @participants.empty?
+
+            @participants.transform_values(&:contribution_count)
+          end
+
+          def decay_all
+            @participants.each_value(&:decay!)
+          end
+
+          def prune_failing
+            failing_ids = @participants.select { |_id, p| p.reliability <= 0.05 }.keys
+            failing_ids.each { |id| @participants.delete(id) }
+            failing_ids.size
+          end
+
+          def to_h
+            {
+              total_participants:  @participants.size,
+              agent_count:         by_type(participant_type: :agent).size,
+              artifact_count:      by_type(participant_type: :artifact).size,
+              environment_count:   by_type(participant_type: :environment).size,
+              total_contributions: @contributions.size,
+              distribution_score:  distribution_score,
+              distribution_label:  distribution_label,
+              history_count:       @history.size
+            }
+          end
+
+          private
+
+          def store_contribution(participant_id, contribution_type, success, context)
+            entry = {
+              participant_id:    participant_id,
+              contribution_type: contribution_type,
+              success:           success,
+              context:           context,
+              at:                Time.now.utc
+            }
+            @contributions << entry
+            @contributions.shift while @contributions.size > MAX_CONTRIBUTIONS
+          end
+
+          def build_contribution_result(participant, contribution_type)
+            {
+              success:           true,
+              participant_id:    participant.id,
+              contribution_type: contribution_type,
+              reliability:       participant.reliability,
+              success_rate:      participant.success_rate
+            }
+          end
+
+          def compute_evenness(counts)
+            total = counts.sum.to_f
+            return 0.0 if total.zero?
+
+            proportions = counts.map { |c| c / total }
+            max_entropy = Math.log2(counts.size)
+            return 1.0 if max_entropy.zero?
+
+            entropy = -proportions.sum { |p| p.positive? ? p * Math.log2(p) : 0.0 }
+            (entropy / max_entropy).clamp(0.0, 1.0)
+          end
+
+          def evict_oldest
+            oldest_id = @participants.min_by { |_id, p| p.last_active_at }&.first
+            @participants.delete(oldest_id) if oldest_id
+          end
+
+          def record_history(event, subject_id)
+            @history << { event: event, subject_id: subject_id, at: Time.now.utc }
+            @history.shift while @history.size > MAX_HISTORY
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/distributed_cognition/helpers/participant.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module DistributedCognition
+      module Helpers
+        class Participant
+          include Constants
+
+          attr_reader :id, :name, :participant_type, :domain, :capabilities,
+                      :reliability, :contribution_count, :success_count,
+                      :created_at, :last_active_at
+
+          def initialize(name:, participant_type:, domain:, capabilities: [])
+            @id                 = SecureRandom.uuid
+            @name               = name
+            @participant_type   = participant_type
+            @domain             = domain
+            @capabilities       = capabilities
+            @reliability        = DEFAULT_RELIABILITY
+            @contribution_count = 0
+            @success_count      = 0
+            @created_at         = Time.now.utc
+            @last_active_at     = @created_at
+          end
+
+          def contribute!(success:)
+            @contribution_count += 1
+            @success_count      += 1 if success
+            @last_active_at      = Time.now.utc
+            adjust_reliability(success)
+          end
+
+          def add_capability(capability)
+            @capabilities << capability unless @capabilities.include?(capability)
+          end
+
+          def capable_of?(capability)
+            @capabilities.include?(capability)
+          end
+
+          def success_rate
+            return 0.0 if @contribution_count.zero?
+
+            @success_count.to_f / @contribution_count
+          end
+
+          def reliability_label
+            RELIABILITY_LABELS.find { |range, _| range.cover?(@reliability) }&.last || :unknown
+          end
+
+          def agent?
+            @participant_type == :agent
+          end
+
+          def artifact?
+            @participant_type == :artifact
+          end
+
+          def decay!
+            @reliability = (@reliability - DECAY_RATE).clamp(RELIABILITY_FLOOR, RELIABILITY_CEILING)
+          end
+
+          def stale?
+            (Time.now.utc - @last_active_at) > STALE_THRESHOLD
+          end
+
+          def to_h
+            {
+              id:                 @id,
+              name:               @name,
+              participant_type:   @participant_type,
+              domain:             @domain,
+              capabilities:       @capabilities,
+              reliability:        @reliability,
+              reliability_label:  reliability_label,
+              contribution_count: @contribution_count,
+              success_rate:       success_rate,
+              created_at:         @created_at,
+              last_active_at:     @last_active_at
+            }
+          end
+
+          private
+
+          def adjust_reliability(success)
+            delta = success ? REINFORCEMENT_RATE : -PENALTY_RATE
+            @reliability = (@reliability + delta).clamp(RELIABILITY_FLOOR, RELIABILITY_CEILING)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module DistributedCognition
+      module Runners
+        module DistributedCognition
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def register_cognitive_participant(name:, participant_type:, domain:, capabilities: [], **)
+            unless Helpers::Constants::PARTICIPANT_TYPES.include?(participant_type)
+              return { success: false, error: :invalid_participant_type,
+                       valid_types: Helpers::Constants::PARTICIPANT_TYPES }
+            end
+
+            result = engine.register_participant(
+              name: name, participant_type: participant_type,
+              domain: domain, capabilities: capabilities
+            )
+
+            return result unless result.is_a?(Helpers::Participant)
+
+            Legion::Logging.debug "[distributed_cognition] registered #{name} " \
+                                  "type=#{participant_type} id=#{result.id[0..7]}"
+            { success: true, participant_id: result.id, name: name,
+              participant_type: participant_type, domain: domain }
+          end
+
+          def record_cognitive_contribution(participant_id:, contribution_type:, success:, context: {}, **)
+            result = engine.record_contribution(
+              participant_id: participant_id, contribution_type: contribution_type,
+              success: success, context: context
+            )
+            Legion::Logging.debug '[distributed_cognition] contribution ' \
+                                  "type=#{contribution_type} success=#{success}"
+            result
+          end
+
+          def find_capable_participants(capability:, **)
+            participants = engine.find_capable(capability: capability)
+            Legion::Logging.debug '[distributed_cognition] find_capable ' \
+                                  "#{capability} count=#{participants.size}"
+            { success: true, capability: capability,
+              participants: participants.map(&:to_h), count: participants.size }
+          end
+
+          def most_reliable_participants(limit: 5, **)
+            participants = engine.most_reliable(limit: limit)
+            Legion::Logging.debug "[distributed_cognition] most_reliable count=#{participants.size}"
+            { success: true, participants: participants.map(&:to_h), count: participants.size }
+          end
+
+          def distribution_assessment(**)
+            score = engine.distribution_score
+            label = engine.distribution_label
+            balance = engine.cognitive_load_balance
+            Legion::Logging.debug '[distributed_cognition] distribution ' \
+                                  "score=#{score.round(3)} label=#{label}"
+            { success: true, distribution_score: score, distribution_label: label,
+              load_balance: balance }
+          end
+
+          def participants_by_type(participant_type:, **)
+            participants = engine.by_type(participant_type: participant_type)
+            Legion::Logging.debug "[distributed_cognition] by_type=#{participant_type} " \
+                                  "count=#{participants.size}"
+            { success: true, participant_type: participant_type,
+              participants: participants.map(&:to_h), count: participants.size }
+          end
+
+          def participants_by_domain(domain:, **)
+            participants = engine.by_domain(domain: domain)
+            Legion::Logging.debug "[distributed_cognition] by_domain=#{domain} " \
+                                  "count=#{participants.size}"
+            { success: true, domain: domain,
+              participants: participants.map(&:to_h), count: participants.size }
+          end
+
+          def update_distributed_cognition(**)
+            engine.decay_all
+            pruned = engine.prune_failing
+            Legion::Logging.debug "[distributed_cognition] decay+prune pruned=#{pruned}"
+            { success: true, pruned: pruned }
+          end
+
+          def distributed_cognition_stats(**)
+            stats = engine.to_h
+            Legion::Logging.debug '[distributed_cognition] stats ' \
+                                  "participants=#{stats[:total_participants]}"
+            { success: true }.merge(stats)
+          end
+
+          private
+
+          def engine
+            @engine ||= Helpers::DistributionEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/distributed_cognition.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/distributed_cognition/version'
+require 'legion/extensions/distributed_cognition/helpers/constants'
+require 'legion/extensions/distributed_cognition/helpers/participant'
+require 'legion/extensions/distributed_cognition/helpers/distribution_engine'
+require 'legion/extensions/distributed_cognition/runners/distributed_cognition'
+require 'legion/extensions/distributed_cognition/client'
+
+module Legion
+  module Extensions
+    module DistributedCognition
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::DistributedCognition::Client do
+  subject(:client) { described_class.new }
+
+  it 'registers and contributes' do
+    created = client.register_cognitive_participant(
+      name: 'worker', participant_type: :agent, domain: :test
+    )
+    result = client.record_cognitive_contribution(
+      participant_id: created[:participant_id],
+      contribution_type: :computation, success: true
+    )
+    expect(result[:success]).to be true
+  end
+
+  it 'returns stats' do
+    result = client.distributed_cognition_stats
+    expect(result[:success]).to be true
+  end
+end

data/spec/legion/extensions/distributed_cognition/helpers/distribution_engine_spec.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::DistributedCognition::Helpers::DistributionEngine do
+  subject(:engine) { described_class.new }
+
+  let(:agent) do
+    engine.register_participant(
+      name: 'worker-alpha', participant_type: :agent,
+      domain: :reasoning, capabilities: %i[computation retrieval]
+    )
+  end
+
+  describe '#register_participant' do
+    it 'creates and stores a participant' do
+      result = agent
+      expect(result).to be_a(Legion::Extensions::DistributedCognition::Helpers::Participant)
+    end
+
+    it 'rejects invalid participant types' do
+      result = engine.register_participant(
+        name: 'test', participant_type: :invalid, domain: :test
+      )
+      expect(result[:success]).to be false
+    end
+
+    it 'records history' do
+      agent
+      expect(engine.history.size).to eq(1)
+    end
+  end
+
+  describe '#record_contribution' do
+    it 'records a successful contribution' do
+      result = engine.record_contribution(
+        participant_id: agent.id, contribution_type: :computation, success: true
+      )
+      expect(result[:success]).to be true
+      expect(result[:reliability]).to be > 0.5
+    end
+
+    it 'returns error for unknown participant' do
+      result = engine.record_contribution(
+        participant_id: 'bad', contribution_type: :computation, success: true
+      )
+      expect(result[:success]).to be false
+    end
+
+    it 'rejects invalid contribution types' do
+      result = engine.record_contribution(
+        participant_id: agent.id, contribution_type: :invalid, success: true
+      )
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#find_capable' do
+    it 'finds participants with capability' do
+      agent
+      results = engine.find_capable(capability: :computation)
+      expect(results.size).to eq(1)
+    end
+
+    it 'returns empty for unknown capability' do
+      agent
+      results = engine.find_capable(capability: :transformation)
+      expect(results).to be_empty
+    end
+  end
+
+  describe '#by_type' do
+    it 'filters by participant type' do
+      agent
+      engine.register_participant(
+        name: 'db', participant_type: :artifact, domain: :storage
+      )
+      agents = engine.by_type(participant_type: :agent)
+      expect(agents.size).to eq(1)
+    end
+  end
+
+  describe '#by_domain' do
+    it 'filters by domain' do
+      agent
+      results = engine.by_domain(domain: :reasoning)
+      expect(results.size).to eq(1)
+    end
+  end
+
+  describe '#most_reliable' do
+    it 'returns sorted by reliability' do
+      agent
+      other = engine.register_participant(
+        name: 'worker-beta', participant_type: :agent, domain: :reasoning
+      )
+      3.times { engine.record_contribution(participant_id: other.id, contribution_type: :computation, success: true) }
+      results = engine.most_reliable(limit: 2)
+      expect(results.first.reliability).to be >= results.last.reliability
+    end
+  end
+
+  describe '#distribution_score' do
+    it 'returns 0.0 with no contributions' do
+      expect(engine.distribution_score).to eq(0.0)
+    end
+
+    it 'returns higher score for even distribution' do
+      other = engine.register_participant(
+        name: 'worker-beta', participant_type: :agent, domain: :reasoning
+      )
+      3.times do
+        engine.record_contribution(participant_id: agent.id, contribution_type: :computation, success: true)
+        engine.record_contribution(participant_id: other.id, contribution_type: :computation, success: true)
+      end
+      expect(engine.distribution_score).to be > 0.5
+    end
+  end
+
+  describe '#distribution_label' do
+    it 'returns a symbol' do
+      expect(engine.distribution_label).to be_a(Symbol)
+    end
+  end
+
+  describe '#decay_all' do
+    it 'reduces reliability of all participants' do
+      original = agent.reliability
+      engine.decay_all
+      expect(agent.reliability).to be < original
+    end
+  end
+
+  describe '#prune_failing' do
+    it 'removes very unreliable participants' do
+      agent
+      30.times { agent.decay! }
+      pruned = engine.prune_failing
+      expect(pruned).to be >= 0
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns summary stats' do
+      agent
+      stats = engine.to_h
+      expect(stats[:total_participants]).to eq(1)
+      expect(stats).to include(:distribution_score, :agent_count)
+    end
+  end
+end

data/spec/legion/extensions/distributed_cognition/helpers/participant_spec.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::DistributedCognition::Helpers::Participant do
+  subject(:participant) do
+    described_class.new(
+      name:             'worker-alpha',
+      participant_type: :agent,
+      domain:           :reasoning,
+      capabilities:     %i[computation retrieval]
+    )
+  end
+
+  describe '#initialize' do
+    it 'assigns a UUID' do
+      expect(participant.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores name and type' do
+      expect(participant.name).to eq('worker-alpha')
+      expect(participant.participant_type).to eq(:agent)
+    end
+
+    it 'stores capabilities' do
+      expect(participant.capabilities).to eq(%i[computation retrieval])
+    end
+  end
+
+  describe '#contribute!' do
+    it 'increments contribution count' do
+      expect { participant.contribute!(success: true) }.to change(participant, :contribution_count).by(1)
+    end
+
+    it 'increments success count on success' do
+      expect { participant.contribute!(success: true) }.to change(participant, :success_count).by(1)
+    end
+
+    it 'increases reliability on success' do
+      original = participant.reliability
+      participant.contribute!(success: true)
+      expect(participant.reliability).to be > original
+    end
+
+    it 'decreases reliability on failure' do
+      original = participant.reliability
+      participant.contribute!(success: false)
+      expect(participant.reliability).to be < original
+    end
+  end
+
+  describe '#capable_of?' do
+    it 'returns true for known capability' do
+      expect(participant).to be_capable_of(:computation)
+    end
+
+    it 'returns false for unknown capability' do
+      expect(participant).not_to be_capable_of(:transformation)
+    end
+  end
+
+  describe '#add_capability' do
+    it 'adds a new capability' do
+      participant.add_capability(:storage)
+      expect(participant.capabilities).to include(:storage)
+    end
+
+    it 'does not add duplicates' do
+      2.times { participant.add_capability(:computation) }
+      expect(participant.capabilities.count(:computation)).to eq(1)
+    end
+  end
+
+  describe '#success_rate' do
+    it 'returns 0.0 with no contributions' do
+      expect(participant.success_rate).to eq(0.0)
+    end
+
+    it 'computes ratio' do
+      3.times { participant.contribute!(success: true) }
+      participant.contribute!(success: false)
+      expect(participant.success_rate).to eq(0.75)
+    end
+  end
+
+  describe '#agent?' do
+    it 'returns true for agent type' do
+      expect(participant).to be_agent
+    end
+  end
+
+  describe '#artifact?' do
+    it 'returns false for agent type' do
+      expect(participant).not_to be_artifact
+    end
+  end
+
+  describe '#reliability_label' do
+    it 'returns a symbol' do
+      expect(participant.reliability_label).to be_a(Symbol)
+    end
+  end
+
+  describe '#decay!' do
+    it 'reduces reliability' do
+      original = participant.reliability
+      participant.decay!
+      expect(participant.reliability).to be < original
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns hash representation' do
+      hash = participant.to_h
+      expect(hash).to include(:id, :name, :participant_type, :reliability, :capabilities)
+    end
+  end
+end

data/spec/legion/extensions/distributed_cognition/runners/distributed_cognition_spec.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::DistributedCognition::Runners::DistributedCognition do
+  let(:runner_host) do
+    obj = Object.new
+    obj.extend(described_class)
+    obj
+  end
+
+  describe '#register_cognitive_participant' do
+    it 'registers a participant' do
+      result = runner_host.register_cognitive_participant(
+        name: 'worker', participant_type: :agent, domain: :test
+      )
+      expect(result[:success]).to be true
+      expect(result[:participant_id]).to be_a(String)
+    end
+
+    it 'rejects invalid type' do
+      result = runner_host.register_cognitive_participant(
+        name: 'test', participant_type: :invalid, domain: :test
+      )
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#record_cognitive_contribution' do
+    it 'records a contribution' do
+      created = runner_host.register_cognitive_participant(
+        name: 'worker', participant_type: :agent, domain: :test
+      )
+      result = runner_host.record_cognitive_contribution(
+        participant_id: created[:participant_id],
+        contribution_type: :computation, success: true
+      )
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#find_capable_participants' do
+    it 'finds capable participants' do
+      runner_host.register_cognitive_participant(
+        name: 'worker', participant_type: :agent,
+        domain: :test, capabilities: [:computation]
+      )
+      result = runner_host.find_capable_participants(capability: :computation)
+      expect(result[:success]).to be true
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#most_reliable_participants' do
+    it 'returns reliable participants' do
+      result = runner_host.most_reliable_participants(limit: 3)
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#distribution_assessment' do
+    it 'returns distribution metrics' do
+      result = runner_host.distribution_assessment
+      expect(result[:success]).to be true
+      expect(result).to include(:distribution_score, :distribution_label)
+    end
+  end
+
+  describe '#participants_by_type' do
+    it 'filters by type' do
+      runner_host.register_cognitive_participant(
+        name: 'db', participant_type: :artifact, domain: :storage
+      )
+      result = runner_host.participants_by_type(participant_type: :artifact)
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#participants_by_domain' do
+    it 'filters by domain' do
+      runner_host.register_cognitive_participant(
+        name: 'worker', participant_type: :agent, domain: :reasoning
+      )
+      result = runner_host.participants_by_domain(domain: :reasoning)
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#update_distributed_cognition' do
+    it 'runs decay and prune cycle' do
+      result = runner_host.update_distributed_cognition
+      expect(result[:success]).to be true
+      expect(result).to include(:pruned)
+    end
+  end
+
+  describe '#distributed_cognition_stats' do
+    it 'returns stats' do
+      result = runner_host.distributed_cognition_stats
+      expect(result[:success]).to be true
+      expect(result).to include(:total_participants, :distribution_score)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Helpers
+      module Lex; end
+    end
+  end
+
+  module Logging
+    def self.debug(*); end
+
+    def self.info(*); end
+
+    def self.warn(*); end
+
+    def self.error(*); end
+  end
+end
+
+require 'legion/extensions/distributed_cognition'
+
+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.filter_run_when_matching :focus
+  config.order = :random
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: lex-distributed-cognition
+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: Hutchins' distributed cognition — cognitive processes spread across agents,
+  artifacts, and environment for brain-modeled agentic AI
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- lex-distributed-cognition.gemspec
+- lib/legion/extensions/distributed_cognition.rb
+- lib/legion/extensions/distributed_cognition/client.rb
+- lib/legion/extensions/distributed_cognition/helpers/constants.rb
+- lib/legion/extensions/distributed_cognition/helpers/distribution_engine.rb
+- lib/legion/extensions/distributed_cognition/helpers/participant.rb
+- lib/legion/extensions/distributed_cognition/runners/distributed_cognition.rb
+- lib/legion/extensions/distributed_cognition/version.rb
+- spec/legion/extensions/distributed_cognition/client_spec.rb
+- spec/legion/extensions/distributed_cognition/helpers/distribution_engine_spec.rb
+- spec/legion/extensions/distributed_cognition/helpers/participant_spec.rb
+- spec/legion/extensions/distributed_cognition/runners/distributed_cognition_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-distributed-cognition
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-distributed-cognition
+  source_code_uri: https://github.com/LegionIO/lex-distributed-cognition
+  documentation_uri: https://github.com/LegionIO/lex-distributed-cognition
+  changelog_uri: https://github.com/LegionIO/lex-distributed-cognition
+  bug_tracker_uri: https://github.com/LegionIO/lex-distributed-cognition/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 Distributed Cognition
+test_files: []