legion-apollo 0.3.7 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd344e49282eb4e397ce81a5920980466dea27d9b23cf4156f549280f46af768
-  data.tar.gz: 96b8d482992dbbe9d442bead192f128cf96dc776879cebd68e8b934b281c157e
+  metadata.gz: 7468f022e582731ace40da083285569d57c98e38ef375e5745f43d93e9c9d171
+  data.tar.gz: 3d2bb59a17a6060e690c7321fc914d2dc2e2bdd7bb1ec108917bf86fc7f26c72
 SHA512:
-  metadata.gz: 35bc5fac20a5d153a54805d23a33218fed71177fe4b4f63724b527cc8fe3ca761912b617c0dc80380609d7eaa32a3197070525c9b08330f200343198ea01988d
-  data.tar.gz: 6b84f74fd517e4500d389fe51d9bd7f149abd96ccd4eaac2d110899f82ed6856be775f5a55c104a0f59cb92a974ba9da6237bc1bce16c564bd1725e738c3de43
+  metadata.gz: a47cb6e18c47432ec0f3a15872f52dc193d7253fda94833da1c63d6046ad39bba8894f10dacc1c3472d7ef538157aad39cf1cf9894061623a9f1a162f69a5c16
+  data.tar.gz: 3ca7dc35c483089a4b2c6bb0af57b524afe3a3cce571b893a14a4aa01f74fbb01b51b5eb09040389db09a6b5f2516d0bd6d97fc499bf8c912aadc6c3b622a587

data/CHANGELOG.md

@@ -1,6 +1,24 @@
 # Changelog
 
-## [Unreleased]
+## [0.4.0] - 2026-04-02
+
+### Changed
+- Adopt `Legion::Logging::Helper` across the Apollo core, local store, graph layer, message publishers, and helper modules
+- Require `legion-logging >= 1.5.0` for structured helper-based logging support
+- Remove unused top-level Apollo defaults for transport mode and timeout settings
+
+### Fixed
+- Start addressing Apollo local lifecycle, merged routing, hydration contract, and route/runtime drift for the 0.4.x line
+- `Apollo.shutdown` now shuts down `Apollo::Local`, and `Apollo::Local.upsert` refreshes expiry and embedding metadata for updated rows
+- `Apollo::Local.hydrate_from_global` now accepts Apollo's `entries` response shape, and `query(scope: :all)` falls back to async global transport when no synchronous backends are available
+- `apollo.enabled` now gates startup, `Apollo::Local.query_by_tags` filters in SQLite before applying limits, and message publish behavior has direct spec coverage
+- Blank local queries now bypass invalid FTS `MATCH ''` calls while still supporting tag-filtered lookups
+- REST query and ingest routes now delegate to `Legion::Apollo`, return `202` for async transport fallback, and stop reporting failed ingests as `201 Created`
+- Apollo and Apollo::Local lifecycle, seeding, and hydration flows are now serialized, while local ingest/upsert keeps base rows and FTS updates inside the same transaction and treats duplicate content races as deterministic deduplication
+- Apollo and Apollo::Local now normalize tag inputs consistently for direct Ruby callers, so ingest, query, and upsert semantics match the route-layer tag contract
+- Apollo graph relationships now reject invalid relation types, deduplicate duplicate semantic edges with a unique index, delete entities transactionally, and traverse larger graphs with batched frontier expansion
+
+## [0.3.7] - 2026-03-31
 
 ### Added
 - `Apollo::Local.promote_to_global(tags:, min_confidence:)` — promotes local entries to Apollo Global

data/README.md

