lex-apollo 0.4.19 → 0.4.21

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1bf0ca8790d13fc3d262ede810ce50a47146dc37743e8806696de970b8a0385a
-  data.tar.gz: 1f1a9115e1a1bb36423150a7290a82352f07aef7aa41f0b4b7da8e0ff5b76f94
+  metadata.gz: 31dc882a8d5fd761bceaba21ff853a3d3dd898df9d4377464b72b110d306af0a
+  data.tar.gz: 8dcfd2bc7c2557b298f3d503cc94b07e5a78b5a9777789f724dede41b9d0efdb
 SHA512:
-  metadata.gz: 3d92269898b53825fff831ef253fc44ac9e9a45602da25628f32fc95c1e6a53edfd86add2f02f7131c449cd1b940258d2c8fc4df3b90ca6306affbf8a76d4ccb
-  data.tar.gz: d6c98fc7a7f351dc929e2d2dac4c9d7d119e32328706c9880e19a6bc3edb53448b008d8a8fefd7f7e8b8a201084f4ec78006088954cb7e56ee72cb312f0d5ce6
+  metadata.gz: 5e066b3c62555b4866bfe99d6bed13a034e2b6b23f613ae7906e8eaebee90ecb2f9dd937a5e928dd8337af8945bfba9a1528deb4d3200eb82b8a92b081b6cf59
+  data.tar.gz: dd1d625f4efc30df8951ee80db9ee0cfc1c25137bae5d8571dd09265bd5eec79add3482eba3cc88d77f43b052994597577abe634080cd995eb4dc0db7601458e

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.4.21] - 2026-04-27
+
+### Changed
+- `Apollo::Runners::Knowledge#handle_ingest` now emits warn-level logs on the three early-return failure paths (nil/blank content, nil content_type, apollo_data_not_available). Companion to PR #15: that PR added `handle_exception` to the rescue paths; this PR closes the silent-failure window for the early-return paths that fire BEFORE any rescue would. Tag values in the log line are sanitized via `gsub(/[\r\n]+/, ' ')` to prevent log-line injection from caller-controlled tags.
+
+## [0.4.20] - 2026-04-25
+
+### Fixed
+- `Knowledge#handle_ingest` now sanitizes stored content for PostgreSQL by scrubbing invalid UTF-8 and removing null bytes before inserts.
+- `Knowledge#handle_ingest` now truncates short metadata fields to schema-safe lengths before writing entries.
+- `Knowledge#handle_query` now treats very short queries as browse/list requests, returning recent non-archived entries without embedding noise while preserving explicit status filters.
+- `Knowledge` Sequel rescue paths now log exception class, message, and a short backtrace before returning structured errors.
+- Apollo runners and actors now emit debug/info lifecycle logs around ingest, query, browse, maintenance, expertise, entity extraction, writeback vectorization, entity watchdog, and GAS pipeline paths so debug-level logging can trace workflows end to end.
+
 ## [0.4.19] - 2026-04-24
 
 ### Fixed

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

@@ -34,6 +34,7 @@ module Legion
 
           def scan_and_ingest
             texts = recent_task_log_texts
+            log.debug("EntityWatchdog scan_and_ingest log_texts=#{texts.size}")
             return { success: true, ingested: 0, reason: :no_logs } if texts.empty?
 
             ingested = 0
@@ -53,10 +54,10 @@ module Legion
               end
             end
 
-            log.debug("EntityWatchdog: ingested #{ingested} new entities from #{texts.size} log entries")
+            log.info("EntityWatchdog ingested=#{ingested} logs_scanned=#{texts.size}")
             { success: true, ingested: ingested, logs_scanned: texts.size }
           rescue StandardError => e
-            log.error("EntityWatchdog scan_and_ingest failed: #{e.message}")
+            handle_exception(e, level: :error, operation: 'apollo.entity_watchdog.scan_and_ingest')
             { success: false, error: e.message }
           end
 
@@ -71,7 +72,9 @@ module Legion
                    .order(Sequel.desc(:created_at))
                    .limit(log_limit)
                    .select_map(:message)
-            logs.map(&:to_s).reject(&:empty?).uniq
+            texts = logs.map(&:to_s).reject(&:empty?).uniq
+            log.debug("EntityWatchdog recent_task_log_texts lookback=#{lookback} limit=#{log_limit} raw=#{logs.size} unique=#{texts.size}")
+            texts
           rescue StandardError => e
             log.warn("EntityWatchdog recent_task_log_texts failed: #{e.message}")
             []
@@ -104,8 +107,9 @@ module Legion
               source_agent: 'lex-apollo:entity_watchdog',
               context:      { entity_type: entity[:type], original_name: entity[:name] }
             ).publish
+            log.info("EntityWatchdog published entity type=#{entity[:type]} name=#{entity[:name]}")
           rescue StandardError => e
-            log.error("EntityWatchdog publish failed: #{e.message}")
+            handle_exception(e, level: :error, operation: 'apollo.entity_watchdog.publish_entity_ingest')
           end
 
           def entity_types

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

@@ -14,21 +14,27 @@ module Legion
 
           def handle_vectorize(payload)
             payload = symbolize(payload)
+            log.debug("WritebackVectorize handle_vectorize content_length=#{payload[:content].to_s.length} content_type=#{payload[:content_type] || 'nil'}")
             result = Legion::LLM::Embeddings.generate(text: payload[:content])
             vector = result.is_a?(Hash) ? result[:vector] : result
             embedding = vector.is_a?(Array) && vector.any? ? vector : Array.new(1024, 0.0)
+            log.debug("WritebackVectorize embedding_dimensions=#{embedding.length} vector_generated=#{vector.is_a?(Array) && vector.any?}")
             enriched = payload.merge(embedding: embedding)
 
             if Helpers::Capability.can_write?
+              log.debug('WritebackVectorize route=direct_ingest')
               Runners::Knowledge.handle_ingest(**enriched)
             else
+              log.debug('WritebackVectorize route=transport_writeback')
               Transport::Messages::Writeback.new(
                 **enriched, has_embedding: true
               ).publish
             end
 
+            log.info('WritebackVectorize completed action=vectorized')
             { success: true, action: :vectorized }
           rescue StandardError => e
+            handle_exception(e, level: :error, operation: 'apollo.writeback_vectorize.handle_vectorize')
             { success: false, error: e.message }
           end
 

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

@@ -51,15 +51,17 @@ module Legion
           req = json_body
           halt 400, { error: 'query is required' }.to_json unless req[:query]
 
