igniter 0.5.0 → 0.5.1

data/packages/igniter-app/lib/igniter/ignite/ignition_plan.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Ignite
+    class IgnitionPlan
+      attr_reader :id, :ignite_mode, :strategy, :approval_mode, :intents, :requested_by, :requested_from,
+                  :seed_node, :metadata
+
+      def initialize(id:, ignite_mode:, strategy:, approval_mode:, intents:, requested_by:, requested_from:, seed_node:, metadata: {})
+        @id = id.to_s.strip
+        @ignite_mode = ignite_mode.to_sym
+        @strategy = strategy.to_sym
+        @approval_mode = approval_mode.to_sym
+        @intents = Array(intents).freeze
+        @requested_by = immutable_hash(requested_by)
+        @requested_from = immutable_hash(requested_from)
+        @seed_node = immutable_hash(seed_node)
+        @metadata = immutable_hash(metadata)
+
+        validate!
+        freeze
+      end
+
+      def local_replica_intents
+        intents.select(&:local_replica?)
+      end
+
+      def remote_intents
+        intents.reject(&:local_replica?)
+      end
+
+      def approval_required?
+        approval_mode == :required
+      end
+
+      def empty?
+        intents.empty?
+      end
+
+      def to_h
+        {
+          id: id,
+          ignite_mode: ignite_mode,
+          strategy: strategy,
+          approval_mode: approval_mode,
+          intents: intents.map(&:to_h),
+          requested_by: requested_by,
+          requested_from: requested_from,
+          seed_node: seed_node,
+          metadata: metadata,
+          summary: {
+            total_intents: intents.size,
+            local_replicas: local_replica_intents.size,
+            remote_targets: remote_intents.size
+          }
+        }
+      end
+
+      private
+
+      def validate!
+        raise ArgumentError, "ignition plan id cannot be empty" if id.empty?
+        unless intents.all? { |intent| intent.is_a?(DeploymentIntent) }
+          raise ArgumentError, "ignition plan intents must be Igniter::Ignite::DeploymentIntent objects"
+        end
+      end
+
+      def immutable_hash(hash)
+        Hash(hash).each_with_object({}) do |(key, value), result|
+          result[key.to_s] =
+            case value
+            when Hash
+              immutable_hash(value)
+            when Array
+              value.map { |item| item.is_a?(Hash) ? immutable_hash(item) : item }.freeze
+            else
+              value
+            end
+        end.freeze
+      end
+    end
+  end
+end

