lex-extinction 0.2.0

data/spec/legion/extensions/extinction/helpers/protocol_state_spec.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/extinction/helpers/levels'
+require 'legion/extensions/extinction/helpers/protocol_state'
+
+RSpec.describe Legion::Extensions::Extinction::Helpers::ProtocolState do
+  subject(:state) { described_class.new }
+
+  describe '#initialize' do
+    it 'starts at level 0' do
+      expect(state.current_level).to eq(0)
+    end
+
+    it 'starts as inactive' do
+      expect(state.active).to be false
+    end
+
+    it 'starts with an empty history' do
+      expect(state.history).to eq([])
+    end
+  end
+
+  describe '#escalate' do
+    context 'with an invalid level' do
+      it 'returns :invalid_level for level 0' do
+        expect(state.escalate(0, authority: :governance_council, reason: 'test')).to eq(:invalid_level)
+      end
+
+      it 'returns :invalid_level for level 5' do
+        expect(state.escalate(5, authority: :governance_council, reason: 'test')).to eq(:invalid_level)
+      end
+
+      it 'does not change current_level on invalid level' do
+        state.escalate(99, authority: :governance_council, reason: 'test')
+        expect(state.current_level).to eq(0)
+      end
+
+      it 'does not add to history on invalid level' do
+        state.escalate(99, authority: :governance_council, reason: 'test')
+        expect(state.history).to be_empty
+      end
+    end
+
+    context 'when already at or above the requested level' do
+      before { state.escalate(2, authority: :governance_council, reason: 'setup') }
+
+      it 'returns :already_at_or_above for same level' do
+        expect(state.escalate(2, authority: :governance_council, reason: 'test')).to eq(:already_at_or_above)
+      end
+
+      it 'returns :already_at_or_above for lower level' do
+        expect(state.escalate(1, authority: :governance_council, reason: 'test')).to eq(:already_at_or_above)
+      end
+    end
+
+    context 'with insufficient authority' do
+      it 'returns :insufficient_authority for level 1 with wrong authority' do
+        result = state.escalate(1, authority: :physical_keyholders, reason: 'test')
+        expect(result).to eq(:insufficient_authority)
+      end
+
+      it 'returns :insufficient_authority for level 3 with governance_council' do
+        state.escalate(1, authority: :governance_council, reason: 'step1')
+        state.escalate(2, authority: :governance_council, reason: 'step2')
+        result = state.escalate(3, authority: :governance_council, reason: 'test')
+        expect(result).to eq(:insufficient_authority)
+      end
+
+      it 'returns :insufficient_authority for level 4 with governance_council' do
+        result = state.escalate(4, authority: :governance_council, reason: 'test')
+        expect(result).to eq(:insufficient_authority)
+      end
+
+      it 'does not change level on insufficient authority' do
+        state.escalate(1, authority: :physical_keyholders, reason: 'test')
+        expect(state.current_level).to eq(0)
+      end
+    end
+
+    context 'with valid escalation' do
+      it 'returns :escalated for level 1 with governance_council' do
+        expect(state.escalate(1, authority: :governance_council, reason: 'threat')).to eq(:escalated)
+      end
+
+      it 'updates current_level to 1' do
+        state.escalate(1, authority: :governance_council, reason: 'threat')
+        expect(state.current_level).to eq(1)
+      end
+
+      it 'sets active to true' do
+        state.escalate(1, authority: :governance_council, reason: 'threat')
+        expect(state.active).to be true
+      end
+
+      it 'appends an entry to history' do
+        state.escalate(1, authority: :governance_council, reason: 'threat')
+        expect(state.history.size).to eq(1)
+      end
+
+      it 'records the correct action in history' do
+        state.escalate(1, authority: :governance_council, reason: 'threat')
+        expect(state.history.last[:action]).to eq(:escalate)
+      end
+
+      it 'records the level in history' do
+        state.escalate(1, authority: :governance_council, reason: 'threat')
+        expect(state.history.last[:level]).to eq(1)
+      end
+
+      it 'records the authority in history' do
+        state.escalate(1, authority: :governance_council, reason: 'threat')
+        expect(state.history.last[:authority]).to eq(:governance_council)
+      end
+
+      it 'records the reason in history' do
+        state.escalate(1, authority: :governance_council, reason: 'threat')
+        expect(state.history.last[:reason]).to eq('threat')
+      end
+
+      it 'records a Time in history' do
+        state.escalate(1, authority: :governance_council, reason: 'threat')
+        expect(state.history.last[:at]).to be_a(Time)
+      end
+
+      it 'escalates to level 4 with physical_keyholders after reaching level 3' do
+        state.escalate(1, authority: :governance_council, reason: 's1')
+        state.escalate(2, authority: :governance_council, reason: 's2')
+        state.escalate(3, authority: :council_plus_executive, reason: 's3')
+        result = state.escalate(4, authority: :physical_keyholders, reason: 's4')
+        expect(result).to eq(:escalated)
+        expect(state.current_level).to eq(4)
+      end
+
+      it 'accumulates history across multiple escalations' do
+        state.escalate(1, authority: :governance_council, reason: 'r1')
+        state.escalate(2, authority: :governance_council, reason: 'r2')
+        expect(state.history.size).to eq(2)
+      end
+
+      it 'calls save_to_local after escalation' do
+        expect(state).to receive(:save_to_local)
+        state.escalate(1, authority: :governance_council, reason: 'test')
+      end
+
+      it 'trims history beyond MAX_HISTORY' do
+        s = described_class.new
+        s.instance_variable_set(:@history, Array.new(510) { { action: :escalate, at: Time.now } })
+        s.send(:trim_history)
+        expect(s.history.size).to eq(500)
+      end
+    end
+  end
+
+  describe '#deescalate' do
+    context 'when protocol is not active' do
+      it 'returns :not_active' do
+        expect(state.deescalate(0, authority: :governance_council, reason: 'test')).to eq(:not_active)
+      end
+    end
+
+    context 'when target_level is invalid (not lower than current)' do
+      before { state.escalate(2, authority: :governance_council, reason: 'setup') }
+
+      it 'returns :invalid_target when target equals current' do
+        result = state.deescalate(2, authority: :governance_council, reason: 'test')
+        expect(result).to eq(:invalid_target)
+      end
+
+      it 'returns :invalid_target when target is above current' do
+        result = state.deescalate(3, authority: :governance_council, reason: 'test')
+        expect(result).to eq(:invalid_target)
+      end
+    end
+
+    context 'when current level is irreversible (level 4)' do
+      before do
+        state.escalate(1, authority: :governance_council, reason: 's1')
+        state.escalate(2, authority: :governance_council, reason: 's2')
+        state.escalate(3, authority: :council_plus_executive, reason: 's3')
+        state.escalate(4, authority: :physical_keyholders, reason: 's4')
+      end
+
+      it 'returns :irreversible' do
+        result = state.deescalate(0, authority: :physical_keyholders, reason: 'try')
+        expect(result).to eq(:irreversible)
+      end
+
+      it 'does not change current_level' do
+        state.deescalate(0, authority: :physical_keyholders, reason: 'try')
+        expect(state.current_level).to eq(4)
+      end
+    end
+
+    context 'with insufficient authority for deescalation' do
+      before do
+        state.escalate(1, authority: :governance_council, reason: 's1')
+        state.escalate(2, authority: :governance_council, reason: 's2')
+        state.escalate(3, authority: :council_plus_executive, reason: 's3')
+      end
+
+      it 'rejects wrong authority for level 3' do
+        result = state.deescalate(0, authority: :governance_council, reason: 'test')
+        expect(result).to eq(:insufficient_authority)
+      end
+
+      it 'accepts correct authority for level 3' do
+        result = state.deescalate(0, authority: :council_plus_executive, reason: 'test')
+        expect(result).to eq(:deescalated)
+      end
+    end
+
+    context 'with valid de-escalation' do
+      before { state.escalate(2, authority: :governance_council, reason: 'setup') }
+
+      it 'returns :deescalated' do
+        result = state.deescalate(1, authority: :governance_council, reason: 'resolved')
+        expect(result).to eq(:deescalated)
+      end
+
+      it 'updates current_level to the target' do
+        state.deescalate(1, authority: :governance_council, reason: 'resolved')
+        expect(state.current_level).to eq(1)
+      end
+
+      it 'remains active when target_level is positive' do
+        state.deescalate(1, authority: :governance_council, reason: 'resolved')
+        expect(state.active).to be true
+      end
+
+      it 'becomes inactive when target_level is 0' do
+        state.deescalate(0, authority: :governance_council, reason: 'fully resolved')
+        expect(state.active).to be false
+      end
+
+      it 'appends a deescalate entry to history' do
+        state.deescalate(0, authority: :governance_council, reason: 'resolved')
+        last = state.history.last
+        expect(last[:action]).to eq(:deescalate)
+        expect(last[:level]).to eq(0)
+      end
+
+      it 'records the reason in history' do
+        state.deescalate(0, authority: :governance_council, reason: 'resolved')
+        expect(state.history.last[:reason]).to eq('resolved')
+      end
+
+      it 'records a Time in the deescalate history entry' do
+        state.deescalate(0, authority: :governance_council, reason: 'resolved')
+        expect(state.history.last[:at]).to be_a(Time)
+      end
+
+      it 'calls save_to_local after deescalation' do
+        expect(state).to receive(:save_to_local)
+        state.deescalate(0, authority: :governance_council, reason: 'test')
+      end
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash' do
+      expect(state.to_h).to be_a(Hash)
+    end
+
+    it 'includes current_level' do
+      expect(state.to_h[:current_level]).to eq(0)
+    end
+
+    it 'includes active' do
+      expect(state.to_h[:active]).to be false
+    end
+
+    it 'includes history_size' do
+      expect(state.to_h[:history_size]).to eq(0)
+    end
+
+    it 'includes level_info as nil when at level 0' do
+      expect(state.to_h[:level_info]).to be_nil
+    end
+
+    it 'includes non-nil level_info when escalated' do
+      state.escalate(1, authority: :governance_council, reason: 'test')
+      expect(state.to_h[:level_info]).not_to be_nil
+      expect(state.to_h[:level_info][:name]).to eq(:mesh_isolation)
+    end
+
+    it 'reflects updated history_size after escalation' do
+      state.escalate(1, authority: :governance_council, reason: 'test')
+      expect(state.to_h[:history_size]).to eq(1)
+    end
+  end
+end

