smith-agents 0.4.3 → 0.4.5

data/lib/smith/persistence_adapters/cache_store.rb

@@ -17,7 +17,7 @@ module Smith
 
       def initialize(store:, namespace: "smith")
         @store_source = store
-        @namespace = namespace
+        @namespace = namespace.nil? ? nil : namespace.to_s.dup.freeze
       end
 
       def store(key, payload, ttl: Smith.config.persistence_ttl)
@@ -42,6 +42,8 @@ module Smith
         end
       end
 
+      def transaction_open? = false
+
       def backend_name
         backend.class.name || backend.class.to_s
       end

data/lib/smith/persistence_adapters/memory.rb

@@ -23,21 +23,16 @@ module Smith
 
       def store(key, payload, ttl: Smith.config.persistence_ttl)
         @monitor.synchronize do
-          @store[key] = { payload: payload, expires_at: ttl ? Time.now.utc + ttl : nil }
+          @store[key] = entry_for(payload, ttl)
         end
       end
 
       def fetch(key)
         @monitor.synchronize do
-          entry = @store[key]
+          entry = live_entry(key)
           next nil if entry.nil?
 
-          if entry[:expires_at] && entry[:expires_at] < Time.now.utc
-            @store.delete(key)
-            next nil
-          end
-
-          entry[:payload]
+          copy_payload(entry[:payload])
         end
       end
 
@@ -48,6 +43,8 @@ module Smith
         end
       end
 
+      def transaction_open? = false
+
       def record_heartbeat(key, ttl: Smith.config.persistence_ttl)
         @monitor.synchronize do
           @heartbeats[key] = { at: Time.now.utc, expires_at: ttl ? Time.now.utc + ttl : nil }
@@ -76,7 +73,7 @@ module Smith
       # across all versioned adapters).
       def store_versioned(key, payload, expected_version:, ttl: Smith.config.persistence_ttl)
         @monitor.synchronize do
-          entry = @store[key]
+          entry = live_entry(key)
           if entry
             current_version = parse_version(entry[:payload])
             if current_version != expected_version
@@ -84,8 +81,10 @@ module Smith
                 key: key, expected: expected_version, actual: current_version
               )
             end
+          else
+            VersionExpectation.validate_missing!(key, expected_version)
           end
-          @store[key] = { payload: payload, expires_at: ttl ? Time.now.utc + ttl : nil }
+          @store[key] = entry_for(payload, ttl)
         end
       end
 
@@ -95,10 +94,27 @@ module Smith
 
       private
 
+      def live_entry(key)
+        entry = @store[key]
+        return unless entry
+        return entry unless entry[:expires_at] && entry[:expires_at] < Time.now.utc
+
+        @store.delete(key)
+        nil
+      end
+
+      def entry_for(payload, ttl)
+        { payload: copy_payload(payload), expires_at: ttl ? Time.now.utc + ttl : nil }
+      end
+
+      def copy_payload(payload)
+        payload.dup
+      rescue TypeError
+        payload
+      end
+
       def parse_version(payload)
-        JSON.parse(payload).fetch("persistence_version", 0)
-      rescue JSON::ParserError
-        0
+        PayloadVersion.call(payload)
       end
     end
   end

data/lib/smith/persistence_adapters/payload_version.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Smith
+  module PersistenceAdapters
+    module PayloadVersion
+      module_function
+
+      def call(payload)
+        document = payload.is_a?(String) ? JSON.parse(payload) : payload
+        raise TypeError, "persisted workflow payload must be a JSON object" unless document.is_a?(Hash)
+
+        version = document.fetch("persistence_version", 0)
+        unless version.is_a?(Integer) && version >= 0
+          raise TypeError, "persisted workflow persistence_version must be a non-negative integer"
+        end
+
+        version
+      rescue JSON::ParserError
+        0
+      end
+    end
+  end
+end

data/lib/smith/persistence_adapters/redis_store.rb

@@ -26,7 +26,7 @@ module Smith
 
       def initialize(redis:, namespace: "smith")
         @redis_source = redis
