smith-agents 0.4.5 → 0.5.0

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

@@ -13,7 +13,11 @@ module Smith
           handle_split_step_preparation_conflict!
           raise
         rescue StandardError
-          mark_split_step_preparation_unknown!
+          if @split_step_dispatch_started
+            mark_split_step_preparation_unknown!
+          else
+            reset_failed_split_step_preparation!
+          end
           raise
         end
 
@@ -37,7 +41,11 @@ module Smith
 
         def mark_split_step_preparation_unknown!
           @split_step_mutex.synchronize do
-            @split_step_phase = :preparation_unknown if @split_step_phase == :preparing
+            if @split_step_phase == :preparing
+              @split_step_phase = :preparation_unknown
+              @split_step_prepared_descriptor = nil
+              @split_step_transaction_identity = nil
+            end
           end
         end
       end

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

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      module Recovery
+        private
+
+        def recover_prepared_step(recovery, adapter)
+          decision = validate_prepared_step_recovery!(recovery)
+          descriptor = decision.prepared_step
+          store = persistence_adapter!(adapter)
+          ensure_strict_split_step_persistence!
+          validate_split_step_adapter!(store)
+          ensure_recovery_outside_transaction!(store)
+          payload = fetch_recovery_payload!(store, descriptor.persistence_key)
+          document = validate_recovery_payload!(payload, decision, store)
+          restore_state(document, allow_step_in_progress: true)
+          attach_recovered_split_step!(descriptor, payload, store, dispatch_claim: decision.dispatch_claim)
+          self
+        end
+
+        def validate_prepared_step_recovery!(recovery)
+          return recovery if recovery.is_a?(PreparedStepRecovery)
+
+          raise ArgumentError, "recovery must be a Smith::Workflow::PreparedStepRecovery"
+        end
+
+        def ensure_recovery_outside_transaction!(adapter)
+          return unless Smith::PersistenceAdapters.supports?(adapter, :transaction_open?)
+          return unless adapter.transaction_open?
+
+          raise WorkflowError, "prepared-step recovery requires committed host authority outside a transaction"
+        end
+
+        def fetch_recovery_payload!(adapter, key)
+          payload = adapter.fetch(key)
+          return payload if payload.is_a?(String)
+
+          raise WorkflowError, "the persisted split-step preparation is not available"
+        end
+
+        def validate_recovery_payload!(payload, decision, adapter)
+          if payload.bytesize > CanonicalPayloadDigest::MAX_BYTES
+            raise WorkflowError,
+                  "persisted split-step preparation exceeds maximum bytes #{CanonicalPayloadDigest::MAX_BYTES}"
+          end
+
+          document = JSON.parse(payload)
+          raise WorkflowError, "the persisted split-step preparation must be an object" unless document.is_a?(Hash)
+
+          validate_recovery_definition!(document, decision.prepared_step)
+          validate_recovery_identity!(document, decision, adapter)
+          validate_recovery_digest!(payload, decision)
+          document
+        rescue JSON::ParserError, TypeError
+          raise WorkflowError, "the persisted split-step preparation is invalid"
+        end
+
+        def validate_recovery_definition!(document, descriptor)
+          current_digest = self.class.definition_digest
+          return if recovery_digests_match?(document, descriptor, current_digest) &&
+                    recovery_class_matches?(document) && recovery_schema_matches?(document)
+
+          raise WorkflowError, "the prepared step does not match the current workflow definition"
+        end
+
+        def recovery_digests_match?(document, descriptor, current_digest)
+          current_digest &&
+            descriptor.definition_digest == current_digest &&
+            document["definition_digest"] == current_digest
+        end
+
+        def recovery_class_matches?(document)
+          !self.class.name.to_s.empty? && document["class"] == self.class.name
+        end
+
+        def recovery_schema_matches?(document)
+          document["schema_version"] == self.class.persistence_schema_version
+        end
+
+        def validate_recovery_identity!(document, decision, adapter)
+          descriptor = decision.prepared_step
+          return if recovery_marker_matches?(document, decision, adapter) &&
+                    recovery_position_matches?(document, descriptor)
+
+          raise WorkflowError, "the persisted split-step preparation does not match the recovery descriptor"
+        end
+
+        def recovery_marker_matches?(document, decision, adapter)
+          descriptor = decision.prepared_step
+          document["step_in_progress"] == true &&
+            recovery_phase_matches?(document, decision.dispatch_claim) &&
+            document["split_step_persistence_identity"] == adapter.persistence_identity &&
+            document["split_step_token"] == descriptor.token &&
+            document["persistence_key"] == descriptor.persistence_key &&
+            document["persistence_version"] == descriptor.persistence_version
+        end
+
+        def recovery_phase_matches?(document, dispatch_claim)
+          if dispatch_claim
+            document["split_step_phase"] == "dispatching" &&
+              document["split_step_dispatch_token"] == dispatch_claim.token
+          else
+            document["split_step_phase"] == "prepared" && !document.key?("split_step_dispatch_token")
+          end
+        end
+
+        def recovery_position_matches?(document, descriptor)
+          step_count = document["step_count"]
+          step_count.is_a?(Integer) &&
+            step_count + 1 == descriptor.step_number &&
+            document["state"].to_s == descriptor.from
+        end
+
+        def validate_recovery_digest!(payload, decision)
+          expected = decision.dispatch_claim&.dispatch_digest || decision.prepared_step.preparation_digest
+          return if CanonicalPayloadDigest.call(payload) == expected
+
+          raise WorkflowError, "the persisted split-step recovery payload digest does not match"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      module RecoveryBoundary
+        private
+
+        def attach_recovered_split_step!(descriptor, payload, adapter, dispatch_claim:)
+          transition = pending_split_step_transition
+          transition_name = @next_transition_name || transition&.name
+          unless transition && transition_name.to_s == descriptor.transition && @state.to_s == descriptor.from
+            raise WorkflowError, "the recovered transition does not match the current workflow position"
+          end
+
+          detach_split_step_execution_state!
+          install_recovered_split_step!(descriptor, payload, adapter, transition, dispatch_claim)
+        end
+
+        def install_recovered_split_step!(descriptor, payload, adapter, transition, dispatch_claim)
+          signature = TransitionContract.capture(transition)
+          @split_step_mutex.synchronize do
+            install_recovered_transition!(transition, signature)
+            install_recovered_persistence!(descriptor, payload, adapter)
+            install_recovered_dispatch!(dispatch_claim)
+          end
+        end
+
+        def install_recovered_transition!(transition, signature)
+          @split_step_transition_name = transition.name
+          @split_step_transition = transition
+          @split_step_transition_signature = signature
+          @split_step_origin_state = @state
+        end
+
+        def install_recovered_persistence!(descriptor, payload, adapter)
+          @split_step_token = descriptor.token
+          @split_step_prepared_descriptor = descriptor
+          @split_step_persistence_key = descriptor.persistence_key
+          @split_step_adapter = adapter
+          @split_step_persistence_ttl = nil
+          @split_step_preparation_payload = payload.dup.freeze
+          @split_step_preparation_digest = descriptor.preparation_digest
+          @split_step_definition_digest = descriptor.definition_digest
+        end
+
+        def install_recovered_dispatch!(dispatch_claim)
+          @split_step_dispatch_started = false
+          @split_step_dispatch_token = dispatch_claim&.token
+          @split_step_dispatch_descriptor = dispatch_claim
+          @split_step_phase = dispatch_claim ? :dispatch_claimed : :prepared
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      module RecoveryClassMethods
+        def recover_prepared_step(recovery, adapter: Smith.persistence_adapter)
+          seal_definition_identity!
+          allocate.send(:recover_prepared_step, recovery, adapter)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      class ReplaceExactSignature
+        extend Dry::Initializer
+
+        CONTRACT_KEYWORDS = %i[expected_payload ttl].freeze
+
+        param :callable
+
+        def valid? = accepts_two_values? && accepts_keywords?
+
+        private
+
+        def parameters = callable.parameters
+
+        def accepts_two_values?
+          required = parameters.count { |kind, _| kind == :req }
+          positional = parameters.count { |kind, _| %i[req opt].include?(kind) }
+          rest = parameters.any? { |kind, _| kind == :rest }
+          required <= 2 && (positional >= 2 || rest)
+        end
+
+        def accepts_keywords?
+          required_keywords_supported? && contract_keywords_accepted?
+        end
+
+        def required_keywords_supported?
+          required = parameters.filter_map { |kind, name| name if kind == :keyreq }
+          (required - CONTRACT_KEYWORDS).empty?
+        end
+
+        def contract_keywords_accepted?
+          return true if parameters.any? { |kind, _| kind == :keyrest }
+
+          keywords = parameters.filter_map { |kind, name| name if %i[key keyreq].include?(kind) }
+          CONTRACT_KEYWORDS.all? { |name| keywords.include?(name) }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "replace_exact_signature"
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      module RestartSafeAdapter
+        private
+
+        def validate_restart_safe_adapter!(adapter)
+          return unless restart_safe_split_step?
+
+          ensure_replace_exact_capability!(adapter)
+          ensure_replace_exact_signature!(adapter)
+          ensure_persistence_identity!(adapter)
+        end
+
+        def ensure_replace_exact_capability!(adapter)
+          return if Smith::PersistenceAdapters.supports?(adapter, :replace_exact)
+
+          raise WorkflowError, "restart-safe split-step persistence requires replace_exact"
+        end
+
+        def ensure_replace_exact_signature!(adapter)
+          return if ReplaceExactSignature.new(adapter.method(:replace_exact)).valid?
+
+          raise WorkflowError,
+                "restart-safe split-step persistence requires replace_exact(key, payload, expected_payload:, ttl:)"
+        end
+
+        def ensure_persistence_identity!(adapter)
+          identity = adapter.persistence_identity if
+            Smith::PersistenceAdapters.supports?(adapter, :persistence_identity)
+          return if identity.is_a?(String) && !identity.empty? && identity.bytesize <= 256
+
+          raise WorkflowError, "restart-safe split-step persistence requires a bounded persistence_identity"
+        end
+      end
+    end
+  end
+end

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

