smith-agents 0.4.3 → 0.4.5

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

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      class TransitionContractFreezer
+        extend Dry::Initializer
+
+        CORE_FREEZE = Object.instance_method(:freeze)
+
+        option :value
+        option :max_depth
+        option :max_nodes
+
+        def call
+          stack = [[value, 0]]
+          seen = {}.compare_by_identity
+          nodes = 0
+          until stack.empty?
+            item, depth = stack.pop
+            nodes = visit!(nodes, depth)
+            freeze_item(item, depth, stack, seen)
+          end
+          value
+        end
+
+        private
+
+        def visit!(nodes, depth)
+          raise WorkflowError, "split-step transition contract exceeds maximum depth #{max_depth}" if depth > max_depth
+          return nodes + 1 if nodes < max_nodes
+
+          raise WorkflowError, "split-step transition contract exceeds maximum size #{max_nodes}"
+        end
+
+        def freeze_item(item, depth, stack, seen)
+          return if immutable?(item) || item.is_a?(Module) || seen.key?(item)
+
+          seen[item] = true
+          children(item).reverse_each { |child| stack << [child, depth + 1] }
+          CORE_FREEZE.bind_call(item)
+        end
+
+        def children(item)
+          return [] if leaf?(item)
+          return item.flat_map { |key, value| [key, value] } if item.is_a?(Hash)
+          return [item.begin, item.end] if item.is_a?(Range)
+
+          object_children(item)
+        end
+
+        def object_children(item)
+          return item.to_a if item.is_a?(Array) || item.is_a?(Set)
+          return member_children(item) if item.is_a?(Struct) || item.is_a?(Data)
+
+          transition_children(item)
+        end
+
+        def member_children(item)
+          item.members.map { |name| item.public_send(name) }
+        end
+
+        def transition_children(item)
+          unless item.is_a?(Workflow::Transition)
+            raise WorkflowError, "split-step transition contract contains unsupported value #{item.class}"
+          end
+
+          item.instance_variables.map { |name| item.instance_variable_get(name) }
+        end
+
+        def leaf?(item)
+          item.is_a?(String) || item.is_a?(Proc)
+        end
+
+        def immutable?(item)
+          item.nil? || item.is_a?(Symbol) || item.is_a?(Numeric) || item == true || item == false
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+require "digest"
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      class TransitionContractSignature
+        extend Dry::Initializer
+        include TransitionContractStructuredValues
+
+        option :value
+        option :max_depth
+        option :max_nodes
+        option :max_bytes
+
+        def call
+          @nodes = 0
+          @bytes = 0
+          @seen = {}.compare_by_identity
+          signature_value(value, 0)
+        end
+
+        private
+
+        def signature_value(item, depth)
+          visit!(depth)
+          reference = reference_for(item)
+          return reference if reference
+          return terminal_signature(item) if terminal?(item)
+
+          composite_signature(item, depth)
+        end
+
+        def composite_signature(item, depth)
+          case item
+          when Hash then hash_signature(item, depth)
+          when Array then collection_signature(:array, item, depth)
+          when Set then collection_signature(:set, item, depth)
+          else structured_signature(item, depth)
+          end
+        end
+
+        def terminal_signature(item)
+          case item
+          when String then string_signature(item)
+          when Module then [:module, item.name, item.object_id]
+          when Proc then proc_signature(item)
+          else item
+          end
+        end
+
+        def hash_signature(hash, depth)
+          [:hash, reference_id(hash), hash.map do |key, item|
+            [signature_value(key, depth + 1), signature_value(item, depth + 1)]
+          end]
+        end
+
+        def collection_signature(kind, collection, depth)
+          [kind, reference_id(collection), collection.map { |item| signature_value(item, depth + 1) }]
+        end
+
+        def proc_signature(callable)
+          [:proc, callable.object_id, callable.source_location, callable.parameters, callable.lambda?]
+        end
+
+        def string_signature(string)
+          @bytes += string.bytesize
+          raise WorkflowError, "split-step transition contract exceeds maximum bytes #{max_bytes}" if @bytes > max_bytes
+
+          [:string, string.bytesize, Digest::SHA256.hexdigest(string)]
+        end
+
+        def reference_for(item)
+          return unless referenceable?(item)
+          return [:reference, reference_id(item)] if @seen.key?(item)
+
+          @seen[item] = @seen.size
+          nil
+        end
+
+        def reference_id(item) = @seen.fetch(item)
+
+        def referenceable?(item)
+          !terminal?(item)
+        end
+
+        def terminal?(item)
+          case item
+          when String, Symbol, Numeric, Module, Proc, true, false, nil then true
+          else false
+          end
+        end
+
+        def visit!(depth)
+          raise WorkflowError, "split-step transition contract exceeds maximum depth #{max_depth}" if depth > max_depth
+
+          @nodes += 1
+          return if @nodes <= max_nodes
+
+          raise WorkflowError, "split-step transition contract exceeds maximum size #{max_nodes}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      module TransitionContractStructuredValues
+        private
+
+        def structured_signature(item, depth)
+          case item
+          when Struct then member_signature(:struct, item, depth)
+          when Data then member_signature(:data, item, depth)
+          when Range then range_signature(item, depth)
+          when Workflow::Transition then object_signature(item, depth)
+          else unsupported!(item)
+          end
+        end
+
+        def member_signature(kind, object, depth)
+          members = object.members.map do |name|
+            [name, signature_value(object.public_send(name), depth + 1)]
+          end
+          [kind, object.class.name, reference_id(object), members]
+        end
+
+        def object_signature(item, depth)
+          variables = item.instance_variables.sort.map do |name|
+            [name, signature_value(item.instance_variable_get(name), depth + 1)]
+          end
+          [:object, item.class.name, item.object_id, variables]
+        end
+
+        def range_signature(range, depth)
+          [
+            :range,
+            reference_id(range),
+            signature_value(range.begin, depth + 1),
+            signature_value(range.end, depth + 1),
+            range.exclude_end?
+          ]
+        end
+
+        def unsupported!(item)
+          raise WorkflowError,
+                "split-step transition contract contains unsupported value #{item.class}; " \
+                "use primitives, Hash, Array, Set, Struct, Data, Range, Module, or Proc"
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/split_step_persistence.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "securerandom"
+
+require_relative "split_step_persistence/subclass_boundary"
+require_relative "split_step_persistence/inheritance"
+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/boundary"
+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/execution"
+require_relative "split_step_persistence/checkpoint_state"
+require_relative "split_step_persistence/checkpoint"
+require_relative "split_step_persistence/payloads"
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      NO_SPLIT_TRANSITION = Object.new.freeze
+
+      def self.prepended(base)
+        base.singleton_class.prepend(Inheritance)
+      end
+
+      include Boundary
+      include StateSnapshot
+      include PreparationClaim
+      include PreparationRecovery
+      include Preparation
+      include Execution
+      include CheckpointState
+      include Checkpoint
+      include Payloads
+    end
+  end
+end

