lex-apollo 0.4.6 → 0.4.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a1c9042626e5d9e09a783b8c703b11f261573fe1658498a4fa48ad023306baf
-  data.tar.gz: 2f3e561b6851825d9d5c67325007802eafea63c10c93a00e37a40170202a0bdc
+  metadata.gz: 4ed5f6ac36b031c41850cae2f4e4c6768666c4151c730b7557f7d5f21ac24df7
+  data.tar.gz: 870ffad7838f068a01aa2b03af51ba2ae7df1cfe30debda9a8d3275705ef775a
 SHA512:
-  metadata.gz: d2dae8784e591deeb1608671dbabbd313813a6f94214b77de0539d2316d6ef3a34e21d5002eb28a262e98c4c4d57773793be4ba006d185e0fd3afcf6816902c5
-  data.tar.gz: 41e11ae62a001fab8e79b514d30c3c28374d38d1d4379926e00752df74e35ccfa79c61b3ac75e7e60341de0420287635413b265eca5fa0cd7fe4e7f02a5fad0f
+  metadata.gz: '0583ae3da3f19c3e852929e97947bf49b94e89d37f918d65fcc2507719049ac641ab6867c1e2b7eee899c923c1cb52ec75670c3cab345b159506d34a01099463'
+  data.tar.gz: 4f77f0e210baa01f3e77b06808ddfe06456d4f10358b8add5e4d602b8669be9b8223e6b69c30f2b56b2d18f20e5d0eabde504b05a8426812236d9a5918631bc4

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [0.4.7] - 2026-03-25
+
+### Added
+- Knowledge capture writeback system: `Helpers::Writeback` evaluates LLM responses for Apollo ingest with echo chamber prevention
+- `Helpers::TagNormalizer` for mechanical tag normalization (aliases, special chars, max 5)
+- `Helpers::Capability` for detecting embed/write capabilities per node
+- Writeback transport layer: `Messages::Writeback`, `Queues::WritebackStore`, `Queues::WritebackVectorize`
+- Writeback subscription actors: `Actor::WritebackStore` (pre-embedded), `Actor::WritebackVectorize` (needs embedding)
+- Content hash dedup in `Runners::Knowledge#handle_ingest` — collision boosts confidence instead of inserting
+- Identity tracking: `submitted_by`, `submitted_from`, `content_hash` fields on knowledge entries
+
 ## [0.4.6] - 2026-03-25
 
 ### Added

