lex-agentic-social 0.1.13 → 0.1.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f68ab7b55f1227a283fd1d658a83972249adf14c16c830f05484b7e7c4dbdd5
-  data.tar.gz: e4c8b7b5d490ced1d15657a28a695a51ec2282f9dd3b3a6777502e4728ce3a33
+  metadata.gz: 4ae718ace3eafb04ea8f811bb5cf0d9ef384e6b63887f1423c8461b04269a524
+  data.tar.gz: 84e78ce21707ba78c4f90dc5168a99ca494fa4610d12cc609a72f5664cf43bee
 SHA512:
-  metadata.gz: 8a905ea7a1dd03b5bf61f3fece78f6add34b32830f843914857d115a9a44e708a01944e94a7310a2339c2ae674449f8cc11671823a3b06352c135a08ca4f8349
-  data.tar.gz: 1a7f7af65cbba67a13d23f9aec91403f82081df517d3283fc2ad91827e8cdbdf73d2139f83333a881c3db3c27d1a8a6d9a8ffb7dcd95c1a970d26cbfd4de130b
+  metadata.gz: 14f3884ae4814a76e9872081d132cd4b9b3fbf5a3dcf247541a67e5cf6c4d3a152e071753de8fc45a50a99cdb83df78dc2a8019f1fb949dea1f628a4da7870af
+  data.tar.gz: 3f991289c88888c67ddb146e094ea07f39f7fd79698c35c1b8b4bbb01cf29c74e6b256238c4b0f6b2c411eab6a070893db5350a99c8c1f0e7775461eca2c0ce4

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.1.15] - 2026-04-27
+### Fixed
+- Stop social calibration partner-knowledge promotion when Legion is shutting down or Apollo Local becomes unavailable between promotable tag groups
+
+## [0.1.14] - 2026-04-22
+### Added
+- `Governance#review_transition` method — API expected by lex-extinction for containment governance gate
+- Mirror::Actor::ResonanceDecay (120s) for `decay_resonances`
+### Fixed
+- `Governance#validate_action` now logs the action parameter instead of ignoring it
+- Documented Mirror vs MirrorSystem state isolation and ObservedBehavior class distinctions
+
 ## [0.1.13] - 2026-04-15
 ### Changed
 - Set `mcp_tools?`, `mcp_tools_deferred?`, and `transport_required?` to `false` — internal cognitive pipeline extension

data/README.md

@@ -1,45 +1,52 @@
 # lex-agentic-social
 
-Domain consolidation gem for social cognition, governance, and multi-agent interaction. Bundles 17 source extensions into one loadable unit under `Legion::Extensions::Agentic::Social`.
+Domain consolidation gem for social cognition, governance, and multi-agent interaction. Bundles 17 sub-modules into one loadable unit under `Legion::Extensions::Agentic::Social`.
 
 ## Overview
 
 **Gem**: `lex-agentic-social`
-**Version**: 0.1.13
+**Version**: 0.1.14
 **Namespace**: `Legion::Extensions::Agentic::Social`
 
 ## Sub-Modules
 
