igniter 0.5.0 → 0.5.1

data/{lib/igniter → packages/igniter-core/lib/igniter/core}/model/branch_node.rb

@@ -29,6 +29,16 @@ module Igniter
         (cases.map { |entry| entry[:contract] } + [default_contract]).uniq
       end
 
+      def match_case(selector_value)
+        cases.find { |entry| case_matches?(entry, selector_value) }
+      end
+
+      def case_payload(entry)
+        return entry[:value] if entry[:matcher] == :eq
+
+        entry[:value].inspect
+      end
+
       def input_mapper?
         !input_mapper.nil?
       end
@@ -36,11 +46,37 @@ module Igniter
       private
 
       def normalize_case(entry)
+        matcher = (entry[:matcher] || :eq).to_sym
+        value = entry.key?(:value) ? entry[:value] : entry[:match]
+
         {
-          match: entry.fetch(:match),
+          matcher: matcher,
+          value: normalize_case_value(matcher, value),
           contract: entry.fetch(:contract)
         }
       end
+
+      def normalize_case_value(matcher, value)
+        case matcher
+        when :in
+          Array(value).freeze
+        else
+          value
+        end
+      end
+
+      def case_matches?(entry, selector_value)
+        case entry[:matcher]
+        when :eq
+          entry[:value] == selector_value
+        when :in
+          entry[:value].include?(selector_value)
+        when :matches
+          entry[:value].match?(selector_value.to_s)
+        else
+          false
+        end
+      end
     end
   end
 end

data/packages/igniter-core/lib/igniter/core/model/remote_node.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Model
+    # Represents a node that executes a contract on a remote igniter-stack node.
+    # The result is the outputs hash returned by the remote contract.
+    #
+    # Three routing modes:
+    #   :static     — node_url is a hard-coded URL (original behaviour)
+    #   :capability — auto-select an alive peer via capability shorthand or query
+    #   :pinned     — must use the specific named peer; IncidentError if down
+    class RemoteNode < Node
+      SYMBOL_LIST_KEYS = %i[
+        all_of any_of none_of tags
+        allows denies requires_approval
+        permits approvable forbidden
+        actions risky
+      ].freeze
+      SYMBOL_SCALAR_KEYS = %i[name direction nulls mode identity attestation governance trust latest_type].freeze
+
+      attr_reader :contract_name, :node_url, :input_mapping, :timeout,
+                  :capability, :capability_query, :pinned_to
+
+      def initialize(id:, name:, contract_name:, input_mapping:, # rubocop:disable Metrics/ParameterLists, Metrics/MethodLength
+                     node_url: "", timeout: 30, path: nil, metadata: {},
+                     capability: nil, capability_query: nil, pinned_to: nil)
+        super(
+          id: id,
+          kind: :remote,
+          name: name,
+          path: path || name.to_s,
+          dependencies: input_mapping.values.map(&:to_sym),
+          metadata: metadata
+        )
+        @contract_name = contract_name.to_s
+        @node_url      = node_url.to_s
+        @input_mapping = input_mapping.transform_keys(&:to_sym).transform_values(&:to_sym).freeze
+        @timeout       = Integer(timeout)
+        @capability    = capability&.to_sym
+        @capability_query = normalize_query(capability_query)
+        @pinned_to     = pinned_to&.to_s
+      end
+
+      # Returns :static, :capability, or :pinned.
+      def routing_mode
+        return :pinned     if @pinned_to
+        return :capability if @capability || @capability_query
+
+        :static
+      end
+
+      private
+
+      def normalize_query(query)
+        case query
+        when nil
+          nil
+        when Symbol, String
+          { all_of: [query.to_sym] }.freeze
+        when Array
+          { all_of: query.map(&:to_sym).freeze }.freeze
+        when Hash
+          normalize_query_hash(query).freeze
+        else
+          query
+        end
+      end
+
+      def normalize_query_hash(hash)
+        hash.each_with_object({}) do |(key, value), memo|
+          normalized_key = key.to_sym
+          memo[normalized_key] = normalize_query_value(normalized_key, value)
+        end
+      end
+
+      def normalize_query_value(key, value)
+        if SYMBOL_LIST_KEYS.include?(key)
+          Array(value).map { |item| item.is_a?(String) || item.is_a?(Symbol) ? item.to_sym : item }.freeze
+        elsif SYMBOL_SCALAR_KEYS.include?(key) && (value.is_a?(String) || value.is_a?(Symbol))
+          value.to_sym
+        elsif value.is_a?(Hash)
+          normalize_query_hash(value).freeze
+        elsif value.is_a?(Array)
+          value.map { |item| item.is_a?(Hash) ? normalize_query_hash(item).freeze : item }.freeze
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/{lib/igniter → packages/igniter-core/lib/igniter/core}/model.rb

@@ -10,6 +10,8 @@ require_relative "model/collection_node"
 require_relative "model/output_node"
 require_relative "model/await_node"
 require_relative "model/remote_node"
