smith-agents 0.4.4 → 0.5.0

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

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+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!
+          return unless intent_claimed
+
+          preparation_finalized = false
+          prepare_claimed_persisted_step!(key, adapter)
+          preparation_finalized = true
+          persist_claimed_split_step_preparation!(@split_step_persistence_key, @split_step_adapter)
+          @split_step_transition_name
+        ensure
+          release_split_step_preparation_intent! if intent_claimed && !preparation_finalized
+        end
+
+        def confirm_prepared_step!
+          confirmation_claimed = false
+          claim_split_step_confirmation!
+          confirmation_claimed = true
+          confirmed = false
+          payload = @split_step_adapter.fetch(@split_step_persistence_key)
+          raise WorkflowError, "the persisted split-step preparation is not committed" unless
+            persisted_split_step_payload?(payload, @split_step_preparation_payload)
+
+          @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!
+          return if strict_idempotency?
+
+          raise WorkflowError, "split-step persistence requires idempotency_mode :strict"
+        end
+
+        def prepare_claimed_persisted_step!(key, adapter)
+          transition = pending_split_step_transition
+          transition_name = @next_transition_name || transition&.name
+          raise WorkflowError, "workflow has no pending transition" unless transition_name
+
+          ensure_transition_budget!
+          resolved_key = normalize_split_step_persistence_key(candidate_split_step_persistence_key(key))
+          store = persistence_adapter!(adapter)
+          persistence_ttl = validate_split_step_adapter!(store)
+          finalize_split_step_preparation!(transition, transition_name, resolved_key, store, persistence_ttl)
+        end
+
+        def pending_split_step_transition
+          transition = if @next_transition_name
+                         self.class.find_transition(@next_transition_name)
+                       else
+                         self.class.first_transition_from(@state)
+                       end
+          validate_transition_origin!(transition) if transition
+          transition
+        end
+
+        def candidate_split_step_persistence_key(key)
+          return key unless key.nil? || blank_key?(key)
+          return @persistence_key unless blank_key?(@persistence_key)
+
+          self.class.send(:resolve_persistence_key!, key:, context: @context)
+        end
+
+        def normalize_split_step_persistence_key(key) = key.to_s.dup.freeze
+
+        def validate_split_step_adapter!(adapter)
+          unless Smith::PersistenceAdapters.supports?(adapter, :store_versioned)
+            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
+          return unless effective_persistence_ttl
+
+          raise WorkflowError, "split-step persistence requires non-expiring workflow persistence"
+        end
+
+        def split_step_adapter_accepts_explicit_ttl?(adapter)
+          adapter.method(:store_versioned).parameters.any? do |kind, name|
+            kind == :keyrest || (%i[key keyreq].include?(kind) && name == :ttl)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      module PreparationClaim
+        private
+
+        def claim_split_step_preparation_intent!
+          @split_step_mutex.synchronize do
+            ensure_no_split_step_boundary!
+            return false if terminal?
+
+            @split_step_phase = :claiming_preparation
+            @split_step_preparation_thread = Thread.current
+            @split_step_definition_digest = self.class.send(:seal_definition_identity!)
+            true
+          end
+        end
+
+        def release_split_step_preparation_intent!
+          @split_step_mutex.synchronize do
+            next unless @split_step_phase == :claiming_preparation
+            next unless @split_step_preparation_thread.equal?(Thread.current)
+
+            @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?
+              raise WorkflowError, "the split-step preparation claim is no longer active"
+            end
+
+            @split_step_phase = :preparing
+            @split_step_transition_name = transition_name
+            @split_step_transition = transition
+            @split_step_transition_signature = transition_signature
+            @split_step_origin_state = @state
+            @split_step_token = SecureRandom.uuid.freeze
+            detach_split_step_execution_state!
+            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)
+          @split_step_mutex.synchronize do
+            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
+              raise WorkflowError, "no uncommitted split-step preparation is awaiting confirmation"
+            end
+            if @split_step_adapter.transaction_open?
+              raise WorkflowError, "the split-step preparation transaction is still open"
+            end
+
+            @split_step_phase = :confirming_preparation
+          end
+        end
+
+        def restore_unconfirmed_preparation!
+          @split_step_mutex.synchronize do
+            @split_step_phase = :prepared_uncommitted if @split_step_phase == :confirming_preparation
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      module PreparationRecovery
+        private
+
+        def persist_claimed_split_step_preparation!(resolved_key, store)
+          persist!(resolved_key, adapter: store)
+          mark_split_step_prepared!(store)
+        rescue PersistenceVersionConflict
+          handle_split_step_preparation_conflict!
+          raise
+        rescue StandardError
+          if @split_step_dispatch_started
+            mark_split_step_preparation_unknown!
+          else
+            reset_failed_split_step_preparation!
+          end
+          raise
+        end
+
+        def reset_failed_split_step_preparation!
+          return unless @split_step_phase == :preparing
+
+          clear_step_in_progress!
+          clear_split_step_boundary!
+        end
+
+        def handle_split_step_preparation_conflict!
+          payload = @split_step_adapter.fetch(@split_step_persistence_key)
+          if persisted_split_step_payload?(payload, @split_step_preparation_payload)
+            mark_split_step_preparation_unknown!
+          else
+            reset_failed_split_step_preparation!
+          end
+        rescue StandardError
+          mark_split_step_preparation_unknown!
+        end
+
+        def mark_split_step_preparation_unknown!
+          @split_step_mutex.synchronize do
+            if @split_step_phase == :preparing
+              @split_step_phase = :preparation_unknown
+              @split_step_prepared_descriptor = nil
+              @split_step_transaction_identity = nil
+            end
+          end
+        end
+      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