lex-global-workspace 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7e43f7f4fe9651e9509cdc5b2c92212b617571f81996118c258bf91f4226c2a7
+  data.tar.gz: a9a08a51d92c11f4d1480e50b6768202f498c7ec179d9e589104d7aa3bb9ffa5
+SHA512:
+  metadata.gz: aa1b26d8aed0354075e509ea803f819b344d60c70686399c9277e12083b1b059671d36b4d11511710633d2d8bd6111ae726605c96109141c7bb3fc0fc4a77b43
+  data.tar.gz: 363e6dc2064a884834078c146f1310ef266714dc61295e12d3bca341a6c2f730dd5cb8ccae5cdbe6e2be86e401c4b454b22f4b30ce96534031c137fafe881099

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/lex-global-workspace.gemspec

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/global_workspace/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-global-workspace'
+  spec.version       = Legion::Extensions::GlobalWorkspace::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Global Workspace'
+  spec.description   = "Baars' Global Workspace Theory for brain-modeled agentic AI — information " \
+                       'competes for access to a limited-capacity workspace; winners are broadcast to ' \
+                       'all subscribed cognitive subsystems, implementing a computational model of ' \
+                       'conscious access and attentional bottleneck.'
+  spec.homepage      = 'https://github.com/LegionIO/lex-global-workspace'
+  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-global-workspace'
+  spec.metadata['documentation_uri']     = 'https://github.com/LegionIO/lex-global-workspace'
+  spec.metadata['changelog_uri']         = 'https://github.com/LegionIO/lex-global-workspace'
+  spec.metadata['bug_tracker_uri']       = 'https://github.com/LegionIO/lex-global-workspace/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-global-workspace.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

data/lib/legion/extensions/global_workspace/actors/competition.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module GlobalWorkspace
+      module Actor
+        class Competition < Legion::Extensions::Actors::Every
+          def runner_class
+            Legion::Extensions::GlobalWorkspace::Runners::GlobalWorkspace
+          end
+
+          def runner_function
+            'update_global_workspace'
+          end
+
+          def time
+            2
+          end
+
+          def run_now?
+            false
+          end
+
+          def use_runner?
+            false
+          end
+
+          def check_subtask?
+            false
+          end
+
+          def generate_task?
+            false
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/global_workspace/helpers/constants'
+require 'legion/extensions/global_workspace/helpers/broadcast'
+require 'legion/extensions/global_workspace/helpers/competitor'
+require 'legion/extensions/global_workspace/helpers/workspace'
+require 'legion/extensions/global_workspace/runners/global_workspace'
+
+module Legion
+  module Extensions
+    module GlobalWorkspace
+      class Client
+        include Runners::GlobalWorkspace
+
+        def initialize(workspace: nil, **)
+          @workspace = workspace || Helpers::Workspace.new
+        end
+
+        private
+
+        attr_reader :workspace
+      end
+    end
+  end
+end