+require_relative "model/agent_interaction_contract"
+require_relative "model/agent_node"
 require_relative "model/effect_node"
 
 module Igniter

data/{lib/igniter → packages/igniter-core/lib/igniter/core}/node_cache.rb

@@ -13,7 +13,7 @@ module Igniter
   #
   # == Setup
   #
-  #   require "igniter/node_cache"
+  #   require "igniter/core/node_cache"
   #   Igniter::NodeCache.cache = Igniter::NodeCache::Memory.new
   #   Igniter::NodeCache.coalescing_lock = Igniter::NodeCache::CoalescingLock.new
   #

data/{lib/igniter → packages/igniter-core/lib/igniter/core}/property_testing.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
-require "igniter"
-require "igniter/extensions/invariants"
-require "igniter/property_testing/generators"
-require "igniter/property_testing/run"
-require "igniter/property_testing/result"
-require "igniter/property_testing/formatter"
-require "igniter/property_testing/runner"
+require_relative "contract"
+require_relative "extensions/invariants"
+require_relative "property_testing/generators"
+require_relative "property_testing/run"
+require_relative "property_testing/result"
+require_relative "property_testing/formatter"
+require_relative "property_testing/runner"
 
 module Igniter
   # Property-based testing for Igniter contracts.
@@ -16,7 +16,7 @@ module Igniter
   # as data so you can inspect the first counterexample.
   #
   # @example
-  #   require "igniter/property_testing"
+  #   require "igniter/core/property_testing"
   #
   #   G = Igniter::PropertyTesting::Generators
   #

data/{lib/igniter → packages/igniter-core/lib/igniter/core}/provenance/builder.rb

@@ -80,14 +80,43 @@ module Igniter
       def extract_value(state) # rubocop:disable Metrics/MethodLength
         return nil unless state
 
+        if state.failed?
+          return {
+            failed: true,
+            error: {
+              type: state.error.class.name,
+              message: state.error.message,
+              context: state.error.respond_to?(:context) ? state.error.context : {}
+            }
+          }
+        end
+
         val = state.value
         case val
+        when Runtime::StreamResult
+          {
+            pending: true,
+            stream: true,
+            event: val.waiting_on,
+            phase: val.phase,
+            events: val.events,
+            chunks: val.chunks,
+            payload: val.payload,
+            routing_trace: val.routing_trace,
+            agent_trace: val.agent_trace
+          }.compact
         when Runtime::Result
           val.to_h
         when Runtime::CollectionResult
           val.summary
         when Runtime::DeferredResult
-          { pending: true, event: val.waiting_on }
+          {
+            pending: true,
+            event: val.waiting_on,
+            payload: val.payload,
+            routing_trace: val.routing_trace,
+            agent_trace: val.agent_trace
+          }.compact
         else
           val
         end

data/packages/igniter-core/lib/igniter/core/runtime/agent_adapter.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Runtime
+    # Base transport seam for agent nodes.
+    #
+    # Core runtime delegates agent-node delivery to this adapter instead of
+    # directly depending on the actor runtime package.
+    class AgentAdapter
+      def call(node:, inputs:, execution: nil) # rubocop:disable Lint/UnusedMethodArgument
+        raise ResolutionError,
+              "agent :#{node.name} requires a configured agent adapter. " \
+              "Require 'igniter/agent', pass `runner :inline, agent_adapter: ...`, " \
+              "or set `Igniter::Runtime.agent_adapter`."
+      end
+
+      def cast(node:, inputs:, execution: nil) # rubocop:disable Lint/UnusedMethodArgument
+        raise ResolutionError,
+              "agent :#{node.name} requires a configured agent adapter. " \
+              "Require 'igniter/agent', pass `runner :inline, agent_adapter: ...`, " \
+              "or set `Igniter::Runtime.agent_adapter`."
+      end
+
+      def continue_session(session:, payload:, execution: nil, trace: nil, token: nil, waiting_on: nil, request: nil, reply: nil, phase: nil) # rubocop:disable Metrics/ParameterLists, Lint/UnusedMethodArgument
+        nil
+      end
+
+      def resume_session(session:, execution: nil, value: nil) # rubocop:disable Lint/UnusedMethodArgument
+        nil
+      end
+    end
+
+    class << self
+      attr_writer :agent_adapter
+
+      def agent_adapter
+        @agent_adapter ||= AgentAdapter.new
+      end
+    end
+  end
+end

