lex-cognitive-catalyst 0.1.0

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

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveCatalyst
+      module Runners
+        module CognitiveCatalyst
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def create_catalyst(catalyst_type:, domain:, potency: nil, specificity: nil, engine: nil, **)
+            e = engine || default_engine
+            unless Helpers::Constants::CATALYST_TYPES.include?(catalyst_type.to_sym)
+              raise ArgumentError, "invalid catalyst_type: #{catalyst_type}"
+            end
+
+            opts = {
+              catalyst_type: catalyst_type.to_sym,
+              domain:        domain
+            }
+            opts[:potency]     = potency     unless potency.nil?
+            opts[:specificity] = specificity unless specificity.nil?
+
+            catalyst = e.create_catalyst(**opts)
+            Legion::Logging.debug "[cognitive_catalyst] create_catalyst id=#{catalyst.id[0..7]} " \
+                                  "type=#{catalyst_type} domain=#{domain} potency=#{catalyst.potency.round(2)}"
+            { success: true, catalyst: catalyst.to_h }
+          rescue ArgumentError => e
+            Legion::Logging.warn "[cognitive_catalyst] create_catalyst failed: #{e.message}"
+            { success: false, reason: e.message }
+          end
+
+          def create_reaction(reaction_type:, reactants:, activation_energy: nil, engine: nil, **)
+            e = engine || default_engine
+            unless Helpers::Constants::REACTION_TYPES.include?(reaction_type.to_sym)
+              raise ArgumentError, "invalid reaction_type: #{reaction_type}"
+            end
+
+            opts = {
+              reaction_type: reaction_type.to_sym,
+              reactants:     Array(reactants)
+            }
+            opts[:activation_energy] = activation_energy unless activation_energy.nil?
+
+            reaction = e.create_reaction(**opts)
+            Legion::Logging.debug "[cognitive_catalyst] create_reaction id=#{reaction.id[0..7]} " \
+                                  "type=#{reaction_type} reactants=#{reaction.reactants.size}"
+            { success: true, reaction: reaction.to_h }
+          rescue ArgumentError => e
+            Legion::Logging.warn "[cognitive_catalyst] create_reaction failed: #{e.message}"
+            { success: false, reason: e.message }
+          end
+
+          def apply_catalyst(catalyst_id:, reaction_id:, engine: nil, **)
+            e = engine || default_engine
+            result = e.apply_catalyst(catalyst_id: catalyst_id, reaction_id: reaction_id)
+            Legion::Logging.debug '[cognitive_catalyst] apply_catalyst ' \
+                                  "catalyst=#{catalyst_id[0..7]} reaction=#{reaction_id[0..7]} " \
+                                  "success=#{result[:success]}"
+            result
+          end
+
+          def attempt_reaction(reaction_id:, energy_input:, engine: nil, **)
+            e = engine || default_engine
+            result = e.attempt_reaction(reaction_id: reaction_id, energy_input: energy_input)
+            Legion::Logging.debug "[cognitive_catalyst] attempt_reaction id=#{reaction_id[0..7]} " \
+                                  "energy=#{energy_input} completed=#{result[:completed]}"
+            result
+          end
+
+          def recharge(catalyst_id:, amount:, engine: nil, **)
+            e = engine || default_engine
+            result = e.recharge_catalyst(catalyst_id: catalyst_id, amount: amount)
+            Legion::Logging.debug "[cognitive_catalyst] recharge id=#{catalyst_id[0..7]} " \
+                                  "amount=#{amount} potency=#{result[:potency]&.round(2)}"
+            result
+          end
+
+          def list_catalysts(engine: nil, **)
+            e = engine || default_engine
+            catalysts = e.all_catalysts
+            Legion::Logging.debug "[cognitive_catalyst] list_catalysts count=#{catalysts.size}"
+            { success: true, catalysts: catalysts.map(&:to_h), count: catalysts.size }
+          end
+
+          def catalyst_status(engine: nil, **)
+            e = engine || default_engine
+            report = e.catalyst_report
+            Legion::Logging.debug "[cognitive_catalyst] catalyst_status total=#{report[:total_catalysts]} " \
+                                  "reactions=#{report[:total_reactions]} rate=#{report[:catalyzed_rate].round(2)}"
+            { success: true }.merge(report)
+          end
+
+          private
+
+          def default_engine
+            @default_engine ||= Helpers::CatalystEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/cognitive_catalyst.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+require_relative 'cognitive_catalyst/version'
+require_relative 'cognitive_catalyst/helpers/constants'
+require_relative 'cognitive_catalyst/helpers/catalyst'
+require_relative 'cognitive_catalyst/helpers/reaction'
+require_relative 'cognitive_catalyst/helpers/catalyst_engine'
+require_relative 'cognitive_catalyst/runners/cognitive_catalyst'
+require_relative 'cognitive_catalyst/client'
+
+module Legion
+  module Extensions
+    module CognitiveCatalyst
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined?(:Core)
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::CognitiveCatalyst::Client do
+  subject(:client) { described_class.new }
+
+  it 'includes Runners::CognitiveCatalyst' do
+    expect(client).to respond_to(:create_catalyst)
+    expect(client).to respond_to(:create_reaction)
+    expect(client).to respond_to(:apply_catalyst)
+    expect(client).to respond_to(:attempt_reaction)
+    expect(client).to respond_to(:recharge)
+    expect(client).to respond_to(:list_catalysts)
+    expect(client).to respond_to(:catalyst_status)
+  end
+
+  it 'can create and then apply a catalyst to a reaction' do
+    engine = Legion::Extensions::CognitiveCatalyst::Helpers::CatalystEngine.new
+    cat = client.create_catalyst(catalyst_type: :experience, domain: :learning,
+                                 potency: 0.9, specificity: 0.9, engine: engine)
+    rxn = client.create_reaction(reaction_type: :synthesis, reactants: %w[a b], engine: engine)
+    result = client.apply_catalyst(catalyst_id: cat[:catalyst][:id],
+                                   reaction_id: rxn[:reaction][:id],
+                                   engine:      engine)
+    expect(result[:success]).to be true
+    expect(result[:activation_energy]).to be < 0.6
+  end
+
+  it 'can complete a full catalyst workflow: create -> apply -> attempt -> report' do
+    engine = Legion::Extensions::CognitiveCatalyst::Helpers::CatalystEngine.new
+    cat = client.create_catalyst(catalyst_type: :insight, domain: :reasoning,
+                                 potency: 1.0, specificity: 1.0, engine: engine)
+    rxn = client.create_reaction(reaction_type:     :decomposition,
+                                 reactants:         %w[complex_idea],
+                                 activation_energy: 0.1,
+                                 engine:            engine)
+    client.apply_catalyst(catalyst_id: cat[:catalyst][:id],
+                          reaction_id: rxn[:reaction][:id],
+                          engine:      engine)
+    result = client.attempt_reaction(reaction_id:  rxn[:reaction][:id],
+                                     energy_input: 0.8,
+                                     engine:       engine)
+    expect(result[:completed]).to be true
+    expect(result[:catalyzed]).to be true
+    status = client.catalyst_status(engine: engine)
+    expect(status[:catalyzed_count]).to eq(1)
+    expect(status[:catalyzed_rate]).to eq(1.0)
+  end
+
+  it 'maintains separate state per client instance' do
+    c1 = described_class.new
+    c2 = described_class.new
+    c1.create_catalyst(catalyst_type: :insight, domain: :d)
+    s1 = c1.catalyst_status
+    s2 = c2.catalyst_status
+    expect(s1[:total_catalysts]).to eq(1)
+    expect(s2[:total_catalysts]).to eq(0)
+  end
+end

