lex-extinction 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '09d900581a92a527c43ffce88cf96c499f8aae44a4c12cf00adedd47a079dd38'
+  data.tar.gz: 6f5ac264ef4ae83879bec5f515dedebf0662a79eb551804e96669263446e3314
+SHA512:
+  metadata.gz: 70b94eeb7b31f41f9cb721d45229efc17c89e91b25eb8068e4ae3a1de3b316b9f902309d3b2c9188edc51e1d99c39bcbebcf1463909b24a1e5941ea632a41319
+  data.tar.gz: a59842aade6c008b7e33927988732045e6e45660be85b2541db543b5ef7005ff4fbfdee22a638786a00b148f50718600bd114e042b933b1203b263817e4f58d2

data/Gemfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rspec', '~> 3.13'
+gem 'rubocop', '~> 1.75', require: false
+gem 'sequel', '>= 5.70'
+gem 'sqlite3', '>= 2.0'

data/lex-extinction.gemspec

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/extinction/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-extinction'
+  spec.version       = Legion::Extensions::Extinction::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Extinction'
+  spec.description   = 'Escalation and extinction protocol (4 levels) for brain-modeled agentic AI'
+  spec.homepage      = 'https://github.com/LegionIO/lex-extinction'
+  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-extinction'
+  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-extinction'
+  spec.metadata['changelog_uri'] = 'https://github.com/LegionIO/lex-extinction'
+  spec.metadata['bug_tracker_uri'] = 'https://github.com/LegionIO/lex-extinction/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-extinction.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+end

data/lib/legion/extensions/extinction/actors/protocol_monitor.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module Extinction
+      module Actor
+        class ProtocolMonitor < Legion::Extensions::Actors::Every
+          def runner_class
+            Legion::Extensions::Extinction::Runners::Extinction
+          end
+
+          def runner_function
+            'monitor_protocol'
+          end
+
+          def time
+            300
+          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/extinction/client.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/extinction/helpers/levels'
+require 'legion/extensions/extinction/helpers/protocol_state'
+require 'legion/extensions/extinction/runners/extinction'
+
+module Legion
+  module Extensions
+    module Extinction
+      class Client
+        include Runners::Extinction
+
+        def initialize(**)
+          @protocol_state = Helpers::ProtocolState.new
+        end
+
+        private
+
+        attr_reader :protocol_state
+      end
+    end
+  end
+end