data/lib/legion/extensions/apollo/actors/writeback_store.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/subscription' if defined?(Legion::Extensions::Actors::Subscription)
+
+module Legion
+  module Extensions
+    module Apollo
+      module Actor
+        class WritebackStore < Legion::Extensions::Actors::Subscription
+          def runner_class    = 'Legion::Extensions::Apollo::Runners::Knowledge'
+          def runner_function = 'handle_ingest'
+          def check_subtask?  = false
+          def generate_task?  = false
+
+          def enabled?
+            defined?(Legion::Extensions::Apollo::Runners::Knowledge) &&
+              defined?(Legion::Transport) &&
+              Helpers::Capability.apollo_write_enabled?
+          rescue StandardError
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/apollo/actors/writeback_vectorize.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/subscription' if defined?(Legion::Extensions::Actors::Subscription)
+
+module Legion
+  module Extensions
+    module Apollo
+      module Actor
+        class WritebackVectorize < Legion::Extensions::Actors::Subscription
+          def runner_class    = self.class
+          def runner_function = 'handle_vectorize'
+          def check_subtask?  = false
+          def generate_task?  = false
+
+          def handle_vectorize(payload)
+            payload = symbolize(payload)
+            embedding = Helpers::Embedding.generate(text: payload[:content])
+            enriched = payload.merge(embedding: embedding)
+
+            if Helpers::Capability.can_write?
+              Runners::Knowledge.handle_ingest(**enriched)
+            else
+              Transport::Messages::Writeback.new(
+                **enriched, has_embedding: true
+              ).publish
+            end
+
+            { success: true, action: :vectorized }
+          rescue StandardError => e
+            { success: false, error: e.message }
+          end
+
+          def enabled?
+            defined?(Legion::Transport) && Helpers::Capability.can_embed?
+          rescue StandardError
+            false
+          end
+
+          private
+
+          def symbolize(hash)
+            hash.transform_keys(&:to_sym)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/apollo/helpers/capability.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Apollo
+      module Helpers
+        module Capability
+          EMBEDDING_MODELS = %w[mxbai-embed-large bge-large snowflake-arctic-embed].freeze
+
+          module_function
+
+          def can_embed?
+            return false unless defined?(Legion::LLM) && Legion::LLM.started?
+
+            ollama_embedding_available? || cloud_embedding_configured?
+          rescue StandardError
+            false
+          end
+
+          def can_write?
+            return false unless apollo_write_enabled?
+            return false unless defined?(Legion::Data) && Legion::Data.connected?
+
+            check_db_write_privilege
+          rescue StandardError
+            false
+          end
+
+          def apollo_write_enabled?
+            Legion::Settings.dig(:data, :apollo_write) == true
+          rescue StandardError
+            false
+          end
+
+          def ollama_embedding_available?
+            return false unless defined?(Legion::LLM::Discovery::Ollama)
+
+            EMBEDDING_MODELS.any? { |m| Legion::LLM::Discovery::Ollama.model_available?(m) }
+          rescue StandardError
+            false
+          end
+
+          def cloud_embedding_configured?
+            provider = Legion::Settings.dig(:apollo, :embedding, :provider)
+            model = Legion::Settings.dig(:apollo, :embedding, :model)
+            !provider.nil? && !model.nil?
+          rescue StandardError
+            false
+          end
+
+          def check_db_write_privilege
+            return @apollo_write_privilege unless @apollo_write_privilege.nil?
+
+            @apollo_write_privilege = Legion::Data.connection
+                                                  .fetch("SELECT has_table_privilege(current_user, 'apollo_entries', 'INSERT') AS can_insert")
+                                                  .first[:can_insert] == true
+          rescue StandardError
+            @apollo_write_privilege = false
+          end
+
+          def reset!
+            @apollo_write_privilege = nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/apollo/helpers/tag_normalizer.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Apollo
+      module Helpers
+        module TagNormalizer
+          ALIASES = {
+            'c#' => 'csharp', '.net' => 'dotnet', 'c++' => 'cplusplus',
+            'node.js' => 'nodejs', 'vue.js' => 'vuejs', 'react.js' => 'reactjs'
+          }.freeze
+
+          module_function
+
+          def normalize(raw)
+            tag = raw.to_s.strip.downcase
+            tag = ALIASES[tag] if ALIASES.key?(tag)
+            tag = tag.gsub(/[^a-z0-9\- ]/, '')
+                     .gsub(/\s+/, '-')
+                     .gsub(/-+/, '-')
+                     .sub(/^-/, '')
+                     .sub(/-$/, '')
+            tag.empty? ? nil : tag
+          end
+
+          def normalize_all(tags, max: 5)
+            Array(tags)
+              .filter_map { |t| normalize(t) }
+              .uniq
+              .first(max)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/apollo/helpers/writeback.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'socket'
+
+module Legion
+  module Extensions
+    module Apollo
+      module Helpers
+        module Writeback
+          RESEARCH_TOOLS = %w[read_file search_files search_content run_command].freeze
+          MAX_CONTENT_LENGTH = 4000
+          MIN_CONTENT_LENGTH = 50
+
+          module_function
+
+          def evaluate_and_route(request:, response:, enrichments: {})
+            return unless writeback_enabled?
+            return unless should_capture?(request, response, enrichments)
+
+            payload = build_payload(request: request, response: response)
+            route_payload(payload)
+          rescue StandardError => e
+            Legion::Logging.warn("apollo writeback failed: #{e.message}") if defined?(Legion::Logging)
+          end
+
+          def should_capture?(_request, response, enrichments)
+            content = response_content(response)
+            return false if content.nil? || content.length < min_content_length
+
+            tool_calls = extract_tool_calls(response, enrichments)
+            research_calls = tool_calls.select { |tc| RESEARCH_TOOLS.include?(tc[:name] || tc['name']) }
+
+            return false if research_calls.empty?
+
+            apollo_results = enrichments['rag_context:apollo_results']
+            return true if apollo_results.nil? || (apollo_results[:count] || 0).zero?
+
+            # Apollo had results — only capture if LLM also did additional research
+            research_calls.any?
+          end
+
+          def build_payload(request:, response:, source_channel: nil)
+            content = response_content(response)
+            caller_identity = extract_identity(request)
+            user_query = extract_user_query(request)
+            tags = derive_tags(user_query)
+
+            {
+              content:          content[0...MAX_CONTENT_LENGTH],
+              content_type:     'observation',
+              tags:             Helpers::TagNormalizer.normalize_all(tags),
+              source_agent:     response.respond_to?(:model) ? response.model : 'unknown',
+              source_channel:   "#{source_channel || 'pipeline'}_synthesis",
+              submitted_by:     caller_identity,
+              submitted_from:   Socket.gethostname,
+              knowledge_domain: nil,
+              content_hash:     content_hash(content)
+            }
+          end
+
+          def route_payload(payload)
+            can_embed = Helpers::Capability.can_embed?
+            can_write = Helpers::Capability.can_write?
+
+            if can_embed
+              embedding = Helpers::Embedding.generate(text: payload[:content])
+              payload[:embedding] = embedding
+            end
+
+            if can_write && can_embed
+              write_directly(payload)
+            else
+              publish_to_transport(payload, has_embedding: can_embed)
+            end
+          end
+
+          def write_directly(payload)
+            Runners::Knowledge.handle_ingest(**payload)
+          rescue StandardError => e
+            Legion::Logging.warn("apollo direct write failed, falling back to transport: #{e.message}") if defined?(Legion::Logging)
+            publish_to_transport(payload, has_embedding: !payload[:embedding].nil?)
+          end
+
+          def publish_to_transport(payload, has_embedding: false)
+            return unless defined?(Legion::Transport)
+
+            Transport::Messages::Writeback.new(
+              **payload, has_embedding: has_embedding
+            ).publish
+          rescue StandardError => e
+            Legion::Logging.warn("apollo writeback publish failed: #{e.message}") if defined?(Legion::Logging)
+          end
+
+          def writeback_enabled?
+            Legion::Settings.dig(:apollo, :writeback, :enabled) != false
+          rescue StandardError
+            true
+          end
+
+          def min_content_length
+            Legion::Settings.dig(:apollo, :writeback, :min_content_length) || MIN_CONTENT_LENGTH
+          rescue StandardError
+            MIN_CONTENT_LENGTH
+          end
+
+          def content_hash(content)
+            normalized = content.to_s.strip.downcase.gsub(/\s+/, ' ')
+            Digest::MD5.hexdigest(normalized)
+          end
+
+          def response_content(response)
+            msg = response.respond_to?(:message) ? response.message : nil
+            return nil unless msg.is_a?(Hash)
+
+            msg[:content] || msg['content']
+          end
+
+          def extract_identity(request)
+            return 'unknown' unless request.respond_to?(:caller) && request.caller.is_a?(Hash)
+
+            request.caller.dig(:requested_by, :identity) || 'unknown'
+          rescue StandardError
+            'unknown'
+          end
+
+          def extract_user_query(request)
+            return '' unless request.respond_to?(:messages)
+
+            user_msgs = Array(request.messages).select { |m| m[:role] == 'user' || m['role'] == 'user' }
+            (user_msgs.last || {})[:content] || ''
+          rescue StandardError
+            ''
+          end
+
+          def extract_tool_calls(response, enrichments)
+            calls = []
+            calls += Array(response.tool_calls) if response.respond_to?(:tool_calls)
+            calls += Array(enrichments['tool_calls']) if enrichments['tool_calls']
+            calls.uniq { |tc| tc[:name] || tc['name'] }
+          end
+
+          def derive_tags(query)
+            stop_words = %w[a an the is are was were be been being have has had do does did will would shall
+                            should may might can could of in to for on with at by from as into about between
+                            how what when where why who which this that these those it its and or but not]
+            words = query.to_s.downcase.gsub(/[^a-z0-9\s]/, '').split
+            words.reject { |w| stop_words.include?(w) || w.length < 3 }
+                 .uniq
+                 .first(5)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/apollo/runners/knowledge.rb

