lex-cognitive-volcano 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f79db54f8bbca323744fbb95f9efc778521d66e01ef25f9301eb8ec173374cb7
+  data.tar.gz: ed15b25b8ac357b18b2a7aa8d1ac76aa3201661cb3b3ad3bfde77caa43044037
+SHA512:
+  metadata.gz: 828961a9d272b16adf514121b9599b10c2d52e343091a1a3ddeb5780563c0127a6e1639019a2d4c822ebb016fee231262cdc54e30f50ff700e58f48754cc7f39
+  data.tar.gz: d16173b4a14f96d9a5957d31ea775392aa8da6d495a9be6b0824a8cdff01811f6cc2e394e8266f5ddf94f41ee968e341eec01a109971ea551c2780b2e2ee5c52

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,64 @@
+AllCops:
+  TargetRubyVersion: 3.4
+  NewCops: enable
+  SuggestExtensions: false
+
+Layout/LineLength:
+  Max: 160
+
+Layout/SpaceAroundEqualsInParameterDefault:
+  EnforcedStyle: space
+
+Layout/HashAlignment:
+  EnforcedHashRocketStyle: table
+  EnforcedColonStyle: table
+
+Metrics/MethodLength:
+  Max: 25
+
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/ModuleLength:
+  Max: 150
+
+Metrics/BlockLength:
+  Max: 40
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/AbcSize:
+  Max: 25
+
+Metrics/CyclomaticComplexity:
+  Max: 15
+
+Metrics/PerceivedComplexity:
+  Max: 17
+
+Metrics/ParameterLists:
+  Max: 8
+  MaxOptionalParameters: 8
+
+Style/Documentation:
+  Enabled: false
+
+Style/OneClassPerFile:
+  Exclude:
+    - 'spec/spec_helper.rb'
+
+Style/SymbolArray:
+  Enabled: true
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+Naming/FileName:
+  Enabled: false
+
+Naming/PredicateMethod:
+  Enabled: false
+
+Naming/PredicatePrefix:
+  Enabled: false

data/CLAUDE.md

