igniter 0.5.0 → 0.5.1

data/packages/igniter-cluster/lib/igniter/cluster/ownership/registry.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    module Ownership
+      class Registry
+        def initialize(store: nil, collection: "igniter_cluster_ownership_claims")
+          @store = store
+          @collection = collection.to_s
+          @claims = {}
+          @mutex = Mutex.new
+        end
+
+        def claim(entity_type, entity_id, owner:, metadata: {})
+          claim = Claim.new(
+            entity_type: entity_type,
+            entity_id: entity_id,
+            owner: owner,
+            metadata: metadata
+          )
+          write_claim(claim)
+          claim
+        end
+
+        def lookup(entity_type, entity_id)
+          key = claim_key(entity_type, entity_id)
+          if persistent?
+            payload = @store.get(collection: @collection, key: key)
+            payload ? Claim.from_h(payload) : nil
+          else
+            @mutex.synchronize { @claims[key] }
+          end
+        end
+
+        def owner_for(entity_type, entity_id)
+          lookup(entity_type, entity_id)&.owner
+        end
+
+        def claimed?(entity_type, entity_id)
+          !lookup(entity_type, entity_id).nil?
+        end
+
+        def release(entity_type, entity_id, owner: nil)
+          key = claim_key(entity_type, entity_id)
+          existing = lookup(entity_type, entity_id)
+          return nil unless existing
+          return nil if owner && existing.owner != owner.to_s
+
+          if persistent?
+            @store.delete(collection: @collection, key: key)
+          else
+            @mutex.synchronize { @claims.delete(key) }
+          end
+        end
+
+        def claims_for_owner(owner)
+          @mutex.synchronize do
+            @claims.values.select { |claim| claim.owner == owner.to_s }
+          end
+        end
+
+        def all
+          if persistent?
+            @store.all(collection: @collection).values.map { |payload| Claim.from_h(payload) }
+          else
+            @mutex.synchronize { @claims.values.dup }
+          end
+        end
+
+        def clear
+          if persistent?
+            @store.clear(collection: @collection)
+          else
+            @mutex.synchronize { @claims.clear }
+          end
+        end
+
+        private
+
+        def persistent?
+          !@store.nil?
+        end
+
+        def write_claim(claim)
+          if persistent?
+            @store.put(collection: @collection, key: claim.key, value: claim.to_h)
+          else
+            @mutex.synchronize { @claims[claim.key] = claim }
+          end
+        end
+
+        def claim_key(entity_type, entity_id)
+          "#{entity_type}:#{entity_id}"
+        end
+      end
+    end
+  end
+end

data/packages/igniter-cluster/lib/igniter/cluster/ownership/resolver.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    module Ownership
+      class Resolver
+        def initialize(registry:, mesh_router: nil)
+          @registry = registry
+          @mesh_router = mesh_router
+        end
+
+        def resolve(entity_type, entity_id, fallback_capability: nil, fallback_query: nil, deferred_result: nil)
+          claim = @registry.lookup(entity_type, entity_id)
+          if claim
+            return {
+              mode: :owner,
+              owner: claim.owner,
+              claim: claim,
+              url: mesh_router.resolve_pinned(claim.owner)
+            }
+          end
+
+          if fallback_query
+            return {
+              mode: :capability_query,
+              owner: nil,
+              claim: nil,
+              url: mesh_router.find_peer_for_query(fallback_query, deferred_result)
+            }
+          end
+
+          if fallback_capability
+            return {
+              mode: :capability,
+              owner: nil,
+              claim: nil,
+              url: mesh_router.find_peer_for(fallback_capability, deferred_result)
+            }
+          end
+
+          raise NoOwnerError.new(entity_type, entity_id)
+        end
+
+        def resolve_url(entity_type, entity_id, fallback_capability: nil, fallback_query: nil, deferred_result: nil)
+          resolve(
+            entity_type,
+            entity_id,
+            fallback_capability: fallback_capability,
+            fallback_query: fallback_query,
+            deferred_result: deferred_result
+          ).fetch(:url)
+        end
+
+        private
+
+        def mesh_router
+          @mesh_router ||= Igniter::Cluster::Mesh.router
+        end
+      end
+    end
+  end
+end