@@ -46,6 +46,7 @@ Features:
 ```json
 {
   "apollo": {
+    "enabled": true,
     "default_limit": 5,
     "min_confidence": 0.3,
     "max_tags": 20,

data/lib/legion/apollo/helpers/confidence.rb

@@ -1,11 +1,15 @@
 # frozen_string_literal: true
 
+require 'legion/logging'
+
 module Legion
   module Apollo
     module Helpers
       # Confidence constants and predicate helpers for Apollo knowledge entries.
       # DB-dependent methods live in lex-apollo; only pure-function logic here.
       module Confidence
+        extend Legion::Logging::Helper
+
         INITIAL_CONFIDENCE     = 0.5
         CORROBORATION_BOOST    = 0.15
         CONTRADICTION_PENALTY  = 0.20
@@ -43,7 +47,8 @@ module Legion
           return default unless defined?(Legion::Settings) && !Legion::Settings[:apollo].nil?
 
           Legion::Settings[:apollo][key] || default
-        rescue StandardError
+        rescue StandardError => e
+          handle_exception(e, level: :debug, operation: 'apollo.helpers.confidence.apollo_setting', key: key)
           default
         end
       end

data/lib/legion/apollo/helpers/similarity.rb

@@ -1,10 +1,14 @@
 # frozen_string_literal: true
 
+require 'legion/logging'
+
 module Legion
   module Apollo
     module Helpers
       # Pure cosine similarity math and match classification for Apollo vectors.
       module Similarity
+        extend Legion::Logging::Helper
+
         EXACT_MATCH_THRESHOLD     = 0.95
         HIGH_SIMILARITY_THRESHOLD = 0.85
         CORROBORATION_THRESHOLD   = 0.75
@@ -12,7 +16,7 @@ module Legion
 
         module_function
 
-        def cosine_similarity(vec_a, vec_b) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+        def cosine_similarity(vec_a, vec_b) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/CyclomaticComplexity
           return 0.0 if vec_a.nil? || vec_b.nil? || vec_a.empty? || vec_b.empty?
           return 0.0 unless vec_a.size == vec_b.size
 
@@ -30,9 +34,18 @@ module Legion
 
           denom = Math.sqrt(mag_a) * Math.sqrt(mag_b)
           denom.zero? ? 0.0 : (dot / denom)
+        rescue StandardError => e
+          handle_exception(
+            e,
+            level:      :debug,
+            operation:  'apollo.helpers.similarity.cosine_similarity',
+            vec_a_size: Array(vec_a).size,
+            vec_b_size: Array(vec_b).size
+          )
+          0.0
         end
 
-        def classify_match(similarity)
+        def classify_match(similarity) # rubocop:disable Metrics/MethodLength
           case similarity
           when EXACT_MATCH_THRESHOLD..1.0                          then :exact
           when HIGH_SIMILARITY_THRESHOLD...EXACT_MATCH_THRESHOLD   then :high
@@ -40,6 +53,14 @@ module Legion
           when RELATED_THRESHOLD...CORROBORATION_THRESHOLD          then :related
           else :unrelated
           end
+        rescue StandardError => e
+          handle_exception(
+            e,
+            level:      :debug,
+            operation:  'apollo.helpers.similarity.classify_match',
+            similarity: similarity
+          )
+          :unrelated
         end
       end
     end

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

@@ -1,16 +1,20 @@
 # frozen_string_literal: true
 
+require 'legion/logging'
+
 module Legion
   module Apollo
     module Helpers
       # Pure-function tag normalization: lowercase, strip invalid chars, dedup, truncate.
       module TagNormalizer
+        extend Legion::Logging::Helper
+
         MAX_TAG_LENGTH = 64
         MAX_TAGS       = 20
 
         module_function
 
-        def normalize(tags)
+        def normalize(tags) # rubocop:disable Metrics/MethodLength
           return [] unless tags.is_a?(Array)
 
           tags
@@ -18,14 +22,30 @@ module Legion
             .compact
             .uniq
             .first(MAX_TAGS)
+        rescue StandardError => e
+          handle_exception(
+            e,
+            level:     :debug,
+            operation: 'apollo.helpers.tag_normalizer.normalize',
+            tag_count: Array(tags).size
+          )
+          []
         end
 
-        def normalize_one(tag)
+        def normalize_one(tag) # rubocop:disable Metrics/MethodLength
           return nil if tag.nil?
 
           normalized = tag.to_s.strip.downcase.gsub(/[^a-z0-9_:-]/, '_').squeeze('_')
           normalized = normalized[0, MAX_TAG_LENGTH] if normalized.length > MAX_TAG_LENGTH
           normalized.empty? ? nil : normalized
+        rescue StandardError => e
+          handle_exception(
+            e,
+            level:     :debug,
+            operation: 'apollo.helpers.tag_normalizer.normalize_one',
+            tag_class: tag.class.to_s
+          )
+          nil
         end
       end
     end

data/lib/legion/apollo/local/graph.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'legion/logging'
 require 'time'
 
 module Legion
@@ -8,25 +9,37 @@ module Legion
       # Entity-relationship graph layer backed by local SQLite tables.
       # Entities are schema-flexible (type + name + domain + JSON attributes).
       # Relationships are directional typed edges between two entities.
-      # Graph traversal uses recursive SQLite CTEs (max_depth enforced).
+      # Graph traversal expands one frontier batch per depth to avoid per-node queries.
       module Graph # rubocop:disable Metrics/ModuleLength
         VALID_RELATION_TYPES = %w[AFFECTS OWNED_BY DEPENDS_ON RELATED_TO].freeze
 
         class << self # rubocop:disable Metrics/ClassLength
+          include Legion::Logging::Helper
+
           # --- Entity CRUD ---
 
           def create_entity(type:, name:, domain: nil, attributes: {}) # rubocop:disable Metrics/MethodLength
             now = timestamp
-            id = db[:local_entities].insert(
-              entity_type: type.to_s,
-              name:        name.to_s,
-              domain:      domain&.to_s,
-              attributes:  encode(attributes),
-              created_at:  now,
-              updated_at:  now
-            )
+            id = db.transaction do
+              db[:local_entities].insert(
+                entity_type: type.to_s,
+                name:        name.to_s,
+                domain:      domain&.to_s,
+                attributes:  encode(attributes),
+                created_at:  now,
+                updated_at:  now
+              )
+            end
+            log.info { "Apollo::Local::Graph created entity id=#{id} type=#{type} name=#{name}" }
             { success: true, id: id }
           rescue Sequel::Error => e
+            handle_exception(
+              e,
+              level:       :error,
+              operation:   'apollo.local.graph.create_entity',
+              entity_type: type,
+              name:        name
+            )
             { success: false, error: e.message }
           end
 
@@ -34,26 +47,44 @@ module Legion
             row = db[:local_entities].where(id: id).first
             return { success: false, error: :not_found } unless row
 
+            log.debug { "Apollo::Local::Graph found entity id=#{id}" }
             { success: true, entity: decode_entity(row) }
           rescue Sequel::Error => e
+            handle_exception(e, level: :error, operation: 'apollo.local.graph.find_entity', entity_id: id)
             { success: false, error: e.message }
           end
 
-          def find_entities_by_type(type:, limit: 50)
+          def find_entities_by_type(type:, limit: 50) # rubocop:disable Metrics/MethodLength
             rows = db[:local_entities].where(entity_type: type.to_s).limit(limit).all
+            log.debug { "Apollo::Local::Graph found entities type=#{type} count=#{rows.size}" }
             { success: true, entities: rows.map { |r| decode_entity(r) }, count: rows.size }
           rescue Sequel::Error => e
+            handle_exception(
+              e,
+              level:       :error,
+              operation:   'apollo.local.graph.find_entities_by_type',
+              entity_type: type,
+              limit:       limit
+            )
             { success: false, error: e.message }
           end
 
-          def find_entities_by_name(name:, limit: 50)
+          def find_entities_by_name(name:, limit: 50) # rubocop:disable Metrics/MethodLength
             rows = db[:local_entities].where(name: name.to_s).limit(limit).all
+            log.debug { "Apollo::Local::Graph found entities name=#{name} count=#{rows.size}" }
             { success: true, entities: rows.map { |r| decode_entity(r) }, count: rows.size }
           rescue Sequel::Error => e
+            handle_exception(
+              e,
+              level:     :error,
+              operation: 'apollo.local.graph.find_entities_by_name',
+              name:      name,
+              limit:     limit
+            )
             { success: false, error: e.message }
           end
 
-          def update_entity(id:, **fields)
+          def update_entity(id:, **fields) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
             now = timestamp
             updates = fields.slice(:entity_type, :name, :domain).transform_values(&:to_s)
             updates[:attributes] = encode(fields[:attributes]) if fields.key?(:attributes)
@@ -62,40 +93,71 @@ module Legion
             count = db[:local_entities].where(id: id).update(updates)
             return { success: false, error: :not_found } if count.zero?
 
+            log.info { "Apollo::Local::Graph updated entity id=#{id}" }
             { success: true, id: id }
           rescue Sequel::Error => e
+            handle_exception(
+              e,
+              level:     :error,
+              operation: 'apollo.local.graph.update_entity',
+              entity_id: id,
+              fields:    fields.keys
+            )
             { success: false, error: e.message }
           end
 
           def delete_entity(id:)
-            db[:local_relationships].where(source_entity_id: id).delete
-            db[:local_relationships].where(target_entity_id: id).delete
-            count = db[:local_entities].where(id: id).delete
-            return { success: false, error: :not_found } if count.zero?
+            result = delete_entity_transaction(id)
+            return result unless result[:success]
 
-            { success: true, id: id }
+            log.info { "Apollo::Local::Graph deleted entity id=#{id}" }
+            result
           rescue Sequel::Error => e
+            handle_exception(e, level: :error, operation: 'apollo.local.graph.delete_entity', entity_id: id)
             { success: false, error: e.message }
           end
 
           # --- Relationship CRUD ---
 
           def create_relationship(source_id:, target_id:, relation_type:, attributes: {}) # rubocop:disable Metrics/MethodLength
-            now = timestamp
-            id = db[:local_relationships].insert(
-              source_entity_id: source_id,
-              target_entity_id: target_id,
-              relation_type:    relation_type.to_s.upcase,
-              attributes:       encode(attributes),
-              created_at:       now,
-              updated_at:       now
-            )
+            normalized_relation_type = normalize_relation_type(relation_type)
+            return invalid_relation_type_error(relation_type) unless normalized_relation_type
+
+            existing = existing_relationship(source_id, target_id, normalized_relation_type)
+            return deduplicated_relationship(existing) if existing
+
+            id = insert_relationship(source_id, target_id, normalized_relation_type, attributes)
+            log.info do
+              "Apollo::Local::Graph created relationship id=#{id} source_id=#{source_id} " \
+                "target_id=#{target_id} relation_type=#{normalized_relation_type}"
+            end
             { success: true, id: id }
+          rescue Sequel::UniqueConstraintViolation => e
+            duplicate = handle_duplicate_relationship(source_id, target_id, normalized_relation_type)
+            return duplicate if duplicate
+
+            handle_exception(
+              e,
+              level:         :error,
+              operation:     'apollo.local.graph.create_relationship',
+              source_id:     source_id,
+              target_id:     target_id,
+              relation_type: normalized_relation_type
+            )
+            { success: false, error: e.message }
           rescue Sequel::Error => e
+            handle_exception(
+              e,
+              level:         :error,
+              operation:     'apollo.local.graph.create_relationship',
+              source_id:     source_id,
+              target_id:     target_id,
+              relation_type: relation_type
+            )
             { success: false, error: e.message }
           end
 
-          def find_relationships(entity_id:, relation_type: nil, direction: :outbound)
+          def find_relationships(entity_id:, relation_type: nil, direction: :outbound) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
             ds = case direction
                  when :inbound  then db[:local_relationships].where(target_entity_id: entity_id)
                  when :both     then relationship_both_directions(entity_id)
@@ -103,24 +165,39 @@ module Legion
                  end
             ds = ds.where(relation_type: relation_type.to_s.upcase) if relation_type
             rows = ds.all
+            log.debug do
+              "Apollo::Local::Graph found relationships entity_id=#{entity_id} direction=#{direction} " \
+                "relation_type=#{relation_type || 'any'} count=#{rows.size}"
+            end
             { success: true, relationships: rows.map { |r| decode_relationship(r) }, count: rows.size }
           rescue Sequel::Error => e
+            handle_exception(
+              e,
+              level:         :error,
+              operation:     'apollo.local.graph.find_relationships',
+              entity_id:     entity_id,
+              relation_type: relation_type,
+              direction:     direction
+            )
             { success: false, error: e.message }
           end
 
           def delete_relationship(id:)
-            count = db[:local_relationships].where(id: id).delete
+            count = db.transaction { db[:local_relationships].where(id: id).delete }
             return { success: false, error: :not_found } if count.zero?
 
+            log.info { "Apollo::Local::Graph deleted relationship id=#{id}" }
             { success: true, id: id }
           rescue Sequel::Error => e
+            handle_exception(e, level: :error, operation: 'apollo.local.graph.delete_relationship', relationship_id: id)
             { success: false, error: e.message }
           end
 
           # --- Graph Traversal ---
 
           # Traverse from an entity following edges of the given relation_type.
-          # Returns all reachable entities within max_depth hops using a recursive CTE.
+          # Returns all reachable entities within max_depth hops by expanding one
+          # frontier batch per depth level instead of querying neighbors per node.
           #
           # @param entity_id [Integer] starting entity id
           # @param relation_type [String, nil] filter by edge type (nil = any)
@@ -141,50 +218,135 @@ module Legion
               count:   entity_rows.size
             }
           rescue Sequel::Error => e
+            handle_exception(
+              e,
+              level:         :error,
+              operation:     'apollo.local.graph.traverse',
+              entity_id:     entity_id,
+              relation_type: relation_type,
+              depth:         depth,
+              direction:     direction
+            )
             { success: false, error: e.message }
           end
 
           private
 
-          def run_traversal(start_id, rel_filter, max_depth, direction) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
-            visited   = Set.new
+          def run_traversal(start_id, rel_filter, max_depth, direction) # rubocop:disable Metrics/MethodLength
+            visited   = Set.new([start_id])
             frontier  = [start_id]
             edge_rows = []
 
-            # Run max_depth + 1 passes so that depth=1 means "start node + its direct neighbors".
-            # Pass 0 visits the start node and pushes its neighbors into the next frontier.
-            # Passes 1..max_depth each follow one more hop.
-            (max_depth + 1).times do
+            max_depth.times do
               break if frontier.empty?
 
-              next_frontier = []
-              frontier.each do |current_id|
-                next if visited.include?(current_id)
-
-                visited.add(current_id)
-                neighbors, edges = fetch_neighbors(current_id, rel_filter, direction)
-                edge_rows.concat(edges)
-                neighbors.each { |n| next_frontier << n unless visited.include?(n) }
-              end
-              frontier = next_frontier
+              rows = fetch_frontier_edges(frontier, rel_filter, direction)
+              edge_rows.concat(rows)
+              frontier = next_frontier_ids(rows, direction).reject { |neighbor_id| visited.include?(neighbor_id) }.uniq
+              frontier.each { |neighbor_id| visited.add(neighbor_id) }
             end
 
             [visited.to_a, edge_rows.uniq { |r| r[:id] }]
           end
 
-          def fetch_neighbors(entity_id, rel_filter, direction)
+          def fetch_frontier_edges(frontier, rel_filter, direction)
             ds = case direction
-                 when :inbound then db[:local_relationships].where(target_entity_id: entity_id)
-                 else               db[:local_relationships].where(source_entity_id: entity_id)
+                 when :inbound then db[:local_relationships].where(target_entity_id: frontier)
+                 else               db[:local_relationships].where(source_entity_id: frontier)
                  end
             ds = ds.where(relation_type: rel_filter) if rel_filter
-            rows = ds.all
+            ds.all
+          end
 
-            neighbor_ids = rows.map do |r|
-              direction == :inbound ? r[:source_entity_id] : r[:target_entity_id]
+          def next_frontier_ids(rows, direction)
+            rows.map do |row|
+              direction == :inbound ? row[:source_entity_id] : row[:target_entity_id]
             end
+          end
+
+          def normalize_relation_type(relation_type)
+            normalized = relation_type.to_s.upcase
+            return normalized if VALID_RELATION_TYPES.include?(normalized)
+
+            nil
+          end
+
+          def invalid_relation_type_error(relation_type)
+            log.warn { "Apollo::Local::Graph rejected invalid relation_type=#{relation_type}" }
+            { success: false, error: :invalid_relation_type }
+          end
+
+          def existing_relationship(source_id, target_id, relation_type)
+            db[:local_relationships].where(
+              source_entity_id: source_id,
+              target_entity_id: target_id,
+              relation_type:    relation_type
+            ).first
+          end
+
+          def deduplicated_relationship(existing)
+            log.info do
+              "Apollo::Local::Graph deduplicated relationship id=#{existing[:id]} " \
+                "relation_type=#{existing[:relation_type]}"
+            end
+            { success: true, id: existing[:id], mode: :deduplicated }
+          end
+
+          def insert_relationship(source_id, target_id, relation_type, attributes)
+            db.transaction do
+              db[:local_relationships].insert(relationship_row(source_id, target_id, relation_type, attributes))
+            end
+          end
+
+          def relationship_row(source_id, target_id, relation_type, attributes)
+            now = timestamp
+            {
+              source_entity_id: source_id,
+              target_entity_id: target_id,
+              relation_type:    relation_type,
+              attributes:       encode(attributes),
+              created_at:       now,
+              updated_at:       now
+            }
+          end
+
+          def handle_duplicate_relationship(source_id, target_id, relation_type)
+            existing = existing_relationship(source_id, target_id, relation_type)
+            return deduplicated_relationship(existing) if existing
+
+            nil
+          end
+
+          def delete_entity_transaction(id)
+            result = nil
+            db.transaction do
+              result = existing_entity?(id) ? delete_existing_entity(id) : missing_entity_result
+              raise Sequel::Rollback unless result[:success]
+            end
+            result
+          end
+
+          def existing_entity?(id)
+            !db[:local_entities].where(id: id).first.nil?
+          end
+
+          def delete_existing_entity(id)
+            delete_entity_relationships(id)
+            delete_entity_row(id)
+            { success: true, id: id }
+          end
+
+          def missing_entity_result
+            { success: false, error: :not_found }
+          end
+
+          def delete_entity_relationships(id)
+            db[:local_relationships].where(source_entity_id: id).delete
+            db[:local_relationships].where(target_entity_id: id).delete
+          end
 
-            [neighbor_ids, rows]
+          def delete_entity_row(id)
+            db[:local_entities].where(id: id).delete
           end
 
           def relationship_both_directions(entity_id)
@@ -206,7 +368,8 @@ module Legion
             return '{}' if obj.nil? || obj.empty?
 
             Legion::JSON.dump(obj)
-          rescue StandardError
+          rescue StandardError => e
+            handle_exception(e, level: :debug, operation: 'apollo.local.graph.encode')
             '{}'
           end
 
@@ -214,7 +377,8 @@ module Legion
             return {} if json_str.nil? || json_str.strip.empty?
 
             Legion::JSON.parse(json_str, symbolize_names: true)
-          rescue StandardError
+          rescue StandardError => e
+            handle_exception(e, level: :debug, operation: 'apollo.local.graph.decode')
             {}
           end
 

data/lib/legion/apollo/local/migrations/003_harden_graph_relationships.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+Sequel.migration do
+  up do
+    run <<~SQL
+      DELETE FROM local_relationships
+      WHERE id NOT IN (
+        SELECT MIN(id)
+        FROM local_relationships
+        GROUP BY source_entity_id, target_entity_id, relation_type
+      )
+    SQL
+
+    run <<~SQL
+      CREATE UNIQUE INDEX IF NOT EXISTS idx_local_rel_unique
+      ON local_relationships (source_entity_id, target_entity_id, relation_type)
+    SQL
+  end
+
+  down do
+    run 'DROP INDEX IF EXISTS idx_local_rel_unique'
+  end
+end