@@ -59,12 +59,25 @@ module Legion
             }
           end
 
-          def handle_ingest(content:, content_type:, tags: [], source_agent: 'unknown', source_provider: nil, source_channel: nil, knowledge_domain: nil, context: {}, **) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
+          def handle_ingest(content:, content_type:, tags: [], source_agent: 'unknown', source_provider: nil, source_channel: nil, knowledge_domain: nil, submitted_by: nil, submitted_from: nil, content_hash: nil, context: {}, **) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
             return { success: false, error: 'apollo_data_not_available' } unless defined?(Legion::Data::Model::ApolloEntry)
 
+            # Content hash dedup
+            hash = content_hash || (defined?(Helpers::Writeback) ? Helpers::Writeback.content_hash(content) : nil)
+            if hash
+              existing = Legion::Data::Model::ApolloEntry
+                         .where(content_hash: hash)
+                         .exclude(status: 'archived')
+                         .first
+              if existing
+                existing.update(confidence: [existing.confidence + Helpers::Confidence.retrieval_boost, 1.0].min)
+                return { success: true, entry_id: existing.id, deduped: true }
+              end
+            end
+
             embedding = Helpers::Embedding.generate(text: content)
             content_type_sym = content_type.to_s
-            tag_array = Array(tags)
+            tag_array = defined?(Helpers::TagNormalizer) ? Helpers::TagNormalizer.normalize_all(tags) : Array(tags)
             domain = knowledge_domain || tag_array.first || 'general'
 
             corroborated, existing_id = find_corroboration(embedding, content_type_sym, source_agent, source_channel)
@@ -81,6 +94,9 @@ module Legion
                 tags:             Sequel.pg_array(tag_array),
                 status:           'candidate',
                 knowledge_domain: domain,
+                submitted_by:     submitted_by,
+                submitted_from:   submitted_from,
+                content_hash:     hash,
                 embedding:        Sequel.lit("'[#{embedding.join(',')}]'::vector")
               )
               existing_id = new_entry.id

data/lib/legion/extensions/apollo/transport/messages/writeback.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'legion/transport/message' if defined?(Legion::Transport)
+
+module Legion
+  module Extensions
+    module Apollo
+      module Transport
+        module Messages
+          class Writeback < Legion::Transport::Message
+            def exchange
+              Exchanges::Apollo
+            end
+
+            def routing_key
+              @options[:has_embedding] ? 'apollo.writeback.store' : 'apollo.writeback.vectorize'
+            end
+
+            def type
+              'apollo_writeback'
+            end
+
+            def message
+              {
+                content:          @options[:content],
+                content_type:     @options[:content_type],
+                tags:             @options[:tags],
+                source_agent:     @options[:source_agent],
+                source_channel:   @options[:source_channel],
+                submitted_by:     @options[:submitted_by],
+                submitted_from:   @options[:submitted_from],
+                embedding:        @options[:embedding],
+                knowledge_domain: @options[:knowledge_domain],
+                context:          @options[:context] || {}
+              }.compact
+            end
+
+            def validate
+              raise TypeError, 'content is required' unless @options[:content].is_a?(String)
+
+              @valid = true
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/apollo/transport/queues/writeback_store.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'legion/transport/queue' if defined?(Legion::Transport)
+
+module Legion
+  module Extensions
+    module Apollo
+      module Transport
+        module Queues
+          class WritebackStore < Legion::Transport::Queue
+            def queue_name
+              'apollo.writeback.store'
+            end
+
+            def queue_options
+              { manual_ack: true, durable: true, arguments: { 'x-dead-letter-exchange': 'apollo.dlx' } }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/apollo/transport/queues/writeback_vectorize.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'legion/transport/queue' if defined?(Legion::Transport)
+
+module Legion
+  module Extensions
+    module Apollo
+      module Transport
+        module Queues
+          class WritebackVectorize < Legion::Transport::Queue
+            def queue_name
+              'apollo.writeback.vectorize'
+            end
+
+            def queue_options
+              { manual_ack: true, durable: true, arguments: { 'x-dead-letter-exchange': 'apollo.dlx' } }
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -3,7 +3,7 @@
 module Legion
   module Extensions
     module Apollo
