lex-tick 0.1.14 → 0.1.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5057fa93fb198fd044c7bf73802d9e454311d0913bf32c8c01b73cb508f0ed02
-  data.tar.gz: 85ee186078e9db6e4d7250de0745f51d5c85703385c2e9396c21ed947f1b57fd
+  metadata.gz: 94918234bd1b19854887b794867550d1a6252f74ea4ad10dd6009b6df2797c5b
+  data.tar.gz: df175d240f2a5816e9b7be4269aa12880051e1bbe5bdf6f761731cca585b0e10
 SHA512:
-  metadata.gz: 43833d847d50dd1e1a5a88549c1082c5a076198ee04cf8cf511b6dca3029b1b8c357d435bf6838fa5b8f3a06cf45dab6477f041219326c2f609b7c9ef4ab8179
-  data.tar.gz: e74030f8aabd9eb496a01b18b36e782cd61cfb6be83cb3ba842c1d5ca62098a2defb9c2c02a4a3c28a465805bce74dee5c25c487fad75371878ebcae5ba0659d
+  metadata.gz: 291b85fa4cfe572c00bb279026569c08691daf1233d7900ffe619e6c4f8d15b3cc9241d18f98aa8ef22715a0438a78a1239919181decf4463f8ab26e13c708cc
+  data.tar.gz: 56b3a74946173477cbd2d3d85a6b35ff15cc61472b9065bade72af63dcbdab5a8392ceaf50a54ca7e4397db01142cf6d4ee702786d60d938bbd7fa2ff541f954

data/lex-tick.gemspec

@@ -9,7 +9,7 @@ Gem::Specification.new do |spec|
   spec.email         = ['matthewdiverson@gmail.com']
 
   spec.summary       = 'LEX Tick'
-  spec.description   = 'Atomic cognitive processing cycle (11 phases, 3 modes) for brain-modeled agentic AI'
+  spec.description   = 'Atomic cognitive processing cycle (16 phases, 4 modes, 10 dream phases) for brain-modeled agentic AI'
   spec.homepage      = 'https://github.com/LegionIO/lex-tick'
   spec.license       = 'MIT'
   spec.required_ruby_version = '>= 3.4'

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

@@ -55,12 +55,16 @@ module Legion
           SENTINEL_TIMEOUT              = 3600   # seconds without any signal before demotion to dormant
           DREAM_IDLE_THRESHOLD          = 1800   # seconds dormant with no signal before entering dream cycle
           SENTINEL_TO_DREAM_THRESHOLD   = 600    # seconds sentinel with no signal before entering dream cycle
+          DREAM_BACKOFF_INTERVAL        = 1800   # seconds after a completed dream before another dream cycle
           MAX_TICK_DURATION             = 5.0    # hard ceiling for full active tick (seconds)
+          DREAM_TICK_BUDGET             = 5.0    # hard ceiling for dormant-active dream tick (seconds)
           SENTINEL_TICK_BUDGET          = 0.5    # time budget for sentinel tick
           DORMANT_TICK_BUDGET           = 0.2    # time budget for dormant tick
           EMERGENCY_PROMOTION_BUDGET    = 0.05   # max latency for emergency mode promotion
 
