smith-agents 0.4.5 → 0.6.0

data/lib/smith/workflow/split_step_persistence/execution_authorization.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      module ExecutionAuthorization
+        def release_prepared_step_execution!(authorization)
+          authorization = validate_split_step_execution_authorization!(authorization)
+          Thread.handle_interrupt(Object => :never) do
+            @split_step_mutex.synchronize do
+              unless active_split_step_execution_authorization?(authorization)
+                raise WorkflowError, "the prepared-step execution authorization is no longer active"
+              end
+
+              @split_step_phase = @split_step_execution_previous_phase
+              clear_split_step_execution_authorization!
+            end
+            PreparedStepExecutionAuthorization
+              .instance_method(:close_execution!)
+              .bind_call(authorization)
+          end
+          self
+        end
+
+        private
+
+        def authorize_claimed_prepared_step_execution!(verification_token)
+          ExecutionVerification
+            .instance_method(:verify_claimed_split_step_execution!)
+            .bind_call(self, verification_token)
+          authorization = ExecutionAuthorization
+                          .instance_method(:build_split_step_execution_authorization)
+                          .bind_call(self)
+          ExecutionAuthorization
+            .instance_method(:activate_split_step_execution_authorization!)
+            .bind_call(self, authorization, verification_token)
+          authorization
+        end
+
+        def claim_framework_execution_verification!
+          ExecutionVerification
+            .instance_method(:claim_split_step_execution_verification!)
+            .bind_call(self)
+        end
+
+        def restore_framework_execution_verification!(verification_token)
+          return unless verification_token
+
+          active = ExecutionAuthorization
+                   .instance_method(:active_split_step_execution_verification?)
+                   .bind_call(self, verification_token)
+          return unless active
+
+          Execution.instance_method(:restore_unverified_execution!).bind_call(self, verification_token)
+        end
+
+        def build_split_step_execution_authorization
+          PreparedStepExecutionAuthorization.new(
+            prepared_step: @split_step_prepared_descriptor,
+            dispatch_claim: @split_step_dispatch_descriptor,
+            execution_bindings: ExecutionBindingSnapshot.capture(
+              @split_step_transition,
+              workflow_class: self.class
+            )
+          )
+        end
+
+        def activate_split_step_execution_authorization!(authorization, verification_token)
+          @split_step_mutex.synchronize do
+            unless active_split_step_execution_verification?(verification_token)
+              raise WorkflowError, "the prepared execution verification is no longer active"
+            end
+
+            @split_step_execution_authorization = authorization
+            clear_split_step_execution_verification!
+            @split_step_phase = :execution_authorized
+          end
+        end
+
+        def validate_split_step_execution_authorization!(authorization)
+          return authorization if authorization.is_a?(PreparedStepExecutionAuthorization)
+
+          raise ArgumentError,
+                "authorization must be a Smith::Workflow::PreparedStepExecutionAuthorization"
+        end
+
+        def active_split_step_execution_authorization?(authorization)
+          @split_step_phase == :execution_authorized &&
+            @split_step_execution_authorization.equal?(authorization) &&
+            authorization.issued_in_current_process?
+        end
+
+        def active_split_step_execution_verification?(verification_token)
+          @split_step_phase == :verifying_execution &&
+            @split_step_execution_verification_token.equal?(verification_token)
+        end
+
+        def clear_split_step_execution_verification!
+          @split_step_execution_verification_token = nil
+        end
+
+        def clear_split_step_execution_authorization!
+          @split_step_execution_authorization = nil
+          @split_step_execution_previous_phase = nil
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/split_step_persistence/execution_authorization_issuance.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      module ExecutionAuthorizationIssuance
+        def authorize_prepared_step_execution!
+          authorization = nil
+          handed_off = false
+          authorization = ExecutionAuthorizationIssuance
+                          .instance_method(:interrupt_safe_prepared_step_authorization)
+                          .bind_call(self)
+          handed_off = true
+          authorization
+        ensure
+          unless handed_off
+            ExecutionLifecycle
+              .instance_method(:release_failed_execution_authorization!)
+              .bind_call(self, authorization)
+          end
+        end
+
+        private
+
+        def with_prepared_step_execution_authorization
+          Thread.handle_interrupt(Object => :never) do
+            authorization = interrupt_safe_prepared_step_authorization
+            begin
+              Thread.handle_interrupt(Object => :immediate) { yield(authorization) }
+            ensure
+              ExecutionLifecycle
+                .instance_method(:release_failed_execution_authorization!)
+                .bind_call(self, authorization)
+            end
+          end
+        end
+
+        def interrupt_safe_prepared_step_authorization
+          Thread.handle_interrupt(Object => :never) do
+            verification_token = ExecutionAuthorization
+                                 .instance_method(:claim_framework_execution_verification!)
+                                 .bind_call(self)
+            begin
+              ExecutionAuthorization
+                .instance_method(:authorize_claimed_prepared_step_execution!)
+                .bind_call(self, verification_token)
+            ensure
+              ExecutionAuthorization
+                .instance_method(:restore_framework_execution_verification!)
+                .bind_call(self, verification_token)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/split_step_persistence/execution_binding_collector.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require_relative "../../agent"
+require_relative "../../agent/registry"
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      class ExecutionBindingCollector
+        MAX_BINDINGS = 10_000
+
+        def initialize
+          @requests = {}
+          @bindings = {}
+        end
+
+        def capture(transition, workflow_class:)
+          capture_binding(transition.agent_name, workflow_class:, transition:, role: :agent)
+          capture_fanout(transition, workflow_class:)
+          capture_optimization(transition, workflow_class:)
+          capture_orchestration(transition, workflow_class:)
+        end
+
+        def fetch!(name, workflow_class:, transition_name:, role:)
+          @bindings.fetch(name.to_s) do
+            raise WorkflowError,
+                  "execution authorization does not contain #{role} :#{name} " \
+                  "for workflow #{workflow_class}, transition :#{transition_name}"
+          end
+        end
+
+        def capture_agent(name, workflow_class:, transition:, role:)
+          capture_binding(name, workflow_class:, transition:, role:)
+          self
+        end
+
+        def resolve!
+          @bindings = Agent::Registry.capture_bindings!(@requests.values)
+
+          @requests.freeze
+          self
+        end
+
+        def each(&)
+          @bindings.each(&)
+        end
+
+        def freeze
+          @requests.freeze
+          @bindings.freeze
+          super
+        end
+
+        private
+
+        def capture_fanout(transition, workflow_class:)
+          transition.fanout_config&.fetch(:branches, nil)&.each_value do |agent|
+            capture_binding(agent, workflow_class:, transition:, role: :fanout_agent)
+          end
+        end
+
+        def capture_optimization(transition, workflow_class:)
+          return unless (config = transition.optimization_config)
+
+          capture_binding(config.fetch(:generator), workflow_class:, transition:, role: :generator)
+          capture_binding(config.fetch(:evaluator), workflow_class:, transition:, role: :evaluator)
+        end
+
+        def capture_orchestration(transition, workflow_class:)
+          return unless (config = transition.orchestrator_config)
+
+          capture_binding(config.fetch(:orchestrator), workflow_class:, transition:, role: :orchestrator)
+          capture_binding(config.fetch(:worker), workflow_class:, transition:, role: :worker)
+        end
+
+        def capture_binding(name, workflow_class:, transition:, role:)
+          return unless name
+
+          key = name.to_s
+          return if @requests.key?(key)
+          if @requests.length >= MAX_BINDINGS
+            raise WorkflowError, "execution authorization exceeds maximum agent bindings #{MAX_BINDINGS}"
+          end
+
+          @requests[key] = {
+            name:,
+            workflow_class:,
+            transition_name: transition.name,
+            role:
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/split_step_persistence/execution_binding_snapshot.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require_relative "execution_binding_collector"
+require_relative "execution_workflow_snapshot"
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      class ExecutionBindingSnapshot
+        MAX_NESTED_WORKFLOWS = 128
+        MAX_TRANSITIONS = 10_000
+
+        def self.capture(transition, workflow_class:)
+          new(transition, workflow_class:).capture
+        end
+
+        def self.capture_agent(transition, workflow_class:, name:, role:)
+          new(transition, workflow_class:, selected_agent: { name:, role: }).capture
+        end
+
+        def initialize(transition, workflow_class:, selected_agent: nil)
+          @transition = transition
+          @workflow_class = workflow_class
+          @selected_agent = selected_agent
+          @bindings = ExecutionBindingCollector.new
+          @visited_workflows = {}.compare_by_identity
+          @visited_workflows[workflow_class] = true
+          @workflow_snapshots = {}.compare_by_identity
+          @workflow_queue = []
+          @workflow_queue_index = 0
+          @transition_count = 0
+        end
+
+        def capture
+          if @selected_agent
+            @bindings.capture_agent(
+              @selected_agent.fetch(:name),
+              workflow_class: @workflow_class,
+              transition: @transition,
+              role: @selected_agent.fetch(:role)
+            )
+          else
+            capture_transition(@transition, workflow_class: @workflow_class)
+            drain_workflow_queue
+          end
+          @bindings.resolve!
+          @bindings.freeze
+          @workflow_snapshots.freeze
+          freeze
+        end
+
+        def fetch!(name, workflow_class:, transition_name:, role:)
+          @bindings.fetch!(name, workflow_class:, transition_name:, role:)
+        end
+
+        def each_agent_binding(&)
+          @bindings.each(&)
+        end
+
+        def verify_workflow!(workflow_class)
+          snapshot = @workflow_snapshots.fetch(workflow_class) do
+            raise WorkflowError, "execution authorization does not contain nested workflow #{workflow_class}"
+          end
+          snapshot.verify!
+        end
+
+        private
+
+        def capture_transition(transition, workflow_class:)
+          return unless transition
+
+          visit_transition!
+          @bindings.capture(transition, workflow_class:)
+          enqueue_nested_workflow(transition.workflow_class)
+        end
+
+        def enqueue_nested_workflow(workflow_class)
+          return unless workflow_class
+          return if @visited_workflows.key?(workflow_class)
+
+          @visited_workflows[workflow_class] = true
+          if @visited_workflows.length > MAX_NESTED_WORKFLOWS
+            raise WorkflowError,
+                  "execution authorization exceeds maximum nested workflows #{MAX_NESTED_WORKFLOWS}"
+          end
+
+          @workflow_queue << workflow_class
+        end
+
+        def drain_workflow_queue
+          while @workflow_queue_index < @workflow_queue.length
+            workflow_class = @workflow_queue.fetch(@workflow_queue_index)
+            @workflow_queue_index += 1
+            @workflow_snapshots[workflow_class] = ExecutionWorkflowSnapshot.capture(workflow_class) do |transition|
+              capture_transition(transition, workflow_class:)
+            end
+          end
+        end
+
+        def visit_transition!
+          @transition_count += 1
+          return if @transition_count <= MAX_TRANSITIONS
+
+          raise WorkflowError, "execution authorization exceeds maximum transitions #{MAX_TRANSITIONS}"
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/split_step_persistence/execution_lifecycle.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      module ExecutionLifecycle
+        private
+
+        def perform_authorized_prepared_step_execution!(authorization)
+          authorization = validate_split_step_execution_authorization!(authorization)
+          execution_thread = Thread.current
+          execute_prepared_step_lifecycle!(authorization, execution_thread) { yield(execution_thread) }
+        end
+
+        def execute_prepared_step_lifecycle!(authorization, execution_thread)
+          execution_active = false
+          step = nil
+          result = nil
+          Thread.handle_interrupt(Object => :never) do
+            activate_split_step_execution!(authorization, execution_thread)
+            execution_active = true
+            Thread.handle_interrupt(Object => :immediate) do
+              step, result = yield(execution_thread)
+            end
+          ensure
+            finish_split_step_execution!(step, authorization, execution_thread) if execution_active
+          end
+          result
+        end
+
+        def activate_split_step_execution!(authorization, execution_thread)
+          Thread.handle_interrupt(Object => :never) do
+            @split_step_mutex.synchronize do
+              ensure_active_split_step_execution_authorization!(authorization)
+              ensure_split_step_definition_current!
+              ensure_prepared_split_step_transition_matches!
+              activate_prepared_step_execution_scope!(authorization)
+              publish_active_split_step_execution!(authorization, execution_thread)
+            end
+          end
+        end
+
+        def finish_split_step_execution!(step, authorization, execution_thread)
+          Thread.handle_interrupt(Object => :never) do
+            @split_step_mutex.synchronize do
+              reset_active_split_step_execution!(step) if active_split_step_execution?(execution_thread)
+            end
+          ensure
+            PreparedStepExecutionAuthorization.instance_method(:close_execution!).bind_call(authorization)
+          end
+        end
+
+        def ensure_active_split_step_execution_authorization!(authorization)
+          return if active_split_step_execution_authorization?(authorization)
+
+          raise WorkflowError, "the prepared-step execution authorization is no longer active"
+        end
+
+        def activate_prepared_step_execution_scope!(authorization)
+          PreparedStepExecutionAuthorization.instance_method(:activate_execution!).bind_call(authorization)
+        end
+
+        def publish_active_split_step_execution!(authorization, execution_thread)
+          @split_step_active_execution_authorization = authorization
+          @split_step_execution_result = nil
+          @split_step_phase = :executing
+          clear_split_step_execution_authorization!
+          @split_step_execution_thread = execution_thread
+          @split_step_advance_permit = true
+        end
+
+        def active_split_step_execution?(execution_thread)
+          @split_step_phase == :executing && @split_step_execution_thread.equal?(execution_thread)
+        end
+
+        def reset_active_split_step_execution!(step)
+          @split_step_execution_thread = nil
+          @split_step_advance_permit = false
+          @split_step_execution_previous_phase = nil
+          @split_step_active_execution_authorization = nil
+          @split_step_execution_result = nil
+          @split_step_phase = step ? :executed : :attempted
+        end
+
+        def release_failed_execution_authorization!(authorization)
+          return unless authorization
+          return unless active_split_step_execution_authorization?(authorization)
+
+          ExecutionAuthorization
+            .instance_method(:release_prepared_step_execution!)
+            .bind_call(self, authorization)
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/split_step_persistence/execution_result_capture.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      module ExecutionResultCapture
+        private
+
+        def capture_split_step_execution_result!(step)
+          result = prepare_split_step_execution_result(step)
+          commit_split_step_execution_result!(result)
+        end
+
+        def prepare_split_step_execution_result(step)
+          return unless active_split_step_execution_thread?
+
+          PreparedStepExecutionResult.from_step(step)
+        end
+
+        def commit_split_step_execution_result!(result)
+          return unless result
+
+          @split_step_mutex.synchronize do
+            return unless active_split_step_execution_thread?
+            raise WorkflowError, "prepared-step execution produced more than one result" if @split_step_execution_result
+
+            @split_step_execution_result = result
+          end
+        end
+
+        def consume_split_step_execution_result!(execution_thread)
+          @split_step_mutex.synchronize do
+            unless @split_step_phase == :executing && @split_step_execution_thread.equal?(execution_thread)
+              raise WorkflowError, "prepared-step execution is no longer active"
+            end
+
+            @split_step_execution_result ||
+              raise(WorkflowError, "prepared-step execution did not produce a result")
+          end
+        end
+
+        def active_split_step_execution_thread?
+          @split_step_phase == :executing && @split_step_execution_thread.equal?(Thread.current)
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/split_step_persistence/execution_verification.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      module ExecutionVerification
+        private
+
+        def claim_split_step_execution_verification!
+          @split_step_mutex.synchronize do
+            DefinitionBoundary
+              .instance_method(:ensure_split_step_definition_current!)
+              .bind_call(self)
+            restart_safe = DefinitionBoundary
+                           .instance_method(:restart_safe_split_step?)
+                           .bind_call(self)
+            expected = restart_safe ? :dispatch_claimed : :prepared
+            raise WorkflowError, "no persisted step is prepared for execution" unless @split_step_phase == expected
+
+            ExecutionVerification
+              .instance_method(:ensure_prepared_split_step_transition_matches!)
+              .bind_call(self)
+
+            token = Object.new.freeze
+            @split_step_execution_previous_phase = expected
+            @split_step_execution_verification_token = token
+            @split_step_phase = :verifying_execution
+            token
+          end
+        end
+
+        def verify_claimed_split_step_execution!(verification_token)
+          restart_safe = DefinitionBoundary
+                         .instance_method(:restart_safe_split_step?)
+                         .bind_call(self)
+          if restart_safe
+            DispatchVerification
+              .instance_method(:verify_split_step_dispatch_available!)
+              .bind_call(self, verification_token)
+          else
+            verify_split_step_preparation_available!
+          end
+        end
+
+        def prepared_split_step_transition_matches?
+          transition = pending_split_step_transition
+          transition_name = @next_transition_name || transition&.name
+          transition_name == @split_step_transition_name &&
+            transition.equal?(@split_step_transition) &&
+            split_step_transition_signature(transition) == @split_step_transition_signature
+        end
+
+        def ensure_prepared_split_step_transition_matches!
+          return if prepared_split_step_transition_matches?
+
+          raise WorkflowError, "the prepared transition no longer matches the workflow"
+        end
+
+        def verify_split_step_preparation_available!
+          payload = @split_step_adapter.fetch(@split_step_persistence_key)
+          durable = persisted_split_step_payload?(payload, @split_step_preparation_payload)
+          live = persisted_split_step_payload?(current_split_step_preparation_payload, @split_step_preparation_payload)
+          stable = split_step_transition_signature(@split_step_transition) == @split_step_transition_signature
+          return if durable && live && stable
+
+          raise WorkflowError, "the persisted split-step preparation is no longer available"
+        end
+
+        def current_split_step_preparation_payload
+          split_step_preparation_payload(
+            JSON.generate(to_state.merge(persistence_version: @persistence_version))
+          )
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/split_step_persistence/execution_workflow_snapshot.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+require_relative "../../errors"
+require_relative "../graph"
+require_relative "transition_contract"
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      class ExecutionWorkflowSnapshot
+        extend Dry::Initializer
+
+        param :workflow_class
+
+        def self.capture(workflow_class, &)
+          new(workflow_class).capture(&)
+        end
+
+        def capture
+          @initial_state_signature = initial_state_signature
+          @transitions = reachable_definition_transitions.map do |transition|
+            yield transition if block_given?
+            [transition.name, transition, TransitionContract.capture(transition)].freeze
+          end.freeze
+          freeze
+        end
+
+        def verify!
+          unless initial_state_signature == @initial_state_signature
+            raise WorkflowError, "authorized nested workflow definition changed before execution"
+          end
+
+          index = 0
+          reachable_definition_transitions.each do |transition|
+            expected = @transitions[index]
+            verify_transition!(transition, expected)
+            index += 1
+          end
+          return true if index == @transitions.length
+
+          raise WorkflowError, "authorized nested workflow definition changed before execution"
+        end
+
+        private
+
+        def reachable_definition_transitions
+          workflow_class.graph.reachable_transitions.map do |transition|
+            workflow_class.transition_at(transition.definition_index)
+          end
+        rescue IndexError
+          raise WorkflowError, "authorized nested workflow definition changed before execution"
+        end
+
+        def initial_state_signature
+          TransitionContractSignature.new(
+            value: workflow_class.initial_state,
+            max_depth: TransitionContract::MAX_DEPTH,
+            max_nodes: TransitionContract::MAX_NODES,
+            max_bytes: TransitionContract::MAX_BYTES
+          ).call
+        end
+
+        def verify_transition!(transition, expected)
+          matches = expected &&
+                    transition.name == expected.fetch(0) &&
+                    transition.equal?(expected.fetch(1)) &&
+                    TransitionContract.signature(transition) == expected.fetch(2)
+          return if matches
+
+          raise WorkflowError, "authorized nested workflow definition changed before execution"
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/split_step_persistence/inheritance.rb

@@ -11,7 +11,9 @@ module Smith
 
         def prepend(*features)
           result = super
-          Module.instance_method(:prepend).bind_call(self, SubclassBoundary.guard)
+          guard = SubclassBoundary.guard
+          guard.freeze
+          Module.instance_method(:prepend).bind_call(self, guard)
           result
         end
       end