@@ -4,6 +4,43 @@ module Smith
   class Workflow
     module SplitStepPersistence
       module SubclassBoundary
+        class << self
+          def protect_execution_path!(workflow_class, *owners)
+            protected_method_names(owners).each do |method_name|
+              protect_method!(workflow_class, method_name)
+            end
+          end
+
+          private
+
+          def protected_method_names(owners)
+            owners.flat_map do |owner|
+              owner.private_instance_methods(false) + owner.protected_instance_methods(false)
+            end.uniq
+          end
+
+          def protect_method!(workflow_class, method_name)
+            return if boundary_method_names.include?(method_name)
+
+            implementation = workflow_class.instance_method(method_name)
+            define_method(method_name) do |*arguments, **keywords, &block|
+              active = SubclassBoundary
+                       .instance_method(:smith_prepared_execution_active?)
+                       .bind_call(self)
+              if active
+                implementation.bind_call(self, *arguments, **keywords, &block)
+              else
+                super(*arguments, **keywords, &block)
+              end
+            end
+            private method_name
+          end
+
+          def boundary_method_names
+            instance_methods(false) + private_instance_methods(false) + protected_instance_methods(false)
+          end
+        end
+
         def self.guard
           Module.new.tap do |guard|
             instance_methods(false).each do |method_name|