-          # Phase timing budgets (fraction of total tick time)
+          # Phase timing budgets (fraction of total tick time).
+          # Informational only — not enforced by run_phases, which uses the tick-level budget.
+          # Useful as a reference for callers that want to self-limit within a phase handler.
           PHASE_BUDGETS = {
             sensory_processing:         0.12,
             emotional_evaluation:       0.08,
@@ -93,7 +97,7 @@ module Legion
           def tick_budget(mode)
             case mode
             when :dormant        then DORMANT_TICK_BUDGET
-            when :dormant_active then Float::INFINITY
+            when :dormant_active then DREAM_TICK_BUDGET
             when :sentinel       then SENTINEL_TICK_BUDGET
             else                      MAX_TICK_DURATION
             end

data/lib/legion/extensions/tick/helpers/state.rb

@@ -5,7 +5,7 @@ module Legion
     module Tick
       module Helpers
         class State
-          attr_reader :mode, :tick_count, :last_signal_at, :last_high_salience_at,
+          attr_reader :mode, :tick_count, :last_signal_at, :last_high_salience_at, :last_dream_completed_at,
                       :phase_results, :current_phase, :mode_history
 
           def initialize(mode: :dormant)
@@ -13,6 +13,7 @@ module Legion
             @tick_count = 0
             @last_signal_at = nil
             @last_high_salience_at = nil
+            @last_dream_completed_at = nil
             @phase_results = {}
             @current_phase = nil
             @mode_history = [{ mode: mode, at: Time.now.utc }]
@@ -44,6 +45,10 @@ module Legion
             @mode_history.shift while @mode_history.size > 50
           end
 
+          def record_dream_completed
+            @last_dream_completed_at = Time.now.utc
+          end
+
           def seconds_since_signal
             return 0.0 unless @last_signal_at
 
@@ -56,14 +61,21 @@ module Legion
             Time.now.utc - @last_high_salience_at
           end
 
+          def seconds_since_dream_completed
+            return Float::INFINITY unless @last_dream_completed_at
+
+            Time.now.utc - @last_dream_completed_at
+          end
+
           def to_h
             {
-              mode:                  @mode,
-              tick_count:            @tick_count,
-              current_phase:         @current_phase,
-              last_signal_at:        @last_signal_at,
-              last_high_salience_at: @last_high_salience_at,
-              phases_completed:      @phase_results.keys
+              mode:                    @mode,
+              tick_count:              @tick_count,
+              current_phase:           @current_phase,
+              last_signal_at:          @last_signal_at,
+              last_high_salience_at:   @last_high_salience_at,
+              last_dream_completed_at: @last_dream_completed_at,
+              phases_completed:        @phase_results.keys
             }
           end
         end

data/lib/legion/extensions/tick/runners/orchestrator.rb

@@ -25,7 +25,7 @@ module Legion
             end
           end
 
-          def evaluate_mode_transition(signals: [], emergency: nil, dream_complete: false, **) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+          def evaluate_mode_transition(signals: [], emergency: nil, dream_complete: false, **) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
             state = tick_state
             previous_mode = state.mode
 
@@ -44,7 +44,7 @@ module Legion
                        when :dormant
                          if signals.any?
                            :sentinel
-                         elsif state.seconds_since_signal >= Helpers::Constants::DREAM_IDLE_THRESHOLD
+                         elsif state.seconds_since_signal >= Helpers::Constants::DREAM_IDLE_THRESHOLD && dream_backoff_elapsed?(state)
                            :dormant_active
                          else
                            :dormant
@@ -53,6 +53,7 @@ module Legion
                          if max_salience >= Helpers::Constants::HIGH_SALIENCE_THRESHOLD || has_human
                            :sentinel
                          elsif dream_complete
+                           state.record_dream_completed
                            :dormant
                          else
                            :dormant_active
@@ -60,10 +61,11 @@ module Legion
                        when :sentinel
                          if has_human || max_salience >= Helpers::Constants::HIGH_SALIENCE_THRESHOLD
                            :full_active
-                         elsif state.seconds_since_signal >= Helpers::Constants::SENTINEL_TO_DREAM_THRESHOLD
-                           :dormant_active
                          elsif state.seconds_since_signal >= Helpers::Constants::SENTINEL_TIMEOUT
                            :dormant
+                         elsif state.seconds_since_signal >= Helpers::Constants::SENTINEL_TO_DREAM_THRESHOLD &&
+                               dream_backoff_elapsed?(state)
+                           :dormant_active
                          else
                            :sentinel
                          end
@@ -98,7 +100,9 @@ module Legion
 
             previous = tick_state.mode
             tick_state.transition_to(mode)
-            log.info "[tick] mode forced: #{previous} -> #{mode}"
+            @mode_forced      = true
+            @force_expires_at = Time.now.utc + Helpers::Constants.tick_budget(mode).clamp(0, Helpers::Constants::MAX_TICK_DURATION)
+            log.info "[tick] mode forced: #{previous} -> #{mode} (protected until #{@force_expires_at})"
             { mode: mode }
           end
 
@@ -114,7 +118,15 @@ module Legion
 
             log.debug "[tick] ##{state.tick_count} starting | mode=#{state.mode} signals=#{signals.size} max_salience=#{max_salience.round(2)}"
 
-            evaluate_mode_transition(signals: signals)
+            # Skip automatic mode evaluation for the one tick following a forced set_mode call.
+            # @mode_forced is set by set_mode and cleared here so the force lasts exactly one cycle.
+            if @mode_forced
+              log.debug "[tick] ##{state.tick_count} skipping mode evaluation (mode forced to #{state.mode})"
+              @mode_forced      = false
+              @force_expires_at = nil
+            else
+              evaluate_mode_transition(signals: signals)
+            end
 
             phases = Helpers::Constants.phases_for_mode(state.mode)
             budget = Helpers::Constants.tick_budget(state.mode)
@@ -127,6 +139,7 @@ module Legion
               context:        context
             }
             results = run_phases(phases, state, ctx)