data/packages/igniter-app/lib/igniter/ignite/ignition_report.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Ignite
+    class IgnitionReport
+      attr_reader :plan_id, :status, :strategy, :approval_mode, :entries, :events, :summary
+
+      def initialize(plan_id:, status:, strategy:, approval_mode:, entries:, events:, summary:)
+        @plan_id = plan_id.to_s
+        @status = status.to_sym
+        @strategy = strategy.to_sym
+        @approval_mode = approval_mode.to_sym
+        @entries = Array(entries).map { |entry| immutable(entry) }.freeze
+        @events = Array(events).map { |event| immutable(event) }.freeze
+        @summary = immutable(summary)
+        freeze
+      end
+
+      def awaiting_approval?
+        status == :awaiting_approval
+      end
+
+      def prepared?
+        status == :prepared
+      end
+
+      def pending_remote?
+        status == :pending_remote
+      end
+
+      def awaiting_join?
+        status == :awaiting_join
+      end
+
+      def joined?
+        status == :joined
+      end
+
+      def detached?
+        status == :detached
+      end
+
+      def torn_down?
+        status == :torn_down
+      end
+
+      def blocked?
+        status == :blocked
+      end
+
+      def by_status
+        summary.fetch(:by_status, {})
+      end
+
+      def by_join_status
+        summary.fetch(:by_join_status, {})
+      end
+
+      def latest_event
+        events.last
+      end
+
+      def by_event_type
+        events.each_with_object(Hash.new(0)) do |event, counts|
+          counts[event.fetch(:type)] += 1
+        end
+      end
+
+      def recent_events(limit = 5)
+        events.last(limit)
+      end
+
+      def target_timelines
+        entry_index = entries.each_with_object({}) do |entry, result|
+          result[entry.fetch(:target_id).to_s] = entry
+        end
+
+        grouped_events = events.each_with_object(Hash.new { |hash, key| hash[key] = [] }) do |event, result|
+          target_id = event[:target_id]
+          next unless target_id
+
+          result[target_id.to_s] << event
+        end
+
+        entry_index.each_with_object({}) do |(target_id, entry), result|
+          target_events = grouped_events[target_id]
+          result[target_id] = {
+            target_id: target_id,
+            kind: entry[:kind],
+            status: entry[:status],
+            action: entry[:action],
+            admission_status: entry.dig(:admission, :status),
+            join_status: entry.dig(:join, :status),
+            latest_event_type: target_events.last&.dig(:type),
+            event_count: target_events.size,
+            events: target_events
+          }.freeze
+        end
+      end
+
+      def timeline_for(target_id)
+        target_timelines[target_id.to_s]
+      end
+
+      def progress
+        {
+          latest_event: latest_event,
+          total_events: events.size,
+          by_event_type: by_event_type.freeze,
+          recent_events: recent_events.freeze,
+          targets: target_timelines.freeze
+        }
+      end
+
+      def to_h
+        {
+          plan_id: plan_id,
+          status: status,
+          strategy: strategy,
+          approval_mode: approval_mode,
+          entries: entries,
+          events: events,
+          summary: summary,
+          progress: progress
+        }
+      end
+
+      private
+
+      def immutable(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, nested), result|
+            result[key.to_sym] = immutable(nested)
+          end.freeze
+        when Array
+          value.map { |item| immutable(item) }.freeze
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/packages/igniter-app/lib/igniter/ignite/store.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Ignite
+    class Store
+      def append(_event)
+        raise NotImplementedError, "#{self.class}#append not implemented"
+      end
+
+      def load_events
+        raise NotImplementedError, "#{self.class}#load_events not implemented"
+      end
+
+      def clear!
+        raise NotImplementedError, "#{self.class}#clear! not implemented"
+      end
+    end
+  end
+end

data/packages/igniter-app/lib/igniter/ignite/stores/file_store.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+module Igniter
+  module Ignite
+    module Stores
+      class FileStore < Store
+        attr_reader :path, :max_events, :archive_path
+
+        def initialize(path:, max_events: nil, archive_path: nil)
+          @path = path
+          @max_events = max_events&.to_i
+          @archive_path = archive_path
+          FileUtils.mkdir_p(File.dirname(path))
+          FileUtils.mkdir_p(File.dirname(archive_path)) if archive_path
+        end
+
+        def append(event)
+          File.open(path, "a") do |file|
+            file.puts(JSON.generate(event))
+          end
+          rotate_if_needed!
+          event
+        end
+
+        def load_events
+          return [] unless File.exist?(path)
+
+          File.readlines(path, chomp: true).filter_map do |line|
+            next if line.strip.empty?
+
+            deep_symbolize(JSON.parse(line))
+          rescue JSON::ParserError
+            next
+          end
+        end
+
+        def clear!
+          FileUtils.rm_f(path)
+          FileUtils.rm_f(archive_path) if archive_path
+          self
+        end
+
+        def retained_limit
+          max_events
+        end
+
+        def prune_events(events)
+          return Array(events) unless max_events && max_events.positive?
+          return Array(events) if events.size <= max_events
+
+          Array(events).last(max_events).map { |event| deep_symbolize(event) }
+        end
+
+        def persistence_metadata
+          {
+            enabled: true,
+            store_class: self.class.name,
+            path: path,
+            max_events: max_events,
+            archive_path: archive_path,
+            archived_events: archived_events_count
+          }.compact
+        end
+
+        private
+
+        def deep_symbolize(value)
+          case value
+          when Hash
+            value.each_with_object({}) do |(key, nested), memo|
+              memo[key.to_sym] = deep_symbolize(nested)
+            end
+          when Array
+            value.map { |item| deep_symbolize(item) }
+          else
+            value
+          end
+        end
+
+        def rotate_if_needed!
+          return unless max_events && max_events.positive?
+          return unless File.exist?(path)
+
+          lines = File.readlines(path, chomp: true)
+          return if lines.size <= max_events
+
+          overflow = lines.first(lines.size - max_events)
+          retained = lines.last(max_events)
+          append_archive_lines(overflow)
+          File.write(path, retained.empty? ? "" : "#{retained.join("\n")}\n")
+        end
+
+        def append_archive_lines(lines)
+          return if lines.empty? || archive_path.nil?
+
+          File.open(archive_path, "a") do |file|
+            lines.each { |line| file.puts(line) }
+          end
+        end
+
+        def archived_events_count
+          return 0 unless archive_path && File.exist?(archive_path)
+
+          File.foreach(archive_path).count
+        end
+      end
+    end
+  end
+end