-      VERSION = '0.4.6'
+      VERSION = '0.4.7'
     end
   end
 end

data/lib/legion/extensions/apollo.rb

@@ -4,6 +4,9 @@ require 'legion/extensions/apollo/version'
 require 'legion/extensions/apollo/helpers/confidence'
 require 'legion/extensions/apollo/helpers/similarity'
 require 'legion/extensions/apollo/helpers/graph_query'
+require 'legion/extensions/apollo/helpers/tag_normalizer'
+require 'legion/extensions/apollo/helpers/capability'
+require 'legion/extensions/apollo/helpers/writeback'
 require 'legion/extensions/apollo/runners/knowledge'
 require 'legion/extensions/apollo/runners/expertise'
 require 'legion/extensions/apollo/runners/maintenance'
@@ -21,6 +24,9 @@ if defined?(Legion::Transport)
   require 'legion/extensions/apollo/transport/queues/gas'
   require 'legion/extensions/apollo/transport/messages/ingest'
   require 'legion/extensions/apollo/transport/messages/query'
+  require 'legion/extensions/apollo/transport/messages/writeback'
+  require 'legion/extensions/apollo/transport/queues/writeback_store'
+  require 'legion/extensions/apollo/transport/queues/writeback_vectorize'
 end
 
 module Legion

data/spec/legion/extensions/apollo/actors/writeback_store_spec.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+unless defined?(Legion::Extensions::Actors::Subscription)
+  module Legion
+    module Extensions
+      module Actors
+        class Subscription; end # rubocop:disable Lint/EmptyClass
+      end
+    end
+  end
+end
+$LOADED_FEATURES << 'legion/extensions/actors/subscription' unless $LOADED_FEATURES.include?('legion/extensions/actors/subscription')
+
+require 'legion/extensions/apollo/helpers/capability'
+require 'legion/extensions/apollo/runners/knowledge'
+require 'legion/extensions/apollo/actors/writeback_store'
+
+RSpec.describe Legion::Extensions::Apollo::Actor::WritebackStore do
+  subject(:actor) { described_class.new }
+
+  describe '#runner_class' do
+    it 'returns Knowledge runner string' do
+      expect(actor.runner_class).to eq('Legion::Extensions::Apollo::Runners::Knowledge')
+    end
+  end
+
+  describe '#runner_function' do
+    it 'returns handle_ingest' do
+      expect(actor.runner_function).to eq('handle_ingest')
+    end
+  end
+
+  describe '#check_subtask?' do
+    it { expect(actor.check_subtask?).to be false }
+  end
+
+  describe '#generate_task?' do
+    it { expect(actor.generate_task?).to be false }
+  end
+end

data/spec/legion/extensions/apollo/actors/writeback_vectorize_spec.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+unless defined?(Legion::Extensions::Actors::Subscription)
+  module Legion
+    module Extensions
+      module Actors
+        class Subscription; end # rubocop:disable Lint/EmptyClass
+      end
+    end
+  end
+end
+$LOADED_FEATURES << 'legion/extensions/actors/subscription' unless $LOADED_FEATURES.include?('legion/extensions/actors/subscription')
+
+unless defined?(Legion::Transport::Message)
+  module Legion
+    module Transport
+      class Message
+        attr_reader :options
+
+        def initialize(**opts)
+          @options = opts
+        end
+
+        def publish
+          { published: true }
+        end
+      end
+
+      class Exchange
+        def exchange_name
+          'mock'
+        end
+      end
+    end
+  end
+  $LOADED_FEATURES << 'legion/transport/message' unless $LOADED_FEATURES.include?('legion/transport/message')
+  $LOADED_FEATURES << 'legion/transport/exchange' unless $LOADED_FEATURES.include?('legion/transport/exchange')
+end
+
+require 'legion/extensions/apollo/helpers/embedding'
+require 'legion/extensions/apollo/helpers/capability'
+require 'legion/extensions/apollo/transport/exchanges/apollo'
+require 'legion/extensions/apollo/transport/messages/writeback'
+require 'legion/extensions/apollo/actors/writeback_vectorize'
+
+RSpec.describe Legion::Extensions::Apollo::Actor::WritebackVectorize do
+  subject(:actor) { described_class.new }
+
+  describe '#runner_function' do
+    it 'returns handle_vectorize' do
+      expect(actor.runner_function).to eq('handle_vectorize')
+    end
+  end
+
+  describe '#handle_vectorize' do
+    let(:payload) { { content: 'test content', content_type: 'observation', tags: %w[test] } }
+
+    before do
+      allow(Legion::Extensions::Apollo::Helpers::Embedding).to receive(:generate).and_return([0.1] * 1024)
+      allow(Legion::Extensions::Apollo::Helpers::Capability).to receive(:can_write?).and_return(false)
+    end
+
+    it 'generates embedding and re-publishes when cannot write' do
+      msg = instance_double(Legion::Extensions::Apollo::Transport::Messages::Writeback)
+      allow(Legion::Extensions::Apollo::Transport::Messages::Writeback).to receive(:new).and_return(msg)
+      allow(msg).to receive(:publish)
+
+      result = actor.handle_vectorize(payload)
+      expect(result[:success]).to be true
+      expect(result[:action]).to eq(:vectorized)
+      expect(msg).to have_received(:publish)
+    end
+
+    it 'writes directly when can_write? is true' do
+      allow(Legion::Extensions::Apollo::Helpers::Capability).to receive(:can_write?).and_return(true)
+      allow(Legion::Extensions::Apollo::Runners::Knowledge).to receive(:handle_ingest).and_return({ success: true })
+
+      result = actor.handle_vectorize(payload)
+      expect(result[:success]).to be true
+      expect(Legion::Extensions::Apollo::Runners::Knowledge).to have_received(:handle_ingest)
+    end
+
+    it 'returns error hash on failure' do
+      allow(Legion::Extensions::Apollo::Helpers::Embedding).to receive(:generate).and_raise(RuntimeError, 'boom')
+
+      result = actor.handle_vectorize(payload)
+      expect(result[:success]).to be false
+      expect(result[:error]).to eq('boom')
+    end
+  end
+end

