igniter 0.5.0 → 0.5.2

data/lib/igniter/registry.rb

@@ -1,67 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  # Thread-safe process registry mapping names to agent Refs.
-  #
-  # Names can be any object that is a valid Hash key (Symbols recommended).
-  #
-  #   Igniter::Registry.register(:counter, ref)
-  #   Igniter::Registry.find(:counter)    # => ref
-  #   Igniter::Registry.unregister(:counter)
-  #
-  module Registry
-    class RegistryError < Igniter::Error; end
-
-    @store = {}
-    @mutex = Mutex.new
-
-    class << self
-      # Register +ref+ under +name+. Raises RegistryError if the name is taken.
-      def register(name, ref)
-        @mutex.synchronize do
-          raise RegistryError, "Name '#{name}' is already registered" if @store.key?(name)
-
-          @store[name] = ref
-        end
-        ref
-      end
-
-      # Register (or replace) +ref+ under +name+ without uniqueness check.
-      def register!(name, ref)
-        @mutex.synchronize { @store[name] = ref }
-        ref
-      end
-
-      # Return the Ref registered under +name+, or nil if not found.
-      def find(name)
-        @mutex.synchronize { @store[name] }
-      end
-
-      # Return the Ref or raise RegistryError if not found.
-      def fetch(name)
-        @mutex.synchronize do
-          @store.fetch(name) { raise RegistryError, "No agent registered as '#{name}'" }
-        end
-      end
-
-      # Remove and return the Ref registered under +name+.
-      def unregister(name)
-        @mutex.synchronize { @store.delete(name) }
-      end
-
-      def registered?(name)
-        @mutex.synchronize { @store.key?(name) }
-      end
-
-      # Snapshot of the current name→Ref map.
-      def all
-        @mutex.synchronize { @store.dup }
-      end
-
-      # Remove all registrations (useful in tests).
-      def clear
-        @mutex.synchronize { @store.clear }
-      end
-    end
-  end
-end

data/lib/igniter/replication/bootstrapper.rb

@@ -1,61 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Replication
-    # Abstract base class for deployment bootstrappers.
-    #
-    # Subclasses implement three lifecycle methods:
-    #   install — copy/install the application on the remote
-    #   start   — launch the application process
-    #   verify  — confirm the application is running (default impl provided)
-    class Bootstrapper
-      BootstrapError = Class.new(Igniter::Error)
-
-      # Install the application on the remote server.
-      #
-      # @param session [SSHSession] active SSH session to the remote host
-      # @param manifest [Manifest] self-description of the running instance
-      # @param env [Hash] environment variables to write on remote
-      # @param target_path [String] base directory on the remote server
-      def install(session:, manifest:, env: {}, target_path: "/opt/igniter")
-        raise NotImplementedError, "#{self.class}#install not implemented"
-      end
-
-      # Start the application on the remote server.
-      #
-      # @param session [SSHSession] active SSH session to the remote host
-      # @param manifest [Manifest] self-description of the running instance
-      # @param target_path [String] base directory on the remote server
-      def start(session:, manifest:, target_path: "/opt/igniter")
-        raise NotImplementedError, "#{self.class}#start not implemented"
-      end
-
-      # Verify the application is running on the remote server.
-      # Returns true if Igniter can be loaded, false otherwise.
-      #
-      # @param session [SSHSession] active SSH session to the remote host
-      # @param target_path [String] base directory on the remote server (unused by default impl)
-      def verify(session:, target_path: "/opt/igniter") # rubocop:disable Lint/UnusedMethodArgument
-        result = session.exec("ruby -e 'require \"igniter\"; puts Igniter::VERSION' 2>/dev/null")
-        result[:success] && !result[:stdout].strip.empty?
-      rescue SSHSession::SSHError
-        false
-      end
-
-      protected
-
-      # Write environment variables to a shell-sourceable file on the remote.
-      #
-      # @param session [SSHSession] active SSH session
-      # @param env [Hash] key-value pairs to export
-      # @param path [String] remote path for the env file
-      def write_env_file(session:, env:, path:)
-        return if env.nil? || env.empty?
-
-        require "shellwords"
-        lines = env.map { |k, v| "export #{k}=#{v.to_s.shellescape}" }.join("\n")
-        session.exec!("printf '%s\\n' #{lines.shellescape} > #{path}")
-      end
-    end
-  end
-end

data/lib/igniter/replication/bootstrappers/gem.rb

