lex-cognitive-debt 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3393bad153f282e51a0542ee0272f7ccfd57699f0407003ad3b0fe94c57bbc04
+  data.tar.gz: f1c1c120c4a8ae30651b098a11954f5761975c9c5a9c55226f5c63699233a1eb
+SHA512:
+  metadata.gz: edaa0467353d508aa9d0a5f265978684a9d033d44f401f1958ba83dc135ac17279b90a202524e32033f7647cd22bebfa3929cbff747008f2fbd61f53318dd792
+  data.tar.gz: 82c7d74195f7560227ca4409c814c9ddbd8702c7772eb1f2cf9db5a2685e350cb454318534acc3240e7378065cd7f04b6c41d1f2c325dc277ba6aa4988c68a8c

data/Gemfile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+gemspec
+
+group :test do
+  gem 'rake'
+  gem 'rspec', '~> 3.13'
+  gem 'rspec_junit_formatter'
+  gem 'rubocop', '~> 1.75', require: false
+  gem 'rubocop-rspec', require: false
+  gem 'simplecov'
+end

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Iverson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,42 @@
+# lex-cognitive-debt
+
+Cognitive debt modeling for LegionIO. Deferred processing that accrues interest over time.
+
+## What It Does
+
+When the agent defers decisions, leaves inputs unprocessed, abandons partial analysis, or fails to integrate new information, cognitive debt accumulates. Like financial debt, it compounds with interest — the longer you defer, the more costly resolution becomes. This extension tracks that debt, applies interest each cycle, and supports structured repayment.
+
+Five debt types are modeled: deferred decision, unprocessed input, incomplete analysis, pending integration, and unresolved conflict.
+
+## Usage
+
+```ruby
+client = Legion::Extensions::CognitiveDebt::Client.new
+
+debt = client.create_debt(
+  label: 'deferred analysis of conflicting trust signals',
+  debt_type: :incomplete_analysis,
+  principal: 0.5,
+  domain: 'trust'
+)
+
+client.accrue_interest
+client.total_debt
+# => { total_debt: 0.525 }  # 5% interest applied
+
+client.repay_debt(debt_id: debt[:id], amount: 0.2)
+client.debt_report
+client.prune_repaid
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-cognitive-debt.gemspec

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_debt/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-debt'
+  spec.version       = Legion::Extensions::CognitiveDebt::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Cognitive Debt'
+  spec.description   = 'Cognitive debt modeling for brain-modeled agentic AI — deferred processing that accrues interest over time'
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-debt'
+  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-cognitive-debt'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-cognitive-debt'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-cognitive-debt'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-cognitive-debt/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-cognitive-debt.gemspec Gemfile LICENSE README.md]
+  end
+  spec.require_paths = ['lib']
+end

data/lib/legion/extensions/cognitive_debt/client.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_debt/helpers/constants'
+require 'legion/extensions/cognitive_debt/helpers/debt_item'
+require 'legion/extensions/cognitive_debt/helpers/debt_engine'
+require 'legion/extensions/cognitive_debt/runners/cognitive_debt'
+
+module Legion
+  module Extensions
+    module CognitiveDebt
+      class Client
+        include Runners::CognitiveDebt
+
+        def initialize(engine: nil, **)
+          @default_engine = engine || Helpers::DebtEngine.new
+        end
+
+        private
+
+        attr_reader :default_engine
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_debt/helpers/constants.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveDebt
+      module Helpers
+        module Constants
+          MAX_DEBTS      = 300
+          INTEREST_RATE  = 0.05
+          DEFAULT_PRINCIPAL = 0.3
+          REPAYMENT_RATE = 0.1
+
+          SEVERITY_LABELS = {
+            (0.0...0.2)            => :negligible,
+            (0.2...0.4)            => :minor,
+            (0.4...0.6)            => :moderate,
+            (0.6...0.8)            => :severe,
+            (0.8..Float::INFINITY) => :critical
+          }.freeze
+
+          DEBT_TYPES = %i[
+            deferred_decision
+            unprocessed_input
+            incomplete_analysis
+            pending_integration
+            unresolved_conflict
+          ].freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_debt/helpers/debt_engine.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveDebt
+      module Helpers
+        class DebtEngine
+          def initialize
+            @debts = {}
+          end
+
+          def create_debt(label:, debt_type:, principal: Constants::DEFAULT_PRINCIPAL, domain: 'general')
+            return { created: false, reason: :debt_type_invalid } unless Constants::DEBT_TYPES.include?(debt_type.to_sym)
+            return { created: false, reason: :limit_reached } if @debts.size >= Constants::MAX_DEBTS
+
+            item = DebtItem.new(
+              label:     label,
+              debt_type: debt_type,
+              principal: principal,
+              domain:    domain
+            )
+            @debts[item.id] = item
+            { created: true, debt_id: item.id, debt: item.to_h }
+          end
+
+          def repay_debt(debt_id:, amount: Constants::REPAYMENT_RATE)
+            item = @debts[debt_id]
+            return { found: false } unless item
+            return { found: true, repaid: false, reason: :already_repaid } if item.repaid?
+
+            item.repay!(amount: amount)
+            { found: true, repaid: true, debt_id: debt_id, debt: item.to_h }
+          end
+
+          def accrue_all_interest
+            count = 0
+            @debts.each_value do |item|
+              next if item.repaid?
+
+              item.accrue!
+              count += 1
+            end
+            { accrued: count, total_debt: total_debt }
+          end
+
+          def total_debt
+            @debts.values.reject(&:repaid?).sum(&:total_cost).round(10)
+          end
+
+          def debt_by_type(debt_type:)
+            type = debt_type.to_sym
+            items = @debts.values.select { |d| d.debt_type == type && !d.repaid? }
+            { debt_type: type, count: items.size, items: items.map(&:to_h) }
+          end
+
+          def debt_by_domain(domain:)
+            items = @debts.values.select { |d| d.domain == domain && !d.repaid? }
+            { domain: domain, count: items.size, items: items.map(&:to_h) }
+          end
+
+          def most_costly(limit: 10)
+            items = @debts.values
+                          .reject(&:repaid?)
+                          .sort_by { |d| -d.total_cost }
+                          .first(limit)
+            { count: items.size, items: items.map(&:to_h) }
+          end
+
+          def oldest_debts(limit: 10)
+            items = @debts.values
+                          .reject(&:repaid?)
+                          .sort_by(&:created_at)
+                          .first(limit)
+            { count: items.size, items: items.map(&:to_h) }
+          end
+
+          def debt_report
+            active = @debts.values.reject(&:repaid?)
+            by_type = Constants::DEBT_TYPES.to_h do |type|
+              typed = active.select { |d| d.debt_type == type }
+              [type, { count: typed.size, total_cost: typed.sum(&:total_cost).round(10) }]
+            end
+
+            priority = active.sort_by { |d| -d.total_cost }.first(5)
+
+            {
+              total_debt:           total_debt,
+              active_count:         active.size,
+              repaid_count:         @debts.values.count(&:repaid?),
+              by_type:              by_type,
+              recommended_priority: priority.map(&:to_h)
+            }
+          end
+
+          def prune_repaid
+            before = @debts.size
+            @debts.delete_if { |_id, item| item.repaid? }
+            pruned = before - @debts.size
+            { pruned: pruned, remaining: @debts.size }
+          end
+
+          def to_h
+            {
+              total_debt:   total_debt,
+              active_count: @debts.values.reject(&:repaid?).size,
+              total_count:  @debts.size,
+              debts:        @debts.values.map(&:to_h)
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_debt/helpers/debt_item.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveDebt
+      module Helpers
+        class DebtItem
+          attr_reader :id, :label, :debt_type, :principal, :accrued_interest,
+                      :domain, :created_at, :repaid_at
+
+          def initialize(label:, debt_type:, principal:, domain:)
+            @id               = SecureRandom.uuid
+            @label            = label
+            @debt_type        = debt_type.to_sym
+            @principal        = principal.clamp(0.0, Float::INFINITY)
+            @accrued_interest = 0.0
+            @domain           = domain
+            @created_at       = Time.now.utc
+            @repaid_at        = nil
+          end
+
+          def total_cost
+            (@principal + @accrued_interest).round(10)
+          end
+
+          def accrue!
+            return if repaid?
+
+            @accrued_interest = (@accrued_interest + (Constants::INTEREST_RATE * @principal)).round(10)
+          end
+
+          def repay!(amount: Constants::REPAYMENT_RATE)
+            return if repaid?
+
+            @accrued_interest = [0.0, @accrued_interest - amount].max.round(10)
+            @principal        = [0.0, @principal - amount].max.round(10)
+            @repaid_at        = Time.now.utc if @principal.zero? && @accrued_interest.zero?
+          end
+
+          def repaid?
+            !@repaid_at.nil?
+          end
+
+          def severity_label
+            cost = total_cost
+            Constants::SEVERITY_LABELS.each do |range, label|
+              return label if range.cover?(cost)
+            end
+            :critical
+          end
+
+          def age_seconds
+            reference = @repaid_at || Time.now.utc
+            (reference - @created_at).to_f
+          end
+
+          def to_h
+            {
+              id:               @id,
+              label:            @label,
+              debt_type:        @debt_type,
+              principal:        @principal,
+              accrued_interest: @accrued_interest,
+              total_cost:       total_cost,
+              domain:           @domain,
+              severity:         severity_label,
+              age_seconds:      age_seconds.round(2),
+              created_at:       @created_at.iso8601,
+              repaid_at:        @repaid_at&.iso8601,
+              repaid:           repaid?
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveDebt
+      module Runners
+        module CognitiveDebt
+          def create_debt(label:, debt_type:, principal: Helpers::Constants::DEFAULT_PRINCIPAL,
+                          domain: 'general', engine: nil, **)
+            eng = engine || default_engine
+            Legion::Logging.debug "[cognitive_debt] create debt label=#{label} type=#{debt_type} principal=#{principal}"
+            eng.create_debt(label: label, debt_type: debt_type, principal: principal, domain: domain)
+          end
+
+          def repay_debt(debt_id:, amount: Helpers::Constants::REPAYMENT_RATE, engine: nil, **)
+            eng = engine || default_engine
+            Legion::Logging.debug "[cognitive_debt] repay debt_id=#{debt_id[0..7]} amount=#{amount}"
+            eng.repay_debt(debt_id: debt_id, amount: amount)
+          end
+
+          def accrue_interest(engine: nil, **)
+            eng = engine || default_engine
+            result = eng.accrue_all_interest
+            Legion::Logging.debug "[cognitive_debt] accrued interest on #{result[:accrued]} debts total_debt=#{result[:total_debt]}"
+            result
+          end
+
+          def total_debt(engine: nil, **)
+            eng = engine || default_engine
+            cost = eng.total_debt
+            Legion::Logging.debug "[cognitive_debt] total_debt=#{cost}"
+            { total_debt: cost }
+          end
+
+          def debt_by_type(debt_type:, engine: nil, **)
+            eng = engine || default_engine
+            eng.debt_by_type(debt_type: debt_type)
+          end
+
+          def debt_by_domain(domain:, engine: nil, **)
+            eng = engine || default_engine
+            eng.debt_by_domain(domain: domain)
+          end
+
+          def most_costly(limit: 10, engine: nil, **)
+            eng = engine || default_engine
+            eng.most_costly(limit: limit)
+          end
+
+          def oldest_debts(limit: 10, engine: nil, **)
+            eng = engine || default_engine
+            eng.oldest_debts(limit: limit)
+          end
+
+          def debt_report(engine: nil, **)
+            eng = engine || default_engine
+            report = eng.debt_report
+            Legion::Logging.debug "[cognitive_debt] report total_debt=#{report[:total_debt]} active=#{report[:active_count]}"
+            report
+          end
+
+          def prune_repaid(engine: nil, **)
+            eng = engine || default_engine
+            result = eng.prune_repaid
+            Legion::Logging.debug "[cognitive_debt] pruned #{result[:pruned]} repaid debts remaining=#{result[:remaining]}"
+            result
+          end
+
+          include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+          private
+
+          def default_engine
+            @default_engine ||= Helpers::DebtEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/cognitive_debt.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_debt/version'
+require 'legion/extensions/cognitive_debt/helpers/constants'
+require 'legion/extensions/cognitive_debt/helpers/debt_item'
+require 'legion/extensions/cognitive_debt/helpers/debt_engine'
+require 'legion/extensions/cognitive_debt/runners/cognitive_debt'
+
+module Legion
+  module Extensions
+    module CognitiveDebt
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_debt/client'
+
+RSpec.describe Legion::Extensions::CognitiveDebt::Client do
+  let(:client) { described_class.new }
+
+  it 'responds to create_debt' do
+    expect(client).to respond_to(:create_debt)
+  end
+
+  it 'responds to repay_debt' do
+    expect(client).to respond_to(:repay_debt)
+  end
+
+  it 'responds to accrue_interest' do
+    expect(client).to respond_to(:accrue_interest)
+  end
+
+  it 'responds to total_debt' do
+    expect(client).to respond_to(:total_debt)
+  end
+
+  it 'responds to debt_by_type' do
+    expect(client).to respond_to(:debt_by_type)
+  end
+
+  it 'responds to debt_by_domain' do
+    expect(client).to respond_to(:debt_by_domain)
+  end
+
+  it 'responds to most_costly' do
+    expect(client).to respond_to(:most_costly)
+  end
+
+  it 'responds to oldest_debts' do
+    expect(client).to respond_to(:oldest_debts)
+  end
+
+  it 'responds to debt_report' do
+    expect(client).to respond_to(:debt_report)
+  end
+
+  it 'responds to prune_repaid' do
+    expect(client).to respond_to(:prune_repaid)
+  end
+
+  it 'accepts an injected engine' do
+    engine = Legion::Extensions::CognitiveDebt::Helpers::DebtEngine.new
+    c = described_class.new(engine: engine)
+    c.create_debt(label: 'test', debt_type: :deferred_decision, principal: 0.3)
+    expect(engine.total_debt).to be_within(1e-10).of(0.3)
+  end
+
+  it 'round-trips a full lifecycle' do
+    created = client.create_debt(label: 'pick caching layer', debt_type: :deferred_decision, principal: 0.4)
+    expect(created[:created]).to be true
+    debt_id = created[:debt_id]
+
+    client.accrue_interest
+    report = client.debt_report
+    expect(report[:total_debt]).to be > 0.4
+
+    repaid = client.repay_debt(debt_id: debt_id, amount: 99.0)
+    expect(repaid[:repaid]).to be true
+
+    pruned = client.prune_repaid
+    expect(pruned[:pruned]).to eq(1)
+
+    final = client.total_debt
+    expect(final[:total_debt]).to eq(0.0)
+  end
+end

data/spec/legion/extensions/cognitive_debt/helpers/constants_spec.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::CognitiveDebt::Helpers::Constants do
+  describe 'MAX_DEBTS' do
+    it 'is 300' do
+      expect(described_class::MAX_DEBTS).to eq(300)
+    end
+  end
+
+  describe 'INTEREST_RATE' do
+    it 'is 0.05' do
+      expect(described_class::INTEREST_RATE).to eq(0.05)
+    end
+  end
+
+  describe 'DEFAULT_PRINCIPAL' do
+    it 'is 0.3' do
+      expect(described_class::DEFAULT_PRINCIPAL).to eq(0.3)
+    end
+  end
+
+  describe 'REPAYMENT_RATE' do
+    it 'is 0.1' do
+      expect(described_class::REPAYMENT_RATE).to eq(0.1)
+    end
+  end
+
+  describe 'SEVERITY_LABELS' do
+    it 'is a frozen hash' do
+      expect(described_class::SEVERITY_LABELS).to be_frozen
+    end
+
+    it 'maps low cost to :negligible' do
+      label = described_class::SEVERITY_LABELS.find { |range, _| range.cover?(0.1) }&.last
+      expect(label).to eq(:negligible)
+    end
+
+    it 'maps 0.3 to :minor' do
+      label = described_class::SEVERITY_LABELS.find { |range, _| range.cover?(0.3) }&.last
+      expect(label).to eq(:minor)
+    end
+
+    it 'maps 0.5 to :moderate' do
+      label = described_class::SEVERITY_LABELS.find { |range, _| range.cover?(0.5) }&.last
+      expect(label).to eq(:moderate)
+    end
+
+    it 'maps 0.7 to :severe' do
+      label = described_class::SEVERITY_LABELS.find { |range, _| range.cover?(0.7) }&.last
+      expect(label).to eq(:severe)
+    end
+
+    it 'maps 0.9 to :critical' do
+      label = described_class::SEVERITY_LABELS.find { |range, _| range.cover?(0.9) }&.last
+      expect(label).to eq(:critical)
+    end
+  end
+
+  describe 'DEBT_TYPES' do
+    it 'includes all five expected types' do
+      expect(described_class::DEBT_TYPES).to include(
+        :deferred_decision,
+        :unprocessed_input,
+        :incomplete_analysis,
+        :pending_integration,
+        :unresolved_conflict
+      )
+    end
+
+    it 'has exactly five types' do
+      expect(described_class::DEBT_TYPES.size).to eq(5)
+    end
+
+    it 'contains only symbols' do
+      expect(described_class::DEBT_TYPES).to all(be_a(Symbol))
+    end
+  end
+end