igniter 0.5.0 → 0.5.1

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

@@ -0,0 +1,281 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    module Mesh
+      # Canonical per-node snapshot: a typed, multi-dimensional observation of
+      # a cluster peer at a point in time.
+      #
+      # Each NodeObservation is an OLAP Point — a slice through the cluster's
+      # observable field across seven dimensions:
+      #
+      #   capabilities  — what the node can do and how fresh/trusted that claim is
+      #   trust         — identity, signing key, trust status
+      #   state         — runtime health, load, concurrency, queue depth
+      #   locality      — region, zone, proximity tags
+      #   governance    — signed checkpoint, trail crest, governance trust
+      #   provenance    — who observed this, when, with what confidence, via how many hops
+      #   workload      — live failure rate, avg latency, degraded/overloaded flags
+      #
+      # Implements the duck-typed interface expected by CapabilityQuery:
+      #   capability?(cap), tag?(tag), metadata (Hash)
+      #
+      # Always build via NodeObservation.from_peer_hash so freshness is computed
+      # at observation time. Do not cache long-lived instances — freshness_seconds
+      # ages from the construction timestamp.
+      class NodeObservation
+        attr_reader :name, :url, :capabilities, :tags, :metadata
+
+        def initialize(name:, url:, capabilities:, tags:, metadata:)
+          @name         = name.to_s.freeze
+          @url          = url.to_s.freeze
+          @capabilities = Array(capabilities).map(&:to_sym).freeze
+          @tags         = Array(tags).map(&:to_sym).freeze
+          @metadata     = PeerMetadata.normalize(metadata).freeze
+          freeze
+        end
+
+        # ── CapabilityQuery interface ─────────────────────────────────────────
+
+        def capability?(capability)
+          @capabilities.include?(capability.to_sym)
+        end
+
+        def tag?(tag)
+          @tags.include?(tag.to_sym)
+        end
+
+        def matches_query?(query)
+          normalized = Igniter::Cluster::Replication::CapabilityQuery.normalize(query)
+          normalized.matches_profile?(self)
+        end
+
+        # ── Observation provenance ────────────────────────────────────────────
+
+        def node_id
+          @metadata.dig(:mesh_identity, :node_id) || @metadata.dig(:mesh, :origin)
+        end
+
+        def observed_at
+          @metadata.dig(:mesh, :observed_at)
+        end
+
+        def observed_by
+          @metadata.dig(:mesh, :origin)
+        end
+
+        def confidence
+          @metadata.dig(:mesh, :confidence) || 1.0
+        end
+
+        def hops
+          @metadata.dig(:mesh, :hops) || 0
+        end
+
+        def relayed_by
+          @metadata.dig(:mesh, :relayed_by)
+        end
+
+        def authoritative?
+          hops == 0
+        end
+
+        def fresh?(max_seconds: 60)
+          freshness = @metadata.dig(:mesh, :freshness_seconds)
+          freshness && freshness <= max_seconds
+        end
+
+        # ── Capabilities dimension ────────────────────────────────────────────
+
+        def capabilities_trust_status
+          @metadata.dig(:mesh_capabilities, :trust, :status)&.to_sym
+        end
+
+        def capabilities_freshness_seconds
+          @metadata.dig(:mesh_capabilities, :freshness_seconds)
+        end
+
+        def capabilities_observed_at
+          @metadata.dig(:mesh_capabilities, :observed_at)
+        end
+
+        # ── Trust dimension ───────────────────────────────────────────────────
+
+        def trust_status
+          @metadata.dig(:mesh_trust, :status)&.to_sym
+        end
+
+        def trusted?
+          @metadata.dig(:mesh_trust, :trusted) == true
+        end
+
+        def identity_fingerprint
+          @metadata.dig(:mesh_identity, :fingerprint)
+        end
+
+        def contracts
+          Array(@metadata.dig(:mesh_identity, :contracts))
+        end
+
+        # ── State dimension ───────────────────────────────────────────────────
+
+        def health
+          @metadata.dig(:mesh_state, :health)&.to_sym || :unknown
+        end
+
+        def load_cpu
+          @metadata.dig(:mesh_state, :load_cpu)
+        end
+
+        def load_memory
+          @metadata.dig(:mesh_state, :load_memory)
+        end
+
+        def concurrency
+          @metadata.dig(:mesh_state, :concurrency) || 0
+        end
+
+        def queue_depth
+          @metadata.dig(:mesh_state, :queue_depth) || 0
+        end
+
+        # ── Locality dimension ────────────────────────────────────────────────
+
+        def region
+          @metadata.dig(:mesh_locality, :region)
+        end
+
+        def zone
+          @metadata.dig(:mesh_locality, :zone)
+        end
+
+        def proximity_tags
+          Array(@metadata.dig(:mesh_locality, :proximity_tags)).map(&:to_sym)
+        end
+
+        # ── Workload dimension ────────────────────────────────────────────────
+
+        def workload_failure_rate
+          @metadata.dig(:mesh_workload, :failure_rate)
+        end
+
+        def workload_avg_duration_ms
+          @metadata.dig(:mesh_workload, :avg_duration_ms)
+        end
+
+        def workload_total
+          @metadata.dig(:mesh_workload, :total) || 0
+        end
+
+        def workload_degraded?
+          @metadata.dig(:mesh_workload, :degraded) == true
+        end
+
+        def workload_overloaded?
+          @metadata.dig(:mesh_workload, :overloaded) == true
+        end
+
+        def workload_healthy?
+          !workload_degraded? && !workload_overloaded?
+        end
+
+        # True only when the workload dimension was populated (tracker is present).
+        def workload_observed?
+          @metadata.key?(:mesh_workload)
+        end
+
+        # ── Governance dimension ──────────────────────────────────────────────
+
+        def governance_trust_status
+          @metadata.dig(:mesh_governance, :trust, :status)&.to_sym
+        end
+
+        def governance_freshness_seconds
+          @metadata.dig(:mesh_governance, :freshness_seconds)
+        end
+
+        def governance_crest_digest
+          @metadata.dig(:mesh_governance, :crest_digest)
+        end
+
+        def governance_total
+          @metadata.dig(:mesh_governance, :total) || 0
+        end
+
+        # ── OLAP Point summary ────────────────────────────────────────────────
+
+        def dimensions
+          {
+            capabilities: {
+              values:           @capabilities,
+              trust:            capabilities_trust_status,
+              freshness_seconds: capabilities_freshness_seconds
+            },
+            trust: {
+              status:      trust_status,
+              trusted:     trusted?,
+              fingerprint: identity_fingerprint
+            },
+            state: {
+              health:      health,
+              load_cpu:    load_cpu,
+              load_memory: load_memory,
+              concurrency: concurrency,
+              queue_depth: queue_depth
+            },
+            locality: {
+              region:         region,
+              zone:           zone,
+              proximity_tags: proximity_tags
+            },
+            governance: {
+              trust:             governance_trust_status,
+              freshness_seconds: governance_freshness_seconds,
+              crest_digest:      governance_crest_digest,
+              total:             governance_total
+            },
+            provenance: {
+              observed_at:  observed_at,
+              observed_by:  observed_by,
+              confidence:   confidence,
+              hops:         hops,
+              authoritative: authoritative?
+            },
+            workload: {
+              failure_rate:    workload_failure_rate,
+              avg_duration_ms: workload_avg_duration_ms,
+              total:           workload_total,
+              degraded:        workload_degraded?,
+              overloaded:      workload_overloaded?,
+              observed:        workload_observed?
+            }
+          }.freeze
+        end
+
+        def to_h
+          { name: @name, url: @url, capabilities: @capabilities, tags: @tags, metadata: @metadata }
+        end
+
+        # ── Factory ───────────────────────────────────────────────────────────
+
+        # Build from a peer hash (PeerIdentityEnvelope output format) with
+        # freshness computed at observation time.
+        def self.from_peer_hash(hash, now: Time.now.utc)
+          hash = PeerMetadata.normalize(hash)
+          runtime_meta = PeerMetadata.runtime(hash[:metadata] || {}, now: now)
+          new(
+            name:         hash[:name] || "",
+            url:          hash[:url] || "",
+            capabilities: hash[:capabilities] || [],
+            tags:         hash[:tags] || [],
+            metadata:     runtime_meta
+          )
+        end
+
+        def self.from_h(hash)
+          from_peer_hash(PeerMetadata.normalize(hash))
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,284 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    module Mesh
+      # Chainable, immutable query builder over a collection of NodeObservation.
+      #
+      # Each method returns a new ObservationQuery — the original is unchanged.
+      # Execution is lazy: filtering and sorting happen only when #to_a / #each
+      # / #first / #count is called.
+      #
+      # Entry points:
+      #   Igniter::Cluster::Mesh.query(now:)
+      #   registry.query(now:)
+      #
+      # Example:
+      #   Igniter::Cluster::Mesh.query
+      #     .with(:database)
+      #     .healthy
+      #     .max_load_cpu(0.7)
+      #     .in_zone("us-east-1a")
+      #     .trusted
+      #     .order_by(:load_cpu)
+      #     .limit(3)
+      #     .to_a
+      class ObservationQuery
+        include Enumerable
+
+        ORDERABLE_DIMENSIONS = %i[
+          load_cpu load_memory concurrency queue_depth
+          confidence hops governance_total capabilities_freshness
+          failure_rate avg_latency_ms
+        ].freeze
+
+        def initialize(observations)
+          @observations = observations
+          @filters      = [].freeze
+          @orderings    = [].freeze
+          @limit_count  = nil
+          freeze
+        end
+
+        # ── Capabilities dimension ──────────────────────────────────────────
+
+        def with(*caps)
+          syms = caps.map(&:to_sym)
+          add_filter { |o| syms.all? { |c| o.capability?(c) } }
+        end
+
+        def without(*caps)
+          syms = caps.map(&:to_sym)
+          add_filter { |o| syms.none? { |c| o.capability?(c) } }
+        end
+
+        def tagged(*tags)
+          syms = tags.map(&:to_sym)
+          add_filter { |o| syms.all? { |t| o.tag?(t) } }
+        end
+
+        # ── Trust dimension ─────────────────────────────────────────────────
+
+        def trusted
+          add_filter(&:trusted?)
+        end
+
+        def trust_status_in(*statuses)
+          syms = statuses.map(&:to_sym)
+          add_filter { |o| syms.include?(o.trust_status) }
+        end
+
+        # ── State dimension ─────────────────────────────────────────────────
+
+        def healthy
+          add_filter { |o| o.health == :healthy }
+        end
+
+        def health_in(*statuses)
+          syms = statuses.map(&:to_sym)
+          add_filter { |o| syms.include?(o.health) }
+        end
+
+        def max_load_cpu(threshold)
+          add_filter { |o| o.load_cpu.nil? || o.load_cpu <= threshold }
+        end
+
+        def max_load_memory(threshold)
+          add_filter { |o| o.load_memory.nil? || o.load_memory <= threshold }
+        end
+
+        def max_concurrency(threshold)
+          add_filter { |o| o.concurrency <= threshold }
+        end
+
+        def max_queue_depth(threshold)
+          add_filter { |o| o.queue_depth <= threshold }
+        end
+
+        # ── Locality dimension ──────────────────────────────────────────────
+
+        def in_region(region)
+          add_filter { |o| o.region == region }
+        end
+
+        def in_zone(zone)
+          add_filter { |o| o.zone == zone }
+        end
+
+        def proximity_tagged(*tags)
+          syms = tags.map(&:to_sym)
+          add_filter { |o| syms.all? { |t| o.proximity_tags.include?(t) } }
+        end
+
+        # ── Governance dimension ────────────────────────────────────────────
+
+        def governance_trusted
+          add_filter { |o| o.governance_trust_status == :trusted }
+        end
+
+        # ── Workload dimension ──────────────────────────────────────────────
+
+        def not_degraded
+          add_filter { |o| !o.workload_degraded? }
+        end
+
+        def not_overloaded
+          add_filter { |o| !o.workload_overloaded? }
+        end
+
+        def workload_healthy
+          add_filter(&:workload_healthy?)
+        end
+
+        def max_failure_rate(threshold)
+          add_filter { |o| o.workload_failure_rate.nil? || o.workload_failure_rate <= threshold }
+        end
+
+        def max_latency_ms(threshold)
+          add_filter { |o| o.workload_avg_duration_ms.nil? || o.workload_avg_duration_ms <= threshold }
+        end
+
+        # ── Observation quality ─────────────────────────────────────────────
+
+        def fresh(max_seconds: 60)
+          add_filter { |o| o.fresh?(max_seconds: max_seconds) }
+        end
+
+        def authoritative
+          add_filter(&:authoritative?)
+        end
+
+        # ── General predicate ───────────────────────────────────────────────
+
+        def where(&block)
+          raise ArgumentError, "where requires a block" unless block
+
+          add_filter(&block)
+        end
+
+        # ── CapabilityQuery passthrough ────────────────────────────────────
+
+        def matching(query)
+          normalized = Igniter::Cluster::Replication::CapabilityQuery.normalize(query)
+          add_filter { |o| normalized.matches_profile?(o) }
+        end
+
+        # ── Ordering ────────────────────────────────────────────────────────
+
+        def order_by(dimension, direction: :asc)
+          raise ArgumentError, "direction must be :asc or :desc" unless %i[asc desc].include?(direction)
+          unless ORDERABLE_DIMENSIONS.include?(dimension) || dimension.respond_to?(:call)
+            raise ArgumentError, "Unknown ordering dimension: #{dimension.inspect}. " \
+                                  "Use one of #{ORDERABLE_DIMENSIONS.inspect} or a Proc."
+          end
+
+          clone_query do |q|
+            q.instance_variable_set(:@orderings, (@orderings + [{ dimension: dimension, direction: direction }]).freeze)
+          end
+        end
+
+        # ── Limiting ────────────────────────────────────────────────────────
+
+        def limit(n)
+          clone_query { |q| q.instance_variable_set(:@limit_count, n) }
+        end
+
+        # ── Execution ───────────────────────────────────────────────────────
+
+        def to_a
+          result = @observations.select { |obs| match?(obs) }
+          result = apply_orderings(result) unless @orderings.empty?
+          @limit_count ? result.first(@limit_count) : result
+        end
+
+        def each(&block)
+          to_a.each(&block)
+        end
+
+        def count
+          @observations.count { |obs| match?(obs) }
+        end
+
+        def empty?
+          !@observations.any? { |obs| match?(obs) }
+        end
+
+        def first(n = nil)
+          n ? to_a.first(n) : to_a.first
+        end
+
+        # Summary of what this query will filter and sort by.
+        def explain
+          lines = ["ObservationQuery(#{@observations.size} candidates)"]
+          lines << "  filters: #{@filters.size}"
+          unless @orderings.empty?
+            order_desc = @orderings.map { |o| "#{o[:dimension]} #{o[:direction]}" }.join(", ")
+            lines << "  order_by: #{order_desc}"
+          end
+          lines << "  limit: #{@limit_count}" if @limit_count
+          lines.join("\n")
+        end
+
+        private
+
+        def add_filter(&block)
+          clone_query { |q| q.instance_variable_set(:@filters, (@filters + [block]).freeze) }
+        end
+
+        def clone_query
+          q = self.class.allocate
+          q.instance_variable_set(:@observations, @observations)
+          q.instance_variable_set(:@filters,      @filters.dup.freeze)
+          q.instance_variable_set(:@orderings,    @orderings.dup.freeze)
+          q.instance_variable_set(:@limit_count,  @limit_count)
+          yield q
+          q.freeze
+          q
+        end
+
+        def match?(obs)
+          @filters.all? { |f| f.call(obs) }
+        end
+
+        def apply_orderings(observations)
+          observations.sort do |a, b|
+            comparison = 0
+            @orderings.each do |order|
+              left  = dimension_value(a, order[:dimension])
+              right = dimension_value(b, order[:dimension])
+              comparison = compare_values(left, right, order[:direction])
+              break unless comparison.zero?
+            end
+            comparison
+          end
+        end
+
+        def dimension_value(obs, dimension)
+          return dimension.call(obs) if dimension.respond_to?(:call)
+
+          case dimension
+          when :load_cpu                then obs.load_cpu
+          when :load_memory             then obs.load_memory
+          when :concurrency             then obs.concurrency
+          when :queue_depth             then obs.queue_depth
+          when :confidence              then obs.confidence
+          when :hops                    then obs.hops
+          when :governance_total        then obs.governance_total
+          when :capabilities_freshness  then obs.capabilities_freshness_seconds
+          when :failure_rate            then obs.workload_failure_rate
+          when :avg_latency_ms          then obs.workload_avg_duration_ms
+          end
+        end
+
+        def compare_values(left, right, direction)
+          return 0 if left == right
+          return (direction == :asc ? 1 : -1) if left.nil?
+          return (direction == :asc ? -1 : 1) if right.nil?
+
+          comparison = left <=> right
+          direction == :desc ? -comparison : comparison
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    module Mesh
+    # Immutable value object representing a peer in the static mesh.
+    class Peer
+      require_relative "../replication/capability_query"
+
+      attr_reader :name, :url, :capabilities, :tags, :metadata
+
+      def initialize(name:, url:, capabilities: [], tags: [], metadata: {})
+        @name         = name.to_s.freeze
+        @url          = url.to_s.chomp("/").freeze
+        @capabilities = Array(capabilities).map(&:to_sym).freeze
+        @tags         = Array(tags).map(&:to_sym).freeze
+        @metadata     = PeerMetadata.normalize(metadata).freeze
+        freeze
+      end
+
+      def capable?(capability)
+        @capabilities.include?(capability.to_sym)
+      end
+
+      def matches_query?(query)
+        normalized = Igniter::Cluster::Replication::CapabilityQuery.normalize(query)
+        normalized.matches_profile?(to_observation)
+      end
+
+      def to_observation(now: Time.now.utc, workload_tracker: nil)
+        meta = PeerMetadata.runtime(@metadata, now: now)
+        if workload_tracker
+          workload_meta = workload_tracker.to_metadata_for(@name)
+          meta = meta.merge(workload_meta) if workload_meta
+        end
+        NodeObservation.new(
+          name:         @name,
+          url:          @url,
+          capabilities: @capabilities,
+          tags:         @tags,
+          metadata:     meta
+        )
+      end
+
+      def profile
+        to_observation
+      end
+    end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    module Mesh
+      # Aggregated capacity snapshot for a single peer, computed by WorkloadTracker.
+      #
+      # degraded?   — failure_rate >= degraded_threshold (default 0.3)
+      # overloaded? — avg_duration_ms >= overload_threshold_ms (default 500)
+      PeerCapacityReport = ::Data.define(
+        :peer_name,
+        :total,
+        :successes,
+        :failures,
+        :failure_rate,
+        :avg_duration_ms,
+        :degraded,
+        :overloaded,
+        :capabilities
+      ) do
+        def degraded?;   degraded;   end
+        def overloaded?; overloaded; end
+        def healthy?;    !degraded? && !overloaded?; end
+
+        def to_h
+          {
+            peer_name:       peer_name,
+            total:           total,
+            successes:       successes,
+            failures:        failures,
+            failure_rate:    failure_rate.round(4),
+            avg_duration_ms: avg_duration_ms&.round(2),
+            degraded:        degraded?,
+            overloaded:      overloaded?,
+            healthy:         healthy?,
+            capabilities:    capabilities
+          }.compact
+        end
+      end
+    end
+  end
+end