-        @namespace = namespace
+        @namespace = namespace.nil? ? nil : namespace.to_s.dup.freeze
       end
 
       def store(key, payload, ttl: Smith.config.persistence_ttl)
@@ -51,6 +51,8 @@ module Smith
         end
       end
 
+      def transaction_open? = false
+
       def record_heartbeat(key, ttl: Smith.config.persistence_ttl)
         Retry.with_retries(operation: :record_heartbeat, transient: self.class.transient_errors) do
           iso = Time.now.utc.iso8601
@@ -78,32 +80,14 @@ module Smith
       # OR on EXEC failure (WATCH detected concurrent write).
       def store_versioned(key, payload, expected_version:, ttl: Smith.config.persistence_ttl)
         Retry.with_retries(operation: :store_versioned, transient: self.class.transient_errors) do
-          namespaced_key = namespaced(key)
-          result = client.watch(namespaced_key) do
-            current = client.get(namespaced_key)
-            if current && (current_version = parse_version(current)) != expected_version
-              client.unwatch
-              raise Smith::PersistenceVersionConflict.new(
-                key: key, expected: expected_version, actual: current_version
-              )
-            end
-
-            client.multi do |tx|
-              if ttl
-                tx.set(namespaced_key, payload, ex: ttl)
-              else
-                tx.set(namespaced_key, payload)
-              end
-            end
-          end
-
-          if result.nil?
-            raise Smith::PersistenceVersionConflict.new(
-              key: key, expected: expected_version, actual: :concurrent
-            )
-          end
-
-          result
+          RedisVersionedWrite.new(
+            client: client,
+            key: key,
+            storage_key: namespaced(key),
+            payload: payload,
+            expected_version: expected_version,
+            ttl: ttl
+          ).call
         end
       end
 
@@ -125,12 +109,6 @@ module Smith
       def namespaced_heartbeat(key)
         [@namespace, "heartbeat", key].compact.join(":")
       end
-
-      def parse_version(payload)
-        JSON.parse(payload).fetch("persistence_version", 0)
-      rescue JSON::ParserError
-        0
-      end
     end
   end
 end

data/lib/smith/persistence_adapters/redis_versioned_write.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  module PersistenceAdapters
+    class RedisVersionedWrite
+      extend Dry::Initializer
+
+      option :client
+      option :key
+      option :storage_key
+      option :payload
+      option :expected_version
+      option :ttl
+
+      def call
+        result = client.watch(storage_key) do
+          current = client.get(storage_key)
+          validate_current!(current)
+          enqueue_write
+        end
+        return result unless result.nil?
+
+        raise PersistenceVersionConflict.new(
+          key: key,
+          expected: expected_version,
+          actual: :concurrent
+        )
+      end
+
+      private
+
+      def validate_current!(current)
+        return VersionExpectation.validate_missing!(key, expected_version) unless current
+
+        current_version = PayloadVersion.call(current)
+        return if current_version == expected_version
+
+        client.unwatch
+        raise PersistenceVersionConflict.new(
+          key: key,
+          expected: expected_version,
+          actual: current_version
+        )
+      end
+
+      def enqueue_write
+        client.multi do |transaction|
+          options = ttl ? { ex: ttl } : {}
+          transaction.set(storage_key, payload, **options)
+        end
+      end
+    end
+  end
+end

data/lib/smith/persistence_adapters/version_expectation.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Smith
+  module PersistenceAdapters
+    module VersionExpectation
+      module_function
+
+      def validate_missing!(key, expected_version)
+        return if expected_version.is_a?(Integer) && expected_version.zero?
+
+        raise Smith::PersistenceVersionConflict.new(
+          key: key,
+          expected: expected_version,
+          actual: :missing
+        )
+      end
+    end
+  end
+end

data/lib/smith/persistence_adapters.rb

@@ -1,8 +1,13 @@
 # frozen_string_literal: true
 
 require "monitor"
+require_relative "persistence_adapters/active_record_connection_errors"
+require_relative "persistence_adapters/active_record_initial_write"
+require_relative "persistence_adapters/payload_version"
+require_relative "persistence_adapters/version_expectation"
 require_relative "persistence_adapters/cache_store"
 require_relative "persistence_adapters/rails_cache"
