igniter 0.5.0 → 0.5.2

data/lib/igniter/replication/reflective_replication_agent.rb

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

data/lib/igniter/replication/replication_agent.rb

@@ -1,87 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../agent"
-
-module Igniter
-  module Replication
-    # Agent that handles :replicate messages to deploy Igniter to remote servers.
-    #
-    # In production, start via ReplicationAgent.start and send messages through
-    # the Ref. In tests, instantiate directly and call handle_message/1.
-    #
-    # Message payload keys:
-    #   host:                  [String]  (required) remote hostname or IP
-    #   user:                  [String]  (required) SSH username
-    #   key:                   [String]  path to SSH private key (optional)
-    #   port:                  [Integer] SSH port (default: 22)
-    #   env:                   [Hash]    environment variables for remote (default: {})
-    #   strategy:              [Symbol]  :git, :gem, or :tarball (default: :git)
-    #   target_path:           [String]  installation path on remote (default: /opt/igniter)
-    #   bootstrapper_options:  [Hash]    forwarded to the bootstrapper constructor
-    #
-    class ReplicationAgent < Igniter::Agent
-      MAX_REPLICAS = 10
-
-      initial_state events: []
-
-      # Class-level handler for the agent mailbox runtime.
-      # Instantiates a temporary agent to run the replication so that
-      # deliver/1 can be overridden in subclasses.
-      on :replicate do |state:, payload:, **|
-        agent = new
-        agent.send(:run_replicate, payload)
-        state
-      end
-
-      # Emit a named lifecycle event. Override or stub in tests.
-      #
-      # @param type    [Symbol] event name (e.g. :replication_started)
-      # @param payload [Hash]   associated data
-      def deliver(type, payload = {})
-        # Base implementation: no-op. Override in subclasses for real routing.
-      end
-
-      # Process a raw message hash synchronously (used in tests and internal tooling).
-      #
-      # @param message [Hash] must have :type key; optional :payload key
-      def handle_message(message)
-        type    = message.fetch(:type).to_sym
-        payload = message.fetch(:payload, {})
-        return unless type == :replicate
-
-        run_replicate(payload)
-      end
-
-      private
-
-      def run_replicate(payload) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
-        host        = payload[:host]        || raise(ArgumentError, "host is required")
-        user        = payload[:user]        || raise(ArgumentError, "user is required")
-        key         = payload[:key]
-        port        = payload.fetch(:port, 22)
-        env         = payload.fetch(:env, {})
-        strategy    = payload.fetch(:strategy, :git).to_sym
-        target_path = payload.fetch(:target_path, "/opt/igniter")
-        bs_options  = payload.fetch(:bootstrapper_options, {})
-
-        session      = SSHSession.new(host: host, user: user, key: key, port: port)
-        bootstrapper = Replication.bootstrapper_for(strategy, **bs_options)
-        manifest     = Manifest.current
-
-        deliver(:replication_started, host: host, instance_id: manifest.instance_id)
-
-        bootstrapper.install(session: session, manifest: manifest,
-                             env: env, target_path: target_path)
-        bootstrapper.start(session: session, manifest: manifest, target_path: target_path)
-        verified = bootstrapper.verify(session: session, target_path: target_path)
-
-        deliver(:replication_completed,
-                host: host, instance_id: manifest.instance_id, verified: verified)
-      rescue SSHSession::SSHError => e
-        deliver(:replication_failed, host: host, error: e.message)
-      rescue ArgumentError => e
-        deliver(:replication_failed, host: payload[:host], error: e.message)
-      end
-    end
-  end
-end

data/lib/igniter/replication/role_registry.rb