-| Sub-Module | Source Gem | Purpose |
-|---|---|---|
-| `Social::Social` | `lex-social` | Group membership, multi-dimensional reputation, reciprocity, norm violations |
-| `Social::TheoryOfMind` | `lex-theory-of-mind` | BDI model — belief/desire/intention tracking, false-belief detection |
-| `Social::Mentalizing` | `lex-mentalizing` | Mentalizing network — tracking of mentalizing capacity |
-| `Social::SocialLearning` | `lex-social-learning` | Learning by observation — vicarious reinforcement |
-| `Social::PerspectiveShifting` | `lex-perspective-shifting` | Deliberate perspective adoption |
-| `Social::Trust` | `lex-trust` | Domain-scoped trust scores — asymmetric reinforcement and decay |
-| `Social::Conflict` | `lex-conflict` | Conflict registration, severity-based posture, optional LLM resolution |
-| `Social::Conscience` | `lex-conscience` | Internalized moral compass — guilt/pride signal generation |
-| `Social::Consent` | `lex-consent` | Four-tier consent gradient with earned autonomy, HITL gate |
-| `Social::MoralReasoning` | `lex-moral-reasoning` | Six Haidt foundations, six Kohlberg stages, six ethical frameworks |
-| `Social::Governance` | `lex-governance` | Four-layer governance — council proposals, quorum voting, action validation |
-| `Social::JointAttention` | `lex-joint-attention` | Shared attention between agents — coordinating focus |
-| `Social::Mirror` | `lex-mirror` | Mirror neuron analog — action observation and imitation |
-| `Social::MirrorSystem` | `lex-mirror` | Extended mirror system |
-| `Social::Entrainment` | `lex-cognitive-entrainment` | Rhythmic synchronization between agents |
-| `Social::Symbiosis` | `lex-cognitive-symbiosis` | Mutually beneficial cognitive partnerships |
-| `Social::Apprenticeship` | `lex-cognitive-apprenticeship` | Expert-novice learning relationships |
+| Sub-Module | Purpose |
+|---|---|
+| `Social::Social` | Group membership, multi-dimensional reputation, reciprocity, norm violations |
+| `Social::TheoryOfMind` | BDI model — belief/desire/intention tracking, false-belief detection |
+| `Social::Mentalizing` | Mentalizing network — tracking of mentalizing capacity |
+| `Social::SocialLearning` | Learning by observation — vicarious reinforcement |
+| `Social::PerspectiveShifting` | Deliberate perspective adoption |
+| `Social::Trust` | Domain-scoped trust scores — asymmetric reinforcement and decay |
+| `Social::Conflict` | Conflict registration, severity-based posture, optional LLM resolution |
+| `Social::Conscience` | Internalized moral compass — guilt/pride signal generation |
+| `Social::Consent` | Four-tier consent gradient with earned autonomy, HITL gate |
+| `Social::MoralReasoning` | Six Haidt foundations, six Kohlberg stages, six ethical frameworks |
+| `Social::Governance` | Four-layer governance — council proposals, quorum voting, action validation |
+| `Social::JointAttention` | Shared attention between agents — coordinating focus |
+| `Social::Mirror` | Mirror neuron analog — action observation, simulation, and resonance decay |
+| `Social::MirrorSystem` | Extended mirror system with resonance-based familiarity tracking |
+| `Social::Entrainment` | Rhythmic synchronization between agents |
+| `Social::Symbiosis` | Mutually beneficial cognitive partnerships |
+| `Social::Apprenticeship` | Expert-novice learning relationships |
 
 ## Actors
 
-- `Social::Conflict::Actors::StaleCheck` — runs every 3600s, checks for stale conflicts
-- `Social::Consent::Actors::TierEvaluation` — runs every 3600s, evaluates and applies consent tiers
+9 actors handle autonomous background processing:
+
+- `Social::Conflict::Actors::StaleCheck` — every 3600s, checks for stale conflicts
+- `Social::Consent::Actors::TierEvaluation` — every 3600s, evaluates and applies consent tiers
 - `Social::Governance::Actors::ShadowAiScan` — interval actor, scans for shadow AI activity
-- `Social::Governance::Actors::VoteTimeout` — runs every 300s, times out expired proposals
+- `Social::Governance::Actors::VoteTimeout` — every 300s, times out expired proposals
 - `Social::JointAttention::Actors::Decay` — interval actor, decays joint attention focus
 - `Social::Mentalizing::Actors::Decay` — interval actor, decays mentalizing model confidence
+- `Social::Mirror::Actor::ResonanceDecay` — every 120s, decays resonance on observed actions
 - `Social::MirrorSystem::Actors::Decay` — interval actor, decays mirror system activation
-- `Social::Trust::Actors::Decay` — runs every 300s, decays all trust scores
+- `Social::Trust::Actors::Decay` — every 300s, decays all trust scores
+
+## Safety Notes
+
+`Social::Consent` governs whether actions require human approval — the HITL gate must not be bypassed. `Social::Governance` provides the council approval mechanism used by `Defense::Extinction` for containment escalation.
 
 ## Installation
 
@@ -51,8 +58,8 @@ gem 'lex-agentic-social'
 
 ```bash
 bundle install
-bundle exec rspec        # 1673 examples, 0 failures
-bundle exec rubocop      # 0 offenses
+bundle exec rspec
+bundle exec rubocop
 ```
 
 ## License

data/lib/legion/extensions/agentic/social/calibration/runners/calibration.rb

@@ -79,10 +79,14 @@ module Legion
               end
 
               def promote_partner_knowledge(**)
