lex-tick 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4a3808a8152389198268ec0a2064aee1a4acdcf8fc7aa5593118e1cd7f82deda
+  data.tar.gz: 770f22284ee087b9319597ebe194b34bcc4e1b17b901db13f4bc8d45b38a6d3c
+SHA512:
+  metadata.gz: 80498e4cfb7859876f8efb0e72ad89bad390f307d56f7a27dea617092f946d828db57522591af4629a3fe00e6c1ae279e7effca892a35cb5d14fe4085ad5eb3d
+  data.tar.gz: f9a62ee7072446e4c0caf5b55c05fff8d12323ab3619fb7d9c923e0e252649ec9acab3d287f46a1358b6298ecb7285e519499838bf6e6c0b3c1f66b36c7662a6

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 'legion-gaia', path: '../../legion-gaia'

data/lex-tick.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/tick/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-tick'
+  spec.version       = Legion::Extensions::Tick::VERSION
+  spec.authors       = ['Esity']
+  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.homepage      = 'https://github.com/LegionIO/lex-tick'
+  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-tick'
+  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-tick'
+  spec.metadata['changelog_uri'] = 'https://github.com/LegionIO/lex-tick'
+  spec.metadata['bug_tracker_uri'] = 'https://github.com/LegionIO/lex-tick/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-tick.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module Tick
+      module Actor
+        # Disabled: lex-cortex's Think actor replaces this.
+        # Cortex wires phase_handlers from all agentic extensions
+        # and calls execute_tick with real handlers instead of empty ones.
+        # To use tick standalone (without cortex), re-enable this actor.
+        class Tick < Legion::Extensions::Actors::Every
+          def initialize(**opts)
+            return unless enabled?
+
+            super
+          end
+
+          def runner_class
+            Legion::Extensions::Tick::Runners::Orchestrator
+          end
+
+          def runner_function
+            'execute_tick'
+          end
+
+          def enabled?
+            !Legion::Extensions.const_defined?(:Cortex)
+          end
+
+          def time
+            1
+          end
+
+          def run_now?
+            true
+          end
+
+          def use_runner?
+            false
+          end
+
+          def check_subtask?
+            false
+          end
+
+          def generate_task?
+            false
+          end
+
+          def args
+            { signals: [], phase_handlers: {} }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/tick/helpers/constants'
+require 'legion/extensions/tick/helpers/state'
+require 'legion/extensions/tick/runners/orchestrator'
+
+module Legion
+  module Extensions
+    module Tick
+      class Client
+        include Runners::Orchestrator
+
+        def initialize(mode: :dormant, **)
+          @tick_state = Helpers::State.new(mode: mode)
+        end
+
+        private
+
+        attr_reader :tick_state
+      end
+    end
+  end
+end

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

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Tick
+      module Helpers
+        module Constants
+          # Tick modes
+          MODES = %i[dormant dormant_active sentinel full_active].freeze
+
+          # 12 phases of a full active tick
+          PHASES = %i[
+            sensory_processing
+            emotional_evaluation
+            memory_retrieval
+            identity_entropy_check
+            working_memory_integration
+            procedural_check
+            prediction_engine
+            mesh_interface
+            gut_instinct
+            action_selection
+            memory_consolidation
+            post_tick_reflection
+          ].freeze
+
+          # Phases for dream cycle (dormant_active mode)
+          DREAM_PHASES = %i[
+            memory_audit
+            association_walk
+            contradiction_resolution
+            identity_entropy_check
+            agenda_formation
+            consolidation_commit
+            dream_reflection
+            dream_narration
+          ].freeze
+
+          # Which phases run in each mode
+          MODE_PHASES = {
+            dormant:        %i[memory_consolidation],
+            dormant_active: DREAM_PHASES,
+            sentinel:       %i[sensory_processing emotional_evaluation memory_retrieval prediction_engine memory_consolidation],
+            full_active:    PHASES
+          }.freeze
+
+          # Timing constants (in seconds)
+          ACTIVE_TIMEOUT                = 300    # seconds without high-salience signal before demotion
+          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
+          MAX_TICK_DURATION             = 5.0    # hard ceiling for full active 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_BUDGETS = {
+            sensory_processing:         0.15,
+            emotional_evaluation:       0.10,
+            memory_retrieval:           0.20,
+            identity_entropy_check:     0.05,
+            working_memory_integration: 0.05,
+            procedural_check:           0.10,
+            prediction_engine:          0.15,
+            mesh_interface:             0.05,
+            gut_instinct:               0.05,
+            action_selection:           0.05,
+            memory_consolidation:       0.05,
+            post_tick_reflection:       0.05
+          }.freeze
+
+          # Salience thresholds for mode transitions
+          HIGH_SALIENCE_THRESHOLD = 0.7
+          EMERGENCY_TRIGGERS = %i[firmware_violation extinction_protocol].freeze
+
+          module_function
+
+          def phases_for_mode(mode)
+            MODE_PHASES.fetch(mode, PHASES)
+          end
+
+          def tick_budget(mode)
+            case mode
+            when :dormant        then DORMANT_TICK_BUDGET
+            when :dormant_active then Float::INFINITY
+            when :sentinel       then SENTINEL_TICK_BUDGET
+            else                      MAX_TICK_DURATION
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Tick
+      module Helpers
+        class State
+          attr_reader :mode, :tick_count, :last_signal_at, :last_high_salience_at,
+                      :phase_results, :current_phase, :mode_history
+
+          def initialize(mode: :dormant)
+            @mode = mode
+            @tick_count = 0
+            @last_signal_at = nil
+            @last_high_salience_at = nil
+            @phase_results = {}
+            @current_phase = nil
+            @mode_history = [{ mode: mode, at: Time.now.utc }]
+          end
+
+          def record_signal(salience: 0.0)
+            @last_signal_at = Time.now.utc
+            @last_high_salience_at = Time.now.utc if salience >= Constants::HIGH_SALIENCE_THRESHOLD
+          end
+
+          def record_phase(phase, result)
+            @current_phase = phase
+            @phase_results[phase] = result
+          end
+
+          def increment_tick
+            @tick_count += 1
+            @phase_results = {}
+            @current_phase = nil
+          end
+
+          def transition_to(new_mode)
+            return if new_mode == @mode
+
+            @mode = new_mode
+            @mode_history << { mode: new_mode, at: Time.now.utc }
+            @mode_history.shift while @mode_history.size > 50
+          end
+
+          def seconds_since_signal
+            return Float::INFINITY unless @last_signal_at
+
+            Time.now.utc - @last_signal_at
+          end
+
+          def seconds_since_high_salience
+            return Float::INFINITY unless @last_high_salience_at
+
+            Time.now.utc - @last_high_salience_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
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Tick
+      module Runners
+        module Orchestrator
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def execute_tick(signals: [], phase_handlers: {}, **)
+            state = tick_state
+            state.increment_tick
+
+            max_salience = signals.map { |s| s.is_a?(Hash) ? (s[:salience] || 0.0) : 0.0 }.max || 0.0
+            state.record_signal(salience: max_salience) unless signals.empty?
+
+            Legion::Logging.debug "[tick] ##{state.tick_count} starting | mode=#{state.mode} signals=#{signals.size} max_salience=#{max_salience.round(2)}"
+
+            transition = evaluate_mode_transition(signals: signals)
+            if transition[:transitioned]
+              Legion::Logging.info "[tick] mode transition: #{transition[:previous_mode]} -> #{transition[:new_mode]} (#{transition[:reason]})"
+            end
+
+            phases = Helpers::Constants.phases_for_mode(state.mode)
+            budget = Helpers::Constants.tick_budget(state.mode)
+            start_time = Time.now.utc
+            ctx = { budget: budget, start_time: start_time, phase_handlers: phase_handlers, signals: signals }
+            results = run_phases(phases, state, ctx)
+
+            total_elapsed = Time.now.utc - start_time
+            skipped = phases - results.keys
+            log_tick_complete(state, results, phases, total_elapsed, skipped)
+
+            {
+              tick_number:     state.tick_count,
+              mode:            state.mode,
+              phases_executed: results.keys,
+              phases_skipped:  skipped,
+              results:         results,
+              elapsed:         total_elapsed
+            }
+          end
+
+          def evaluate_mode_transition(signals: [], emergency: nil, dream_complete: false, **) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+            state = tick_state
+            previous_mode = state.mode
+
+            # Emergency promotion
+            if emergency && Helpers::Constants::EMERGENCY_TRIGGERS.include?(emergency)
+              Legion::Logging.warn "[tick] emergency promotion triggered: #{emergency}"
+              state.transition_to(:full_active)
+              return { transitioned: true, new_mode: :full_active, previous_mode: previous_mode, reason: :emergency }
+            end
+
+            # Check signal-based promotions
+            max_salience = signals.map { |s| s.is_a?(Hash) ? (s[:salience] || 0.0) : 0.0 }.max || 0.0
+            has_human = signals.any? { |s| s.is_a?(Hash) && s[:source_type] == :human_direct }
+
+            new_mode = case state.mode
+                       when :dormant
+                         if signals.any?
+                           :sentinel
+                         elsif state.seconds_since_signal >= Helpers::Constants::DREAM_IDLE_THRESHOLD
+                           :dormant_active
+                         else
+                           :dormant
+                         end
+                       when :dormant_active
+                         if max_salience >= Helpers::Constants::HIGH_SALIENCE_THRESHOLD || has_human
+                           :sentinel
+                         elsif dream_complete
+                           :dormant
+                         else
+                           :dormant_active
+                         end
+                       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
+                         else
+                           :sentinel
+                         end
+                       when :full_active
+                         if state.seconds_since_high_salience >= Helpers::Constants::ACTIVE_TIMEOUT
+                           :sentinel
+                         else
+                           :full_active
+                         end
+                       end
+
+            if new_mode == state.mode
+              { transitioned: false, current_mode: state.mode }
+            else
+              state.transition_to(new_mode)
+              Legion::Logging.info "[tick] mode transition: #{previous_mode} -> #{new_mode} (threshold)"
+              { transitioned: true, new_mode: new_mode, previous_mode: previous_mode, reason: :threshold }
+            end
+          end
+
+          def tick_status(**)
+            status = tick_state.to_h
+            Legion::Logging.debug "[tick] status query: mode=#{status[:mode]} tick_count=#{status[:tick_count]}"
+            status
+          end
+
+          def set_mode(mode:, **)
+            unless Helpers::Constants::MODES.include?(mode)
+              Legion::Logging.warn "[tick] invalid mode requested: #{mode}"
+              return { error: :invalid_mode, valid_modes: Helpers::Constants::MODES }
+            end
+
+            previous = tick_state.mode
+            tick_state.transition_to(mode)
+            Legion::Logging.info "[tick] mode forced: #{previous} -> #{mode}"
+            { mode: mode }
+          end
+
+          private
+
+          def run_phases(phases, state, ctx)
+            results = {}
+            budget = ctx[:budget]
+            start_time = ctx[:start_time]
+            Legion::Logging.debug "[tick] ##{state.tick_count} running #{phases.size} phases with #{budget}s budget"
+            phases.each do |phase|
+              elapsed = Time.now.utc - start_time
+              if elapsed >= budget
+                Legion::Logging.debug "[tick] ##{state.tick_count} budget exhausted at #{elapsed.round(3)}s, skipping remaining phases"
+                break
+              end
+
+              result = run_single_phase(phase, ctx[:phase_handlers][phase], state, ctx[:signals], results)
+              state.record_phase(phase, result)
+              results[phase] = result
+            end
+            results
+          end
+
+          def run_single_phase(phase, handler, state, signals, results)
+            phase_start = Time.now.utc
+            result = handler ? handler.call(state: state, signals: signals, prior_results: results) : { status: :no_handler }
+            phase_elapsed = ((Time.now.utc - phase_start) * 1000).round(1)
+            status = result.is_a?(Hash) ? (result[:status] || :ok) : :ok
+            Legion::Logging.debug "[tick] ##{state.tick_count} phase=#{phase} status=#{status} (#{phase_elapsed}ms)"
+            result
+          end
+
+          def log_tick_complete(state, results, phases, total_elapsed, skipped)
+            skipped_suffix = skipped.empty? ? '' : " skipped=#{skipped}"
+            Legion::Logging.info "[tick] ##{state.tick_count} complete | mode=#{state.mode} " \
+                                 "phases=#{results.size}/#{phases.size} " \
+                                 "elapsed=#{(total_elapsed * 1000).round(1)}ms#{skipped_suffix}"
+          end
+
+          def tick_state
+            @tick_state ||= Helpers::State.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/tick.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/tick/version'
+require 'legion/extensions/tick/helpers/constants'
+require 'legion/extensions/tick/helpers/state'
+require 'legion/extensions/tick/runners/orchestrator'
+
+module Legion
+  module Extensions
+    module Tick
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