@@ -1,73 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Replication
-    # Module-level registry of named NodeRoles.
-    #
-    # @example
-    #   RoleRegistry.define(:worker,
-    #     contracts:     ["ComputeContract"],
-    #     capabilities:  [:compute],
-    #     env_overrides: { "WORKER_POOL" => "4" }
-    #   )
-    #
-    #   role = RoleRegistry.fetch(:worker)
-    #   role.env_overrides  # => { "WORKER_POOL" => "4" }
-    module RoleRegistry
-      @roles = {}
-
-      class << self
-        # Define and register a new role.
-        #
-        # @param name          [Symbol, String]
-        # @param contracts     [Array<String>]
-        # @param capabilities  [Array<Symbol>]
-        # @param env_overrides [Hash]
-        # @param tags          [Array<Symbol>]
-        # @return [NodeRole]
-        def define(name, contracts: [], capabilities: [], env_overrides: {}, tags: [])
-          role = NodeRole.new(
-            name:          name,
-            contracts:     contracts,
-            capabilities:  capabilities,
-            env_overrides: env_overrides,
-            tags:          tags
-          )
-          @roles[role.name] = role
-        end
-
-        # Fetch a role by name.
-        #
-        # @param name [Symbol, String]
-        # @return [NodeRole]
-        # @raise [ArgumentError] if not registered
-        def fetch(name)
-          @roles.fetch(name.to_sym) do
-            raise ArgumentError,
-                  "Unknown role: #{name}. Available: #{@roles.keys.join(", ")}"
-          end
-        end
-
-        # Returns true if a role with the given name is registered.
-        #
-        # @param name [Symbol, String]
-        # @return [Boolean]
-        def registered?(name)
-          @roles.key?(name.to_sym)
-        end
-
-        # All registered roles (copy to prevent external mutation).
-        #
-        # @return [Hash{Symbol => NodeRole}]
-        def all
-          @roles.dup
-        end
-
-        # Remove all registrations. Useful in tests.
-        def reset!
-          @roles = {}
-        end
-      end
-    end
-  end
-end

data/lib/igniter/replication/ssh_session.rb

@@ -1,77 +0,0 @@
-# frozen_string_literal: true
-
-require "open3"
-
-module Igniter
-  module Replication
-    # Thin subprocess wrapper over the +ssh+ and +scp+ CLI tools.
-    #
-    # Provides exec/exec! for running remote commands and upload! for
-    # copying local files to the remote host. No external gems required.
-    class SSHSession
-      class SSHError < Igniter::Error; end
-
-      DEFAULT_CONNECT_TIMEOUT = 10
-
-      def initialize(host:, user:, key: nil, port: 22, connect_timeout: DEFAULT_CONNECT_TIMEOUT)
-        @host            = host
-        @user            = user
-        @key             = key
-        @port            = port
-        @connect_timeout = connect_timeout
-      end
-
-      # Run a command on the remote host. Raises SSHError on non-zero exit.
-      # Returns stdout string on success.
-      def exec!(command)
-        result = exec(command)
-        raise SSHError, "SSH command failed on #{@host}: #{command.inspect}\n#{result[:stderr]}" \
-          unless result[:success]
-
-        result[:stdout]
-      end
-
-      # Run a command on the remote host.
-      # Returns a Hash: { stdout:, stderr:, success:, exit_code: }
-      def exec(command)
-        stdout, stderr, status = Open3.capture3(*build_cmd(command))
-        { stdout: stdout, stderr: stderr, success: status.success?, exit_code: status.exitstatus }
-      end
-
-      # Upload a local file to the remote host via scp.
-      # Raises SSHError on failure.
-      def upload!(local_path, remote_path)
-        args = ["scp", *scp_opts, "-P", @port.to_s, local_path, "#{@user}@#{@host}:#{remote_path}"]
-        _, stderr, status = Open3.capture3(*args)
-        raise SSHError, "SCP upload failed to #{@host}: #{stderr}" unless status.success?
-      end
-
-      # Quick connectivity test. Returns true if the remote responds.
-      def test_connection
-        exec("echo ok")[:success]
-      end
-
-      private
-
-      def build_cmd(command)
-        ["ssh", *ssh_opts, "-p", @port.to_s, "#{@user}@#{@host}", command]
-      end
-
-      def ssh_opts
-        opts = [
-          "-o", "StrictHostKeyChecking=no",
-          "-o", "BatchMode=yes",
-          "-o", "ConnectTimeout=#{@connect_timeout}"
-        ]
-        opts += ["-i", @key] if @key
-        opts
-      end
-
-      def scp_opts
-        opts = ["-o", "StrictHostKeyChecking=no", "-B"]
-        opts += ["-i", @key] if @key
-        opts
-      end
-    end
-  end
-end

data/lib/igniter/replication.rb