data/packages/igniter-cluster/lib/igniter/cluster/ownership.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative "ownership/errors"
+require_relative "ownership/claim"
+require_relative "ownership/registry"
+require_relative "ownership/resolver"
+require_relative "ownership/owner_client"
+
+module Igniter
+  module Cluster
+    module Ownership
+      class << self
+        attr_reader :store
+
+        def registry
+          @registry ||= Registry.new(store: @store)
+        end
+
+        def resolver
+          @resolver ||= Resolver.new(registry: registry)
+        end
+
+        def client
+          @client ||= OwnerClient.new(resolver: resolver)
+        end
+
+        def configure
+          yield self
+        end
+
+        def store=(store)
+          @store = store
+          @registry = nil
+          @resolver = nil
+          @client = nil
+        end
+
+        def claim(entity_type, entity_id, owner:, metadata: {})
+          registry.claim(entity_type, entity_id, owner: owner, metadata: metadata)
+        end
+
+        def lookup(entity_type, entity_id)
+          registry.lookup(entity_type, entity_id)
+        end
+
+        def owner_for(entity_type, entity_id)
+          registry.owner_for(entity_type, entity_id)
+        end
+
+        def claimed?(entity_type, entity_id)
+          registry.claimed?(entity_type, entity_id)
+        end
+
+        def release(entity_type, entity_id, owner: nil)
+          registry.release(entity_type, entity_id, owner: owner)
+        end
+
+        def claims_for_owner(owner)
+          registry.claims_for_owner(owner)
+        end
+
+        def resolve_url(entity_type, entity_id, fallback_capability: nil, fallback_query: nil, deferred_result: nil)
+          resolver.resolve_url(
+            entity_type,
+            entity_id,
+            fallback_capability: fallback_capability,
+            fallback_query: fallback_query,
+            deferred_result: deferred_result
+          )
+        end
+
+        def reset!
+          @registry = nil
+          @resolver = nil
+          @client = nil
+          @store = nil
+        end
+      end
+    end
+  end
+end

data/packages/igniter-cluster/lib/igniter/cluster/projection_store.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Igniter
+  module Cluster
+    class ProjectionStore
+      def initialize(store:, collection:, primary_key: "id", timestamp_field: "projection_updated_at", clock: nil)
+        @store = store
+        @collection = collection.to_s
+        @primary_key = primary_key.to_s
+        @timestamp_field = timestamp_field.to_s
+        @clock = clock || -> { Time.now.utc.iso8601 }
+      end
+
+      def project(record = nil, key: nil, metadata: {}, **attributes)
+        entry = stringify_keys(record || attributes).merge(stringify_keys(metadata))
+        projection_key = key_for(entry, explicit_key: key)
+        entry[@primary_key] = projection_key
+        entry[@timestamp_field] = @clock.call
+        active_store.put(collection: @collection, key: projection_key, value: entry)
+      end
+
+      def get(key)
+        active_store.get(collection: @collection, key: key.to_s)
+      end
+
+      def all
+        active_store.all(collection: @collection).values
+      end
+
+      def delete(key)
+        active_store.delete(collection: @collection, key: key.to_s)
+      end
+
+      def clear
+        active_store.clear(collection: @collection)
+      end
+
+      private
+
+      def active_store
+        @store.respond_to?(:call) ? @store.call : @store
+      end
+
+      def key_for(entry, explicit_key:)
+        return explicit_key.to_s unless explicit_key.nil?
+
+        key = entry[@primary_key]
+        raise ArgumentError, "projection record is missing primary key #{@primary_key.inspect}" if key.to_s.empty?
+
+        key.to_s
+      end
+
+      def stringify_keys(hash)
+        hash.each_with_object({}) do |(key, value), memo|
+          memo[key.to_s] = value
+        end
+      end
+    end
+  end
+end