+                return { success: true, skipped: :shutting_down } if shutting_down?
                 return { success: true, skipped: :local_unavailable } unless apollo_local_available?
 
                 total = 0
                 Helpers::Constants::PROMOTABLE_TAGS.each do |tags|
+                  return { success: true, promoted: total, stopped: :shutting_down } if shutting_down?
+                  return { success: true, promoted: total, stopped: :local_unavailable } unless apollo_local_available?
+
                   result = Legion::Apollo::Local.promote_to_global(tags: tags, min_confidence: Helpers::Constants::PROMOTION_MIN_CONFIDENCE)
                   total += result[:promoted] if result[:success]
                 end
@@ -112,6 +116,14 @@ module Legion
                 defined?(Legion::Apollo::Local) && Legion::Apollo::Local.started?
               end
 
+              def shutting_down?
+                return Legion.shutting_down? if defined?(Legion) && Legion.respond_to?(:shutting_down?)
+
+                defined?(Legion::Settings) && Legion::Settings.dig(:client, :shutting_down) == true
+              rescue StandardError => _e
+                false
+              end
+
               def retrieve_interaction_traces
                 traces = retrieve_from_memory
                 return traces if traces.any?

data/lib/legion/extensions/agentic/social/governance/helpers/proposal.rb

@@ -8,6 +8,11 @@ module Legion
       module Social
         module Governance
           module Helpers
+            # NOTE: Proposal state is stored in-memory only (@proposals hash).
+            # This is a safety-critical system (controls consent and containment approval).
+            # Persistence to a durable store (e.g. legion-data) is required so that
+            # proposals survive process restarts. Implementing persistence is tracked
+            # as a separate task.
             class Proposal
               attr_reader :proposals
 

data/lib/legion/extensions/agentic/social/governance/runners/governance.rb

@@ -56,9 +56,15 @@ module Legion
                 { checked: open.size, timed_out: timed.size, timed_out_ids: timed_ids }
               end
 
-              def validate_action(layer:, action: nil, _context: {}, **) # rubocop:disable Lint/UnusedMethodArgument
+              def review_transition(action:, authority: nil, context: {}, **)
+                log.info "[governance] review_transition: action=#{action} authority=#{authority}"
+                validate_action(layer: :agent_validation, action: action, _context: context)
+              end
+
+              def validate_action(layer:, action: nil, _context: {}, **)
                 return { error: :invalid_layer } unless Helpers::Layers.valid_layer?(layer)
 
+                log.info "[governance] validating action=#{action} layer=#{layer}"
                 result = case layer
                          when :agent_validation
                            { allowed: true, layer: layer, reason: :self_validated }

data/lib/legion/extensions/agentic/social/mirror/actors/resonance_decay.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module Mirror
+          module Actor
+            class ResonanceDecay < Legion::Extensions::Actors::Every
+              def runner_class
+                Legion::Extensions::Agentic::Social::Mirror::Client
+              end
+
+              def runner_function
+                'decay_resonances'
+              end
+
+              def time
+                120
+              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
+  end
+end

data/lib/legion/extensions/agentic/social/mirror/runners/observe.rb

@@ -40,6 +40,11 @@ module Legion
 
               private
 
+              # mirror_engine is provided by Mirror::Client, which initializes
+              # @mirror_engine once in its constructor and exposes it via attr_reader.
+              # All three runner modules (Observe, Simulate, Resonance) share that
+              # single engine instance through the Client, ensuring observations in
+              # Observe are visible to Resonance and Simulate.
               def mirror_engine
                 @mirror_engine ||= Helpers::MirrorEngine.new
               end

data/lib/legion/extensions/agentic/social/mirror/runners/resonance.rb

@@ -67,6 +67,10 @@ module Legion
 
               private
 
+              # mirror_engine is provided by Mirror::Client, which initializes
+              # @mirror_engine once in its constructor and exposes it via attr_reader.
+              # All three runner modules (Observe, Simulate, Resonance) share that
+              # single engine instance through the Client, ensuring state is not isolated.
               def mirror_engine
                 @mirror_engine ||= Helpers::MirrorEngine.new
               end

data/lib/legion/extensions/agentic/social/mirror/runners/simulate.rb

@@ -51,6 +51,10 @@ module Legion
 
               private
 
