lex-agentic-integration 0.1.0

data/spec/legion/extensions/agentic/integration/phenomenal_binding/helpers/binding_engine_spec.rb

@@ -0,0 +1,290 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Integration::PhenomenalBinding::Helpers::BindingEngine do
+  subject(:engine) { described_class.new }
+
+  let(:stream_mod) { Legion::Extensions::Agentic::Integration::PhenomenalBinding::Helpers::Stream }
+
+  def register_n_streams(count, salience: 0.7)
+    count.times.map do |i|
+      engine.register_stream(stream_type: :perception, content: "content #{i}", salience: salience)
+    end
+  end
+
+  describe '#register_stream' do
+    it 'returns a Stream' do
+      stream = engine.register_stream(stream_type: :thought, content: 'hello')
+      expect(stream).to be_a(stream_mod)
+    end
+
+    it 'uses the given stream_type' do
+      stream = engine.register_stream(stream_type: :emotion, content: 'joy')
+      expect(stream.stream_type).to eq(:emotion)
+    end
+
+    it 'uses the given salience' do
+      stream = engine.register_stream(stream_type: :memory, content: 'old', salience: 0.9)
+      expect(stream.salience).to eq(0.9)
+    end
+
+    it 'stores stream internally' do
+      stream = engine.register_stream(stream_type: :prediction, content: 'rain')
+      stats = engine.to_h
+      expect(stats[:stream_count]).to eq(1)
+      expect(engine.unbound_streams.map(&:id)).to include(stream.id)
+    end
+
+    it 'prunes oldest stream when MAX_STREAMS exceeded' do
+      101.times { |i| engine.register_stream(stream_type: :perception, content: "s#{i}") }
+      expect(engine.to_h[:stream_count]).to eq(100)
+    end
+  end
+
+  describe '#create_binding' do
+    it 'returns a BindingUnit' do
+      s = engine.register_stream(stream_type: :perception, content: 'x')
+      binding = engine.create_binding(stream_ids: [s.id], binding_type: :perceptual)
+      expect(binding).to be_a(Legion::Extensions::Agentic::Integration::PhenomenalBinding::Helpers::BindingUnit)
+    end
+
+    it 'computes initial coherence from stream saliences' do
+      s1 = engine.register_stream(stream_type: :perception, content: 'a', salience: 0.8)
+      s2 = engine.register_stream(stream_type: :thought, content: 'b', salience: 0.6)
+      binding = engine.create_binding(stream_ids: [s1.id, s2.id], binding_type: :conceptual)
+      expect(binding.coherence).to be_within(0.001).of(0.7)
+    end
+
+    it 'ignores stream_ids that are not registered' do
+      s = engine.register_stream(stream_type: :perception, content: 'real')
+      binding = engine.create_binding(stream_ids: [s.id, 'ghost-id'], binding_type: :temporal)
+      expect(binding.stream_ids).to eq([s.id])
+    end
+
+    it 'stores binding internally' do
+      s = engine.register_stream(stream_type: :memory, content: 'y')
+      engine.create_binding(stream_ids: [s.id], binding_type: :narrative)
+      expect(engine.to_h[:binding_count]).to eq(1)
+    end
+
+    it 'sets attention_weight' do
+      s = engine.register_stream(stream_type: :intention, content: 'z')
+      binding = engine.create_binding(stream_ids: [s.id], binding_type: :emotional, attention_weight: 0.9)
+      expect(binding.attention_weight).to eq(0.9)
+    end
+
+    it 'prunes oldest binding when MAX_BINDINGS exceeded' do
+      s = engine.register_stream(stream_type: :perception, content: 'base')
+      201.times { engine.create_binding(stream_ids: [s.id], binding_type: :perceptual) }
+      expect(engine.to_h[:binding_count]).to eq(200)
+    end
+  end
+
+  describe '#reinforce_binding' do
+    it 'increases coherence' do
+      s = engine.register_stream(stream_type: :thought, content: 'q')
+      binding = engine.create_binding(stream_ids: [s.id], binding_type: :conceptual, attention_weight: 0.5)
+      initial_coherence = binding.coherence
+      engine.reinforce_binding(binding_id: binding.id)
+      expect(binding.coherence).to be > initial_coherence
+    end
+
+    it 'returns reinforced status with coherence' do
+      s = engine.register_stream(stream_type: :perception, content: 'r')
+      binding = engine.create_binding(stream_ids: [s.id], binding_type: :perceptual)
+      result = engine.reinforce_binding(binding_id: binding.id)
+      expect(result[:status]).to eq(:reinforced)
+      expect(result[:coherence]).to be_a(Float)
+    end
+
+    it 'returns not_found for unknown binding_id' do
+      result = engine.reinforce_binding(binding_id: 'no-such-id')
+      expect(result[:status]).to eq(:not_found)
+    end
+  end
+
+  describe '#dissolve_binding' do
+    it 'removes the binding' do
+      s = engine.register_stream(stream_type: :emotion, content: 'fear')
+      binding = engine.create_binding(stream_ids: [s.id], binding_type: :emotional)
+      engine.dissolve_binding(binding_id: binding.id)
+      expect(engine.to_h[:binding_count]).to eq(0)
+    end
+
+    it 'returns dissolved status' do
+      s = engine.register_stream(stream_type: :memory, content: 'past')
+      binding = engine.create_binding(stream_ids: [s.id], binding_type: :narrative)
+      result = engine.dissolve_binding(binding_id: binding.id)
+      expect(result[:status]).to eq(:dissolved)
+    end
+
+    it 'returns not_found for unknown binding_id' do
+      result = engine.dissolve_binding(binding_id: 'ghost')
+      expect(result[:status]).to eq(:not_found)
+    end
+  end
+
+  describe '#unified_experience' do
+    it 'returns nil when no bindings exist' do
+      expect(engine.unified_experience).to be_nil
+    end
+
+    it 'returns nil when no coherent bindings exist' do
+      s = engine.register_stream(stream_type: :perception, content: 'dim', salience: 0.1)
+      engine.create_binding(stream_ids: [s.id], binding_type: :perceptual)
+      expect(engine.unified_experience).to be_nil
+    end
+
+    it 'returns the strongest coherent binding' do
+      s1 = engine.register_stream(stream_type: :perception, content: 'a', salience: 0.8)
+      s2 = engine.register_stream(stream_type: :thought, content: 'b', salience: 0.9)
+      engine.create_binding(stream_ids: [s1.id], binding_type: :perceptual, attention_weight: 0.5)
+      b2 = engine.create_binding(stream_ids: [s2.id], binding_type: :conceptual, attention_weight: 0.9)
+      experience = engine.unified_experience
+      # b2 has higher coherence * attention_weight
+      expect(experience.id).to eq(b2.id)
+    end
+  end
+
+  describe '#fragmentation_index' do
+    it 'returns 0.0 when no streams registered' do
+      expect(engine.fragmentation_index).to eq(0.0)
+    end
+
+    it 'returns 1.0 when all streams are unbound' do
+      register_n_streams(3)
+      expect(engine.fragmentation_index).to eq(1.0)
+    end
+
+    it 'returns 0.0 when all streams are bound' do
+      streams = register_n_streams(2)
+      engine.create_binding(stream_ids: streams.map(&:id), binding_type: :perceptual)
+      expect(engine.fragmentation_index).to eq(0.0)
+    end
+
+    it 'returns partial fraction for partially bound streams' do
+      streams = register_n_streams(4)
+      engine.create_binding(stream_ids: [streams[0].id, streams[1].id], binding_type: :temporal)
+      expect(engine.fragmentation_index).to be_within(0.001).of(0.5)
+    end
+  end
+
+  describe '#binding_by_type' do
+    it 'returns bindings of the given type' do
+      s = engine.register_stream(stream_type: :prediction, content: 'p')
+      engine.create_binding(stream_ids: [s.id], binding_type: :temporal)
+      engine.create_binding(stream_ids: [s.id], binding_type: :perceptual)
+      result = engine.binding_by_type(binding_type: :temporal)
+      expect(result.size).to eq(1)
+      expect(result.first.binding_type).to eq(:temporal)
+    end
+
+    it 'returns empty array when no bindings of that type' do
+      expect(engine.binding_by_type(binding_type: :narrative)).to be_empty
+    end
+  end
+
+  describe '#streams_for_binding' do
+    it 'returns the streams belonging to a binding' do
+      s1 = engine.register_stream(stream_type: :emotion, content: 'warm')
+      s2 = engine.register_stream(stream_type: :memory, content: 'sunny')
+      binding = engine.create_binding(stream_ids: [s1.id, s2.id], binding_type: :emotional)
+      streams = engine.streams_for_binding(binding_id: binding.id)
+      expect(streams.map(&:id)).to contain_exactly(s1.id, s2.id)
+    end
+
+    it 'returns empty array for unknown binding_id' do
+      expect(engine.streams_for_binding(binding_id: 'ghost')).to be_empty
+    end
+  end
+
+  describe '#unbound_streams' do
+    it 'returns all streams when none are bound' do
+      register_n_streams(3)
+      expect(engine.unbound_streams.size).to eq(3)
+    end
+
+    it 'excludes streams that are in a binding' do
+      s1 = engine.register_stream(stream_type: :perception, content: 'bound')
+      engine.register_stream(stream_type: :thought, content: 'free')
+      engine.create_binding(stream_ids: [s1.id], binding_type: :perceptual)
+      unbound = engine.unbound_streams
+      expect(unbound.map(&:id)).not_to include(s1.id)
+      expect(unbound.size).to eq(1)
+    end
+  end
+
+  describe '#decay_all' do
+    it 'decreases coherence of all bindings' do
+      s = engine.register_stream(stream_type: :memory, content: 'm', salience: 0.9)
+      binding = engine.create_binding(stream_ids: [s.id], binding_type: :narrative)
+      initial = binding.coherence
+      engine.decay_all
+      expect(binding.coherence).to be < initial
+    end
+
+    it 'does not raise when no bindings exist' do
+      expect { engine.decay_all }.not_to raise_error
+    end
+  end
+
+  describe '#prune_incoherent' do
+    it 'removes bindings below COHERENCE_THRESHOLD' do
+      s = engine.register_stream(stream_type: :perception, content: 'faint', salience: 0.1)
+      engine.create_binding(stream_ids: [s.id], binding_type: :perceptual)
+      engine.prune_incoherent
+      expect(engine.to_h[:binding_count]).to eq(0)
+    end
+
+    it 'retains coherent bindings' do
+      s = engine.register_stream(stream_type: :intention, content: 'strong', salience: 0.9)
+      binding = engine.create_binding(stream_ids: [s.id], binding_type: :conceptual)
+      engine.prune_incoherent
+      expect(engine.to_h[:binding_count]).to eq(1)
+      expect(engine.streams_for_binding(binding_id: binding.id)).not_to be_empty
+    end
+  end
+
+  describe '#consciousness_report' do
+    it 'returns a hash with expected keys' do
+      report = engine.consciousness_report
+      expect(report.keys).to include(
+        :unified_experience, :fragmentation_index,
+        :coherence_distribution, :stream_count, :binding_count, :unbound_count
+      )
+    end
+
+    it 'includes nil unified_experience when no coherent bindings' do
+      report = engine.consciousness_report
+      expect(report[:unified_experience]).to be_nil
+    end
+
+    it 'includes a coherence_distribution hash with all labels' do
+      report = engine.consciousness_report
+      labels = report[:coherence_distribution].keys
+      expect(labels).to include(:unified, :coherent, :fragmented, :dissociated, :unbound)
+    end
+
+    it 'reports correct stream_count' do
+      register_n_streams(4)
+      report = engine.consciousness_report
+      expect(report[:stream_count]).to eq(4)
+    end
+
+    it 'includes unified_experience hash when a coherent binding exists' do
+      s = engine.register_stream(stream_type: :perception, content: 'vivid', salience: 0.9)
+      engine.create_binding(stream_ids: [s.id], binding_type: :perceptual)
+      report = engine.consciousness_report
+      expect(report[:unified_experience]).to be_a(Hash)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns engine stats' do
+      register_n_streams(2)
+      stats = engine.to_h
+      expect(stats[:stream_count]).to eq(2)
+      expect(stats[:binding_count]).to eq(0)
+      expect(stats[:unbound_count]).to eq(2)
+    end
+  end
+end