-          result = runner.handle_query(
+          query_options = {
             query:          req[:query],
             limit:          req[:limit] || 10,
             min_confidence: req[:min_confidence] || 0.3,
-            status:         req[:status] || [:confirmed],
             tags:           req[:tags],
             domain:         req[:domain],
             agent_id:       req[:agent_id] || 'api'
-          )
+          }
+          query_options[:status] = req[:status] if req.key?(:status)
+
+          result = runner.handle_query(**query_options)
           status result[:success] ? 200 : 500
           result.to_json
         end

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

@@ -4,17 +4,24 @@ module Legion
   module Extensions
     module Apollo
       module Runners
-        module EntityExtractor # rubocop:disable Legion/Extension/RunnerIncludeHelpers
+        module EntityExtractor
           DEFAULT_ENTITY_TYPES = %w[person service repository concept].freeze
           DEFAULT_MIN_CONFIDENCE = 0.7
 
           def extract_entities(text:, entity_types: nil, min_confidence: Helpers::Confidence.apollo_setting(:entity_extractor, :min_confidence, default: DEFAULT_MIN_CONFIDENCE), **) # rubocop:disable Layout/LineLength
-            return { success: true, entities: [], source: :empty } if text.to_s.strip.empty?
+            if text.to_s.strip.empty?
+              log.debug('Apollo EntityExtractor.extract_entities skipped reason=empty_text')
+              return { success: true, entities: [], source: :empty }
+            end
 
-            return { success: true, entities: [], source: :unavailable } unless defined?(Legion::LLM) && Legion::LLM.started?
+            unless defined?(Legion::LLM) && Legion::LLM.started?
+              log.debug('Apollo EntityExtractor.extract_entities skipped reason=llm_unavailable')
+              return { success: true, entities: [], source: :unavailable }
+            end
 
             types = Array(entity_types).map(&:to_s)
             types = DEFAULT_ENTITY_TYPES if types.empty?
