smith-agents 0.4.5 → 0.5.0

data/lib/smith/workflow/persistence.rb

@@ -10,17 +10,17 @@ module Smith
           class: self.class.name,
           state: @state,
           persistence_key: @persistence_key,
-          context: persisted_context,
+          context: snapshot_value(persisted_context),
           budget_consumed: ledger_consumed,
           step_count: @step_count,
           execution_namespace: @execution_namespace,
           created_at: @created_at,
           updated_at: @updated_at,
           next_transition_name: @next_transition_name,
-          session_messages: @session_messages || [],
+          session_messages: snapshot_session_messages,
           total_cost: @total_cost || 0.0,
           total_tokens: @total_tokens || 0,
-          tool_results: @tool_results || [],
+          tool_results: snapshot_value(@tool_results || []),
           outcome: snapshot_outcome,
           # Durable usage fields. All wrapped in
           # snapshot_value so non-JSON-safe runtime values (e.g.
@@ -38,6 +38,11 @@ module Smith
           # stored value lags the workflow's current
           # persistence_schema_version.
           schema_version: self.class.persistence_schema_version,
+          # Host-supplied digest of the complete executable workflow
+          # definition. Smith does not derive this from Ruby Proc or VM
+          # internals; hosts that need restart-safe prepared-step recovery
+          # must bind it to their immutable code/package identity.
+          definition_digest: effective_definition_digest,
           # SHA256 digest of the seed_messages produced at this
           # workflow's construction. Stays stable across persist/restore
           # cycles so seed_validation can detect when the seed builder
@@ -59,7 +64,9 @@ module Smith
 
       private
 
-      def restore_state(hash)
+      def restore_state(hash, allow_step_in_progress: false)
+        validate_raw_step_in_progress!(hash) if
+          self.class.idempotency_mode == :strict && !allow_step_in_progress
         migrated = migrate_if_needed(hash)
         normalized = normalize_persisted_state(migrated)
         persistence_version = validated_persistence_version(normalized)
@@ -89,6 +96,7 @@ module Smith
         # so the first persist! after restore expects version 0 (matches
         # the original store from the legacy adapter contract).
         @persistence_version = persistence_version
+        validate_definition_digest!(normalized)
         # 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
@@ -100,7 +108,8 @@ module Smith
         # 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
+        validate_step_in_progress!(normalized) if
+          self.class.idempotency_mode == :strict && !allow_step_in_progress
       end
 
       def validated_persistence_version(normalized)
@@ -111,6 +120,18 @@ module Smith
               "persisted workflow persistence_version must be a non-negative integer, got #{version.inspect}"
       end
 
+      def validate_definition_digest!(normalized)
+        stored = normalized[:definition_digest]
+        return if stored.nil?
+
+        unless Smith::Types::Sha256Hex.valid?(stored)
+          raise Smith::SerializationError, "persisted workflow definition_digest must be a SHA-256 hex digest"
+        end
+        return if stored == self.class.definition_digest
+
+        raise Smith::WorkflowError, "persisted workflow definition does not match the current workflow class"
+      end
+
       def validate_step_in_progress!(normalized)
         return unless normalized[:step_in_progress] == true
 
@@ -120,6 +141,14 @@ module Smith
         )
       end
 
+      def validate_raw_step_in_progress!(state)
+        return unless state.is_a?(Hash)
+
+        marker = state[:step_in_progress] || state["step_in_progress"]
+        persistence_key = state[:persistence_key] || state["persistence_key"]
+        validate_step_in_progress!(step_in_progress: marker, persistence_key:)
+      end
+
       def validate_seed_digest!(normalized)
         stored_digest = normalized[:seed_digest]
         return if stored_digest.nil?
@@ -256,13 +285,13 @@ module Smith
       end
 
       def normalize_persisted_state(hash)