data/lib/legion/extensions/global_workspace/helpers/broadcast.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module GlobalWorkspace
+      module Helpers
+        class Broadcast
+          include Constants
+
+          attr_reader :content, :source, :domain, :salience, :coalition,
+                      :broadcast_at, :received_by
+
+          def initialize(content:, source:, domain:, salience:, coalition: [])
+            @content      = content
+            @source       = source
+            @domain       = domain
+            @salience     = salience.to_f.clamp(0.0, 1.0)
+            @coalition    = Array(coalition).first(MAX_COALITION_SIZE)
+            @broadcast_at = Time.now.utc
+            @received_by  = []
+          end
+
+          def acknowledge(subscriber_id)
+            @received_by << subscriber_id unless @received_by.include?(subscriber_id)
+          end
+
+          def expired?
+            (Time.now.utc - @broadcast_at) > BROADCAST_TTL
+          end
+
+          def age
+            Time.now.utc - @broadcast_at
+          end
+
+          def label
+            SALIENCE_LABELS.each { |range, lbl| return lbl if range.cover?(@salience) }
+            :subliminal
+          end
+
+          def to_h
+            {
+              content: @content,
+              source: @source,
+              domain: @domain,
+              salience: @salience.round(4),
+              label: label,
+              coalition: @coalition,
+              broadcast_at: @broadcast_at,
+              age: age.round(2),
+              received_by: @received_by.dup,
+              expired: expired?
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/global_workspace/helpers/competitor.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module GlobalWorkspace
+      module Helpers
+        class Competitor
+          include Constants
+
+          attr_reader :content, :source, :domain, :coalition, :submitted_at
+          attr_accessor :salience, :urgency
+
+          def initialize(content:, source:, domain:, salience:, coalition: [])
+            @content      = content
+            @source       = source
+            @domain       = domain
+            @salience     = salience.to_f.clamp(0.0, 1.0)
+            @coalition    = Array(coalition).first(MAX_COALITION_SIZE)
+            @urgency      = 0.0
+            @submitted_at = Time.now.utc
+          end
+
+          def effective_salience
+            (@salience + @urgency).clamp(0.0, 1.0)
+          end
+
+          def decay
+            @salience = [@salience - SALIENCE_DECAY, 0.0].max
+          end
+
+          def boost_urgency
+            @urgency = [@urgency + URGENCY_BOOST, MAX_URGENCY].min
+          end
+
+          def below_threshold?
+            effective_salience < COMPETITION_THRESHOLD
+          end
+
+          def to_h
+            {
+              content: @content,
+              source: @source,
+              domain: @domain,
+              salience: @salience.round(4),
+              urgency: @urgency.round(4),
+              effective_salience: effective_salience.round(4),
+              coalition: @coalition,
+              submitted_at: @submitted_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module GlobalWorkspace
+      module Helpers
+        module Constants
+          # Maximum items that can compete for the workspace in one cycle
+          MAX_COMPETITORS = 50
+
+          # Maximum broadcasts retained in history
+          MAX_BROADCAST_HISTORY = 200
+
+          # Maximum number of coalition members per broadcast
+          MAX_COALITION_SIZE = 10
+
+          # Minimum salience to enter competition
+          COMPETITION_THRESHOLD = 0.2
+
+          # Winner takes all — top competitor must exceed runner-up by this margin
+          DOMINANCE_MARGIN = 0.05
+
+          # How long a broadcast remains "conscious" (seconds)
+          BROADCAST_TTL = 10
+
+          # Salience decay per tick for waiting competitors
+          SALIENCE_DECAY = 0.02
+
+          # Urgency boost per tick for items that keep losing competition
+          URGENCY_BOOST = 0.01
+
+          # Maximum urgency accumulation
+          MAX_URGENCY = 0.5
+
+          # EMA alpha for workspace utilization tracking
+          UTILIZATION_ALPHA = 0.1
+
+          # Maximum registered subscribers
+          MAX_SUBSCRIBERS = 50
+
+          # Labels for workspace state
+          WORKSPACE_STATE_LABELS = {
+            broadcasting: 'actively broadcasting content',
+            idle: 'workspace empty, awaiting input',
+            contention: 'multiple items competing for access',
+            saturated: 'high utilization, processing backlog'
+          }.freeze
+
+          # Labels for broadcast salience
+          SALIENCE_LABELS = {
+            (0.8..) => :dominant,
+            (0.6...0.8) => :salient,
+            (0.4...0.6) => :moderate,
+            (0.2...0.4) => :marginal,
+            (..0.2) => :subliminal
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/global_workspace/helpers/workspace.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module GlobalWorkspace
+      module Helpers
+        class Workspace
+          include Constants
+
+          attr_reader :competitors, :broadcast_history, :subscribers, :current_broadcast, :utilization
+
+          def initialize
+            @competitors       = []
+            @broadcast_history = []
+            @subscribers       = {}   # id => { name:, domains: [] }
+            @current_broadcast = nil
+            @utilization       = 0.0  # EMA of workspace usage
+            @competition_count = 0
+          end
+
+          # --- Subscriber Management ---
+
+          def register_subscriber(id:, name:, domains: [])
+            return false if @subscribers.size >= MAX_SUBSCRIBERS && !@subscribers.key?(id)
+
+            @subscribers[id] = { name: name, domains: Array(domains), registered_at: Time.now.utc }
+            true
+          end
+
+          def unregister_subscriber(id:)
+            !@subscribers.delete(id).nil?
+          end
+
+          # --- Competition ---
+
+          def submit(content:, source:, domain:, salience:, coalition: [])
+            return nil if salience.to_f < COMPETITION_THRESHOLD
+
+            @competitors.shift while @competitors.size >= MAX_COMPETITORS
+            competitor = Competitor.new(
+              content: content,
+              source: source,
+              domain: domain,
+              salience: salience,
+              coalition: coalition
+            )
+            @competitors << competitor
+            competitor
+          end
+
+          def compete
+            @competition_count += 1
+            expire_current_broadcast
+            prune_weak_competitors
+
+            return nil if @competitors.empty?
+
+            sorted = @competitors.sort_by { |c| -c.effective_salience }
+            winner = sorted.first
+
+            if sorted.size > 1
+              runner_up = sorted[1]
+              unless (winner.effective_salience - runner_up.effective_salience) >= DOMINANCE_MARGIN
+                boost_losers
+                update_utilization(busy: true)
+                return nil
+              end
+            end
+
+            @competitors.delete(winner)
+            broadcast = create_broadcast(winner)
+            @current_broadcast = broadcast
+
+            boost_losers
+            update_utilization(busy: true)
+
+            broadcast
+          end
+
+          # --- Query ---
+
+          def conscious?(content)
+            return false unless @current_broadcast && !@current_broadcast.expired?
+
+            @current_broadcast.content == content
+          end
+
+          def current_content
+            return nil unless @current_broadcast && !@current_broadcast.expired?
+
+            @current_broadcast.to_h
+          end
+
+          def acknowledge(subscriber_id:)
+            return false unless @current_broadcast && !@current_broadcast.expired?
+
+            @current_broadcast.acknowledge(subscriber_id)
+            true
+          end
+
+          # --- Workspace State ---
+
+          def state
+            if @current_broadcast && !@current_broadcast.expired?
+              :broadcasting
+            elsif @competitors.size > 1
+              :contention
+            elsif @utilization > 0.7
+              :saturated
+            else
+              :idle
+            end
+          end
+
+          def subscriber_count
+            @subscribers.size
+          end
+
+          def competitor_count
+            @competitors.size
+          end
+
+          # --- Tick / Maintenance ---
+
+          def tick
+            expire_current_broadcast
+            decay_competitors
+            prune_weak_competitors
+            update_utilization(busy: !@competitors.empty? || (@current_broadcast && !@current_broadcast.expired?))
+          end
+
+          def to_h
+            {
+              state: state,
+              state_label: WORKSPACE_STATE_LABELS[state],
+              subscribers: @subscribers.size,
+              competitors: @competitors.size,
+              broadcast_history: @broadcast_history.size,
+              utilization: @utilization.round(4),
+              competitions: @competition_count,
+              current_broadcast: @current_broadcast&.expired? == false ? @current_broadcast.to_h : nil
+            }
+          end
+
+          private
+
+          def create_broadcast(winner)
+            broadcast = Broadcast.new(
+              content: winner.content,
+              source: winner.source,
+              domain: winner.domain,
+              salience: winner.effective_salience,
+              coalition: winner.coalition
+            )
+            @broadcast_history << broadcast
+            @broadcast_history.shift while @broadcast_history.size > MAX_BROADCAST_HISTORY
+            broadcast
+          end
+
+          def expire_current_broadcast
+            @current_broadcast = nil if @current_broadcast&.expired?
+          end
+
+          def prune_weak_competitors
+            @competitors.reject!(&:below_threshold?)
+          end
+
+          def decay_competitors
+            @competitors.each(&:decay)
+          end
+
+          def boost_losers
+            @competitors.each(&:boost_urgency)
+          end
+
+          def update_utilization(busy:)
+            sample = busy ? 1.0 : 0.0
+            @utilization += (UTILIZATION_ALPHA * (sample - @utilization))
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module GlobalWorkspace
+      module Runners
+        module GlobalWorkspace
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def submit_for_broadcast(content:, source:, domain:, salience:, coalition: [], **)
+            Legion::Logging.debug "[global_workspace] submit: source=#{source} domain=#{domain} salience=#{salience}"
+            competitor = workspace.submit(
+              content: content,
+              source: source,
+              domain: domain,
+              salience: salience,
+              coalition: coalition
+            )
+            if competitor
+              { success: true, effective_salience: competitor.effective_salience.round(4),
+                competitors: workspace.competitor_count }
+            else
+              { success: false, reason: :below_threshold, competitors: workspace.competitor_count }
+            end
+          end
+
+          def run_competition(**)
+            Legion::Logging.debug '[global_workspace] run_competition'
+            broadcast = workspace.compete
+            if broadcast
+              {
+                success: true,
+                broadcast: broadcast.to_h,
+                state: workspace.state,
+                remaining: workspace.competitor_count
+              }
+            else
+              { success: false, reason: :no_winner, state: workspace.state, competitors: workspace.competitor_count }
+            end
+          end
+
+          def register_subscriber(id:, name:, domains: [], **)
+            Legion::Logging.debug "[global_workspace] register_subscriber: id=#{id} name=#{name}"
+            registered = workspace.register_subscriber(id: id, name: name, domains: domains)
+            { success: registered, subscriber_count: workspace.subscriber_count }
+          end
+
+          def unregister_subscriber(id:, **)
+            Legion::Logging.debug "[global_workspace] unregister_subscriber: id=#{id}"
+            removed = workspace.unregister_subscriber(id: id)
+            { success: removed, subscriber_count: workspace.subscriber_count }
+          end
+
+          def acknowledge_broadcast(subscriber_id:, **)
+            Legion::Logging.debug "[global_workspace] acknowledge: subscriber=#{subscriber_id}"
+            ack = workspace.acknowledge(subscriber_id: subscriber_id)
+            { success: ack }
+          end
+
+          def query_consciousness(content:, **)
+            is_conscious = workspace.conscious?(content)
+            Legion::Logging.debug "[global_workspace] conscious?(#{content}): #{is_conscious}"
+            { success: true, conscious: is_conscious }
+          end
+
+          def current_broadcast(**)
+            content = workspace.current_content
+            Legion::Logging.debug "[global_workspace] current_broadcast: #{content ? 'active' : 'none'}"
+            { success: true, broadcast: content }
+          end
+
+          def broadcast_history(limit: 10, **)
+            history = workspace.broadcast_history.last(limit.to_i).map(&:to_h)
+            Legion::Logging.debug "[global_workspace] history: #{history.size} entries"
+            { success: true, history: history, total: workspace.broadcast_history.size }
+          end
+
+          def update_global_workspace(**)
+            Legion::Logging.debug '[global_workspace] tick'
+            workspace.tick
+            { success: true, state: workspace.state, competitors: workspace.competitor_count,
+              utilization: workspace.utilization.round(4) }
+          end
+
+          def workspace_stats(**)
+            Legion::Logging.debug '[global_workspace] stats'
+            { success: true, stats: workspace.to_h }
+          end
+
+          private
+
+          def workspace
+            @workspace ||= Helpers::Workspace.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/global_workspace.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/global_workspace/version'
+require 'legion/extensions/global_workspace/helpers/constants'
+require 'legion/extensions/global_workspace/helpers/broadcast'
+require 'legion/extensions/global_workspace/helpers/competitor'
+require 'legion/extensions/global_workspace/helpers/workspace'
+require 'legion/extensions/global_workspace/runners/global_workspace'
+require 'legion/extensions/global_workspace/client'
+
+module Legion
+  module Extensions
+    module GlobalWorkspace
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::GlobalWorkspace::Client do
+  subject(:client) { described_class.new }
+
+  it 'includes Runners::GlobalWorkspace' do
+    expect(described_class.ancestors).to include(Legion::Extensions::GlobalWorkspace::Runners::GlobalWorkspace)
+  end
+
+  it 'supports full conscious access lifecycle' do
+    # Register subscribers (cognitive subsystems)
+    client.register_subscriber(id: :memory, name: 'lex-memory', domains: [:all])
+    client.register_subscriber(id: :emotion, name: 'lex-emotion', domains: [:safety])
+    client.register_subscriber(id: :planning, name: 'lex-planning', domains: [:cognition])
+
+    # Multiple subsystems submit content for conscious access
+    client.submit_for_broadcast(content: 'threat_nearby', source: :emotion, domain: :safety, salience: 0.85)
+    client.submit_for_broadcast(content: 'plan_step_3', source: :planning, domain: :cognition, salience: 0.5)
+    client.submit_for_broadcast(content: 'memory_trace', source: :memory, domain: :recall, salience: 0.3)
+
+    # Competition: emotion wins (highest salience, clear margin)
+    competition = client.run_competition
+    expect(competition[:success]).to be true
+    expect(competition[:broadcast][:content]).to eq('threat_nearby')
+
+    # Verify consciousness
+    conscious = client.query_consciousness(content: 'threat_nearby')
+    expect(conscious[:conscious]).to be true
+
+    # Subscribers acknowledge receipt
+    client.acknowledge_broadcast(subscriber_id: :memory)
+    client.acknowledge_broadcast(subscriber_id: :emotion)
+
+    # Check current state
+    current = client.current_broadcast
+    expect(current[:broadcast][:received_by]).to include(:memory, :emotion)
+
+    # Tick maintenance
+    client.update_global_workspace
+
+    # History preserved
+    history = client.broadcast_history(limit: 10)
+    expect(history[:total]).to eq(1)
+
+    # Stats
+    stats = client.workspace_stats
+    expect(stats[:stats][:subscribers]).to eq(3)
+  end
+end

data/spec/legion/extensions/global_workspace/helpers/broadcast_spec.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::GlobalWorkspace::Helpers::Broadcast do
+  subject(:broadcast) do
+    described_class.new(content: 'threat_detected', source: :emotion, domain: :safety, salience: 0.9,
+                        coalition: %i[fear attention])
+  end
+
+  let(:constants) { Legion::Extensions::GlobalWorkspace::Helpers::Constants }
+
+  describe '#initialize' do
+    it 'sets attributes' do
+      expect(broadcast.content).to eq('threat_detected')
+      expect(broadcast.source).to eq(:emotion)
+      expect(broadcast.domain).to eq(:safety)
+      expect(broadcast.salience).to eq(0.9)
+      expect(broadcast.coalition).to eq(%i[fear attention])
+    end
+
+    it 'clamps salience' do
+      high = described_class.new(content: :x, source: :s, domain: :d, salience: 1.5)
+      expect(high.salience).to eq(1.0)
+    end
+
+    it 'records broadcast_at' do
+      expect(broadcast.broadcast_at).to be_a(Time)
+    end
+
+    it 'starts with empty received_by' do
+      expect(broadcast.received_by).to be_empty
+    end
+
+    it 'limits coalition size' do
+      big = described_class.new(content: :x, source: :s, domain: :d, salience: 0.5,
+                                coalition: (1..20).to_a)
+      expect(big.coalition.size).to eq(constants::MAX_COALITION_SIZE)
+    end
+  end
+
+  describe '#acknowledge' do
+    it 'adds subscriber to received_by' do
+      broadcast.acknowledge(:memory)
+      expect(broadcast.received_by).to include(:memory)
+    end
+
+    it 'does not duplicate' do
+      broadcast.acknowledge(:memory)
+      broadcast.acknowledge(:memory)
+      expect(broadcast.received_by.size).to eq(1)
+    end
+  end
+
+  describe '#expired?' do
+    it 'returns false when fresh' do
+      expect(broadcast.expired?).to be false
+    end
+  end
+
+  describe '#age' do
+    it 'returns elapsed time' do
+      expect(broadcast.age).to be >= 0.0
+    end
+  end
+
+  describe '#label' do
+    it 'returns :dominant for high salience' do
+      expect(broadcast.label).to eq(:dominant)
+    end
+
+    it 'returns :subliminal for low salience' do
+      low = described_class.new(content: :x, source: :s, domain: :d, salience: 0.1)
+      expect(low.label).to eq(:subliminal)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns hash with all fields' do
+      h = broadcast.to_h
+      expect(h).to include(:content, :source, :domain, :salience, :label, :coalition, :broadcast_at, :age,
+                           :received_by, :expired)
+    end
+  end
+end

data/spec/legion/extensions/global_workspace/helpers/competitor_spec.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::GlobalWorkspace::Helpers::Competitor do
+  subject(:competitor) do
+    described_class.new(content: 'idea', source: :cortex, domain: :cognition, salience: 0.6, coalition: [:attention])
+  end
+
+  let(:constants) { Legion::Extensions::GlobalWorkspace::Helpers::Constants }
+
+  describe '#initialize' do
+    it 'sets attributes' do
+      expect(competitor.content).to eq('idea')
+      expect(competitor.source).to eq(:cortex)
+      expect(competitor.salience).to eq(0.6)
+      expect(competitor.urgency).to eq(0.0)
+    end
+
+    it 'clamps salience' do
+      high = described_class.new(content: :x, source: :s, domain: :d, salience: 2.0)
+      expect(high.salience).to eq(1.0)
+    end
+  end
+
+  describe '#effective_salience' do
+    it 'equals salience when no urgency' do
+      expect(competitor.effective_salience).to eq(0.6)
+    end
+
+    it 'includes urgency' do
+      competitor.urgency = 0.2
+      expect(competitor.effective_salience).to eq(0.8)
+    end
+
+    it 'clamps to 1.0' do
+      competitor.salience = 0.9
+      competitor.urgency = 0.3
+      expect(competitor.effective_salience).to eq(1.0)
+    end
+  end
+
+  describe '#decay' do
+    it 'reduces salience' do
+      before = competitor.salience
+      competitor.decay
+      expect(competitor.salience).to eq(before - constants::SALIENCE_DECAY)
+    end
+
+    it 'does not go below 0' do
+      competitor.salience = 0.01
+      competitor.decay
+      expect(competitor.salience).to eq(0.0)
+    end
+  end
+
+  describe '#boost_urgency' do
+    it 'increases urgency' do
+      competitor.boost_urgency
+      expect(competitor.urgency).to eq(constants::URGENCY_BOOST)
+    end
+
+    it 'caps at MAX_URGENCY' do
+      50.times { competitor.boost_urgency }
+      expect(competitor.urgency).to eq(constants::MAX_URGENCY)
+    end
+  end
+
+  describe '#below_threshold?' do
+    it 'returns false when above threshold' do
+      expect(competitor.below_threshold?).to be false
+    end
+
+    it 'returns true when below threshold' do
+      competitor.salience = 0.1
+      expect(competitor.below_threshold?).to be true
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns hash with all fields' do
+      h = competitor.to_h
+      expect(h).to include(:content, :source, :domain, :salience, :urgency, :effective_salience, :coalition)
+    end
+  end
+end

data/spec/legion/extensions/global_workspace/helpers/workspace_spec.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::GlobalWorkspace::Helpers::Workspace do
+  subject(:ws) { described_class.new }
+
+  let(:constants) { Legion::Extensions::GlobalWorkspace::Helpers::Constants }
+
+  describe '#register_subscriber / #unregister_subscriber' do
+    it 'registers a subscriber' do
+      expect(ws.register_subscriber(id: :memory, name: 'lex-memory', domains: [:all])).to be true
+      expect(ws.subscriber_count).to eq(1)
+    end
+
+    it 'unregisters a subscriber' do
+      ws.register_subscriber(id: :memory, name: 'lex-memory')
+      expect(ws.unregister_subscriber(id: :memory)).to be true
+      expect(ws.subscriber_count).to eq(0)
+    end
+
+    it 'returns false for unknown unregister' do
+      expect(ws.unregister_subscriber(id: :unknown)).to be false
+    end
+
+    it 'limits subscribers' do
+      constants::MAX_SUBSCRIBERS.times { |i| ws.register_subscriber(id: "sub_#{i}", name: "s#{i}") }
+      expect(ws.register_subscriber(id: :overflow, name: 'over')).to be false
+    end
+  end
+
+  describe '#submit' do
+    it 'adds a competitor' do
+      comp = ws.submit(content: 'idea', source: :cortex, domain: :cognition, salience: 0.6)
+      expect(comp).to be_a(Legion::Extensions::GlobalWorkspace::Helpers::Competitor)
+      expect(ws.competitor_count).to eq(1)
+    end
+
+    it 'rejects below-threshold submissions' do
+      result = ws.submit(content: 'weak', source: :s, domain: :d, salience: 0.1)
+      expect(result).to be_nil
+      expect(ws.competitor_count).to eq(0)
+    end
+
+    it 'limits competitor queue' do
+      constants::MAX_COMPETITORS.times { |i| ws.submit(content: "c_#{i}", source: :s, domain: :d, salience: 0.5) }
+      ws.submit(content: :overflow, source: :s, domain: :d, salience: 0.5)
+      expect(ws.competitor_count).to eq(constants::MAX_COMPETITORS)
+    end
+  end
+
+  describe '#compete' do
+    it 'returns nil with no competitors' do
+      expect(ws.compete).to be_nil
+    end
+
+    it 'broadcasts the dominant competitor' do
+      ws.submit(content: 'strong', source: :emotion, domain: :safety, salience: 0.9)
+      ws.submit(content: 'weak', source: :cortex, domain: :cognition, salience: 0.3)
+      broadcast = ws.compete
+      expect(broadcast).to be_a(Legion::Extensions::GlobalWorkspace::Helpers::Broadcast)
+      expect(broadcast.content).to eq('strong')
+    end
+
+    it 'returns nil when no clear winner (within margin)' do
+      ws.submit(content: 'a', source: :s, domain: :d, salience: 0.5)
+      ws.submit(content: 'b', source: :s, domain: :d, salience: 0.5)
+      result = ws.compete
+      expect(result).to be_nil
+    end
+
+    it 'boosts urgency of losers' do
+      ws.submit(content: 'a', source: :s, domain: :d, salience: 0.5)
+      ws.submit(content: 'b', source: :s, domain: :d, salience: 0.5)
+      ws.compete
+      expect(ws.competitors.first.urgency).to be > 0
+    end
+
+    it 'removes winner from competitors' do
+      ws.submit(content: 'winner', source: :s, domain: :d, salience: 0.9)
+      ws.compete
+      expect(ws.competitor_count).to eq(0)
+    end
+
+    it 'adds to broadcast history' do
+      ws.submit(content: 'winner', source: :s, domain: :d, salience: 0.9)
+      ws.compete
+      expect(ws.broadcast_history.size).to eq(1)
+    end
+  end
+
+  describe '#conscious?' do
+    it 'returns true for current broadcast content' do
+      ws.submit(content: 'idea', source: :s, domain: :d, salience: 0.9)
+      ws.compete
+      expect(ws.conscious?('idea')).to be true
+    end
+
+    it 'returns false when no broadcast' do
+      expect(ws.conscious?('anything')).to be false
+    end
+
+    it 'returns false for non-matching content' do
+      ws.submit(content: 'idea', source: :s, domain: :d, salience: 0.9)
+      ws.compete
+      expect(ws.conscious?('other')).to be false
+    end
+  end
+
+  describe '#current_content' do
+    it 'returns broadcast hash when active' do
+      ws.submit(content: 'idea', source: :cortex, domain: :cognition, salience: 0.9)
+      ws.compete
+      content = ws.current_content
+      expect(content[:content]).to eq('idea')
+      expect(content[:source]).to eq(:cortex)
+    end
+
+    it 'returns nil when no active broadcast' do
+      expect(ws.current_content).to be_nil
+    end
+  end
+
+  describe '#acknowledge' do
+    it 'acknowledges current broadcast' do
+      ws.submit(content: 'idea', source: :s, domain: :d, salience: 0.9)
+      ws.compete
+      expect(ws.acknowledge(subscriber_id: :memory)).to be true
+    end
+
+    it 'returns false when no broadcast' do
+      expect(ws.acknowledge(subscriber_id: :memory)).to be false
+    end
+  end
+
+  describe '#state' do
+    it 'returns :idle when empty' do
+      expect(ws.state).to eq(:idle)
+    end
+
+    it 'returns :broadcasting when broadcast active' do
+      ws.submit(content: 'idea', source: :s, domain: :d, salience: 0.9)
+      ws.compete
+      expect(ws.state).to eq(:broadcasting)
+    end
+
+    it 'returns :contention when multiple competitors' do
+      ws.submit(content: 'a', source: :s, domain: :d, salience: 0.5)
+      ws.submit(content: 'b', source: :s, domain: :d, salience: 0.5)
+      expect(ws.state).to eq(:contention)
+    end
+  end
+
+  describe '#tick' do
+    it 'decays competitors' do
+      ws.submit(content: 'idea', source: :s, domain: :d, salience: 0.5)
+      before = ws.competitors.first.salience
+      ws.tick
+      expect(ws.competitors.first&.salience || 0).to be <= before
+    end
+
+    it 'prunes weak competitors after decay' do
+      ws.submit(content: 'weak', source: :s, domain: :d, salience: constants::COMPETITION_THRESHOLD + 0.01)
+      ws.tick
+      expect(ws.competitor_count).to eq(0)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns stats hash' do
+      h = ws.to_h
+      expect(h).to include(:state, :state_label, :subscribers, :competitors, :broadcast_history, :utilization,
+                           :competitions)
+    end
+  end
+end

data/spec/legion/extensions/global_workspace/runners/global_workspace_spec.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::GlobalWorkspace::Runners::GlobalWorkspace do
+  let(:client) { Legion::Extensions::GlobalWorkspace::Client.new }
+
+  describe '#submit_for_broadcast' do
+    it 'submits content for competition' do
+      result = client.submit_for_broadcast(content: 'idea', source: :cortex, domain: :cognition, salience: 0.7)
+      expect(result[:success]).to be true
+      expect(result[:effective_salience]).to be > 0
+    end
+
+    it 'rejects below-threshold content' do
+      result = client.submit_for_broadcast(content: 'weak', source: :s, domain: :d, salience: 0.1)
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:below_threshold)
+    end
+  end
+
+  describe '#run_competition' do
+    it 'broadcasts winning content' do
+      client.submit_for_broadcast(content: 'strong', source: :emotion, domain: :safety, salience: 0.9)
+      result = client.run_competition
+      expect(result[:success]).to be true
+      expect(result[:broadcast][:content]).to eq('strong')
+    end
+
+    it 'returns no_winner when no competitors' do
+      result = client.run_competition
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:no_winner)
+    end
+  end
+
+  describe '#register_subscriber / #unregister_subscriber' do
+    it 'registers a subscriber' do
+      result = client.register_subscriber(id: :memory, name: 'lex-memory', domains: [:all])
+      expect(result[:success]).to be true
+      expect(result[:subscriber_count]).to eq(1)
+    end
+
+    it 'unregisters a subscriber' do
+      client.register_subscriber(id: :memory, name: 'lex-memory')
+      result = client.unregister_subscriber(id: :memory)
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#acknowledge_broadcast' do
+    it 'acknowledges active broadcast' do
+      client.submit_for_broadcast(content: 'idea', source: :s, domain: :d, salience: 0.9)
+      client.run_competition
+      result = client.acknowledge_broadcast(subscriber_id: :memory)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns false when no broadcast' do
+      result = client.acknowledge_broadcast(subscriber_id: :memory)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#query_consciousness' do
+    it 'returns conscious: true for broadcasted content' do
+      client.submit_for_broadcast(content: 'idea', source: :s, domain: :d, salience: 0.9)
+      client.run_competition
+      result = client.query_consciousness(content: 'idea')
+      expect(result[:conscious]).to be true
+    end
+
+    it 'returns conscious: false for non-broadcasted content' do
+      result = client.query_consciousness(content: 'nothing')
+      expect(result[:conscious]).to be false
+    end
+  end
+
+  describe '#current_broadcast' do
+    it 'returns broadcast when active' do
+      client.submit_for_broadcast(content: 'idea', source: :s, domain: :d, salience: 0.9)
+      client.run_competition
+      result = client.current_broadcast
+      expect(result[:broadcast]).not_to be_nil
+      expect(result[:broadcast][:content]).to eq('idea')
+    end
+
+    it 'returns nil when no active broadcast' do
+      result = client.current_broadcast
+      expect(result[:broadcast]).to be_nil
+    end
+  end
+
+  describe '#broadcast_history' do
+    it 'returns history' do
+      client.submit_for_broadcast(content: 'idea', source: :s, domain: :d, salience: 0.9)
+      client.run_competition
+      result = client.broadcast_history(limit: 5)
+      expect(result[:success]).to be true
+      expect(result[:history].size).to eq(1)
+    end
+  end
+
+  describe '#update_global_workspace' do
+    it 'runs tick maintenance' do
+      result = client.update_global_workspace
+      expect(result[:success]).to be true
+      expect(result).to have_key(:state)
+      expect(result).to have_key(:utilization)
+    end
+  end
+
+  describe '#workspace_stats' do
+    it 'returns stats' do
+      result = client.workspace_stats
+      expect(result[:success]).to be true
+      expect(result[:stats]).to include(:state, :subscribers, :competitors, :utilization)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,20 @@
+# 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
+end
+
+require 'legion/extensions/global_workspace'
+
+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,80 @@
+--- !ruby/object:Gem::Specification
+name: lex-global-workspace
+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: Baars' Global Workspace Theory for brain-modeled agentic AI — information
+  competes for access to a limited-capacity workspace; winners are broadcast to all
+  subscribed cognitive subsystems, implementing a computational model of conscious
+  access and attentional bottleneck.
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- lex-global-workspace.gemspec
+- lib/legion/extensions/global_workspace.rb
+- lib/legion/extensions/global_workspace/actors/competition.rb
+- lib/legion/extensions/global_workspace/client.rb
+- lib/legion/extensions/global_workspace/helpers/broadcast.rb
+- lib/legion/extensions/global_workspace/helpers/competitor.rb
+- lib/legion/extensions/global_workspace/helpers/constants.rb
+- lib/legion/extensions/global_workspace/helpers/workspace.rb
+- lib/legion/extensions/global_workspace/runners/global_workspace.rb
+- lib/legion/extensions/global_workspace/version.rb
+- spec/legion/extensions/global_workspace/client_spec.rb
+- spec/legion/extensions/global_workspace/helpers/broadcast_spec.rb
+- spec/legion/extensions/global_workspace/helpers/competitor_spec.rb
+- spec/legion/extensions/global_workspace/helpers/workspace_spec.rb
+- spec/legion/extensions/global_workspace/runners/global_workspace_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-global-workspace
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-global-workspace
+  source_code_uri: https://github.com/LegionIO/lex-global-workspace
+  documentation_uri: https://github.com/LegionIO/lex-global-workspace
+  changelog_uri: https://github.com/LegionIO/lex-global-workspace
+  bug_tracker_uri: https://github.com/LegionIO/lex-global-workspace/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 Global Workspace
+test_files: []