+            log.debug("Apollo EntityExtractor.extract_entities text_length=#{text.to_s.length} types=#{types.join(',')} min_confidence=#{min_confidence}")
 
             result = Legion::LLM.structured(
               messages: [
@@ -29,9 +36,11 @@ module Legion
               (entity[:confidence] || 0.0) >= min_confidence &&
                 (types.empty? || types.include?(entity[:type].to_s))
             end
+            log.info("Apollo EntityExtractor.extract_entities raw=#{raw_entities.size} filtered=#{filtered.size}")
 
             { success: true, entities: filtered, source: :llm }
           rescue StandardError => e
+            handle_exception(e, level: :error, operation: 'apollo.entity_extractor.extract_entities')
             { success: false, entities: [], error: e.message, source: :error }
           end
 
@@ -70,6 +79,8 @@ module Legion
               required:   ['entities']
             }
           end
+
+          include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
         end
       end
     end

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

@@ -18,52 +18,65 @@ module Legion
           end
 
           def aggregate(**)
-            return { success: false, error: 'apollo_data_not_available' } unless defined?(Legion::Data::Model::ApolloEntry)
+            unless defined?(Legion::Data::Model::ApolloEntry)
+              log.warn('Apollo Expertise.aggregate skipped: apollo_data_not_available')
+              return { success: false, error: 'apollo_data_not_available' }
+            end
 
             entries = Legion::Data::Model::ApolloEntry
                       .select(:source_agent, :tags, :confidence)
                       .exclude(source_agent: nil)
                       .all
-
-            groups = {}
-            entries.each do |entry|
-              agent = entry.source_agent
-              domain = entry.tags.is_a?(Array) ? (entry.tags.first || 'general') : 'general'
-              key = "#{agent}:#{domain}"
-              groups[key] ||= { agent_id: agent, domain: domain, confidences: [] }
-              groups[key][:confidences] << entry.confidence.to_f
-            end
+            log.debug("Apollo Expertise.aggregate entries=#{entries.size}")
 
             agent_set = Set.new
             domain_set = Set.new
 
-            groups.each_value do |group|
-              avg = group[:confidences].sum / group[:confidences].size
-              count = group[:confidences].size
-              cap = Helpers::Confidence.apollo_setting(:expertise, :proficiency_cap, default: 1.0)
-              proficiency = [avg * Math.log2(count + 1), cap].min
-
-              existing = Legion::Data::Model::ApolloExpertise
-                         .where(agent_id: group[:agent_id], domain: group[:domain]).first
-
-              if existing
-                existing.update(proficiency: proficiency, entry_count: count, last_active_at: Time.now)
-              else
-                Legion::Data::Model::ApolloExpertise.create(
-                  agent_id: group[:agent_id], domain: group[:domain],
-                  proficiency: proficiency, entry_count: count, last_active_at: Time.now
-                )
-              end
-
+            expertise_groups(entries).each_value do |group|
+              upsert_expertise_group(group)
               agent_set << group[:agent_id]
               domain_set << group[:domain]
             end
 
             { success: true, agents: agent_set.size, domains: domain_set.size }
+              .tap { |result| log.info("Apollo Expertise.aggregate agents=#{result[:agents]} domains=#{result[:domains]}") }
           rescue Sequel::Error => e
+            handle_exception(e, level: :error, operation: 'apollo.expertise.aggregate')
             { success: false, error: e.message }
           end
 
+          def expertise_groups(entries)
+            entries.each_with_object({}) do |entry, groups|
+              agent = entry.source_agent
+              domain = entry.tags.is_a?(Array) ? (entry.tags.first || 'general') : 'general'
+              key = "#{agent}:#{domain}"
+              groups[key] ||= { agent_id: agent, domain: domain, confidences: [] }
+              groups[key][:confidences] << entry.confidence.to_f
+            end
+          end
+
+          def upsert_expertise_group(group)
+            count = group[:confidences].size
+            proficiency = expertise_proficiency(group[:confidences])
+            existing = Legion::Data::Model::ApolloExpertise
+                       .where(agent_id: group[:agent_id], domain: group[:domain]).first
+
+            if existing
+              existing.update(proficiency: proficiency, entry_count: count, last_active_at: Time.now)
+            else
+              Legion::Data::Model::ApolloExpertise.create(
+                agent_id: group[:agent_id], domain: group[:domain],
+                proficiency: proficiency, entry_count: count, last_active_at: Time.now
+              )
+            end
+          end
+
+          def expertise_proficiency(confidences)
+            avg = confidences.sum / confidences.size
+            cap = Helpers::Confidence.apollo_setting(:expertise, :proficiency_cap, default: 1.0)
+            [avg * Math.log2(confidences.size + 1), cap].min
+          end
+
           include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
         end
       end

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

@@ -4,7 +4,10 @@ module Legion
   module Extensions
     module Apollo
       module Runners
-        module Gas # rubocop:disable Legion/Extension/RunnerIncludeHelpers
+        module Gas
+          include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+          extend Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
           RELATION_TYPES = %w[
             similar_to contradicts depends_on causes
             part_of supersedes supports_by extends
@@ -16,10 +19,6 @@ module Legion
 
           module_function
 
-          def log
-            Legion::Logging
-          end
-
           def json_load(str)
             ::JSON.parse(str, symbolize_names: true)
           end
@@ -31,7 +30,12 @@ module Legion
           def fallback_confidence     = Helpers::Confidence.apollo_setting(:gas, :fallback_confidence, default: 0.5)
 
           def process(audit_event)
-            return { phases_completed: 0, reason: 'no content' } unless processable?(audit_event)
+            unless processable?(audit_event)
+              log.debug('GAS process skipped reason=no_content')
+              return { phases_completed: 0, reason: 'no content' }
+            end
+
+            log.debug("GAS process start request_id=#{audit_event[:request_id] || 'nil'} messages=#{Array(audit_event[:messages]).size} response_length=#{audit_event[:response_content].to_s.length}") # rubocop:disable Layout/LineLength
 
             facts = phase_comprehend(audit_event)
             entities = phase_extract(audit_event, facts)
@@ -40,7 +44,7 @@ module Legion
             deposit_result = phase_deposit(facts, entities, relations, synthesis, audit_event)
             anticipations = phase_anticipate(facts, synthesis)
 
-            {
+            result = {
               phases_completed: 6,
               facts:            facts.length,
               entities:         entities.length,
@@ -49,8 +53,10 @@ module Legion
               deposited:        deposit_result,
               anticipations:    anticipations.length
             }
+            log.info("GAS process complete facts=#{result[:facts]} entities=#{result[:entities]} relations=#{result[:relations]} synthesis=#{result[:synthesis]} anticipations=#{result[:anticipations]}") # rubocop:disable Layout/LineLength
+            result
           rescue StandardError => e
-            log.warn("GAS pipeline error: #{e.message}")
+            log.error("GAS pipeline error: #{e.message}")
             { phases_completed: 0, error: e.message }
           end
 
@@ -63,19 +69,24 @@ module Legion
             messages = audit_event[:messages]
             response = audit_event[:response_content]
 
-            if llm_available?
-              llm_comprehend(messages, response)
-            else
-              mechanical_comprehend(messages, response)
-            end
+            mode = llm_available? ? :llm : :mechanical
+            log.debug("GAS phase_comprehend mode=#{mode} messages=#{Array(messages).size} response_length=#{response.to_s.length}")
+            facts = mode == :llm ? llm_comprehend(messages, response) : mechanical_comprehend(messages, response)
+            log.debug("GAS phase_comprehend facts=#{facts.size}")
+            facts
           end
 
           # Phase 2: Extract - entity extraction (delegates to existing EntityExtractor)
           def phase_extract(audit_event, _facts)
-            return [] unless defined?(Runners::EntityExtractor)
+            unless defined?(Runners::EntityExtractor)
+              log.debug('GAS phase_extract skipped reason=entity_extractor_unavailable')
+              return []
+            end
 
             result = Runners::EntityExtractor.extract_entities(text: audit_event[:response_content])
-            result[:success] ? (result[:entities] || []) : []
+            entities = result[:success] ? (result[:entities] || []) : []
+            log.debug("GAS phase_extract success=#{result[:success]} entities=#{entities.size}")
+            entities
           rescue StandardError => e
             log.warn("GAS phase_extract failed: #{e.message}")
             []
@@ -83,10 +94,16 @@ module Legion
 
           # Phase 3: Relate - classify relationships between new and existing entries
           def phase_relate(facts, _entities)
-            return [] unless defined?(Runners::Knowledge)
+            unless defined?(Runners::Knowledge)
+              log.debug('GAS phase_relate skipped reason=knowledge_runner_unavailable')
+              return []
+            end
 
             existing = fetch_similar_entries(facts)
-            return [] if existing.empty?
+            if existing.empty?
+              log.debug("GAS phase_relate skipped reason=no_existing_entries facts=#{facts.size}")
+              return []
+            end
 
             relations = []
             facts.each do |fact|
@@ -95,15 +112,24 @@ module Legion
                 relations << relation if relation
               end
             end
+            log.debug("GAS phase_relate facts=#{facts.size} existing=#{existing.size} relations=#{relations.size}")
             relations
           end
 
           # Phase 4: Synthesize - generate derivative knowledge
           def phase_synthesize(facts, _relations)
-            return [] if facts.length < 2
-            return [] unless llm_available?
+            if facts.length < 2
+              log.debug("GAS phase_synthesize skipped reason=insufficient_facts facts=#{facts.length}")
+              return []
+            end
+            unless llm_available?
+              log.debug('GAS phase_synthesize skipped reason=llm_unavailable')
+              return []
+            end
 
-            llm_synthesize(facts)
+            synthesis = llm_synthesize(facts)
+            log.debug("GAS phase_synthesize synthesis=#{synthesis.size}")
+            synthesis
           rescue StandardError => e
             log.warn("GAS phase_synthesize failed: #{e.message}")
             []
@@ -111,7 +137,10 @@ module Legion
 
           # Phase 5: Deposit - atomic write to Apollo
           def phase_deposit(facts, _entities, _relations, _synthesis, audit_event)
-            return { deposited: 0 } unless defined?(Runners::Knowledge)
+            unless defined?(Runners::Knowledge)
+              log.debug('GAS phase_deposit skipped reason=knowledge_runner_unavailable')
+              return { deposited: 0 }
+            end
 
             deposited = 0
             facts.each do |fact|
@@ -128,15 +157,24 @@ module Legion
             rescue StandardError => e
               log.warn("GAS deposit error: #{e.message}")
             end
+            log.info("GAS phase_deposit deposited=#{deposited} facts=#{facts.size}")
             { deposited: deposited }
           end
 
           # Phase 6: Anticipate - pre-cache likely follow-up questions
           def phase_anticipate(facts, _synthesis)
-            return [] if facts.empty?
-            return [] unless llm_available?
+            if facts.empty?
+              log.debug('GAS phase_anticipate skipped reason=no_facts')
+              return []
+            end
+            unless llm_available?
+              log.debug('GAS phase_anticipate skipped reason=llm_unavailable')
+              return []
+            end
 
-            llm_anticipate(facts)
+            anticipations = llm_anticipate(facts)
+            log.debug("GAS phase_anticipate anticipations=#{anticipations.size}")
+            anticipations
           rescue StandardError => e
             log.warn("GAS phase_anticipate failed: #{e.message}")
             []
@@ -153,7 +191,9 @@ module Legion
               log.warn("GAS fetch_similar_entries failed for fact: #{e.message}")
               next
             end
-            entries.uniq { |e| e[:id] }
+            unique = entries.uniq { |e| e[:id] }
+            log.debug("GAS fetch_similar_entries facts=#{facts.size} entries=#{unique.size}")
+            unique
           end
 
           def classify_relation(fact, entry)

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

@@ -21,9 +21,12 @@ module Legion
             link: :association, relation: :association, connection: :association,
             inference: :association, implication: :association
           }.freeze
+          DEFAULT_QUERY_STATUS = [:confirmed].freeze
+          UNSET = Object.new.freeze
 
           def store_knowledge(content:, content_type:, tags: [], source_agent: nil, context: {}, **)
             content_type = normalize_content_type(content_type)
+            log.debug("Apollo Knowledge.store_knowledge content_type=#{content_type} tags=#{Array(tags).size} source_agent=#{source_agent || 'nil'} data_available=#{defined?(Legion::Data::Model::ApolloEntry) ? true : false}") # rubocop:disable Layout/LineLength
 
             if defined?(Legion::Data::Model::ApolloEntry)
               return handle_ingest(content: content, content_type: content_type,
@@ -41,6 +44,7 @@ module Legion
           end
 
           def query_knowledge(query:, limit: Helpers::GraphQuery.default_query_limit, min_confidence: Helpers::GraphQuery.default_query_min_confidence, status: %i[confirmed candidate], tags: nil, **) # rubocop:disable Layout/LineLength
+            log.debug("Apollo Knowledge.query_knowledge query_length=#{query.to_s.length} limit=#{limit} statuses=#{Array(status).join(',')} tags=#{Array(tags).size} data_available=#{defined?(Legion::Data::Model::ApolloEntry) ? true : false}") # rubocop:disable Layout/LineLength
             if defined?(Legion::Data::Model::ApolloEntry)
               return handle_query(query: query, limit: limit, min_confidence: min_confidence,
                                   status: status, tags: tags, **)
@@ -57,6 +61,7 @@ module Legion
           end
 
           def related_entries(entry_id:, relation_types: nil, depth: Helpers::GraphQuery.default_depth, **)
+            log.debug("Apollo Knowledge.related_entries entry_id=#{entry_id} depth=#{depth} relation_types=#{Array(relation_types).join(',')} data_available=#{defined?(Legion::Data::Model::ApolloEntry) ? true : false}") # rubocop:disable Layout/LineLength
             return handle_traverse(entry_id: entry_id, depth: depth, relation_types: relation_types, **) if defined?(Legion::Data::Model::ApolloEntry)
 
             {
@@ -75,74 +80,72 @@ module Legion
             }
           end
 
-          def handle_ingest(content: nil, content_type: nil, tags: [], source_agent: 'unknown', source_provider: nil, source_channel: nil, knowledge_domain: nil, submitted_by: nil, submitted_from: nil, content_hash: nil, context: {}, skip: false, **) # rubocop:disable Metrics/ParameterLists, Layout/LineLength, Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity
+          def handle_ingest(content: nil, content_type: nil, tags: [], source_agent: 'unknown', source_provider: nil, source_channel: nil, knowledge_domain: nil, submitted_by: nil, submitted_from: nil, content_hash: nil, context: {}, skip: false, **) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
             return { status: :skipped } if skip
-            return { success: false, error: 'content is required' } if content.nil? || content.to_s.strip.empty?
-            return { success: false, error: 'content_type is required' } if content_type.nil?
-            return { success: false, error: 'apollo_data_not_available' } unless defined?(Legion::Data::Model::ApolloEntry)
 
-            # Content hash dedup
+            content = normalize_text_input(content)
+            log.debug("Apollo Knowledge.handle_ingest content_length=#{content.length} content_type=#{content_type} tags=#{Array(tags).size} source_agent=#{source_agent} source_channel=#{source_channel || 'nil'}") # rubocop:disable Layout/LineLength
+            early_error = ingest_early_return_error(content: content, content_type: content_type, tags: tags)
+            return early_error if early_error
+
             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
+            existing = active_duplicate_for_hash(hash)
+            if existing
+              log.info("Apollo Knowledge.handle_ingest deduped entry_id=#{existing.id} source_agent=#{source_agent}")
+              return { success: true, entry_id: existing.id, deduped: true }
             end
 
             embedding = embed_text(content)
             content_type_sym = content_type.to_s
-            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)
-
-            unless corroborated
-              new_entry = Legion::Data::Model::ApolloEntry.create(
-                content:          content,
-                content_type:     content_type_sym,
-                confidence:       Helpers::Confidence.initial_confidence,
-                source_agent:     source_agent,
-                source_provider:  source_provider || derive_provider_from_agent(source_agent),
-                source_channel:   source_channel,
-                source_context:   ::JSON.dump(context.is_a?(Hash) ? context : {}),
-                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")
+            metadata = ingest_metadata(tags: tags, knowledge_domain: knowledge_domain, source_agent: source_agent,
+                                       source_provider: source_provider, source_channel: source_channel,
+                                       submitted_by: submitted_by, submitted_from: submitted_from)
+
+            corroborated, existing_id = find_corroboration(
+              embedding, content_type_sym, metadata[:source_agent], metadata[:source_channel]
+            )
+
+            if corroborated
+              log.info("Apollo Knowledge.handle_ingest corroborated entry_id=#{existing_id} source_agent=#{metadata[:source_agent]}")
+            else
+              existing_id = create_candidate_entry(
+                content: content, content_type: content_type_sym, context: context,
+                metadata: metadata, content_hash: hash, embedding: embedding
               )
-              existing_id = new_entry.id
             end
 
-            upsert_expertise(source_agent: source_agent, domain: domain)
+            upsert_expertise(source_agent: metadata[:source_agent], domain: metadata[:domain])
 
             Legion::Data::Model::ApolloAccessLog.create(
-              entry_id: existing_id, agent_id: source_agent, action: 'ingest'
+              entry_id: existing_id, agent_id: metadata[:source_agent], action: 'ingest'
             )
 
             contradictions = detect_contradictions(existing_id, embedding, content)
+            log.debug("Apollo Knowledge.handle_ingest complete entry_id=#{existing_id} corroborated=#{corroborated} contradictions=#{contradictions.size}")
 
             { success: true, entry_id: existing_id, status: corroborated ? 'corroborated' : 'candidate',
               corroborated: corroborated, contradictions: contradictions }
           rescue Sequel::Error => e
+            handle_exception(e, level: :error, operation: 'apollo.knowledge.handle_ingest')
             { success: false, error: e.message }
           end
 
-          def handle_query(query:, limit: Helpers::GraphQuery.default_query_limit, min_confidence: Helpers::GraphQuery.default_query_min_confidence, status: [:confirmed], tags: nil, domain: nil, agent_id: 'unknown', **) # rubocop:disable Layout/LineLength
+          def handle_query(query:, limit: Helpers::GraphQuery.default_query_limit, min_confidence: Helpers::GraphQuery.default_query_min_confidence, status: UNSET, tags: nil, domain: nil, agent_id: 'unknown', **) # rubocop:disable Layout/LineLength
             return { success: false, error: 'apollo_data_not_available' } unless defined?(Legion::Data::Model::ApolloEntry)
 
             query = normalize_text_input(query)
+            status_defaulted = status.equal?(UNSET)
+            requested_status = status_defaulted ? DEFAULT_QUERY_STATUS : status
+            log.debug("Apollo Knowledge.handle_query mode=#{browse_query?(query) ? 'browse' : 'semantic'} query_length=#{query.length} limit=#{limit} statuses=#{Array(requested_status).join(',')} status_defaulted=#{status_defaulted} tags=#{Array(tags).size} domain=#{domain || 'nil'} agent_id=#{agent_id}") # rubocop:disable Layout/LineLength
+            if browse_query?(query)
+              return list_entries_chronologically(query: query, limit: limit, status: requested_status,
+                                                  status_defaulted: status_defaulted, tags: tags, domain: domain)
+            end
+
             embedding = embed_text(query)
             sql = Helpers::GraphQuery.build_semantic_search_sql(
               limit: limit, min_confidence: min_confidence,
-              statuses: Array(status).map(&:to_s), tags: tags, domain: domain
+              statuses: Array(requested_status).map(&:to_s), tags: tags, domain: domain
             )
 
             db = Legion::Data::Model::ApolloEntry.db
@@ -173,14 +176,17 @@ module Legion
                 knowledge_domain: entry[:knowledge_domain] }
             end
 
+            log.info("Apollo Knowledge.handle_query results=#{formatted.size} mode=semantic agent_id=#{agent_id}")
             { success: true, entries: formatted, count: formatted.size }
           rescue Sequel::Error => e
+            handle_exception(e, level: :error, operation: 'apollo.knowledge.handle_query')
             { success: false, error: e.message }
           end
 
           def handle_traverse(entry_id:, depth: Helpers::GraphQuery.default_depth, relation_types: nil, agent_id: 'unknown', **)
             return { success: false, error: 'apollo_data_not_available' } unless defined?(Legion::Data::Model::ApolloEntry)
 
+            log.debug("Apollo Knowledge.handle_traverse entry_id=#{entry_id} depth=#{depth} relation_types=#{Array(relation_types).join(',')} agent_id=#{agent_id}") # rubocop:disable Layout/LineLength
             # Whitelist relation_types to prevent SQL injection (they are string-interpolated in build_traversal_sql)
             if relation_types
               allowed = Helpers::Confidence::RELATION_TYPES
@@ -203,14 +209,17 @@ module Legion
                 depth: entry[:depth], activation: entry[:activation] }
             end
 
+            log.info("Apollo Knowledge.handle_traverse results=#{formatted.size} entry_id=#{entry_id}")
             { success: true, entries: formatted, count: formatted.size }
           rescue Sequel::Error => e
+            handle_exception(e, level: :error, operation: 'apollo.knowledge.handle_traverse')
             { success: false, error: e.message }
           end
 
           def redistribute_knowledge(agent_id:, min_confidence: Helpers::Confidence.apollo_setting(:query, :redistribute_min_confidence, default: 0.5), **)
             return { success: false, error: 'apollo_data_not_available' } unless defined?(Legion::Data::Model::ApolloEntry)
 
+            log.debug("Apollo Knowledge.redistribute_knowledge agent_id=#{agent_id} min_confidence=#{min_confidence}")
             entries = Legion::Data::Model::ApolloEntry
                       .where(source_agent: agent_id, status: 'confirmed')
                       .where { confidence > min_confidence }
@@ -238,6 +247,7 @@ module Legion
             log.info("[apollo] redistributed #{redistributed} entries from departing agent=#{agent_id}")
             { success: true, redistributed: redistributed, agent_id: agent_id }
           rescue Sequel::Error => e
+            handle_exception(e, level: :error, operation: 'apollo.knowledge.redistribute_knowledge')
             { success: false, error: e.message }
           end
 
@@ -247,6 +257,7 @@ module Legion
             return { success: false, error: 'apollo_data_not_available' } unless defined?(Legion::Data::Model::ApolloEntry)
 
             query = normalize_text_input(query)
+            log.debug("Apollo Knowledge.retrieve_relevant query_length=#{query.length} limit=#{limit} min_confidence=#{min_confidence} tags=#{Array(tags).size} domain=#{domain || 'nil'}") # rubocop:disable Layout/LineLength
             return { success: true, entries: [], count: 0 } if query.nil? || query.to_s.strip.empty?
 
             embedding = embed_text(query)
@@ -273,8 +284,10 @@ module Legion
                 knowledge_domain: entry[:knowledge_domain] }
             end
 
