lex-consent 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8cf5e07bea7eb65742f83c8a32000eb93f0d90b2b35334f7d656ddd71d52824c
+  data.tar.gz: c23df3ed550f404a1dbfa6a811bff1bf96ac5bf09567d81ac9c9f161a20fbc8a
+SHA512:
+  metadata.gz: 8448d8366e74202edf6755d830e09e729cc038f32394fe88046f552802a4628b9f53323c98af2b5fbd8739522500293efd720c0090cd0939d25ab0e57273f09b
+  data.tar.gz: 46da76635d0c2c55d4a62a80ec28dd417bac195f0ec9cd44603a6accf193c7f2966f469097537ee1b77955483190367562da123ff93990dd23b17efedc9edd00

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 'sequel', '>= 5.70'
+gem 'sqlite3', '>= 2.0'

data/lex-consent.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/consent/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-consent'
+  spec.version       = Legion::Extensions::Consent::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Consent'
+  spec.description   = 'Four-tier consent gradient with earned autonomy for brain-modeled agentic AI'
+  spec.homepage      = 'https://github.com/LegionIO/lex-consent'
+  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-consent'
+  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-consent'
+  spec.metadata['changelog_uri'] = 'https://github.com/LegionIO/lex-consent'
+  spec.metadata['bug_tracker_uri'] = 'https://github.com/LegionIO/lex-consent/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-consent.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'sequel', '>= 5.70'
+  spec.add_development_dependency 'sqlite3', '>= 2.0'
+end

data/lib/legion/extensions/consent/actors/tier_evaluation.rb

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/consent/helpers/tiers'
+require 'legion/extensions/consent/helpers/consent_map'
+require 'legion/extensions/consent/runners/consent'
+
+module Legion
+  module Extensions
+    module Consent
+      class Client
+        include Runners::Consent
+
+        def initialize(**)
+          @consent_map = Helpers::ConsentMap.new
+        end
+
+        private
+
+        attr_reader :consent_map
+      end
+    end
+  end
+end