data/spec/legion/extensions/apollo/helpers/capability_spec.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/apollo/helpers/capability'
+
+unless defined?(Legion::LLM)
+  module Legion
+    module LLM
+      def self.started? = false
+    end
+  end
+end
+
+RSpec.describe Legion::Extensions::Apollo::Helpers::Capability do
+  before do
+    described_class.instance_variable_set(:@apollo_write_privilege, nil)
+  end
+
+  describe '.can_embed?' do
+    it 'returns true when LLM is started and Ollama has a model' do
+      allow(Legion::LLM).to receive(:started?).and_return(true)
+      allow(described_class).to receive(:ollama_embedding_available?).and_return(true)
+      expect(described_class.can_embed?).to be true
+    end
+
+    it 'returns false when LLM is not started' do
+      allow(Legion::LLM).to receive(:started?).and_return(false) if defined?(Legion::LLM)
+      expect(described_class.can_embed?).to be false
+    end
+  end
+
+  describe '.can_write?' do
+    it 'returns false when apollo_write setting is false' do
+      allow(Legion::Settings).to receive(:dig).with(:data, :apollo_write).and_return(false)
+      expect(described_class.can_write?).to be false
+    end
+
+    it 'returns false when Data is not connected' do
+      allow(Legion::Settings).to receive(:dig).with(:data, :apollo_write).and_return(true)
+      allow(Legion::Data).to receive(:connected?).and_return(false) if defined?(Legion::Data)
+      expect(described_class.can_write?).to be false
+    end
+  end
+
+  describe '.apollo_write_enabled?' do
+    it 'reads from settings' do
+      allow(Legion::Settings).to receive(:dig).with(:data, :apollo_write).and_return(true)
+      expect(described_class.apollo_write_enabled?).to be true
+    end
+
+    it 'defaults to false' do
+      allow(Legion::Settings).to receive(:dig).with(:data, :apollo_write).and_return(nil)
+      expect(described_class.apollo_write_enabled?).to be false
+    end
+  end
+end

data/spec/legion/extensions/apollo/helpers/tag_normalizer_spec.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/apollo/helpers/tag_normalizer'
+
+RSpec.describe Legion::Extensions::Apollo::Helpers::TagNormalizer do
+  describe '.normalize' do
+    it 'lowercases tags' do
+      expect(described_class.normalize('RabbitMQ')).to eq('rabbitmq')
+    end
+
+    it 'strips leading/trailing whitespace' do
+      expect(described_class.normalize('  hello  ')).to eq('hello')
+    end
+
+    it 'replaces spaces with hyphens' do
+      expect(described_class.normalize('message broker')).to eq('message-broker')
+    end
+
+    it 'strips special characters except hyphens' do
+      expect(described_class.normalize('c#')).to eq('csharp')
+      expect(described_class.normalize('hello!')).to eq('hello')
+      expect(described_class.normalize('key=value')).to eq('keyvalue')
+    end
+
+    it 'collapses multiple hyphens' do
+      expect(described_class.normalize('a--b---c')).to eq('a-b-c')
+    end
+
+    it 'applies known aliases' do
+      expect(described_class.normalize('C++')).to eq('cplusplus')
+      expect(described_class.normalize('.NET')).to eq('dotnet')
+      expect(described_class.normalize('node.js')).to eq('nodejs')
+    end
+
+    it 'returns nil for empty results' do
+      expect(described_class.normalize('!!!')).to be_nil
+      expect(described_class.normalize('')).to be_nil
+    end
+  end
+
+  describe '.normalize_all' do
+    it 'normalizes, deduplicates, and caps at max' do
+      tags = %w[RabbitMQ rabbitmq AMQP message-broker extra-tag sixth-tag]
+      result = described_class.normalize_all(tags, max: 5)
+      expect(result).to eq(%w[rabbitmq amqp message-broker extra-tag sixth-tag])
+    end
+
+    it 'filters out nil results' do
+      expect(described_class.normalize_all(['!!!', 'valid'])).to eq(['valid'])
+    end
+
+    it 'handles nil input' do
+      expect(described_class.normalize_all(nil)).to eq([])
+    end
+
+    it 'defaults max to 5' do
+      tags = %w[a b c d e f g]
+      expect(described_class.normalize_all(tags).length).to eq(5)
+    end
+  end
+end