+            log.info("Apollo Knowledge.retrieve_relevant results=#{formatted.size} limit=#{limit}")
             { success: true, entries: formatted, count: formatted.size }
           rescue Sequel::Error => e
+            handle_exception(e, level: :error, operation: 'apollo.knowledge.retrieve_relevant')
             { success: false, error: e.message }
           end
 
@@ -283,6 +296,7 @@ module Legion
               return { success: false, error: 'apollo_data_not_available' }
             end
 
+            log.debug("Apollo Knowledge.prepare_mesh_export target_domain=#{target_domain} min_confidence=#{min_confidence} limit=#{limit}")
             conn = Legion::Data.connection
             allowed = allowed_domains_for(target_domain)
 
@@ -302,7 +316,9 @@ module Legion
             end
 
             { success: true, entries: formatted, count: formatted.size, target_domain: target_domain }
+              .tap { |result| log.info("Apollo Knowledge.prepare_mesh_export results=#{result[:count]} target_domain=#{target_domain}") }
           rescue Sequel::Error => e
+            handle_exception(e, level: :error, operation: 'apollo.knowledge.prepare_mesh_export')
             { success: false, error: e.message }
           end
 
@@ -311,6 +327,7 @@ module Legion
               return { deleted: 0, redacted: 0, error: 'apollo_data_not_available' }
             end
 
