lex-agentic-social 0.1.13 → 0.1.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f68ab7b55f1227a283fd1d658a83972249adf14c16c830f05484b7e7c4dbdd5
-  data.tar.gz: e4c8b7b5d490ced1d15657a28a695a51ec2282f9dd3b3a6777502e4728ce3a33
+  metadata.gz: 785afcf396e852ec5c417d3ddd68f04dc62bb290f5687a9115156f98cf5f59d2
+  data.tar.gz: f6ee2703b49a5e2dcc331596f703dee60a8ddd8ea601425439e26cc4b2e00706
 SHA512:
-  metadata.gz: 8a905ea7a1dd03b5bf61f3fece78f6add34b32830f843914857d115a9a44e708a01944e94a7310a2339c2ae674449f8cc11671823a3b06352c135a08ca4f8349
-  data.tar.gz: 1a7f7af65cbba67a13d23f9aec91403f82081df517d3283fc2ad91827e8cdbdf73d2139f83333a881c3db3c27d1a8a6d9a8ffb7dcd95c1a970d26cbfd4de130b
+  metadata.gz: 687b70c4adafc0718c5634a83ad86353bc02f3b42782eae1d62b637081a4b69f9e4554942f8e9b2f09b28d78d6f4571a09d422259e160c69056bdd091f06d5bd
+  data.tar.gz: c6236731a1a0fae572ed1a36af0b7e7f8e842a95b64b1eac16331a2a366782d99a7313f82a7faa0f9f67b30668f25242a7a4ffd7573ede3105c6de1474b069e3

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [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/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.14'
       end
     end
   end

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.14
 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