data/lib/smith/workflow.rb

@@ -16,6 +16,7 @@ module Smith
     include DSL
     include Persistence
     include Durability
+    prepend SplitStepPersistence
     include GuardrailIntegration
     include BudgetIntegration
     include EventIntegration
@@ -104,6 +105,12 @@ module Smith
       # workflows with the marker set raise
       # Smith::StepInProgressOnRestore. Lax mode leaves it false.
       @step_in_progress = false
+      # Process-local phase for the split-step persistence API. This is not
+      # serialized: strict restore rejects the durable step_in_progress marker
+      # before an uncertain step can be resumed.
+      @split_step_phase = nil
+      @split_step_transition_name = nil
+      @split_step_mutex = Mutex.new
       # Set of context keys recorded via deterministic step write_context
       # writes. Used by persist :auto Context mode to compute the
       # persisted-context slice. Seeded from the Context class's
@@ -119,10 +126,12 @@ module Smith
     end
 
     def advance!
+      advance_claim = SplitStepPersistence.instance_method(:claim_split_step_advance!).bind_call(self)
       ensure_transition_budget!
       @step_work_started = false
 
-      transition = resolve_transition
+      transition = SplitStepPersistence.instance_method(:resolve_split_step_advance_transition).bind_call(self)
+      transition = resolve_transition if transition.equal?(SplitStepPersistence::NO_SPLIT_TRANSITION)
       return if transition.nil?
 
       @step_work_started = true