+            log.warn("Apollo Knowledge.handle_erasure_request agent_id=#{agent_id}")
             conn = Legion::Data.connection
 
             # Delete entries solely from dead agent (not confirmed by others)
@@ -325,7 +342,9 @@ module Legion
                        .update(source_agent: 'redacted', source_provider: nil, source_channel: nil)
 
             { deleted: deleted, redacted: redacted, agent_id: agent_id }
+              .tap { |result| log.info("Apollo Knowledge.handle_erasure_request deleted=#{result[:deleted]} redacted=#{result[:redacted]} agent_id=#{agent_id}") } # rubocop:disable Layout/LineLength
           rescue Sequel::Error => e
+            handle_exception(e, level: :error, operation: 'apollo.knowledge.handle_erasure_request')
             { deleted: 0, redacted: 0, error: e.message }
           end
 
@@ -333,6 +352,27 @@ module Legion
 
           private
 
+          def ingest_early_return_error(content:, content_type:, tags:)
+            if content.strip.empty?
+              safe_tags = Array(tags).map(&:to_s).map { |t| t.gsub(/[\r\n]+/, ' ') }
+              log.warn('[apollo][handle_ingest] early-return: content is required ' \
+                       "content_type=#{content_type} tags=#{safe_tags.inspect}")
+              return { success: false, error: 'content is required' }
+            end
+
+            if content_type.nil?
+              log.warn('[apollo][handle_ingest] early-return: content_type is required ' \
+                       "content_length=#{content.to_s.length}")
+              return { success: false, error: 'content_type is required' }
+            end
+
+            return nil if defined?(Legion::Data::Model::ApolloEntry)
+
+            log.warn('[apollo][handle_ingest] early-return: apollo_data_not_available ' \
+                     "content_type=#{content_type}")
+            { success: false, error: 'apollo_data_not_available' }
+          end
+
           def normalize_content_type(raw)
             sym = raw.to_s.delete_prefix(':').gsub(%r{[/\s]}, '_').strip.downcase.to_sym
             sym = CONTENT_TYPE_ALIASES.fetch(sym, sym)