-        normalized = hash.transform_keys { |k| k.is_a?(String) ? k.to_sym : k }
+        normalized = snapshot_value(hash).transform_keys { |k| k.is_a?(String) ? k.to_sym : k }
+        normalized[:outcome] = symbolize_value(normalized[:outcome]) if normalized[:outcome].is_a?(Hash)
         normalize_symbol_fields!(normalized)
         normalize_nested_hashes!(normalized)
         normalize_session_messages!(normalized)
         normalize_tool_results!(normalized)
         normalize_usage_entries!(normalized)
-        normalized[:outcome] = symbolize_value(normalized[:outcome]) if normalized[:outcome].is_a?(Hash)
         normalized
       end
 
@@ -318,7 +347,7 @@ module Smith
         return unless normalized[:session_messages].is_a?(Array)
 
         normalized[:session_messages] = normalized[:session_messages].map do |msg|
-          msg.is_a?(Hash) ? symbolize_keys(msg) : msg
+          msg.is_a?(Hash) ? symbolize_keys(snapshot_value(msg)) : snapshot_value(msg)
         end
       end
 

data/lib/smith/workflow/prepared_step.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "dry-struct"
+require "json"
+
+require_relative "../types"
+
+module Smith
+  class Workflow
+    class PreparedStep < Dry::Struct
+      ATTRIBUTES = %i[
+        token transition from persistence_key persistence_version step_number preparation_digest definition_digest
+      ].freeze
+      DIGEST_PATTERN = /\A[0-9a-f]{64}\z/
+      MAX_COUNTER_VALUE = (2**63) - 1
+      MAX_ATTRIBUTE_ENTRIES = 16
+      MAX_SERIALIZED_BYTES = 4 * 1024
+      UUID_PATTERN = /\A[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\z/i
+      OwnedString = Types::String.constructor do |value|
+        value.is_a?(String) ? value.dup.freeze : value
+      end
+      private_constant :OwnedString
+
+      attribute :token, OwnedString.constrained(format: UUID_PATTERN)
+      attribute :transition, OwnedString.constrained(min_size: 1)
+      attribute :from, OwnedString.constrained(min_size: 1)
+      attribute :persistence_key, OwnedString.constrained(min_size: 1)
+      attribute :persistence_version, Types::Integer.constrained(gteq: 1, lteq: MAX_COUNTER_VALUE)
+      attribute :step_number, Types::Integer.constrained(gteq: 1, lteq: MAX_COUNTER_VALUE)
+      attribute :preparation_digest, OwnedString.constrained(format: DIGEST_PATTERN)
+      attribute? :definition_digest, Types::Sha256Hex.optional
+
+      def self.deserialize(value)
+        attributes = parse_attributes(value)
+        normalized = normalize_attributes(attributes)
+        validate_attributes!(normalized)
+        validate_bounded_values!(normalized)
+        new(normalized)
+      rescue JSON::ParserError, TypeError => e
+        raise ArgumentError, "prepared step is invalid: #{e.message}"
+      end
+
+      def self.validate_attributes!(attributes)
+        unknown = attributes.keys - ATTRIBUTES
+        missing = ATTRIBUTES.first(7) - attributes.keys
+        raise ArgumentError, "prepared step contains unknown attributes: #{unknown.join(", ")}" if unknown.any?
+        raise ArgumentError, "prepared step is missing attributes: #{missing.join(", ")}" if missing.any?
+      end
+      private_class_method :validate_attributes!
+
+      def self.parse_attributes(value)
+        return validate_attribute_container!(value) if value.is_a?(Hash)
+        unless value.is_a?(String) && value.bytesize <= MAX_SERIALIZED_BYTES
+          raise ArgumentError, "prepared step must be a Hash or bounded JSON object"
+        end
+
+        parsed = JSON.parse(value)
+        return validate_attribute_container!(parsed) if parsed.is_a?(Hash)
+
+        raise ArgumentError, "prepared step JSON must contain an object"
+      end
+      private_class_method :parse_attributes
+
+      def self.validate_attribute_container!(attributes)
+        unless attributes.size <= MAX_ATTRIBUTE_ENTRIES
+          raise ArgumentError, "prepared step contains too many attributes"
+        end
+        unless attributes.keys.all? { |key| key.is_a?(String) || key.is_a?(Symbol) }
+          raise ArgumentError, "prepared step attribute names must be strings or symbols"
+        end
+
+        attributes
+      end
+      private_class_method :validate_attribute_container!
+
+      def self.validate_bounded_values!(attributes)
+        bytes = attributes.sum { |key, value| bounded_attribute_bytes(key, value) }
+        return attributes if bytes <= MAX_SERIALIZED_BYTES
+
+        raise ArgumentError, "prepared step Hash exceeds maximum bytes"
+      end
+      private_class_method :validate_bounded_values!
+
+      def self.bounded_attribute_bytes(key, value)
+        validate_scalar_value!(value)
+        key.to_s.bytesize + (value.is_a?(String) ? value.bytesize : 8)
+      end
+      private_class_method :bounded_attribute_bytes
+
+      def self.validate_scalar_value!(value)
+        unless value.nil? || value.is_a?(String) || value.is_a?(Integer)
+          raise ArgumentError, "prepared step attribute values must be scalar"
+        end
+        return unless value.is_a?(Integer) && !value.between?(1, MAX_COUNTER_VALUE)
+
+        raise ArgumentError, "prepared step integer values must fit a positive signed 64-bit counter"
+      end
+      private_class_method :validate_scalar_value!
+
+      def self.normalize_attributes(attributes)
+        normalized = attributes.each_with_object({}) do |(key, nested), result|
+          normalized_key = key.respond_to?(:to_sym) ? key.to_sym : key
+          raise ArgumentError, "prepared step contains duplicate attributes" if result.key?(normalized_key)
+
+          result[normalized_key] = nested
+        end
+        normalized[:definition_digest] = nil unless normalized.key?(:definition_digest)
+        normalized
+      end
+      private_class_method :normalize_attributes
+
+      def initialize(attributes)
+        owned = attributes.dup
+        digest = owned[:definition_digest] || owned["definition_digest"]
+        owned[:definition_digest] = digest.dup.freeze if digest.is_a?(String)
+        super(owned)
+        self.attributes.freeze
+        freeze
+      end
+    end
+  end
+end

data/lib/smith/workflow/prepared_step_dispatch.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "dry-struct"
+require "json"
+
+require_relative "../types"
+require_relative "prepared_step"
+
+module Smith
+  class Workflow
+    class PreparedStepDispatch < Dry::Struct
+      ATTRIBUTES = %i[prepared_step token dispatch_digest].freeze
+      MAX_ATTRIBUTE_ENTRIES = 8
+      MAX_SERIALIZED_BYTES = 8 * 1024
+      OwnedString = Types::String.constructor do |value|
+        value.is_a?(String) ? value.dup.freeze : value
+      end
+      private_constant :OwnedString
+
+      attribute :prepared_step, Types.Instance(PreparedStep)
+      attribute :token, OwnedString.constrained(format: PreparedStep::UUID_PATTERN)
+      attribute :dispatch_digest, OwnedString.constrained(format: PreparedStep::DIGEST_PATTERN)
+
+      def self.deserialize(value)
+        attributes = parse_attributes(value)
+        normalized = normalize_attributes(attributes)
+        validate_attributes!(normalized)
+        normalized[:prepared_step] = PreparedStep.deserialize(normalized[:prepared_step])
+        new(normalized)
+      rescue JSON::ParserError, TypeError => e
+        raise ArgumentError, "prepared-step dispatch is invalid: #{e.message}"
+      end
+
+      def self.parse_attributes(value)
+        return value if value.is_a?(Hash) && bounded_hash?(value)
+        unless value.is_a?(String) && value.bytesize <= MAX_SERIALIZED_BYTES
+          raise ArgumentError, "prepared-step dispatch must be a bounded Hash or JSON object"
+        end
+
+        parsed = JSON.parse(value)
+        return parsed if parsed.is_a?(Hash) && bounded_hash?(parsed)
+
+        raise ArgumentError, "prepared-step dispatch JSON must contain a bounded object"
+      end
+      private_class_method :parse_attributes
+
+      def self.bounded_hash?(attributes)
+        return false unless attributes.size <= MAX_ATTRIBUTE_ENTRIES
+        return false unless attributes.keys.all? { |key| key.is_a?(String) || key.is_a?(Symbol) }
+
+        attributes.sum { |key, value| key.to_s.bytesize + bounded_value_bytes(value) } <= MAX_SERIALIZED_BYTES
+      end
+      private_class_method :bounded_hash?
+
+      def self.bounded_value_bytes(value)
+        return value.bytesize if value.is_a?(String)
+        return PreparedStep::MAX_SERIALIZED_BYTES if value.is_a?(Hash)
+
+        MAX_SERIALIZED_BYTES + 1
+      end
+      private_class_method :bounded_value_bytes
+
+      def self.normalize_attributes(attributes)
+        attributes.each_with_object({}) do |(key, value), result|
+          normalized_key = key.respond_to?(:to_sym) ? key.to_sym : key
+          raise ArgumentError, "prepared-step dispatch contains duplicate attributes" if result.key?(normalized_key)
+
+          result[normalized_key] = value
+        end
+      end
+      private_class_method :normalize_attributes
+
+      def self.validate_attributes!(attributes)
+        unknown = attributes.keys - ATTRIBUTES
+        missing = ATTRIBUTES - attributes.keys
+        raise ArgumentError, "prepared-step dispatch contains unknown attributes: #{unknown.join(", ")}" if unknown.any?
+        raise ArgumentError, "prepared-step dispatch is missing attributes: #{missing.join(", ")}" if missing.any?
+      end
+      private_class_method :validate_attributes!
+
+      def initialize(attributes)
+        super
+        self.attributes.freeze
+        freeze
+      end
+    end
+  end
+end

data/lib/smith/workflow/prepared_step_execution_authorization.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require_relative "prepared_step"
+require_relative "prepared_step_dispatch"
+require_relative "prepared_step_execution_scope"
+require_relative "split_step_persistence/execution_binding_snapshot"
+require_relative "../errors"
+
+module Smith
+  class Workflow
+    class PreparedStepExecutionAuthorization
+      attr_reader :prepared_step, :dispatch_claim
+
+      def initialize(prepared_step:, dispatch_claim:, execution_bindings:)
+        unless prepared_step.is_a?(PreparedStep)
+          raise ArgumentError, "prepared_step must be a Smith::Workflow::PreparedStep"
+        end
+        unless dispatch_claim.nil? || dispatch_claim.is_a?(PreparedStepDispatch)
+          raise ArgumentError, "dispatch_claim must be a Smith::Workflow::PreparedStepDispatch or nil"
+        end
+        if dispatch_claim && dispatch_claim.prepared_step.to_h != prepared_step.to_h
+          raise ArgumentError, "dispatch claim must belong to the prepared step"
+        end
+        unless execution_bindings.is_a?(SplitStepPersistence::ExecutionBindingSnapshot)
+          raise ArgumentError, "execution_bindings must be a Smith execution binding snapshot"
+        end
+
+        @prepared_step = prepared_step
+        @dispatch_claim = dispatch_claim
+        @execution_bindings = execution_bindings
+        @execution_scope = PreparedStepExecutionScope.new
+        @process_id = Process.pid
+        freeze
+      end
+
+      def issued_in_current_process? = @process_id == Process.pid
+
+      def fetch_agent!(...)
+        ensure_binding_access!
+
+        @execution_bindings.fetch!(...)
+      end
+
+      def each_agent_binding(&block)
+        ensure_binding_access!
+        raise ArgumentError, "a block is required to inspect captured agent bindings" unless block
+
+        @execution_bindings.each_agent_binding(&block)
+        self
+      end
+
+      def verify_workflow!(workflow_class)
+        ensure_active_execution!
+        @execution_bindings.verify_workflow!(workflow_class)
+      end
+
+      def active_in_current_execution?
+        issued_in_current_process? && @execution_scope.active_for?(Thread.current)
+      end
+
+      def initialize_copy(_source)
+        raise TypeError, "prepared-step execution authorizations cannot be copied"
+      end
+
+      def _dump(_depth)
+        raise TypeError, "prepared-step execution authorizations cannot be serialized"
+      end
+
+      def encode_with(_coder)
+        raise TypeError, "prepared-step execution authorizations cannot be serialized"
+      end
+
+      def init_with(_coder)
+        raise TypeError, "prepared-step execution authorizations cannot be deserialized"
+      end
+
+      def as_json(*)
+        raise TypeError, "prepared-step execution authorizations cannot be serialized"
+      end
+
+      def to_json(*)
+        raise TypeError, "prepared-step execution authorizations cannot be serialized"
+      end
+
+      private
+
+      def activate_execution!(thread)
+        ensure_current_process!
+        @execution_scope.activate!(thread)
+      end
+
+      def close_execution!(thread = nil)
+        @execution_scope.close!(thread)
+      end
+
+      def ensure_active_execution!
+        return if active_in_current_execution?
+
+        raise WorkflowError, "prepared-step execution authorization is outside its active execution"
+      end
+
+      def ensure_binding_access!
+        accessible = issued_in_current_process? && @execution_scope.binding_accessible_for?(Thread.current)
+        return if accessible
+
+        raise WorkflowError, "prepared-step execution authorization is outside its binding access scope"
+      end
+
+      def ensure_current_process!
+        return if issued_in_current_process?
+
+        raise WorkflowError, "prepared-step execution authorization belongs to another process"
+      end
+    end
+  end
+end

data/lib/smith/workflow/prepared_step_execution_result.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "dry-struct"
+
+require_relative "../types"
+require_relative "execution_result_snapshot"
+
+module Smith
+  class Workflow
+    class PreparedStepExecutionResult < Dry::Struct
+      attribute :status, Types::Symbol.enum(:succeeded, :failed)
+      attribute :step, Types::Hash
+      attribute? :error, Types.Instance(StandardError).optional
+
+      def self.from_step(step)
+        error = step[:error]
+        new(status: error ? :failed : :succeeded, step:, error:)
+      end
+
+      def initialize(attributes)
+        owned = attributes.dup
+        owned[:step] = snapshot(owned.fetch(:step), freeze_copy: true, preserved_error: owned[:error])
+        super(owned)
+        validate_shape!
+        self.attributes.freeze
+        freeze
+      end
+
+      def succeeded? = status == :succeeded
+      def failed? = status == :failed
+      def step_snapshot = snapshot(step, freeze_copy: false, preserved_error: error)
+
+      private
+
+      def snapshot(value, freeze_copy:, preserved_error:)
+        ExecutionResultSnapshot.new(value, freeze_copy:, preserved_error:).call
+      end
+
+      def validate_shape!
+        valid = if failed?
+                  error && step[:error].equal?(error)
+                else
+                  error.nil? && !step.key?(:error)
+                end
+        raise ArgumentError, "prepared-step execution result fields do not match status" unless valid
+      end
+    end
+  end
+end

data/lib/smith/workflow/prepared_step_execution_scope.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+
+module Smith
+  class Workflow
+    class PreparedStepExecutionScope
+      def initialize
+        @mutex = Mutex.new
+        @phase = :issued
+        @thread = nil
+      end
+
+      def activate!(thread)
+        @mutex.synchronize do
+          raise WorkflowError, "prepared-step execution scope is no longer available" unless @phase == :issued
+
+          @phase = :active
+          @thread = thread
+        end
+      end
+
+      def close!(thread = nil)
+        @mutex.synchronize do
+          if @phase == :active && thread && !@thread.equal?(thread)
+            raise WorkflowError, "prepared-step execution scope belongs to another thread"
+          end
+
+          @phase = :closed
+          @thread = nil
+        end
+      end
+
+      def active_for?(thread)
+        @mutex.synchronize { @phase == :active && @thread.equal?(thread) }
+      end
+
+      def binding_accessible_for?(thread)
+        @mutex.synchronize do
+          @phase == :issued || (@phase == :active && @thread.equal?(thread))
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/prepared_step_recovery.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "dry-struct"
+
+require_relative "../types"
+require_relative "prepared_step"
+require_relative "prepared_step_dispatch"
+
+module Smith
+  class Workflow
+    class PreparedStepRecovery < Dry::Struct
+      attribute :prepared_step, Types.Instance(PreparedStep)
+      attribute? :dispatch_claim, Types.Instance(PreparedStepDispatch).optional
+      attribute :execution_status, Types::Symbol.enum(:not_started)
+
+      def self.not_started(witness)
+        case witness
+        when PreparedStep
+          new(prepared_step: witness, dispatch_claim: nil, execution_status: :not_started)
+        when PreparedStepDispatch
+          new(prepared_step: witness.prepared_step, dispatch_claim: witness, execution_status: :not_started)
+        else
+          raise ArgumentError, "recovery witness must be a PreparedStep or PreparedStepDispatch"
+        end
+      end
+
+      def initialize(attributes)
+        super
+        if dispatch_claim && dispatch_claim.prepared_step.to_h != prepared_step.to_h
+          raise ArgumentError, "dispatch claim must belong to the prepared step"
+        end
+
+        self.attributes.freeze
+        freeze
+      end
+    end
+  end
+end

data/lib/smith/workflow/retry_execution.rb

@@ -9,6 +9,7 @@ module Smith
         config = transition.retry_config
         return run_guarded_step(transition) unless config
 
+        schedule = retry_schedule(config)
         attempt = 0
         begin
           attempt += 1
@@ -16,7 +17,7 @@ module Smith
         rescue StandardError => e
           raise unless retry_transition_error?(config, e, attempt)
 
-          sleep_for_retry(config, attempt)
+          sleep_for_retry(schedule, attempt)
           retry
         end
       end
@@ -32,20 +33,28 @@ module Smith
         end
       end
 
-      def sleep_for_retry(config, failed_attempt)
-        delay = retry_delay(config, failed_attempt)
+      def sleep_for_retry(schedule, failed_attempt)
+        delay = retry_delay(schedule, failed_attempt)
         sleep(delay) if delay.positive?
       end
 
-      def retry_delay(config, failed_attempt)
-        delay = config.fetch(:backoff) * (2**[failed_attempt - 1, 0].max)
-        max_delay = config[:max_delay]
-        delay = [delay, max_delay].min if max_delay
+      def retry_delay(config_or_schedule, failed_attempt)
+        schedule = if config_or_schedule.is_a?(ExponentialBackoff)
+                     config_or_schedule
+                   else
+                     retry_schedule(config_or_schedule)
+                   end
+        schedule.delay(failed_attempt, random: method(:rand))
+      end
 
-        jitter = config.fetch(:jitter)
-        delay += rand * jitter if jitter.positive?
-        delay = [delay, max_delay].min if max_delay
-        delay
+      def retry_schedule(config)
+        ExponentialBackoff.new(
+          attempts: config.fetch(:attempts),
+          base_delay: config.fetch(:backoff),
+          max_delay: config[:max_delay],
+          jitter: config.fetch(:jitter),
+          delay_label: "backoff"
+        )
       end
     end
   end