data/lib/legion/extensions/consent/helpers/consent_map.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Legion
+  module Extensions
+    module Consent
+      module Helpers
+        class ConsentMap
+          APPROVAL_TIMEOUT = 259_200 # 72 hours
+
+          attr_reader :domains
+
+          def initialize
+            @domains = Hash.new do |h, k|
+              h[k] = {
+                tier:                 Tiers::DEFAULT_TIER,
+                success_count:        0,
+                failure_count:        0,
+                total_actions:        0,
+                last_changed_at:      nil,
+                history:              [],
+                pending_tier:         nil,
+                pending_since:        nil,
+                pending_requested_by: nil
+              }
+            end
+            load_from_local
+          end
+
+          def get_tier(domain)
+            @domains[domain][:tier]
+          end
+
+          def set_tier(domain, tier)
+            return unless Tiers.valid_tier?(tier)
+
+            entry = @domains[domain]
+            old_tier = entry[:tier]
+            entry[:tier] = tier
+            entry[:last_changed_at] = Time.now.utc
+            entry[:history] << { from: old_tier, to: tier, at: Time.now.utc }
+            entry[:history].shift while entry[:history].size > 50
+          end
+
+          def record_outcome(domain, success:)
+            entry = @domains[domain]
+            entry[:total_actions] += 1
+            if success
+              entry[:success_count] += 1
+            else
+              entry[:failure_count] += 1
+            end
+          end
+
+          def success_rate(domain)
+            entry = @domains[domain]
+            return 0.0 if entry[:total_actions].zero?
+
+            entry[:success_count].to_f / entry[:total_actions]
+          end
+
+          def eligible_for_change?(domain)
+            entry = @domains[domain]
+            return false if entry[:total_actions] < Tiers::MIN_ACTIONS_TO_PROMOTE
+
+            if entry[:last_changed_at]
+              (Time.now.utc - entry[:last_changed_at]) >= Tiers::PROMOTION_COOLDOWN
+            else
+              true
+            end
+          end
+
+          def evaluate_promotion(domain)
+            return :ineligible unless eligible_for_change?(domain)
+
+            rate = success_rate(domain)
+            current = get_tier(domain)
+
+            if rate >= Tiers::PROMOTION_THRESHOLD
+              promoted = Tiers.promote(current)
+              return :already_max if promoted == current
+
+              :promote
+            elsif rate < Tiers::DEMOTION_THRESHOLD
+              demoted = Tiers.demote(current)
+              return :already_min if demoted == current
+
+              :demote
+            else
+              :maintain
+            end
+          end
+
+          def domain_count
+            @domains.size
+          end
+
+          def to_h
+            @domains.transform_values do |v|
+              { tier: v[:tier], success_rate: success_rate_from(v), total_actions: v[:total_actions],
+                pending_tier: v[:pending_tier], pending_since: v[:pending_since] }
+            end
+          end
+
+          def set_pending(domain, proposed_tier:, requested_by: 'system')
+            entry = @domains[domain]
+            entry[:pending_tier] = proposed_tier
+            entry[:pending_since] = Time.now
+            entry[:pending_requested_by] = requested_by
+            entry
+          end
+
+          def clear_pending(domain)
+            entry = @domains[domain]
+            entry[:pending_tier] = nil
+            entry[:pending_since] = nil
+            entry[:pending_requested_by] = nil
+            entry
+          end
+
+          def pending?(domain)
+            !@domains[domain][:pending_tier].nil?
+          end
+
+          def pending_expired?(domain, timeout: APPROVAL_TIMEOUT)
+            entry = @domains[domain]
+            return false unless entry[:pending_since]
+
+            Time.now - entry[:pending_since] > timeout
+          end
+
+          def save_to_local
+            return unless defined?(Legion::Data::Local) && Legion::Data::Local.connected?
+
+            dataset = Legion::Data::Local.connection[:consent_domains]
+            @domains.each do |domain_key, entry|
+              row = {
+                domain_key:      domain_key,
+                tier:            entry[:tier].to_s,
+                success_count:   entry[:success_count],
+                failure_count:   entry[:failure_count],
+                total_actions:   entry[:total_actions],
+                last_changed_at: entry[:last_changed_at],
+                history:         ::JSON.generate(entry[:history].map { |h| h.transform_values(&:to_s) })
+              }
+              existing = dataset.where(domain_key: domain_key).first
+              if existing
+                dataset.where(domain_key: domain_key).update(row.except(:domain_key))
+              else
+                dataset.insert(row)
+              end
+            end
+          rescue StandardError => e
+            Legion::Logging.warn "[consent] save_to_local failed: #{e.message}" if defined?(Legion::Logging)
+          end
+
+          def load_from_local
+            return unless defined?(Legion::Data::Local) && Legion::Data::Local.connected?
+
+            Legion::Data::Local.connection[:consent_domains].each do |row|
+              key = row[:domain_key]
+              history = begin
+                ::JSON.parse(row[:history] || '[]', symbolize_names: false).map do |h|
+                  { from: h['from'].to_sym, to: h['to'].to_sym, at: h['at'] }
+                end
+              rescue StandardError
+                []
+              end
+
+              @domains[key] = {
+                tier:            row[:tier].to_sym,
+                success_count:   row[:success_count].to_i,
+                failure_count:   row[:failure_count].to_i,
+                total_actions:   row[:total_actions].to_i,
+                last_changed_at: row[:last_changed_at],
+                history:         history
+              }
+            end
+          rescue StandardError => e
+            Legion::Logging.warn "[consent] load_from_local failed: #{e.message}" if defined?(Legion::Logging)
+          end
+
+          private
+
+          def success_rate_from(entry)
+            return 0.0 if entry[:total_actions].zero?
+
+            entry[:success_count].to_f / entry[:total_actions]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/consent/helpers/tiers.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Consent
+      module Helpers
+        module Tiers
+          # Four consent tiers (spec: consent-gradient-spec.md)
+          TIERS = %i[autonomous act_notify consult human_only].freeze
+
+          # Default starting tier for new domains
+          DEFAULT_TIER = :consult
+
+          # Thresholds for tier promotion/demotion
+          PROMOTION_THRESHOLD   = 0.8  # success rate needed to promote
+          DEMOTION_THRESHOLD    = 0.5  # success rate below which demotion occurs
+          MIN_ACTIONS_TO_PROMOTE = 10  # minimum actions before tier change
+          PROMOTION_COOLDOWN = 86_400 # seconds between tier changes (24h)
+
+          # Tier ordering (lower index = more autonomy)
+          TIER_ORDER = { autonomous: 0, act_notify: 1, consult: 2, human_only: 3 }.freeze
+
+          module_function
+
+          def valid_tier?(tier)
+            TIERS.include?(tier)
+          end
+
+          def more_autonomous?(tier_a, tier_b)
+            TIER_ORDER.fetch(tier_a, 99) < TIER_ORDER.fetch(tier_b, 99)
+          end
+
+          def promote(current_tier)
+            idx = TIER_ORDER.fetch(current_tier, 2)
+            return current_tier if idx.zero?
+
+            TIER_ORDER.key(idx - 1) || current_tier
+          end
+
+          def demote(current_tier)
+            idx = TIER_ORDER.fetch(current_tier, 2)
+            return current_tier if idx >= 3
+
+            TIER_ORDER.key(idx + 1) || current_tier
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/consent/local_migrations/20260316000010_create_consent_domains.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+Sequel.migration do
+  change do
+    create_table(:consent_domains) do
+      primary_key :id
+      String :domain_key, null: false, unique: true, index: true
+      String :tier, null: false, default: 'consult'
+      Integer :success_count, default: 0
+      Integer :failure_count, default: 0
+      Integer :total_actions, default: 0
+      DateTime :last_changed_at
+      String :history, text: true
+    end
+  end
+end

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

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Consent
+      module Runners
+        module Consent
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def check_consent(domain:, _action_type: :general, **)
+            tier = consent_map.get_tier(domain)
+            Legion::Logging.debug "[consent] check: domain=#{domain} tier=#{tier} allowed=#{tier == :autonomous}"
+
+            {
+              domain:        domain,
+              tier:          tier,
+              allowed:       tier == :autonomous,
+              needs_notify:  tier == :act_notify,
+              needs_consult: tier == :consult,
+              human_only:    tier == :human_only
+            }
+          end
+
+          def record_action(domain:, success:, **)
+            consent_map.record_outcome(domain, success: success)
+            rate = consent_map.success_rate(domain)
+            total = consent_map.domains[domain][:total_actions]
+            Legion::Logging.info "[consent] action recorded: domain=#{domain} success=#{success} rate=#{rate.round(2)} total=#{total}"
+
+            {
+              domain:       domain,
+              success:      success,
+              success_rate: rate,
+              total:        total
+            }
+          end
+
+          def evaluate_tier_change(domain:, **)
+            recommendation = consent_map.evaluate_promotion(domain)
+            current = consent_map.get_tier(domain)
+
+            result = {
+              domain:         domain,
+              current_tier:   current,
+              recommendation: recommendation,
+              success_rate:   consent_map.success_rate(domain)
+            }
+
+            case recommendation
+            when :promote
+              result[:proposed_tier] = Helpers::Tiers.promote(current)
+              Legion::Logging.info "[consent] tier change: domain=#{domain} recommend=promote from=#{current} to=#{result[:proposed_tier]}"
+            when :demote
+              result[:proposed_tier] = Helpers::Tiers.demote(current)
+              Legion::Logging.warn "[consent] tier change: domain=#{domain} recommend=demote from=#{current} to=#{result[:proposed_tier]}"
+            else
+              Legion::Logging.debug "[consent] tier eval: domain=#{domain} current=#{current} recommendation=#{recommendation}"
+            end
+
+            result
+          end
+
+          def apply_tier_change(domain:, new_tier:, **)
+            return { error: :invalid_tier, valid_tiers: Helpers::Tiers::TIERS } unless Helpers::Tiers.valid_tier?(new_tier)
+
+            old_tier = consent_map.get_tier(domain)
+            consent_map.set_tier(domain, new_tier)
+            changed = old_tier != new_tier
+            Legion::Logging.info "[consent] tier applied: domain=#{domain} old=#{old_tier} new=#{new_tier} changed=#{changed}"
+            { domain: domain, old_tier: old_tier, new_tier: new_tier, changed: changed }
+          end
+
+          def evaluate_all_tiers(**)
+            promotions = []
+            demotions = []
+
+            consent_map.domains.each_key do |domain|
+              result = consent_map.evaluate_promotion(domain)
+              promotions << domain if result == :promote
+              demotions << domain if result == :demote
+            end
+
+            evaluated = consent_map.domain_count
+            Legion::Logging.debug "[consent] tier evaluation sweep: domains=#{evaluated} " \
+                                  "promotions=#{promotions.size} demotions=#{demotions.size}"
+
+            { evaluated: evaluated, promotions: promotions, demotions: demotions }
+          end
+
+          def request_autonomous_approval(domain:, **)
+            map = consent_map
+            current_tier = map.get_tier(domain)
+
+            return { requested: false, error: 'already_autonomous' } if current_tier == :autonomous
+            return { requested: false, error: 'already_pending' } if map.pending?(domain)
+
+            map.set_pending(domain, proposed_tier: :autonomous, requested_by: 'tier_evaluation')
+
+            if defined?(Legion::Events)
+              rate = map.success_rate(domain)
+              total = map.domains[domain][:total_actions]
+              Legion::Events.emit('consent.approval_required', {
+                                    domain:        domain,
+                                    current_tier:  current_tier,
+                                    proposed_tier: :autonomous,
+                                    success_rate:  rate,
+                                    total_actions: total,
+                                    requested_at:  Time.now.utc
+                                  })
+            end
+
+            { requested: true, domain: domain, current_tier: current_tier, proposed_tier: :autonomous }
+          end
+
+          def approve_promotion(domain:, approved_by:, **)
+            map = consent_map
+            return { approved: false, error: 'no_pending_approval' } unless map.pending?(domain)
+
+            pending_tier = map.domains[domain][:pending_tier]
+            old_tier = map.get_tier(domain)
+            map.clear_pending(domain)
+            map.set_tier(domain, pending_tier)
+
+            if defined?(Legion::Events)
+              Legion::Events.emit('consent.promotion_approved', {
+                                    domain: domain, old_tier: old_tier, new_tier: pending_tier,
+                                    approved_by: approved_by, at: Time.now.utc
+                                  })
+            end
+
+            { approved: true, domain: domain, old_tier: old_tier, new_tier: pending_tier, approved_by: approved_by }
+          end
+
+          def reject_promotion(domain:, rejected_by:, reason: nil, **)
+            map = consent_map
+            return { rejected: false, error: 'no_pending_approval' } unless map.pending?(domain)
+
+            map.clear_pending(domain)
+
+            if defined?(Legion::Events)
+              Legion::Events.emit('consent.promotion_rejected', {
+                                    domain: domain, rejected_by: rejected_by, reason: reason, at: Time.now.utc
+                                  })
+            end
+
+            { rejected: true, domain: domain, rejected_by: rejected_by, reason: reason }
+          end
+
+          def expire_pending_approvals(timeout: Helpers::ConsentMap::APPROVAL_TIMEOUT, **)
+            map = consent_map
+            expired = 0
+
+            map.domains.each_key do |domain|
+              next unless map.pending?(domain)
+              next unless map.pending_expired?(domain, timeout: timeout)
+
+              map.clear_pending(domain)
+              expired += 1
+            end
+
+            { expired: expired }
+          end
+
+          def evaluate_and_apply_tiers(**)
+            candidates = evaluate_all_tiers
+            applied_promotions = 0
+            applied_demotions = 0
+            approval_requests = 0
+
+            Array(candidates[:promotions]).each do |domain|
+              current = consent_map.get_tier(domain)
+              proposed = Helpers::Tiers.promote(current)
+
+              if proposed == :autonomous
+                result = request_autonomous_approval(domain: domain)
+                approval_requests += 1 if result[:requested]
+              else
+                apply_tier_change(domain: domain, new_tier: proposed)
+                applied_promotions += 1
+              end
+            end
+
+            Array(candidates[:demotions]).each do |domain|
+              current = consent_map.get_tier(domain)
+              proposed = Helpers::Tiers.demote(current)
+              apply_tier_change(domain: domain, new_tier: proposed)
+              applied_demotions += 1
+            end
+
+            expired = expire_pending_approvals
+
+            { evaluated: candidates[:evaluated], applied_promotions: applied_promotions,
+              applied_demotions: applied_demotions, approval_requests: approval_requests,
+              expired_approvals: expired[:expired] }
+          end
+
+          def consent_status(domain: nil, **)
+            if domain
+              entry = consent_map.domains[domain]
+              Legion::Logging.debug "[consent] status: domain=#{domain} tier=#{entry[:tier]} total=#{entry[:total_actions]}"
+              {
+                domain:       domain,
+                tier:         entry[:tier],
+                success_rate: consent_map.success_rate(domain),
+                total:        entry[:total_actions],
+                eligible:     consent_map.eligible_for_change?(domain)
+              }
+            else
+              Legion::Logging.debug "[consent] status: domains=#{consent_map.domain_count}"
+              { domains: consent_map.to_h, count: consent_map.domain_count }
+            end
+          end
+
+          private
+
+          def consent_map
+            @consent_map ||= Helpers::ConsentMap.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/consent.rb

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

