igniter 0.4.3 → 0.5.0

data/lib/igniter/replication/expansion_plan.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Replication
+    # Immutable value object returned by ExpansionPlanner.
+    #
+    # Carries an ordered list of actions the replication system should execute
+    # and a human-readable rationale explaining why each action was chosen.
+    #
+    # Recognised action hashes:
+    #   { action: :replicate_role, role: :worker,  host: "10.0.0.2" }
+    #   { action: :retire_node,    node_id: "abc", host: "10.0.0.1" }
+    #   { action: :no_op }
+    class ExpansionPlan
+      attr_reader :actions, :rationale
+
+      # @param actions   [Array<Hash>]
+      # @param rationale [String, nil]
+      def initialize(actions:, rationale: nil)
+        @actions   = Array(actions).freeze
+        @rationale = rationale
+        freeze
+      end
+
+      # True when there is nothing to do.
+      #
+      # @return [Boolean]
+      def no_op?
+        @actions.all? { |a| a[:action] == :no_op }
+      end
+
+      # @return [Hash]
+      def to_h
+        { actions: @actions, rationale: @rationale }
+      end
+    end
+  end
+end

data/lib/igniter/replication/expansion_planner.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Replication
+    # Analyses network topology + episodic memory to produce an ExpansionPlan.
+    #
+    # Two modes of operation:
+    # * **Rule-based** (default) — applies fixed heuristics, no LLM required.
+    # * **LLM-assisted** — delegates to an LLM executor for intent-rich reasoning.
+    #
+    # Rule-based heuristics (applied in order):
+    # 1. Retire nodes marked unhealthy in the topology.
+    # 2. Spawn a new node for each required role absent from the topology.
+    # 3. Annotate the rationale when recent replication failures exceed the threshold.
+    # 4. Honour :scale_signal episodes (content: "scale_out:<role>").
+    #
+    # LLM mode receives topology snapshot + recent episodes and expects the
+    # executor to return { actions: [...], rationale: "..." }.
+    #
+    # @example Rule-based
+    #   topology = NetworkTopology.new
+    #   topology.register(node_id: "x", host: "10.0.0.1", role: :worker)
+    #
+    #   planner = ExpansionPlanner.new(
+    #     topology:       topology,
+    #     required_roles: [:worker, :coordinator],
+    #     host_pool:      ["10.0.0.2"]
+    #   )
+    #   plan = planner.plan
+    #   # plan.actions => [{ action: :replicate_role, role: :coordinator, host: "10.0.0.2" }]
+    class ExpansionPlanner
+      DEFAULT_FAILURE_THRESHOLD = 3
+
+      # @param topology          [NetworkTopology]     current node topology
+      # @param memory            [AgentMemory, nil]    episodic memory (optional)
+      # @param required_roles    [Array<Symbol>]       roles that must always be present
+      # @param failure_threshold [Integer]             replication failures before warning
+      # @param host_pool         [Array<String>]       candidate hosts for new nodes
+      # @param llm               [#call, nil]          optional LLM executor
+      def initialize(topology:, memory: nil, required_roles: [],
+                     failure_threshold: DEFAULT_FAILURE_THRESHOLD,
+                     host_pool: [], llm: nil)
+        @topology          = topology
+        @memory            = memory
+        @required_roles    = Array(required_roles).map(&:to_sym)
+        @failure_threshold = failure_threshold
+        @host_pool         = host_pool.dup
+        @llm               = llm
+      end
+
+      # Produce an ExpansionPlan.
+      #
+      # @return [ExpansionPlan]
+      def plan
+        @llm ? smart_plan : rule_based_plan
+      end
+
+      private
+
+      def rule_based_plan
+        actions   = []
+        rationale = []
+
+        retire_unhealthy(actions, rationale)
+        ensure_required_roles(actions, rationale)
+        check_failure_signal(rationale)
+        apply_scale_signals(actions, rationale)
+
+        actions << { action: :no_op } if actions.empty?
+        ExpansionPlan.new(actions: actions, rationale: rationale.join("; "))
+      end
+
+      def retire_unhealthy(actions, rationale)
+        @topology.nodes.reject(&:healthy).each do |node|
+          actions   << { action: :retire_node, node_id: node.node_id, host: node.host }
+          rationale << "node #{node.node_id} (#{node.host}) is unhealthy"
+        end
+      end
+
+      def ensure_required_roles(actions, rationale)
+        @required_roles.each do |role|
+          next unless @topology.needs_role?(role)
+
+          host = next_available_host
+          if host
+            actions   << { action: :replicate_role, role: role, host: host }
+            rationale << "role :#{role} absent; targeting #{host}"
+          else
+            rationale << "role :#{role} absent but no available host in pool"
+          end
+        end
+      end
+
+      def check_failure_signal(rationale)
+        return unless @memory
+
+        failures = @memory.recent(last: 20, type: :replication_event)
+                          .count { |e| e.outcome == "failure" }
+        if failures >= @failure_threshold
+          rationale << "#{failures} recent replication failures — check SSH credentials"
+        end
+      end
+
+      def apply_scale_signals(actions, rationale)
+        return unless @memory
+
+        @memory.recent(last: 10, type: :scale_signal).each do |ep|
+          m = ep.content.to_s.match(/\Ascale_out:(\w+)\z/)
+          next unless m
+
+          role = m[1].to_sym
+          host = next_available_host
+          if host
+            actions   << { action: :replicate_role, role: role, host: host }
+            rationale << "scale_signal requests :#{role} at #{host}"
+          end
+        end
+      end
+
+      def smart_plan
+        episodes = @memory&.recent(last: 50) || []
+        result   = @llm.call(
+          topology:       @topology.nodes.map { |n|
+                            { node_id: n.node_id, host: n.host,
+                              role: n.role, healthy: n.healthy }
+                          },
+          episodes:       episodes.map { |e|
+                            { type: e.type, content: e.content, outcome: e.outcome }
+                          },
+          required_roles: @required_roles,
+          host_pool:      @host_pool
+        )
+        ExpansionPlan.new(actions: Array(result[:actions]), rationale: result[:rationale])
+      end
+
+      def next_available_host
+        used = @topology.nodes.map(&:host).to_set
+        @host_pool.find { |h| !used.include?(h) }
+      end
+    end
+  end
+end

