lex-cognitive-alchemy 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 51513cbacc1a1f0aecbdd72f1b383e406941930fe87cbe1ecc56c956f8fab8eb
+  data.tar.gz: c1e9114adbc5ccaeade7e72c6f0f5d565028bf2d0d642e3d9e12ff81fdd71ddb
+SHA512:
+  metadata.gz: 062f264dfbfc751c3f8224b5b124ad599058705308e626c8d87ed0c672171c161d56d74dddf53a67cc9d9366c819863edaddbe417f5f1eaa14462871766048be
+  data.tar.gz: 3785118d7f7c03f2ea41a6da09c27c18bae76580cb99cc6590f5cc30eef1f1c7e09a985d9580b7876780681fd5fb91b17264ce9da2d6382157dea3736d234321

data/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ci:
+    uses: LegionIO/.github/.github/workflows/ci.yml@main
+
+  release:
+    needs: ci
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    uses: LegionIO/.github/.github/workflows/release.yml@main
+    secrets:
+      rubygems-api-key: ${{ secrets.RUBYGEMS_API_KEY }}

data/.gitignore

@@ -0,0 +1,2 @@
+.rspec_status
+Gemfile.lock

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--format documentation
+--color

data/.rubocop.yml

@@ -0,0 +1,37 @@
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.4
+
+Style/Documentation:
+  Enabled: false
+
+Naming/PredicateMethod:
+  Enabled: false
+
+Naming/PredicatePrefix:
+  Enabled: false
+
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/MethodLength:
+  Max: 25
+
+Metrics/AbcSize:
+  Max: 25
+
+Metrics/ParameterLists:
+  Max: 8
+  MaxOptionalParameters: 8
+
+Layout/HashAlignment:
+  EnforcedColonStyle: table
+  EnforcedHashRocketStyle: table
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+
+Style/OneClassPerFile:
+  Exclude:
+    - 'spec/spec_helper.rb'

data/CLAUDE.md