data/spec/legion/extensions/apollo/helpers/writeback_spec.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/apollo/helpers/tag_normalizer'
+require 'legion/extensions/apollo/helpers/writeback'
+
+RSpec.describe Legion::Extensions::Apollo::Helpers::Writeback do
+  let(:base_request) do
+    double('Request',
+           messages: [{ role: 'user', content: 'How does RabbitMQ clustering work?' }],
+           caller:   { requested_by: { identity: 'user@example.com', type: :human } })
+  end
+
+  let(:base_response) do
+    double('Response',
+           message:    { content: 'RabbitMQ clustering works by...' * 20 },
+           model:      'claude-sonnet-4-6',
+           tool_calls: [])
+  end
+
+  describe '.should_capture?' do
+    it 'returns false for short responses' do
+      short = double('Response', message: { content: 'yes' }, tool_calls: [])
+      expect(described_class.should_capture?(base_request, short, {})).to be false
+    end
+
+    it 'returns false when no research tools were used' do
+      expect(described_class.should_capture?(base_request, base_response, {})).to be false
+    end
+
+    it 'returns true when research tools were used' do
+      enrichments = { 'tool_calls' => [{ name: 'read_file' }] }
+      long_response = double('Response',
+                             message:    { content: 'x' * 100 },
+                             model:      'claude-sonnet-4-6',
+                             tool_calls: [{ name: 'read_file' }])
+      expect(described_class.should_capture?(base_request, long_response, enrichments)).to be true
+    end
+
+    it 'returns false for echo chamber (apollo had results, no additional research)' do
+      enrichments = {
+        'rag_context:apollo_results' => { count: 3 },
+        'tool_calls'                 => []
+      }
+      long_response = double('Response', message: { content: 'x' * 100 }, tool_calls: [])
+      expect(described_class.should_capture?(base_request, long_response, enrichments)).to be false
+    end
+  end
+
+  describe '.build_payload' do
+    it 'builds payload with identity context' do
+      payload = described_class.build_payload(
+        request:        base_request,
+        response:       base_response,
+        source_channel: 'chat'
+      )
+      expect(payload[:submitted_by]).to eq('user@example.com')
+      expect(payload[:source_agent]).to eq('claude-sonnet-4-6')
+      expect(payload[:content_type]).to eq('observation')
+      expect(payload[:source_channel]).to eq('chat_synthesis')
+    end
+
+    it 'truncates content to max length' do
+      long_response = double('Response',
+                             message: { content: 'x' * 10_000 },
+                             model:   'test')
+      payload = described_class.build_payload(request: base_request, response: long_response)
+      expect(payload[:content].length).to be <= 4000
+    end
+
+    it 'includes content_hash' do
+      payload = described_class.build_payload(request: base_request, response: base_response)
+      expect(payload[:content_hash]).to be_a(String)
+      expect(payload[:content_hash].length).to eq(32)
+    end
+
+    it 'normalizes tags' do
+      payload = described_class.build_payload(request: base_request, response: base_response)
+      expect(payload[:tags]).to all(match(/\A[a-z0-9-]+\z/))
+    end
+  end
+
+  describe '.content_hash' do
+    it 'produces consistent hashes for same content' do
+      hash1 = described_class.content_hash('hello world')
+      hash2 = described_class.content_hash('hello world')
+      expect(hash1).to eq(hash2)
+    end
+
+    it 'normalizes whitespace before hashing' do
+      hash1 = described_class.content_hash('hello  world')
+      hash2 = described_class.content_hash('hello world')
+      expect(hash1).to eq(hash2)
+    end
+  end
+end

data/spec/legion/extensions/apollo/runners/knowledge_spec.rb

@@ -5,6 +5,8 @@ require 'legion/extensions/apollo/helpers/confidence'
 require 'legion/extensions/apollo/helpers/similarity'
 require 'legion/extensions/apollo/helpers/embedding'
 require 'legion/extensions/apollo/helpers/graph_query'
+require 'legion/extensions/apollo/helpers/tag_normalizer'
+require 'legion/extensions/apollo/helpers/writeback'
 require 'legion/extensions/apollo/runners/knowledge'
 
 RSpec.describe Legion::Extensions::Apollo::Runners::Knowledge do
@@ -120,7 +122,12 @@ RSpec.describe Legion::Extensions::Apollo::Runners::Knowledge do
         allow(Legion::Extensions::Apollo::Helpers::Embedding).to receive(:generate)
           .and_return(Array.new(1536, 0.0))
 
+        # Corroboration lookup chain
         allow(mock_entry_class).to receive(:where).and_return(double(exclude: double(limit: empty_dataset)))