data/spec/legion/extensions/cognitive_catalyst/helpers/catalyst_engine_spec.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::CognitiveCatalyst::Helpers::CatalystEngine do
+  subject(:engine) { described_class.new }
+
+  let(:constants) { Legion::Extensions::CognitiveCatalyst::Helpers::Constants }
+
+  def build_catalyst(potency: 0.7, specificity: 0.6)
+    engine.create_catalyst(catalyst_type: :insight, domain: :reasoning,
+                           potency: potency, specificity: specificity)
+  end
+
+  def build_reaction(activation_energy: nil)
+    opts = { reaction_type: :synthesis, reactants: %w[a b] }
+    opts[:activation_energy] = activation_energy if activation_energy
+    engine.create_reaction(**opts)
+  end
+
+  describe '#create_catalyst' do
+    it 'creates and returns a Catalyst' do
+      result = build_catalyst
+      expect(result).to be_a(Legion::Extensions::CognitiveCatalyst::Helpers::Catalyst)
+    end
+
+    it 'stores the catalyst' do
+      build_catalyst
+      expect(engine.all_catalysts.size).to eq(1)
+    end
+
+    it 'accepts all valid catalyst types' do
+      constants::CATALYST_TYPES.each do |type|
+        expect { engine.create_catalyst(catalyst_type: type, domain: :d) }.not_to raise_error
+      end
+    end
+
+    it 'raises ArgumentError for invalid catalyst_type' do
+      expect { engine.create_catalyst(catalyst_type: :invalid, domain: :d) }.to raise_error(ArgumentError)
+    end
+
+    it 'evicts oldest when at MAX_CATALYSTS capacity' do
+      max = constants::MAX_CATALYSTS
+      max.times { |i| engine.create_catalyst(catalyst_type: :insight, domain: "d#{i}") }
+      engine.create_catalyst(catalyst_type: :analogy, domain: :overflow)
+      expect(engine.all_catalysts.size).to eq(max)
+    end
+  end
+
+  describe '#create_reaction' do
+    it 'creates and returns a Reaction' do
+      result = build_reaction
+      expect(result).to be_a(Legion::Extensions::CognitiveCatalyst::Helpers::Reaction)
+    end
+
+    it 'stores the reaction' do
+      build_reaction
+      expect(engine.all_reactions.size).to eq(1)
+    end
+
+    it 'accepts all valid reaction types' do
+      constants::REACTION_TYPES.each do |type|
+        expect { engine.create_reaction(reaction_type: type, reactants: ['x']) }.not_to raise_error
+      end
+    end
+
+    it 'raises ArgumentError for invalid reaction_type' do
+      expect { engine.create_reaction(reaction_type: :explode, reactants: []) }.to raise_error(ArgumentError)
+    end
+
+    it 'evicts oldest when at MAX_REACTIONS capacity' do
+      max = constants::MAX_REACTIONS
+      max.times { |i| engine.create_reaction(reaction_type: :synthesis, reactants: ["r#{i}"]) }
+      engine.create_reaction(reaction_type: :exchange, reactants: [:overflow])
+      expect(engine.all_reactions.size).to eq(max)
+    end
+  end
+
+  describe '#apply_catalyst' do
+    let(:catalyst) { build_catalyst }
+    let(:reaction) { build_reaction }
+
+    it 'returns success with updated activation_energy' do
+      result = engine.apply_catalyst(catalyst_id: catalyst.id, reaction_id: reaction.id)
+      expect(result[:success]).to be true
+      expect(result[:activation_energy]).to be < constants::ACTIVATION_ENERGY
+    end
+
+    it 'returns catalyst_not_found for unknown catalyst' do
+      result = engine.apply_catalyst(catalyst_id: 'bad', reaction_id: reaction.id)
+      expect(result[:reason]).to eq(:catalyst_not_found)
+    end
+
+    it 'returns reaction_not_found for unknown reaction' do
+      result = engine.apply_catalyst(catalyst_id: catalyst.id, reaction_id: 'bad')
+      expect(result[:reason]).to eq(:reaction_not_found)
+    end
+
+    it 'returns already_completed for a done reaction' do
+      engine.attempt_reaction(reaction_id: reaction.id, energy_input: 1.0)
+      result = engine.apply_catalyst(catalyst_id: catalyst.id, reaction_id: reaction.id)
+      expect(result[:reason]).to eq(:already_completed)
+    end
+  end
+
+  describe '#attempt_reaction' do
+    let(:reaction) { build_reaction }
+
+    it 'completes the reaction when energy is sufficient' do
+      result = engine.attempt_reaction(reaction_id: reaction.id, energy_input: 1.0)
+      expect(result[:completed]).to be true
+    end
+
+    it 'does not complete when energy is insufficient' do
+      result = engine.attempt_reaction(reaction_id: reaction.id, energy_input: 0.1)
+      expect(result[:completed]).to be false
+    end
+
+    it 'returns not_found for unknown reaction' do
+      result = engine.attempt_reaction(reaction_id: 'missing', energy_input: 1.0)
+      expect(result[:reason]).to eq(:not_found)
+    end
+
+    it 'returns already_completed for a done reaction' do
+      engine.attempt_reaction(reaction_id: reaction.id, energy_input: 1.0)
+      result = engine.attempt_reaction(reaction_id: reaction.id, energy_input: 1.0)
+      expect(result[:reason]).to eq(:already_completed)
+    end
+
+    it 'includes yield_value and yield_label' do
+      result = engine.attempt_reaction(reaction_id: reaction.id, energy_input: 1.0)
+      expect(result).to include(:yield_value, :yield_label)
+    end
+  end
+
+  describe '#degrade_all!' do
+    it 'reduces potency of all catalysts' do
+      c = build_catalyst(potency: 0.8)
+      engine.degrade_all!
+      expect(c.potency).to be < 0.8
+    end
+
+    it 'does nothing when no catalysts exist' do
+      expect { engine.degrade_all! }.not_to raise_error
+    end
+  end
+
+  describe '#recharge_catalyst' do
+    let(:catalyst) { build_catalyst(potency: 0.3) }
+
+    it 'increases potency' do
+      result = engine.recharge_catalyst(catalyst_id: catalyst.id, amount: 0.2)
+      expect(result[:success]).to be true
+      expect(result[:potency]).to be_within(0.001).of(0.5)
+    end
+
+    it 'returns not_found for unknown catalyst' do
+      result = engine.recharge_catalyst(catalyst_id: 'bad', amount: 0.1)
+      expect(result[:reason]).to eq(:not_found)
+    end
+
+    it 'includes potency_label in result' do
+      result = engine.recharge_catalyst(catalyst_id: catalyst.id, amount: 0.6)
+      expect(result).to include(:potency_label)
+    end
+  end
+
+  describe '#all_catalysts' do
+    it 'returns empty array initially' do
+      expect(engine.all_catalysts).to eq([])
+    end
+
+    it 'returns all stored catalysts' do
+      2.times { build_catalyst }
+      expect(engine.all_catalysts.size).to eq(2)
+    end
+  end
+
+  describe '#all_reactions' do
+    it 'returns empty array initially' do
+      expect(engine.all_reactions).to eq([])
+    end
+
+    it 'returns all stored reactions' do
+      2.times { build_reaction }
+      expect(engine.all_reactions.size).to eq(2)
+    end
+  end
+
+  describe '#completed_reactions' do
+    it 'returns only completed reactions' do
+      r1 = build_reaction
+      r2 = build_reaction
+      engine.attempt_reaction(reaction_id: r1.id, energy_input: 1.0)
+      engine.attempt_reaction(reaction_id: r2.id, energy_input: 0.1)
+      expect(engine.completed_reactions.size).to eq(1)
+    end
+  end
+
+  describe '#catalyzed_rate' do
+    it 'returns 0.0 when no reactions completed' do
+      expect(engine.catalyzed_rate).to eq(0.0)
+    end
+
+    it 'returns 1.0 when all completed reactions were catalyzed' do
+      catalyst = build_catalyst(potency: 1.0, specificity: 1.0)
+      reaction = build_reaction(activation_energy: 0.01)
+      engine.apply_catalyst(catalyst_id: catalyst.id, reaction_id: reaction.id)
+      engine.attempt_reaction(reaction_id: reaction.id, energy_input: 1.0)
+      expect(engine.catalyzed_rate).to eq(1.0)
+    end
+
+    it 'returns 0.0 when no completed reactions were catalyzed' do
+      reaction = build_reaction
+      engine.attempt_reaction(reaction_id: reaction.id, energy_input: 1.0)
+      expect(engine.catalyzed_rate).to eq(0.0)
+    end
+
+    it 'returns fractional rate for mixed completions' do
+      r1 = build_reaction
+      r2 = build_reaction
+      engine.attempt_reaction(reaction_id: r1.id, energy_input: 1.0)
+      catalyst = build_catalyst(potency: 1.0, specificity: 1.0)
+      engine.apply_catalyst(catalyst_id: catalyst.id, reaction_id: r2.id)
+      engine.attempt_reaction(reaction_id: r2.id, energy_input: 1.0)
+      expect(engine.catalyzed_rate).to be_within(0.01).of(0.5)
+    end
+  end
+
+  describe '#catalyst_report' do
+    it 'returns a report hash with all required keys' do
+      report = engine.catalyst_report
+      expect(report).to include(
+        :total_catalysts, :total_reactions, :completed, :catalyzed_count,
+        :catalyzed_rate, :avg_potency, :powerful_count, :inert_count
+      )
+    end
+
+    it 'counts powerful catalysts' do
+      build_catalyst(potency: 0.9)
+      build_catalyst(potency: 0.5)
+      report = engine.catalyst_report
+      expect(report[:powerful_count]).to eq(1)
+    end
+
+    it 'counts inert catalysts' do
+      engine.create_catalyst(catalyst_type: :insight, domain: :d, potency: 0.1)
+      engine.create_catalyst(catalyst_type: :insight, domain: :d, potency: 0.5)
+      report = engine.catalyst_report
+      expect(report[:inert_count]).to eq(1)
+    end
+
+    it 'computes avg_potency' do
+      engine.create_catalyst(catalyst_type: :insight, domain: :d, potency: 0.4)
+      engine.create_catalyst(catalyst_type: :insight, domain: :d, potency: 0.6)
+      report = engine.catalyst_report
+      expect(report[:avg_potency]).to be_within(0.01).of(0.5)
+    end
+
+    it 'returns avg_potency of 0.0 when no catalysts' do
+      report = engine.catalyst_report
+      expect(report[:avg_potency]).to eq(0.0)
+    end
+  end
+end

