igniter 0.5.1 → 0.5.2

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

@@ -1,158 +0,0 @@
-# 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

@@ -1,122 +0,0 @@
-# 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

@@ -1,81 +0,0 @@
-# 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

@@ -1,64 +0,0 @@
-# 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

@@ -1,154 +0,0 @@
-# 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

@@ -1,103 +0,0 @@
-# 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