smith-agents 0.4.5 → 0.5.0

data/lib/smith/workflow/transition.rb

@@ -9,53 +9,61 @@ module Smith
                   :deterministic_routes
 
       def initialize(name, from:, to:, &)
-        @name = name
-        @from = from
-        @to = to
+        @name = own_identifier(name)
+        @from = own_identifier(from, allow_nil: true)
+        @to = own_identifier(to)
         instance_eval(&) if block_given?
       end
 
       def execute(agent_name, **opts)
-        validate_execute_conflicts!
+        validate_execution_primitive_conflict!("execute")
 
-        @agent_name = agent_name
-        @agent_opts = opts
+        normalized_agent = normalize_agent_reference!(agent_name, "agent")
+        validate_parallel_options!(opts)
+
+        @agent_name = normalized_agent
+        @agent_opts = opts.freeze
+        commit_execution_primitive!("execute")
       end
 
       def on_success(transition_name)
-        @success_transition = transition_name
+        if routed?
+          raise WorkflowError, "routed transitions cannot declare on_success; router routes select the next transition"
+        end
+
+        @success_transition = own_identifier(transition_name)
       end
 
       def on_failure(transition_name)
-        @failure_transition = transition_name
+        @failure_transition = own_identifier(transition_name)
       end
 
       def route(agent_name, routes:, confidence_threshold:, fallback:)
-        validate_route_conflicts!
+        validate_execution_primitive_conflict!("route")
+        if @success_transition
+          raise WorkflowError, "routed transitions cannot declare on_success; router routes select the next transition"
+        end
 
-        @agent_name = normalize_agent_name!(agent_name, "router")
-        @router_config = {
+        normalized_agent = normalize_agent_name!(agent_name, "router")
+        normalized_config = {
           routes: normalize_router_routes!(routes),
           confidence_threshold: normalize_confidence_threshold!(confidence_threshold),
           fallback: normalize_transition_reference!(fallback, "router fallback")
-        }
+        }.freeze
+
+        @agent_name = normalized_agent
+        @router_config = normalized_config
+        commit_execution_primitive!("route")
       end
 
       def workflow(klass)
         raise WorkflowError, "workflow binding must be a Class" unless klass.is_a?(Class)
         raise WorkflowError, "workflow binding must be a Smith::Workflow subclass" unless klass < Workflow
 
-        validate_conflicts!(
-          "workflow",
-          [
-            ["execute", @agent_name && !@router_config],
-            ["route", @router_config],
-            ["compute/run", @deterministic_block],
-            ["fan_out", @fanout_config]
-          ]
-        )
+        validate_execution_primitive_conflict!("workflow")
 
         @workflow_class = klass
+        commit_execution_primitive!("workflow")
       end
 
       def optimize(generator:, evaluator:, max_rounds:, evaluator_schema:,
@@ -65,57 +73,74 @@ module Smith
                    on_exhaustion: :raise,
                    on_converged: :raise,
                    on_threshold: :raise)
-        validate_optimize_conflicts!
+        validate_execution_primitive_conflict!("optimize")
         validate_optimize_controls!(generator, evaluator, max_rounds, evaluator_schema)
         validate_optimize_exit_modes!(on_exhaustion: on_exhaustion, on_converged: on_converged,
                                       on_threshold: on_threshold)
         validate_optimize_evaluator_context!(evaluator_context)
         validate_optimize_before_eval!(before_eval)
 
-        @optimization_config = {
-          generator: generator, evaluator: evaluator, max_rounds: max_rounds,
+        config = {
+          generator: normalize_agent_reference!(generator, "optimizer generator"),
+          evaluator: normalize_agent_reference!(evaluator, "optimizer evaluator"),
+          max_rounds: max_rounds,
           evaluator_schema: evaluator_schema, improvement_threshold: improvement_threshold,
           evaluator_context: evaluator_context,
           before_eval: before_eval,
           on_exhaustion: on_exhaustion,
           on_converged: on_converged,
           on_threshold: on_threshold
-        }
+        }.freeze
+
+        @optimization_config = config
+        commit_execution_primitive!("optimize")
       end
 
       def orchestrate(**opts)