@@ -0,0 +1,87 @@
+# lex-cognitive-alchemy
+
+**Level 3 Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/extensions-agentic/CLAUDE.md`
+- **Grandparent**: `/Users/miverso2/rubymine/legion/CLAUDE.md`
+
+## Purpose
+
+Alchemical metaphor for cognitive transformation — substances move through four Jungian stages (nigredo, albedo, citrinitas, rubedo) via reactions and catalysts, modeling irreversible knowledge refinement and insight synthesis.
+
+## Gem Info
+
+- **Gem name**: `lex-cognitive-alchemy`
+- **Version**: `0.1.0`
+- **Module**: `Legion::Extensions::CognitiveAlchemy`
+- **Ruby**: `>= 3.4`
+- **License**: MIT
+
+## File Structure
+
+```
+lib/legion/extensions/cognitive_alchemy/
+  cognitive_alchemy.rb           # Main extension module
+  version.rb                     # VERSION = '0.1.0'
+  client.rb                      # Client wrapper
+  helpers/
+    constants.rb                 # Stages, element types, reaction types, multipliers, labels
+    substance.rb                 # Substance value object (stage, purity, potency, element_type)
+    alchemy_engine.rb            # AlchemyEngine — manages substances, reactions, stage progression
+  runners/
+    cognitive_alchemy.rb         # Runner module (extend self) with 7 public methods
+spec/
+  (spec files)
+```
+
+## Key Constants
+
+```ruby
+STAGES = %i[nigredo albedo citrinitas rubedo]
+ELEMENT_TYPES = %i[fire water earth air aether]
+REACTION_TYPES = %i[synthesis decomposition transmutation catalysis dissolution]
+CATALYST_MULTIPLIER = 3.0       # catalyst reactions multiply purity/potency gain by 3x
+PURITY_LABELS = {
+  (0.9..) => :refined, (0.7...0.9) => :purified, (0.5...0.7) => :mixed,
+  (0.3...0.5) => :impure, (..0.3) => :crude
+}
+POTENCY_LABELS = {
+  (0.85..) => :transcendent, (0.65...0.85) => :potent, (0.45...0.65) => :moderate,
+  (0.25...0.45) => :weak, (..0.25) => :inert
+}
+STAGE_LABELS = {
+  nigredo: :decomposition, albedo: :purification,
+  citrinitas: :illumination, rubedo: :completion
+}
+```
+
+## Runners
+
+### `Runners::CognitiveAlchemy`
+
+Uses `extend self` — methods are module-level, not instance-delegating. Delegates to a per-call `engine` (parameter-injected `Helpers::AlchemyEngine` instance via `engine:` keyword, defaulting to a shared `@engine ||=`).
+
+- `create_substance(name:, element_type:, domain: :general, engine: @engine)` — create a new alchemical substance at `:nigredo` stage with default purity/potency
+- `advance_stage(substance_id:, engine: @engine)` — move substance to the next STAGES entry; no-op at `:rubedo`
+- `catalyze(substance_id:, catalyst:, engine: @engine)` — apply a catalyst to a substance, multiplying its purity and potency gain by `CATALYST_MULTIPLIER`
+- `react(substance_id:, reagent_id:, reaction_type:, engine: @engine)` — apply a typed reaction between two substances; returns reaction outcome hash
+- `list_substances(engine: @engine)` — all substances as array of hashes
+- `alchemy_status(engine: @engine)` — summary stats: substance count, stage distribution, average purity/potency
+
+## Helpers
+
+### `Helpers::AlchemyEngine`
+Core engine managing `@substances` hash keyed by ID. `advance_stage` cycles through `STAGES` array index. `catalyze` applies `CATALYST_MULTIPLIER` to substance attribute update. `react` looks up both substances, applies reaction effects based on `reaction_type`, and returns outcome. `substance_list` returns all substances as serialized hashes.
+
+### `Helpers::Substance`
+Value object: name, element_type, domain, stage (starts at `:nigredo`), purity (0.0–1.0), potency (0.0–1.0), reaction_count. `advance!` bumps stage via STAGES index. `refine!(amount)` increases purity clamped to 1.0. `empower!(amount)` increases potency clamped to 1.0. `purity_label` and `potency_label` map to human-readable labels.
+
+## Integration Points
+
+No actor defined — no automatic decay or scanning. This is a transformation metaphor: raw observations enter at `:nigredo` and move through stages as evidence accumulates. Pairs with lex-causal-reasoning (causal chains can trigger stage advancement) and lex-abductive-reasoning (best explanations emerge at `:rubedo`). The CATALYST_MULTIPLIER (3x) models insight events — moments where a catalyst dramatically accelerates refinement.
+
+## Development Notes
+
+- `extend self` pattern means the runner is a module with module-level methods — no `@engine` instance variable in a class; shared state lives in the module's singleton
+- `advance_stage` is a no-op when substance is already at `:rubedo` — callers should check stage before calling
+- `CATALYST_MULTIPLIER = 3.0` is the only numeric constant that differs from the standard 0.1/0.15 rates used by other extensions
+- Stage ordering is fixed by the `STAGES` array index; array order defines the progression

data/Gemfile

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

data/Gemfile.lock

@@ -0,0 +1,78 @@
+PATH
+  remote: .
+  specs:
+    lex-cognitive-alchemy (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.9)
+      public_suffix (>= 2.0.2, < 8.0)
+    ast (2.4.3)
+    bigdecimal (4.0.1)
+    diff-lcs (1.6.2)
+    json (2.19.1)
+    json-schema (6.2.0)
+      addressable (~> 2.8)
+      bigdecimal (>= 3.1, < 5)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    mcp (0.8.0)
+      json-schema (>= 4.1)
+    parallel (1.27.0)
+    parser (3.3.10.2)
+      ast (~> 2.4.1)
+      racc
+    prism (1.9.0)
+    public_suffix (7.0.5)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    regexp_parser (2.11.3)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    rubocop (1.85.1)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      mcp (~> 0.6)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-rspec (3.9.0)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.81)
+    ruby-progressbar (1.13.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+
+PLATFORMS
+  arm64-darwin-25
+  ruby
+
+DEPENDENCIES
+  lex-cognitive-alchemy!
+  rspec (~> 3.13)
+  rubocop (~> 1.75)
+  rubocop-rspec
+
+BUNDLED WITH
+   2.6.9

data/README.md

@@ -0,0 +1,60 @@
+# lex-cognitive-alchemy
+
+Alchemical metaphor for cognitive transformation — substances move through Jungian stages via reactions and catalysts.
+
+## What It Does
+
+Models knowledge refinement as an alchemical process. Cognitive substances (ideas, insights, hypotheses) are created at the crude `:nigredo` stage and purified through four stages: nigredo (decomposition), albedo (purification), citrinitas (illumination), rubedo (completion). Reactions between substances transform them; catalysts multiply the gain by 3x.
+
+## Core Concept: Stage Progression
+
+```
+nigredo -> albedo -> citrinitas -> rubedo
+(crude)   (purified) (illuminated) (complete)
+```
+
+Each substance has `purity` (0.0–1.0, crude to refined) and `potency` (0.0–1.0, inert to transcendent). Stage advancement and reactions increase both.
+
+## Usage
+
+```ruby
+client = Legion::Extensions::CognitiveAlchemy::Client.new
+
+# Create substances from raw observations
+idea = client.create_substance(name: :cache_invalidation_theory, element_type: :fire, domain: :infrastructure)
+evidence = client.create_substance(name: :production_trace_data, element_type: :earth, domain: :infrastructure)
+
+# Apply a reaction between substances
+client.react(
+  substance_id: idea[:substance][:id],
+  reagent_id: evidence[:substance][:id],
+  reaction_type: :synthesis
+)
+
+# A breakthrough insight acts as a catalyst (3x multiplier)
+client.catalyze(substance_id: idea[:substance][:id], catalyst: :root_cause_confirmed)
+
+# Advance to next stage when ready
+client.advance_stage(substance_id: idea[:substance][:id])
+# substance moves from :nigredo -> :albedo
+
+# Check overall transformation progress
+client.alchemy_status
+# => { substance_count: 2, stage_distribution: { nigredo: 1, albedo: 1, ... }, avg_purity: 0.62 }
+```
+
+## Integration
+
+Pairs with lex-causal-reasoning (causal chains can trigger stage advancement as evidence accumulates) and lex-abductive-reasoning (best explanations correspond to `:rubedo` substances — fully refined and potent).
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-cognitive-alchemy.gemspec

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_alchemy/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-alchemy'
+  spec.version       = Legion::Extensions::CognitiveAlchemy::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+  spec.license       = 'MIT'
+
+  spec.summary       = 'Cognitive alchemy LEX — transmutation of ideas through alchemical stages'
+  spec.description   = 'Models the Magnum Opus of idea transmutation: substances pass through ' \
+                       'nigredo/albedo/citrinitas/rubedo stages, crucible reactions combine elements ' \
+                       'under heat and pressure, and philosopher stone catalysis accelerates breakthroughs.'
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-alchemy'
+
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri']      = spec.homepage
+  spec.metadata['source_code_uri']   = spec.homepage
+  spec.metadata['documentation_uri'] = "#{spec.homepage}#readme"
+  spec.metadata['changelog_uri']     = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata['bug_tracker_uri']   = "#{spec.homepage}/issues"
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(test|spec|features)/}) }
+  end
+
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveAlchemy
+      class Client
+        include Runners::CognitiveAlchemy
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_alchemy/helpers/alchemy_engine.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveAlchemy
+      module Helpers
+        class AlchemyEngine
+          def initialize
+            @substances = {}
+            @reactions  = {}
+          end
+
+          def create_substance(element_type:, domain:, content:, purity: nil, potency: nil)
+            raise ArgumentError, 'athanor full' if @substances.size >= Constants::MAX_SUBSTANCES
+
+            sub = Substance.new(element_type: element_type, domain: domain,
+                                content: content, purity: purity, potency: potency)
+            @substances[sub.id] = sub
+            sub
+          end
+
+          def advance_stage(substance_id:)
+            fetch_substance(substance_id).advance_stage!
+          end
+
+          def catalyze(substance_id:, multiplier: Constants::CATALYST_MULTIPLIER)
+            fetch_substance(substance_id).catalyze!(multiplier: multiplier)
+          end
+
+          def react(reaction_type:, input_ids:, heat: 0.5, pressure: 0.5)
+            raise ArgumentError, 'too many reactions' if @reactions.size >= Constants::MAX_REACTIONS
+
+            inputs = input_ids.map { |id| fetch_substance(id) }
+            crucible = Crucible.new(reaction_type: reaction_type, input_ids: input_ids,
+                                    heat: heat, pressure: pressure)
+
+            output = synthesize(inputs, crucible)
+            @substances[output.id] = output
+            crucible.complete!(output.id)
+            @reactions[crucible.id] = crucible
+
+            { crucible: crucible, output: output }
+          end
+
+          def decay_all!(rate: Constants::SUBSTANCE_DECAY)
+            @substances.each_value { |s| s.decay!(rate: rate) }
+            pruned = @substances.select { |_, s| s.inert? }.keys
+            pruned.each { |id| @substances.delete(id) }
+            { decayed: @substances.size, pruned: pruned.size }
+          end
+
+          def substances_by_stage
+            counts = Constants::STAGES.to_h { |s| [s, 0] }
+            @substances.each_value { |s| counts[s.stage] += 1 }
+            counts
+          end
+
+          def substances_by_type
+            counts = Constants::ELEMENT_TYPES.to_h { |t| [t, 0] }
+            @substances.each_value { |s| counts[s.element_type] += 1 }
+            counts
+          end
+
+          def gold_count
+            @substances.count { |_, s| s.gold? }
+          end
+
+          def prima_materia_count
+            @substances.count { |_, s| s.prima_materia? }
+          end
+
+          def purest(limit: 5)
+            @substances.values.sort_by { |s| -s.purity }.first(limit)
+          end
+
+          def most_potent(limit: 5)
+            @substances.values.sort_by { |s| -s.potency }.first(limit)
+          end
+
+          def alchemy_report
+            {
+              total_substances: @substances.size,
+              total_reactions:  @reactions.size,
+              by_stage:         substances_by_stage,
+              by_type:          substances_by_type,
+              gold_count:       gold_count,
+              prima_materia:    prima_materia_count,
+              avg_purity:       avg_metric(:purity),
+              avg_potency:      avg_metric(:potency)
+            }
+          end
+
+          def all_substances
+            @substances.values
+          end
+
+          def all_reactions
+            @reactions.values
+          end
+
+          private
+
+          def fetch_substance(id)
+            @substances.fetch(id) do
+              raise ArgumentError, "substance not found: #{id}"
+            end
+          end
+
+          def synthesize(inputs, crucible)
+            avg_purity  = inputs.sum(&:purity) / inputs.size
+            avg_potency = inputs.sum(&:potency) / inputs.size
+            boost       = crucible.intensity * Constants::TRANSMUTATION_RATE
+
+            create_substance(
+              element_type: inputs.first.element_type,
+              domain:       inputs.first.domain,
+              content:      "synthesis(#{inputs.map(&:content).join(' + ')})",
+              purity:       (avg_purity + boost).clamp(0.0, 1.0),
+              potency:      (avg_potency + (boost * 0.5)).clamp(0.0, 1.0)
+            )
+          end
+
+          def avg_metric(attr)
+            return 0.0 if @substances.empty?
+
+            (substances_metric_sum(attr) / @substances.size).round(10)
+          end
+
+          def substances_metric_sum(attr)
+            @substances.values.sum(&attr)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveAlchemy
+      module Helpers
+        module Constants
+          # Alchemical stages (Magnum Opus)
+          STAGES = %i[nigredo albedo citrinitas rubedo].freeze
+
+          # Transmutation element types
+          ELEMENT_TYPES = %i[
+            concept belief skill memory emotion
+            pattern habit intuition hypothesis
+          ].freeze
+
+          # Crucible reaction types
+          REACTION_TYPES = %i[
+            calcination dissolution separation conjunction
+            fermentation distillation coagulation
+          ].freeze
+
+          # Maximum substances in the athanor
+          MAX_SUBSTANCES = 200
+
+          # Maximum crucible reactions
+          MAX_REACTIONS = 100
+
+          # Base transmutation rate per stage advance
+          TRANSMUTATION_RATE = 0.15
+
+          # Decay rate for unreacted substances
+          SUBSTANCE_DECAY = 0.02
+
+          # Philosopher's stone catalyst multiplier
+          CATALYST_MULTIPLIER = 3.0
+
+          # Stage labels
+          STAGE_LABELS = {
+            nigredo:    'Blackening — decomposition of raw material',
+            albedo:     'Whitening — purification and washing',
+            citrinitas: 'Yellowing — solar awakening',
+            rubedo:     'Reddening — final integration and gold'
+          }.freeze
+
+          # Purity labels (range-based)
+          PURITY_LABELS = [
+            [(0.8..),      :aurum],
+            [(0.6...0.8),  :argentum],
+            [(0.4...0.6),  :cuprum],
+            [(0.2...0.4),  :ferrum],
+            [(..0.2),      :plumbum]
+          ].freeze
+
+          # Potency labels
+          POTENCY_LABELS = [
+            [(0.8..),      :transcendent],
+            [(0.6...0.8),  :potent],
+            [(0.4...0.6),  :moderate],
+            [(0.2...0.4),  :weak],
+            [(..0.2),      :inert]
+          ].freeze
+
+          def self.label_for(table, value)
+            table.each { |range, label| return label if range.cover?(value) }
+            table.last.last
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_alchemy/helpers/crucible.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveAlchemy
+      module Helpers
+        class Crucible
+          attr_reader :id, :reaction_type, :input_ids, :output_id,
+                      :heat, :pressure, :started_at, :completed_at
+
+          def initialize(reaction_type:, input_ids:,
+                         heat: 0.5, pressure: 0.5)
+            validate_reaction!(reaction_type)
+            @id            = SecureRandom.uuid
+            @reaction_type = reaction_type.to_sym
+            @input_ids     = Array(input_ids).dup
+            @output_id     = nil
+            @heat          = heat.to_f.clamp(0.0, 1.0).round(10)
+            @pressure      = pressure.to_f.clamp(0.0, 1.0).round(10)
+            @started_at    = Time.now.utc
+            @completed_at  = nil
+          end
+
+          def complete!(output_id)
+            @output_id    = output_id
+            @completed_at = Time.now.utc
+            self
+          end
+
+          def completed?
+            !@completed_at.nil?
+          end
+
+          def intensity
+            ((@heat + @pressure) / 2.0).round(10)
+          end
+
+          def volatile?
+            @heat > 0.8 && @pressure > 0.8
+          end
+
+          def mild?
+            intensity < 0.3
+          end
+
+          def to_h
+            {
+              id:            @id,
+              reaction_type: @reaction_type,
+              input_ids:     @input_ids,
+              output_id:     @output_id,
+              heat:          @heat,
+              pressure:      @pressure,
+              intensity:     intensity,
+              volatile:      volatile?,
+              mild:          mild?,
+              started_at:    @started_at,
+              completed_at:  @completed_at,
+              completed:     completed?
+            }
+          end
+
+          private
+
+          def validate_reaction!(val)
+            return if Constants::REACTION_TYPES.include?(val.to_sym)
+
+            raise ArgumentError,
+                  "unknown reaction type: #{val.inspect}; " \
+                  "must be one of #{Constants::REACTION_TYPES.inspect}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_alchemy/helpers/substance.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveAlchemy
+      module Helpers
+        class Substance
+          attr_reader :id, :element_type, :domain, :content,
+                      :stage, :discovered_at, :transmutation_count
+          attr_accessor :purity, :potency
+
+          def initialize(element_type:, domain:, content:,
+                         purity: nil, potency: nil)
+            validate_type!(element_type)
+            assign_core(element_type, domain, content)
+            assign_metadata(purity, potency)
+          end
+
+          def advance_stage!
+            idx = Constants::STAGES.index(@stage)
+            return self if idx >= Constants::STAGES.size - 1
+
+            @stage = Constants::STAGES[idx + 1]
+            @purity = (@purity + Constants::TRANSMUTATION_RATE).clamp(0.0, 1.0).round(10)
+            @transmutation_count += 1
+            self
+          end
+
+          def decay!(rate: Constants::SUBSTANCE_DECAY)
+            @potency = (@potency - rate.abs).clamp(0.0, 1.0).round(10)
+            self
+          end
+
+          def catalyze!(multiplier: Constants::CATALYST_MULTIPLIER)
+            boost = Constants::TRANSMUTATION_RATE * multiplier
+            @purity = (@purity + boost).clamp(0.0, 1.0).round(10)
+            @potency = (@potency + (boost * 0.5)).clamp(0.0, 1.0).round(10)
+            @transmutation_count += 1
+            self
+          end
+
+          def prima_materia?
+            @stage == :nigredo && @purity < 0.2
+          end
+
+          def gold?
+            @stage == :rubedo && @purity >= 0.8
+          end
+
+          def inert?
+            @potency < 0.1
+          end
+
+          def purity_label
+            Constants.label_for(Constants::PURITY_LABELS, @purity)
+          end
+
+          def potency_label
+            Constants.label_for(Constants::POTENCY_LABELS, @potency)
+          end
+
+          def stage_label
+            Constants::STAGE_LABELS.fetch(@stage, 'unknown')
+          end
+
+          def to_h
+            {
+              id:                  @id,
+              element_type:        @element_type,
+              domain:              @domain,
+              content:             @content,
+              stage:               @stage,
+              stage_label:         stage_label,
+              purity:              @purity,
+              purity_label:        purity_label,
+              potency:             @potency,
+              potency_label:       potency_label,
+              transmutation_count: @transmutation_count,
+              discovered_at:       @discovered_at,
+              prima_materia:       prima_materia?,
+              gold:                gold?,
+              inert:               inert?
+            }
+          end
+
+          private
+
+          def assign_core(element_type, domain, content)
+            @id           = SecureRandom.uuid
+            @element_type = element_type.to_sym
+            @domain       = domain.to_sym
+            @content      = content.to_s
+          end
+
+          def assign_metadata(purity, potency)
+            @stage               = :nigredo
+            @purity              = (purity || 0.1).to_f.clamp(0.0, 1.0).round(10)
+            @potency             = (potency || 0.5).to_f.clamp(0.0, 1.0).round(10)
+            @transmutation_count = 0
+            @discovered_at       = Time.now.utc
+          end
+
+          def validate_type!(val)
+            return if Constants::ELEMENT_TYPES.include?(val.to_sym)
+
+            raise ArgumentError,
+                  "unknown element type: #{val.inspect}; " \
+                  "must be one of #{Constants::ELEMENT_TYPES.inspect}"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveAlchemy
+      module Runners
+        module CognitiveAlchemy
+          extend self
+
+          def create_substance(element_type:, domain:, content:,
+                               purity: nil, potency: nil, engine: nil, **)
+            eng = resolve_engine(engine)
+            sub = eng.create_substance(element_type: element_type, domain: domain,
+                                       content: content, purity: purity, potency: potency)
+            { success: true, substance: sub.to_h }
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def advance_stage(substance_id:, engine: nil, **)
+            eng = resolve_engine(engine)
+            sub = eng.advance_stage(substance_id: substance_id)
+            { success: true, substance: sub.to_h }
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def catalyze(substance_id:, multiplier: nil, engine: nil, **)
+            eng  = resolve_engine(engine)
+            opts = { substance_id: substance_id }
+            opts[:multiplier] = multiplier if multiplier
+            sub = eng.catalyze(**opts)
+            { success: true, substance: sub.to_h }
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def react(reaction_type:, input_ids:, heat: 0.5,
+                    pressure: 0.5, engine: nil, **)
+            eng    = resolve_engine(engine)
+            result = eng.react(reaction_type: reaction_type, input_ids: input_ids,
+                               heat: heat, pressure: pressure)
+            { success: true, crucible: result[:crucible].to_h,
+              output: result[:output].to_h }
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def list_substances(engine: nil, stage: nil, element_type: nil, **)
+            eng     = resolve_engine(engine)
+            results = filter_substances(eng.all_substances,
+                                        stage: stage, element_type: element_type)
+            { success: true, substances: results.map(&:to_h),
+              count: results.size }
+          end
+
+          def alchemy_status(engine: nil, **)
+            eng = resolve_engine(engine)
+            { success: true, report: eng.alchemy_report }
+          end
+
+          include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+          private
+
+          def filter_substances(substances, stage:, element_type:)
+            r = substances
+            r = r.select { |s| s.stage == stage.to_sym } if stage
+            r = r.select { |s| s.element_type == element_type.to_sym } if element_type
+            r
+          end
+
+          def resolve_engine(engine)
+            engine || default_engine
+          end
+
+          def default_engine
+            @default_engine ||= Helpers::AlchemyEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/cognitive_alchemy.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+require_relative 'cognitive_alchemy/version'
+require_relative 'cognitive_alchemy/helpers/constants'
+require_relative 'cognitive_alchemy/helpers/substance'
+require_relative 'cognitive_alchemy/helpers/crucible'
+require_relative 'cognitive_alchemy/helpers/alchemy_engine'
+require_relative 'cognitive_alchemy/runners/cognitive_alchemy'
+require_relative 'cognitive_alchemy/client'
+
+module Legion
+  module Extensions
+    module CognitiveAlchemy
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: lex-cognitive-alchemy
+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: 'Models the Magnum Opus of idea transmutation: substances pass through
+  nigredo/albedo/citrinitas/rubedo stages, crucible reactions combine elements under
+  heat and pressure, and philosopher stone catalysis accelerates breakthroughs.'
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- CLAUDE.md
+- Gemfile
+- Gemfile.lock
+- README.md
+- lex-cognitive-alchemy.gemspec
+- lib/legion/extensions/cognitive_alchemy.rb
+- lib/legion/extensions/cognitive_alchemy/client.rb
+- lib/legion/extensions/cognitive_alchemy/helpers/alchemy_engine.rb
+- lib/legion/extensions/cognitive_alchemy/helpers/constants.rb
+- lib/legion/extensions/cognitive_alchemy/helpers/crucible.rb
+- lib/legion/extensions/cognitive_alchemy/helpers/substance.rb
+- lib/legion/extensions/cognitive_alchemy/runners/cognitive_alchemy.rb
+- lib/legion/extensions/cognitive_alchemy/version.rb
+homepage: https://github.com/LegionIO/lex-cognitive-alchemy
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-cognitive-alchemy
+  source_code_uri: https://github.com/LegionIO/lex-cognitive-alchemy
+  documentation_uri: https://github.com/LegionIO/lex-cognitive-alchemy#readme
+  changelog_uri: https://github.com/LegionIO/lex-cognitive-alchemy/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/LegionIO/lex-cognitive-alchemy/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: Cognitive alchemy LEX — transmutation of ideas through alchemical stages
+test_files: []