@@ -139,9 +148,12 @@ module Smith
       step_result = { transition: e.requested_name, from: origin_state, to: @state, error: e }
       record_step_snapshot(step_result)
       step_result
+    ensure
+      SplitStepPersistence.instance_method(:release_split_step_advance!).bind_call(self, advance_claim) if advance_claim
     end
 
     def run!
+      SplitStepPersistence.instance_method(:ensure_split_step_execution_allowed!).bind_call(self)
       steps = []
       until terminal?
         step = advance!

data/lib/smith.rb

@@ -241,6 +241,7 @@ require_relative "smith/workflow/worker_execution"
 require_relative "smith/workflow/dsl"
 require_relative "smith/workflow/persistence"
 require_relative "smith/workflow/durability"
+require_relative "smith/workflow/split_step_persistence"
 require_relative "smith/workflow/guardrail_integration"
 require_relative "smith/workflow/budget_integration"
 require_relative "smith/workflow/event_integration"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: smith-agents
 version: !ruby/object:Gem::Version
-  version: 0.4.3
+  version: 0.4.5
 platform: ruby
 authors:
 - Samuel Ralak
@@ -179,12 +179,17 @@ files:
 - lib/smith/models/normalizer.rb
 - lib/smith/models/profile.rb
 - lib/smith/persistence_adapters.rb
+- lib/smith/persistence_adapters/active_record_connection_errors.rb
+- lib/smith/persistence_adapters/active_record_initial_write.rb
 - lib/smith/persistence_adapters/active_record_store.rb
 - lib/smith/persistence_adapters/cache_store.rb
 - lib/smith/persistence_adapters/memory.rb
+- lib/smith/persistence_adapters/payload_version.rb
 - lib/smith/persistence_adapters/rails_cache.rb
 - lib/smith/persistence_adapters/redis_store.rb
+- lib/smith/persistence_adapters/redis_versioned_write.rb
 - lib/smith/persistence_adapters/retry.rb
+- lib/smith/persistence_adapters/version_expectation.rb
 - lib/smith/pricing.rb
 - lib/smith/providers/openai/responses.rb
 - lib/smith/providers/openai/routing.rb
@@ -261,6 +266,22 @@ files:
 - lib/smith/workflow/retry_execution.rb
 - lib/smith/workflow/router.rb
 - lib/smith/workflow/run_result.rb
+- lib/smith/workflow/split_step_persistence.rb
+- lib/smith/workflow/split_step_persistence/boundary.rb
+- lib/smith/workflow/split_step_persistence/checkpoint.rb
+- lib/smith/workflow/split_step_persistence/checkpoint_state.rb
+- lib/smith/workflow/split_step_persistence/execution.rb
+- lib/smith/workflow/split_step_persistence/inheritance.rb
+- lib/smith/workflow/split_step_persistence/payloads.rb
+- lib/smith/workflow/split_step_persistence/preparation.rb
+- lib/smith/workflow/split_step_persistence/preparation_claim.rb
+- lib/smith/workflow/split_step_persistence/preparation_recovery.rb
+- lib/smith/workflow/split_step_persistence/state_snapshot.rb
+- lib/smith/workflow/split_step_persistence/subclass_boundary.rb
+- lib/smith/workflow/split_step_persistence/transition_contract.rb
+- lib/smith/workflow/split_step_persistence/transition_contract_freezer.rb
+- lib/smith/workflow/split_step_persistence/transition_contract_signature.rb
+- lib/smith/workflow/split_step_persistence/transition_contract_structured_values.rb
 - lib/smith/workflow/transition.rb
 - lib/smith/workflow/usage_entry.rb
 - lib/smith/workflow/worker_execution.rb