-        validate_orchestrate_conflicts!
+        validate_execution_primitive_conflict!("orchestrate")
         validate_orchestrate_controls!(opts)
-        @orchestrator_config = opts
+        config = opts.merge(
+          orchestrator: normalize_agent_reference!(opts.fetch(:orchestrator), "orchestrator"),
+          worker: normalize_agent_reference!(opts.fetch(:worker), "orchestrator worker")
+        ).freeze
+
+        @orchestrator_config = config
+        commit_execution_primitive!("orchestrate")
       end
 
       def fan_out(branches:)
-        validate_fanout_conflicts!
+        validate_execution_primitive_conflict!("fan_out")
+
+        config = { branches: normalize_fanout_branches!(branches) }.freeze
 
-        @fanout_config = { branches: normalize_fanout_branches!(branches) }
+        @fanout_config = config
+        commit_execution_primitive!("fan_out")
       end
       alias fanout fan_out
 
       def retry_on(*error_classes, attempts:, backoff: 0, max_delay: nil, jitter: 0)
-        validate_retry_controls!(error_classes, attempts:, backoff:, max_delay:, jitter:)
+        policy = normalize_retry_policy!(error_classes, attempts:, backoff:, max_delay:, jitter:)
 
         @retry_config = {
           error_classes: error_classes.freeze,
-          attempts: attempts,
-          backoff: Float(backoff),
-          max_delay: max_delay.nil? ? nil : Float(max_delay),
-          jitter: Float(jitter)
+          attempts: policy.attempts,
+          backoff: policy.base_delay,
+          max_delay: policy.max_delay,
+          jitter: policy.jitter
         }.freeze
       end
 
       %i[compute run].each do |method_name|
         define_method(method_name) do |routes: nil, &block|
-          validate_deterministic_conflicts!
+          validate_execution_primitive_conflict!("compute/run", declaration: method_name.to_s)
           raise WorkflowError, "#{method_name} requires a block" unless block
 
+          normalized_routes = normalize_deterministic_routes!(routes)
+
           @deterministic_block = block
           @deterministic_kind = method_name
-          @deterministic_routes = normalize_deterministic_routes!(routes)
+          @deterministic_routes = normalized_routes
+          commit_execution_primitive!("compute/run", declaration: method_name.to_s)
         end
       end
 
@@ -149,92 +174,41 @@ module Smith
 
       private
 
-      def validate_execute_conflicts!
-        validate_conflicts!(
-          "execute",
-          [
-            ["compute/run", @deterministic_block],
-            ["fan_out", @fanout_config]
-          ]
-        )
+      def own_identifier(identifier, allow_nil: false)
+        Identifier.normalize(identifier, label: "workflow identifier", allow_nil:)
       end
 
-      def validate_route_conflicts!
-        validate_conflicts!(
-          "route",
-          [
-            ["compute/run", @deterministic_block],
-            ["fan_out", @fanout_config]
-          ]
-        )
+      def normalize_agent_reference!(agent_name, label)
+        Identifier.normalize(agent_name, label: "#{label} agent")
       end
 
-      def validate_deterministic_conflicts!
-        validate_conflicts!(
-          "compute/run",
-          [
-            ["execute", @agent_name && !@router_config],
-            ["route", @router_config],
-            ["workflow", @workflow_class],
-            ["optimize", @optimization_config],
-            ["orchestrate", @orchestrator_config],
-            ["fan_out", @fanout_config]
-          ]
-        )
-        raise WorkflowError, "transition cannot declare both compute and run" if @deterministic_block
-      end
-
-      def validate_optimize_conflicts!
-        validate_conflicts!(
-          "optimize",
-          [
-            ["execute", @agent_name && !@router_config],
-            ["route", @router_config],
-            ["workflow", @workflow_class],
-            ["compute/run", @deterministic_block],
-            ["fan_out", @fanout_config]
-          ]
-        )
-      end
+      def validate_execution_primitive_conflict!(primitive, declaration: primitive)
+        return if @execution_primitive.nil?
 