+              # mirror_engine is provided by Mirror::Client, which initializes
+              # @mirror_engine once in its constructor and exposes it via attr_reader.
+              # All three runner modules (Observe, Simulate, Resonance) share that
+              # single engine instance through the Client, ensuring state is not isolated.
               def mirror_engine
                 @mirror_engine ||= Helpers::MirrorEngine.new
               end

data/lib/legion/extensions/agentic/social/mirror.rb

@@ -8,6 +8,7 @@ require 'legion/extensions/agentic/social/mirror/helpers/mirror_engine'
 require 'legion/extensions/agentic/social/mirror/runners/observe'
 require 'legion/extensions/agentic/social/mirror/runners/simulate'
 require 'legion/extensions/agentic/social/mirror/runners/resonance'
+require 'legion/extensions/agentic/social/mirror/actors/resonance_decay'
 require 'legion/extensions/agentic/social/mirror/client'
 
 module Legion

data/lib/legion/extensions/agentic/social/mirror_system/helpers/observed_behavior.rb

@@ -1,5 +1,17 @@
 # frozen_string_literal: true
 
+# MirrorSystem::Helpers::ObservedBehavior models an ongoing observation of a
+# specific agent's behavior pattern, keyed by (agent_id, action, domain). It
+# tracks resonance (familiarity strength) that increases with repeated
+# observations (observe_again) or explicit simulation boosts (boost_familiarity)
+# and decays over time. Fidelity of imitation is tracked via observation_count.
+#
+# Distinct from SocialLearning::Helpers::ObservedBehavior, which is a one-shot
+# snapshot of a behavior modeled from another agent, with retention (recall)
+# mechanics and a reproduction flag. The SocialLearning variant focuses on
+# whether the observer can reproduce what it saw; the MirrorSystem variant
+# focuses on resonance-based familiarity and imitation fidelity over time.
+
 module Legion
   module Extensions
     module Agentic

data/lib/legion/extensions/agentic/social/social_learning/helpers/observed_behavior.rb

@@ -1,5 +1,16 @@
 # frozen_string_literal: true
 
+# SocialLearning::Helpers::ObservedBehavior models a behavior that one agent
+# observed from a *model agent* (social learning / imitation theory). It tracks
+# retention and reproduction: whether the observer can still recall and replicate
+# what it saw. Retention decays over time via decay_retention!.
+#
+# Distinct from MirrorSystem::Helpers::ObservedBehavior, which models an
+# ongoing observation stream for a specific agent keyed by (action, domain) with
+# resonance-based familiarity boosting and fidelity tracking. The MirrorSystem
+# variant supports repeated observations of the same behavior; the SocialLearning
+# variant is a one-shot snapshot of a modeled behavior with retention mechanics.
+
 require 'securerandom'
 
 module Legion

data/lib/legion/extensions/agentic/social/version.rb

@@ -4,7 +4,7 @@ module Legion
   module Extensions
     module Agentic
       module Social
-        VERSION = '0.1.13'
+        VERSION = '0.1.15'
       end
     end
   end

data/spec/legion/extensions/agentic/social/calibration/runners/calibration_spec.rb

@@ -146,6 +146,32 @@ RSpec.describe Legion::Extensions::Agentic::Social::Calibration::Runners::Calibr
       result = client.promote_partner_knowledge
       expect(result[:skipped]).to eq(:local_unavailable)
     end
+
+    it 'skips when Legion is shutting down' do
+      allow(Legion::Settings).to receive(:dig).with(:client, :shutting_down).and_return(true)
+
+      result = client.promote_partner_knowledge
+      expect(result[:skipped]).to eq(:shutting_down)
+    end
+
+    it 'stops when Apollo Local becomes unavailable between tag groups' do
+      mock_local = double('apollo_local')
+      stub_const('Legion::Apollo', Module.new)
+      stub_const('Legion::Apollo::Local', mock_local)
+      allow(Legion::Settings).to receive(:dig).with(:client, :shutting_down).and_return(false)
+      allow(mock_local).to receive(:started?).and_return(true, true, false)
+      expect(mock_local).to receive(:promote_to_global)
+        .with(
+          tags:           Legion::Extensions::Agentic::Social::Calibration::Helpers::Constants::PROMOTABLE_TAGS.first,
+          min_confidence: Legion::Extensions::Agentic::Social::Calibration::Helpers::Constants::PROMOTION_MIN_CONFIDENCE
+        )
+        .once
+        .and_return({ success: true, promoted: 2 })
+
+      result = client.promote_partner_knowledge
+      expect(result[:promoted]).to eq(2)
+      expect(result[:stopped]).to eq(:local_unavailable)
+    end
   end
 
   describe '#sync_partner_knowledge' do