@@ -341,21 +381,124 @@ module Legion
 
           def embed_text(text)
             text = normalize_text_input(text)
+            log.debug("Apollo Knowledge.embed_text text_length=#{text.length}")
             result = Legion::LLM::Embeddings.generate(text: text)
             vector = result.is_a?(Hash) ? result[:vector] : result
-            vector.is_a?(Array) && vector.any? ? vector : Array.new(1024, 0.0)
+            if vector.is_a?(Array) && vector.any?
+              log.debug("Apollo Knowledge.embed_text vector_dimensions=#{vector.length}")
+              vector
+            else
+              log.warn('Apollo Knowledge.embed_text returned no vector; using zero-vector fallback')
+              Array.new(1024, 0.0)
+            end
           rescue StandardError => e
             log.warn("Apollo Knowledge.embed_text failed: #{e.message}")
             Array.new(1024, 0.0)
           end
 
           def normalize_text_input(value)
-            return Legion::Apollo.send(:normalize_text_input, value) if defined?(Legion::Apollo) && Legion::Apollo.respond_to?(:normalize_text_input, true)
+            result = if defined?(Legion::Apollo) && Legion::Apollo.respond_to?(:normalize_text_input, true)
+                       Legion::Apollo.send(:normalize_text_input, value)
+                     else
+                       value.to_s
+                     end
 
-            value.to_s
+            sanitize_for_postgres(result)
           rescue StandardError => e
             log.warn("Apollo Knowledge.normalize_text_input failed: #{e.message}")
-            value.to_s
+            ''
+          end
+
+          def sanitize_for_postgres(value)
+            return value unless value.is_a?(String)
+
+            string = value.encoding == Encoding::UTF_8 ? value.dup : value.dup.force_encoding(Encoding::UTF_8)
+            changed = string.include?("\x00") || !string.valid_encoding?
+            string = string.scrub('') unless string.valid_encoding?
+            sanitized = string.delete("\x00")
+            log.debug("Apollo Knowledge.sanitize_for_postgres sanitized original_length=#{value.bytesize} sanitized_length=#{sanitized.bytesize}") if changed
+            sanitized
+          end
+
+          def truncate_for_column(value, max_length)
+            return nil if value.nil?
+
+            normalize_text_input(value)[0, max_length]
+          end
+
+          def active_duplicate_for_hash(hash)
+            return nil unless hash
+
+            existing = Legion::Data::Model::ApolloEntry
+                       .where(content_hash: hash)
+                       .exclude(status: 'archived')
+                       .first
+            existing&.update(confidence: [existing.confidence + Helpers::Confidence.retrieval_boost, 1.0].min)
+            log.debug("Apollo Knowledge.active_duplicate_for_hash matched entry_id=#{existing.id}") if existing
+            existing
+          end
+
+          def ingest_metadata(tags:, knowledge_domain:, source_agent:, source_provider:, source_channel:, submitted_by:, submitted_from:)
+            tag_array = defined?(Helpers::TagNormalizer) ? Helpers::TagNormalizer.normalize_all(tags) : Array(tags)
+            agent = truncate_for_column(source_agent, 50) || 'unknown'
+
+            { tags:            tag_array,
+              domain:          truncate_for_column(knowledge_domain || tag_array.first || 'general', 50),
+              source_agent:    agent,
+              source_provider: truncate_for_column(source_provider || derive_provider_from_agent(agent), 50),
+              source_channel:  truncate_for_column(source_channel, 100),
+              submitted_by:    truncate_for_column(submitted_by, 255),
+              submitted_from:  truncate_for_column(submitted_from, 255) }
+          end
+
+          def create_candidate_entry(content:, content_type:, context:, metadata:, content_hash:, embedding:)
+            new_entry = Legion::Data::Model::ApolloEntry.create(
+              content:          content,
+              content_type:     content_type,
+              confidence:       Helpers::Confidence.initial_confidence,
+              source_agent:     metadata[:source_agent],
+              source_provider:  metadata[:source_provider],
+              source_channel:   metadata[:source_channel],
+              source_context:   ::JSON.dump(context.is_a?(Hash) ? context : {}),
+              tags:             Sequel.pg_array(metadata[:tags]),
+              status:           'candidate',
+              knowledge_domain: metadata[:domain],
+              submitted_by:     metadata[:submitted_by],
+              submitted_from:   metadata[:submitted_from],
+              content_hash:     content_hash,
+              embedding:        Sequel.lit("'[#{embedding.join(',')}]'::vector")
+            )
+            log.info("Apollo Knowledge.handle_ingest created entry_id=#{new_entry.id} status=candidate domain=#{metadata[:domain]} source_agent=#{metadata[:source_agent]}") # rubocop:disable Layout/LineLength
+            new_entry.id
+          end
+
+          def browse_query?(query)
+            query.to_s.strip.length < 3
+          end
+
+          def list_entries_chronologically(query:, limit:, status:, status_defaulted:, tags:, domain:)
+            log.debug("Apollo Knowledge.list_entries_chronologically limit=#{limit} statuses=#{Array(status).join(',')} status_defaulted=#{status_defaulted} tags=#{Array(tags).size} domain=#{domain || 'nil'}") # rubocop:disable Layout/LineLength
+            dataset = Legion::Data::Model::ApolloEntry.exclude(status: 'archived')
+            requested = Array(status).map(&:to_s).reject(&:empty?)
+            dataset = dataset.where(status: requested) unless status_defaulted || requested.empty?
+            dataset = dataset.where(Sequel.lit('tags && ?', Sequel.pg_array(Array(tags)))) if tags && !Array(tags).empty?
+            dataset = dataset.where(knowledge_domain: domain) if domain && !domain.to_s.empty?
+
+            entries = dataset.order(Sequel.desc(:created_at)).limit(limit).all.map do |entry|
+              format_entry(entry.is_a?(Hash) ? entry : entry.values)
+            end
+            log.info("Apollo Knowledge.list_entries_chronologically results=#{entries.size}")
+            { success: true, mode: :browse, query: query, entries: entries, count: entries.size }
+          rescue Sequel::Error => e
+            handle_exception(e, level: :error, operation: 'apollo.knowledge.list_entries_chronologically')
+            { success: false, error: e.message }
+          end
+
+          def format_entry(entry)
+            { id: entry[:id], content: entry[:content], content_type: entry[:content_type],
+              confidence: entry[:confidence], distance: entry[:distance]&.to_f,
+              tags: entry[:tags], source_agent: entry[:source_agent],
+              knowledge_domain: entry[:knowledge_domain] }
           end
 
           def allowed_domains_for(target_domain)