-      def validate_orchestrate_conflicts!
-        validate_conflicts!(
-          "orchestrate",
-          [
-            ["execute", @agent_name && !@router_config],
-            ["route", @router_config],
-            ["workflow", @workflow_class],
-            ["optimize", @optimization_config],
-            ["compute/run", @deterministic_block],
-            ["fan_out", @fanout_config]
-          ]
-        )
-      end
+        return raise_duplicate_execution_primitive!(declaration) if @execution_primitive == primitive
 
-      def validate_fanout_conflicts!
-        validate_conflicts!(
-          "fan_out",
-          [
-            ["execute", @agent_name && !@router_config],
-            ["route", @router_config],
-            ["workflow", @workflow_class],
-            ["optimize", @optimization_config],
-            ["orchestrate", @orchestrator_config],
-            ["compute/run", @deterministic_block]
-          ]
-        )
+        raise WorkflowError, "transition cannot declare both #{primitive} and #{@execution_primitive}"
       end
 
-      def validate_conflicts!(primitive, conflicts)
-        conflicts.each do |other, present|
-          raise WorkflowError, "transition cannot declare both #{primitive} and #{other}" if present
+      def raise_duplicate_execution_primitive!(declaration)
+        if @execution_primitive == "compute/run" && @execution_declaration != declaration
+          raise WorkflowError, "transition cannot declare both compute and run"
         end
+
+        raise WorkflowError, "transition cannot declare #{declaration} more than once"
+      end
+
+      def commit_execution_primitive!(primitive, declaration: primitive)
+        @execution_primitive = primitive
+        @execution_declaration = declaration
       end
 
       def normalize_fanout_branches!(branches)
         raise WorkflowError, "fan_out branches must be a Hash" unless branches.is_a?(Hash)
         raise WorkflowError, "fan_out requires at least one branch" if branches.empty?
 
+        validate_fanout_size!(branches)
+
         normalized = branches.each_with_object({}) do |(branch_key, agent_name), map|
           key = normalize_fanout_branch_key!(branch_key)
           agent = normalize_fanout_agent_name!(agent_name, key)
@@ -247,11 +221,30 @@ module Smith
         normalized.freeze
       end
 
-      def normalize_agent_name!(agent_name, label)
-        value = agent_name.to_s.strip
-        raise WorkflowError, "#{label} agent must not be blank" if value.empty?
+      def validate_fanout_size!(branches)
+        limit = Smith.config.parallel_branch_limit
+        return if branches.length <= limit
 
-        value.to_sym
+        raise WorkflowError, "fan_out branch count exceeds configured limit #{limit}"
+      end
+
+      def validate_parallel_options!(options)
+        return unless options[:parallel] == true
+
+        count = options[:count]
+        return if count.nil? || count.respond_to?(:call)
+        unless count.is_a?(Integer) && count.positive?
+          raise WorkflowError, "parallel branch count must be a positive integer"
+        end
+
+        limit = Smith.config.parallel_branch_limit
+        return if count <= limit
+
+        raise WorkflowError, "parallel branch count exceeds configured limit #{limit}"
+      end
+
+      def normalize_agent_name!(agent_name, label)
+        normalize_agent_reference!(agent_name, label).to_sym
       end
 
       def normalize_router_routes!(routes)
@@ -275,7 +268,7 @@ module Smith
 
       def normalize_confidence_threshold!(threshold)
         numeric = Float(threshold)
-        return numeric if numeric >= 0.0 && numeric <= 1.0
+        return numeric if numeric.between?(0.0, 1.0)
 
         raise WorkflowError, "router confidence_threshold must be a number in 0.0..1.0"
       rescue TypeError, ArgumentError