data/lib/igniter/replication/manifest.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Igniter
+  module Replication
+    # Self-description of a running Igniter instance, used during replication.
+    #
+    # Call Manifest.current to capture the current process's metadata.
+    class Manifest
+      attr_reader :gem_version, :ruby_version, :source_path,
+                  :startup_command, :instance_id
+
+      def self.current
+        spec = defined?(Gem) && Gem.loaded_specs["igniter"]
+        new(
+          gem_version: Igniter::VERSION,
+          ruby_version: RUBY_VERSION,
+          source_path: spec&.gem_dir || File.expand_path("../../..", __dir__),
+          startup_command: $PROGRAM_NAME,
+          instance_id: SecureRandom.uuid
+        )
+      end
+
+      def initialize(gem_version:, ruby_version:, source_path:, startup_command:, instance_id:)
+        @gem_version     = gem_version
+        @ruby_version    = ruby_version
+        @source_path     = source_path
+        @startup_command = startup_command
+        @instance_id     = instance_id
+        freeze
+      end
+
+      def to_h
+        {
+          gem_version: gem_version,
+          ruby_version: ruby_version,
+          source_path: source_path,
+          startup_command: startup_command,
+          instance_id: instance_id
+        }
+      end
+    end
+  end
+end

data/lib/igniter/replication/network_topology.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Replication
+    # Thread-safe in-memory registry of known nodes in the deployment network.
+    #
+    # Updated by ReflectiveReplicationAgent as nodes are spawned, heartbeat-ed,
+    # or removed. Can be shared across agent handler invocations via state.
+    #
+    # @example
+    #   topology = NetworkTopology.new
+    #   topology.register(node_id: "abc", host: "10.0.0.2", role: :worker)
+    #   topology.nodes(role: :worker)      # => [NodeEntry]
+    #   topology.needs_role?(:coordinator) # => true
+    class NetworkTopology
+      # Mutable record for a single live node (mutated only inside the Mutex).
+      NodeEntry = Struct.new(:node_id, :host, :role,
+                             :registered_at, :last_seen_at, :healthy,
+                             keyword_init: true)
+
+      def initialize
+        @nodes = {}
+        @mutex = Mutex.new
+      end
+
+      # Register or overwrite a node entry.
+      #
+      # @param node_id [String]
+      # @param host    [String]
+      # @param role    [Symbol, nil]
+      # @return [NodeEntry]
+      def register(node_id:, host:, role: nil)
+        now   = Time.now
+        entry = NodeEntry.new(
+          node_id:       node_id,
+          host:          host,
+          role:          role&.to_sym,
+          registered_at: now,
+          last_seen_at:  now,
+          healthy:       true
+        )
+        @mutex.synchronize { @nodes[node_id] = entry }
+        entry
+      end
+
+      # Update last_seen_at for a known node (heartbeat).
+      #
+      # @param node_id [String]
+      # @return [Boolean] true if the node was found
+      def touch(node_id:)
+        @mutex.synchronize do
+          entry = @nodes[node_id]
+          return false unless entry
+
+          entry.last_seen_at = Time.now
+          true
+        end
+      end
+
+      # Mark a node as unhealthy (e.g. SSH unreachable).
+      #
+      # @param node_id [String]
+      # @return [Boolean] true if the node was found
+      def mark_unhealthy(node_id:)
+        @mutex.synchronize do
+          entry = @nodes[node_id]
+          return false unless entry
+
+          entry.healthy = false
+          true
+        end
+      end
+
+      # Remove a node from the topology.
+      #
+      # @param node_id [String]
+      # @return [NodeEntry, nil] the removed entry, or nil if not found
+      def remove(node_id:)
+        @mutex.synchronize { @nodes.delete(node_id) }
+      end
+
+      # Return nodes, optionally filtered by role.
+      #
+      # @param role [Symbol, nil]
+      # @return [Array<NodeEntry>]
+      def nodes(role: nil)
+        @mutex.synchronize do
+          entries = @nodes.values.dup
+          role ? entries.select { |e| e.role == role.to_sym } : entries
+        end
+      end
+
+      # True when no healthy node with the given role exists.
+      #
+      # @param role [Symbol, String]
+      # @return [Boolean]
+      def needs_role?(role)
+        nodes(role: role).none?(&:healthy)
+      end
+
+      # Count of healthy nodes across all roles.
+      #
+      # @return [Integer]
+      def healthy_count
+        @mutex.synchronize { @nodes.values.count(&:healthy) }
+      end
+
+      # Total number of registered nodes.
+      #
+      # @return [Integer]
+      def size
+        @mutex.synchronize { @nodes.size }
+      end
+
+      # All registered node IDs.
+      #
+      # @return [Array<String>]
+      def node_ids
+        @mutex.synchronize { @nodes.keys.dup }
+      end
+    end
+  end
+end