+require_relative "persistence_adapters/redis_versioned_write"
 require_relative "persistence_adapters/redis_store"
 require_relative "persistence_adapters/active_record_store"
 require_relative "persistence_adapters/memory"
@@ -23,7 +28,7 @@ module Smith
     # check support via `supports?(adapter, capability)` and fall back
     # gracefully (e.g., Workflow#persist! warns once and uses plain
     # `store` when `store_versioned` is missing).
-    OPTIONAL_METHODS = %i[store_versioned record_heartbeat last_heartbeat].freeze
+    OPTIONAL_METHODS = %i[store_versioned record_heartbeat last_heartbeat transaction_open?].freeze
 
     def self.resolve(adapter, **options)
       return nil if adapter.nil?

data/lib/smith/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Smith
-  VERSION = "0.4.3"
+  VERSION = "0.4.5"
 end

data/lib/smith/workflow/durability.rb

@@ -294,6 +294,7 @@ module Smith
         previous_version = @persistence_version || 0
         next_version = previous_version + 1
         payload = JSON.generate(to_state.merge(persistence_version: next_version))
+        payload = yield(payload, next_version) if block_given?
 
         dispatch_store!(store, resolved_key, payload, previous_version: previous_version)
 

data/lib/smith/workflow/persistence.rb

@@ -48,7 +48,7 @@ module Smith
           # workflow class opts into idempotency_mode :strict. Restore
           # raises Smith::StepInProgressOnRestore if true under strict
           # mode. Lax mode leaves this false and never raises.
-          step_in_progress: @step_in_progress || false,
+          step_in_progress: @step_in_progress || !@split_step_phase.nil?,
           # Keys recorded via DeterministicStep#write_context. Used by
           # persist :auto Context mode to scope the persisted context
           # slice. Always emitted (sorted for stable diffing) so
@@ -62,6 +62,7 @@ module Smith
       def restore_state(hash)
         migrated = migrate_if_needed(hash)
         normalized = normalize_persisted_state(migrated)
+        persistence_version = validated_persistence_version(normalized)
         restore_persisted_keys(normalized)
         restore_core_fields(normalized)
         @persistence_key = normalized[:persistence_key]
@@ -87,7 +88,7 @@ module Smith
         # Backward-compat: pre-versioning payloads have no key, restore to 0
         # so the first persist! after restore expects version 0 (matches
         # the original store from the legacy adapter contract).
-        @persistence_version = normalized[:persistence_version] || 0
+        @persistence_version = persistence_version
         # Preserve the seed digest from the persisted payload so it
         # round-trips on subsequent persists. validate_seed_digest!
         # compares this against a fresh evaluation of the seed builder
@@ -98,9 +99,18 @@ module Smith
         # round-trips it. validate_step_in_progress! enforces strict
         # mode by raising if the marker is set on restore.
         @step_in_progress = normalized[:step_in_progress] || false
+        @split_step_mutex = Mutex.new
         validate_step_in_progress!(normalized) if self.class.idempotency_mode == :strict
       end
 