@@ -306,10 +299,11 @@ module Smith
       end
 
       def normalize_fanout_agent_name!(agent_name, branch_key)
-        value = agent_name.to_s.strip
-        raise WorkflowError, "fan_out branch #{branch_key.inspect} must declare an agent" if value.empty?
+        if [String, Symbol].any? { agent_name.is_a?(_1) } && agent_name.to_s.strip.empty?
+          raise WorkflowError, "fan_out branch #{branch_key.inspect} must declare an agent"
+        end
 
-        value.to_sym
+        normalize_agent_reference!(agent_name, "fan_out branch #{branch_key.inspect}").to_sym
       end
 
       def validate_distinct_fanout_agents!(branches)
@@ -319,20 +313,22 @@ module Smith
         raise WorkflowError, "fan_out branch agents must be distinct: #{duplicates.map(&:inspect).join(", ")}"
       end
 
-      def validate_retry_controls!(error_classes, attempts:, backoff:, max_delay:, jitter:)
-        unless attempts.is_a?(Integer) && attempts.positive?
-          raise WorkflowError, "retry_on attempts must be a positive integer"
-        end
-
+      def normalize_retry_policy!(error_classes, attempts:, backoff:, max_delay:, jitter:)
         error_classes.each do |error_class|
           next if error_class.is_a?(Class) && error_class <= StandardError
 
           raise WorkflowError, "retry_on error classes must inherit from StandardError"
         end
 
-        validate_non_negative_numeric!(:backoff, backoff)
-        validate_non_negative_numeric!(:jitter, jitter)
-        validate_non_negative_numeric!(:max_delay, max_delay) unless max_delay.nil?
+        ExponentialBackoff.new(
+          attempts:,
+          base_delay: backoff,
+          max_delay:,
+          jitter:,
+          delay_label: "backoff"
+        )
+      rescue ArgumentError => e
+        raise WorkflowError, "retry_on #{e.message}"
       end
 
       def normalize_deterministic_routes!(routes)
@@ -340,10 +336,12 @@ module Smith
         raise WorkflowError, "deterministic routes must be an Array" unless routes.is_a?(Array)
         raise WorkflowError, "deterministic routes must not be empty" if routes.empty?
 
+        seen = {}
         routes.each_with_object([]) do |route, list|
           name = normalize_deterministic_route!(route)
-          raise WorkflowError, "deterministic route #{name.inspect} is duplicated" if list.include?(name)
+          raise WorkflowError, "deterministic route #{name.inspect} is duplicated" if seen.key?(name)
 
+          seen[name] = true
           list << name
         end.freeze
       end
@@ -364,15 +362,6 @@ module Smith
         end
       end
 
-      def validate_non_negative_numeric!(name, value)
-        numeric = Float(value)
-        return if numeric >= 0.0
-
-        raise WorkflowError, "retry_on #{name} must be non-negative"
-      rescue TypeError, ArgumentError
-        raise WorkflowError, "retry_on #{name} must be numeric"
-      end
-
       def validate_orchestrate_controls!(opts)
         validate_orchestrate_required_fields!(opts)
         validate_orchestrate_bounds!(opts)

data/lib/smith/workflow/transition_actionability.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module TransitionActionability
+      module_function
+
+      def call(transition)
+        [
+          transition.agent_name,
+          transition.deterministic?,
+          transition.routed?,
+          transition.fanout?,
+          transition.nested?,
+          transition.optimized?,
+          transition.orchestrated?,
+          transition.success_transition
+        ].any?
+      end
+    end
+  end
+end

data/lib/smith/workflow.rb

@@ -9,14 +9,17 @@ require "time"
 require_relative "workflow/agent_result"
 require_relative "workflow/branch_env"
 require_relative "workflow/run_result"
+require_relative "workflow/string_snapshot"
 require_relative "workflow/usage_entry"
 
 module Smith
   class Workflow
     include DSL