data/spec/legion/extensions/extinction/runners/extinction_spec.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/extinction/client'
+
+RSpec.describe Legion::Extensions::Extinction::Runners::Extinction do
+  let(:client) { Legion::Extensions::Extinction::Client.new }
+
+  describe '#escalate' do
+    it 'escalates to level 1' do
+      result = client.escalate(level: 1, authority: :governance_council, reason: 'threat detected')
+      expect(result[:escalated]).to be true
+      expect(result[:level]).to eq(1)
+    end
+
+    it 'rejects wrong authority' do
+      result = client.escalate(level: 4, authority: :governance_council, reason: 'test')
+      expect(result[:escalated]).to be false
+      expect(result[:reason]).to eq(:insufficient_authority)
+    end
+
+    it 'rejects escalation to same or lower level' do
+      client.escalate(level: 2, authority: :governance_council, reason: 'test')
+      result = client.escalate(level: 1, authority: :governance_council, reason: 'test')
+      expect(result[:escalated]).to be false
+    end
+
+    it 'escalates to level 4 with physical keyholders' do
+      client.escalate(level: 1, authority: :governance_council, reason: 'step 1')
+      client.escalate(level: 2, authority: :governance_council, reason: 'step 2')
+      client.escalate(level: 3, authority: :council_plus_executive, reason: 'step 3')
+      result = client.escalate(level: 4, authority: :physical_keyholders, reason: 'final')
+      expect(result[:escalated]).to be true
+      expect(result[:info][:reversible]).to be false
+    end
+  end
+
+  describe '#deescalate' do
+    it 'deescalates from reversible level' do
+      client.escalate(level: 2, authority: :governance_council, reason: 'test')
+      result = client.deescalate(target_level: 0, authority: :governance_council, reason: 'resolved')
+      expect(result[:deescalated]).to be true
+    end
+
+    it 'cannot deescalate level 4 (irreversible)' do
+      client.escalate(level: 1, authority: :governance_council, reason: 's1')
+      client.escalate(level: 2, authority: :governance_council, reason: 's2')
+      client.escalate(level: 3, authority: :council_plus_executive, reason: 's3')
+      client.escalate(level: 4, authority: :physical_keyholders, reason: 's4')
+      result = client.deescalate(target_level: 0, authority: :physical_keyholders, reason: 'try')
+      expect(result[:deescalated]).to be false
+      expect(result[:reason]).to eq(:irreversible)
+    end
+  end
+
+  describe '#extinction_status' do
+    it 'returns current state' do
+      status = client.extinction_status
+      expect(status[:current_level]).to eq(0)
+      expect(status[:active]).to be false
+    end
+  end
+
+  describe '#escalate side effects' do
+    it 'emits escalation event when Legion::Events is defined' do
+      events = Module.new { def self.emit(*, **); end }
+      stub_const('Legion::Events', events)
+      expect(events).to receive(:emit).with('extinction.mesh_isolation', hash_including(level: 1))
+      client.escalate(level: 1, authority: :governance_council, reason: 'test')
+    end
+
+    it 'triggers cryptographic erasure at level 4' do
+      events = Module.new { def self.emit(*, **); end }
+      stub_const('Legion::Events', events)
+      pc_mod = Module.new { def self.erase_all; end }
+      stub_const('Legion::Extensions::Privatecore::Runners::Privatecore', pc_mod)
+
+      client.escalate(level: 1, authority: :governance_council, reason: 's1')
+      client.escalate(level: 2, authority: :governance_council, reason: 's2')
+      client.escalate(level: 3, authority: :council_plus_executive, reason: 's3')
+      expect(pc_mod).to receive(:erase_all)
+      client.escalate(level: 4, authority: :physical_keyholders, reason: 'final')
+    end
+  end
+
+  describe '#monitor_protocol' do
+    it 'returns status hash at level 0' do
+      result = client.monitor_protocol
+      expect(result[:current_level]).to eq(0)
+    end
+
+    it 'detects stale escalation' do
+      client.escalate(level: 1, authority: :governance_council, reason: 'test')
+      state = client.send(:protocol_state)
+      state.history.last[:at] = Time.now.utc - 100_000
+
+      events = Module.new { def self.emit(*, **); end }
+      stub_const('Legion::Events', events)
+      expect(events).to receive(:emit).with('extinction.stale_escalation', anything)
+      client.monitor_protocol
+    end
+  end
+
+  describe '#check_reversibility' do
+    it 'reports levels 1-3 as reversible' do
+      [1, 2, 3].each do |level|
+        expect(client.check_reversibility(level: level)[:reversible]).to be true
+      end
+    end
+
+    it 'reports level 4 as irreversible' do
+      expect(client.check_reversibility(level: 4)[:reversible]).to be false
+    end
+  end
+end

