smith-agents 0.4.5 → 0.6.0

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

@@ -7,10 +7,10 @@ module Smith
         private
 
         def persisted_split_step_payload?(payload, expected)
-          return false unless payload
+          return false unless payload.is_a?(String) && expected.is_a?(String)
 
-          JSON.parse(payload) == JSON.parse(expected)
-        rescue JSON::ParserError, TypeError
+          CanonicalPayloadDigest.call(payload) == CanonicalPayloadDigest.call(expected)
+        rescue WorkflowError, JSON::ParserError, TypeError
           false
         end
 
@@ -38,6 +38,10 @@ module Smith
         def split_step_preparation_payload(payload)
           document = JSON.parse(payload)
           document["split_step_token"] = @split_step_token
+          if restart_safe_split_step?
+            document["split_step_phase"] = "prepared"
+            document["split_step_persistence_identity"] = @split_step_adapter.persistence_identity
+          end
           JSON.generate(document)
         end
 

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

@@ -4,6 +4,14 @@ module Smith
   class Workflow
     module SplitStepPersistence
       module Preparation
+        DESCRIPTOR_PHASES = %i[
+          prepared_uncommitted prepared verifying_execution execution_authorized executing executed attempted
+          dispatch_claimed_uncommitted dispatch_claimed dispatch_rejected dispatch_unknown
+          confirming_dispatch checkpointing checkpoint_retryable checkpoint_unknown
+          checkpointed confirming_checkpoint
+        ].freeze
+        private_constant :DESCRIPTOR_PHASES
+
         def prepare_persisted_step!(key = nil, adapter: Smith.persistence_adapter)
           ensure_strict_split_step_persistence!
           intent_claimed = claim_split_step_preparation_intent!
@@ -27,13 +35,32 @@ module Smith
           raise WorkflowError, "the persisted split-step preparation is not committed" unless
             persisted_split_step_payload?(payload, @split_step_preparation_payload)
 
-          @split_step_mutex.synchronize { @split_step_phase = :prepared }
+          @split_step_mutex.synchronize do
+            @split_step_phase = :prepared
+            @split_step_transaction_thread = nil
+            @split_step_transaction_identity = nil
+          end
           confirmed = true
           self
         ensure
           restore_unconfirmed_preparation! if confirmation_claimed && !confirmed
         end
 
+        def prepared_persisted_step
+          phase, descriptor, adapter, transaction_identity = @split_step_mutex.synchronize do
+            [
+              @split_step_phase,
+              @split_step_prepared_descriptor,
+              @split_step_adapter,
+              @split_step_transaction_identity
+            ]
+          end
+          return unless DESCRIPTOR_PHASES.include?(phase) && descriptor
+          return descriptor unless phase == :prepared_uncommitted
+
+          descriptor if TransactionIdentity.matches?(adapter, transaction_identity)
+        end
+
         private
 
         def ensure_strict_split_step_persistence!
@@ -58,7 +85,7 @@ module Smith
           transition = if @next_transition_name
                          self.class.find_transition(@next_transition_name)
                        else
-                         self.class.transitions_from(@state).first
+                         self.class.first_transition_from(@state)
                        end
           validate_transition_origin!(transition) if transition
           transition
@@ -78,6 +105,7 @@ module Smith
             raise WorkflowError, "split-step persistence requires an adapter with store_versioned"
           end
 
+          validate_restart_safe_adapter!(adapter)
           unless split_step_adapter_accepts_explicit_ttl?(adapter)
             raise WorkflowError, "split-step persistence requires store_versioned to accept ttl:"
           end

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

@@ -13,6 +13,7 @@ module Smith
 
             @split_step_phase = :claiming_preparation
             @split_step_preparation_thread = Thread.current
+            @split_step_definition_digest = self.class.send(:seal_definition_identity!)
             true
           end
         end
@@ -24,10 +25,13 @@ module Smith
 
             @split_step_phase = nil
             @split_step_preparation_thread = nil
+            remove_instance_variable(:@split_step_definition_digest) if
+              instance_variable_defined?(:@split_step_definition_digest)
           end
         end
 
         def finalize_split_step_preparation!(transition, transition_name, key, adapter, persistence_ttl)
+          transaction_identity = TransactionIdentity.capture(adapter)
           transition_signature = TransitionContract.capture(transition)
           @split_step_mutex.synchronize do
             unless active_split_step_preparation_claim?