data/lib/legion/extensions/extinction/helpers/levels.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Extinction
+      module Helpers
+        module Levels
+          # Four escalation levels (spec: extinction-protocol-spec.md)
+          ESCALATION_LEVELS = {
+            1 => { name: :mesh_isolation,       reversible: true,  authority: :governance_council },
+            2 => { name: :forced_sentinel,      reversible: true,  authority: :governance_council },
+            3 => { name: :full_suspension,       reversible: true,  authority: :council_plus_executive },
+            4 => { name: :cryptographic_erasure, reversible: false, authority: :physical_keyholders }
+          }.freeze
+
+          VALID_LEVELS = [1, 2, 3, 4].freeze
+
+          module_function
+
+          def valid_level?(level)
+            VALID_LEVELS.include?(level)
+          end
+
+          def level_info(level)
+            ESCALATION_LEVELS[level]
+          end
+
+          def reversible?(level)
+            ESCALATION_LEVELS.dig(level, :reversible) || false
+          end
+
+          def required_authority(level)
+            ESCALATION_LEVELS.dig(level, :authority)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/extinction/helpers/protocol_state.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Legion
+  module Extensions
+    module Extinction
+      module Helpers
+        class ProtocolState
+          MAX_HISTORY = 500
+
+          attr_reader :current_level, :history, :active
+
+          def initialize
+            @current_level = 0 # 0 = normal operation
+            @active = false
+            @history = []
+            load_from_local
+          end
+
+          def escalate(level, authority:, reason:)
+            return :invalid_level unless Levels.valid_level?(level)
+            return :already_at_or_above if level <= @current_level
+            return :insufficient_authority unless authority == Levels.required_authority(level)
+
+            @current_level = level
+            @active = true
+            @history << {
+              action: :escalate, level: level, authority: authority,
+              reason: reason, at: Time.now.utc
+            }
+            trim_history
+            save_to_local
+            :escalated
+          end
+
+          def deescalate(target_level, authority:, reason:)
+            return :not_active unless @active
+            return :invalid_target if target_level >= @current_level
+            return :irreversible unless Levels.reversible?(@current_level)
+            return :insufficient_authority unless authority == Levels.required_authority(@current_level)
+
+            @current_level = target_level
+            @active = target_level.positive?
+            @history << {
+              action: :deescalate, level: target_level, authority: authority,
+              reason: reason, at: Time.now.utc
+            }
+            trim_history
+            save_to_local
+            :deescalated
+          end
+
+          def to_h
+            {
+              current_level: @current_level,
+              active:        @active,
+              level_info:    @current_level.positive? ? Levels.level_info(@current_level) : nil,
+              history_size:  @history.size
+            }
+          end
+
+          def save_to_local
+            return unless defined?(Legion::Data::Local) && Legion::Data::Local.connected?
+
+            row = {
+              id:            1,
+              current_level: @current_level,
+              active:        @active,
+              history:       ::JSON.dump(@history.map { |h| h.merge(at: h[:at].to_s) }),
+              updated_at:    Time.now.utc
+            }
+            db = Legion::Data::Local.connection
+            if db[:extinction_state].where(id: 1).any?
+              db[:extinction_state].where(id: 1).update(row.except(:id))
+            else
+              db[:extinction_state].insert(row)
+            end
+          rescue StandardError
+            nil
+          end
+
+          private
+
+          def trim_history
+            @history = @history.last(MAX_HISTORY) if @history.size > MAX_HISTORY
+          end
+
+          def load_from_local
+            return unless defined?(Legion::Data::Local) && Legion::Data::Local.connected?
+
+            row = Legion::Data::Local.connection[:extinction_state].where(id: 1).first
+            return unless row
+
+            db_level = row[:current_level].to_i
+            @current_level = [db_level, @current_level].max
+            @active = [true, 1].include?(row[:active])
+            @history = parse_history(row[:history])
+          rescue StandardError
+            nil
+          end
+
+          def parse_history(raw)
+            return [] if raw.nil? || raw.empty?
+
+            parsed = ::JSON.parse(raw, symbolize_names: true)
+            parsed.map do |h|
+              h.merge(
+                action:    h[:action].to_sym,
+                authority: h[:authority].to_sym,
+                at:        Time.parse(h[:at].to_s)
+              )
+            end
+          rescue StandardError
+            []
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/extinction/local_migrations/20260316000040_create_extinction_state.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+Sequel.migration do
+  change do
+    create_table(:extinction_state) do
+      primary_key :id
+      Integer :current_level, null: false, default: 0
+      TrueClass :active, null: false, default: false
+      String :history, text: true
+      DateTime :updated_at
+    end
+  end
+end

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

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Extinction
+      module Runners
+        module Extinction
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def escalate(level:, authority:, reason:, **)
+            result = protocol_state.escalate(level, authority: authority, reason: reason)
+            case result
+            when :escalated
+              info = Helpers::Levels.level_info(level)
+              Legion::Logging.warn "[extinction] ESCALATED: level=#{level} name=#{info[:name]} authority=#{authority} reason=#{reason}"
+              enforce_escalation_effects(level)
+              emit_escalation_event(level, authority, reason)
+              { escalated: true, level: level, info: info }
+            else
+              Legion::Logging.debug "[extinction] escalation denied: level=#{level} reason=#{result}"
+              { escalated: false, reason: result }
+            end
+          end
+
+          def deescalate(authority:, reason:, target_level: 0, **)
+            result = protocol_state.deescalate(target_level, authority: authority, reason: reason)
+            case result
+            when :deescalated
+              Legion::Logging.info "[extinction] de-escalated: target=#{target_level} authority=#{authority} reason=#{reason}"
+              { deescalated: true, level: target_level }
+            else
+              Legion::Logging.debug "[extinction] de-escalation denied: target=#{target_level} reason=#{result}"
+              { deescalated: false, reason: result }
+            end
+          end
+
+          def extinction_status(**)
+            status = protocol_state.to_h
+            Legion::Logging.debug "[extinction] status: level=#{status[:current_level]} active=#{status[:active]}"
+            status
+          end
+
+          def monitor_protocol(**)
+            status = protocol_state.to_h
+            level = status[:current_level]
+
+            if level.positive?
+              Legion::Logging.warn "[extinction] ACTIVE: level=#{level} active=#{status[:active]}"
+              detect_stale_escalation(level)
+            else
+              Legion::Logging.debug '[extinction] status: level=0 active=false'
+            end
+
+            status
+          end
+
+          def check_reversibility(level:, **)
+            reversible = Helpers::Levels.reversible?(level)
+            Legion::Logging.debug "[extinction] reversibility: level=#{level} reversible=#{reversible}"
+            {
+              level:      level,
+              reversible: reversible,
+              authority:  Helpers::Levels.required_authority(level)
+            }
+          end
+
+          STALE_ESCALATION_THRESHOLD = 86_400
+
+          private
+
+          def enforce_escalation_effects(level)
+            if level >= 1 && defined?(Legion::Extensions::Mesh::Runners::Mesh)
+              Legion::Extensions::Mesh::Runners::Mesh.disconnect rescue nil # rubocop:disable Style/RescueModifier
+              Legion::Logging.warn '[extinction] mesh isolation enforced'
+            end
+
+            return unless level == 4
+
+            if defined?(Legion::Extensions::Privatecore::Runners::Privatecore)
+              Legion::Extensions::Privatecore::Runners::Privatecore.erase_all rescue nil # rubocop:disable Style/RescueModifier
+              Legion::Logging.warn '[extinction] cryptographic erasure triggered'
+            end
+
+            return unless defined?(Legion::Data::Model::DigitalWorker)
+
+            begin
+              Legion::Data::Model::DigitalWorker.where(lifecycle_state: 'active').update(
+                lifecycle_state: 'terminated', updated_at: Time.now.utc
+              )
+            rescue StandardError
+              nil
+            end
+            Legion::Logging.warn '[extinction] all active workers terminated'
+          end
+
+          def emit_escalation_event(level, authority, reason)
+            return unless defined?(Legion::Events)
+
+            info = Helpers::Levels.level_info(level)
+            Legion::Events.emit("extinction.#{info[:name]}", {
+                                  level: level, authority: authority, reason: reason, at: Time.now.utc
+                                })
+          end
+
+          def detect_stale_escalation(level)
+            last_escalation = protocol_state.history.select { |h| h[:action] == :escalate }.last
+            return unless last_escalation && (Time.now.utc - last_escalation[:at]) > STALE_ESCALATION_THRESHOLD
+
+            Legion::Logging.warn "[extinction] STALE: level=#{level} has been active > 24 hours"
+            return unless defined?(Legion::Events)
+
+            Legion::Events.emit('extinction.stale_escalation', {
+                                  level: level, since: last_escalation[:at],
+                                  hours: ((Time.now.utc - last_escalation[:at]) / 3600).round(1)
+                                })
+          end
+
+          def protocol_state
+            @protocol_state ||= Helpers::ProtocolState.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/extinction.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/extinction/version'
+require 'legion/extensions/extinction/helpers/levels'
+require 'legion/extensions/extinction/helpers/protocol_state'
+require 'legion/extensions/extinction/runners/extinction'
+
+module Legion
+  module Extensions
+    module Extinction
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end
+
+if defined?(Legion::Data::Local)
+  Legion::Data::Local.register_migrations(
+    name: :extinction,
+    path: File.join(__dir__, 'extinction', 'local_migrations')
+  )
+end