+            finish_dream_cycle(state, phases, results)
 
             total_elapsed = Time.now.utc - start_time
             skipped = phases - results.keys
@@ -177,6 +190,28 @@ module Legion
                       "elapsed=#{(total_elapsed * 1000).round(1)}ms#{skipped_suffix}"
           end
 
+          def finish_dream_cycle(state, phases, results)
+            return unless state.mode == :dormant_active
+            return unless phases == Helpers::Constants::DREAM_PHASES
+
+            skipped = phases - results.keys
+            failed = failed_dream_phases(results)
+            state.record_dream_completed
+            state.transition_to(:dormant)
+            if skipped.empty? && failed.empty?
+              log.info '[tick] dream cycle complete; backing off to dormant'
+            else
+              log.info "[tick] dream cycle deferred; backing off to dormant skipped=#{skipped} failed=#{failed}"
+            end
+          end
+
+          def failed_dream_phases(results)
+            results.each_with_object([]) do |(phase, result), failed|
+              status = result.is_a?(Hash) ? result[:status] : nil
+              failed << phase if %i[error failed failure timeout].include?(status)
+            end
+          end
+
           def full_active_cooldown_elapsed(state)
             if state.last_high_salience_at
               state.seconds_since_high_salience
@@ -187,6 +222,10 @@ module Legion
             end
           end
 
+          def dream_backoff_elapsed?(state)
+            state.seconds_since_dream_completed >= Helpers::Constants::DREAM_BACKOFF_INTERVAL
+          end
+
           def tick_state
             @tick_state ||= Helpers::State.new
           end

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

@@ -3,7 +3,7 @@
 module Legion
   module Extensions
     module Tick
-      VERSION = '0.1.14'
+      VERSION = '0.1.16'
     end
   end
 end

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

@@ -87,8 +87,8 @@ RSpec.describe Legion::Extensions::Tick::Helpers::Constants do
   end
 
   describe '.tick_budget' do
-    it 'returns Float::INFINITY for dormant_active' do
-      expect(described_class.tick_budget(:dormant_active)).to eq(Float::INFINITY)
+    it 'returns DREAM_TICK_BUDGET for dormant_active' do
+      expect(described_class.tick_budget(:dormant_active)).to eq(described_class::DREAM_TICK_BUDGET)
     end
   end
 
@@ -100,5 +100,13 @@ RSpec.describe Legion::Extensions::Tick::Helpers::Constants do
     it 'defines SENTINEL_TO_DREAM_THRESHOLD as 600' do
       expect(described_class::SENTINEL_TO_DREAM_THRESHOLD).to eq(600)
     end
+
+    it 'defines DREAM_BACKOFF_INTERVAL as 1800' do
+      expect(described_class::DREAM_BACKOFF_INTERVAL).to eq(1800)
+    end
+
+    it 'defines DREAM_TICK_BUDGET as finite' do
+      expect(described_class::DREAM_TICK_BUDGET).to eq(5.0)
+    end
   end
 end

data/spec/legion/extensions/tick/helpers/state_spec.rb

@@ -60,6 +60,19 @@ RSpec.describe Legion::Extensions::Tick::Helpers::State do
     end
   end
 
+  describe '#record_dream_completed' do
+    it 'updates last_dream_completed_at' do
+      state.record_dream_completed
+      expect(state.last_dream_completed_at).not_to be_nil
+    end
+  end
+
+  describe '#seconds_since_dream_completed' do
+    it 'treats missing dream completion history as eligible for a dream cycle' do
+      expect(state.seconds_since_dream_completed).to eq(Float::INFINITY)
+    end
+  end
+
   describe '#transition_to' do
     it 'changes mode' do
       state.transition_to(:sentinel)
@@ -83,6 +96,7 @@ RSpec.describe Legion::Extensions::Tick::Helpers::State do
       h = state.to_h
       expect(h).to have_key(:mode)
       expect(h).to have_key(:tick_count)
+      expect(h).to have_key(:last_dream_completed_at)
       expect(h).to have_key(:phases_completed)
     end
   end

data/spec/legion/extensions/tick/runners/orchestrator_spec.rb