data/packages/igniter-cluster/lib/igniter/cluster/rag/chunk.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Igniter
+  module Cluster
+    module RAG
+      # A content-addressed unit of knowledge stored in a KnowledgeShard.
+      #
+      # The id is derived from the first 16 hex digits of SHA256(content),
+      # making adds idempotent: storing the same text twice yields the same id.
+      #
+      # Chunk is a frozen value object — use KnowledgeShard to build and store chunks.
+      Chunk = ::Data.define(:id, :content, :tags, :metadata, :indexed_at) do
+        # Build a Chunk from raw content. Computes the content-addressed id.
+        #
+        # @param content    [String]
+        # @param tags       [Array<Symbol, String>]
+        # @param metadata   [Hash]
+        # @param indexed_at [Time]
+        # @return [Chunk]
+        def self.build(content, tags: [], metadata: {}, indexed_at: Time.now.utc)
+          text = content.to_s
+          new(
+            id:         Digest::SHA256.hexdigest(text)[0, 16],
+            content:    text.freeze,
+            tags:       Array(tags).map(&:to_sym).freeze,
+            metadata:   Hash(metadata).freeze,
+            indexed_at: indexed_at
+          )
+        end
+
+        def tag?(tag)
+          tags.include?(tag.to_sym)
+        end
+
+        def to_h
+          {
+            id:         id,
+            content:    content,
+            tags:       tags,
+            metadata:   metadata,
+            indexed_at: indexed_at.iso8601
+          }
+        end
+      end
+    end
+  end
+end

data/packages/igniter-cluster/lib/igniter/cluster/rag/fanout_retriever.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    module RAG
+      # Fans out a RetrievalQuery to all :rag-capable peers discovered via the
+      # PeerRegistry, merges remote results with the local shard through the
+      # trust-aware Ranker.
+      #
+      # Fan-out is parallel (one Thread per peer) with a configurable timeout.
+      # Any peer that fails or times out silently returns [] — the local shard
+      # always contributes regardless of remote availability.
+      #
+      # Usage:
+      #   retriever = FanoutRetriever.new(
+      #     registry:    Igniter::Cluster::Mesh.config.peer_registry,
+      #     local_shard: Igniter::Cluster::Mesh.shard,
+      #     adapter:     RAG::NetHttpAdapter.new(timeout: 3)
+      #   )
+      #   results = retriever.retrieve("how closures work in Ruby", tags: [:ruby], limit: 10)
+      #
+      # Or via the Mesh convenience entry point:
+      #   Igniter::Cluster::Mesh.retrieve("closures", distributed: true)
+      class FanoutRetriever
+        DEFAULT_TIMEOUT    = 5
+        DEFAULT_REQUIRE_TRUST = true
+
+        # @param registry      [PeerRegistry]             live peer registry
+        # @param local_shard   [KnowledgeShard, nil]      local shard (nil = skip local)
+        # @param adapter       [#call(url, query, observation:)]  HTTP adapter
+        # @param now           [Time]
+        # @param timeout       [Numeric]                  seconds per remote call
+        # @param require_trust [Boolean]                  skip untrusted peers
+        def initialize(registry:, local_shard: nil, adapter: nil, now: Time.now.utc,
+                       timeout: DEFAULT_TIMEOUT, require_trust: DEFAULT_REQUIRE_TRUST)
+          @registry      = registry
+          @local_shard   = local_shard
+          @adapter       = adapter || NetHttpAdapter.new(timeout: timeout)
+          @now           = now
+          @require_trust = require_trust
+        end
+
+        # Run local + distributed retrieval and return merged results.
+        #
+        # @param query_or_text [RetrievalQuery, String]
+        # @param tags          [Array<Symbol>]   used only when query_or_text is a String
+        # @param limit         [Integer]
+        # @param min_score     [Float]
+        # @return [Array<RetrievalResult>]
+        def retrieve(query_or_text, tags: [], limit: 10, min_score: 0.0)
+          query = coerce_query(query_or_text, tags: tags, limit: limit, min_score: min_score)
+
+          local_results = @local_shard ? @local_shard.search(query) : []
+
+          remote_peers = discover_rag_peers
+          remote_groups = fan_out(remote_peers, query)
+
+          Ranker.new.merge(local_results, *remote_groups, limit: query.limit)
+        end
+
+        private
+
+        def coerce_query(query_or_text, tags:, limit:, min_score:)
+          return query_or_text if query_or_text.is_a?(RetrievalQuery)
+
+          RetrievalQuery.new(text: query_or_text.to_s, tags: tags, limit: limit, min_score: min_score)
+        end
+
+        def discover_rag_peers
+          obs = Igniter::Cluster::Mesh::ObservationQuery.new(
+            @registry.observations(now: @now)
+          ).with(:rag)
+          obs = obs.trusted if @require_trust
+          obs.to_a
+        end
+
+        def fan_out(peers, query)
+          return [] if peers.empty?
+
+          threads = peers.map do |observation|
+            Thread.new do
+              @adapter.call(observation.url, query, observation: observation)
+            rescue StandardError
+              []
+            end
+          end
+
+          threads.map { |t| t.value rescue [] }
+        end
+      end
+    end
+  end
+end