data/spec/legion/extensions/extinction/actors/protocol_monitor_spec.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Actors
+      class Every; end # rubocop:disable Lint/EmptyClass
+    end
+  end
+end
+
+$LOADED_FEATURES << 'legion/extensions/actors/every'
+
+require_relative '../../../../../lib/legion/extensions/extinction/actors/protocol_monitor'
+
+RSpec.describe Legion::Extensions::Extinction::Actor::ProtocolMonitor do
+  subject(:actor) { described_class.new }
+
+  describe '#runner_class' do
+    it { expect(actor.runner_class).to eq Legion::Extensions::Extinction::Runners::Extinction }
+  end
+
+  describe '#runner_function' do
+    it { expect(actor.runner_function).to eq 'monitor_protocol' }
+  end
+
+  describe '#time' do
+    it { expect(actor.time).to eq 300 }
+  end
+
+  describe '#run_now?' do
+    it { expect(actor.run_now?).to be false }
+  end
+
+  describe '#use_runner?' do
+    it { expect(actor.use_runner?).to be false }
+  end
+
+  describe '#check_subtask?' do
+    it { expect(actor.check_subtask?).to be false }
+  end
+
+  describe '#generate_task?' do
+    it { expect(actor.generate_task?).to be false }
+  end
+end

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/extinction/client'
+
+RSpec.describe Legion::Extensions::Extinction::Client do
+  it 'responds to extinction runner methods' do
+    client = described_class.new
+    expect(client).to respond_to(:escalate)
+    expect(client).to respond_to(:deescalate)
+    expect(client).to respond_to(:extinction_status)
+    expect(client).to respond_to(:check_reversibility)
+  end
+end

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

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/extinction/helpers/levels'
+
+RSpec.describe Legion::Extensions::Extinction::Helpers::Levels do
+  describe 'ESCALATION_LEVELS' do
+    it 'defines exactly four levels' do
+      expect(described_class::ESCALATION_LEVELS.size).to eq(4)
+    end
+
+    it 'is keyed by integers 1 through 4' do
+      expect(described_class::ESCALATION_LEVELS.keys).to eq([1, 2, 3, 4])
+    end
+
+    it 'is frozen' do
+      expect(described_class::ESCALATION_LEVELS).to be_frozen
+    end
+
+    it 'defines level 1 as mesh_isolation' do
+      expect(described_class::ESCALATION_LEVELS[1][:name]).to eq(:mesh_isolation)
+    end
+
+    it 'defines level 2 as forced_sentinel' do
+      expect(described_class::ESCALATION_LEVELS[2][:name]).to eq(:forced_sentinel)
+    end
+
+    it 'defines level 3 as full_suspension' do
+      expect(described_class::ESCALATION_LEVELS[3][:name]).to eq(:full_suspension)
+    end
+
+    it 'defines level 4 as cryptographic_erasure' do
+      expect(described_class::ESCALATION_LEVELS[4][:name]).to eq(:cryptographic_erasure)
+    end
+
+    it 'marks levels 1-3 as reversible' do
+      [1, 2, 3].each do |level|
+        expect(described_class::ESCALATION_LEVELS[level][:reversible]).to be true
+      end
+    end
+
+    it 'marks level 4 as not reversible' do
+      expect(described_class::ESCALATION_LEVELS[4][:reversible]).to be false
+    end
+
+    it 'assigns governance_council authority to levels 1 and 2' do
+      expect(described_class::ESCALATION_LEVELS[1][:authority]).to eq(:governance_council)
+      expect(described_class::ESCALATION_LEVELS[2][:authority]).to eq(:governance_council)
+    end
+
+    it 'assigns council_plus_executive authority to level 3' do
+      expect(described_class::ESCALATION_LEVELS[3][:authority]).to eq(:council_plus_executive)
+    end
+
+    it 'assigns physical_keyholders authority to level 4' do
+      expect(described_class::ESCALATION_LEVELS[4][:authority]).to eq(:physical_keyholders)
+    end
+  end
+
+  describe 'VALID_LEVELS' do
+    it 'contains exactly [1, 2, 3, 4]' do
+      expect(described_class::VALID_LEVELS).to eq([1, 2, 3, 4])
+    end
+
+    it 'is frozen' do
+      expect(described_class::VALID_LEVELS).to be_frozen
+    end
+  end
+
+  describe '.valid_level?' do
+    it 'returns true for level 1' do
+      expect(described_class.valid_level?(1)).to be true
+    end
+
+    it 'returns true for level 2' do
+      expect(described_class.valid_level?(2)).to be true
+    end
+
+    it 'returns true for level 3' do
+      expect(described_class.valid_level?(3)).to be true
+    end
+
+    it 'returns true for level 4' do
+      expect(described_class.valid_level?(4)).to be true
+    end
+
+    it 'returns false for level 0' do
+      expect(described_class.valid_level?(0)).to be false
+    end
+
+    it 'returns false for level 5' do
+      expect(described_class.valid_level?(5)).to be false
+    end
+
+    it 'returns false for negative levels' do
+      expect(described_class.valid_level?(-1)).to be false
+    end
+
+    it 'returns false for nil' do
+      expect(described_class.valid_level?(nil)).to be false
+    end
+
+    it 'returns false for string level' do
+      expect(described_class.valid_level?('1')).to be false
+    end
+  end
+
+  describe '.level_info' do
+    it 'returns the full info hash for a valid level' do
+      info = described_class.level_info(1)
+      expect(info).to be_a(Hash)
+      expect(info.keys).to contain_exactly(:name, :reversible, :authority)
+    end
+
+    it 'returns nil for an invalid level' do
+      expect(described_class.level_info(99)).to be_nil
+    end
+
+    it 'returns nil for level 0' do
+      expect(described_class.level_info(0)).to be_nil
+    end
+
+    [1, 2, 3, 4].each do |level|
+      it "returns a hash for level #{level}" do
+        expect(described_class.level_info(level)).to be_a(Hash)
+      end
+    end
+  end
+
+  describe '.reversible?' do
+    it 'returns true for level 1' do
+      expect(described_class.reversible?(1)).to be true
+    end
+
+    it 'returns true for level 2' do
+      expect(described_class.reversible?(2)).to be true
+    end
+
+    it 'returns true for level 3' do
+      expect(described_class.reversible?(3)).to be true
+    end
+
+    it 'returns false for level 4' do
+      expect(described_class.reversible?(4)).to be false
+    end
+
+    it 'returns false for an invalid level (fallback to false)' do
+      expect(described_class.reversible?(99)).to be false
+    end
+
+    it 'returns false for nil level' do
+      expect(described_class.reversible?(nil)).to be false
+    end
+  end
+
+  describe '.required_authority' do
+    it 'returns :governance_council for level 1' do
+      expect(described_class.required_authority(1)).to eq(:governance_council)
+    end
+
+    it 'returns :governance_council for level 2' do
+      expect(described_class.required_authority(2)).to eq(:governance_council)
+    end
+
+    it 'returns :council_plus_executive for level 3' do
+      expect(described_class.required_authority(3)).to eq(:council_plus_executive)
+    end
+
+    it 'returns :physical_keyholders for level 4' do
+      expect(described_class.required_authority(4)).to eq(:physical_keyholders)
+    end
+
+    it 'returns nil for an invalid level' do
+      expect(described_class.required_authority(0)).to be_nil
+    end
+
+    it 'returns nil for an out-of-range level' do
+      expect(described_class.required_authority(5)).to be_nil
+    end
+  end
+end