+      def validated_persistence_version(normalized)
+        version = normalized.fetch(:persistence_version, 0)
+        return version if version.is_a?(Integer) && version >= 0
+
+        raise Smith::SerializationError,
+              "persisted workflow persistence_version must be a non-negative integer, got #{version.inspect}"
+      end
+
       def validate_step_in_progress!(normalized)
         return unless normalized[:step_in_progress] == true
 

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

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      module Boundary
+        def run_persisted!(...)
+          ensure_no_split_step_boundary!
+          super
+        end
+
+        def advance_persisted!(...)
+          ensure_no_split_step_boundary!
+          super
+        end
+
+        def clear_persisted!(...)
+          ensure_no_split_step_boundary!
+          super
+        end
+
+        def initialize_copy(source)
+          super
+          @split_step_mutex = Mutex.new
+          return unless source.instance_variable_get(:@split_step_phase)
+
+          @split_step_phase = :copied_boundary
+          @split_step_token = nil
+          @split_step_execution_thread = nil
+          @split_step_advance_permit = false
+          @split_step_preparation_thread = nil
+          @split_step_persist_permit = false
+        end
+        private :initialize_copy
+
+        private
+
+        def ensure_split_step_execution_allowed!
+          @split_step_mutex.synchronize do
+            return unless @split_step_phase
+
+            if split_step_advance_permitted?
+              @split_step_advance_permit = false
+              return
+            end
+          end
+
+          raise WorkflowError, "use execute_prepared_step! for the active split-step boundary"
+        end
+
+        def claim_split_step_advance!
+          @split_step_mutex.synchronize do
+            unless @split_step_phase
+              @split_step_phase = :ordinary_execution
+              return :ordinary
+            end
+            if split_step_advance_permitted?
+              @split_step_advance_permit = false
+              return :split_step
+            end
+
+            raise WorkflowError, "use execute_prepared_step! for the active split-step boundary"
+          end
+        end
+
+        def release_split_step_advance!(claim)
+          return unless claim == :ordinary
+
+          @split_step_mutex.synchronize do
+            @split_step_phase = nil if @split_step_phase == :ordinary_execution
+          end
+        end
+
+        def ensure_no_split_step_boundary!
+          return unless @split_step_phase
+
+          raise WorkflowError, "a split-step persistence boundary is already active"
+        end
+
+        def guard_split_step_subclass_execution!
+          @split_step_mutex.synchronize do
+            return unless @split_step_phase
+            return if split_step_advance_permitted?
+          end
+
+          raise WorkflowError, "use execute_prepared_step! for the active split-step boundary"
+        end
+
+        def split_step_advance_permitted?
+          @split_step_phase == :executing &&
+            @split_step_execution_thread.equal?(Thread.current) &&
+            @split_step_advance_permit
+        end
+
+        def clear_split_step_boundary!
+          @split_step_phase = nil
+          @split_step_transition_name = nil
+          @split_step_transition = nil
+          @split_step_transition_signature = nil
+          @split_step_origin_state = nil
+          @split_step_token = nil
+          @split_step_persistence_key = nil
+          @split_step_adapter = nil
+          remove_instance_variable(:@split_step_persistence_ttl) if
+            instance_variable_defined?(:@split_step_persistence_ttl)
+          @split_step_preparation_payload = nil
+          @split_step_checkpoint_digest = nil
+          @split_step_checkpoint_version = nil
+          @split_step_preparation_thread = nil
+          @split_step_persist_permit = false
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      module Checkpoint
+        def complete_persisted_step!
+          completion_claimed = false
+          previous_phase = claim_split_step_completion!
+          completion_claimed = true
+          completed = false
+          payload = @split_step_adapter.fetch(@split_step_persistence_key)
+          unless persisted_split_step_checkpoint?(payload)
+            recover_rolled_back_split_step_checkpoint!(payload)
+            raise WorkflowError, "the persisted split-step checkpoint is not committed"
+          end
+
+          @split_step_mutex.synchronize do
+            @persistence_version = @split_step_checkpoint_version
+            clear_step_in_progress!
+            clear_split_step_boundary!
+          end
+          completed = true
+          self
+        ensure
+          restore_incomplete_checkpoint!(previous_phase) if completion_claimed && !completed
+        end
+
+        def persist!(key = nil, adapter: Smith.persistence_adapter)
+          checkpoint_claimed = false
+          resolved_key, store = resolve_split_step_target(key, adapter)
+          checkpoint_claimed = claim_split_step_checkpoint!
+          result = super(resolved_key, adapter: store) do |payload, next_version|
+            capture_split_step_payload!(payload, next_version, checkpoint_claimed:)
+          end
+          @split_step_mutex.synchronize { @split_step_phase = :checkpointed } if checkpoint_claimed
+          result
+        rescue StandardError
+          mark_split_step_checkpoint_unknown! if checkpoint_claimed
+          raise
+        end
+
+        private
+
+        def resolve_split_step_target(key, adapter)
+          resolved_key = if @split_step_persistence_key
+                           candidate = candidate_split_step_persistence_key(key)
+                           if candidate.equal?(@split_step_persistence_key)
+                             candidate
+                           else
+                             normalize_split_step_persistence_key(candidate)
+                           end
+                         else
+                           resolve_persistence_key!(key)
+                         end
+          store = persistence_adapter!(adapter)
+          validate_split_step_target!(resolved_key, store)
+          resolved_key = @split_step_persistence_key if @split_step_persistence_key
+          @persistence_key = resolved_key
+          [resolved_key, store]
+        end
+
+        def claim_split_step_checkpoint!
+          @split_step_mutex.synchronize do
+            if split_step_preparation_persist_permitted?
+              @split_step_persist_permit = false
+              return false
+            end
+            return false unless @split_step_phase
+
+            if %i[executed checkpoint_retryable].include?(@split_step_phase)
+              @split_step_phase = :checkpointing
+              return true
+            end
+
+            raise WorkflowError, "the active split-step boundary cannot be checkpointed"
+          end
+        end
+
+        def split_step_preparation_persist_permitted?
+          @split_step_phase == :preparing &&
+            @split_step_preparation_thread.equal?(Thread.current) &&
+            @split_step_persist_permit
+        end
+
+        def validate_split_step_target!(key, adapter)
+          return unless @split_step_persistence_key
+          return if key == @split_step_persistence_key && adapter.equal?(@split_step_adapter)
+
+          raise WorkflowError, "the split-step persistence target cannot change"
+        end
+
+        def capture_split_step_payload!(payload, next_version, checkpoint_claimed:)
+          validate_split_step_marker!(payload, expected: true) if @split_step_phase == :preparing || checkpoint_claimed
+          if @split_step_phase == :preparing
+            payload = split_step_preparation_payload(payload)
+            @split_step_preparation_payload = payload
+          end
+          return payload unless checkpoint_claimed
+
+          checkpoint_payload = split_step_checkpoint_payload(payload)
+          checkpoint_digest = Digest::SHA256.hexdigest(checkpoint_payload)
+          validate_split_step_retry_payload!(checkpoint_digest)
+          @split_step_checkpoint_digest = checkpoint_digest
+          @split_step_checkpoint_version = next_version
+          checkpoint_payload
+        end
+
+        def validate_split_step_retry_payload!(checkpoint_digest)
+          return unless @split_step_checkpoint_digest
+          return if @split_step_checkpoint_digest == checkpoint_digest
+
+          @split_step_mutex.synchronize do
+            @split_step_phase = :checkpoint_retryable if @split_step_phase == :checkpointing
+          end
+          raise WorkflowError, "the reconciled split-step checkpoint payload changed"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      module CheckpointState
+        private
+
+        def claim_split_step_completion!
+          @split_step_mutex.synchronize do
+            unless %i[checkpoint_unknown checkpointed].include?(@split_step_phase)
+              raise WorkflowError, "no persisted split-step checkpoint is awaiting completion"
+            end
+            if Smith::PersistenceAdapters.supports?(@split_step_adapter, :transaction_open?) &&
+               @split_step_adapter.transaction_open?
+              raise WorkflowError, "the split-step checkpoint transaction is still open"
+            end
+
+            previous_phase = @split_step_phase
+            @split_step_phase = :confirming_checkpoint
+            previous_phase
+          end
+        end
+
+        def restore_incomplete_checkpoint!(previous_phase)
+          @split_step_mutex.synchronize do
+            @split_step_phase = previous_phase if @split_step_phase == :confirming_checkpoint
+          end
+        end
+
+        def recover_rolled_back_split_step_checkpoint!(payload)
+          return unless persisted_split_step_payload?(payload, @split_step_preparation_payload)
+
+          preparation_version = JSON.parse(payload).fetch("persistence_version")
+          @split_step_mutex.synchronize do
+            return unless @split_step_phase == :confirming_checkpoint
+
+            @persistence_version = preparation_version
+            @split_step_phase = :checkpoint_retryable
+          end
+        end
+
+        def mark_split_step_checkpoint_unknown!
+          @split_step_mutex.synchronize do
+            @split_step_phase = :checkpoint_unknown if @split_step_phase == :checkpointing
+          end
+        end
+      end
+    end
+  end
+end