+    include DefinitionIdentity
     include Persistence
     include Durability
     prepend SplitStepPersistence
+    include MessageAdmissionBoundary
     include GuardrailIntegration
     include BudgetIntegration
     include EventIntegration
@@ -66,7 +69,11 @@ module Smith
     RETRYABLE_BEARING_FAMILIES = %w[deterministic_step_failure tool_guardrail_failed].freeze
     private_constant :RETRYABLE_BEARING_FAMILIES
 
-    attr_reader :state, :last_prepared_input, :session_messages, :ledger
+    attr_reader :state, :last_prepared_input, :ledger
+
+    def session_messages
+      snapshot_session_messages
+    end
 
     def initialize(context: {}, ledger: nil, created_at: nil)
       @state = self.class.initial_state
@@ -135,17 +142,19 @@ module Smith
       return if transition.nil?
 
       @step_work_started = true
-      step_result = execute_step(transition)
+      step_result = if advance_claim == :split_step
+                      Execution.instance_method(:execute_step).bind_call(self, transition)
+                    else
+                      execute_step(transition)
+                    end
       @step_count += 1
       @updated_at = Time.now.utc.iso8601
       record_step_snapshot(step_result)
       step_result
     rescue UnresolvedTransitionError => e
-      origin_state = @state
-      @outcome = nil
-      raise unless route_to_fail_state!
-
-      step_result = { transition: e.requested_name, from: origin_state, to: @state, error: e }
+      step_result = GuardrailIntegration
+                    .instance_method(:handle_unresolved_transition_failure)
+                    .bind_call(self, e)
       record_step_snapshot(step_result)
       step_result
     ensure
@@ -162,8 +171,12 @@ module Smith
       build_run_result(steps)
     end
 
+    def pending_transition_name
+      @next_transition_name || self.class.first_transition_from(@state)&.name
+    end
+
     def terminal?
-      self.class.transitions_from(@state).empty? && @next_transition_name.nil?
+      !self.class.transition_from?(@state) && @next_transition_name.nil?
     end
 
     def done?
@@ -245,14 +258,6 @@ module Smith
       Budget::Ledger.new(limits: config)
     end
 
-    def route_to_fail_state!
-      fail_transition = self.class.find_transition(:fail)
-      return false unless fail_transition
-
-      @state = fail_transition.to
-      true
-    end
-
     def ensure_transition_budget!
       max = self.class.max_transitions || DEFAULT_MAX_TRANSITIONS
       raise MaxTransitionsExceeded if @step_count >= max
@@ -267,7 +272,7 @@ module Smith
         validate_transition_origin!(transition)
         transition
       else
-        self.class.transitions_from(@state).first
+        self.class.first_transition_from(@state)
       end
     end
 
@@ -460,7 +465,7 @@ module Smith
       when Array
         value.map { |nested| snapshot_value(nested) }
       when String
-        value.dup
+        StringSnapshot.copy(value)
       else
         value.dup
       end
@@ -469,3 +474,24 @@ module Smith
     end
   end
 end
+
+Smith::Workflow::SplitStepPersistence::SubclassBoundary.protect_execution_path!(
+  Smith::Workflow,
+  Smith::Workflow::Execution,
+  Smith::Workflow::ExecutionBindingResolution,
+  Smith::Workflow::StepCompletion,
+  Smith::Agent::Lifecycle,
+  Smith::Workflow::NestedExecution,
+  Smith::Workflow::EvaluatorOptimizer,
+  Smith::Workflow::OrchestratorWorker,
+  Smith::Workflow::ParallelExecution,
+  Smith::Workflow::FanoutExecution,
+  Smith::Workflow::RetryExecution,
+  Smith::Workflow::DeterministicExecution,
+  Smith::Workflow::GuardrailIntegration,
+  Smith::Workflow::BudgetIntegration,
+  Smith::Workflow::EventIntegration,
+  Smith::Workflow::ArtifactIntegration,
+  Smith::Workflow::DataVolumePolicy,
+  Smith::Workflow::DeadlineEnforcement
+)