@@ -33,6 +70,15 @@ module Smith
 
         private
 
+        def smith_prepared_execution_active?
+          root_execution = @split_step_phase == :executing &&
+                           @split_step_execution_thread.equal?(Thread.current)
+          return true if root_execution
+
+          authorization = @split_step_active_execution_authorization
+          authorization&.active_in_current_execution? == true
+        end
+
         def effective_persistence_ttl
           return super unless split_step_boundary_active?
           return super unless instance_variable_defined?(:@split_step_persistence_ttl)
@@ -46,6 +92,10 @@ module Smith
 
           { ttl: ttl }
         end
+
+        def dispatch_store!(...)
+          DispatchBoundary.instance_method(:dispatch_store!).bind_call(self, ...)
+        end
       end
     end
   end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      class TransactionIdentity
+        extend Dry::Initializer
+
+        param :adapter
+
+        def self.capture(adapter) = new(adapter).capture
+        def self.matches?(adapter, expected) = new(adapter).matches?(expected)
+
+        def capture
+          return unless PersistenceAdapters.supports?(adapter, :transaction_open?)
+          return unless adapter.transaction_open?
+
+          ensure_identity_capability!
+          identity = adapter.transaction_identity
+          if !identity || identity.to_s.empty?
+            raise WorkflowError, "transactional split-step persistence requires an active transaction identity"
+          end
+
+          identity.to_s.dup.freeze
+        end
+
+        def matches?(expected)
+          capture == expected
+        rescue StandardError
+          false
+        end
+
+        private
+
+        def ensure_identity_capability!
+          return if PersistenceAdapters.supports?(adapter, :transaction_identity)
+
+          raise WorkflowError, "transactional split-step persistence requires transaction_identity"
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/split_step_persistence.rb