data/spec/legion/extensions/cognitive_catalyst/helpers/catalyst_spec.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::CognitiveCatalyst::Helpers::Catalyst do
+  subject(:catalyst) { described_class.new(catalyst_type: :insight, domain: :reasoning) }
+
+  describe '#initialize' do
+    it 'assigns a uuid id' do
+      expect(catalyst.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'assigns catalyst_type' do
+      expect(catalyst.catalyst_type).to eq(:insight)
+    end
+
+    it 'assigns domain' do
+      expect(catalyst.domain).to eq(:reasoning)
+    end
+
+    it 'defaults potency to 0.5' do
+      expect(catalyst.potency).to eq(0.5)
+    end
+
+    it 'defaults specificity to 0.5' do
+      expect(catalyst.specificity).to eq(0.5)
+    end
+
+    it 'defaults uses_count to 0' do
+      expect(catalyst.uses_count).to eq(0)
+    end
+
+    it 'records created_at' do
+      expect(catalyst.created_at).to be_a(Time)
+    end
+
+    it 'clamps potency above 1.0' do
+      c = described_class.new(catalyst_type: :analogy, domain: :d, potency: 2.0)
+      expect(c.potency).to eq(1.0)
+    end
+
+    it 'clamps potency below 0.0' do
+      c = described_class.new(catalyst_type: :analogy, domain: :d, potency: -0.5)
+      expect(c.potency).to eq(0.0)
+    end
+
+    it 'clamps specificity above 1.0' do
+      c = described_class.new(catalyst_type: :analogy, domain: :d, specificity: 5.0)
+      expect(c.specificity).to eq(1.0)
+    end
+
+    it 'accepts custom potency' do
+      c = described_class.new(catalyst_type: :pattern, domain: :d, potency: 0.9)
+      expect(c.potency).to eq(0.9)
+    end
+  end
+
+  describe '#catalyze!' do
+    it 'increments uses_count each call' do
+      catalyst.catalyze!(:synthesis)
+      catalyst.catalyze!(:synthesis)
+      expect(catalyst.uses_count).to eq(2)
+    end
+
+    it 'returns activation_reduction = potency * specificity' do
+      c = described_class.new(catalyst_type: :insight, domain: :d, potency: 0.8, specificity: 0.5)
+      reduction = c.catalyze!(:synthesis)
+      expect(reduction).to be_within(0.0001).of(0.4)
+    end
+
+    it 'does NOT reduce potency (catalysts are not consumed)' do
+      original = catalyst.potency
+      catalyst.catalyze!(:synthesis)
+      expect(catalyst.potency).to eq(original)
+    end
+
+    it 'returns a float' do
+      expect(catalyst.catalyze!(:exchange)).to be_a(Float)
+    end
+
+    it 'works with all reaction types' do
+      Legion::Extensions::CognitiveCatalyst::Helpers::Constants::REACTION_TYPES.each do |rt|
+        expect { catalyst.catalyze!(rt) }.not_to raise_error
+      end
+    end
+  end
+
+  describe '#degrade!' do
+    it 'reduces potency by POTENCY_DECAY' do
+      decay = Legion::Extensions::CognitiveCatalyst::Helpers::Constants::POTENCY_DECAY
+      original = catalyst.potency
+      catalyst.degrade!
+      expect(catalyst.potency).to be_within(0.0001).of(original - decay)
+    end
+
+    it 'does not reduce potency below 0.0' do
+      c = described_class.new(catalyst_type: :insight, domain: :d, potency: 0.01)
+      c.degrade!
+      expect(c.potency).to eq(0.0)
+    end
+
+    it 'can be called multiple times' do
+      5.times { catalyst.degrade! }
+      expect(catalyst.potency).to be >= 0.0
+      expect(catalyst.potency).to be < 0.5
+    end
+  end
+
+  describe '#recharge!' do
+    it 'increases potency by amount' do
+      c = described_class.new(catalyst_type: :insight, domain: :d, potency: 0.3)
+      c.recharge!(0.2)
+      expect(c.potency).to be_within(0.0001).of(0.5)
+    end
+
+    it 'clamps at 1.0' do
+      c = described_class.new(catalyst_type: :insight, domain: :d, potency: 0.9)
+      c.recharge!(0.5)
+      expect(c.potency).to eq(1.0)
+    end
+
+    it 'returns the new potency' do
+      result = catalyst.recharge!(0.1)
+      expect(result).to be_a(Float)
+    end
+  end
+
+  describe '#powerful?' do
+    it 'returns true for potency >= 0.8' do
+      c = described_class.new(catalyst_type: :insight, domain: :d, potency: 0.8)
+      expect(c.powerful?).to be true
+    end
+
+    it 'returns false for potency < 0.8' do
+      c = described_class.new(catalyst_type: :insight, domain: :d, potency: 0.7)
+      expect(c.powerful?).to be false
+    end
+  end
+
+  describe '#inert?' do
+    it 'returns true for potency < 0.2' do
+      c = described_class.new(catalyst_type: :insight, domain: :d, potency: 0.1)
+      expect(c.inert?).to be true
+    end
+
+    it 'returns false for potency >= 0.2' do
+      c = described_class.new(catalyst_type: :insight, domain: :d, potency: 0.2)
+      expect(c.inert?).to be false
+    end
+  end
+
+  describe '#specific?' do
+    it 'returns true for specificity >= 0.7' do
+      c = described_class.new(catalyst_type: :insight, domain: :d, specificity: 0.7)
+      expect(c.specific?).to be true
+    end
+
+    it 'returns false for specificity < 0.7' do
+      c = described_class.new(catalyst_type: :insight, domain: :d, specificity: 0.6)
+      expect(c.specific?).to be false
+    end
+  end
+
+  describe '#broad?' do
+    it 'returns true for specificity < 0.3' do
+      c = described_class.new(catalyst_type: :insight, domain: :d, specificity: 0.2)
+      expect(c.broad?).to be true
+    end
+
+    it 'returns false for specificity >= 0.3' do
+      c = described_class.new(catalyst_type: :insight, domain: :d, specificity: 0.3)
+      expect(c.broad?).to be false
+    end
+  end
+
+  describe '#potency_label' do
+    it 'returns :powerful for potency >= 0.8' do
+      c = described_class.new(catalyst_type: :insight, domain: :d, potency: 0.9)
+      expect(c.potency_label).to eq(:powerful)
+    end
+
+    it 'returns :strong for potency in 0.6...0.8' do
+      c = described_class.new(catalyst_type: :insight, domain: :d, potency: 0.7)
+      expect(c.potency_label).to eq(:strong)
+    end
+
+    it 'returns :moderate for potency in 0.4...0.6' do
+      c = described_class.new(catalyst_type: :insight, domain: :d, potency: 0.5)
+      expect(c.potency_label).to eq(:moderate)
+    end
+
+    it 'returns :weak for potency in 0.2...0.4' do
+      c = described_class.new(catalyst_type: :insight, domain: :d, potency: 0.3)
+      expect(c.potency_label).to eq(:weak)
+    end
+
+    it 'returns :inert for potency < 0.2' do
+      c = described_class.new(catalyst_type: :insight, domain: :d, potency: 0.1)
+      expect(c.potency_label).to eq(:inert)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with all required keys' do
+      h = catalyst.to_h
+      expect(h).to include(:id, :catalyst_type, :domain, :potency, :specificity,
+                           :uses_count, :potency_label, :powerful, :inert,
+                           :specific, :broad, :created_at)
+    end
+
+    it 'reflects current state' do
+      catalyst.catalyze!(:synthesis)
+      expect(catalyst.to_h[:uses_count]).to eq(1)
+    end
+  end
+end