@@ -0,0 +1,121 @@
+# lex-cognitive-volcano
+
+**Level 3 Leaf Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/extensions-agentic/CLAUDE.md`
+- **Gem**: `lex-cognitive-volcano`
+- **Version**: 0.1.0
+- **Namespace**: `Legion::Extensions::CognitiveVolcano`
+
+## Purpose
+
+Models cognitive pressure accumulation and eruption as a volcanic system. Magma units represent suppressed or building cognitive content (suppression, creativity, emotion, memory, frustration) that accumulate pressure over time. Chambers hold magma deposits and can erupt when critical-pressure magma is present. Eruption type is determined by the dominant magma type: suppression -> breakthrough, creativity -> insight, emotion/frustration -> outburst, memory -> catharsis.
+
+## Gem Info
+
+- **Gemspec**: `lex-cognitive-volcano.gemspec`
+- **Require**: `lex-cognitive-volcano`
+- **Ruby**: >= 3.4
+- **License**: MIT
+- **Homepage**: https://github.com/LegionIO/lex-cognitive-volcano
+
+## File Structure
+
+```
+lib/legion/extensions/cognitive_volcano/
+  version.rb
+  helpers/
+    constants.rb         # Magma/eruption types, pressure/intensity label tables, thresholds
+    magma.rb             # Magma class — one pressurizable cognitive deposit
+    chamber.rb           # Chamber class — holds magma, can erupt
+    volcano_engine.rb    # VolcanoEngine — registry for chambers and magma
+  runners/
+    cognitive_volcano.rb  # Runner module — public API (extend self)
+  client.rb
+```
+
+## Key Constants
+
+| Constant | Value | Meaning |
+|---|---|---|
+| `MAX_CHAMBERS` | 100 | Hard cap on chambers (raises if exceeded) |
+| `PRESSURE_RATE` | 0.08 | Default pressure increase per `pressurize!` call |
+| `ERUPTION_THRESHOLD` | 0.85 | Pressure >= this = critical magma |
+| `COOLDOWN_RATE` | 0.03 | Pressure released per `cool_all!` tick |
+
+`MAGMA_TYPES`: `[:suppression, :creativity, :emotion, :memory, :frustration]`
+
+`ERUPTION_TYPES`: `[:breakthrough, :outburst, :insight, :catharsis]`
+
+Eruption type mapping (by dominant magma): `suppression -> :breakthrough`, `creativity -> :insight`, `emotion -> :outburst`, `frustration -> :outburst`, `memory -> :catharsis`
+
+Pressure labels: `0.0..0.2` = `:dormant`, `0.2..0.4` = `:building`, `0.4..0.6` = `:active`, `0.6..0.8` = `:elevated`, `0.8..1.0` = `:critical`
+
+Intensity labels: `0.0..0.2` = `:minor`, `0.2..0.4` = `:moderate`, `0.4..0.6` = `:significant`, `0.6..0.8` = `:major`, `0.8..1.0` = `:cataclysmic`
+
+## Key Classes
+
+### `Helpers::Magma`
+
+One pressurizable cognitive deposit.
+
+- `pressurize!(rate:)` — increases pressure by rate (default `PRESSURE_RATE`)
+- `release!(amount:)` — reduces pressure by at most `amount`; returns released amount
+- `critical?` — pressure >= `ERUPTION_THRESHOLD`
+- `dormant?` — pressure < 0.2
+- `pressure_label` — label from `PRESSURE_LABELS`
+- Invalid `magma_type` raises `ArgumentError`
+
+### `Helpers::Chamber`
+
+A volcanic chamber holding magma deposits.
+
+- `add_magma(magma)` — appends magma; raises temperature by 0.05 (capped at 1.0)
+- `erupt!` — if no critical magma, returns `{ erupted: false, reason: :no_critical_magma }`; otherwise releases all critical magma, removes dormant deposits, lowers temperature by 0.2, lowers structural_integrity by 0.1, increments `eruption_count`; returns eruption event hash
+- `reinforce!(amount:)` / `degrade!(amount:)` — adjust structural integrity
+- `volatile?` — any critical magma OR structural_integrity < 0.3
+- `stable?` — not volatile AND structural_integrity >= 0.7
+- `average_pressure` — mean pressure across all magma deposits
+- Eruption type determined by dominant magma type count via `ERUPTION_TYPE_MAP`
+
+### `Helpers::VolcanoEngine`
+
+Registry for chambers and magma.
+
+- `create_magma(magma_type:, domain:, content:, source:, pressure:)` — stores in `@magma_registry`
+- `create_chamber(name:, temperature:, structural_integrity:)` — raises if at `MAX_CHAMBERS`
+- `pressurize_magma(magma_id:, rate:)` — delegates to magma
+- `trigger_eruption(chamber_id:)` — delegates to chamber's `erupt!`; records in `@eruption_history` (ring buffer, 500 max)
+- `cool_all!(rate:)` — releases `rate` pressure from all non-dormant magma; returns count cooled
+- `most_volatile` — chamber with highest `average_pressure`
+- `pressure_report` — aggregate with critical count, volatile chamber count, eruption history size
+
+Note: magma is stored in `@magma_registry` independently; chambers maintain `@magma_deposits` separately. Adding magma to the registry does NOT automatically add it to a chamber — that requires `chamber.add_magma(magma)`.
+
+## Runners
+
+Module: `Legion::Extensions::CognitiveVolcano::Runners::CognitiveVolcano` (uses `extend self`)
+
+| Runner | Key Args | Returns |
+|---|---|---|
+| `create_magma` | `magma_type:`, `domain:`, `content:`, `source:`, `pressure:` | `{ success:, magma: }` or `{ success: false, error: :invalid_magma_type }` |
+| `create_chamber` | `name:`, `temperature:`, `structural_integrity:` | `{ success:, chamber: }` |
+| `pressurize` | `magma_id:`, `rate:` | `{ success:, magma: }` or `{ success: false, error: :magma_not_found }` |
+| `trigger_eruption` | `chamber_id:` | `{ success:, erupted:, eruption_type:, intensity:, ... }` |
+| `list_chambers` | — | `{ success:, chambers:, count: }` |
+| `pressure_status` | — | `{ success:, total_chambers:, critical_count:, average_pressure:, ... }` |
+
+All runners accept optional `engine:` keyword for test injection.
+
+## Integration Points
+
+- No actors defined; `cool_all!` and `pressurize_magma` must be triggered externally
+- Can model emotional pressure build-up alongside `lex-emotion` for a complementary pressure+valence model
+- `trigger_eruption` is the culminating action — represents sudden expressive release
+- All state is in-memory per `VolcanoEngine` instance
+
+## Development Notes
+
+- Magma and chambers are separate: magma must be explicitly added to a chamber via `chamber.add_magma(magma)` — the engine runners do not perform this linking automatically
+- The runner's `trigger_eruption` merges `success:` after the fact: `result.merge(success: result[:erupted])`
+- `erupt!` removes dormant deposits (pressure < 0.2) after releasing critical ones — slight behavior to be aware of in tests
+- `VolcanoEngine#cool_all!` releases from `@magma_registry` (the flat registry), not from chamber deposits