data/spec/legion/extensions/tick/actors/tick_spec.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+# Stub the framework actor base class since legionio gem is not available in test
+module Legion
+  module Extensions
+    module Actors
+      class Every # rubocop:disable Lint/EmptyClass
+      end
+    end
+  end
+end
+
+# Intercept the require in the actor file so it doesn't fail
+$LOADED_FEATURES << 'legion/extensions/actors/every'
+
+require 'legion/extensions/tick/actors/tick'
+
+RSpec.describe Legion::Extensions::Tick::Actor::Tick do
+  subject(:actor) { described_class.new }
+
+  describe '#initialize' do
+    context 'when Cortex is NOT defined' do
+      before { hide_const('Legion::Extensions::Cortex') }
+
+      it 'instantiates without error' do
+        expect { described_class.new }.not_to raise_error
+      end
+    end
+
+    context 'when Cortex IS defined' do
+      before { stub_const('Legion::Extensions::Cortex', Module.new) }
+
+      it 'instantiates without error (returns early, skips super)' do
+        expect { described_class.new }.not_to raise_error
+      end
+    end
+  end
+
+  describe '#enabled?' do
+    context 'when Cortex is NOT defined' do
+      before { hide_const('Legion::Extensions::Cortex') }
+
+      it 'returns truthy' do
+        expect(actor.enabled?).to be_truthy
+      end
+    end
+
+    context 'when Cortex IS defined' do
+      before { stub_const('Legion::Extensions::Cortex', Module.new) }
+
+      it 'returns falsey' do
+        expect(actor.enabled?).to be_falsey
+      end
+    end
+  end
+
+  describe '#runner_class' do
+    it 'returns the Orchestrator module' do
+      expect(actor.runner_class).to eq(Legion::Extensions::Tick::Runners::Orchestrator)
+    end
+  end
+
+  describe '#runner_function' do
+    it 'returns execute_tick' do
+      expect(actor.runner_function).to eq('execute_tick')
+    end
+  end
+
+  describe '#time' do
+    it 'returns 1' do
+      expect(actor.time).to eq(1)
+    end
+  end
+
+  describe '#run_now?' do
+    it 'returns true' do
+      expect(actor.run_now?).to be true
+    end
+  end
+
+  describe '#use_runner?' do
+    it 'returns false' do
+      expect(actor.use_runner?).to be false
+    end
+  end
+
+  describe '#check_subtask?' do
+    it 'returns false' do
+      expect(actor.check_subtask?).to be false
+    end
+  end
+
+  describe '#generate_task?' do
+    it 'returns false' do
+      expect(actor.generate_task?).to be false
+    end
+  end
+
+  describe '#args' do
+    it 'returns a hash with empty signals and phase_handlers' do
+      expect(actor.args).to eq({ signals: [], phase_handlers: {} })
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/tick/client'
+
+RSpec.describe Legion::Extensions::Tick::Client do
+  it 'responds to orchestrator methods' do
+    client = described_class.new
+    expect(client).to respond_to(:execute_tick)
+    expect(client).to respond_to(:evaluate_mode_transition)
+    expect(client).to respond_to(:tick_status)
+    expect(client).to respond_to(:set_mode)
+  end
+
+  it 'accepts initial mode' do
+    client = described_class.new(mode: :sentinel)
+    expect(client.tick_status[:mode]).to eq(:sentinel)
+  end
+
+  it 'runs a full active tick with all 12 phases' do
+    client = described_class.new(mode: :full_active)
+    result = client.execute_tick(signals: [{ salience: 0.9, source_type: :human_direct }])
+    expect(result[:phases_executed].size).to eq(12)
+  end
+end

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

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Tick::Helpers::Constants do
+  describe '.phases_for_mode' do
+    it 'returns 1 phase for dormant' do
+      phases = described_class.phases_for_mode(:dormant)
+      expect(phases).to eq([:memory_consolidation])
+    end
+
+    it 'returns 5 phases for sentinel' do
+      phases = described_class.phases_for_mode(:sentinel)
+      expect(phases.size).to eq(5)
+      expect(phases).to include(:sensory_processing, :memory_retrieval)
+    end
+
+    it 'returns all 12 phases for full_active' do
+      phases = described_class.phases_for_mode(:full_active)
+      expect(phases.size).to eq(12)
+    end
+  end
+
+  describe '.tick_budget' do
+    it 'returns 0.2s for dormant' do
+      expect(described_class.tick_budget(:dormant)).to eq(0.2)
+    end
+
+    it 'returns 0.5s for sentinel' do
+      expect(described_class.tick_budget(:sentinel)).to eq(0.5)
+    end
+
+    it 'returns 5.0s for full_active' do
+      expect(described_class.tick_budget(:full_active)).to eq(5.0)
+    end
+  end
+
+  it 'defines exactly 12 phases' do
+    expect(described_class::PHASES.size).to eq(12)
+  end
+
+  it 'defines phase budgets for all active phases' do
+    described_class::PHASES.each do |phase|
+      expect(described_class::PHASE_BUDGETS).to have_key(phase)
+    end
+  end
+
+  describe 'MODES' do
+    it 'includes dormant_active' do
+      expect(described_class::MODES).to include(:dormant_active)
+    end
+
+    it 'has exactly 4 modes' do
+      expect(described_class::MODES.size).to eq(4)
+    end
+  end
+
+  describe 'DREAM_PHASES' do
+    it 'defines 8 dream phases' do
+      expect(described_class::DREAM_PHASES.size).to eq(8)
+    end
+
+    it 'includes all expected dream phase symbols' do
+      expected = %i[memory_audit association_walk contradiction_resolution
+                    identity_entropy_check agenda_formation consolidation_commit
+                    dream_reflection dream_narration]
+      expect(described_class::DREAM_PHASES).to eq(expected)
+    end
+  end
+
+  describe 'MODE_PHASES' do
+    it 'maps dormant_active to the 8 dream phases' do
+      expect(described_class::MODE_PHASES[:dormant_active]).to eq(described_class::DREAM_PHASES)
+    end
+  end
+
+  describe '.tick_budget' do
+    it 'returns Float::INFINITY for dormant_active' do
+      expect(described_class.tick_budget(:dormant_active)).to eq(Float::INFINITY)
+    end
+  end
+
+  describe 'dream thresholds' do
+    it 'defines DREAM_IDLE_THRESHOLD as 1800' do
+      expect(described_class::DREAM_IDLE_THRESHOLD).to eq(1800)
+    end
+
+    it 'defines SENTINEL_TO_DREAM_THRESHOLD as 600' do
+      expect(described_class::SENTINEL_TO_DREAM_THRESHOLD).to eq(600)
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Tick::Helpers::State do
+  let(:state) { described_class.new }
+
+  describe '#initialize' do
+    it 'starts in dormant mode' do
+      expect(state.mode).to eq(:dormant)
+    end
+
+    it 'starts with zero tick count' do
+      expect(state.tick_count).to eq(0)
+    end
+  end
+
+  describe '#record_signal' do
+    it 'updates last_signal_at' do
+      state.record_signal
+      expect(state.last_signal_at).not_to be_nil
+    end
+
+    it 'updates last_high_salience_at for high salience signals' do
+      state.record_signal(salience: 0.8)
+      expect(state.last_high_salience_at).not_to be_nil
+    end
+
+    it 'does not update last_high_salience_at for low salience' do
+      state.record_signal(salience: 0.3)
+      expect(state.last_high_salience_at).to be_nil
+    end
+  end
+
+  describe '#increment_tick' do
+    it 'increments the tick count' do
+      state.increment_tick
+      expect(state.tick_count).to eq(1)
+    end
+
+    it 'clears phase results' do
+      state.record_phase(:test, { result: true })
+      state.increment_tick
+      expect(state.phase_results).to be_empty
+    end
+  end
+
+  describe '#transition_to' do
+    it 'changes mode' do
+      state.transition_to(:sentinel)
+      expect(state.mode).to eq(:sentinel)
+    end
+
+    it 'tracks mode history' do
+      state.transition_to(:sentinel)
+      state.transition_to(:full_active)
+      expect(state.mode_history.size).to eq(3) # initial + 2 transitions
+    end
+
+    it 'does not add duplicate entries for same mode' do
+      state.transition_to(:dormant) # already dormant
+      expect(state.mode_history.size).to eq(1)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns state as hash' do
+      h = state.to_h
+      expect(h).to have_key(:mode)
+      expect(h).to have_key(:tick_count)
+      expect(h).to have_key(:phases_completed)
+    end
+  end
+end

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

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/tick/client'
+
+RSpec.describe Legion::Extensions::Tick::Runners::Orchestrator do
+  let(:client) { Legion::Extensions::Tick::Client.new }
+
+  describe '#execute_tick' do
+    before do
+      allow(client.send(:tick_state)).to receive(:seconds_since_signal).and_return(60.0)
+    end
+
+    it 'executes phases for current mode' do
+      result = client.execute_tick
+      expect(result[:mode]).to eq(:dormant)
+      expect(result[:phases_executed]).to include(:memory_consolidation)
+    end
+
+    it 'increments tick number' do
+      r1 = client.execute_tick
+      r2 = client.execute_tick
+      expect(r2[:tick_number]).to eq(r1[:tick_number] + 1)
+    end
+
+    it 'uses phase handlers when provided' do
+      handler_called = false
+      handlers = {
+        memory_consolidation: lambda { |**|
+          handler_called = true
+          { status: :ok }
+        }
+      }
+      client.execute_tick(phase_handlers: handlers)
+      expect(handler_called).to be true
+    end
+
+    it 'reports no_handler for unhandled phases' do
+      result = client.execute_tick
+      expect(result[:results][:memory_consolidation][:status]).to eq(:no_handler)
+    end
+
+    it 'promotes to sentinel on incoming signals' do
+      client.execute_tick(signals: [{ salience: 0.3 }])
+      result = client.execute_tick(signals: [{ salience: 0.3 }])
+      expect(result[:mode]).to eq(:sentinel)
+    end
+  end
+
+  describe '#evaluate_mode_transition' do
+    it 'promotes dormant to sentinel on any signal' do
+      result = client.evaluate_mode_transition(signals: [{ salience: 0.1 }])
+      expect(result[:transitioned]).to be true
+      expect(result[:new_mode]).to eq(:sentinel)
+    end
+
+    it 'promotes sentinel to full_active on high salience' do
+      client.set_mode(mode: :sentinel)
+      result = client.evaluate_mode_transition(signals: [{ salience: 0.9 }])
+      expect(result[:transitioned]).to be true
+      expect(result[:new_mode]).to eq(:full_active)
+    end
+
+    it 'promotes sentinel to full_active on human interaction' do
+      client.set_mode(mode: :sentinel)
+      result = client.evaluate_mode_transition(signals: [{ source_type: :human_direct, salience: 0.3 }])
+      expect(result[:transitioned]).to be true
+      expect(result[:new_mode]).to eq(:full_active)
+    end
+
+    it 'promotes to full_active on emergency' do
+      result = client.evaluate_mode_transition(emergency: :firmware_violation)
+      expect(result[:transitioned]).to be true
+      expect(result[:new_mode]).to eq(:full_active)
+    end
+
+    it 'does not transition without trigger when recently active' do
+      state = client.send(:tick_state)
+      allow(state).to receive(:seconds_since_signal).and_return(60.0)
+      result = client.evaluate_mode_transition
+      expect(result[:transitioned]).to be false
+    end
+
+    context 'dormant_active transitions' do
+      it 'transitions dormant -> dormant_active after DREAM_IDLE_THRESHOLD with no signals' do
+        state = client.send(:tick_state)
+        allow(state).to receive(:seconds_since_signal).and_return(1801.0)
+        result = client.evaluate_mode_transition
+        expect(result[:transitioned]).to be true
+        expect(result[:new_mode]).to eq(:dormant_active)
+      end
+
+      it 'transitions dormant -> sentinel when signals arrive (not dormant_active)' do
+        state = client.send(:tick_state)
+        allow(state).to receive(:seconds_since_signal).and_return(1801.0)
+        result = client.evaluate_mode_transition(signals: [{ salience: 0.3 }])
+        expect(result[:transitioned]).to be true
+        expect(result[:new_mode]).to eq(:sentinel)
+      end
+
+      it 'transitions dormant_active -> sentinel on high-salience signal' do
+        client.set_mode(mode: :dormant_active)
+        result = client.evaluate_mode_transition(signals: [{ salience: 0.9 }])
+        expect(result[:transitioned]).to be true
+        expect(result[:new_mode]).to eq(:sentinel)
+      end
+
+      it 'transitions dormant_active -> dormant when dream_complete: true with no signals' do
+        client.set_mode(mode: :dormant_active)
+        result = client.evaluate_mode_transition(dream_complete: true)
+        expect(result[:transitioned]).to be true
+        expect(result[:new_mode]).to eq(:dormant)
+      end
+
+      it 'stays dormant_active when no signals and dream not complete' do
+        client.set_mode(mode: :dormant_active)
+        result = client.evaluate_mode_transition
+        expect(result[:transitioned]).to be false
+        expect(result[:current_mode]).to eq(:dormant_active)
+      end
+    end
+
+    context 'sentinel -> dormant_active' do
+      it 'transitions sentinel -> dormant_active after SENTINEL_TO_DREAM_THRESHOLD with no signals' do
+        client.set_mode(mode: :sentinel)
+        state = client.send(:tick_state)
+        allow(state).to receive(:seconds_since_signal).and_return(601.0)
+        result = client.evaluate_mode_transition
+        expect(result[:transitioned]).to be true
+        expect(result[:new_mode]).to eq(:dormant_active)
+      end
+    end
+  end
+
+  describe '#set_mode' do
+    it 'sets valid mode' do
+      result = client.set_mode(mode: :full_active)
+      expect(result[:mode]).to eq(:full_active)
+    end
+
+    it 'rejects invalid mode' do
+      result = client.set_mode(mode: :invalid)
+      expect(result[:error]).to eq(:invalid_mode)
+    end
+  end
+
+  describe '#tick_status' do
+    it 'returns current state' do
+      status = client.tick_status
+      expect(status[:mode]).to eq(:dormant)
+      expect(status[:tick_count]).to eq(0)
+    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/tick'
+
+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,76 @@
+--- !ruby/object:Gem::Specification
+name: lex-tick
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Esity
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: legion-gaia
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Atomic cognitive processing cycle (11 phases, 3 modes) for brain-modeled
+  agentic AI
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- lex-tick.gemspec
+- lib/legion/extensions/tick.rb
+- lib/legion/extensions/tick/actors/tick.rb
+- lib/legion/extensions/tick/client.rb
+- lib/legion/extensions/tick/helpers/constants.rb
+- lib/legion/extensions/tick/helpers/state.rb
+- lib/legion/extensions/tick/runners/orchestrator.rb
+- lib/legion/extensions/tick/version.rb
+- spec/legion/extensions/tick/actors/tick_spec.rb
+- spec/legion/extensions/tick/client_spec.rb
+- spec/legion/extensions/tick/helpers/constants_spec.rb
+- spec/legion/extensions/tick/helpers/state_spec.rb
+- spec/legion/extensions/tick/runners/orchestrator_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-tick
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-tick
+  source_code_uri: https://github.com/LegionIO/lex-tick
+  documentation_uri: https://github.com/LegionIO/lex-tick
+  changelog_uri: https://github.com/LegionIO/lex-tick
+  bug_tracker_uri: https://github.com/LegionIO/lex-tick/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 Tick
+test_files: []