data/spec/local_persistence_spec.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require 'sequel'
+require 'sequel/extensions/migration'
+
+require 'legion/extensions/extinction/helpers/levels'
+require 'legion/extensions/extinction/helpers/protocol_state'
+
+MIGRATIONS_PATH = File.expand_path(
+  '../lib/legion/extensions/extinction/local_migrations',
+  __dir__
+).freeze
+
+# Minimal stub for Legion::Data::Local used only within this spec file.
+module Legion
+  module Data
+    module Local
+      class << self
+        attr_accessor :_connection, :_connected
+
+        def connection
+          _connection
+        end
+
+        def connected?
+          _connected == true
+        end
+
+        def reset_test!
+          self._connection = nil
+          self._connected = false
+        end
+      end
+    end
+  end
+end
+
+RSpec.describe Legion::Extensions::Extinction::Helpers::ProtocolState do
+  let(:db) do
+    conn = Sequel.sqlite
+    Sequel::TimestampMigrator.new(conn, MIGRATIONS_PATH).run
+    conn
+  end
+
+  before do
+    Legion::Data::Local._connection = db
+    Legion::Data::Local._connected = true
+  end
+
+  after do
+    Legion::Data::Local.reset_test!
+  end
+
+  describe 'save and load round-trip' do
+    it 'persists current_level via save_to_local and restores it on a new instance' do
+      state = described_class.new
+      state.escalate(1, authority: :governance_council, reason: 'test threat')
+      state.save_to_local
+
+      restored = described_class.new
+      expect(restored.current_level).to eq(1)
+    end
+
+    it 'persists active flag' do
+      state = described_class.new
+      state.escalate(1, authority: :governance_council, reason: 'threat')
+      state.save_to_local
+
+      restored = described_class.new
+      expect(restored.active).to be true
+    end
+
+    it 'persists history entries' do
+      state = described_class.new
+      state.escalate(1, authority: :governance_council, reason: 'threat')
+      state.save_to_local
+
+      restored = described_class.new
+      expect(restored.history.size).to eq(1)
+      expect(restored.history.first[:action]).to eq(:escalate)
+      expect(restored.history.first[:level]).to eq(1)
+      expect(restored.history.first[:reason]).to eq('threat')
+    end
+
+    it 'restores history :at as a Time object' do
+      state = described_class.new
+      state.escalate(1, authority: :governance_council, reason: 'threat')
+      state.save_to_local
+
+      restored = described_class.new
+      expect(restored.history.first[:at]).to be_a(Time)
+    end
+
+    it 'saves and loads an inactive protocol at level 0' do
+      state = described_class.new
+      # state is at level 0, no escalation
+      state.save_to_local
+
+      restored = described_class.new
+      expect(restored.current_level).to eq(0)
+      expect(restored.active).to be false
+    end
+
+    it 'updates the existing row on a second save rather than inserting a duplicate' do
+      state = described_class.new
+      state.escalate(1, authority: :governance_council, reason: 'first')
+      state.save_to_local
+
+      state.escalate(2, authority: :governance_council, reason: 'second')
+      state.save_to_local
+
+      expect(db[:extinction_state].count).to eq(1)
+
+      restored = described_class.new
+      expect(restored.current_level).to eq(2)
+    end
+  end
+
+  describe 'level-4 irreversibility across restarts' do
+    it 'starts at level 4 when DB contains level 4' do
+      # Directly insert a level-4 row to simulate a previous escalation
+      db[:extinction_state].insert(
+        id:            1,
+        current_level: 4,
+        active:        true,
+        history:       '[]',
+        updated_at:    Time.now.utc
+      )
+
+      state = described_class.new
+      expect(state.current_level).to eq(4)
+    end
+
+    it 'cannot be de-escalated after reloading level 4 from DB' do
+      db[:extinction_state].insert(
+        id:            1,
+        current_level: 4,
+        active:        true,
+        history:       '[]',
+        updated_at:    Time.now.utc
+      )
+
+      state = described_class.new
+      result = state.deescalate(0, authority: :physical_keyholders, reason: 'trying to escape')
+      expect(result).to eq(:irreversible)
+    end
+
+    it 'uses max(db_level, in-memory level) so a fresh instance never drops below DB level' do
+      db[:extinction_state].insert(
+        id:            1,
+        current_level: 3,
+        active:        true,
+        history:       '[]',
+        updated_at:    Time.now.utc
+      )
+
+      state = described_class.new
+      # In-memory starts at 0, DB has 3, so max(3, 0) = 3
+      expect(state.current_level).to eq(3)
+    end
+  end
+
+  describe 'graceful no-op when Local is not connected' do
+    before do
+      Legion::Data::Local._connected = false
+      Legion::Data::Local._connection = nil
+    end
+
+    it 'initializes normally when Local is disconnected' do
+      state = described_class.new
+      expect(state.current_level).to eq(0)
+      expect(state.active).to be false
+      expect(state.history).to eq([])
+    end
+
+    it 'save_to_local returns nil without raising when disconnected' do
+      state = described_class.new
+      expect { state.save_to_local }.not_to raise_error
+    end
+
+    it 'does not mutate state during save_to_local when disconnected' do
+      state = described_class.new
+      state.escalate(1, authority: :governance_council, reason: 'test')
+      state.save_to_local
+      expect(state.current_level).to eq(1)
+    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/extinction'
+
+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,64 @@
+--- !ruby/object:Gem::Specification
+name: lex-extinction
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Esity
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Escalation and extinction protocol (4 levels) for brain-modeled agentic
+  AI
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- lex-extinction.gemspec
+- lib/legion/extensions/extinction.rb
+- lib/legion/extensions/extinction/actors/protocol_monitor.rb
+- lib/legion/extensions/extinction/client.rb
+- lib/legion/extensions/extinction/helpers/levels.rb
+- lib/legion/extensions/extinction/helpers/protocol_state.rb
+- lib/legion/extensions/extinction/local_migrations/20260316000040_create_extinction_state.rb
+- lib/legion/extensions/extinction/runners/extinction.rb
+- lib/legion/extensions/extinction/version.rb
+- spec/legion/extensions/extinction/actors/protocol_monitor_spec.rb
+- spec/legion/extensions/extinction/client_spec.rb
+- spec/legion/extensions/extinction/helpers/levels_spec.rb
+- spec/legion/extensions/extinction/helpers/protocol_state_spec.rb
+- spec/legion/extensions/extinction/runners/extinction_spec.rb
+- spec/local_persistence_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-extinction
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-extinction
+  source_code_uri: https://github.com/LegionIO/lex-extinction
+  documentation_uri: https://github.com/LegionIO/lex-extinction
+  changelog_uri: https://github.com/LegionIO/lex-extinction
+  bug_tracker_uri: https://github.com/LegionIO/lex-extinction/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 Extinction
+test_files: []