data/Gemfile

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

data/Gemfile.lock

@@ -0,0 +1,78 @@
+PATH
+  remote: .
+  specs:
+    lex-cognitive-volcano (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-volcano!
+  rspec (~> 3.13)
+  rubocop (~> 1.75)
+  rubocop-rspec
+
+BUNDLED WITH
+   2.6.9

data/README.md

@@ -0,0 +1,68 @@
+# lex-cognitive-volcano
+
+A LegionIO cognitive architecture extension that models cognitive pressure accumulation and release as a volcanic system. Suppressed thoughts, creative impulses, and emotional energy accumulate as magma that pressurizes until a chamber erupts.
+
+## What It Does
+
+Tracks **magma** — cognitive content of five types:
+
+`suppression`, `creativity`, `emotion`, `memory`, `frustration`
+
+Magma pressurizes over time. Once pressure reaches 0.85 (critical), it becomes eligible for eruption. **Chambers** hold magma deposits; when a chamber erupts, all critical magma releases and the eruption type is determined by the dominant magma:
+
+- Suppression -> `:breakthrough`
+- Creativity -> `:insight`
+- Emotion/Frustration -> `:outburst`
+- Memory -> `:catharsis`
+
+## Usage
+
+```ruby
+require 'lex-cognitive-volcano'
+
+client = Legion::Extensions::CognitiveVolcano::Client.new
+
+# Create a volcanic chamber
+chamber = client.create_chamber(name: 'emotional_pressure_chamber', temperature: 0.4)
+# => { success: true, chamber: { chamber_id: "uuid...", volatile: false, stable: true, ... } }
+
+chamber_id = chamber[:chamber][:chamber_id]
+
+# Create magma units
+m1 = client.create_magma(magma_type: :emotion, domain: :social, content: 'unresolved conflict', source: :interaction, pressure: 0.5)
+# => { success: true, magma: { magma_id: "uuid...", pressure: 0.5, label: :active, critical: false, ... } }
+
+# Pressurize magma
+client.pressurize(magma_id: m1[:magma][:magma_id])
+# => { success: true, magma: { pressure: 0.58, label: :active, critical: false, ... } }
+
+# Pressurize repeatedly until critical
+8.times { client.pressurize(magma_id: m1[:magma][:magma_id]) }
+client.pressurize(magma_id: m1[:magma][:magma_id])
+# => { success: true, magma: { pressure: 0.86+, label: :critical, critical: true, ... } }
+
+# Check system pressure
+client.pressure_status
+# => { success: true, critical_count: 1, average_pressure: 0.86, pressure_label: :critical, volatile_chambers: 0, ... }
+
+# Trigger eruption from a chamber (requires magma added to chamber directly via Chamber#add_magma)
+client.trigger_eruption(chamber_id: chamber_id)
+# => { success: false, erupted: false, reason: :no_critical_magma }
+# (Note: magma must be added to the chamber object to trigger eruption)
+
+# List all chambers
+client.list_chambers
+# => { success: true, chambers: [...], count: 1 }
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-cognitive-volcano.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_volcano/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-volcano'
+  spec.version       = Legion::Extensions::CognitiveVolcano::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Cognitive Volcano'
+  spec.description   = 'Models cognitive pressure buildup and eruption cycles — suppressed thoughts accumulate ' \
+                       'pressure (like magma) until they erupt as breakthroughs, emotional outbursts, or creative explosions'
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-volcano'
+  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-cognitive-volcano'
+  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-cognitive-volcano'
+  spec.metadata['changelog_uri']     = 'https://github.com/LegionIO/lex-cognitive-volcano'
+  spec.metadata['bug_tracker_uri']   = 'https://github.com/LegionIO/lex-cognitive-volcano/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveVolcano
+      class Client
+        include Runners::CognitiveVolcano
+
+        attr_reader :engine
+
+        def initialize(engine: nil, **)
+          @engine = engine || Helpers::VolcanoEngine.new
+        end
+
+        def create_magma(magma_type:, domain:, content:, source:, pressure: 0.0, **)
+          super(magma_type: magma_type, domain: domain, content: content,
+                source: source, pressure: pressure, engine: @engine)
+        end
+
+        def create_chamber(name:, temperature: 0.5, structural_integrity: 1.0, **)
+          super(name: name, temperature: temperature,
+                structural_integrity: structural_integrity, engine: @engine)
+        end
+
+        def pressurize(magma_id:, rate: Helpers::Constants::PRESSURE_RATE, **)
+          super(magma_id: magma_id, rate: rate, engine: @engine)
+        end
+
+        def trigger_eruption(chamber_id:, **)
+          super(chamber_id: chamber_id, engine: @engine)
+        end
+
+        def list_chambers(**)
+          super(engine: @engine)
+        end
+
+        def pressure_status(**)
+          super(engine: @engine)
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_volcano/helpers/chamber.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveVolcano
+      module Helpers
+        class Chamber
+          attr_reader :chamber_id, :name, :temperature, :structural_integrity, :magma_deposits, :eruption_count
+
+          def initialize(name:, temperature: 0.5, structural_integrity: 1.0)
+            @chamber_id          = SecureRandom.uuid
+            @name                = name
+            @temperature         = temperature.clamp(0.0, 1.0)
+            @structural_integrity = structural_integrity.clamp(0.0, 1.0)
+            @magma_deposits      = []
+            @eruption_count      = 0
+            @created_at          = Time.now.utc
+          end
+
+          def add_magma(magma)
+            raise ArgumentError, 'magma must be a Magma instance' unless magma.is_a?(Magma)
+
+            @magma_deposits << magma
+            @temperature = [@temperature + 0.05, 1.0].min
+            magma
+          end
+
+          def erupt!
+            critical = @magma_deposits.select(&:critical?)
+            return { erupted: false, reason: :no_critical_magma } if critical.empty?
+
+            eruption_type   = determine_eruption_type(critical)
+            total_pressure  = critical.sum(&:pressure)
+            avg_pressure    = total_pressure / critical.size
+            intensity       = avg_pressure.clamp(0.0, 1.0)
+
+            critical.each { |m| m.release!(amount: m.pressure) }
+            @magma_deposits.reject!(&:dormant?)
+
+            @temperature = [@temperature - 0.2, 0.0].max
+            @structural_integrity = [@structural_integrity - 0.1, 0.0].max
+            @eruption_count      += 1
+
+            {
+              erupted:         true,
+              chamber_id:      @chamber_id,
+              eruption_type:   eruption_type,
+              intensity:       intensity.round(10),
+              intensity_label: Constants.label_for(Constants::INTENSITY_LABELS, intensity),
+              magma_count:     critical.size,
+              domains:         critical.map(&:domain).uniq,
+              erupted_at:      Time.now.utc
+            }
+          end
+
+          def reinforce!(amount: 0.1)
+            @structural_integrity = [@structural_integrity + amount, 1.0].min
+            @structural_integrity
+          end
+
+          def degrade!(amount: 0.05)
+            @structural_integrity = [@structural_integrity - amount, 0.0].max
+            @structural_integrity
+          end
+
+          def volatile?
+            @magma_deposits.any?(&:critical?) || @structural_integrity < 0.3
+          end
+
+          def stable?
+            !volatile? && @structural_integrity >= 0.7
+          end
+
+          def average_pressure
+            return 0.0 if @magma_deposits.empty?
+
+            @magma_deposits.sum(&:pressure) / @magma_deposits.size
+          end
+
+          ERUPTION_TYPE_MAP = {
+            suppression: :breakthrough,
+            creativity:  :insight,
+            emotion:     :outburst,
+            memory:      :catharsis,
+            frustration: :outburst
+          }.freeze
+
+          def to_h
+            {
+              chamber_id:           @chamber_id,
+              name:                 @name,
+              temperature:          @temperature.round(10),
+              structural_integrity: @structural_integrity.round(10),
+              magma_count:          @magma_deposits.size,
+              average_pressure:     average_pressure.round(10),
+              volatile:             volatile?,
+              stable:               stable?,
+              eruption_count:       @eruption_count,
+              created_at:           @created_at
+            }
+          end
+
+          private
+
+          def determine_eruption_type(critical_deposits)
+            type_counts = critical_deposits.each_with_object(Hash.new(0)) do |m, counts|
+              counts[m.magma_type] += 1
+            end
+
+            dominant = type_counts.max_by { |_type, count| count }&.first
+            ERUPTION_TYPE_MAP.fetch(dominant, :breakthrough)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveVolcano
+      module Helpers
+        module Constants
+          MAGMA_TYPES     = %i[suppression creativity emotion memory frustration].freeze
+          ERUPTION_TYPES  = %i[breakthrough outburst insight catharsis].freeze
+
+          MAX_CHAMBERS       = 100
+          PRESSURE_RATE      = 0.08
+          ERUPTION_THRESHOLD = 0.85
+          COOLDOWN_RATE      = 0.03
+
+          PRESSURE_LABELS = [
+            [0.0..0.2,  :dormant],
+            [0.2..0.4,  :building],
+            [0.4..0.6,  :active],
+            [0.6..0.8,  :elevated],
+            [0.8..1.0,  :critical]
+          ].freeze
+
+          INTENSITY_LABELS = [
+            [0.0..0.2,  :minor],
+            [0.2..0.4,  :moderate],
+            [0.4..0.6,  :significant],
+            [0.6..0.8,  :major],
+            [0.8..1.0,  :cataclysmic]
+          ].freeze
+
+          def self.label_for(table, value)
+            clamped = value.clamp(0.0, 1.0)
+            entry = table.find { |range, _label| range.cover?(clamped) }
+            entry ? entry[1] : table.last[1]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_volcano/helpers/magma.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveVolcano
+      module Helpers
+        class Magma
+          attr_reader :magma_id, :magma_type, :domain, :content, :source, :created_at, :pressure
+
+          def initialize(magma_type:, domain:, content:, source:, pressure: 0.0)
+            unless Constants::MAGMA_TYPES.include?(magma_type)
+              raise ArgumentError, "unknown magma_type: #{magma_type.inspect}; " \
+                                   "must be one of #{Constants::MAGMA_TYPES.inspect}"
+            end
+
+            @magma_id   = SecureRandom.uuid
+            @magma_type = magma_type
+            @domain     = domain
+            @content    = content
+            @source     = source
+            @pressure   = pressure.clamp(0.0, 1.0)
+            @created_at = Time.now.utc
+          end
+
+          def pressurize!(rate: Constants::PRESSURE_RATE)
+            @pressure = (@pressure + rate).clamp(0.0, 1.0)
+            @pressure
+          end
+
+          def release!(amount:)
+            released  = [amount, @pressure].min
+            @pressure = (@pressure - released).clamp(0.0, 1.0)
+            released
+          end
+
+          def critical?
+            @pressure >= Constants::ERUPTION_THRESHOLD
+          end
+
+          def dormant?
+            @pressure < 0.2
+          end
+
+          def pressure_label
+            Constants.label_for(Constants::PRESSURE_LABELS, @pressure)
+          end
+
+          def to_h
+            {
+              magma_id:   @magma_id,
+              magma_type: @magma_type,
+              domain:     @domain,
+              content:    @content,
+              source:     @source,
+              pressure:   @pressure.round(10),
+              label:      pressure_label,
+              critical:   critical?,
+              dormant:    dormant?,
+              created_at: @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_volcano/helpers/volcano_engine.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveVolcano
+      module Helpers
+        class VolcanoEngine
+          attr_reader :eruption_history
+
+          def initialize
+            @chambers        = {}
+            @magma_registry  = {}
+            @eruption_history = []
+          end
+
+          def create_magma(magma_type:, domain:, content:, source:, pressure: 0.0)
+            magma = Magma.new(
+              magma_type: magma_type,
+              domain:     domain,
+              content:    content,
+              source:     source,
+              pressure:   pressure
+            )
+            @magma_registry[magma.magma_id] = magma
+            magma
+          end
+
+          def create_chamber(name:, temperature: 0.5, structural_integrity: 1.0)
+            raise ArgumentError, "chamber limit of #{Constants::MAX_CHAMBERS} reached" if @chambers.size >= Constants::MAX_CHAMBERS
+
+            chamber = Chamber.new(
+              name:                 name,
+              temperature:          temperature,
+              structural_integrity: structural_integrity
+            )
+            @chambers[chamber.chamber_id] = chamber
+            chamber
+          end
+
+          def pressurize_magma(magma_id:, rate: Constants::PRESSURE_RATE)
+            magma = @magma_registry.fetch(magma_id, nil)
+            return nil unless magma
+
+            magma.pressurize!(rate: rate)
+            magma
+          end
+
+          def trigger_eruption(chamber_id:)
+            chamber = @chambers.fetch(chamber_id, nil)
+            return { erupted: false, reason: :chamber_not_found } unless chamber
+
+            result = chamber.erupt!
+            if result[:erupted]
+              @eruption_history << result
+              @eruption_history.shift while @eruption_history.size > 500
+            end
+            result
+          end
+
+          def cool_all!(rate: Constants::COOLDOWN_RATE)
+            cooled = 0
+            @magma_registry.each_value do |magma|
+              next if magma.dormant?
+
+              magma.release!(amount: rate)
+              cooled += 1
+            end
+            cooled
+          end
+
+          def most_volatile
+            return nil if @chambers.empty?
+
+            @chambers.values.max_by(&:average_pressure)
+          end
+
+          def pressure_report
+            chambers_data = @chambers.values.map(&:to_h)
+            critical_magma = @magma_registry.values.select(&:critical?)
+            total_pressure = @magma_registry.values.sum(&:pressure)
+            avg_pressure   = @magma_registry.empty? ? 0.0 : total_pressure / @magma_registry.size
+
+            {
+              total_chambers:    @chambers.size,
+              total_magma:       @magma_registry.size,
+              critical_count:    critical_magma.size,
+              average_pressure:  avg_pressure.round(10),
+              pressure_label:    Constants.label_for(Constants::PRESSURE_LABELS, avg_pressure),
+              volatile_chambers: @chambers.values.count(&:volatile?),
+              eruption_count:    @eruption_history.size,
+              chambers:          chambers_data
+            }
+          end
+
+          def get_chamber(chamber_id)
+            @chambers[chamber_id]
+          end
+
+          def get_magma(magma_id)
+            @magma_registry[magma_id]
+          end
+
+          def all_chambers
+            @chambers.values
+          end
+
+          def all_magma
+            @magma_registry.values
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveVolcano
+      module Runners
+        module CognitiveVolcano
+          extend self
+
+          include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+          def create_magma(magma_type:, domain:, content:, source:, pressure: 0.0, engine: nil, **)
+            unless Helpers::Constants::MAGMA_TYPES.include?(magma_type)
+              return { success: false, error: :invalid_magma_type, valid_types: Helpers::Constants::MAGMA_TYPES }
+            end
+
+            magma = resolve_engine(engine).create_magma(
+              magma_type: magma_type,
+              domain:     domain,
+              content:    content,
+              source:     source,
+              pressure:   pressure
+            )
+
+            Legion::Logging.debug "[cognitive_volcano] created magma type=#{magma_type} domain=#{domain} " \
+                                  "pressure=#{magma.pressure.round(2)} id=#{magma.magma_id[0..7]}"
+
+            { success: true, magma: magma.to_h }
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def create_chamber(name:, temperature: 0.5, structural_integrity: 1.0, engine: nil, **)
+            chamber = resolve_engine(engine).create_chamber(
+              name:                 name,
+              temperature:          temperature,
+              structural_integrity: structural_integrity
+            )
+
+            Legion::Logging.debug "[cognitive_volcano] created chamber name=#{name} id=#{chamber.chamber_id[0..7]}"
+
+            { success: true, chamber: chamber.to_h }
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def pressurize(magma_id:, rate: Helpers::Constants::PRESSURE_RATE, engine: nil, **)
+            magma = resolve_engine(engine).pressurize_magma(magma_id: magma_id, rate: rate)
+            return { success: false, error: :magma_not_found, magma_id: magma_id } unless magma
+
+            Legion::Logging.debug "[cognitive_volcano] pressurized magma=#{magma_id[0..7]} " \
+                                  "pressure=#{magma.pressure.round(2)} critical=#{magma.critical?}"
+
+            { success: true, magma: magma.to_h }
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def trigger_eruption(chamber_id:, engine: nil, **)
+            result = resolve_engine(engine).trigger_eruption(chamber_id: chamber_id)
+
+            if result[:erupted]
+              Legion::Logging.info "[cognitive_volcano] eruption! chamber=#{chamber_id[0..7]} " \
+                                   "type=#{result[:eruption_type]} intensity=#{result[:intensity_label]}"
+            else
+              Legion::Logging.debug "[cognitive_volcano] no eruption chamber=#{chamber_id[0..7]} reason=#{result[:reason]}"
+            end
+
+            result.merge(success: result[:erupted])
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def list_chambers(engine: nil, **)
+            chambers = resolve_engine(engine).all_chambers.map(&:to_h)
+            Legion::Logging.debug "[cognitive_volcano] list_chambers count=#{chambers.size}"
+            { success: true, chambers: chambers, count: chambers.size }
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def pressure_status(engine: nil, **)
+            report = resolve_engine(engine).pressure_report
+            Legion::Logging.debug "[cognitive_volcano] pressure_status avg=#{report[:pressure_label]} " \
+                                  "critical=#{report[:critical_count]}"
+            report.merge(success: true)
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          private
+
+          def resolve_engine(engine)
+            engine || volcano_engine
+          end
+
+          def volcano_engine
+            @volcano_engine ||= Helpers::VolcanoEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/cognitive_volcano.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require_relative 'cognitive_volcano/version'
+require_relative 'cognitive_volcano/helpers/constants'
+require_relative 'cognitive_volcano/helpers/magma'
+require_relative 'cognitive_volcano/helpers/chamber'
+require_relative 'cognitive_volcano/helpers/volcano_engine'
+require_relative 'cognitive_volcano/runners/cognitive_volcano'
+require_relative 'cognitive_volcano/client'
+
+module Legion
+  module Extensions
+    module CognitiveVolcano
+      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-volcano
+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 cognitive pressure buildup and eruption cycles — suppressed thoughts
+  accumulate pressure (like magma) until they erupt as breakthroughs, emotional outbursts,
+  or creative explosions
+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-volcano.gemspec
+- lib/legion/extensions/cognitive_volcano.rb
+- lib/legion/extensions/cognitive_volcano/client.rb
+- lib/legion/extensions/cognitive_volcano/helpers/chamber.rb
+- lib/legion/extensions/cognitive_volcano/helpers/constants.rb
+- lib/legion/extensions/cognitive_volcano/helpers/magma.rb
+- lib/legion/extensions/cognitive_volcano/helpers/volcano_engine.rb
+- lib/legion/extensions/cognitive_volcano/runners/cognitive_volcano.rb
+- lib/legion/extensions/cognitive_volcano/version.rb
+homepage: https://github.com/LegionIO/lex-cognitive-volcano
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-cognitive-volcano
+  source_code_uri: https://github.com/LegionIO/lex-cognitive-volcano
+  documentation_uri: https://github.com/LegionIO/lex-cognitive-volcano
+  changelog_uri: https://github.com/LegionIO/lex-cognitive-volcano
+  bug_tracker_uri: https://github.com/LegionIO/lex-cognitive-volcano/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 Cognitive Volcano
+test_files: []