@@ -67,6 +67,56 @@ RSpec.describe Legion::Extensions::Tick::Runners::Orchestrator do
       result = client.execute_tick(signals: [{ salience: 0.3 }])
       expect(result[:mode]).to eq(:sentinel)
     end
+
+    it 'completes one dormant_active dream cycle and backs off to dormant' do
+      client.set_mode(mode: :dormant_active)
+
+      result = client.execute_tick
+
+      expect(result[:phases_executed]).to eq(Legion::Extensions::Tick::Helpers::Constants::DREAM_PHASES)
+      expect(result[:mode]).to eq(:dormant)
+      expect(client.tick_status[:last_dream_completed_at]).not_to be_nil
+    end
+
+    it 'does not immediately restart a completed dream cycle on the next heartbeat' do
+      state = client.send(:tick_state)
+      allow(state).to receive(:seconds_since_signal).and_return(1801.0)
+
+      client.set_mode(mode: :dormant_active)
+      client.execute_tick
+      result = client.execute_tick
+
+      expect(result[:mode]).to eq(:dormant)
+      expect(result[:phases_executed]).to eq([:memory_consolidation])
+    end
+
+    it 'backs off to dormant when a dream phase fails' do
+      client.set_mode(mode: :dormant_active)
+
+      result = client.execute_tick(
+        phase_handlers: {
+          dream_narration: ->(**) { { status: :error } }
+        }
+      )
+
+      expect(result[:mode]).to eq(:dormant)
+      expect(result[:results][:dream_narration][:status]).to eq(:error)
+      expect(client.tick_status[:last_dream_completed_at]).not_to be_nil
+    end
+
+    it 'backs off to dormant when the dream tick budget is exhausted before all phases run' do
+      constants = Legion::Extensions::Tick::Helpers::Constants
+      allow(constants).to receive(:tick_budget).and_call_original
+      allow(constants).to receive(:tick_budget).with(:dormant_active).and_return(0.0)
+
+      client.set_mode(mode: :dormant_active)
+      result = client.execute_tick
+
+      expect(result[:mode]).to eq(:dormant)
+      expect(result[:phases_executed]).to be_empty
+      expect(result[:phases_skipped]).to eq(constants::DREAM_PHASES)
+      expect(client.tick_status[:last_dream_completed_at]).not_to be_nil
+    end
   end
 
   describe '#evaluate_mode_transition' do
@@ -138,6 +188,7 @@ RSpec.describe Legion::Extensions::Tick::Runners::Orchestrator do
         result = client.evaluate_mode_transition(dream_complete: true)
         expect(result[:transitioned]).to be true
         expect(result[:new_mode]).to eq(:dormant)
+        expect(client.tick_status[:last_dream_completed_at]).not_to be_nil
       end
 
       it 'stays dormant_active when no signals and dream not complete' do
@@ -146,6 +197,29 @@ RSpec.describe Legion::Extensions::Tick::Runners::Orchestrator do
         expect(result[:transitioned]).to be false
         expect(result[:current_mode]).to eq(:dormant_active)
       end
+
+      it 'keeps dormant backed off after a completed dream cycle' do
+        state = client.send(:tick_state)
+        state.record_dream_completed
+        allow(state).to receive(:seconds_since_signal).and_return(1801.0)
+
+        result = client.evaluate_mode_transition
+
+        expect(result[:transitioned]).to be false
+        expect(result[:current_mode]).to eq(:dormant)
+      end
+
+      it 'allows dormant_active again after dream backoff elapses' do
+        state = client.send(:tick_state)
+        state.record_dream_completed
+        allow(state).to receive(:seconds_since_signal).and_return(1801.0)
+        allow(state).to receive(:seconds_since_dream_completed).and_return(1801.0)
+
+        result = client.evaluate_mode_transition
+
+        expect(result[:transitioned]).to be true
+        expect(result[:new_mode]).to eq(:dormant_active)
+      end
     end
 
     context 'sentinel -> dormant_active' do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-tick
 version: !ruby/object:Gem::Version
-  version: 0.1.14
+  version: 0.1.16
 platform: ruby
 authors:
 - Esity
@@ -107,8 +107,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.3.9
-description: Atomic cognitive processing cycle (11 phases, 3 modes) for brain-modeled
-  agentic AI
+description: Atomic cognitive processing cycle (16 phases, 4 modes, 10 dream phases)
+  for brain-modeled agentic AI
 email:
 - matthewdiverson@gmail.com
 executables: []