@@ -1,32 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Replication
-    module Bootstrappers
-      # Deploys by installing the igniter gem from RubyGems on the remote host.
-      #
-      # Optionally pins a specific gem version. The startup script defaults to
-      # the +igniter-server+ executable installed with the gem.
-      class Gem < Bootstrapper
-        def initialize(version: nil, startup_script: nil)
-          super()
-          @version        = version
-          @startup_script = startup_script
-        end
-
-        def install(session:, manifest:, env: {}, target_path: "/opt/igniter") # rubocop:disable Lint/UnusedMethodArgument
-          ver_flag = @version ? " -v #{@version}" : ""
-          session.exec!("gem install igniter#{ver_flag} --no-document")
-          session.exec!("mkdir -p #{target_path}")
-          write_env_file(session: session, env: env, path: "#{target_path}/.env")
-        end
-
-        def start(session:, manifest:, target_path: "/opt/igniter") # rubocop:disable Lint/UnusedMethodArgument
-          log_path = "#{target_path}/igniter.log"
-          script   = @startup_script || "igniter-server"
-          session.exec!("nohup #{script} >> #{log_path} 2>&1 &")
-        end
-      end
-    end
-  end
-end

data/lib/igniter/replication/bootstrappers/git.rb

@@ -1,39 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Replication
-    module Bootstrappers
-      # Deploys by cloning a git repository on the remote host.
-      #
-      # Requires git to be installed on the remote. After cloning, installs
-      # bundler and runs bundle install.
-      class Git < Bootstrapper
-        DEFAULT_BRANCH         = "main"
-        DEFAULT_BUNDLE_OPTIONS = "--without development test"
-
-        def initialize(repo_url:, branch: DEFAULT_BRANCH, bundle_options: DEFAULT_BUNDLE_OPTIONS)
-          super()
-          @repo_url       = repo_url
-          @branch         = branch
-          @bundle_options = bundle_options
-        end
-
-        def install(session:, manifest:, env: {}, target_path: "/opt/igniter") # rubocop:disable Lint/UnusedMethodArgument
-          app_path = "#{target_path}/app"
-          session.exec!("mkdir -p #{target_path}")
-          session.exec!("git clone --branch #{@branch} --depth 1 #{@repo_url} #{app_path}")
-          session.exec!("cd #{app_path} && gem install bundler --no-document")
-          session.exec!("cd #{app_path} && bundle install #{@bundle_options}")
-          write_env_file(session: session, env: env, path: "#{target_path}/.env")
-        end
-
-        def start(session:, manifest:, target_path: "/opt/igniter")
-          app_path = "#{target_path}/app"
-          log_path = "#{target_path}/igniter.log"
-          cmd      = manifest.startup_command
-          session.exec!("cd #{app_path} && nohup ruby #{cmd} >> #{log_path} 2>&1 &")
-        end
-      end
-    end
-  end
-end

data/lib/igniter/replication/bootstrappers/tarball.rb

@@ -1,56 +0,0 @@
-# frozen_string_literal: true
-
-require "tmpdir"
-require "fileutils"
-
-module Igniter
-  module Replication
-    module Bootstrappers
-      # Deploys by creating a gzipped tarball of the local source tree,
-      # uploading it via SCP, and extracting it on the remote host.
-      #
-      # This strategy works without git or internet access on the remote,
-      # making it suitable for air-gapped or private environments.
-      class Tarball < Bootstrapper
-        def install(session:, manifest:, env: {}, target_path: "/opt/igniter")
-          tarball = create_tarball(manifest)
-          begin
-            remote_tar = "/tmp/igniter_replication_#{Process.pid}.tar.gz"
-            session.upload!(tarball, remote_tar)
-            extract_and_install(session, remote_tar, target_path)
-            write_env_file(session: session, env: env, path: "#{target_path}/.env")
-          ensure
-            FileUtils.rm_f(tarball)
-          end
-        end
-
-        def start(session:, manifest:, target_path: "/opt/igniter")
-          app_path = "#{target_path}/app"
-          log_path = "#{target_path}/igniter.log"
-          cmd      = File.basename(manifest.startup_command)
-          session.exec!("cd #{app_path} && nohup ruby #{cmd} >> #{log_path} 2>&1 &")
-        end
-
-        private
-
-        def extract_and_install(session, remote_tar, target_path)
-          app_path = "#{target_path}/app"
-          session.exec!("mkdir -p #{app_path}")
-          session.exec!("tar -xzf #{remote_tar} -C #{app_path} --strip-components=1")
-          session.exec!("cd #{app_path} && gem install bundler --no-document")
-          session.exec!("cd #{app_path} && bundle install --without development test")
-          session.exec!("rm -f #{remote_tar}")
-        end
-
-        def create_tarball(manifest)
-          source  = manifest.source_path
-          tmpfile = File.join(Dir.tmpdir, "igniter_replication_#{Process.pid}.tar.gz")
-          parent  = File.dirname(source)
-          name    = File.basename(source)
-          system("tar", "-czf", tmpfile, "-C", parent, name)
-          tmpfile
-        end
-      end
-    end
-  end
-end

data/lib/igniter/replication/expansion_plan.rb

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

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

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

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

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