data/lib/igniter/replication/node_role.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Replication
+    # Immutable description of a specialised role a differentiated node can assume.
+    #
+    # When a node replicates with differentiation it carries a NodeRole that
+    # shapes its remote configuration: which contracts to activate, which env
+    # vars to inject, and which capability tags to advertise in the mesh.
+    #
+    # @example
+    #   role = NodeRole.new(
+    #     name:          :worker,
+    #     contracts:     ["ComputeContract"],
+    #     capabilities:  [:compute],
+    #     env_overrides: { "WORKER_POOL" => "8" },
+    #     tags:          [:cpu_heavy]
+    #   )
+    class NodeRole
+      attr_reader :name, :contracts, :capabilities, :env_overrides, :tags
+
+      def initialize(name:, contracts: [], capabilities: [], env_overrides: {}, tags: [])
+        @name          = name.to_sym
+        @contracts     = Array(contracts).map(&:to_s).freeze
+        @capabilities  = Array(capabilities).map(&:to_sym).freeze
+        @env_overrides = Hash(env_overrides).transform_keys(&:to_s).freeze
+        @tags          = Array(tags).map(&:to_sym).freeze
+        freeze
+      end
+
+      def to_h
+        {
+          name:          @name,
+          contracts:     @contracts,
+          capabilities:  @capabilities,
+          env_overrides: @env_overrides,
+          tags:          @tags
+        }
+      end
+    end
+  end
+end