data/lib/smith.rb

@@ -3,12 +3,32 @@
 require "dry-configurable"
 
 require_relative "smith/version"
+require_relative "smith/error"
 
 module Smith
-  class Error < StandardError; end
-
   extend Dry::Configurable
 
+  positive_integer_setting = lambda do |name|
+    lambda do |value|
+      unless value.is_a?(Integer) && value.positive?
+        raise ArgumentError, "Smith.config.#{name} must be a positive integer, got #{value.inspect}"
+      end
+
+      value
+    end
+  end
+
+  bounded_positive_integer_setting = lambda do |name, maximum|
+    lambda do |value|
+      unless value.is_a?(Integer) && value.positive? && value <= maximum
+        message = "Smith.config.#{name} must be a positive integer no greater than #{maximum}"
+        raise ArgumentError, "#{message}, got #{value.inspect}"
+      end
+
+      value
+    end
+  end
+
   # Artifact store (§4.7)
   setting :artifact_store
   setting :artifact_retention
@@ -46,6 +66,15 @@ module Smith
   #   max_delay:   cap on per-retry sleep
   setting :persistence_retry_policy, default: { attempts: 3, base_delay: 0.1, max_delay: 1.0 }
 
+  # Generic runtime resource bounds. Branch concurrency is scoped to one
+  # parallel execution; hosts retain control over process-level concurrency.
+  setting :parallel_branch_limit, default: 1_000, constructor: positive_integer_setting.call(:parallel_branch_limit)
+  setting :parallel_concurrency, default: 8, constructor: positive_integer_setting.call(:parallel_concurrency)
+  setting :parallel_nesting_limit, default: 64, constructor: bounded_positive_integer_setting.call(
+    :parallel_nesting_limit, 256
+  )
+  setting :retry_attempt_limit, default: 100, constructor: positive_integer_setting.call(:retry_attempt_limit)
+
   # Test isolation: when true AND persistence_adapter is nil, Smith
   # auto-selects the in-process Memory adapter. Lets specs avoid wiring
   # Redis/Rails.cache in spec_helper.rb.
@@ -148,6 +177,8 @@ end
 # Leaf modules (no internal dependencies)
 require_relative "smith/types"
 require_relative "smith/errors"
+require_relative "smith/persistence_payload_conflict"
+require_relative "smith/exponential_backoff"
 
 # Event system (depends on Types)
 require_relative "smith/event"
@@ -228,7 +259,9 @@ require_relative "smith/agent/registry_binding"
 require_relative "smith/agent/registry"
 
 # Workflow (Transition, DSL, Persistence, and Execution must load before Workflow)
+require_relative "smith/workflow/identifier"
 require_relative "smith/workflow/transition"
+require_relative "smith/workflow/transition_actionability"
 require_relative "smith/workflow/graph"
 require_relative "smith/workflow/graph_dsl"
 require_relative "smith/workflow/run_result"
@@ -239,6 +272,12 @@ require_relative "smith/workflow/optimization_state"
 require_relative "smith/workflow/orchestration_state"
 require_relative "smith/workflow/worker_execution"
 require_relative "smith/workflow/dsl"
+require_relative "smith/workflow/definition_identity"
+require_relative "smith/workflow/prepared_step_dispatch"
+require_relative "smith/workflow/message_value_normalizer"
+require_relative "smith/workflow/message_admission"
+require_relative "smith/workflow/message_batch"
+require_relative "smith/workflow/message_admission_boundary"
 require_relative "smith/workflow/persistence"
 require_relative "smith/workflow/durability"
 require_relative "smith/workflow/split_step_persistence"

data/sig/smith.rbs

@@ -1,4 +1,5 @@
 module Smith
   VERSION: String
+  EXECUTION_SEMANTICS_VERSION: String
   # See the writing guide of rbs: https://github.com/ruby/rbs#guides
 end