@@ -379,6 +522,7 @@ module Legion
             rel_weight = Helpers::Confidence.apollo_setting(:contradiction, :relation_weight, default: 0.8)
 
             db = Legion::Data::Model::ApolloEntry.db
+            log.debug("Apollo Knowledge.detect_contradictions entry_id=#{entry_id} similar_limit=#{sim_limit} threshold=#{sim_threshold}")
             similar = db.fetch(
               "SELECT id, content, embedding FROM apollo_entries WHERE id != :entry_id AND embedding IS NOT NULL ORDER BY embedding <=> :embedding LIMIT #{sim_limit}", # rubocop:disable Layout/LineLength
               entry_id:  entry_id,
@@ -403,9 +547,10 @@ module Legion
               Legion::Data::Model::ApolloEntry.where(id: [entry_id, existing[:id]]).update(status: 'disputed')
               contradictions << existing[:id]
             end
+            log.info("Apollo Knowledge.detect_contradictions entry_id=#{entry_id} contradictions=#{contradictions.size}") if contradictions.any?
             contradictions
           rescue Sequel::Error => e
-            log.warn("Apollo Knowledge.detect_contradictions failed: #{e.message}")
+            handle_exception(e, level: :error, operation: 'apollo.knowledge.detect_contradictions')
             []
           end
 
@@ -430,6 +575,7 @@ module Legion
 
           def find_corroboration(embedding, content_type_sym, source_agent, source_channel = nil)
             scan_limit = Helpers::Confidence.apollo_setting(:corroboration, :scan_limit, default: 50)
+            log.debug("Apollo Knowledge.find_corroboration content_type=#{content_type_sym} source_agent=#{source_agent} source_channel=#{source_channel || 'nil'} scan_limit=#{scan_limit}") # rubocop:disable Layout/LineLength
             existing = Legion::Data::Model::ApolloEntry
                        .where(content_type: content_type_sym)
                        .exclude(embedding: nil)
@@ -462,9 +608,11 @@ module Legion
                 source_agent:  source_agent,
                 weight:        sim
               )
+              log.info("Apollo Knowledge.find_corroboration matched entry_id=#{entry.id} source_agent=#{source_agent} similarity=#{sim}")
               return [true, entry.id]
             end
 
+            log.debug("Apollo Knowledge.find_corroboration no_match source_agent=#{source_agent}")
             [false, nil]
           end
 
@@ -483,6 +631,7 @@ module Legion
           end
 
           def upsert_expertise(source_agent:, domain:)
+            log.debug("Apollo Knowledge.upsert_expertise source_agent=#{source_agent} domain=#{domain}")
             expertise = Legion::Data::Model::ApolloExpertise
                         .where(agent_id: source_agent, domain: domain).first
             if expertise

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

@@ -25,7 +25,11 @@ module Legion
             min_confidence ||= Helpers::Confidence.decay_threshold
             min_age_hours = Helpers::Confidence.decay_min_age_hours
 
-            return { decayed: 0, archived: 0 } unless defined?(Legion::Data) && Legion::Data.respond_to?(:connection) && Legion::Data.connection
+            log.debug("Apollo Maintenance.run_decay_cycle alpha=#{alpha} min_confidence=#{min_confidence} min_age_hours=#{min_age_hours}")
+            unless defined?(Legion::Data) && Legion::Data.respond_to?(:connection) && Legion::Data.connection
+              log.warn('Apollo Maintenance.run_decay_cycle skipped: apollo_data_not_available')
+              return { decayed: 0, archived: 0 }
+            end
 
             conn = Legion::Data.connection
 
@@ -54,15 +58,21 @@ module Legion
 
             { decayed: decayed, archived: archived, alpha: alpha, threshold: min_confidence,
               min_age_hours: min_age_hours }
+              .tap { |result| log.info("Apollo Maintenance.run_decay_cycle decayed=#{result[:decayed]} archived=#{result[:archived]} alpha=#{alpha} threshold=#{min_confidence}") } # rubocop:disable Layout/LineLength
           rescue Sequel::Error => e
+            handle_exception(e, level: :error, operation: 'apollo.maintenance.run_decay_cycle')
             { decayed: 0, archived: 0, error: e.message }
           end
 
           def check_corroboration(**) # rubocop:disable Metrics/CyclomaticComplexity
-            return { success: false, error: 'apollo_data_not_available' } unless defined?(Legion::Data::Model::ApolloEntry)
+            unless defined?(Legion::Data::Model::ApolloEntry)
+              log.warn('Apollo Maintenance.check_corroboration skipped: apollo_data_not_available')
+              return { success: false, error: 'apollo_data_not_available' }
+            end
 
             candidates = Legion::Data::Model::ApolloEntry.where(status: 'candidate').exclude(embedding: nil).all
             confirmed = Legion::Data::Model::ApolloEntry.where(status: 'confirmed').exclude(embedding: nil).all
+            log.debug("Apollo Maintenance.check_corroboration candidates=#{candidates.size} confirmed=#{confirmed.size}")
 
             promoted = 0
 
@@ -106,7 +116,9 @@ module Legion
             end
 
             { success: true, promoted: promoted, scanned: candidates.size }
+              .tap { |result| log.info("Apollo Maintenance.check_corroboration scanned=#{result[:scanned]} promoted=#{result[:promoted]}") }
           rescue Sequel::Error => e
+            handle_exception(e, level: :error, operation: 'apollo.maintenance.check_corroboration')
             { success: false, error: e.message }
           end
 

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

@@ -3,7 +3,7 @@
 module Legion
   module Extensions
     module Apollo
