lex-tick

Atomic cognitive processing cycle for brain-modeled agentic AI. Implements 16 default active phases, 4 operating modes, mode transitions, and explicitly enabled optional work.

lex-tick schedules bounded cognitive phase handlers and returns their results. Request/event processing and extension-owned background maintenance remain outside the tick; loading a handler does not schedule it.

The agent operates in one of four modes at any time:

Mode transitions are driven by signal salience thresholds and time-since-signal:

• Low-salience non-human signal: dormant -> sentinel
• High salience (>= 0.7) or human direct input: dormant, dormant_active, or sentinel -> full_active on that interaction
• No high-salience or human signal for 300s: full_active -> sentinel; an empty heartbeat alone does not demote
• No signal for 600s while sentinel and dream backoff elapsed: sentinel -> dormant_active (dream cycle)
• No signal for 3600s while sentinel: sentinel -> dormant
• No signal for 1800s while dormant and dream backoff elapsed: dormant -> dormant_active (dream cycle)
• Finished or deferred dream cycle: dormant_active -> dormant, with backoff before another dream cycle
• Emergency trigger (:firmware_violation, :extinction_protocol): immediate full_active

1. sensory_processing (12% budget)
2. emotional_evaluation (8%)
3. memory_retrieval (12%)
4. knowledge_retrieval (5%)
5. identity_entropy_check (4%)
6. working_memory_integration (5%)
7. procedural_check (8%)
8. prediction_engine (12%)
9. mesh_interface (4%)
10. social_cognition (4%)
11. theory_of_mind (4%)
12. gut_instinct (4%)
13. action_selection (4%)
14. memory_consolidation (4%)
15. homeostasis_regulation (5%)
16. post_tick_reflection (5%)

Phase budgets are informational — enforcement is at the tick level, not per-phase. Execution budgets use a monotonic clock and stop starting phases once the mode's budget is exhausted; an already-running handler is not forcibly interrupted. Corrected promotion runs the existing 16-phase, 5-second-budget active schedule instead of the 5-phase sentinel schedule for the first human interaction. Optional work shares that budget and is disabled by default.

1. memory_audit
2. association_walk
3. contradiction_resolution
4. identity_entropy_check
5. agenda_formation
6. consolidation_commit
7. knowledge_promotion
8. dream_reflection
9. partner_reflection
10. dream_narration

Version 0.1.18 adds execute_tick(enabled_optional_phases: []). Existing callers retain exactly their existing schedules, even if they supply additional handlers. Only these opt-ins are supported:

result = client.execute_tick(
  signals: signals,
  phase_handlers: handlers,
  enabled_optional_phases: %i[global_workspace metacognition]
)

Unknown names or a non-array opt-in raise ArgumentError before tick state advances. Repeated names run once. An opt-in does not override the operating mode. Missing optional handlers return status: :unavailable; failed, missing, or deferred prerequisite results return status: :deferred without invoking the dependent handler. The caller remains responsible for domain readiness: submit real candidates to the same workspace that competes, consume its result, and do not supply fabricated claim, belief, or intention IDs.

phases_scheduled is the selected schedule, phases_executed contains the visited phases (including unavailable/no-handler results), and phases_skipped contains phases not visited because the shared tick budget expired. Inspect each phase's result status rather than treating a visited phase as completed work.

The other currently unscheduled GAIA mappings are deliberately not tick opt-ins:

Consumers must require 0.1.18 or verify the explicit keyword before opting in. Older versions accept arbitrary context keywords and would silently ignore it.

Add to your Gemfile:

gem 'lex-tick'

require 'legion/extensions/tick'

client = Legion::Extensions::Tick::Client.new

# Execute a tick with signals and phase handlers
result = client.execute_tick(
  signals: [{ salience: 0.8, source_type: :human_direct, content: "Hello" }],
  phase_handlers: {
    sensory_processing: ->(state:, signals:, prior_results:) {
      { processed: signals.size }
    },
    action_selection: ->(state:, signals:, prior_results:) {
      { action: :respond }
    }
  }
)

# Result shape
result[:mode]            # => :full_active
result[:tick_number]     # => 1
result[:phases_executed] # => [:sensory_processing, ..., :post_tick_reflection]
result[:elapsed]         # => 0.001

# Check/set mode
client.tick_status
client.set_mode(mode: :sentinel)
# set_mode is sticky for one tick — automatic mode evaluation is skipped on the next execute_tick call

# Force mode transition for emergency
client.evaluate_mode_transition(
  emergency: :firmware_violation
)

The State object (Helpers::State) persists across ticks and tracks:

• mode - current operating mode
• tick_count - total ticks executed
• last_signal_at / last_high_salience_at - timestamps driving mode decay
• last_dream_completed_at - most recent fully successful dream cycle
• last_dream_deferred_at - most recent incomplete, failed, unhandled, or interrupted dream; both timestamps enforce dream backoff
• phase_results - results from the current tick's phases
• mode_history - last 50 mode transitions with timestamps

bundle install
bundle exec rspec
bundle exec rubocop

MIT