data/spec/legion/extensions/consent/actors/tier_evaluation_spec.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# Stub the base class before loading the actor
+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/consent/actors/tier_evaluation'
+
+RSpec.describe Legion::Extensions::Consent::Actor::TierEvaluation do
+  subject(:actor) { described_class.new }
+
+  describe '#runner_class' do
+    it { expect(actor.runner_class).to eq Legion::Extensions::Consent::Runners::Consent }
+  end
+
+  describe '#runner_function' do
+    it { expect(actor.runner_function).to eq 'evaluate_and_apply_tiers' }
+  end
+
+  describe '#time' do
+    it { expect(actor.time).to eq 3600 }
+  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/consent/client_spec.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/consent/client'
+
+RSpec.describe Legion::Extensions::Consent::Client do
+  let(:client) { described_class.new }
+
+  it 'responds to consent runner methods' do
+    expect(client).to respond_to(:check_consent)
+    expect(client).to respond_to(:record_action)
+    expect(client).to respond_to(:evaluate_tier_change)
+    expect(client).to respond_to(:apply_tier_change)
+    expect(client).to respond_to(:consent_status)
+  end
+
+  it 'round-trips earned autonomy lifecycle' do
+    # Start with consult
+    check = client.check_consent(domain: 'scheduling')
+    expect(check[:tier]).to eq(:consult)
+
+    # Build track record
+    12.times { client.record_action(domain: 'scheduling', success: true) }
+
+    # Evaluate
+    eval_result = client.evaluate_tier_change(domain: 'scheduling')
+    expect(eval_result[:recommendation]).to eq(:promote)
+
+    # Apply
+    client.apply_tier_change(domain: 'scheduling', new_tier: eval_result[:proposed_tier])
+    check = client.check_consent(domain: 'scheduling')
+    expect(check[:tier]).to eq(:act_notify)
+  end
+end

