lex-imagination 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 796ec9d97b9cc1782cf232c968efd46f14dcdc7612b4f1122368071729c86bd4
+  data.tar.gz: ac83b7c6f4aa92c5017bfed3afd2ef19a193f11054a84f726faffd27d94b159f
+SHA512:
+  metadata.gz: 8a0f5965a249e2eee28d411d9d03755bf38c70cc5194ca3ae6c88eeb6d30b7f3b012c63112f11307b4e3b054da20f4fc1aa132d61f92308389641ea8a499e3bf
+  data.tar.gz: 79402cb3ff9b14aa04bcd3b15f3ccaa6217c2aacdae953e8c26f9894daa133b2aecd5ef0197b7a907c9218cf891a2143d13fcabbfa836360cd25dc1ee1512ae1

data/Gemfile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+group :dev, :test do
+  gem 'rspec', '~> 3.12'
+  gem 'rubocop', '~> 1.75'
+  gem 'rubocop-rspec', '~> 3.0'
+end
+
+gem 'legion-gaia', path: '../../legion-gaia'

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,82 @@
+# lex-imagination
+
+Counterfactual simulation and mental rehearsal for LegionIO agents. Part of the LegionIO cognitive architecture extension ecosystem (LEX).
+
+## What It Does
+
+`lex-imagination` lets an agent mentally rehearse actions before committing to them. Given a list of candidate actions, it builds scenarios with success, failure, and wildcard outcomes, evaluates each via a weighted composite score (expected value, risk, reversibility, novelty, alignment), and returns a ranked recommendation. Deep what-if chains trace consequences recursively. Actual outcomes can be recorded to track simulation accuracy over time.
+
+Key capabilities:
+
+- **Multi-scenario simulation**: evaluate up to 5 candidate actions per call
+- **Composite scoring**: expected value (35%), risk (25%), reversibility (20%), novelty (10%), alignment (10%)
+- **Recursive what-if chains**: trace consequences up to depth 3
+- **Head-to-head comparison**: compare two actions directly
+- **Outcome tracking**: record actual results to measure simulation accuracy
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'lex-imagination'
+```
+
+Or install directly:
+
+```
+gem install lex-imagination
+```
+
+## Usage
+
+```ruby
+require 'legion/extensions/imagination'
+
+client = Legion::Extensions::Imagination::Client.new
+
+# Simulate candidate actions
+result = client.simulate(
+  actions: ['deploy_hotfix', 'wait_for_review', 'rollback'],
+  context: { familiar: true, alignment: 0.8, risky: false },
+  risk_tolerance: :moderate
+)
+# => { recommendation: { action: 'deploy_hotfix', composite: 0.72, confidence: :high },
+#      scenarios: [...], simulation_id: "..." }
+
+# Deep what-if analysis
+chain = client.what_if(action: 'merge_without_tests', context: { risky: true }, depth: 3)
+# => { consequence_chain: [...], overall_valence: :negative_trajectory }
+
+# Compare two options
+comparison = client.compare(action_a: 'refactor_first', action_b: 'ship_now', context: {})
+# => { winner: :a, margin: 0.15, decisive: true }
+
+# Record what actually happened
+client.record_actual_outcome(simulation_id: result[:simulation_id], actual_outcome: :success)
+
+# Stats
+client.imagination_stats
+```
+
+## Runner Methods
+
+| Method | Description |
+|---|---|
+| `simulate` | Build and rank scenarios for a list of candidate actions |
+| `what_if` | Recursive consequence chain for a single action |
+| `compare` | Head-to-head composite score comparison of two actions |
+| `record_actual_outcome` | Log actual result for accuracy tracking |
+| `imagination_stats` | Total simulations, accuracy, avg composite |
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-imagination.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/imagination/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-imagination'
+  spec.version       = Legion::Extensions::Imagination::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Imagination'
+  spec.description   = 'Counterfactual simulation engine — mental rehearsal of actions before committing'
+  spec.homepage      = 'https://github.com/LegionIO/lex-imagination'
+  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-imagination'
+  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-imagination'
+  spec.metadata['changelog_uri'] = 'https://github.com/LegionIO/lex-imagination'
+  spec.metadata['bug_tracker_uri'] = 'https://github.com/LegionIO/lex-imagination/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-imagination.gemspec Gemfile LICENSE README.md]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Imagination
+      class Client
+        include Runners::Imagination
+
+        attr_reader :simulation_store
+
+        def initialize(simulation_store: nil, **)
+          @simulation_store = simulation_store || Helpers::SimulationStore.new
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Imagination
+      module Helpers
+        module Constants
+          # Maximum scenarios per simulation
+          MAX_SCENARIOS = 5
+
+          # Maximum simulation depth (chained consequence steps)
+          MAX_DEPTH = 3
+
+          # Simulation history capacity
+          MAX_SIMULATIONS = 100
+
+          # Confidence thresholds
+          HIGH_CONFIDENCE   = 0.7
+          MEDIUM_CONFIDENCE = 0.4
+          LOW_CONFIDENCE    = 0.2
+
+          # Outcome valence labels
+          OUTCOME_VALENCES = %i[very_positive positive neutral negative very_negative].freeze
+
+          # Risk tolerance levels
+          RISK_TOLERANCES = %i[conservative moderate aggressive].freeze
+
+          # Default evaluation weights
+          EVALUATION_WEIGHTS = {
+            expected_value: 0.3,
+            risk:           0.25,
+            reversibility:  0.2,
+            alignment:      0.15,
+            novelty:        0.1
+          }.freeze
+
+          # Scenario outcome types
+          OUTCOME_TYPES = %i[success partial_success neutral partial_failure failure wildcard].freeze
+
+          # Imagination modes
+          MODES = %i[
+            prospective
+            retrospective
+            counterfactual
+            exploratory
+          ].freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/imagination/helpers/scenario.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Imagination
+      module Helpers
+        class Scenario
+          attr_reader :scenario_id, :action, :context, :outcomes, :evaluation, :created_at
+
+          def initialize(action:, context: {})
+            @scenario_id = SecureRandom.uuid
+            @action = action
+            @context = context
+            @outcomes = []
+            @evaluation = nil
+            @created_at = Time.now.utc
+          end
+
+          def add_outcome(outcome)
+            @outcomes << {
+              outcome_id:   SecureRandom.uuid,
+              type:         outcome[:type] || :neutral,
+              likelihood:   (outcome[:likelihood] || 0.5).clamp(0.0, 1.0),
+              valence:      classify_valence(outcome[:value] || 0.0),
+              value:        (outcome[:value] || 0.0).clamp(-1.0, 1.0),
+              description:  outcome[:description],
+              consequences: outcome[:consequences] || [],
+              reversible:   outcome.fetch(:reversible, true)
+            }
+          end
+
+          def expected_value
+            return 0.0 if @outcomes.empty?
+
+            @outcomes.sum { |o| o[:likelihood] * o[:value] }
+          end
+
+          def risk_score
+            return 0.0 if @outcomes.empty?
+
+            negative_outcomes = @outcomes.select { |o| o[:value].negative? }
+            return 0.0 if negative_outcomes.empty?
+
+            negative_outcomes.sum { |o| o[:likelihood] * o[:value].abs }
+          end
+
+          def best_outcome
+            @outcomes.max_by { |o| o[:value] }
+          end
+
+          def worst_outcome
+            @outcomes.min_by { |o| o[:value] }
+          end
+
+          def reversibility
+            return 1.0 if @outcomes.empty?
+
+            reversible_count = @outcomes.count { |o| o[:reversible] }
+            reversible_count.to_f / @outcomes.size
+          end
+
+          def evaluate(weights: Constants::EVALUATION_WEIGHTS, alignment: 0.5, novelty: 0.5)
+            @evaluation = {
+              expected_value: expected_value,
+              risk:           risk_score,
+              reversibility:  reversibility,
+              alignment:      alignment,
+              novelty:        novelty,
+              composite:      compute_composite(weights, alignment, novelty),
+              evaluated_at:   Time.now.utc
+            }
+          end
+
+          def to_h
+            {
+              scenario_id:    @scenario_id,
+              action:         @action,
+              context:        @context,
+              outcomes:       @outcomes,
+              expected_value: expected_value,
+              risk_score:     risk_score,
+              reversibility:  reversibility,
+              evaluation:     @evaluation,
+              created_at:     @created_at
+            }
+          end
+
+          private
+
+          def classify_valence(value)
+            if value > 0.5
+              :very_positive
+            elsif value > 0.1
+              :positive
+            elsif value > -0.1
+              :neutral
+            elsif value > -0.5
+              :negative
+            else
+              :very_negative
+            end
+          end
+
+          def compute_composite(weights, alignment, novelty)
+            ev_score = (expected_value + 1.0) / 2.0
+            risk_penalty = 1.0 - risk_score
+            rev_score = reversibility
+
+            (weights[:expected_value] * ev_score) +
+              (weights[:risk] * risk_penalty) +
+              (weights[:reversibility] * rev_score) +
+              (weights[:alignment] * alignment) +
+              (weights[:novelty] * novelty)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/imagination/helpers/simulation_store.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Imagination
+      module Helpers
+        class SimulationStore
+          attr_reader :simulations
+
+          def initialize
+            @simulations = []
+          end
+
+          def store(simulation)
+            @simulations << simulation
+            @simulations = @simulations.last(Constants::MAX_SIMULATIONS)
+            simulation
+          end
+
+          def get(simulation_id)
+            @simulations.find { |s| s[:simulation_id] == simulation_id }
+          end
+
+          def recent(limit: 10)
+            @simulations.last(limit)
+          end
+
+          def by_mode(mode)
+            @simulations.select { |s| s[:mode] == mode }
+          end
+
+          def best_decisions
+            @simulations.select { |s| s[:recommendation] }
+                        .sort_by { |s| -(s.dig(:recommendation, :composite) || 0) }
+          end
+
+          def accuracy_check(simulation_id, actual_outcome:)
+            sim = get(simulation_id)
+            return nil unless sim
+
+            sim[:actual_outcome] = actual_outcome
+            sim[:accurate] = outcome_matches?(sim, actual_outcome)
+            sim[:accurate]
+          end
+
+          def simulation_accuracy
+            checked = @simulations.select { |s| s.key?(:accurate) }
+            return nil if checked.empty?
+
+            correct = checked.count { |s| s[:accurate] }
+            correct.to_f / checked.size
+          end
+
+          def size
+            @simulations.size
+          end
+
+          def clear
+            @simulations.clear
+          end
+
+          private
+
+          def outcome_matches?(simulation, actual)
+            recommended = simulation.dig(:recommendation, :action)
+            return false unless recommended
+
+            actual_valence = actual[:valence] || :neutral
+            positive_outcomes = %i[very_positive positive]
+            positive_outcomes.include?(actual_valence)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Imagination
+      module Runners
+        module Imagination
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def simulate(actions:, context: {}, mode: :prospective, risk_tolerance: :moderate, **)
+            scenarios = actions.first(Helpers::Constants::MAX_SCENARIOS).map do |action|
+              build_scenario(action, context)
+            end
+
+            scenarios.each { |s| s.evaluate(alignment: context[:alignment] || 0.5, novelty: context[:novelty] || 0.5) }
+
+            ranked = rank_scenarios(scenarios, risk_tolerance)
+            recommendation = ranked.first
+
+            simulation = {
+              simulation_id:  SecureRandom.uuid,
+              mode:           mode.to_sym,
+              scenarios:      scenarios.map(&:to_h),
+              recommendation: recommendation ? format_recommendation(recommendation) : nil,
+              risk_tolerance: risk_tolerance,
+              simulated_at:   Time.now.utc
+            }
+
+            simulation_store.store(simulation)
+
+            Legion::Logging.debug "[imagination] simulated #{scenarios.size} scenarios, " \
+                                  "recommended=#{recommendation&.action || 'none'}"
+
+            simulation
+          end
+
+          def what_if(action:, context: {}, depth: 1, **)
+            actual_depth = [depth, Helpers::Constants::MAX_DEPTH].min
+            scenario = build_scenario(action, context)
+            chain = build_consequence_chain(scenario, actual_depth)
+            scenario.evaluate
+
+            Legion::Logging.debug "[imagination] what_if: action=#{action} depth=#{actual_depth} " \
+                                  "ev=#{scenario.expected_value.round(2)}"
+
+            {
+              scenario:          scenario.to_h,
+              consequence_chain: chain,
+              depth:             actual_depth,
+              overall_valence:   classify_chain_valence(chain)
+            }
+          end
+
+          def compare(action_a:, action_b:, context: {}, **)
+            scenario_a = build_scenario(action_a, context)
+            scenario_b = build_scenario(action_b, context)
+            scenario_a.evaluate
+            scenario_b.evaluate
+
+            winner = scenario_a.evaluation[:composite] >= scenario_b.evaluation[:composite] ? :a : :b
+            margin = (scenario_a.evaluation[:composite] - scenario_b.evaluation[:composite]).abs
+
+            Legion::Logging.debug "[imagination] compare: #{action_a} vs #{action_b} -> winner=#{winner} margin=#{margin.round(3)}"
+
+            {
+              scenario_a: scenario_a.to_h,
+              scenario_b: scenario_b.to_h,
+              winner:     winner,
+              margin:     margin,
+              decisive:   margin > 0.1
+            }
+          end
+
+          def record_actual_outcome(simulation_id:, actual_outcome: {}, **)
+            result = simulation_store.accuracy_check(simulation_id, actual_outcome: actual_outcome)
+            if result.nil?
+              { error: :not_found }
+            else
+              Legion::Logging.info "[imagination] outcome recorded: simulation=#{simulation_id} accurate=#{result}"
+              { simulation_id: simulation_id, accurate: result, overall_accuracy: simulation_store.simulation_accuracy }
+            end
+          end
+
+          def imagination_stats(**)
+            {
+              total_simulations: simulation_store.size,
+              accuracy:          simulation_store.simulation_accuracy,
+              by_mode:           mode_distribution,
+              recent_count:      simulation_store.recent(limit: 10).size
+            }
+          end
+
+          private
+
+          def simulation_store
+            @simulation_store ||= Helpers::SimulationStore.new
+          end
+
+          def build_scenario(action, context)
+            scenario = Helpers::Scenario.new(action: action, context: context)
+
+            scenario.add_outcome(type: :success, likelihood: estimate_success_likelihood(action, context),
+                                 value: estimate_positive_value(context), description: "#{action} succeeds",
+                                 reversible: true)
+
+            scenario.add_outcome(type: :failure, likelihood: estimate_failure_likelihood(action, context),
+                                 value: estimate_negative_value(context), description: "#{action} fails",
+                                 reversible: context.fetch(:reversible, true))
+
+            if context[:wildcard]
+              scenario.add_outcome(type: :wildcard, likelihood: 0.1,
+                                   value: context[:wildcard_value] || 0.0,
+                                   description: context[:wildcard], reversible: true)
+            end
+
+            scenario
+          end
+
+          def estimate_success_likelihood(_action, context)
+            base = 0.5
+            base += 0.1 if context[:familiar]
+            base += 0.1 if context[:alignment].is_a?(Numeric) && context[:alignment] > 0.6
+            base -= 0.1 if context[:risky]
+            base.clamp(0.1, 0.9)
+          end
+
+          def estimate_failure_likelihood(_action, context)
+            1.0 - estimate_success_likelihood(nil, context)
+          end
+
+          def estimate_positive_value(context)
+            (context[:positive_value] || 0.6).clamp(0.0, 1.0)
+          end
+
+          def estimate_negative_value(context)
+            -(context[:negative_value] || 0.4).clamp(0.0, 1.0)
+          end
+
+          def rank_scenarios(scenarios, risk_tolerance)
+            scenarios.sort_by do |s|
+              composite = s.evaluation[:composite]
+              risk_adjust = case risk_tolerance.to_sym
+                            when :conservative then composite - (s.risk_score * 0.3)
+                            when :aggressive   then composite + (s.expected_value * 0.2)
+                            else composite
+                            end
+              -risk_adjust
+            end
+          end
+
+          def format_recommendation(scenario)
+            {
+              action:         scenario.action,
+              composite:      scenario.evaluation[:composite],
+              expected_value: scenario.expected_value,
+              risk:           scenario.risk_score,
+              reversibility:  scenario.reversibility,
+              confidence:     classify_confidence(scenario.evaluation[:composite])
+            }
+          end
+
+          def classify_confidence(composite)
+            if composite >= Helpers::Constants::HIGH_CONFIDENCE
+              :high
+            elsif composite >= Helpers::Constants::MEDIUM_CONFIDENCE
+              :medium
+            else
+              :low
+            end
+          end
+
+          def build_consequence_chain(scenario, depth)
+            chain = [{ depth: 0, expected_value: scenario.expected_value, risk: scenario.risk_score }]
+
+            depth.times do |d|
+              prev = chain.last
+              dampened_ev = prev[:expected_value] * 0.7
+              dampened_risk = prev[:risk] * 0.8
+              chain << { depth: d + 1, expected_value: dampened_ev, risk: dampened_risk }
+            end
+
+            chain
+          end
+
+          def classify_chain_valence(chain)
+            total_ev = chain.sum { |c| c[:expected_value] }
+            if total_ev > 0.3
+              :positive_trajectory
+            elsif total_ev < -0.3
+              :negative_trajectory
+            else
+              :uncertain_trajectory
+            end
+          end
+
+          def mode_distribution
+            dist = Hash.new(0)
+            simulation_store.simulations.each { |s| dist[s[:mode]] += 1 }
+            dist
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/imagination.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'legion/extensions/imagination/version'
+require 'legion/extensions/imagination/helpers/constants'
+require 'legion/extensions/imagination/helpers/scenario'
+require 'legion/extensions/imagination/helpers/simulation_store'
+require 'legion/extensions/imagination/runners/imagination'
+require 'legion/extensions/imagination/client'
+
+module Legion
+  module Extensions
+    module Imagination
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined?(:Core)
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Imagination::Client do
+  it 'creates default simulation store' do
+    client = described_class.new
+    expect(client.simulation_store).to be_a(Legion::Extensions::Imagination::Helpers::SimulationStore)
+  end
+
+  it 'accepts injected simulation store' do
+    store = Legion::Extensions::Imagination::Helpers::SimulationStore.new
+    client = described_class.new(simulation_store: store)
+    expect(client.simulation_store).to equal(store)
+  end
+
+  it 'includes Imagination runner methods' do
+    client = described_class.new
+    expect(client).to respond_to(:simulate, :what_if, :compare,
+                                 :record_actual_outcome, :imagination_stats)
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Imagination::Helpers::Constants do
+  it 'defines 4 imagination modes' do
+    expect(described_class::MODES.size).to eq(4)
+  end
+
+  it 'defines 6 outcome types' do
+    expect(described_class::OUTCOME_TYPES.size).to eq(6)
+  end
+
+  it 'defines 3 risk tolerances' do
+    expect(described_class::RISK_TOLERANCES).to contain_exactly(:conservative, :moderate, :aggressive)
+  end
+
+  it 'defines evaluation weights summing to 1.0' do
+    total = described_class::EVALUATION_WEIGHTS.values.sum
+    expect(total).to be_within(0.001).of(1.0)
+  end
+
+  it 'defines ordered confidence thresholds' do
+    expect(described_class::LOW_CONFIDENCE).to be < described_class::MEDIUM_CONFIDENCE
+    expect(described_class::MEDIUM_CONFIDENCE).to be < described_class::HIGH_CONFIDENCE
+  end
+end

data/spec/legion/extensions/imagination/helpers/scenario_spec.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Imagination::Helpers::Scenario do
+  subject(:scenario) { described_class.new(action: 'deploy', context: { env: :prod }) }
+
+  describe '#initialize' do
+    it 'assigns a UUID' do
+      expect(scenario.scenario_id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores action and context' do
+      expect(scenario.action).to eq('deploy')
+      expect(scenario.context[:env]).to eq(:prod)
+    end
+  end
+
+  describe '#add_outcome' do
+    it 'adds an outcome' do
+      scenario.add_outcome(type: :success, likelihood: 0.7, value: 0.8)
+      expect(scenario.outcomes.size).to eq(1)
+      expect(scenario.outcomes.first[:type]).to eq(:success)
+    end
+
+    it 'clamps likelihood to 0-1' do
+      scenario.add_outcome(likelihood: 1.5, value: 0.5)
+      expect(scenario.outcomes.first[:likelihood]).to eq(1.0)
+    end
+
+    it 'classifies valence' do
+      scenario.add_outcome(value: 0.8)
+      expect(scenario.outcomes.first[:valence]).to eq(:very_positive)
+    end
+  end
+
+  describe '#expected_value' do
+    it 'returns 0 with no outcomes' do
+      expect(scenario.expected_value).to eq(0.0)
+    end
+
+    it 'computes weighted expected value' do
+      scenario.add_outcome(likelihood: 0.7, value: 0.8)
+      scenario.add_outcome(likelihood: 0.3, value: -0.5)
+      ev = scenario.expected_value
+      expect(ev).to be_within(0.001).of((0.7 * 0.8) + (0.3 * -0.5))
+    end
+  end
+
+  describe '#risk_score' do
+    it 'returns 0 with no negative outcomes' do
+      scenario.add_outcome(likelihood: 0.5, value: 0.5)
+      expect(scenario.risk_score).to eq(0.0)
+    end
+
+    it 'computes risk from negative outcomes' do
+      scenario.add_outcome(likelihood: 0.3, value: -0.6)
+      expect(scenario.risk_score).to be_within(0.001).of(0.3 * 0.6)
+    end
+  end
+
+  describe '#best_outcome / #worst_outcome' do
+    before do
+      scenario.add_outcome(value: 0.8, likelihood: 0.5)
+      scenario.add_outcome(value: -0.3, likelihood: 0.5)
+    end
+
+    it 'returns highest value outcome as best' do
+      expect(scenario.best_outcome[:value]).to eq(0.8)
+    end
+
+    it 'returns lowest value outcome as worst' do
+      expect(scenario.worst_outcome[:value]).to eq(-0.3)
+    end
+  end
+
+  describe '#reversibility' do
+    it 'returns 1.0 when all outcomes are reversible' do
+      scenario.add_outcome(value: 0.5, reversible: true)
+      expect(scenario.reversibility).to eq(1.0)
+    end
+
+    it 'returns 0.0 when no outcomes are reversible' do
+      scenario.add_outcome(value: 0.5, reversible: false)
+      expect(scenario.reversibility).to eq(0.0)
+    end
+  end
+
+  describe '#evaluate' do
+    before do
+      scenario.add_outcome(likelihood: 0.7, value: 0.6)
+      scenario.add_outcome(likelihood: 0.3, value: -0.3)
+    end
+
+    it 'produces evaluation hash' do
+      scenario.evaluate
+      expect(scenario.evaluation).to include(:expected_value, :risk, :reversibility, :composite)
+    end
+
+    it 'produces a composite score' do
+      scenario.evaluate
+      expect(scenario.evaluation[:composite]).to be_a(Numeric)
+      expect(scenario.evaluation[:composite]).to be > 0
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns complete scenario hash' do
+      h = scenario.to_h
+      expect(h).to include(:scenario_id, :action, :context, :outcomes, :expected_value)
+    end
+  end
+end

data/spec/legion/extensions/imagination/helpers/simulation_store_spec.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Imagination::Helpers::SimulationStore do
+  subject(:store) { described_class.new }
+
+  let(:simulation) do
+    {
+      simulation_id:  SecureRandom.uuid,
+      mode:           :prospective,
+      scenarios:      [],
+      recommendation: { action: 'deploy', composite: 0.8 },
+      simulated_at:   Time.now.utc
+    }
+  end
+
+  describe '#store' do
+    it 'stores a simulation' do
+      store.store(simulation)
+      expect(store.size).to eq(1)
+    end
+
+    it 'caps at MAX_SIMULATIONS' do
+      (Legion::Extensions::Imagination::Helpers::Constants::MAX_SIMULATIONS + 5).times do |i|
+        store.store(simulation.merge(simulation_id: "sim-#{i}"))
+      end
+      expect(store.size).to eq(Legion::Extensions::Imagination::Helpers::Constants::MAX_SIMULATIONS)
+    end
+  end
+
+  describe '#get' do
+    it 'retrieves by ID' do
+      store.store(simulation)
+      found = store.get(simulation[:simulation_id])
+      expect(found).to eq(simulation)
+    end
+
+    it 'returns nil for missing ID' do
+      expect(store.get('nonexistent')).to be_nil
+    end
+  end
+
+  describe '#recent' do
+    it 'returns last N simulations' do
+      3.times { |i| store.store(simulation.merge(simulation_id: "sim-#{i}")) }
+      expect(store.recent(limit: 2).size).to eq(2)
+    end
+  end
+
+  describe '#by_mode' do
+    it 'filters by mode' do
+      store.store(simulation.merge(mode: :prospective))
+      store.store(simulation.merge(simulation_id: 'x', mode: :counterfactual))
+      expect(store.by_mode(:prospective).size).to eq(1)
+    end
+  end
+
+  describe '#accuracy_check' do
+    it 'records actual outcome' do
+      store.store(simulation)
+      result = store.accuracy_check(simulation[:simulation_id], actual_outcome: { valence: :positive })
+      expect(result).to be true
+    end
+
+    it 'returns nil for missing simulation' do
+      result = store.accuracy_check('nonexistent', actual_outcome: {})
+      expect(result).to be_nil
+    end
+  end
+
+  describe '#simulation_accuracy' do
+    it 'returns nil with no checked simulations' do
+      expect(store.simulation_accuracy).to be_nil
+    end
+
+    it 'computes accuracy' do
+      store.store(simulation)
+      store.accuracy_check(simulation[:simulation_id], actual_outcome: { valence: :positive })
+      expect(store.simulation_accuracy).to eq(1.0)
+    end
+  end
+
+  describe '#clear' do
+    it 'removes all simulations' do
+      store.store(simulation)
+      store.clear
+      expect(store.size).to eq(0)
+    end
+  end
+end

data/spec/legion/extensions/imagination/runners/imagination_spec.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Imagination::Runners::Imagination do
+  let(:client) { Legion::Extensions::Imagination::Client.new }
+
+  describe '#simulate' do
+    it 'simulates multiple actions' do
+      result = client.simulate(actions: %w[deploy rollback wait])
+      expect(result[:scenarios].size).to eq(3)
+      expect(result).to have_key(:recommendation)
+    end
+
+    it 'limits to MAX_SCENARIOS' do
+      actions = (1..10).map { |i| "action_#{i}" }
+      result = client.simulate(actions: actions)
+      expect(result[:scenarios].size).to be <= Legion::Extensions::Imagination::Helpers::Constants::MAX_SCENARIOS
+    end
+
+    it 'stores simulation in history' do
+      client.simulate(actions: %w[deploy])
+      expect(client.simulation_store.size).to eq(1)
+    end
+
+    it 'recommends the best action' do
+      result = client.simulate(
+        actions:        %w[safe_action risky_action],
+        context:        { familiar: true, alignment: 0.8 },
+        risk_tolerance: :conservative
+      )
+      expect(result[:recommendation]).to have_key(:action)
+      expect(result[:recommendation]).to have_key(:composite)
+    end
+
+    it 'respects risk tolerance' do
+      conservative = client.simulate(actions: %w[deploy], risk_tolerance: :conservative)
+      aggressive = client.simulate(actions: %w[deploy], risk_tolerance: :aggressive)
+      expect(conservative[:recommendation]).not_to be_nil
+      expect(aggressive[:recommendation]).not_to be_nil
+    end
+  end
+
+  describe '#what_if' do
+    it 'returns scenario with consequence chain' do
+      result = client.what_if(action: 'merge_without_tests', depth: 2)
+      expect(result[:consequence_chain].size).to eq(3)
+      expect(result[:depth]).to eq(2)
+    end
+
+    it 'limits depth to MAX_DEPTH' do
+      result = client.what_if(action: 'test', depth: 100)
+      expect(result[:depth]).to eq(Legion::Extensions::Imagination::Helpers::Constants::MAX_DEPTH)
+    end
+
+    it 'returns overall valence' do
+      result = client.what_if(action: 'safe_deploy', context: { familiar: true })
+      expect(result[:overall_valence]).to be_a(Symbol)
+    end
+  end
+
+  describe '#compare' do
+    it 'compares two actions' do
+      result = client.compare(action_a: 'refactor', action_b: 'ship_now')
+      expect(%i[a b]).to include(result[:winner])
+      expect(result).to have_key(:margin)
+      expect(result).to have_key(:decisive)
+    end
+
+    it 'returns scenario details for both' do
+      result = client.compare(action_a: 'a', action_b: 'b')
+      expect(result[:scenario_a]).to have_key(:expected_value)
+      expect(result[:scenario_b]).to have_key(:expected_value)
+    end
+  end
+
+  describe '#record_actual_outcome' do
+    it 'records outcome for existing simulation' do
+      sim = client.simulate(actions: %w[deploy])
+      result = client.record_actual_outcome(
+        simulation_id:  sim[:simulation_id],
+        actual_outcome: { valence: :positive }
+      )
+      expect(result[:accurate]).not_to be_nil
+    end
+
+    it 'returns error for missing simulation' do
+      result = client.record_actual_outcome(simulation_id: 'nonexistent', actual_outcome: {})
+      expect(result[:error]).to eq(:not_found)
+    end
+  end
+
+  describe '#imagination_stats' do
+    it 'returns stats summary' do
+      client.simulate(actions: %w[deploy])
+      result = client.imagination_stats
+      expect(result[:total_simulations]).to eq(1)
+      expect(result).to have_key(:by_mode)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Legion
+  module Logging
+    module_function
+
+    def debug(*); end
+
+    def info(*); end
+
+    def warn(*); end
+
+    def error(*); end
+  end
+
+  module Extensions
+    module Helpers; end
+  end
+end
+
+require 'legion/extensions/imagination'
+
+RSpec.configure do |config|
+  config.expect_with :rspec do |expectations|
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  config.mock_with :rspec do |mocks|
+    mocks.verify_partial_doubles = true
+  end
+
+  config.shared_context_metadata_behavior = :apply_to_host_groups
+  config.order = :random
+  Kernel.srand config.seed
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: lex-imagination
+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: Counterfactual simulation engine — mental rehearsal of actions before
+  committing
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENSE
+- README.md
+- lex-imagination.gemspec
+- lib/legion/extensions/imagination.rb
+- lib/legion/extensions/imagination/client.rb
+- lib/legion/extensions/imagination/helpers/constants.rb
+- lib/legion/extensions/imagination/helpers/scenario.rb
+- lib/legion/extensions/imagination/helpers/simulation_store.rb
+- lib/legion/extensions/imagination/runners/imagination.rb
+- lib/legion/extensions/imagination/version.rb
+- spec/legion/extensions/imagination/client_spec.rb
+- spec/legion/extensions/imagination/helpers/constants_spec.rb
+- spec/legion/extensions/imagination/helpers/scenario_spec.rb
+- spec/legion/extensions/imagination/helpers/simulation_store_spec.rb
+- spec/legion/extensions/imagination/runners/imagination_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-imagination
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-imagination
+  source_code_uri: https://github.com/LegionIO/lex-imagination
+  documentation_uri: https://github.com/LegionIO/lex-imagination
+  changelog_uri: https://github.com/LegionIO/lex-imagination
+  bug_tracker_uri: https://github.com/LegionIO/lex-imagination/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 Imagination
+test_files: []