Class: Legion::Extensions::Agentic::Homeostasis::Surplus::Helpers::SurplusEngine

Inherits:
Object
  • Object
show all
Includes:
Constants
Defined in:
lib/legion/extensions/agentic/homeostasis/surplus/helpers/surplus_engine.rb

Constant Summary

Constants included from Constants

Constants::ALLOCATION_TYPES, Constants::DEPLETION_RATE, Constants::MIN_RESERVE, Constants::QUALITY_LABELS, Constants::REPLENISH_RATE, Constants::SURPLUS_LABELS, Constants::SURPLUS_THRESHOLD, Constants::TOTAL_CAPACITY

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Constants

clamp, quality_label, surplus_label, valid_allocation_type?

Constructor Details

#initialize ⇒ SurplusEngine

Returns a new instance of SurplusEngine.



14
15
16
17
18
 
# File 'lib/legion/extensions/agentic/homeostasis/surplus/helpers/surplus_engine.rb', line 14

def initialize
  @committed   = 0.0
  @reserved    = Constants::MIN_RESERVE
  @allocations = {}
end

Instance Attribute Details

#allocations ⇒ Object (readonly)

Returns the value of attribute allocations.



12
13
14
 
# File 'lib/legion/extensions/agentic/homeostasis/surplus/helpers/surplus_engine.rb', line 12

def allocations
  @allocations
end

#committed ⇒ Object (readonly)

Returns the value of attribute committed.



12
13
14
 
# File 'lib/legion/extensions/agentic/homeostasis/surplus/helpers/surplus_engine.rb', line 12

def committed
  @committed
end

#reserved ⇒ Object (readonly)

Returns the value of attribute reserved.



12
13
14
 
# File 'lib/legion/extensions/agentic/homeostasis/surplus/helpers/surplus_engine.rb', line 12

def reserved
  @reserved
end

Instance Method Details

#allocate!(activity_type:, amount:) ⇒ Object 



31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
 
# File 'lib/legion/extensions/agentic/homeostasis/surplus/helpers/surplus_engine.rb', line 31

def allocate!(activity_type:, amount:)
  return { allocated: false, reason: :invalid_type } unless Constants.valid_allocation_type?(activity_type)
  return { allocated: false, reason: :below_threshold } if available_surplus < Constants::SURPLUS_THRESHOLD

  clamped = Constants.clamp(amount, 0.0, available_surplus).round(10)
  return { allocated: false, reason: :insufficient_surplus } if clamped <= 0.0

  quality = surplus_quality
  allocation = Allocation.new(activity_type: activity_type, amount: clamped, quality: quality)
  @allocations[allocation.id] = allocation

  {
    allocated:     true,
    allocation_id: allocation.id,
    amount:        clamped,
    quality:       quality,
    activity_type: activity_type
  }
end

#available_surplus ⇒ Object 



20
21
22
23
 
# File 'lib/legion/extensions/agentic/homeostasis/surplus/helpers/surplus_engine.rb', line 20

def available_surplus
  used = @committed + @reserved + active_allocated
  Constants.clamp(Constants::TOTAL_CAPACITY - used).round(10)
end

#commit!(amount:) ⇒ Object 



60
61
62
63
64
 
# File 'lib/legion/extensions/agentic/homeostasis/surplus/helpers/surplus_engine.rb', line 60

def commit!(amount:)
  clamped = Constants.clamp(amount.round(10), 0.0, Constants::TOTAL_CAPACITY - @reserved)
  @committed = Constants.clamp((@committed + clamped).round(10))
  { committed: @committed, available_surplus: available_surplus }
end

#deplete!(amount:) ⇒ Object 



79
80
81
82
83
 
# File 'lib/legion/extensions/agentic/homeostasis/surplus/helpers/surplus_engine.rb', line 79

def deplete!(amount:)
  delta = Constants.clamp(amount.round(10), 0.0, available_surplus)
  @committed = Constants.clamp((@committed + delta).round(10))
  { depleted: true, amount: delta, available_surplus: available_surplus }
end

#release!(allocation_id:) ⇒ Object 



51
52
53
54
55
56
57
58
 
# File 'lib/legion/extensions/agentic/homeostasis/surplus/helpers/surplus_engine.rb', line 51

def release!(allocation_id:)
  allocation = @allocations[allocation_id]
  return { released: false, reason: :not_found } unless allocation
  return { released: false, reason: :already_released } unless allocation.active?

  allocation.release!
  { released: true, allocation_id: allocation_id, amount: allocation.amount }
end

#replenish! ⇒ Object 



72
73
74
75
76
77
 
# File 'lib/legion/extensions/agentic/homeostasis/surplus/helpers/surplus_engine.rb', line 72

def replenish!
  old_committed = @committed
  @committed = Constants.clamp((@committed - Constants::REPLENISH_RATE).round(10))
  gained = (old_committed - @committed).round(10)
  { replenished: true, gained: gained, available_surplus: available_surplus }
end

#surplus_quality ⇒ Object 



25
26
27
28
29
 
# File 'lib/legion/extensions/agentic/homeostasis/surplus/helpers/surplus_engine.rb', line 25

def surplus_quality
  idle = Constants::TOTAL_CAPACITY - @committed
  raw = idle / Constants::TOTAL_CAPACITY
  Constants.clamp(raw).round(10)
end

#surplus_report ⇒ Object 



85
86
87
88
89
90
91
92
93
94
95
96
97
98
 
# File 'lib/legion/extensions/agentic/homeostasis/surplus/helpers/surplus_engine.rb', line 85

def surplus_report
  surplus = available_surplus
  {
    total_capacity:    Constants::TOTAL_CAPACITY,
    committed:         @committed.round(10),
    reserved:          @reserved.round(10),
    active_allocated:  active_allocated.round(10),
    available_surplus: surplus,
    surplus_label:     Constants.surplus_label(surplus),
    quality:           surplus_quality,
    quality_label:     Constants.quality_label(surplus_quality),
    allocation_count:  active_allocations.size
  }
end

#to_h ⇒ Object 



100
101
102
 
# File 'lib/legion/extensions/agentic/homeostasis/surplus/helpers/surplus_engine.rb', line 100

def to_h
  surplus_report.merge(allocations: @allocations.transform_values(&:to_h))
end

#uncommit!(amount:) ⇒ Object 



66
67
68
69
70
 
# File 'lib/legion/extensions/agentic/homeostasis/surplus/helpers/surplus_engine.rb', line 66

def uncommit!(amount:)
  clamped = Constants.clamp(amount.round(10), 0.0, @committed)
  @committed = Constants.clamp((@committed - clamped).round(10))
  { committed: @committed, available_surplus: available_surplus }
end