data/spec/legion/extensions/consent/helpers/tiers_spec.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Consent::Helpers::Tiers do
+  describe '.valid_tier?' do
+    it 'accepts valid tiers' do
+      %i[autonomous act_notify consult human_only].each do |tier|
+        expect(described_class.valid_tier?(tier)).to be true
+      end
+    end
+
+    it 'rejects invalid tiers' do
+      expect(described_class.valid_tier?(:invalid)).to be false
+    end
+  end
+
+  describe '.promote' do
+    it 'promotes consult to act_notify' do
+      expect(described_class.promote(:consult)).to eq(:act_notify)
+    end
+
+    it 'promotes act_notify to autonomous' do
+      expect(described_class.promote(:act_notify)).to eq(:autonomous)
+    end
+
+    it 'cannot promote beyond autonomous' do
+      expect(described_class.promote(:autonomous)).to eq(:autonomous)
+    end
+  end
+
+  describe '.demote' do
+    it 'demotes consult to human_only' do
+      expect(described_class.demote(:consult)).to eq(:human_only)
+    end
+
+    it 'cannot demote beyond human_only' do
+      expect(described_class.demote(:human_only)).to eq(:human_only)
+    end
+  end
+
+  describe '.more_autonomous?' do
+    it 'returns true when first tier is more autonomous' do
+      expect(described_class.more_autonomous?(:autonomous, :consult)).to be true
+    end
+
+    it 'returns false when second tier is more autonomous' do
+      expect(described_class.more_autonomous?(:human_only, :consult)).to be false
+    end
+  end
+end

