igniter 0.5.0 → 0.5.1

data/packages/igniter-cluster/lib/igniter/cluster/identity/node_identity.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "openssl"
+require "time"
+
+module Igniter
+  module Cluster
+    module Identity
+      class NodeIdentity
+        DEFAULT_ALGORITHM = "rsa-sha256"
+
+        attr_reader :node_id, :algorithm, :created_at
+
+        def self.generate(node_id:, created_at: Time.now.utc.iso8601)
+          key = OpenSSL::PKey::RSA.generate(2048)
+          new(
+            node_id: node_id,
+            public_key_pem: key.public_key.to_pem,
+            private_key_pem: key.to_pem,
+            algorithm: DEFAULT_ALGORITHM,
+            created_at: created_at
+          )
+        end
+
+        def initialize(node_id:, public_key_pem:, private_key_pem:, algorithm: DEFAULT_ALGORITHM, created_at: nil)
+          @node_id = node_id.to_s.freeze
+          @public_key_pem = public_key_pem.to_s.freeze
+          @private_key_pem = private_key_pem.to_s.freeze
+          @algorithm = algorithm.to_s.freeze
+          @created_at = (created_at || Time.now.utc.iso8601).to_s.freeze
+          freeze
+        end
+
+        def sign(payload)
+          encoded = canonical_json(payload)
+          Base64.strict_encode64(private_key.sign(OpenSSL::Digest::SHA256.new, encoded))
+        end
+
+        def verify(payload, signature:)
+          public_key.verify(
+            OpenSSL::Digest::SHA256.new,
+            Base64.strict_decode64(signature.to_s),
+            canonical_json(payload)
+          )
+        rescue OpenSSL::PKey::PKeyError, ArgumentError
+          false
+        end
+
+        def public_key_pem
+          @public_key_pem
+        end
+
+        def private_key_pem
+          @private_key_pem
+        end
+
+        def fingerprint
+          OpenSSL::Digest::SHA256.hexdigest(public_key.to_der)[0, 24]
+        end
+
+        def to_h(include_private: false)
+          payload = {
+            node_id: node_id,
+            algorithm: algorithm,
+            public_key: public_key_pem,
+            fingerprint: fingerprint,
+            created_at: created_at
+          }
+          payload[:private_key] = private_key_pem if include_private
+          payload
+        end
+
+        private
+
+        def public_key
+          OpenSSL::PKey.read(@public_key_pem)
+        end
+
+        def private_key
+          OpenSSL::PKey.read(@private_key_pem)
+        end
+
+        def canonical_json(value)
+          JSON.generate(deep_sort(value))
+        end
+
+        def deep_sort(value)
+          case value
+          when Hash
+            value.each_with_object({}) do |(key, nested), memo|
+              memo[key.to_s] = deep_sort(nested)
+            end.sort.to_h
+          when Array
+            value.map { |item| deep_sort(item) }
+          when Symbol
+            value.to_s
+          else
+            value
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "identity/node_identity"
+require_relative "identity/capability_attestation"
+require_relative "identity/manifest"

data/{lib/igniter → packages/igniter-cluster/lib/igniter/cluster}/mesh/announcer.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 module Igniter
-  module Mesh
+  module Cluster
+    module Mesh
     # Announces this node's identity to seed nodes at startup and withdraws
     # the registration on graceful shutdown.
     #
@@ -36,10 +37,41 @@ module Igniter
       end
 
       def announce_to(seed_url)