data/lib/igniter/replication/reflective_replication_agent.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require_relative "replication_agent"
+require_relative "network_topology"
+require_relative "expansion_plan"
+require_relative "expansion_planner"
+require_relative "role_registry"
+
+module Igniter
+  module Replication
+    # ReplicationAgent extended with episodic memory, self-reflection, and
+    # topology-aware network expansion.
+    #
+    # == Additional message types
+    #
+    #   :assess_network  — run ExpansionPlanner; execute replicate_role/retire_node actions
+    #   :reflect         — run a ReflectionCycle over recent episodes; store summary in state
+    #   :register_node   — register a remote node in the local NetworkTopology
+    #   :node_heartbeat  — update last_seen_at for a known node
+    #   :signal_scale    — emit a :scale_signal episode (e.g. from load monitors)
+    #
+    # == State keys (in addition to inherited :events)
+    #
+    #   :topology        — NetworkTopology instance (created lazily on first access)
+    #   :host_pool       — Array<String> of candidate hosts
+    #   :required_roles  — Array<Symbol> of roles that must always be present
+    #   :last_plan       — Hash from the most recent ExpansionPlan
+    #   :last_reflection — String summary from the most recent reflection cycle
+    #
+    # == Memory
+    #
+    # Call +enable_class_memory+ in the class body to activate episodic memory.
+    # Memory is class-level (shared across handler invocations on this class).
+    #
+    # == Auto-assessment
+    #
+    # Call +auto_assess(every: N)+ to schedule periodic topology assessment.
+    #
+    # @example
+    #   RoleRegistry.define(:worker, env_overrides: { "POOL" => "4" })
+    #
+    #   class MyAgent < ReflectiveReplicationAgent
+    #     enable_class_memory
+    #     auto_assess every: 60
+    #   end
+    #
+    #   ref = MyAgent.start(initial_state: {
+    #     topology:       NetworkTopology.new,
+    #     required_roles: [:worker],
+    #     host_pool:      ["10.0.0.2", "10.0.0.3"]
+    #   })
+    #   ref.call(:assess_network)
+    class ReflectiveReplicationAgent < ReplicationAgent
+      initial_state topology: nil, host_pool: [], required_roles: [],
+                    last_plan: nil, last_reflection: nil
+
+      # ── Class-level memory ─────────────────────────────────────────────────────
+
+      class << self
+        # Activate episodic memory for this class.
+        #
+        # @param store [Memory::Store, nil] backing store; defaults to global default
+        # @return [void]
+        def enable_class_memory(store: nil)
+          require "igniter/memory"
+          @class_memory_store   = store || Igniter::Memory.default_store
+          @class_memory_enabled = true
+        end
+
+        # Returns true when class-level memory has been activated.
+        #
+        # @return [Boolean]
+        def class_memory_enabled?
+          @class_memory_enabled || false
+        end
+
+        # Returns the AgentMemory facade bound to this class, or nil when disabled.
+        #
+        # @return [Memory::AgentMemory, nil]
+        def class_memory
+          return nil unless class_memory_enabled?
+
+          @class_memory ||= Igniter::Memory::AgentMemory.new(
+            store:    @class_memory_store,
+            agent_id: name.to_s
+          )
+        end
+
+        # Reset class-level memory state. Intended for use in tests.
+        #
+        # @return [void]
+        def reset_class_memory!
+          @class_memory         = nil
+          @class_memory_store   = nil
+          @class_memory_enabled = false
+        end
+
+        # Register a recurring topology assessment.
+        #
+        # @param every [Numeric] interval in seconds
+        # @return [void]
+        def auto_assess(every:)
+          schedule(:auto_assessment, every: every) do |state:|
+            agent = new
+            agent.send(:run_assess_network, state, {})
+          end
+        end
+      end
+
+      # ── deliver: intercept lifecycle events into memory ────────────────────────
+
+      # Override the no-op deliver from ReplicationAgent to record events.
+      # Subclasses can call +super+ and then add their own routing.
+      #
+      # @param type    [Symbol]
+      # @param payload [Hash]
+      def deliver(type, payload = {})
+        self.class.class_memory&.record(
+          type:       :replication_event,
+          content:    "#{type}: #{payload.inspect}",
+          outcome:    type == :replication_failed ? "failure" : "success",
+          importance: 0.6
+        )
+      end
+
+      # ── Handlers ───────────────────────────────────────────────────────────────
+
+      # Re-define :replicate (parent's handler is cleared by Agent.inherited).
+      on :replicate do |state:, payload:, **|
+        agent = new
+        agent.send(:run_replicate, payload)
+        state
+      end
+
+      on :assess_network do |state:, payload:, **|
+        agent = new
+        agent.send(:run_assess_network, state, payload)
+      end
+
+      on :reflect do |state:, payload:, **|
+        next state unless class_memory_enabled?
+
+        rec = class_memory.reflect
+        class_memory.record(
+          type:       :reflection,
+          content:    rec.summary,
+          outcome:    "success",
+          importance: 0.8
+        )
+        state.merge(last_reflection: rec.summary)
+      end
+
+      on :register_node do |state:, payload:, **|
+        topology = state[:topology] || NetworkTopology.new
+        topology.register(
+          node_id: payload.fetch(:node_id),
+          host:    payload.fetch(:host),
+          role:    payload[:role]
+        )
+        state.merge(topology: topology)
+      end
+
+      on :node_heartbeat do |state:, payload:, **|
+        state[:topology]&.touch(node_id: payload.fetch(:node_id))
+        state
+      end
+
+      on :signal_scale do |state:, payload:, **|
+        role = payload.fetch(:role)
+        class_memory&.record(
+          type:    :scale_signal,
+          content: "scale_out:#{role}",
+          outcome: nil
+        )
+        state
+      end
+
+      private
+
+      # Assess the network topology and execute the resulting plan.
+      # Returns the updated state hash.
+      #
+      # @param state   [Hash]
+      # @param payload [Hash]
+      # @return [Hash]
+      def run_assess_network(state, payload)
+        topology = state[:topology] || NetworkTopology.new
+        planner  = ExpansionPlanner.new(
+          topology:       topology,
+          memory:         self.class.class_memory,
+          required_roles: Array(payload[:required_roles] || state[:required_roles]),
+          host_pool:      Array(payload[:host_pool]      || state[:host_pool])
+        )
+
+        plan = planner.plan
+
+        plan.actions.each do |action|
+          case action[:action]
+          when :replicate_role
+            run_replicate_role(action, topology)
+          when :retire_node
+            topology.remove(node_id: action[:node_id])
+            deliver(:node_retired, node_id: action[:node_id], host: action[:host])
+          end
+        end
+
+        self.class.class_memory&.record(
+          type:    :assessment,
+          content: plan.rationale.to_s,
+          outcome: "success"
+        )
+
+        state.merge(topology: topology, last_plan: plan.to_h)
+      end
+
+      # Execute a :replicate_role action: call run_replicate + register in topology.
+      #
+      # @param action   [Hash]
+      # @param topology [NetworkTopology]
+      def run_replicate_role(action, topology)
+        role_obj = RoleRegistry.registered?(action[:role]) ? RoleRegistry.fetch(action[:role]) : nil
+        env      = role_obj&.env_overrides || {}
+
+        run_replicate(
+          host:                 action.fetch(:host),
+          user:                 action.fetch(:user, "deploy"),
+          strategy:             action.fetch(:strategy, :git),
+          env:                  env,
+          bootstrapper_options: action.fetch(:bootstrapper_options, {})
+        )
+
+        topology.register(node_id: SecureRandom.uuid, host: action[:host], role: action[:role])
+        deliver(:role_replicated, host: action[:host], role: action[:role])
+      end
+    end
+  end
+end