@@ -1,54 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "replication/manifest"
-require_relative "replication/ssh_session"
-require_relative "replication/bootstrapper"
-require_relative "replication/bootstrappers/git"
-require_relative "replication/bootstrappers/gem"
-require_relative "replication/bootstrappers/tarball"
-require_relative "replication/replication_agent"
-require_relative "replication/node_role"
-require_relative "replication/role_registry"
-require_relative "replication/network_topology"
-require_relative "replication/expansion_plan"
-require_relative "replication/expansion_planner"
-require_relative "replication/reflective_replication_agent"
-
-module Igniter
-  # Self-replication capability: deploy a running Igniter instance to a
-  # remote server via SSH using one of three deployment strategies.
-  #
-  # Usage:
-  #   require "igniter/replication"
-  #   ref = Igniter::Replication::ReplicationAgent.start
-  #   ref.send(:replicate,
-  #     host:     "10.0.0.2",
-  #     user:     "deploy",
-  #     strategy: :git,
-  #     bootstrapper_options: { repo_url: "https://github.com/org/app" }
-  #   )
-  #
-  module Replication
-    ReplicationError = Class.new(Igniter::Error)
-
-    BOOTSTRAPPERS = {
-      git: Bootstrappers::Git,
-      gem: Bootstrappers::Gem,
-      tarball: Bootstrappers::Tarball
-    }.freeze
-
-    # Instantiate the bootstrapper for the given strategy.
-    #
-    # @param strategy [Symbol] one of :git, :gem, :tarball
-    # @param options  [Hash]   forwarded to the bootstrapper constructor
-    # @return [Bootstrapper]
-    # @raise [ArgumentError] for unknown strategies
-    def self.bootstrapper_for(strategy, **options)
-      klass = BOOTSTRAPPERS.fetch(strategy.to_sym) do
-        raise ArgumentError,
-              "Unknown bootstrapper: #{strategy}. Available: #{BOOTSTRAPPERS.keys.join(", ")}"
-      end
-      klass.new(**options)
-    end
-  end
-end

data/lib/igniter/runtime/cache.rb

@@ -1,126 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Runtime
-    class Cache
-      def initialize
-        @states = {}
-        @mutex = Mutex.new
-        @condition = ConditionVariable.new
-      end
-
-      def fetch(node_name)
-        @mutex.synchronize { @states[node_name.to_sym] }
-      end
-
-      def write(state) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
-        @mutex.synchronize do
-          current = @states[state.node.name]
-          version = state.version || (current&.running? ? current.version : next_version(current))
-          value_version = compute_value_version(state, current)
-          @states[state.node.name] = NodeState.new(
-            node: state.node,
-            status: state.status,
-            value: state.value,
-            error: state.error,
-            version: version,
-            value_version: value_version,
-            resolved_at: state.resolved_at,
-            invalidated_by: state.invalidated_by,
-            dep_snapshot: state.dep_snapshot
-          )
-          @condition.broadcast
-        end
-      end
-
-      def begin_resolution(node) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
-        @mutex.synchronize do
-          loop do
-            current = @states[node.name]
-            return [:cached, current] if current && !current.stale? && !current.running?
-
-            unless current&.running?
-              @states[node.name] = NodeState.new(
-                node: node,
-                status: :running,
-                value: current&.value,
-                error: current&.error,
-                version: next_version(current),
-                value_version: current&.value_version,
-                resolved_at: current&.resolved_at || Time.now.utc,
-                invalidated_by: nil,
-                dep_snapshot: current&.dep_snapshot
-              )
-              return [:started, @states[node.name]]
-            end
-
-            @condition.wait(@mutex)
-          end
-        end
-      end
-
-      def stale!(node, invalidated_by:) # rubocop:disable Metrics/MethodLength
-        @mutex.synchronize do
-          current = @states[node.name]
-          return unless current
-
-          @states[node.name] = NodeState.new(
-            node: node,
-            status: :stale,
-            value: current.value,
-            error: current.error,
-            version: current.version + 1,
-            value_version: current.value_version,
-            resolved_at: current.resolved_at,
-            invalidated_by: invalidated_by,
-            dep_snapshot: current.dep_snapshot
-          )
-          @condition.broadcast
-        end
-      end
-
-      def values
-        @mutex.synchronize { @states.values }
-      end
-
-      def to_h
-        @mutex.synchronize { @states.dup }
-      end
-
-      def restore!(states)
-        @mutex.synchronize do
-          @states = states.transform_keys(&:to_sym)
-          @condition.broadcast
-        end
-      end
-
-      private
-
-      def next_version(current)
-        current ? current.version + 1 : 1
-      end
-
-      # value_version only increments when the actual value changes.
-      # When state.value_version is set explicitly (backdating from resolver), use it.
-      # For :succeeded states, compare the new value against the old value:
-      #   - same value → preserve value_version
-      #   - different (or first time) → increment
-      # For all other statuses (failed, pending, etc.) → no value_version.
-      def compute_value_version(state, current)
-        return state.value_version if state.value_version
-
-        return nil unless state.status == :succeeded
-
-        base_vv = current&.value_version || 0
-        # When current is :running, current.value holds the pre-stale value for comparison.
-        old_value = current&.value
-
-        if base_vv.positive? && old_value == state.value
-          base_vv
-        else
-          base_vv + 1
-        end
-      end
-    end
-  end
-end