data/spec/legion/extensions/agentic/integration/phenomenal_binding/helpers/binding_unit_spec.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Integration::PhenomenalBinding::Helpers::BindingUnit do
+  let(:stream_ids) { %w[stream-1 stream-2 stream-3] }
+  let(:binding) do
+    described_class.new(stream_ids: stream_ids, binding_type: :perceptual, coherence: 0.7)
+  end
+
+  describe '#initialize' do
+    it 'assigns a uuid id' do
+      expect(binding.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'assigns stream_ids' do
+      expect(binding.stream_ids).to eq(stream_ids)
+    end
+
+    it 'assigns binding_type' do
+      expect(binding.binding_type).to eq(:perceptual)
+    end
+
+    it 'assigns coherence' do
+      expect(binding.coherence).to eq(0.7)
+    end
+
+    it 'defaults attention_weight to 0.5' do
+      expect(binding.attention_weight).to eq(0.5)
+    end
+
+    it 'accepts custom attention_weight' do
+      b = described_class.new(stream_ids: [], binding_type: :temporal, coherence: 0.5, attention_weight: 0.9)
+      expect(b.attention_weight).to eq(0.9)
+    end
+
+    it 'clamps coherence above 1.0' do
+      b = described_class.new(stream_ids: [], binding_type: :conceptual, coherence: 1.5)
+      expect(b.coherence).to eq(1.0)
+    end
+
+    it 'clamps coherence below 0.0' do
+      b = described_class.new(stream_ids: [], binding_type: :narrative, coherence: -0.2)
+      expect(b.coherence).to eq(0.0)
+    end
+
+    it 'does not share the input array reference' do
+      original = %w[a b]
+      b = described_class.new(stream_ids: original, binding_type: :emotional, coherence: 0.5)
+      original << 'c'
+      expect(b.stream_ids.size).to eq(2)
+    end
+  end
+
+  describe '#add_stream' do
+    it 'adds a new stream_id' do
+      binding.add_stream(stream_id: 'stream-4')
+      expect(binding.stream_ids).to include('stream-4')
+    end
+
+    it 'does not duplicate an existing stream_id' do
+      binding.add_stream(stream_id: 'stream-1')
+      expect(binding.stream_ids.count('stream-1')).to eq(1)
+    end
+  end
+
+  describe '#remove_stream' do
+    it 'removes an existing stream_id' do
+      binding.remove_stream(stream_id: 'stream-2')
+      expect(binding.stream_ids).not_to include('stream-2')
+    end
+
+    it 'does not raise when removing a non-existent id' do
+      expect { binding.remove_stream(stream_id: 'ghost') }.not_to raise_error
+    end
+  end
+
+  describe '#reinforce!' do
+    it 'increases coherence by BINDING_BOOST' do
+      initial = binding.coherence
+      binding.reinforce!
+      expect(binding.coherence).to be_within(0.001).of(initial + 0.08)
+    end
+
+    it 'clamps coherence at 1.0' do
+      b = described_class.new(stream_ids: [], binding_type: :perceptual, coherence: 0.97)
+      b.reinforce!
+      expect(b.coherence).to eq(1.0)
+    end
+  end
+
+  describe '#decay!' do
+    it 'decreases coherence by BINDING_DECAY' do
+      initial = binding.coherence
+      binding.decay!
+      expect(binding.coherence).to be_within(0.001).of(initial - 0.03)
+    end
+
+    it 'clamps coherence at 0.0' do
+      b = described_class.new(stream_ids: [], binding_type: :perceptual, coherence: 0.01)
+      b.decay!
+      expect(b.coherence).to eq(0.0)
+    end
+  end
+
+  describe '#coherent?' do
+    it 'returns true when coherence >= COHERENCE_THRESHOLD' do
+      b = described_class.new(stream_ids: [], binding_type: :temporal, coherence: 0.7)
+      expect(b.coherent?).to be true
+    end
+
+    it 'returns true at the exact threshold' do
+      b = described_class.new(stream_ids: [], binding_type: :temporal, coherence: 0.6)
+      expect(b.coherent?).to be true
+    end
+
+    it 'returns false below the threshold' do
+      b = described_class.new(stream_ids: [], binding_type: :temporal, coherence: 0.5)
+      expect(b.coherent?).to be false
+    end
+  end
+
+  describe '#coherence_label' do
+    it 'returns :unified at 0.9' do
+      b = described_class.new(stream_ids: [], binding_type: :perceptual, coherence: 0.9)
+      expect(b.coherence_label).to eq(:unified)
+    end
+
+    it 'returns :coherent at 0.7' do
+      b = described_class.new(stream_ids: [], binding_type: :perceptual, coherence: 0.7)
+      expect(b.coherence_label).to eq(:coherent)
+    end
+
+    it 'returns :fragmented at 0.5' do
+      b = described_class.new(stream_ids: [], binding_type: :perceptual, coherence: 0.5)
+      expect(b.coherence_label).to eq(:fragmented)
+    end
+
+    it 'returns :dissociated at 0.3' do
+      b = described_class.new(stream_ids: [], binding_type: :perceptual, coherence: 0.3)
+      expect(b.coherence_label).to eq(:dissociated)
+    end
+
+    it 'returns :unbound at 0.1' do
+      b = described_class.new(stream_ids: [], binding_type: :perceptual, coherence: 0.1)
+      expect(b.coherence_label).to eq(:unbound)
+    end
+  end
+
+  describe '#stream_count' do
+    it 'returns the number of stream ids' do
+      expect(binding.stream_count).to eq(3)
+    end
+
+    it 'updates after adding a stream' do
+      binding.add_stream(stream_id: 'new')
+      expect(binding.stream_count).to eq(4)
+    end
+  end
+
+  describe '#to_h' do
+    subject(:hash) { binding.to_h }
+
+    it 'includes id' do
+      expect(hash[:id]).to be_a(String)
+    end
+
+    it 'includes stream_ids' do
+      expect(hash[:stream_ids]).to eq(stream_ids)
+    end
+
+    it 'includes binding_type' do
+      expect(hash[:binding_type]).to eq(:perceptual)
+    end
+
+    it 'includes coherence as a float' do
+      expect(hash[:coherence]).to be_a(Float)
+    end
+
+    it 'includes coherent boolean' do
+      expect(hash[:coherent]).to be true
+    end
+
+    it 'includes coherence_label' do
+      expect(hash[:coherence_label]).to eq(:coherent)
+    end
+
+    it 'includes stream_count' do
+      expect(hash[:stream_count]).to eq(3)
+    end
+
+    it 'does not share stream_ids array reference' do
+      hash[:stream_ids] << 'extra'
+      expect(binding.stream_ids.size).to eq(3)
+    end
+  end
+end

data/spec/legion/extensions/agentic/integration/phenomenal_binding/helpers/constants_spec.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Integration::PhenomenalBinding::Helpers::Constants do
+  describe 'capacity constants' do
+    it 'defines MAX_STREAMS' do
+      expect(described_class::MAX_STREAMS).to eq(100)
+    end
+
+    it 'defines MAX_BINDINGS' do
+      expect(described_class::MAX_BINDINGS).to eq(200)
+    end
+  end
+
+  describe 'coherence constants' do
+    it 'defines COHERENCE_THRESHOLD' do
+      expect(described_class::COHERENCE_THRESHOLD).to eq(0.6)
+    end
+
+    it 'defines BINDING_DECAY' do
+      expect(described_class::BINDING_DECAY).to eq(0.03)
+    end
+
+    it 'defines BINDING_BOOST' do
+      expect(described_class::BINDING_BOOST).to eq(0.08)
+    end
+
+    it 'defines DEFAULT_SALIENCE' do
+      expect(described_class::DEFAULT_SALIENCE).to eq(0.5)
+    end
+  end
+
+  describe 'BINDING_TYPES' do
+    it 'includes all five types' do
+      expect(described_class::BINDING_TYPES).to contain_exactly(
+        :perceptual, :conceptual, :temporal, :narrative, :emotional
+      )
+    end
+
+    it 'is frozen' do
+      expect(described_class::BINDING_TYPES).to be_frozen
+    end
+  end
+
+  describe 'STREAM_TYPES' do
+    it 'includes all six types' do
+      expect(described_class::STREAM_TYPES).to contain_exactly(
+        :perception, :thought, :emotion, :memory, :intention, :prediction
+      )
+    end
+
+    it 'is frozen' do
+      expect(described_class::STREAM_TYPES).to be_frozen
+    end
+  end
+
+  describe 'COHERENCE_LABELS' do
+    it 'maps 0.9 to :unified' do
+      label = described_class::COHERENCE_LABELS.find { |range, _| range.cover?(0.9) }&.last
+      expect(label).to eq(:unified)
+    end
+
+    it 'maps 0.7 to :coherent' do
+      label = described_class::COHERENCE_LABELS.find { |range, _| range.cover?(0.7) }&.last
+      expect(label).to eq(:coherent)
+    end
+
+    it 'maps 0.5 to :fragmented' do
+      label = described_class::COHERENCE_LABELS.find { |range, _| range.cover?(0.5) }&.last
+      expect(label).to eq(:fragmented)
+    end
+
+    it 'maps 0.3 to :dissociated' do
+      label = described_class::COHERENCE_LABELS.find { |range, _| range.cover?(0.3) }&.last
+      expect(label).to eq(:dissociated)
+    end
+
+    it 'maps 0.1 to :unbound' do
+      label = described_class::COHERENCE_LABELS.find { |range, _| range.cover?(0.1) }&.last
+      expect(label).to eq(:unbound)
+    end
+
+    it 'maps exactly 0.8 to :unified' do
+      label = described_class::COHERENCE_LABELS.find { |range, _| range.cover?(0.8) }&.last
+      expect(label).to eq(:unified)
+    end
+
+    it 'maps exactly 0.6 to :coherent' do
+      label = described_class::COHERENCE_LABELS.find { |range, _| range.cover?(0.6) }&.last
+      expect(label).to eq(:coherent)
+    end
+  end
+end

data/spec/legion/extensions/agentic/integration/phenomenal_binding/helpers/stream_spec.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Integration::PhenomenalBinding::Helpers::Stream do
+  let(:stream) { described_class.new(stream_type: :perception, content: 'a red circle') }
+
+  describe '#initialize' do
+    it 'assigns a uuid id' do
+      expect(stream.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'assigns stream_type' do
+      expect(stream.stream_type).to eq(:perception)
+    end
+
+    it 'assigns content' do
+      expect(stream.content).to eq('a red circle')
+    end
+
+    it 'defaults salience to 0.5' do
+      expect(stream.salience).to eq(0.5)
+    end
+
+    it 'accepts custom salience' do
+      s = described_class.new(stream_type: :thought, content: 'deep', salience: 0.9)
+      expect(s.salience).to eq(0.9)
+    end
+
+    it 'clamps salience above 1.0' do
+      s = described_class.new(stream_type: :emotion, content: 'joy', salience: 1.5)
+      expect(s.salience).to eq(1.0)
+    end
+
+    it 'clamps salience below 0.0' do
+      s = described_class.new(stream_type: :memory, content: 'old', salience: -0.3)
+      expect(s.salience).to eq(0.0)
+    end
+
+    it 'assigns domain' do
+      s = described_class.new(stream_type: :intention, content: 'plan', domain: 'work')
+      expect(s.domain).to eq('work')
+    end
+
+    it 'defaults domain to nil' do
+      expect(stream.domain).to be_nil
+    end
+
+    it 'sets created_at to a Time' do
+      expect(stream.created_at).to be_a(Time)
+    end
+
+    it 'sets timestamp' do
+      expect(stream.timestamp).to be_a(Time)
+    end
+
+    it 'accepts explicit timestamp' do
+      t = Time.now.utc - 60
+      s = described_class.new(stream_type: :prediction, content: 'rain', timestamp: t)
+      expect(s.timestamp).to eq(t)
+    end
+  end
+
+  describe '#salient?' do
+    it 'returns true when salience >= 0.5' do
+      s = described_class.new(stream_type: :perception, content: 'x', salience: 0.7)
+      expect(s.salient?).to be true
+    end
+
+    it 'returns true when salience exactly 0.5' do
+      expect(stream.salient?).to be true
+    end
+
+    it 'returns false when salience < 0.5' do
+      s = described_class.new(stream_type: :thought, content: 'dim', salience: 0.3)
+      expect(s.salient?).to be false
+    end
+  end
+
+  describe '#fresh?' do
+    it 'returns true for a just-created stream' do
+      expect(stream.fresh?).to be true
+    end
+
+    it 'returns false for an old stream' do
+      allow(stream).to receive(:created_at).and_return(Time.now.utc - 60)
+      expect(stream.fresh?(window: 30)).to be false
+    end
+
+    it 'uses default window of 30 seconds' do
+      expect(stream.fresh?).to be true
+    end
+
+    it 'accepts a custom window' do
+      expect(stream.fresh?(window: 3600)).to be true
+    end
+  end
+
+  describe '#to_h' do
+    subject(:hash) { stream.to_h }
+
+    it 'includes id' do
+      expect(hash[:id]).to be_a(String)
+    end
+
+    it 'includes stream_type' do
+      expect(hash[:stream_type]).to eq(:perception)
+    end
+
+    it 'includes content' do
+      expect(hash[:content]).to eq('a red circle')
+    end
+
+    it 'includes salience as a rounded float' do
+      expect(hash[:salience]).to be_a(Float)
+    end
+
+    it 'includes domain' do
+      expect(hash).to have_key(:domain)
+    end
+
+    it 'includes timestamp' do
+      expect(hash[:timestamp]).to be_a(Time)
+    end
+
+    it 'includes created_at' do
+      expect(hash[:created_at]).to be_a(Time)
+    end
+  end
+end