data/spec/legion/extensions/agentic/social/governance/runners/governance_spec.rb

@@ -40,6 +40,18 @@ RSpec.describe Legion::Extensions::Agentic::Social::Governance::Runners::Governa
     end
   end
 
+  describe '#review_transition' do
+    it 'delegates to validate_action and returns allowed: true' do
+      result = client.review_transition(action: 'terminate', authority: 'admin')
+      expect(result[:allowed]).to be true
+    end
+
+    it 'accepts context keyword argument' do
+      result = client.review_transition(action: 'pause', context: { reason: 'maintenance' })
+      expect(result).to have_key(:allowed)
+    end
+  end
+
   describe '#validate_action' do
     it 'allows agent_validation' do
       result = client.validate_action(layer: :agent_validation, action: 'test')

data/spec/legion/extensions/agentic/social/mirror/actors/resonance_decay_spec.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# Stub the framework actor base class since legionio gem is not available in test
+unless defined?(Legion::Extensions::Actors::Every)
+  module Legion
+    module Extensions
+      module Actors
+        class Every # rubocop:disable Lint/EmptyClass
+        end
+      end
+    end
+  end
+end
+
+# Intercept the require in the actor file so it doesn't fail
+$LOADED_FEATURES << 'legion/extensions/actors/every' unless $LOADED_FEATURES.include?('legion/extensions/actors/every')
+
+require 'legion/extensions/agentic/social/mirror/actors/resonance_decay'
+
+RSpec.describe Legion::Extensions::Agentic::Social::Mirror::Actor::ResonanceDecay do
+  subject(:actor) { described_class.new }
+
+  describe '#runner_class' do
+    it 'returns Mirror::Client' do
+      expect(actor.runner_class).to eq(Legion::Extensions::Agentic::Social::Mirror::Client)
+    end
+  end
+
+  describe '#runner_function' do
+    it 'returns decay_resonances' do
+      expect(actor.runner_function).to eq('decay_resonances')
+    end
+  end
+
+  describe '#time' do
+    it 'returns 120 seconds' do
+      expect(actor.time).to eq(120)
+    end
+  end
+
+  describe '#run_now?' do
+    it 'returns false' do
+      expect(actor.run_now?).to be false
+    end
+  end
+
+  describe '#use_runner?' do
+    it 'returns false' do
+      expect(actor.use_runner?).to be false
+    end
+  end
+
+  describe '#check_subtask?' do
+    it 'returns false' do
+      expect(actor.check_subtask?).to be false
+    end
+  end
+
+  describe '#generate_task?' do
+    it 'returns false' do
+      expect(actor.generate_task?).to be false
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-agentic-social
 version: !ruby/object:Gem::Version
-  version: 0.1.13
+  version: 0.1.15
 platform: ruby
 authors:
 - Esity
@@ -251,6 +251,7 @@ files:
 - lib/legion/extensions/agentic/social/mentalizing/runners/mentalizing.rb
 - lib/legion/extensions/agentic/social/mentalizing/version.rb
 - lib/legion/extensions/agentic/social/mirror.rb
+- lib/legion/extensions/agentic/social/mirror/actors/resonance_decay.rb
 - lib/legion/extensions/agentic/social/mirror/client.rb
 - lib/legion/extensions/agentic/social/mirror/helpers/constants.rb
 - lib/legion/extensions/agentic/social/mirror/helpers/mirror_engine.rb
@@ -370,6 +371,7 @@ files:
 - spec/legion/extensions/agentic/social/mentalizing/helpers/belief_attribution_spec.rb
 - spec/legion/extensions/agentic/social/mentalizing/helpers/mental_model_spec.rb
 - spec/legion/extensions/agentic/social/mentalizing/runners/mentalizing_spec.rb
+- spec/legion/extensions/agentic/social/mirror/actors/resonance_decay_spec.rb
 - spec/legion/extensions/agentic/social/mirror/client_spec.rb
 - spec/legion/extensions/agentic/social/mirror/helpers/constants_spec.rb
 - spec/legion/extensions/agentic/social/mirror/helpers/mirror_engine_spec.rb