data/packages/igniter-cluster/lib/igniter/cluster/rag/knowledge_shard.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    module RAG
+      # Thread-safe, in-memory knowledge shard.
+      #
+      # A shard is a named collection of content-addressed Chunks.
+      # Adding the same content twice is idempotent (same id → same slot).
+      #
+      # Keyword search algorithm:
+      #   1. Tokenize query into words (≥ 2 chars, alphanumeric).
+      #   2. Count how many query words appear anywhere in chunk.content.
+      #   3. text_score = hits / total_query_words.
+      #   4. tag_bonus  = 0.1 × (tags in query that appear on chunk).
+      #   5. raw_score  = text_score + tag_bonus   (capped at 1.0).
+      #
+      # Entry points:
+      #   shard = KnowledgeShard.new(name: "node-a")
+      #   chunk = shard.add("Ruby closures bind their env at creation time", tags: [:ruby])
+      #   results = shard.search("how do closures work in Ruby", limit: 5)
+      #   Igniter::Cluster::Mesh.shard.search("...")   # via Mesh entry point
+      class KnowledgeShard
+        attr_reader :name
+
+        def initialize(name: "local")
+          @name   = name.to_s.freeze
+          @chunks = {}
+          @mutex  = Mutex.new
+        end
+
+        # Add content to the shard and return the resulting Chunk.
+        # Adding identical content is idempotent.
+        #
+        # @param content  [String]
+        # @param tags     [Array<Symbol, String>]
+        # @param metadata [Hash]
+        # @return [Chunk]
+        def add(content, tags: [], metadata: {})
+          chunk = Chunk.build(content.to_s, tags: tags, metadata: metadata)
+          @mutex.synchronize { @chunks[chunk.id] = chunk }
+          chunk
+        end
+
+        # Retrieve a chunk by its content-addressed id.
+        #
+        # @return [Chunk, nil]
+        def get(id)
+          @mutex.synchronize { @chunks[id.to_s] }
+        end
+
+        # Remove a chunk by id.
+        #
+        # @return [Chunk, nil] the removed chunk, or nil if not found
+        def remove(id)
+          @mutex.synchronize { @chunks.delete(id.to_s) }
+        end
+
+        # All chunks in insertion order (thread-safe snapshot).
+        #
+        # @return [Array<Chunk>]
+        def all
+          @mutex.synchronize { @chunks.values.dup }
+        end
+
+        def size
+          @mutex.synchronize { @chunks.size }
+        end
+
+        def empty?
+          size.zero?
+        end
+
+        def clear
+          @mutex.synchronize { @chunks.clear }
+          self
+        end
+
+        # Keyword search over all chunks in this shard.
+        #
+        # @param query_or_text [RetrievalQuery, String]
+        # @param tags          [Array<Symbol>]  (used only when query_or_text is a String)
+        # @param limit         [Integer]
+        # @param min_score     [Float]
+        # @return [Array<RetrievalResult>]
+        def search(query_or_text, tags: [], limit: 10, min_score: 0.0)
+          query = coerce_query(query_or_text, tags: tags, limit: limit, min_score: min_score)
+          return [] if query.text.strip.empty? && query.tags.empty?
+
+          chunks = @mutex.synchronize { @chunks.values.dup }
+          chunks = filter_by_tags(chunks, query.tags) if query.tags.any?
+
+          scored = chunks
+            .map    { |c| [c, compute_score(c, query)] }
+            .select { |_, s| s >= query.min_score }
+            .sort_by { |_, s| -s }
+            .first(query.limit)
+
+          scored.map { |chunk, s| RetrievalResult.new(chunk: chunk, score: s, source: @name) }
+        end
+
+        private
+
+        def coerce_query(query_or_text, tags:, limit:, min_score:)
+          return query_or_text if query_or_text.is_a?(RetrievalQuery)
+
+          RetrievalQuery.new(
+            text:      query_or_text.to_s,
+            tags:      tags,
+            limit:     limit,
+            min_score: min_score
+          )
+        end
+
+        def filter_by_tags(chunks, tags)
+          chunks.select { |c| tags.all? { |t| c.tag?(t) } }
+        end
+
+        def compute_score(chunk, query)
+          return 0.0 if query.text.strip.empty?
+
+          words = tokenize(query.text)
+          return 0.0 if words.empty?
+
+          content_lower = chunk.content.downcase
+          hits = words.count { |w| content_lower.include?(w) }
+          text_score = hits.to_f / words.size
+
+          tag_bonus = query.tags.count { |t| chunk.tag?(t) } * 0.1
+
+          [text_score + tag_bonus, 1.0].min.round(6)
+        end
+
+        def tokenize(text)
+          text.downcase.scan(/[a-z0-9]+/).uniq.select { |w| w.size >= 2 }
+        end
+      end
+    end
+  end
+end