data/packages/igniter-app/lib/igniter/ignite/trail.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "set"
+require "time"
+
+module Igniter
+  module Ignite
+    class Trail
+      attr_reader :store
+
+      def initialize(store: nil, clock: -> { Time.now.utc.iso8601 })
+        @store = store
+        @clock = clock
+        @events = Array(store&.load_events).map { |event| normalize_loaded_event(event).freeze }
+        @report_signatures = Set.new
+        seed_report_signatures!
+      end
+
+      def record(type, source:, payload: {})
+        event = {
+          event_id: SecureRandom.uuid,
+          type: type.to_sym,
+          source: source.to_sym,
+          timestamp: @clock.call,
+          payload: deep_dup(payload)
+        }.freeze
+
+        @events << event
+        store&.append(event)
+        prune_retained_events!
+        event
+      end
+
+      def ingest_report(report, source:)
+        Array(report.events).each do |event|
+          signature = report_signature(report.plan_id, event)
+          next if @report_signatures.include?(signature)
+
+          record(
+            event.fetch(:type),
+            source: source,
+            payload: event.merge(
+              plan_id: report.plan_id,
+              report_status: report.status,
+              report_strategy: report.strategy,
+              report_approval_mode: report.approval_mode,
+              report_signature: signature
+            )
+          )
+          @report_signatures << signature
+        end
+
+        Array(report.entries).each do |entry|
+          signature = target_snapshot_signature(report.plan_id, entry, report.status)
+          next if @report_signatures.include?(signature)
+
+          record(
+            :ignition_target_snapshot,
+            source: source,
+            payload: entry.merge(
+              plan_id: report.plan_id,
+              report_status: report.status,
+              report_strategy: report.strategy,
+              report_approval_mode: report.approval_mode,
+              report_signature: signature
+            )
+          )
+          @report_signatures << signature
+        end
+
+        record(
+          :ignition_report_snapshot,
+          source: source,
+          payload: {
+            plan_id: report.plan_id,
+            report_status: report.status,
+            report: deep_dup(report.to_h),
+            summary: deep_dup(report.summary),
+            total_report_events: report.events.size
+          }
+        )
+      end
+
+      def events(limit: nil)
+        selected = limit ? @events.last(limit) : @events
+        selected.map(&:dup)
+      end
+
+      def snapshot(limit: 10)
+        selected = events(limit: limit)
+
+        {
+          total: @events.size,
+          latest_type: @events.last&.dig(:type),
+          latest_at: @events.last&.dig(:timestamp),
+          by_type: @events.each_with_object(Hash.new(0)) { |event, memo| memo[event[:type]] += 1 },
+          by_target: counts_by_target,
+          persistence: persistence_metadata,
+          events: selected
+        }
+      end
+
+      def clear!
+        @events.clear
+        @report_signatures.clear
+        store&.clear!
+        self
+      end
+
+      def latest_report
+        payload = @events.reverse_each.lazy
+                         .filter_map { |event| event.dig(:payload, :report) if event[:type] == :ignition_report_snapshot }
+                         .first
+        return nil unless payload
+
+        IgnitionReport.new(
+          plan_id: payload.fetch(:plan_id),
+          status: payload.fetch(:status),
+          strategy: payload.fetch(:strategy),
+          approval_mode: payload.fetch(:approval_mode),
+          entries: payload.fetch(:entries),
+          events: payload.fetch(:events),
+          summary: payload.fetch(:summary)
+        )
+      end
+
+      private
+
+      def report_signature(plan_id, event)
+        [
+          plan_id.to_s,
+          event[:type].to_s,
+          event[:target_id].to_s,
+          event[:intent_id].to_s,
+          event[:timestamp].to_s
+        ].join("|")
+      end
+
+      def target_snapshot_signature(plan_id, entry, report_status)
+        [
+          "target_snapshot",
+          plan_id.to_s,
+          entry[:target_id].to_s,
+          entry[:status].to_s,
+          entry[:action].to_s,
+          entry.dig(:admission, :status).to_s,
+          entry.dig(:join, :status).to_s,
+          report_status.to_s
+        ].join("|")
+      end
+
+      def seed_report_signatures!
+        @events.each do |event|
+          signature = event.dig(:payload, :report_signature)
+          @report_signatures << signature if signature
+        end
+      end
+
+      def counts_by_target
+        @events.each_with_object(Hash.new(0)) do |event, memo|
+          target_id = event.dig(:payload, :target_id)
+          next unless target_id
+
+          memo[target_id] += 1
+        end
+      end
+
+      def deep_dup(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, nested), memo|
+            memo[key] = deep_dup(nested)
+          end
+        when Array
+          value.map { |item| deep_dup(item) }
+        else
+          value
+        end
+      end
+
+      def normalize_loaded_event(event)
+        loaded = deep_dup(event)
+        loaded[:type] = loaded[:type]&.to_sym
+        loaded[:source] = loaded[:source]&.to_sym
+        loaded
+      end
+
+      def persistence_metadata
+        return { enabled: false } unless store
+
+        return store.persistence_metadata if store.respond_to?(:persistence_metadata)
+
+        {
+          enabled: true,
+          store_class: store.class.name,
+          path: store.respond_to?(:path) ? store.path : nil
+        }.compact
+      end
+
+      def prune_retained_events!
+        if store&.respond_to?(:prune_events)
+          @events = store.prune_events(@events).map(&:freeze)
+          return
+        end
+
+        limit = store&.respond_to?(:retained_limit) ? store.retained_limit : nil
+        return unless limit && limit.positive?
+        return if @events.size <= limit
+
+        @events.shift(@events.size - limit)
+      end
+    end
+  end
+end