-        Igniter::Server::Client.new(seed_url, timeout: 5).register_peer(
-          name: @config.peer_name,
+        metadata = PeerMetadata.authoritative(@config.local_metadata, origin: @config.peer_name)
+        checkpoint = @config.governance_checkpoint(limit: 10)
+        metadata = metadata.merge(
+          mesh_governance: {
+            node_id: checkpoint.node_id,
+            peer_name: checkpoint.peer_name,
+            fingerprint: checkpoint.fingerprint,
+            checkpointed_at: checkpoint.checkpointed_at,
+            crest_digest: checkpoint.crest_digest,
+            checkpoint: checkpoint.to_h,
+            trust: Igniter::Cluster::Trust::Verifier.assess_governance_checkpoint(
+              checkpoint,
+              trust_store: @config.trust_store
+            ).to_h
+          }
+        )
+
+        state = @config.local_state
+        metadata = metadata.merge(mesh_state: state) if state && !state.empty?
+
+        locality = @config.local_locality
+        metadata = metadata.merge(mesh_locality: locality) if locality && !locality.empty?
+
+        manifest = Igniter::Cluster::Identity::Manifest.build(
+          identity: @config.ensure_identity!,
+          peer_name: @config.peer_name,
           url: @config.local_url,
-          capabilities: @config.local_capabilities
+          capabilities: @config.local_capabilities,
+          tags: @config.local_tags,
+          metadata: metadata,
+          contracts: []
+        )
+
+        Igniter::Server::Client.new(seed_url, timeout: 5).register_peer(
+          manifest: manifest
         )
       rescue Igniter::Server::Client::ConnectionError
         nil
@@ -51,5 +83,6 @@ module Igniter
         nil
       end
     end
+    end
   end
 end

data/packages/igniter-cluster/lib/igniter/cluster/mesh/checkpoint_gossip.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Igniter
+  module Cluster
+    module Mesh
+      # Shared helper: accepts a governance checkpoint embedded in a peer's
+      # metadata (received during Poller seed-fetch or GossipRound peer-exchange)
+      # and persists it locally when it is newer than the current local checkpoint.
+      #
+      # Called after every peer registration in both Poller and GossipRound.
+      # No-op when config.checkpoint_store is nil.
+      #
+      # Security: the remote checkpoint's RSA/ECDSA signature is verified before
+      # the checkpoint is accepted. Tampered or unsigned payloads are silently
+      # dropped.
+      #
+      # Governance trail: records :checkpoint_replicated when a newer checkpoint
+      # is saved, allowing operators to audit the replication history.
+      module CheckpointGossip
+        module_function
+
+        # @param peer_metadata [Hash]  symbol-keyed metadata from PeerIdentityEnvelope
+        # @param config        [Mesh::Config]
+        # @param source        [Symbol]  :poller or :gossip (for trail attribution)
+        def sync(peer_metadata, config:, source: :discovery)
+          store = config.checkpoint_store
+          return unless store
+
+          checkpoint_hash = peer_metadata.dig(:mesh_governance, :checkpoint)
+          return unless checkpoint_hash.is_a?(Hash)
+
+          remote_cp = Igniter::Cluster::Governance::Checkpoint.from_h(checkpoint_hash)
+          return unless remote_cp&.verify_signature
+
+          local_cp = store.load
+          if local_cp
+            remote_time = Time.parse(remote_cp.checkpointed_at)
+            local_time  = Time.parse(local_cp.checkpointed_at)
+            return if local_time >= remote_time
+          end
+
+          store.save(remote_cp)
+          config.governance_trail&.record(
+            :checkpoint_replicated,
+            source:  source,
+            payload: {
+              from_peer:       peer_metadata.dig(:mesh_governance, :peer_name),
+              crest_digest:    remote_cp.crest_digest,
+              checkpointed_at: remote_cp.checkpointed_at
+            }
+          )
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

data/packages/igniter-cluster/lib/igniter/cluster/mesh/config.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    module Mesh
+    # Configuration for the local mesh node: registered peers and local identity.
+    class Config
+      attr_accessor :peer_name, :local_capabilities, :local_tags, :local_metadata,
+                    :local_state, :local_locality,
+                    :seeds, :discovery_interval, :auto_announce, :local_url, :gossip_fanout,
+                    :identity, :trust_store, :governance_trail, :auto_self_heal,
+                    :self_heal_interval, :self_heal_limit, :self_heal_report_provider,
+                    :ownership_registry, :checkpoint_store,
+                    :knowledge_shard,
+                    :admission_policy, :admission_queue,
+                    :workload_tracker
+      attr_reader   :peers, :peer_registry
+
+      def initialize
+        @peer_name          = nil
+        @local_capabilities = []
+        @local_tags         = []
+        @local_metadata     = {}
+        @local_state        = {}
+        @local_locality     = {}
+        @peers              = []
+        @peer_registry      = PeerRegistry.new
+        @seeds              = []
+        @discovery_interval = 30
+        @auto_announce      = true
+        @local_url          = nil
+        @gossip_fanout      = 3
+        @identity           = nil
+        @trust_store        = Igniter::Cluster::Trust::TrustStore.new
+        @governance_trail   = Igniter::Cluster::Governance::Trail.new
+        @auto_self_heal     = false
+        @self_heal_interval = 15
+        @self_heal_limit    = nil
+        @self_heal_report_provider = nil
+        @ownership_registry = nil
+        @checkpoint_store   = nil
+        @knowledge_shard    = nil
+        @admission_policy   = nil
+        @admission_queue    = nil
+        @workload_tracker   = nil
+        @last_routing_report = nil
+      end
+
+      def ensure_identity!
+        @identity ||= Igniter::Cluster::Identity::NodeIdentity.generate(node_id: @peer_name || "anonymous-node")
+      end
+
+      def governance_log(path, archive: nil, retain_events: nil, retention_policy: nil)
+        @governance_trail = Igniter::Cluster::Governance::Trail.new(
+          store: Igniter::Cluster::Governance::Stores::FileStore.new(
+            path: path,
+            max_events: retain_events,
+            archive_path: archive,
+            retention_policy: retention_policy
+          )
+        )
+        self
+      end
+
+      def reload_governance_trail!
+        return @governance_trail unless @governance_trail&.store
+
+        @governance_trail = Igniter::Cluster::Governance::Trail.new(store: @governance_trail.store)
+      end
+
+      def governance_checkpoint(limit: 10, checkpointed_at: Time.now.utc.iso8601)
+        identity = ensure_identity!
+        Igniter::Cluster::Governance::Checkpoint.build(
+          identity: identity,
+          peer_name: @peer_name || identity.node_id,
+          trail: @governance_trail,
+          limit: limit,
+          checkpointed_at: checkpointed_at
+        )
+      end
+
+      def record_routing_report!(target)
+        @last_routing_report = normalize_routing_report(target)
+      end
+
+      def current_routing_report
+        provided = @self_heal_report_provider&.call
+        report = normalize_routing_report(provided)
+        return report if report
+
+        @last_routing_report
+      rescue StandardError
+        @last_routing_report
+      end
+
+      # Register a remote peer by name.
+      #
+      #   Igniter::Cluster::Mesh.configure do |c|
+      #     c.add_peer "orders-node", url: "http://orders.internal:4567",
+      #                               capabilities: [:orders, :inventory]
+      #   end
+      def add_peer(name, url:, capabilities: [], tags: [], metadata: {})
+        @peers << Peer.new(name: name, url: url, capabilities: capabilities, tags: tags, metadata: metadata)
+        self
+      end
+
+      # All static peers that advertise a given capability.
+      def peers_with_capability(capability)
+        @peers.select { |p| p.capable?(capability) }
+      end
+
+      # All static peers matching a capability query.
+      def peers_matching_query(query)
+        @peers.select { |p| p.matches_query?(query) }
+      end
+
+      # Find a static peer by its registered name. Returns nil if not found.
+      def peer_named(name)
+        @peers.find { |p| p.name == name.to_s }
+      end
+
+      private
+
+      def normalize_routing_report(target)
+        return nil if target.nil?
+
+        report =
+          if target.respond_to?(:diagnostics)
+            target.diagnostics.to_h
+          elsif target.is_a?(Hash)
+            target
+          elsif target.respond_to?(:to_h)
+            target.to_h
+          end
+
+        return nil unless report.is_a?(Hash)
+        return nil unless report.dig(:routing, :plans).is_a?(Array)
+
+        report
+      rescue StandardError
+        nil
+      end
+    end
+    end
+  end
+end

data/{lib/igniter → packages/igniter-cluster/lib/igniter/cluster}/mesh/discovery.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 module Igniter
-  module Mesh
+  module Cluster
+    module Mesh
     # Orchestrates the full dynamic-discovery lifecycle:
     #
     #   1. Announce self to all seeds (POST /v1/mesh/peers).
@@ -16,24 +17,28 @@ module Igniter
         @config    = config
         @announcer = Announcer.new(config)
         @poller    = Poller.new(config)
+        @repair_loop = RepairLoop.new(config)
       end
 
       def start
         @announcer.announce_all
         @poller.poll_once
         @poller.start
+        @repair_loop.start if @config.auto_self_heal
         self
       end
 
       def stop
         @announcer.deannounce_all
         @poller.stop
+        @repair_loop.stop
         self
       end
 
       def running?
-        @poller.running?
+        @poller.running? || @repair_loop.running?
       end
     end
+    end
   end
 end

data/{lib/igniter → packages/igniter-cluster/lib/igniter/cluster}/mesh/errors.rb

@@ -1,16 +1,20 @@
 # frozen_string_literal: true
 
 module Igniter
-  module Mesh
+  module Cluster
+    module Mesh
     # Raised when a capability-routed remote node has no alive peers.
     # Inherits from PendingDependencyError so the resolver transitions
     # the node to :pending (same as await/distributed workflow nodes).
     class DeferredCapabilityError < Igniter::PendingDependencyError
-      attr_reader :capability
+      attr_reader :capability, :query, :explanation
 
-      def initialize(capability, deferred_result, message = nil)
-        @capability = capability
-        super(deferred_result, message || "No alive peer with capability :#{capability}")
+      def initialize(capability, deferred_result, message = nil, query: nil, explanation: nil)
+        @capability  = capability
+        @query       = query
+        @explanation = explanation
+        label       = query ? query.inspect : ":#{capability}"
+        super(deferred_result, message || "No alive peer matching capability #{label}")
       end
     end
 
@@ -27,5 +31,6 @@ module Igniter
               context: context)
       end
     end