+        # Content hash dedup chain — no match by default
+        dedup_chain = double('dedup_chain')
+        allow(mock_entry_class).to receive(:where).with(content_hash: anything).and_return(dedup_chain)
+        allow(dedup_chain).to receive(:exclude).with(status: 'archived').and_return(double(first: nil))
         allow(mock_entry_class).to receive(:db).and_return(mock_db)
         allow(mock_db).to receive(:fetch).and_return(double(all: []))
         allow(mock_entry_class).to receive(:create).and_return(mock_entry)
@@ -190,6 +197,53 @@ RSpec.describe Legion::Extensions::Apollo::Runners::Knowledge do
         ).and_return(mock_entry)
         host.handle_ingest(content: 'test', content_type: 'fact', source_agent: 'agent-1')
       end
+
+      it 'passes submitted_by and submitted_from to create' do
+        expect(mock_entry_class).to receive(:create).with(
+          hash_including(submitted_by: 'user@example.com', submitted_from: 'node-1')
+        ).and_return(mock_entry)
+        host.handle_ingest(content: 'test', content_type: 'fact',
+                           source_agent: 'agent-1',
+                           submitted_by: 'user@example.com',
+                           submitted_from: 'node-1')
+      end
+
+      it 'passes content_hash to create' do
+        expect(mock_entry_class).to receive(:create).with(
+          hash_including(content_hash: 'abc123')
+        ).and_return(mock_entry)
+        host.handle_ingest(content: 'test', content_type: 'fact',
+                           source_agent: 'agent-1', content_hash: 'abc123')
+      end
+
+      it 'normalizes tags before storage' do
+        expect(mock_entry_class).to receive(:create).with(
+          hash_including(tags: Sequel.pg_array(%w[rabbitmq]))
+        ).and_return(mock_entry)
+        host.handle_ingest(content: 'test', content_type: 'fact',
+                           tags: ['RabbitMQ'], source_agent: 'agent-1')
+      end
+
+      context 'content hash dedup' do
+        let(:existing_entry) do
+          double('existing', id: 'uuid-existing', confidence: 0.6,
+                             update: true)
+        end
+
+        it 'returns deduped result on hash collision with active entry' do
+          dedup_dataset = double('dataset')
+          allow(mock_entry_class).to receive(:where).with(content_hash: anything).and_return(dedup_dataset)
+          allow(dedup_dataset).to receive(:exclude).with(status: 'archived').and_return(dedup_dataset)
+          allow(dedup_dataset).to receive(:first).and_return(existing_entry)
+
+          result = host.handle_ingest(content: 'test', content_type: 'fact',
+                                      source_agent: 'agent-1',
+                                      content_hash: 'deadbeef12345678deadbeef12345678')
+          expect(result[:success]).to be true
+          expect(result[:deduped]).to be true
+          expect(result[:entry_id]).to eq('uuid-existing')
+        end
+      end
     end
 
     context 'when Sequel raises an error' do

data/spec/legion/extensions/apollo/runners/request_spec.rb

@@ -138,7 +138,7 @@ RSpec.describe Legion::Extensions::Apollo::Runners::Request do
         stub_const('Legion::Data::Model::ApolloAccessLog', mock_access_log_class)
         allow(Legion::Extensions::Apollo::Helpers::Embedding).to receive(:generate)
           .and_return(Array.new(1536, 0.0))
-        allow(mock_entry_class).to receive(:where).and_return(double(exclude: double(limit: double(each: nil))))
+        allow(mock_entry_class).to receive(:where).and_return(double(exclude: double(limit: double(each: nil), first: nil)))
         allow(mock_entry_class).to receive(:exclude)
           .and_return(double(exclude: double(limit: double(all: []))))
         allow(mock_entry_class).to receive(:db).and_return(double(fetch: double(all: [])))

data/spec/legion/extensions/apollo/transport/messages/writeback_spec.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+unless defined?(Legion::Transport::Message)
+  module Legion
+    module Transport
+      class Message
+        attr_reader :options
+
+        def initialize(**opts)
+          @options = opts
+        end
+
+        def publish
+          { published: true }
+        end
+      end
+
+      class Exchange
+        def exchange_name
+          'mock'
+        end
+      end
+    end
+  end
+  $LOADED_FEATURES << 'legion/transport/message' unless $LOADED_FEATURES.include?('legion/transport/message')
+  $LOADED_FEATURES << 'legion/transport/exchange' unless $LOADED_FEATURES.include?('legion/transport/exchange')
+end
+
+require 'legion/extensions/apollo/transport/exchanges/apollo'
+require 'legion/extensions/apollo/transport/messages/writeback'
+
+RSpec.describe Legion::Extensions::Apollo::Transport::Messages::Writeback do
+  let(:base_opts) do
+    { content: 'test knowledge', content_type: 'observation',
+      tags: %w[test], source_agent: 'claude-sonnet-4-6',
+      submitted_by: 'user@example.com', submitted_from: 'node-1' }
+  end
+
+  describe '#routing_key' do
+    it 'routes to store when embedding present' do
+      msg = described_class.new(**base_opts, has_embedding: true, embedding: [0.1] * 1024)
+      expect(msg.routing_key).to eq('apollo.writeback.store')
+    end
+
+    it 'routes to vectorize when no embedding' do
+      msg = described_class.new(**base_opts, has_embedding: false)
+      expect(msg.routing_key).to eq('apollo.writeback.vectorize')
+    end
+  end
+
+  describe '#message' do
+    it 'includes identity fields' do
+      msg = described_class.new(**base_opts)
+      payload = msg.message
+      expect(payload[:submitted_by]).to eq('user@example.com')
+      expect(payload[:submitted_from]).to eq('node-1')
+      expect(payload[:source_agent]).to eq('claude-sonnet-4-6')
+    end
+
+    it 'compacts nil values' do
+      msg = described_class.new(**base_opts, embedding: nil, knowledge_domain: nil)
+      expect(msg.message).not_to have_key(:embedding)
+      expect(msg.message).not_to have_key(:knowledge_domain)
+    end
+  end
+
+  describe '#type' do
+    it 'returns apollo_writeback' do
+      msg = described_class.new(**base_opts)
+      expect(msg.type).to eq('apollo_writeback')
+    end
+  end
+
+  describe '#validate' do
+    it 'raises on missing content' do
+      expect { described_class.new(**base_opts, content: nil) }.to raise_error(TypeError)
+    end
+
+    it 'passes with valid content' do
+      msg = described_class.new(**base_opts)
+      msg.validate
+      expect(msg.instance_variable_get(:@valid)).to be true
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-apollo
 version: !ruby/object:Gem::Version