data/packages/igniter-app/lib/igniter/ignite.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "ignite/bootstrap_target"
+require_relative "ignite/bootstrap_agent"
+require_relative "ignite/deployment_intent"
+require_relative "ignite/ignition_plan"
+require_relative "ignite/ignition_report"
+require_relative "ignite/ignition_agent"
+require_relative "ignite/store"
+require_relative "ignite/stores/file_store"
+require_relative "ignite/trail"

data/packages/igniter-app/lib/igniter-app.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "igniter/ignite"
+require_relative "igniter/app"
+require_relative "igniter/app/generator"

data/packages/igniter-cluster/README.md

@@ -0,0 +1,9 @@
+# igniter-cluster
+
+Local monorepo gem for Igniter's cluster, mesh, trust, and replication layer.
+
+Docs:
+
+- [Guide](../../docs/guide/README.md)
+- [Cluster guide](../../docs/guide/cluster.md)
+- [Dev](../../docs/dev/README.md)

data/packages/igniter-cluster/lib/igniter/cluster/agent_route_resolver.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    # Mesh-aware route resolver for agent nodes.
+    class AgentRouteResolver < Igniter::Runtime::AgentRouteResolver
+      def resolve(node:, execution: nil) # rubocop:disable Lint/UnusedMethodArgument
+        case node.routing_mode
+        when :capability
+          resolve_capability_route(node)
+        when :pinned
+          resolve_pinned_route(node)
+        else
+          super
+        end
+      end
+
+      private
+
+      def resolve_capability_route(node)
+        query = node.capability_query || { all_of: [node.capability] }
+        deferred = Igniter::Runtime::DeferredResult.build(
+          payload: {
+            via: node.agent_name,
+            message: node.message_name,
+            capability: node.capability,
+            query: query
+          },
+          source_node: node.name,
+          waiting_on: node.name
+        )
+        url =
+          if node.capability_query
+            Igniter::Cluster::Mesh.router.find_peer_for_query(node.capability_query, deferred)
+          else
+            Igniter::Cluster::Mesh.router.find_peer_for(node.capability, deferred)
+          end
+
+        Igniter::Runtime::AgentRoute.static(
+          via: node.agent_name,
+          message: node.message_name,
+          url: url,
+          capability: node.capability,
+          query: node.capability_query || query
+        )
+      end
+
+      def resolve_pinned_route(node)
+        Igniter::Runtime::AgentRoute.static(
+          via: node.agent_name,
+          message: node.message_name,
+          url: Igniter::Cluster::Mesh.router.resolve_pinned(node.pinned_to),
+          pinned_to: node.pinned_to
+        )
+      end
+    end
+  end
+end