data/spec/legion/extensions/consent/runners/consent_spec.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/consent/client'
+
+RSpec.describe Legion::Extensions::Consent::Runners::Consent do
+  let(:client) { Legion::Extensions::Consent::Client.new }
+
+  describe '#check_consent' do
+    it 'returns default tier for new domain' do
+      result = client.check_consent(domain: 'email')
+      expect(result[:tier]).to eq(:consult)
+      expect(result[:needs_consult]).to be true
+    end
+  end
+
+  describe '#record_action' do
+    it 'records action outcome' do
+      result = client.record_action(domain: 'email', success: true)
+      expect(result[:success]).to be true
+      expect(result[:total]).to eq(1)
+    end
+
+    it 'tracks success rate' do
+      3.times { client.record_action(domain: 'email', success: true) }
+      client.record_action(domain: 'email', success: false)
+      result = client.record_action(domain: 'email', success: true)
+      expect(result[:success_rate]).to eq(0.8)
+    end
+  end
+
+  describe '#evaluate_tier_change' do
+    it 'returns ineligible when not enough actions' do
+      result = client.evaluate_tier_change(domain: 'email')
+      expect(result[:recommendation]).to eq(:ineligible)
+    end
+
+    it 'recommends promotion with high success rate' do
+      15.times { client.record_action(domain: 'calendar', success: true) }
+      result = client.evaluate_tier_change(domain: 'calendar')
+      expect(result[:recommendation]).to eq(:promote)
+      expect(result[:proposed_tier]).to eq(:act_notify)
+    end
+
+    it 'recommends demotion with low success rate' do
+      4.times { client.record_action(domain: 'risky', success: true) }
+      8.times { client.record_action(domain: 'risky', success: false) }
+      result = client.evaluate_tier_change(domain: 'risky')
+      expect(result[:recommendation]).to eq(:demote)
+      expect(result[:proposed_tier]).to eq(:human_only)
+    end
+  end
+
+  describe '#apply_tier_change' do
+    it 'changes tier' do
+      result = client.apply_tier_change(domain: 'email', new_tier: :autonomous)
+      expect(result[:new_tier]).to eq(:autonomous)
+      expect(result[:changed]).to be true
+    end
+
+    it 'rejects invalid tier' do
+      result = client.apply_tier_change(domain: 'email', new_tier: :invalid)
+      expect(result[:error]).to eq(:invalid_tier)
+    end
+  end
+
+  describe '#evaluate_all_tiers' do
+    it 'returns zero evaluated for empty consent map' do
+      result = client.evaluate_all_tiers
+      expect(result[:evaluated]).to eq(0)
+      expect(result[:promotions]).to eq([])
+      expect(result[:demotions]).to eq([])
+    end
+
+    it 'includes promoted domains in promotions list' do
+      15.times { client.record_action(domain: 'calendar', success: true) }
+      result = client.evaluate_all_tiers
+      expect(result[:promotions]).to include('calendar')
+    end
+
+    it 'includes demoted domains in demotions list' do
+      4.times { client.record_action(domain: 'risky', success: true) }
+      8.times { client.record_action(domain: 'risky', success: false) }
+      result = client.evaluate_all_tiers
+      expect(result[:demotions]).to include('risky')
+    end
+
+    it 'returns evaluated count matching number of known domains' do
+      client.record_action(domain: 'email', success: true)
+      client.record_action(domain: 'calendar', success: true)
+      result = client.evaluate_all_tiers
+      expect(result[:evaluated]).to eq(2)
+    end
+
+    it 'does not include ineligible domains in promotions or demotions' do
+      client.record_action(domain: 'email', success: true)
+      result = client.evaluate_all_tiers
+      expect(result[:promotions]).not_to include('email')
+      expect(result[:demotions]).not_to include('email')
+    end
+  end
+
+  describe '#request_autonomous_approval' do
+    it 'sets pending state for non-autonomous domain' do
+      client.record_action(domain: 'email', success: true)
+      result = client.request_autonomous_approval(domain: 'email')
+      expect(result[:requested]).to be true
+      expect(result[:proposed_tier]).to eq(:autonomous)
+    end
+
+    it 'rejects if already autonomous' do
+      client.apply_tier_change(domain: 'email', new_tier: :autonomous)
+      result = client.request_autonomous_approval(domain: 'email')
+      expect(result[:requested]).to be false
+      expect(result[:error]).to eq('already_autonomous')
+    end
+
+    it 'rejects if already pending' do
+      client.request_autonomous_approval(domain: 'email')
+      result = client.request_autonomous_approval(domain: 'email')
+      expect(result[:requested]).to be false
+      expect(result[:error]).to eq('already_pending')
+    end
+  end
+
+  describe '#approve_promotion' do
+    it 'applies pending tier change' do
+      client.request_autonomous_approval(domain: 'email')
+      result = client.approve_promotion(domain: 'email', approved_by: 'admin')
+      expect(result[:approved]).to be true
+      expect(result[:new_tier]).to eq(:autonomous)
+      expect(result[:approved_by]).to eq('admin')
+    end
+
+    it 'rejects when no pending approval' do
+      result = client.approve_promotion(domain: 'email', approved_by: 'admin')
+      expect(result[:approved]).to be false
+      expect(result[:error]).to eq('no_pending_approval')
+    end
+  end
+
+  describe '#reject_promotion' do
+    it 'clears pending state' do
+      client.request_autonomous_approval(domain: 'email')
+      result = client.reject_promotion(domain: 'email', rejected_by: 'admin', reason: 'not ready')
+      expect(result[:rejected]).to be true
+      expect(result[:reason]).to eq('not ready')
+    end
+
+    it 'rejects when no pending approval' do
+      result = client.reject_promotion(domain: 'email', rejected_by: 'admin')
+      expect(result[:rejected]).to be false
+    end
+  end
+
+  describe '#expire_pending_approvals' do
+    it 'expires stale approvals' do
+      client.request_autonomous_approval(domain: 'email')
+      result = client.expire_pending_approvals(timeout: 0)
+      expect(result[:expired]).to eq(1)
+    end
+
+    it 'does not expire fresh approvals' do
+      client.request_autonomous_approval(domain: 'email')
+      result = client.expire_pending_approvals(timeout: 999_999)
+      expect(result[:expired]).to eq(0)
+    end
+  end
+
+  describe '#evaluate_and_apply_tiers' do
+    it 'returns summary with zero counts for empty map' do
+      result = client.evaluate_and_apply_tiers
+      expect(result[:evaluated]).to eq(0)
+      expect(result[:applied_promotions]).to eq(0)
+      expect(result[:applied_demotions]).to eq(0)
+      expect(result[:approval_requests]).to eq(0)
+    end
+
+    it 'auto-applies non-autonomous promotions' do
+      15.times { client.record_action(domain: 'calendar', success: true) }
+      result = client.evaluate_and_apply_tiers
+      expect(result[:applied_promotions]).to eq(1)
+      status = client.consent_status(domain: 'calendar')
+      expect(status[:tier]).to eq(:act_notify)
+    end
+
+    it 'requests approval for autonomous promotions instead of auto-applying' do
+      client.apply_tier_change(domain: 'calendar', new_tier: :act_notify)
+      # Backdate last_changed_at to bypass the 24h cooldown
+      map = client.send(:consent_map)
+      map.domains['calendar'][:last_changed_at] = Time.now.utc - 100_000
+      15.times { client.record_action(domain: 'calendar', success: true) }
+      result = client.evaluate_and_apply_tiers
+      expect(result[:approval_requests]).to eq(1)
+      expect(result[:applied_promotions]).to eq(0)
+      status = client.consent_status(domain: 'calendar')
+      expect(status[:tier]).to eq(:act_notify)
+    end
+
+    it 'auto-applies demotions' do
+      4.times { client.record_action(domain: 'risky', success: true) }
+      8.times { client.record_action(domain: 'risky', success: false) }
+      result = client.evaluate_and_apply_tiers
+      expect(result[:applied_demotions]).to eq(1)
+      status = client.consent_status(domain: 'risky')
+      expect(status[:tier]).to eq(:human_only)
+    end
+  end
+
+  describe '#consent_status' do
+    it 'returns domain-specific status' do
+      client.record_action(domain: 'email', success: true)
+      result = client.consent_status(domain: 'email')
+      expect(result[:tier]).to eq(:consult)
+      expect(result[:total]).to eq(1)
+    end
+
+    it 'returns all domains when no domain specified' do
+      client.record_action(domain: 'email', success: true)
+      client.record_action(domain: 'calendar', success: true)
+      result = client.consent_status
+      expect(result[:count]).to eq(2)
+    end
+  end
+end