data/packages/igniter-core/lib/igniter/core/runtime/agent_result_contract.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Runtime
+    class AgentResultContract
+      attr_reader :kind, :waiting_on, :source_node, :session_lifecycle_state, :phase,
+                  :interaction_contract, :tool_runtime, :ownership, :owner_url,
+                  :delivery_route, :interactive, :terminal, :continuable, :routed
+
+      def self.from_result(result, kind:)
+        session = result.session if result.respond_to?(:session)
+        trace = result.agent_trace if result.respond_to?(:agent_trace)
+        return nil unless session || trace
+
+        new(
+          kind: kind,
+          waiting_on: result.waiting_on,
+          source_node: result.source_node,
+          session_lifecycle_state: session&.lifecycle_state,
+          phase: session&.phase,
+          interaction_contract: session&.interaction_contract&.to_h,
+          tool_runtime: session&.tool_runtime,
+          ownership: session&.ownership,
+          owner_url: session&.owner_url,
+          delivery_route: session&.delivery_route,
+          interactive: session ? session.interactive? : false,
+          terminal: session ? session.terminal? : false,
+          continuable: session ? session.continuable? : false,
+          routed: session ? session.routed? : trace_routed?(trace)
+        )
+      end
+
+      def initialize(kind:, waiting_on:, source_node:, session_lifecycle_state:, phase:, # rubocop:disable Metrics/ParameterLists
+                     interaction_contract:, tool_runtime:, ownership:, owner_url:,
+                     delivery_route:, interactive:, terminal:, continuable:, routed:)
+        @kind = kind&.to_sym
+        @waiting_on = waiting_on&.to_sym
+        @source_node = source_node&.to_sym
+        @session_lifecycle_state = session_lifecycle_state&.to_sym
+        @phase = phase&.to_sym
+        @interaction_contract = interaction_contract&.dup&.freeze
+        @tool_runtime = tool_runtime&.dup&.freeze
+        @ownership = ownership&.to_sym
+        @owner_url = owner_url&.to_s
+        @delivery_route = delivery_route&.dup&.freeze
+        @interactive = !!interactive
+        @terminal = !!terminal
+        @continuable = !!continuable
+        @routed = !!routed
+        freeze
+      end
+
+      def deferred?
+        kind == :deferred
+      end
+
+      def stream?
+        kind == :stream
+      end
+
+      def to_h
+        {
+          kind: kind,
+          waiting_on: waiting_on,
+          source_node: source_node,
+          session_lifecycle_state: session_lifecycle_state,
+          phase: phase,
+          interaction_contract: interaction_contract,
+          tool_runtime: tool_runtime,
+          ownership: ownership,
+          owner_url: owner_url,
+          delivery_route: delivery_route,
+          interactive: interactive,
+          terminal: terminal,
+          continuable: continuable,
+          routed: routed
+        }.compact.freeze
+      end
+
+      private
+
+      def self.trace_routed?(trace)
+        return false unless trace.is_a?(Hash)
+
+        %i[node capability query pinned_to url peer_url].any? do |key|
+          trace.key?(key) || trace.key?(key.to_s)
+        end
+      end
+    end
+  end
+end

data/packages/igniter-core/lib/igniter/core/runtime/agent_route.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Runtime
+    # Immutable delivery route for an agent node.
+    class AgentRoute
+      attr_reader :routing_mode, :via, :message, :url, :capability, :query, :pinned_to, :metadata
+
+      def initialize(routing_mode:, via:, message:, url: nil, capability: nil, query: nil, pinned_to: nil, metadata: {})
+        @routing_mode = routing_mode.to_sym
+        @via = via&.to_sym
+        @message = message&.to_sym
+        @url = url&.to_s
+        @capability = capability&.to_sym
+        @query = query&.dup&.freeze
+        @pinned_to = pinned_to&.to_s
+        @metadata = metadata.dup.freeze
+        freeze
+      end
+
+      def self.local(via:, message:, metadata: {})
+        new(routing_mode: :local, via: via, message: message, metadata: metadata)
+      end
+
+      def self.static(via:, message:, url:, capability: nil, query: nil, pinned_to: nil, metadata: {})
+        new(
+          routing_mode: :static,
+          via: via,
+          message: message,
+          url: url,
+          capability: capability,
+          query: query,
+          pinned_to: pinned_to,
+          metadata: metadata
+        )
+      end
+
+      def local?
+        routing_mode == :local
+      end
+
+      def remote?
+        !local?
+      end
+
+      def to_h
+        {
+          routing_mode: routing_mode,
+          via: via,
+          message: message,
+          url: url,
+          capability: capability,
+          query: query,
+          pinned_to: pinned_to,
+          metadata: metadata
+        }.reject { |_key, value| value.nil? || value == {} }
+      end
+    end
+  end
+end

data/packages/igniter-core/lib/igniter/core/runtime/agent_route_resolver.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "agent_route"
+
+module Igniter
+  module Runtime
+    # Resolves an agent node into a concrete delivery route.
+    class AgentRouteResolver
+      def resolve(node:, execution: nil) # rubocop:disable Lint/UnusedMethodArgument
+        case node.routing_mode
+        when :local
+          AgentRoute.local(via: node.agent_name, message: node.message_name)
+        when :static
+          AgentRoute.static(
+            via: node.agent_name,
+            message: node.message_name,
+            url: node.node_url
+          )
+        else
+          raise ResolutionError,
+                "agent :#{node.name} uses #{node.routing_mode} routing — add `require 'igniter/cluster'`"
+        end
+      end
+    end
+  end
+end