@@ -41,32 +45,54 @@ module Smith
             @split_step_origin_state = @state
             @split_step_token = SecureRandom.uuid.freeze
             detach_split_step_execution_state!
-            @split_step_persistence_key = key
-            @split_step_adapter = adapter
-            @split_step_persistence_ttl = persistence_ttl
-            @persistence_key = key
-            @split_step_persist_permit = true
+            target_writer = PreparationClaim.instance_method(:assign_split_step_persistence_target!)
+            target_writer.bind_call(self, key, adapter, persistence_ttl, transaction_identity)
           end
         end
 
+        def assign_split_step_persistence_target!(key, adapter, persistence_ttl, transaction_identity)
+          @split_step_persistence_key = key
+          @split_step_adapter = adapter
+          @split_step_persistence_ttl = persistence_ttl
+          @split_step_transaction_identity = transaction_identity
+          @split_step_dispatch_started = false
+          @persistence_key = key
+          @split_step_persist_permit = true
+        end
+
         def active_split_step_preparation_claim?
           @split_step_phase == :claiming_preparation &&
             @split_step_preparation_thread.equal?(Thread.current)
         end
 
-        def mark_split_step_prepared!(adapter)
+        def mark_split_step_prepared!(_adapter)
           @split_step_mutex.synchronize do
-            @split_step_phase = if Smith::PersistenceAdapters.supports?(adapter, :transaction_open?) &&
-                                   adapter.transaction_open?
-                                  :prepared_uncommitted
-                                else
-                                  :prepared
-                                end
+            phase = @split_step_transaction_identity ? :prepared_uncommitted : :prepared
+            unless @split_step_pending_descriptor
+              raise WorkflowError, "split-step preparation descriptor was not captured"
+            end
+
+            @split_step_prepared_descriptor = @split_step_pending_descriptor
+            @split_step_pending_descriptor = nil
+            @split_step_phase = phase
             @split_step_preparation_thread = nil
             @split_step_persist_permit = false
           end
         end
 
+        def build_split_step_prepared_descriptor(persistence_version)
+          PreparedStep.new(
+            token: @split_step_token,
+            transition: @split_step_transition_name.to_s,
+            from: @split_step_origin_state.to_s,
+            persistence_key: @split_step_persistence_key,
+            persistence_version: persistence_version,
+            step_number: @step_count + 1,
+            preparation_digest: @split_step_preparation_digest,
+            definition_digest: effective_definition_digest
+          )
+        end
+
         def claim_split_step_confirmation!
           @split_step_mutex.synchronize do
             unless @split_step_phase == :prepared_uncommitted

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      module PreparationPayload
+        private
+
+        def capture_split_step_preparation_payload!(payload, next_version)
+          validate_split_step_marker!(payload, expected: true)
+          prepared_payload = split_step_preparation_payload(payload)
+          @split_step_preparation_payload = prepared_payload
+          @split_step_preparation_digest = CanonicalPayloadDigest.call(prepared_payload)
+          descriptor_builder = PreparationClaim.instance_method(:build_split_step_prepared_descriptor)
+          @split_step_pending_descriptor = descriptor_builder.bind_call(self, next_version)
+          prepared_payload
+        rescue StandardError
+          resetter = PreparationRecovery.instance_method(:reset_failed_split_step_preparation!)
+          resetter.bind_call(self)
+          raise
+        end
+      end
+    end
+  end
+end

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|
@@ -31,8 +68,33 @@ module Smith
           super
         end
 
+        def authorize_prepared_step_execution!(...)
+          ExecutionAuthorizationIssuance.instance_method(:authorize_prepared_step_execution!).bind_call(self, ...)
+        end
+
+        def prepare_composite_step!(...)
+          CompositeExecution.instance_method(:prepare_composite_step!).bind_call(self, ...)
+        end
+
+        def execute_prepared_composite_branch!(...)
+          CompositeExecution.instance_method(:execute_prepared_composite_branch!).bind_call(self, ...)
+        end
+
+        def reduce_prepared_composite_step!(...)
+          CompositeExecution.instance_method(:reduce_prepared_composite_step!).bind_call(self, ...)
+        end
+
         private
 
+        def smith_prepared_execution_active?
+          authorization = @split_step_active_execution_authorization
+          return true if authorization&.active_in_current_execution? == true
+
+          authorization = @split_step_execution_authorization
+          @split_step_phase == :execution_authorized &&
+            authorization&.issued_in_current_process? == 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 +108,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