data/{lib/igniter → packages/igniter-cluster/lib/igniter/cluster}/consensus/cluster.rb

@@ -1,13 +1,14 @@
 # frozen_string_literal: true
 
 module Igniter
-  module Consensus
+  module Cluster
+    module Consensus
     # Manages a consensus cluster: node lifecycle, leader discovery,
     # high-level read/write, quorum checks, and Igniter::Contract integration.
     #
     # == Quick start (default KV state machine)
     #
-    #   cluster = Igniter::Consensus::Cluster.start(nodes: %i[n1 n2 n3 n4 n5])
+    #   cluster = Igniter::Cluster::Consensus::Cluster.start(nodes: %i[n1 n2 n3 n4 n5])
     #   cluster.wait_for_leader
     #   cluster.write(key: :price, value: 99)
     #   cluster.read(:price)   # => 99
@@ -15,12 +16,12 @@ module Igniter
     #
     # == Custom state machine
     #
-    #   class OrderBook < Igniter::Consensus::StateMachine
+    #   class OrderBook < Igniter::Cluster::Consensus::StateMachine
     #     apply :add    do |state, cmd| state.merge(cmd[:id] => cmd[:data]) end
     #     apply :cancel do |state, cmd| state.reject { |k, _| k == cmd[:id] } end
     #   end
     #
-    #   cluster = Igniter::Consensus::Cluster.start(
+    #   cluster = Igniter::Cluster::Consensus::Cluster.start(
     #     nodes: %i[n1 n2 n3 n4 n5],
     #     state_machine: OrderBook,
     #   )
@@ -112,6 +113,8 @@ module Igniter
       #
       # @raise [NoLeaderError] if no leader is currently available
       def write(command = {})
+        raise NoLeaderError, "No quorum available — cluster cannot commit writes" unless has_quorum?
+
         ref = leader
         raise NoLeaderError, "No leader available — cluster may be electing or lacks quorum" unless ref
         ref.send(:client_write, command: command)
@@ -179,5 +182,6 @@ module Igniter
         end
       end
     end
+    end
   end
 end