@@ -4,17 +4,39 @@ require "digest"
 require "json"
 require "securerandom"
 
+require_relative "prepared_step"
+require_relative "prepared_step_dispatch"
+require_relative "prepared_step_execution_authorization"
+require_relative "prepared_step_execution_result"
+require_relative "prepared_step_recovery"
 require_relative "split_step_persistence/subclass_boundary"
 require_relative "split_step_persistence/inheritance"
+require_relative "split_step_persistence/recovery_class_methods"
 require_relative "split_step_persistence/transition_contract_structured_values"
 require_relative "split_step_persistence/transition_contract_signature"
 require_relative "split_step_persistence/transition_contract_freezer"
 require_relative "split_step_persistence/transition_contract"
+require_relative "split_step_persistence/transaction_identity"
+require_relative "split_step_persistence/canonical_payload_digest"
+require_relative "split_step_persistence/definition_boundary"
 require_relative "split_step_persistence/boundary"
+require_relative "split_step_persistence/boundary_reset"
 require_relative "split_step_persistence/state_snapshot"
 require_relative "split_step_persistence/preparation_claim"
 require_relative "split_step_persistence/preparation_recovery"
 require_relative "split_step_persistence/preparation"
+require_relative "split_step_persistence/restart_safe_adapter"
+require_relative "split_step_persistence/recovery"
+require_relative "split_step_persistence/recovery_boundary"
+require_relative "split_step_persistence/preparation_payload"
+require_relative "split_step_persistence/dispatch_boundary"
+require_relative "split_step_persistence/dispatch_claim"
+require_relative "split_step_persistence/dispatch_verification"
+require_relative "split_step_persistence/dispatch_confirmation"
+require_relative "split_step_persistence/execution_verification"
+require_relative "split_step_persistence/execution_binding_snapshot"
+require_relative "split_step_persistence/execution_authorization"
+require_relative "split_step_persistence/execution_result_capture"
 require_relative "split_step_persistence/execution"
 require_relative "split_step_persistence/checkpoint_state"
 require_relative "split_step_persistence/checkpoint"
@@ -27,13 +49,27 @@ module Smith
 
       def self.prepended(base)
         base.singleton_class.prepend(Inheritance)
+        base.extend(RecoveryClassMethods)
       end
 
       include Boundary
+      include BoundaryReset
+      include DefinitionBoundary
       include StateSnapshot
       include PreparationClaim
       include PreparationRecovery
       include Preparation
+      include RestartSafeAdapter
+      include Recovery
+      include RecoveryBoundary
+      include PreparationPayload
+      include DispatchBoundary
+      include DispatchClaim
+      include DispatchVerification
+      include DispatchConfirmation
+      include ExecutionVerification
+      include ExecutionAuthorization
+      include ExecutionResultCapture
       include Execution
       include CheckpointState
       include Checkpoint

data/lib/smith/workflow/step_completion.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module StepCompletion
+      private
+
+      def complete_step(transition, output)
+        step = { transition: transition.name, from: transition.from, to: transition.to, output: output }
+        result = SplitStepPersistence
+                 .instance_method(:prepare_split_step_execution_result)
+                 .bind_call(self, step)
+        StepCompletion.instance_method(:append_accepted_output).bind_call(self, output)
+        SplitStepPersistence
+          .instance_method(:commit_split_step_execution_result!)
+          .bind_call(self, result)
+        @state = transition.to
+        @next_transition_name = @router_next_transition || transition.success_transition
+        @router_next_transition = nil
+        emit_step_completed(transition, output)
+        step
+      end
+
+      def append_accepted_output(output)
+        return unless @session_messages && !output.nil?
+
+        @session_messages << { role: :assistant, content: output }
+      end
+    end
+  end
+end

data/lib/smith/workflow/string_snapshot.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class StringSnapshot
+      BYTESIZE = String.instance_method(:bytesize)
+      FREEZE = String.instance_method(:freeze)
+      INITIALIZE_COPY = String.instance_method(:initialize_copy)
+      private_constant :BYTESIZE, :FREEZE, :INITIALIZE_COPY
+
+      class << self
+        def bytesize(value)
+          BYTESIZE.bind_call(value)
+        end
+
+        def copy(value, freeze: false)
+          String.allocate.tap do |copy|
+            INITIALIZE_COPY.bind_call(copy, value)
+            FREEZE.bind_call(copy) if freeze
+          end
+        end
+      end
+    end
+  end
+end