igniter 0.5.0 → 0.5.1

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

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    module Mesh
+      # Bridges signed manifests into peer metadata so discovery and gossip can
+      # relay identity/trust without introducing a dedicated replication layer yet.
+      module PeerIdentityEnvelope
+        module_function
+
+        def build(source:, trust_store:, relayed_by: nil)
+          normalized = PeerMetadata.normalize(source || {})
+          manifest = extract_manifest(normalized)
+          attestation = extract_attestation(normalized, manifest)
+          governance_checkpoint = extract_governance_checkpoint(normalized)
+
+          if manifest
+            assessment = Igniter::Cluster::Trust::Verifier.assess(manifest, trust_store: trust_store)
+            base_metadata = base_metadata_for(normalized, manifest)
+            metadata = relayed_by ? PeerMetadata.relay(base_metadata, relayed_by: relayed_by) : base_metadata
+            metadata = attach_identity(metadata, manifest, assessment)
+            metadata = attach_attestation(metadata, attestation, trust_store) if attestation
+            metadata = attach_governance(metadata, governance_checkpoint, trust_store) if governance_checkpoint
+
+            return {
+              name: manifest.peer_name,
+              url: manifest.url,
+              capabilities: manifest.capabilities,
+              tags: manifest.tags,
+              metadata: metadata
+            }
+          end
+
+          metadata = Hash(normalized[:metadata] || {})
+          metadata = PeerMetadata.relay(metadata, relayed_by: relayed_by) if relayed_by
+          metadata = attach_attestation(metadata, attestation, trust_store) if attestation
+          metadata = attach_governance(metadata, governance_checkpoint, trust_store) if governance_checkpoint
+
+          {
+            name: attestation&.peer_name || normalized[:name],
+            url: attestation&.url || normalized[:url],
+            capabilities: attestation ? attestation.capabilities : Array(normalized[:capabilities]).map(&:to_sym),
+            tags: attestation ? attestation.tags : Array(normalized[:tags]).map(&:to_sym),
+            metadata: metadata
+          }
+        end
+
+        def attach_identity(metadata, manifest, assessment)
+          base = PeerMetadata.normalize(metadata)
+          base.merge(
+            mesh_identity: {
+              node_id: manifest.node_id,
+              peer_name: manifest.peer_name,
+              algorithm: manifest.algorithm,
+              fingerprint: manifest.fingerprint,
+              public_key: manifest.public_key,
+              signed_at: manifest.signed_at,
+              contracts: manifest.contracts,
+              manifest: manifest.to_h
+            },
+            mesh_trust: assessment.to_h
+          )
+        end
+
+        def attach_attestation(metadata, attestation, trust_store)
+          assessment = Igniter::Cluster::Trust::Verifier.assess_attestation(attestation, trust_store: trust_store)
+          base = PeerMetadata.normalize(metadata)
+          base.merge(
+            mesh_capabilities: {
+              node_id: attestation.node_id,
+              peer_name: attestation.peer_name,
+              fingerprint: attestation.fingerprint,
+              observed_at: attestation.observed_at,
+              capabilities: attestation.capabilities,
+              tags: attestation.tags,
+              attestation: attestation.to_h,
+              trust: assessment.to_h
+            }
+          )
+        end
+
+        def attach_governance(metadata, checkpoint, trust_store)
+          assessment = Igniter::Cluster::Trust::Verifier.assess_governance_checkpoint(checkpoint, trust_store: trust_store)
+          blocked_events = governance_event_count(checkpoint.crest, "blocked")
+          applied_events = governance_event_count(checkpoint.crest, "applied")
+          base = PeerMetadata.normalize(metadata)
+          base.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,
+              total: checkpoint.crest[:total],
+              latest_type: checkpoint.crest[:latest_type],
+              by_type: checkpoint.crest[:by_type],
+              blocked_events: blocked_events,
+              applied_events: applied_events,
+              checkpoint: checkpoint.to_h,
+              trust: assessment.to_h
+            }
+          )
+        end
+
+        def extract_manifest(source)
+          manifest_hash = if source[:manifest].is_a?(Hash)
+                            source[:manifest]
+                          elsif source[:node_id] || source[:public_key] || source[:signature]
+                            source
+                          else
+                            source.dig(:metadata, :mesh_identity, :manifest)
+                          end
+
+          return nil unless manifest_hash.is_a?(Hash)
+
+          Igniter::Cluster::Identity::Manifest.from_h(manifest_hash)
+        end
+
+        def extract_attestation(source, manifest = nil)
+          attestation_hash = if source[:capability_attestation].is_a?(Hash)
+                               source[:capability_attestation]
+                             elsif source.dig(:metadata, :mesh_capabilities, :attestation).is_a?(Hash)
+                               source.dig(:metadata, :mesh_capabilities, :attestation)
+                             else
+                               manifest&.capability_attestation&.to_h
+                             end
+
+          return nil unless attestation_hash.is_a?(Hash)
+
+          Igniter::Cluster::Identity::CapabilityAttestation.from_h(attestation_hash)
+        end
+
+        def extract_governance_checkpoint(source)
+          checkpoint_hash = if source[:governance_checkpoint].is_a?(Hash)
+                              source[:governance_checkpoint]
+                            elsif source.dig(:metadata, :mesh_governance, :checkpoint).is_a?(Hash)
+                              source.dig(:metadata, :mesh_governance, :checkpoint)
+                            end
+
+          return nil unless checkpoint_hash.is_a?(Hash)
+
+          Igniter::Cluster::Governance::Checkpoint.from_h(checkpoint_hash)
+        end
+
+        def base_metadata_for(source, manifest)
+          metadata = Hash(source[:metadata] || {})
+          metadata.empty? ? manifest.metadata : metadata
+        end
+
+        def governance_event_count(crest, fragment)
+          Hash(crest[:by_type] || {}).sum do |type, count|
+            type.to_s.include?(fragment) ? count.to_i : 0
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Igniter
+  module Cluster
+    module Mesh
+      # Normalizes and enriches peer metadata with mesh observation coordinates.
+      #
+      # The mesh envelope captures how fresh and how trustworthy a capability
+      # snapshot is as it propagates through the network:
+      #   - observed_at: original authoritative observation timestamp
+      #   - confidence:  confidence in the snapshot after relay decay
+      #   - hops:        relay distance from the authoritative source
+      #
+      # Freshness is derived dynamically from observed_at so it naturally ages.
+      module PeerMetadata
+        CONFIDENCE_DECAY = 0.9
+
+        module_function
+
+        def normalize(value)
+          case value
+          when Hash
+            value.each_with_object({}) do |(key, nested), memo|
+              memo[key.to_sym] = normalize(nested)
+            end
+          when Array
+            value.map { |item| normalize(item) }
+          else
+            value
+          end
+        end
+
+        def authoritative(metadata, origin: nil, observed_at: Time.now.utc)
+          base = normalize(metadata)
+          mesh = normalize(base[:mesh] || {})
+
+          base.merge(
+            mesh: mesh.merge(
+              observed_at: iso8601(observed_at),
+              confidence: 1.0,
+              hops: 0,
+              origin: origin&.to_s || mesh[:origin]
+            ).compact
+          )
+        end
+
+        def relay(metadata, relayed_by:, observed_at: Time.now.utc, confidence_decay: CONFIDENCE_DECAY)
+          base = normalize(metadata)
+          mesh = normalize(base[:mesh] || {})
+
+          base.merge(
+            mesh: mesh.merge(
+              observed_at: mesh[:observed_at] || iso8601(observed_at),
+              confidence: decayed_confidence(mesh[:confidence], confidence_decay),
+              hops: mesh.fetch(:hops, 0).to_i + 1,
+              relayed_by: relayed_by.to_s,
+              relayed_at: iso8601(observed_at)
+            )
+          )
+        end
+
+        def runtime(metadata, now: Time.now.utc)
+          base = normalize(metadata)
+          mesh = normalize(base[:mesh] || {})
+          attestation = normalize(base[:mesh_capabilities] || {})
+          governance = normalize(base[:mesh_governance] || {})
+
+          base = if mesh.empty?
+                   base
+                 else
+                   observed_at = parse_time(mesh[:observed_at])
+                   freshness_seconds = observed_at ? [(now - observed_at).to_i, 0].max : nil
+
+                   base.merge(
+                     mesh: mesh.merge(freshness_seconds: freshness_seconds).compact
+                   )
+                 end
+
+          base = if attestation.empty?
+                   base
+                 else
+                   observed_at = parse_time(attestation[:observed_at])
+                   freshness_seconds = observed_at ? [(now - observed_at).to_i, 0].max : nil
+
+                   base.merge(
+                     mesh_capabilities: attestation.merge(freshness_seconds: freshness_seconds).compact
+                   )
+                 end
+
+          return base if governance.empty?
+
+          checkpointed_at = parse_time(governance[:checkpointed_at])
+          freshness_seconds = checkpointed_at ? [(now - checkpointed_at).to_i, 0].max : nil
+
+          base.merge(
+            mesh_governance: governance.merge(freshness_seconds: freshness_seconds).compact
+          )
+        end
+
+        def decayed_confidence(value, decay)
+          upstream = value.nil? ? 1.0 : value.to_f
+          (upstream * decay).round(4)
+        end
+
+        def iso8601(value)
+          value.utc.iso8601
+        end
+
+        def parse_time(value)
+          return value if value.is_a?(Time)
+          return nil if value.nil?
+
+          Time.iso8601(value.to_s)
+        rescue ArgumentError
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    module Mesh
+    # Thread-safe registry for dynamically discovered peers.
+    #
+    # Stores peers indexed by name so that registering the same peer twice
+    # (e.g. from two different seeds) is idempotent and the latest wins.
+    class PeerRegistry
+      def initialize
+        @peers = {}
+        @mutex = Mutex.new
+      end
+
+      # Register (or update) a peer. Thread-safe.
+      def register(peer)
+        @mutex.synchronize { @peers[peer.name] = peer }
+      end
+
+      # Remove a peer by name. No-op if not registered.
+      def unregister(name)
+        @mutex.synchronize { @peers.delete(name.to_s) }
+      end
+
+      # All currently registered peers (snapshot).
+      def all
+        @mutex.synchronize { @peers.values.dup }
+      end
+
+      # Peers that advertise a given capability.
+      def peers_with_capability(capability)
+        all.select { |p| p.capable?(capability) }
+      end
+
+      # Peers matching a capability query.
+      def peers_matching_query(query)
+        all.select { |p| p.matches_query?(query) }
+      end
+
+      # Find a peer by name. Returns nil if not found.
+      def peer_named(name)
+        @mutex.synchronize { @peers[name.to_s] }
+      end
+
+      # Remove all registered peers. Useful in tests.
+      def clear
+        @mutex.synchronize { @peers.clear }
+      end
+
+      # Number of registered peers.
+      def size
+        @mutex.synchronize { @peers.size }
+      end
+
+      # NodeObservation for a peer by name at the given point in time.
+      # Returns nil if the peer is not registered.
+      def observation_for(name, now: Time.now.utc, workload_tracker: nil)
+        peer_named(name)&.to_observation(now: now, workload_tracker: workload_tracker)
+      end
+
+      # All peers as NodeObservation snapshots at the given point in time.
+      # Pass workload_tracker: to enrich each observation with live signal data.
+      def observations(now: Time.now.utc, workload_tracker: nil)
+        all.map { |p| p.to_observation(now: now, workload_tracker: workload_tracker) }
+      end
+
+      # Observations matching a capability query.
+      def observations_matching_query(query, now: Time.now.utc, workload_tracker: nil)
+        normalized = Igniter::Cluster::Replication::CapabilityQuery.normalize(query)
+        observations(now: now, workload_tracker: workload_tracker).select { |obs| normalized.matches_profile?(obs) }
+      end
+
+      # Returns an ObservationQuery builder over all current observations.
+      def query(now: Time.now.utc, workload_tracker: nil)
+        ObservationQuery.new(observations(now: now, workload_tracker: workload_tracker))
+      end
+    end
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    module Mesh
+      # Result of a PlacementPlanner#place call.
+      #
+      # Carries the chosen node, its composite score (0..1), per-dimension
+      # score breakdown, rejected candidates, and whether degraded-mode
+      # fallback was triggered.
+      class PlacementDecision
+        attr_reader :node, :score, :dimensions, :rejected, :policy
+
+        # @param node       [NodeObservation, nil]  chosen node; nil = no placement found
+        # @param score      [Float, nil]            composite score (0..1)
+        # @param dimensions [Hash]                  per-dimension score breakdown
+        # @param rejected   [Array<Hash>]           losing candidates with name, score
+        # @param degraded   [Boolean]               true when relaxed policy was used
+        # @param policy     [PlacementPolicy]       the policy that was applied
+        def initialize(node:, score:, dimensions:, rejected:, degraded:, policy:)
+          @node       = node
+          @score      = score
+          @dimensions = Hash(dimensions).freeze
+          @rejected   = Array(rejected).freeze
+          @degraded   = degraded
+          @policy     = policy
+          freeze
+        end
+
+        def placed?
+          !@node.nil?
+        end
+
+        def failed?
+          @node.nil?
+        end
+
+        def degraded?
+          @degraded
+        end
+
+        def url
+          @node&.url
+        end
+
+        def name
+          @node&.name
+        end
+
+        def to_h
+          {
+            placed:     placed?,
+            degraded:   @degraded,
+            node:       @node ? { name: @node.name, url: @node.url } : nil,
+            score:      @score,
+            dimensions: @dimensions,
+            rejected:   @rejected,
+            policy:     @policy.to_h
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    module Mesh
+      # Multi-dimensional placement engine that selects the best NodeObservation
+      # from a candidate pool for a given capability requirement.
+      #
+      # Placement proceeds in three stages:
+      #   1. Filter  — apply PlacementPolicy hard constraints via ObservationQuery
+      #   2. Score   — compute a weighted composite score across eight dimensions
+      #   3. Select  — pick the highest-scoring candidate; ties broken by name (stable)
+      #
+      # When degraded_fallback is enabled in the policy and the primary candidate
+      # set is empty, the planner retries with a fully relaxed policy and marks the
+      # result as degraded.
+      #
+      # Scoring weights:
+      #   health:      0.25  (healthy=1.0, degraded=0.3, unknown=0.0)
+      #   trust:       0.20  (trusted=1.0, else=0.0)
+      #   load_cpu:    0.18  (1 - load_cpu; nil → 0.5 neutral)
+      #   load_memory: 0.12  (1 - load_memory; nil → 0.5 neutral)
+      #   workload:    0.15  (live signals: healthy=1.0, overloaded=0.3, degraded=0.2, both=0.0, unknown=0.8)
+      #   locality:    0.07  (zone match=1.0, region match=0.5, none=0.0)
+      #   confidence:  0.02  (0..1, defaults to 1.0 when unknown)
+      #   freshness:   0.01  (observed within 120s → 1.0, stale → 0.0)
+      #
+      # Entry points:
+      #   PlacementPlanner.new(observations, policy: policy).place(:database)
+      #   Igniter::Cluster::Mesh.place(:database, policy: policy)
+      class PlacementPlanner
+        WEIGHTS = {
+          health:      0.25,
+          trust:       0.20,
+          load_cpu:    0.18,
+          load_memory: 0.12,
+          workload:    0.15,
+          locality:    0.07,
+          confidence:  0.02,
+          freshness:   0.01
+        }.freeze
+
+        # @param observations [Array<NodeObservation>]
+        # @param policy       [PlacementPolicy]
+        def initialize(observations, policy: PlacementPolicy.new)
+          @observations = observations
+          @policy       = policy
+        end
+
+        # Select the best node for the given capabilities.
+        #
+        # @param capabilities [Symbol, Array<Symbol>, nil]  required capabilities; nil = any
+        # @return [PlacementDecision]
+        def place(capabilities = nil)
+          base_query = ObservationQuery.new(@observations)
+          base_query = base_query.with(*Array(capabilities)) unless capabilities.nil?
+
+          candidates, degraded = filtered_candidates(base_query)
+
+          if candidates.empty?
+            return PlacementDecision.new(
+              node: nil, score: nil, dimensions: {}, rejected: [],
+              degraded: degraded, policy: @policy
+            )
+          end
+
+          scored = score_all(candidates).sort_by { |obs, s| [-s[:total], obs.name] }
+          best_node, best_score = scored.first
+
+          rejected = scored.drop(1).map do |obs, s|
+            { name: obs.name, url: obs.url, score: s[:total], dimensions: s.except(:total) }
+          end
+
+          PlacementDecision.new(
+            node:       best_node,
+            score:      best_score[:total],
+            dimensions: best_score.except(:total),
+            rejected:   rejected,
+            degraded:   degraded,
+            policy:     @policy
+          )
+        end
+
+        private
+
+        def filtered_candidates(base_query)
+          candidates = @policy.constrain(base_query).to_a
+          return [candidates, false] unless candidates.empty? && @policy.degraded_fallback
+
+          [@policy.relaxed.constrain(base_query).to_a, true]
+        end
+
+        def score_all(candidates)
+          candidates.map { |obs| [obs, score(obs)] }
+        end
+
+        def score(obs)
+          dims = {
+            health:      health_score(obs),
+            trust:       trust_score(obs),
+            load_cpu:    load_cpu_score(obs),
+            load_memory: load_memory_score(obs),
+            workload:    workload_score(obs),
+            locality:    locality_score(obs),
+            confidence:  obs.confidence || 1.0,
+            freshness:   obs.fresh?(max_seconds: 120) ? 1.0 : 0.0
+          }
+          total = WEIGHTS.sum { |dim, w| w * dims.fetch(dim, 0.0) }
+          dims.merge(total: total.round(6))
+        end
+
+        def health_score(obs)
+          case obs.health
+          when :healthy  then 1.0
+          when :degraded then 0.3
+          else 0.0
+          end
+        end
+
+        def trust_score(obs)
+          obs.trusted? ? 1.0 : 0.0
+        end
+
+        def load_cpu_score(obs)
+          obs.load_cpu ? [1.0 - obs.load_cpu, 0.0].max : 0.5
+        end
+
+        def load_memory_score(obs)
+          obs.load_memory ? [1.0 - obs.load_memory, 0.0].max : 0.5
+        end
+
+        def workload_score(obs)
+          return 0.8 unless obs.workload_observed?
+
+          degraded   = obs.workload_degraded?
+          overloaded = obs.workload_overloaded?
+
+          if degraded && overloaded then 0.0
+          elsif degraded            then 0.2
+          elsif overloaded          then 0.3
+          else                           1.0
+          end
+        end
+
+        def locality_score(obs)
+          return 1.0 if @policy.zone && obs.zone == @policy.zone
+          return 0.5 if @policy.region && obs.region == @policy.region
+
+          0.0
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    module Mesh
+      # Declarative placement constraints applied before multi-dimensional scoring.
+      #
+      # A PlacementPolicy acts as a hard filter gate — only candidates satisfying
+      # all constraints reach the scorer. Soft preferences (zone/region affinity)
+      # influence the locality score dimension without hard-excluding nodes unless
+      # locality_preference is set to :zone or :region.
+      #
+      # degraded_fallback: when true, PlacementPlanner re-runs with a fully
+      # relaxed policy when the primary candidate set is empty.
+      class PlacementPolicy
+        LOCALITY_PREFERENCES = %i[zone region any].freeze
+
+        attr_reader :zone, :region,
+                    :max_load_cpu, :max_load_memory, :max_concurrency, :max_queue_depth,
+                    :require_trust, :require_health,
+                    :locality_preference, :degraded_fallback
+
+        def initialize(
+          zone: nil,
+          region: nil,
+          max_load_cpu: nil,
+          max_load_memory: nil,
+          max_concurrency: nil,
+          max_queue_depth: nil,
+          require_trust: false,
+          require_health: true,
+          locality_preference: :any,
+          degraded_fallback: false
+        )
+          lp = locality_preference.to_sym
+          unless LOCALITY_PREFERENCES.include?(lp)
+            raise ArgumentError, "locality_preference must be one of #{LOCALITY_PREFERENCES.inspect}"
+          end
+
+          @zone               = zone
+          @region             = region
+          @max_load_cpu       = max_load_cpu
+          @max_load_memory    = max_load_memory
+          @max_concurrency    = max_concurrency
+          @max_queue_depth    = max_queue_depth
+          @require_trust      = require_trust
+          @require_health     = require_health
+          @locality_preference = lp
+          @degraded_fallback  = degraded_fallback
+          freeze
+        end
+
+        # Apply hard constraints to an ObservationQuery.
+        # Returns a new ObservationQuery with all applicable filters applied.
+        def constrain(query)
+          q = query
+          q = q.healthy                       if @require_health
+          q = q.trusted                       if @require_trust
+          q = q.max_load_cpu(@max_load_cpu)       if @max_load_cpu
+          q = q.max_load_memory(@max_load_memory) if @max_load_memory
+          q = q.max_concurrency(@max_concurrency) if @max_concurrency
+          q = q.max_queue_depth(@max_queue_depth) if @max_queue_depth
+          case @locality_preference
+          when :zone   then q = q.in_zone(@zone)     if @zone
+          when :region then q = q.in_region(@region) if @region
+          end
+          q
+        end
+
+        # Return a maximally relaxed copy for degraded-mode fallback.
+        def relaxed
+          self.class.new(
+            zone:                nil,
+            region:              nil,
+            max_load_cpu:        nil,
+            max_load_memory:     nil,
+            max_concurrency:     nil,
+            max_queue_depth:     nil,
+            require_trust:       false,
+            require_health:      false,
+            locality_preference: :any,
+            degraded_fallback:   false
+          )
+        end
+
+        def to_h
+          {
+            zone:                @zone,
+            region:              @region,
+            max_load_cpu:        @max_load_cpu,
+            max_load_memory:     @max_load_memory,
+            max_concurrency:     @max_concurrency,
+            max_queue_depth:     @max_queue_depth,
+            require_trust:       @require_trust,
+            require_health:      @require_health,
+            locality_preference: @locality_preference,
+            degraded_fallback:   @degraded_fallback
+          }
+        end
+      end
+    end
+  end
+end