+    end
   end
 end

data/{lib/igniter → packages/igniter-cluster/lib/igniter/cluster}/mesh/gossip.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 module Igniter
-  module Mesh
+  module Cluster
+    module Mesh
     # Executes a single peer-to-peer gossip round.
     #
     # Picks up to config.gossip_fanout random peers from the local PeerRegistry
@@ -32,16 +33,30 @@ module Igniter
       def exchange_with(peer) # rubocop:disable Metrics/AbcSize
         peers = Igniter::Server::Client.new(peer.url, timeout: 5).list_peers
         peers.each do |pd|
-          next if pd[:name].nil? || pd[:url].nil?
-          next if pd[:name] == @config.peer_name
+          attributes = PeerIdentityEnvelope.build(
+            source: pd,
+            trust_store: @config.trust_store,
+            relayed_by: peer.name
+          )
+          next if attributes[:name].nil? || attributes[:url].nil?
+          next if attributes[:name] == @config.peer_name
 
           @config.peer_registry.register(
-            Peer.new(name: pd[:name], url: pd[:url], capabilities: pd[:capabilities] || [])
+            Peer.new(
+              name: attributes[:name],
+              url: attributes[:url],
+              capabilities: attributes[:capabilities] || [],
+              tags: attributes[:tags] || [],
+              metadata: attributes[:metadata] || {}
+            )
           )
+
+          CheckpointGossip.sync(attributes[:metadata] || {}, config: @config, source: :gossip)
         end
       rescue Igniter::Server::Client::ConnectionError
         nil
       end
     end
+    end
   end
 end