igniter 0.4.5 → 0.5.1

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/packages/igniter-core/lib/igniter/core/node_cache.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Igniter
+  # Cross-execution TTL cache and request coalescing for compute nodes.
+  #
+  # Activated per-node via the `cache_ttl:` and `coalesce:` options on `compute`:
+  #
+  #   compute :available_slots, with: [...], call: CheckAvailability,
+  #           cache_ttl: 60,     # seconds — reuse result across executions
+  #           coalesce: true     # deduplicate concurrent in-flight requests
+  #
+  # == Setup
+  #
+  #   require "igniter/core/node_cache"
+  #   Igniter::NodeCache.cache = Igniter::NodeCache::Memory.new
+  #   Igniter::NodeCache.coalescing_lock = Igniter::NodeCache::CoalescingLock.new
+  #
+  # Or via the configure block:
+  #
+  #   Igniter.configure do |c|
+  #     c.node_cache = Igniter::NodeCache::Memory.new
+  #     c.node_coalescing = true   # auto-creates a CoalescingLock
+  #   end
+  #
+  # == AR fingerprinting (Gap 3)
+  #
+  # Cache keys are built from a stable fingerprint of dep values.
+  # For ActiveRecord objects, include Igniter::Fingerprint (or use the Railtie):
+  #
+  #   class Trade < ApplicationRecord
+  #     include Igniter::Fingerprint
+  #     # default: "Trade:42:1712345678"
+  #   end
+  module NodeCache
+    class << self
+      # Global TTL cache backend. nil = disabled (default).
+      # Must respond to: #fetch(key) → value | nil
+      #                  #store(key, value, ttl:)
+      attr_accessor :cache
+
+      # Global coalescing lock. nil = disabled (default).
+      attr_accessor :coalescing_lock
+    end
+
+    # ─── Cache key ────────────────────────────────────────────────────────────
+
+    # Immutable key uniquely identifying a node result for a given set of dep values.
+    # Format: "ttl:{contract_name}:{node_name}:{dep_fingerprint_hex}"
+    class CacheKey
+      attr_reader :hex
+
+      def initialize(contract_name, node_name, dep_hex)
+        @hex = "ttl:#{contract_name}:#{node_name}:#{dep_hex}".freeze
+        freeze
+      end
+
+      def to_s    = @hex
+      def inspect = "#<NodeCache::CacheKey #{@hex}>"
+      def ==(other) = other.is_a?(CacheKey) && other.hex == @hex
+    end
+
+    # ─── Memory backend ───────────────────────────────────────────────────────
+
+    # Thread-safe in-process TTL store. Entries expire after their TTL.
+    # Replace with a Redis-backed implementation for multi-process sharing.
+    class Memory
+      Entry = Struct.new(:value, :expires_at) do
+        def expired? = Time.now.utc > expires_at
+      end
+
+      def initialize
+        @store  = {}
+        @mu     = Mutex.new
+        @hits   = 0
+        @misses = 0
+      end
+
+      # Returns the cached value, or nil on miss / expiry.
+      def fetch(key)
+        @mu.synchronize do
+          entry = @store[key.hex]
+          if entry.nil? || entry.expired?
+            @store.delete(key.hex) if entry
+            @misses += 1
+            nil
+          else
+            @hits += 1
+            entry.value
+          end
+        end
+      end
+
+      # Stores value with a TTL in seconds.
+      def store(key, value, ttl:)
+        @mu.synchronize do
+          @store[key.hex] = Entry.new(value, Time.now.utc + ttl)
+        end
+        value
+      end
+
+      # Remove all expired entries. Call periodically to reclaim memory.
+      def prune!
+        @mu.synchronize do
+          now = Time.now.utc
+          @store.delete_if { |_, e| e.expires_at < now }
+        end
+      end
+
+      def size  = @mu.synchronize { @store.size }
+      def clear = @mu.synchronize { @store.clear; @hits = 0; @misses = 0 }
+      def stats = @mu.synchronize { { size: @store.size, hits: @hits, misses: @misses } }
+    end
+
+    # ─── Coalescing lock ──────────────────────────────────────────────────────
+
+    # In-flight deduplication for concurrent requests with identical dep fingerprints.
+    #
+    # When two executions race to compute the same `coalesce: true` node:
+    #   • The first caller becomes the leader — computes and stores the result.
+    #   • Subsequent callers become followers — wait for the leader, then reuse its result.
+    #
+    # This eliminates duplicate work for concurrent auction-style requests
+    # (e.g. 3 vendors arriving within ~50ms for the same lead).
+    #
+    # Scope: single Ruby process. For Puma multi-worker, extend with a Redis-based
+    # implementation using SETNX advisory locks + Pub/Sub.
+    class CoalescingLock
+      WAIT_TIMEOUT = 30 # seconds before a follower gives up and computes independently
+
+      InFlight = Struct.new(:mutex, :cond, :done, :value, :error, keyword_init: true)
+
+      def initialize
+        @mu      = Mutex.new
+        @flights = {}
+      end
+
+      # Attempt to acquire a computation slot for `hex`.
+      #
+      # Returns [:leader, flight]   — caller is first; must compute then call finish!
+      # Returns [:follower, flight] — another caller is already computing; call wait(flight)
+      def acquire(hex)
+        @mu.synchronize do
+          if @flights.key?(hex)
+            [:follower, @flights[hex]]
+          else
+            flight = InFlight.new(
+              mutex: Mutex.new,
+              cond:  ConditionVariable.new,
+              done:  false,
+              value: nil,
+              error: nil
+            )
+            @flights[hex] = flight
+            [:leader, flight]
+          end
+        end
+      end
+
+      # Called by the leader when computation finishes (success or failure).
+      # Unblocks all waiting followers.
+      def finish!(hex, value: nil, error: nil)
+        flight = @mu.synchronize { @flights.delete(hex) }
+        return unless flight
+
+        flight.mutex.synchronize do
+          flight.value = value
+          flight.error = error
+          flight.done  = true
+          flight.cond.broadcast
+        end
+      end
+
+      # Called by a follower after receiving the flight object from acquire.
+      # Blocks until the leader calls finish!, then returns [value, error].
+      # Times out after WAIT_TIMEOUT seconds and returns [nil, nil] (follower recomputes).
+      def wait(flight)
+        flight.mutex.synchronize do
+          deadline = Time.now + WAIT_TIMEOUT
+          until flight.done
+            remaining = deadline - Time.now
+            break if remaining <= 0
+
+            flight.cond.wait(flight.mutex, remaining)
+          end
+          [flight.value, flight.error]
+        end
+      end
+
+      def in_flight_count = @mu.synchronize { @flights.size }
+    end
+
+    # ─── Fingerprinter ────────────────────────────────────────────────────────
+
+    # Produces a stable hex fingerprint for a set of dependency values.
+    # Used as part of the NodeCache::CacheKey.
+    #
+    # Supports the Igniter::Fingerprint protocol:
+    #   objects responding to #igniter_fingerprint return a stable string
+    #   (e.g. "Trade:42:1712345678").
+    #
+    # Fallback for unknown objects: "#ClassName@object_id" — stable within
+    # a single process but NOT across restarts. Sufficient for the in-process
+    # Memory backend; Redis-backed deployments should ensure all dep objects
+    # implement igniter_fingerprint.
+    module Fingerprinter
+      def self.call(dep_values)
+        Digest::SHA256.hexdigest(serialize(dep_values))[0..23]
+      end
+
+      def self.serialize(val) # rubocop:disable Metrics/CyclomaticComplexity
+        case val
+        when Hash
+          pairs = val.sort_by { |k, _| k.to_s }.map { |k, v| "#{k}:#{serialize(v)}" }
+          "{#{pairs.join(",")}}"
+        when Array  then "[#{val.map { |v| serialize(v) }.join(",")}]"
+        when String then val.inspect
+        when Symbol then ":#{val}"
+        when Numeric, NilClass, TrueClass, FalseClass then val.inspect
+        else
+          if val.respond_to?(:igniter_fingerprint)
+            "fp:#{val.igniter_fingerprint}"
+          else
+            "obj:#{val.class.name}@#{val.object_id}"
+          end
+        end
+      end
+    end
+  end
+end

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