data/spec/local_persistence_spec.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'sequel'
+require 'json'
+require 'tmpdir'
+
+RSpec.describe 'lex-consent local SQLite persistence' do
+  let(:db_path) { File.join(Dir.tmpdir, "consent_test_#{Process.pid}_#{rand(9999)}.db") }
+  let(:db) { Sequel.sqlite(db_path) }
+
+  before do
+    # Create the schema in the temp DB
+    db.create_table(:consent_domains) do
+      primary_key :id
+      String :domain_key, null: false, unique: true
+      String :tier, null: false, default: 'consult'
+      Integer :success_count, default: 0
+      Integer :failure_count, default: 0
+      Integer :total_actions, default: 0
+      DateTime :last_changed_at
+      String :history, text: true
+    end
+
+    # Stub Legion::Data::Local to use our temp DB
+    stub_const('Legion::Data::Local', Module.new do
+      def self.connected?
+        true
+      end
+
+      def self.connection
+        @_connection
+      end
+
+      def self._set_connection(conn)
+        @_connection = conn
+      end
+    end)
+
+    Legion::Data::Local._set_connection(db)
+  end
+
+  after do
+    db.disconnect
+    FileUtils.rm_f(db_path)
+  end
+
+  describe 'save_to_local' do
+    it 'writes domain state to the database' do
+      map = Legion::Extensions::Consent::Helpers::ConsentMap.new
+      map.record_outcome('email', success: true)
+      map.record_outcome('email', success: true)
+      map.save_to_local
+
+      row = db[:consent_domains].where(domain_key: 'email').first
+      expect(row).not_to be_nil
+      expect(row[:domain_key]).to eq('email')
+      expect(row[:tier]).to eq('consult')
+      expect(row[:success_count]).to eq(2)
+      expect(row[:total_actions]).to eq(2)
+    end
+
+    it 'updates an existing row on second save' do
+      map = Legion::Extensions::Consent::Helpers::ConsentMap.new
+      map.record_outcome('email', success: true)
+      map.save_to_local
+
+      map.record_outcome('email', success: false)
+      map.save_to_local
+
+      rows = db[:consent_domains].where(domain_key: 'email').all
+      expect(rows.size).to eq(1)
+      expect(rows.first[:failure_count]).to eq(1)
+      expect(rows.first[:total_actions]).to eq(2)
+    end
+
+    it 'serializes tier as a string' do
+      map = Legion::Extensions::Consent::Helpers::ConsentMap.new
+      map.set_tier('scheduling', :autonomous)
+      map.save_to_local
+
+      row = db[:consent_domains].where(domain_key: 'scheduling').first
+      expect(row[:tier]).to eq('autonomous')
+    end
+
+    it 'serializes history as JSON' do
+      map = Legion::Extensions::Consent::Helpers::ConsentMap.new
+      map.set_tier('scheduling', :autonomous)
+      map.save_to_local
+
+      row = db[:consent_domains].where(domain_key: 'scheduling').first
+      parsed = JSON.parse(row[:history])
+      expect(parsed).to be_an(Array)
+      expect(parsed.first['from']).to eq('consult')
+      expect(parsed.first['to']).to eq('autonomous')
+    end
+
+    it 'persists multiple domains' do
+      map = Legion::Extensions::Consent::Helpers::ConsentMap.new
+      map.record_outcome('email', success: true)
+      map.record_outcome('calendar', success: false)
+      map.save_to_local
+
+      expect(db[:consent_domains].count).to eq(2)
+    end
+  end
+
+  describe 'load_from_local' do
+    it 'restores domain state from the database' do
+      db[:consent_domains].insert(
+        domain_key:    'email',
+        tier:          'act_notify',
+        success_count: 5,
+        failure_count: 1,
+        total_actions: 6,
+        history:       '[]'
+      )
+
+      map = Legion::Extensions::Consent::Helpers::ConsentMap.new
+      expect(map.get_tier('email')).to eq(:act_notify)
+      expect(map.domains['email'][:success_count]).to eq(5)
+      expect(map.domains['email'][:total_actions]).to eq(6)
+    end
+
+    it 'restores history as an array of hashes with symbol keys' do
+      history_json = JSON.generate([{ 'from' => 'consult', 'to' => 'act_notify', 'at' => Time.now.utc.to_s }])
+      db[:consent_domains].insert(
+        domain_key:    'scheduling',
+        tier:          'act_notify',
+        success_count: 10,
+        failure_count: 0,
+        total_actions: 10,
+        history:       history_json
+      )
+
+      map = Legion::Extensions::Consent::Helpers::ConsentMap.new
+      history = map.domains['scheduling'][:history]
+      expect(history).to be_an(Array)
+      expect(history.first[:from]).to eq(:consult)
+      expect(history.first[:to]).to eq(:act_notify)
+    end
+
+    it 'handles empty history JSON gracefully' do
+      db[:consent_domains].insert(
+        domain_key:    'empty_history',
+        tier:          'consult',
+        success_count: 0,
+        failure_count: 0,
+        total_actions: 0,
+        history:       '[]'
+      )
+
+      map = Legion::Extensions::Consent::Helpers::ConsentMap.new
+      expect(map.domains['empty_history'][:history]).to eq([])
+    end
+  end
+
+  describe 'round-trip persistence' do
+    it 'saves and restores earned tier' do
+      # First instance: build history and promote
+      map1 = Legion::Extensions::Consent::Helpers::ConsentMap.new
+      15.times { map1.record_outcome('tasks', success: true) }
+      map1.set_tier('tasks', :act_notify)
+      map1.save_to_local
+
+      # Second instance: loads from DB
+      map2 = Legion::Extensions::Consent::Helpers::ConsentMap.new
+      expect(map2.get_tier('tasks')).to eq(:act_notify)
+      expect(map2.domains['tasks'][:success_count]).to eq(15)
+      expect(map2.domains['tasks'][:total_actions]).to eq(15)
+    end
+
+    it 'round-trips multiple domains independently' do
+      map1 = Legion::Extensions::Consent::Helpers::ConsentMap.new
+      map1.set_tier('email', :autonomous)
+      map1.record_outcome('calendar', success: true)
+      map1.record_outcome('calendar', success: false)
+      map1.save_to_local
+
+      map2 = Legion::Extensions::Consent::Helpers::ConsentMap.new
+      expect(map2.get_tier('email')).to eq(:autonomous)
+      expect(map2.get_tier('calendar')).to eq(:consult)
+      expect(map2.domains['calendar'][:success_count]).to eq(1)
+      expect(map2.domains['calendar'][:failure_count]).to eq(1)
+    end
+  end
+
+  describe 'graceful no-op when Legion::Data::Local is unavailable' do
+    before do
+      # Simulate no Legion::Data::Local defined
+      hide_const('Legion::Data::Local')
+    end
+
+    it 'save_to_local does nothing without raising' do
+      map = Legion::Extensions::Consent::Helpers::ConsentMap.new
+      map.record_outcome('email', success: true)
+      expect { map.save_to_local }.not_to raise_error
+    end
+
+    it 'load_from_local does nothing without raising (no DB loaded at init)' do
+      expect { Legion::Extensions::Consent::Helpers::ConsentMap.new }.not_to raise_error
+    end
+
+    it 'starts with default in-memory state' do
+      map = Legion::Extensions::Consent::Helpers::ConsentMap.new
+      expect(map.get_tier('email')).to eq(:consult)
+    end
+  end
+
+  describe 'graceful no-op when Legion::Data::Local is defined but not connected' do
+    before do
+      stub_const('Legion::Data::Local', Module.new do
+        def self.connected?
+          false
+        end
+      end)
+    end
+
+    it 'save_to_local does nothing without raising' do
+      map = Legion::Extensions::Consent::Helpers::ConsentMap.new
+      map.record_outcome('email', success: true)
+      expect { map.save_to_local }.not_to raise_error
+    end
+
+    it 'initialize completes without raising' do
+      expect { Legion::Extensions::Consent::Helpers::ConsentMap.new }.not_to raise_error
+    end
+
+    it 'starts with default in-memory state' do
+      map = Legion::Extensions::Consent::Helpers::ConsentMap.new
+      expect(map.get_tier('email')).to eq(:consult)
+    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/consent'
+
+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,91 @@
+--- !ruby/object:Gem::Specification
+name: lex-consent
+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:
+- !ruby/object:Gem::Dependency
+  name: sequel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.70'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.70'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: Four-tier consent gradient with earned autonomy for brain-modeled agentic
+  AI
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- lex-consent.gemspec
+- lib/legion/extensions/consent.rb
+- lib/legion/extensions/consent/actors/tier_evaluation.rb
+- lib/legion/extensions/consent/client.rb
+- lib/legion/extensions/consent/helpers/consent_map.rb
+- lib/legion/extensions/consent/helpers/tiers.rb
+- lib/legion/extensions/consent/local_migrations/20260316000010_create_consent_domains.rb
+- lib/legion/extensions/consent/runners/consent.rb
+- lib/legion/extensions/consent/version.rb
+- spec/legion/extensions/consent/actors/tier_evaluation_spec.rb
+- spec/legion/extensions/consent/client_spec.rb
+- spec/legion/extensions/consent/helpers/tiers_spec.rb
+- spec/legion/extensions/consent/runners/consent_spec.rb
+- spec/local_persistence_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-consent
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-consent
+  source_code_uri: https://github.com/LegionIO/lex-consent
+  documentation_uri: https://github.com/LegionIO/lex-consent
+  changelog_uri: https://github.com/LegionIO/lex-consent
+  bug_tracker_uri: https://github.com/LegionIO/lex-consent/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 Consent
+test_files: []