data/packages/igniter-cluster/lib/igniter/cluster/rag/net_http_adapter.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Igniter
+  module Cluster
+    module RAG
+      # Production HTTP adapter: POSTs a RetrievalQuery to a remote node's
+      # /rag/search endpoint and deserialises the response into RetrievalResult
+      # objects, attaching the caller's NodeObservation for composite scoring.
+      #
+      # Wire format (request body, JSON):
+      #   { "text": "...", "tags": [...], "limit": N, "min_score": 0.0 }
+      #
+      # Wire format (response body, JSON):
+      #   { "results": [ { "id", "content", "score", "source", "tags", ... }, ... ] }
+      #
+      # Any non-200 or network error returns [] — graceful degradation.
+      class NetHttpAdapter
+        DEFAULT_TIMEOUT = 5
+
+        def initialize(timeout: DEFAULT_TIMEOUT)
+          @timeout = timeout
+        end
+
+        # @param base_url    [String]             peer URL (e.g. "http://node-a:4567")
+        # @param query       [RetrievalQuery]
+        # @param observation [NodeObservation, nil]  attached to each result for composite scoring
+        # @return [Array<RetrievalResult>]
+        def call(base_url, query, observation: nil)
+          uri     = URI.parse("#{base_url.to_s.chomp("/")}/rag/search")
+          http    = build_http(uri)
+          request = build_request(uri, query)
+          resp    = http.request(request)
+
+          return [] unless resp.code == "200"
+
+          data = JSON.parse(resp.body)
+          deserialize(data["results"], observation: observation)
+        rescue StandardError
+          []
+        end
+
+        private
+
+        def build_http(uri)
+          http              = Net::HTTP.new(uri.host, uri.port)
+          http.open_timeout = @timeout
+          http.read_timeout = @timeout
+          http.use_ssl      = uri.scheme == "https"
+          http
+        end
+
+        def build_request(uri, query)
+          req = Net::HTTP::Post.new(uri.path.empty? ? "/rag/search" : uri.path,
+                                    "Content-Type" => "application/json",
+                                    "Accept"       => "application/json")
+          req.body = JSON.generate(query.to_h)
+          req
+        end
+
+        def deserialize(raw_results, observation:)
+          Array(raw_results).filter_map do |r|
+            content  = r["content"].to_s
+            next if content.empty?
+
+            tags     = Array(r["tags"]).map(&:to_sym)
+            metadata = {}
+            Array(r["metadata"]).each { |k, v| metadata[k.to_sym] = v } if r["metadata"].is_a?(Hash)
+
+            chunk = Chunk.build(content, tags: tags, metadata: metadata)
+            RetrievalResult.new(
+              chunk:       chunk,
+              score:       r["score"].to_f,
+              source:      r["source"].to_s,
+              observation: observation
+            )
+          end
+        end
+      end
+    end
+  end
+end