-      VERSION = '0.4.19'
+      VERSION = '0.4.21'
     end
   end
 end

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

@@ -263,6 +263,36 @@ RSpec.describe Legion::Extensions::Apollo::Runners::Knowledge do
                            tags: ['RabbitMQ'], source_agent: 'agent-1')
       end
 
+      it 'sanitizes null bytes before storing content' do
+        expect(mock_entry_class).to receive(:create).with(
+          hash_including(content: 'helloworld')
+        ).and_return(mock_entry)
+        host.handle_ingest(content: "hello\x00world", content_type: 'fact', source_agent: 'agent-1')
+      end
+
+      it 'truncates short varchar metadata fields at the database boundary' do
+        expect(mock_entry_class).to receive(:create).with(
+          hash_including(
+            source_agent:     'a' * 50,
+            source_provider:  'p' * 50,
+            source_channel:   'c' * 100,
+            knowledge_domain: 'd' * 50,
+            submitted_by:     'u' * 255,
+            submitted_from:   'n' * 255
+          )
+        ).and_return(mock_entry)
+        host.handle_ingest(
+          content:          'test',
+          content_type:     'fact',
+          source_agent:     'a' * 60,
+          source_provider:  'p' * 60,
+          source_channel:   'c' * 120,
+          knowledge_domain: 'd' * 60,
+          submitted_by:     'u' * 300,
+          submitted_from:   'n' * 300
+        )
+      end
+
       context 'content hash dedup' do
         let(:existing_entry) do
           double('existing', id: 'uuid-existing', confidence: 0.6,
@@ -295,9 +325,46 @@ RSpec.describe Legion::Extensions::Apollo::Runners::Knowledge do
       end
 
       it 'returns a structured error' do
+        allow(host).to receive(:handle_exception)
+
         result = host.handle_ingest(content: 'test', content_type: 'fact', source_agent: 'a')
         expect(result[:success]).to be false
         expect(result[:error]).to eq('connection lost')
+        expect(host).to have_received(:handle_exception).with(
+          instance_of(Sequel::Error),
+          level:     :error,
+          operation: 'apollo.knowledge.handle_ingest'
+        )
+      end
+    end
+
+    context 'early-return warn logs' do
+      let(:logger) { instance_double('Logger', debug: nil, info: nil, warn: nil) }
+
+      before { allow(host).to receive(:log).and_return(logger) }
+
+      it 'emits a warn log when content is nil' do
+        host.handle_ingest(content: nil, content_type: 'fact')
+        expect(logger).to have_received(:warn).with(/early-return: content is required/)
+      end
+
+      it 'emits a warn log when content_type is nil' do
+        host.handle_ingest(content: 'something', content_type: nil)
+        expect(logger).to have_received(:warn).with(/early-return: content_type is required/)
+      end
+
+      it 'emits a warn log when apollo_data_not_available' do
+        hide_const('Legion::Data::Model::ApolloEntry') if defined?(Legion::Data::Model::ApolloEntry)
+        host.handle_ingest(content: 'something', content_type: 'fact')
+        expect(logger).to have_received(:warn).with(/early-return: apollo_data_not_available/)
+      end
+
+      it 'sanitizes newline-bearing tags in the warn log' do
+        host.handle_ingest(content: nil, content_type: 'fact', tags: ["evil\nFAKE LOG LINE", 'normal'])
+        expect(logger).to have_received(:warn) do |msg|
+          expect(msg).to include('evil FAKE LOG LINE')
+          expect(msg).not_to include("\n")
+        end
       end
     end
   end
@@ -376,6 +443,64 @@ RSpec.describe Legion::Extensions::Apollo::Runners::Knowledge do
         expect(result[:count]).to eq(0)
       end
     end
+
+    context 'when query is browse-shaped' do
+      let(:mock_entry_class) { double('ApolloEntry') }
+      let(:dataset) { double('dataset') }
+      let(:entries) do
+        [{ id: 'uuid-1', content: 'Candidate fact', content_type: 'fact',
+           confidence: 0.7, tags: ['ruby'], source_agent: 'agent-1',
+           knowledge_domain: 'general' }]
+      end
+
+      before do
+        stub_const('Legion::Data::Model::ApolloEntry', mock_entry_class)
+        allow(mock_entry_class).to receive(:exclude).with(status: 'archived').and_return(dataset)
+        allow(dataset).to receive(:where).and_return(dataset)
+        allow(dataset).to receive(:order).with(:created_at).and_return(dataset)
+        allow(dataset).to receive(:limit).with(50).and_return(dataset)
+        allow(dataset).to receive(:all).and_return(entries)
+      end
+
+      it 'lists recent non-archived entries without generating an embedding' do
+        expect(Legion::LLM::Embeddings).not_to receive(:generate)
+
+        result = host.handle_query(query: 'x', limit: 50)
+
+        expect(result[:success]).to be true
+        expect(result[:mode]).to eq(:browse)
+        expect(result[:count]).to eq(1)
+        expect(result[:entries].first[:content]).to eq('Candidate fact')
+        expect(dataset).not_to have_received(:where).with(status: ['confirmed'])
+      end
+
+      it 'respects an explicit confirmed status filter' do
+        host.handle_query(query: 'x', limit: 50, status: [:confirmed])
+
+        expect(dataset).to have_received(:where).with(status: ['confirmed'])
+      end
+
+      it 'applies tags and domain filters when provided' do
+        host.handle_query(query: 'x', limit: 50, tags: ['ruby'], domain: 'general')
+
+        expect(dataset).to have_received(:where).with('tags && ?')
+        expect(dataset).to have_received(:where).with(knowledge_domain: 'general')
+      end
+    end
+  end
+
+  describe '#normalize_text_input' do
+    let(:host) { Object.new.extend(described_class) }
+
+    it 'strips null bytes in the local fallback path' do
+      expect(host.send(:normalize_text_input, "hello\x00world")).to eq('helloworld')
+    end
+
+    it 'scrubs invalid UTF-8 in the local fallback path' do
+      invalid = "hello\xC3(world".dup.force_encoding(Encoding::UTF_8)
+
+      expect(host.send(:normalize_text_input, invalid)).to eq('hello(world')
+    end
   end
 
   describe '#retrieve_relevant' do

data/spec/spec_helper.rb

@@ -16,6 +16,7 @@ unless defined?(Sequel)
 
     def self.pg_array(arr) = arr
     def self.lit(str, *) = str
+    def self.desc(sym) = sym
     Expr = Struct.new(:value) do
       def +(other) = "#{value} + #{other}"
       def *(other) = "#{value} * #{other}"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-apollo
 version: !ruby/object:Gem::Version
-  version: 0.4.19
+  version: 0.4.21
 platform: ruby
 authors:
 - Esity