-  version: 0.4.6
+  version: 0.4.7
 platform: ruby
 authors:
 - Esity
@@ -153,14 +153,19 @@ files:
 - lib/legion/extensions/apollo/actors/gas_subscriber.rb
 - lib/legion/extensions/apollo/actors/ingest.rb
 - lib/legion/extensions/apollo/actors/query_responder.rb
+- lib/legion/extensions/apollo/actors/writeback_store.rb
+- lib/legion/extensions/apollo/actors/writeback_vectorize.rb
 - lib/legion/extensions/apollo/api.rb
 - lib/legion/extensions/apollo/client.rb
 - lib/legion/extensions/apollo/gaia_integration.rb
+- lib/legion/extensions/apollo/helpers/capability.rb
 - lib/legion/extensions/apollo/helpers/confidence.rb
 - lib/legion/extensions/apollo/helpers/embedding.rb
 - lib/legion/extensions/apollo/helpers/entity_watchdog.rb
 - lib/legion/extensions/apollo/helpers/graph_query.rb
 - lib/legion/extensions/apollo/helpers/similarity.rb
+- lib/legion/extensions/apollo/helpers/tag_normalizer.rb
+- lib/legion/extensions/apollo/helpers/writeback.rb
 - lib/legion/extensions/apollo/runners/entity_extractor.rb
 - lib/legion/extensions/apollo/runners/expertise.rb
 - lib/legion/extensions/apollo/runners/gas.rb
@@ -172,24 +177,32 @@ files:
 - lib/legion/extensions/apollo/transport/exchanges/llm_audit.rb
 - lib/legion/extensions/apollo/transport/messages/ingest.rb
 - lib/legion/extensions/apollo/transport/messages/query.rb
+- lib/legion/extensions/apollo/transport/messages/writeback.rb
 - lib/legion/extensions/apollo/transport/queues/gas.rb
 - lib/legion/extensions/apollo/transport/queues/ingest.rb
 - lib/legion/extensions/apollo/transport/queues/query.rb
+- lib/legion/extensions/apollo/transport/queues/writeback_store.rb
+- lib/legion/extensions/apollo/transport/queues/writeback_vectorize.rb
 - lib/legion/extensions/apollo/version.rb
 - spec/legion/extensions/apollo/actors/decay_spec.rb
 - spec/legion/extensions/apollo/actors/entity_watchdog_spec.rb
 - spec/legion/extensions/apollo/actors/expertise_aggregator_spec.rb
 - spec/legion/extensions/apollo/actors/gas_subscriber_spec.rb
 - spec/legion/extensions/apollo/actors/ingest_spec.rb
+- spec/legion/extensions/apollo/actors/writeback_store_spec.rb
+- spec/legion/extensions/apollo/actors/writeback_vectorize_spec.rb
 - spec/legion/extensions/apollo/api_spec.rb
 - spec/legion/extensions/apollo/client_spec.rb
 - spec/legion/extensions/apollo/contradiction_spec.rb
 - spec/legion/extensions/apollo/gaia_integration_spec.rb
+- spec/legion/extensions/apollo/helpers/capability_spec.rb
 - spec/legion/extensions/apollo/helpers/confidence_spec.rb
 - spec/legion/extensions/apollo/helpers/embedding_spec.rb
 - spec/legion/extensions/apollo/helpers/entity_watchdog_spec.rb
 - spec/legion/extensions/apollo/helpers/graph_query_spec.rb
 - spec/legion/extensions/apollo/helpers/similarity_spec.rb
+- spec/legion/extensions/apollo/helpers/tag_normalizer_spec.rb
+- spec/legion/extensions/apollo/helpers/writeback_spec.rb
 - spec/legion/extensions/apollo/runners/decay_cycle_spec.rb
 - spec/legion/extensions/apollo/runners/entity_extractor_spec.rb
 - spec/legion/extensions/apollo/runners/expertise_spec.rb
@@ -202,6 +215,7 @@ files:
 - spec/legion/extensions/apollo/runners/request_spec.rb
 - spec/legion/extensions/apollo/transport/messages/ingest_spec.rb
 - spec/legion/extensions/apollo/transport/messages/query_spec.rb
+- spec/legion/extensions/apollo/transport/messages/writeback_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/LegionIO/lex-apollo
 licenses: