smith-agents 0.10.0 → 0.12.0

data/lib/smith/workflow/persistence.rb

@@ -13,7 +13,19 @@ module Smith
           context: snapshot_value(persisted_context),
           budget_consumed: ledger_consumed,
           step_count: @step_count,
+          awaiting: @awaiting&.dup,
+          # The attempt a durable retry makes next, and its key generation.
+          pending_retry: @pending_retry&.dup,
+          pending_batch: @pending_batch&.dup,
+          # The scope the run's budget_ledger is built from.
+          budget_ledger_scope: @budget_ledger_scope&.transform_keys(&:to_s),
+          active_seconds: @active_seconds || 0.0,
+          active_step_started_at: @active_step_started_at,
           execution_namespace: @execution_namespace,
+          # Untrusted keys inherited from a parent run (a durable child's).
+          inherited_untrusted_keys: (@inherited_untrusted_keys || []).map(&:to_s),
+          # Artifact namespaces a child run may read (its ancestors').
+          inherited_artifact_namespaces: (@inherited_artifact_namespaces || []).dup,
           created_at: @created_at,
           updated_at: @updated_at,
           next_transition_name: @next_transition_name,
@@ -85,6 +97,7 @@ module Smith
         @next_transition_name = normalized[:next_transition_name]
         @session_messages = normalized[:session_messages] || []
         @seed_message_count = validated_seed_message_count(normalized)
+        validate_session_parts!
         @total_cost = normalized[:total_cost] || 0.0
         @total_tokens = normalized[:total_tokens] || 0
         @outcome = normalized[:outcome]
@@ -99,12 +112,14 @@ module Smith
         @usage_mutex = Mutex.new
         @usage_entries = restore_usage_entries(normalized)
         @last_output = restore_last_output(normalized)
+        @last_transcript_output = restored_transcript_output
         # Backward-compat: pre-patch states have no last_agent_execution key and
-        # restore to nil. @pending_agent_execution is transient (nil between
-        # steps), never persisted, but must be initialized because from_state
-        # allocates and bypasses #initialize.
+        # restore to nil. @pending_agent_execution and @pending_evaluations are
+        # transient (nil between steps), never persisted, but must be
+        # initialized because from_state allocates and bypasses #initialize.
         @last_agent_execution = restore_last_agent_execution(normalized)
         @pending_agent_execution = nil
+        @pending_evaluations = nil
         @last_failed_step = restore_last_failed_step(normalized)
         # Restore the optimistic-locking version from the persisted payload.
         # Backward-compat: pre-versioning payloads have no key, restore to 0
@@ -112,6 +127,16 @@ module Smith
         # the original store from the legacy adapter contract).
         @persistence_version = persistence_version
         validate_definition_digest!(normalized)
+        validate_restored_position!(normalized)
+        @awaiting = WaitRecord.restore(normalized[:awaiting], workflow_class: self.class,
+                                                              persistence_key: normalized[:persistence_key],
+                                                              state: @state, next_transition: @next_transition_name)
+        @pending_retry = restore_pending_retry(normalized[:pending_retry], normalized[:persistence_key])
+        @pending_batch = restore_pending_batch(normalized[:pending_batch])
+        @active_seconds = restored_active_seconds(normalized[:active_seconds])
+        charge_unfinished_step!(normalized[:active_step_started_at])
+        @wait_mutex = Mutex.new
+        @wait_claimed = false
         # 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
@@ -125,6 +150,18 @@ module Smith
         @split_step_mutex = Mutex.new
         validate_step_in_progress!(normalized) if
           self.class.idempotency_mode == :strict && !allow_step_in_progress
+        initialize_budget_ledger
+        @memo_attempts = []
+        @budget_ledger_scope = restored_budget_ledger_scope(normalized[:budget_ledger_scope])
+      end
+
+      # The stored scope, or, for a run stored before its class declared
+      # these scope keys, the one its context gives now.
+      def restored_budget_ledger_scope(stored)
+        return unless self.class.budget_ledger
+
+        Budget::HostLedger.stored_scope(self.class.budget_ledger_scope_keys, stored) ||
+          capture_budget_ledger_scope
       end
 
       def validated_persistence_version(normalized)
@@ -135,6 +172,24 @@ module Smith
               "persisted workflow persistence_version must be a non-negative integer, got #{version.inspect}"
       end
 
+      # Content parts come only from seed messages: anywhere else in a
+      # stored session they are refused, and a seed's are checked and kept
+      # as checked (String-keyed parts), however the payload was parsed.
+      def validate_session_parts!
+        @session_messages = @session_messages.each_with_index.map do |message, index|
+          next message unless Message.parts?(message)
+
+          checked = index < @seed_message_count && begin
+            Message.check_seed!(message)
+          rescue WorkflowError
+            nil
+          end
+          raise Smith::SerializationError, "persisted session content parts must be valid seed messages" unless checked
+
+          { role: checked["role"], content: checked["content"], parts: true }
+        end
+      end
+
       def validated_seed_message_count(normalized)
         count = normalized.fetch(:seed_message_count, 0)
         return count if count.is_a?(Integer) && count >= 0 && count <= @session_messages.length
@@ -160,16 +215,17 @@ module Smith
 
         raise Smith::StepInProgressOnRestore.new(
           workflow: self.class.name,
-          persistence_key: normalized[:persistence_key]
+          persistence_key: normalized[:persistence_key],
+          state: normalized[:state],
+          transition: normalized[:next_transition_name]
         )
       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:)
+        fields = %i[step_in_progress persistence_key state next_transition_name]
+        validate_step_in_progress!(fields.to_h { |field| [field, state[field] || state[field.to_s]] })
       end
 
       def validate_seed_digest!(normalized)
@@ -225,6 +281,14 @@ module Smith
         end
       end
 
+      # The last assistant message after the seeds: the output the run last
+      # added to its transcript, unless the host admitted one after it.
+      def restored_transcript_output
+        seeds = @seed_message_count || 0
+        message = @session_messages.drop(seeds).reverse_each.find { |item| MessageRoles.role(item) == "assistant" }
+        message && message[:content]
+      end
+
       def restore_last_agent_execution(normalized)
         value = if normalized.key?(:last_agent_execution)
           normalized[:last_agent_execution]
@@ -233,7 +297,9 @@ module Smith
         end
         return unless value.is_a?(Hash)
 
-        symbolize_keys(value)
+        execution = symbolize_keys(value)
+        execution[:provider] = execution[:provider].to_sym if execution[:provider].is_a?(String)
+        execution
       end
 
       # Symbolize ONLY the top-level keys of last_failed_step + the
@@ -252,15 +318,73 @@ module Smith
         ).call
       end
 
+      # A state or pending transition the class does not know (a deploy
+      # renamed or removed it, or the payload has none) fails the restore.
+      # Restoring it would leave the run in a state with no outgoing
+      # transitions, which reads as terminal and ends the run silently. Runs
+      # after `migrate_from` and after the definition digest check, so a
+      # migration can map an old name and a digest mismatch is reported as
+      # one.
+      def validate_restored_position!(normalized)
+        validate_restored_state!(normalized[:state], normalized[:persistence_key])
+        validate_restored_transition!(normalized[:next_transition_name], normalized[:persistence_key])
+      end
+
+      def validate_restored_state!(state, persistence_key)
+        return if state.nil? && self.class.initial_state.nil?
+        return if !state.nil? && self.class.known_state?(state)
+
+        raise Smith::UnknownStateOnRestore.new(workflow: self.class.name, persistence_key:, state:)
+      end
+
+      def validate_restored_transition!(transition, persistence_key)
+        return if transition.nil? || self.class.find_transition(transition)
+
+        raise Smith::UnknownTransitionOnRestore.new(workflow: self.class.name, persistence_key:, transition:)
+      end
+
       def restore_core_fields(normalized)
         @state = normalized[:state]
         @context = filter_persisted_context(normalized[:context] || {})
         @step_count = normalized[:step_count] || 0
-        @execution_namespace = normalized[:execution_namespace]
+        @execution_namespace = restored_execution_namespace(normalized)
+        @inherited_untrusted_keys = restored_inherited_untrusted_keys(normalized)
+        @inherited_artifact_namespaces = restored_artifact_namespaces(normalized)
         @created_at = normalized[:created_at]
         @updated_at = normalized[:updated_at]
       end
 
+      def restored_inherited_untrusted_keys(normalized)
+        keys = normalized.fetch(:inherited_untrusted_keys, [])
+        unless keys.is_a?(Array) && keys.length <= 1_000 && keys.all? { untrusted_key_name?(_1) }
+          raise Smith::SerializationError, "persisted workflow inherited_untrusted_keys are invalid"
+        end
+
+        keys.map(&:to_sym).uniq.freeze
+      end
+
+      def untrusted_key_name?(key) = (key.is_a?(String) || key.is_a?(Symbol)) && key.length.between?(1, 256)
+
+      def restored_artifact_namespaces(normalized)
+        ArtifactIntegration.artifact_namespaces!(normalized.fetch(:inherited_artifact_namespaces, []))
+      rescue WorkflowError
+        raise Smith::SerializationError, "persisted workflow inherited_artifact_namespaces are invalid"
+      end
+
+      # A payload written before namespaces were assigned at construction
+      # gets one derived from its own durable facts, the same on every
+      # restore of it, until a checkpoint stores it.
+      def restored_execution_namespace(normalized)
+        namespace = normalized[:execution_namespace]
+        if namespace.nil?
+          return IdempotencyKey.__send__(:legacy_namespace, normalized[:class] || self.class.name,
+                                         normalized[:persistence_key], normalized[:created_at])
+        end
+        return namespace if namespace.is_a?(String) && PreparedStep::UUID_PATTERN.match?(namespace)
+
+        raise Smith::SerializationError, "persisted workflow execution_namespace must be a UUID"
+      end
+
       def restore_persisted_keys(normalized)
         @persisted_keys_mutex = Mutex.new
         raw = normalized[:persisted_keys]
@@ -357,24 +481,22 @@ module Smith
         symbolized
       end
 
+      # The identifier the class itself uses for a payload's state name, so a
+      # String-named state stays a String; an unknown name is symbolized.
       def normalize_state_name(value)
         return if value.nil?
-        return value if declared_state?(value)
-        return value unless value.is_a?(String)
 
-        symbolized = value.to_sym
-        return symbolized if declared_state?(symbolized)
+        resolved = self.class.resolve_state_name(value)
+        return resolved unless resolved.nil?
 
-        symbolized
-      end
-
-      def declared_state?(value)
-        states = self.class.instance_variable_get(:@states) || []
-        states.include?(value)
+        value.is_a?(String) ? value.to_sym : value
       end
 
+      # Context keys are Symbols at every depth, matching what construction
+      # and deterministic writes produce, so a nested read behaves the same
+      # before and after a restore.
       def normalize_nested_hashes!(normalized)
-        normalized[:context] = symbolize_keys(normalized[:context]) if normalized[:context].is_a?(Hash)
+        normalized[:context] = ContextKeys.normalize(normalized[:context]) if normalized[:context].is_a?(Hash)
         return unless normalized[:budget_consumed].is_a?(Hash)
 
         normalized[:budget_consumed] = symbolize_keys(normalized[:budget_consumed])
@@ -384,7 +506,12 @@ 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(snapshot_value(msg)) : snapshot_value(msg)
+          unless MessageRoles.role(msg)
+            raise Smith::SerializationError,
+                  "persisted session message must have the role system, user, assistant or tool"
+          end
+
+          symbolize_keys(snapshot_value(msg))
         end
       end
 
@@ -430,7 +557,20 @@ module Smith
         config = self.class.budget
         return nil unless config
 
-        Budget::Ledger.new(limits: config, consumed: consumed)
+        Budget::Ledger.new(limits: config, consumed: declared_budget_consumed(consumed, config))
+      end
+
+      # A dimension the workflow no longer declares has no limit, so its
+      # consumed entry (a key an earlier version accepted and ignored) is
+      # dropped rather than refused.
+      def declared_budget_consumed(consumed, config)
+        return consumed unless consumed.is_a?(Hash)
+
+        declared = config.each_key.to_h { |dimension| [dimension.to_s, dimension] }
+        consumed.each_with_object({}) do |(key, amount), kept|
+          dimension = declared[key.to_s]
+          kept[dimension] = amount if dimension
+        end
       end
 
       def persisted_context

data/lib/smith/workflow/remembered_calls.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    # A step's provider calls through a host's response memo
+    # (Smith::ResponseMemo): each call takes its kept messages, if any, and
+    # sends nothing when they end it (a streamed step's sink gets the reply's
+    # text at once), else goes on from them, and is recorded as it goes.
+    # Kept tool results count as tools the step ran, and the live part goes
+    # on from the kept rounds (Resumed): its first request is a later round,
+    # and a pause for budget keeps the kept rounds too.
+    module RememberedCalls
+      CALLS_LOCK = Mutex.new
+      private_constant :CALLS_LOCK
+
+      # Where a call's live part starts: the call's first message, and the
+      # rounds its kept messages made.
+      Resumed = Data.define(:start, :rounds)
+
+      private
+
+      def remembered_completion(chat, model_reference, facts, &)
+        memo = Smith.config.response_memo
+        key = memo && memo_key(chat, facts)
+        return yield(nil) unless key
+
+        start = chat.messages.length
+        kept = ResponseMemo.fetch(memo, key)
+        keep_messages(chat, kept.fetch(:messages)) if kept
+        return replayed_completion(chat, model_reference) if kept&.fetch(:complete)
+
+        recorded_completion(chat, memo, key, Resumed.new(start:, rounds: kept_rounds(kept)), &)
+      end
+
+      def kept_rounds(kept) = kept ? kept.fetch(:messages).count { _1.role == :assistant } : 0
+
+      def memo_key(chat, facts)
+        ResponseMemo.key([*@memo_attempts, @step_attempt.to_i], facts[:attempt_index], next_memo_call, chat)
+      end
+
+      # The kept messages, after the call's own; their tool results are
+      # tools the step ran.
+      def keep_messages(chat, messages)
+        messages.each { chat.add_message(_1) }
+        Tool.current_tool_execution_tracker&.mark_started! if messages.any? { _1.role == :tool }
+      end
+
+      def recorded_completion(chat, memo, key, resumed)
+        live = chat.messages.length
+        result = ResponseMemo.recording(chat_provider(chat), memo, key, resumed.start) { yield(resumed) }
+        ResponseMemo.store(memo, key, chat.messages.drop(resumed.start), complete: true,
+                                                                         facts: streamed_facts(chat, live, result))
+        result
+      end
+
+      # A streamed call's replies' facts, read from its stream.
+      def streamed_facts(chat, live, result)
+        stream = result[1]
+        return {} unless stream.is_a?(Hash) && stream[:rounds]
+
+        replies = chat.messages.drop(live).select { _1.role == :assistant }
+        replies.zip(Providers::StreamFacts.per_message(replies, stream[:rounds], stream[:output_limit]))
+               .to_h.compare_by_identity
+      end
+
+      def replayed_completion(chat, model_reference)
+        response = chat.messages.last
+        if (stream = @step_stream)
+          stream.start(attempt: @step_attempt, model: model_reference.model_id,
+                       provider: model_reference.provider&.to_s)
+          content = response.content
+          stream.delta(content.is_a?(String) ? content : JSON.generate(content))
+        end
+        [response, nil, nil, { memo: true }]
+      end
+
+      # The call's place among its attempt's calls at its position (a
+      # fan-out's branches count their own).
+      def next_memo_call
+        slot = [IdempotencyKey.__send__(:current_scope)&.key, @step_attempt]
+        memo_calls_lock.synchronize do
+          @memo_calls ||= {}
+          @memo_calls[slot] = @memo_calls.fetch(slot, 0) + 1
+        end
+      end
+
+      def memo_calls_lock = @memo_calls_lock || CALLS_LOCK.synchronize { @memo_calls_lock ||= Mutex.new }
+
+      def start_memo_calls = memo_calls_lock.synchronize { @memo_calls = {} }
+    end
+  end
+end

data/lib/smith/workflow/retry_execution.rb

@@ -5,27 +5,88 @@ module Smith
     module RetryExecution
       private
 
+      # `@step_attempt` is the attempt under way, from 1, which the optimizer
+      # names its verdicts by; transient, set here before every attempt.
+      #
+      # Every attempt sends its requests under the step's idempotency keys,
+      # so a retry after an uncertain failure (a timeout, a lost connection)
+      # cannot repeat a request that took effect. Only an attempt that
+      # failed in a way the step declares settled moves later attempts to
+      # new keys. Attempts replay in the same order after a restore, so a
+      # replay reaches the same keys as long as the receivers answer the
+      # replayed requests as before. A durable policy waits out the backoff
+      # as a wait of the run (RetryWait) and resumes at the attempt and key
+      # generation it recorded.
       def run_with_retry_policy(transition)
         config = transition.retry_config
+        position = pending_batch_position
+        @step_attempt = position ? position.first + 1 : 1
+        @step_key_generation = position ? position.last : 0
+        start_budget_pause(transition)
+        start_memo_calls
         return run_guarded_step(transition) unless config
 
+        run_attempts(transition, config, *(position || pending_retry_position(transition)))
+      end
+
+      # Attempts after the `attempt` already made, under `key_generation`.
+      def run_attempts(transition, config, attempt, key_generation)
         schedule = retry_schedule(config)
-        attempt = 0
         begin
           attempt += 1
-          run_guarded_step(transition)
+          @step_attempt = attempt
+          @step_key_generation = key_generation
+          attempt_scope = attempt_idempotency_scope(key_generation)
+          run_attempt_under_keys(transition, attempt_scope)
         rescue StandardError => e
           raise unless retry_transition_error?(config, e, attempt)
 
-          sleep_for_retry(schedule, attempt)
+          key_generation += 1 if new_idempotency_key_after?(config, e, attempt_scope)
+          keep_budget_continuation(e)
+          delay = retry_delay(schedule, attempt)
+          return wait_to_retry(transition, delay, attempt + 1, key_generation, e) if config[:durable]
+
+          sleep(delay) if delay.positive?
           retry
         end
       end
 
+      def attempt_idempotency_scope(key_generation)
+        step_scope = IdempotencyKey.__send__(:current_scope)
+        return step_scope if step_scope.nil? || key_generation.zero?
+
+        step_scope.within(:key_generation, key_generation)
+      end
+
+      def run_attempt_under_keys(transition, attempt_scope)
+        return run_guarded_step(transition) if attempt_scope.equal?(IdempotencyKey.__send__(:current_scope))
+
+        IdempotencyKey.__send__(:swap, attempt_scope) { run_guarded_step(transition) }
+      end
+
+      # A `fail!(new_idempotency_key: true)` counts only when this step's own
+      # attempt raised it, never a nested workflow's step, whose flag speaks
+      # for its own requests and not for the earlier steps of the attempt.
+      def new_idempotency_key_after?(config, error, attempt_scope)
+        return true if own_settled_failure?(error, attempt_scope)
+
+        config.fetch(:new_idempotency_key_on, EMPTY_ERROR_CLASSES).any? { |error_class| error.is_a?(error_class) }
+      end
+
+      def own_settled_failure?(error, attempt_scope)
+        error.is_a?(DeterministicStepFailure) && error.new_idempotency_key &&
+          !attempt_scope.nil? && error.idempotency_scope == attempt_scope
+      end
+
+      EMPTY_ERROR_CLASSES = [].freeze
+      private_constant :EMPTY_ERROR_CLASSES
+
       def retry_transition_error?(config, error, attempt)
         return false if attempt >= config.fetch(:attempts)
         return false if terminal_retry_error?(error)
 
+        return false if retry_deadline_passed?
+
         classes = config.fetch(:error_classes)
         if classes.any?
           classes.any? { |error_class| error.is_a?(error_class) }
@@ -34,13 +95,15 @@ module Smith
         end
       end
 
-      def terminal_retry_error?(error)
-        Smith::Errors.retry_forbidden?(error)
+      # No attempt starts once the wall-clock deadline has passed: it could
+      # only fail again, after sleeping through its backoff.
+      def retry_deadline_passed?
+        deadline = effective_deadline
+        !deadline.nil? && Time.now.utc >= deadline
       end
 
-      def sleep_for_retry(schedule, failed_attempt)
-        delay = retry_delay(schedule, failed_attempt)
-        sleep(delay) if delay.positive?
+      def terminal_retry_error?(error)
+        Smith::Errors.retry_forbidden?(error)
       end
 
       def retry_delay(config_or_schedule, failed_attempt)

data/lib/smith/workflow/retry_wait.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Smith
+  class Workflow
+    # The waits of durable retries. An attempt that fails in a way a
+    # `retry_on ..., durable: true` policy retries does not sleep: the run
+    # enters a wait of kind `retry`, due when the backoff ends, and records
+    # its pending retry (the transition, the next attempt, its key
+    # generation, and the class of the error that failed the last attempt).
+    # `expire_wait!` past the deadline ends the wait without a step and
+    # leaves the transition as the run's next; the host continues the run as
+    # after any wait, and the step makes the recorded attempt under the
+    # recorded keys. A step that ends without entering a wait clears the
+    # pending retry (Workflow#advance!).
+    module RetryWait
+      PENDING_RETRY_FIELDS = %w[attempt error key_generation transition].freeze
+      private_constant :PENDING_RETRY_FIELDS
+
+      private
+
+      # Enters the wait, due after the backoff, under a token of the attempt
+      # it waits to make. Like any wait it is not a step. The pending retry
+      # is recorded before the wait, so an interrupt between the two leaves
+      # a step that ended without a wait, whose pending retry is cleared.
+      def wait_to_retry(transition, seconds, attempt, key_generation, error)
+        if @split_step_phase == :executing
+          raise WorkflowError, "a durable retry cannot wait inside split-step execution"
+        end
+
+        check_wait_ttl!(seconds)
+        error_name = DiagnosticText.error_class_name(error)
+        @pending_retry = { "transition" => transition.name.to_s, "attempt" => attempt,
+                           "key_generation" => key_generation, "error" => error_name,
+                           "continuation" => @budget_continuation }.compact.freeze
+        @retry_wait_error = error
+        @awaiting = WaitRecord.build_retry(transition, wait_token_for(transition, ["retry", attempt]), seconds,
+                                           Time.now.utc)
+        record_retry_trace(transition, :retrying, attempt:, error: error_name, deadline_at: @awaiting["deadline_at"])
+        WAIT_PENDING
+      end
+
+      # A step that ran and did not enter a wait has made its pending retry,
+      # whether it completed, failed or raised.
+      def clear_settled_pending_retry
+        @pending_retry = nil if step_work_started? && !waiting?
+      end
+
+      # [attempts already made, key generation] where the step starts: the
+      # pending retry's for its transition, else [0, 0].
+      def pending_retry_position(transition)
+        pending = @pending_retry
+        return [0, 0] unless pending && pending["transition"] == transition.name.to_s
+
+        [pending["attempt"] - 1, pending["key_generation"]]
+      end
+
+      # The backoff is over: the transition becomes the run's next step, then
+      # the wait ends; nothing counts. Returns :expired.
+      def end_retry_wait(transition)
+        @next_transition_name = transition.name
+        @updated_at = Time.now.utc.iso8601(6)
+        @awaiting = nil
+        Attribution.with(execution_key: @persistence_key, workflow: self.class.name || "anonymous") do
+          record_retry_trace(transition, :retry_due, attempt: @pending_retry&.fetch("attempt"))
+        end
+        :expired
+      ensure
+        @wait_claimed = false
+      end
+
+      def record_retry_trace(transition, outcome, **details)
+        Smith::Trace.record(
+          type: :transition,
+          data: { transition: transition.name, from: transition.from, to: transition.to, outcome:, **details }
+        )
+      end
+
+      # The error that failed the attempt a retry wait follows, while this
+      # instance holds it (for a nested child's parent).
+      def retry_wait_error = (@retry_wait_error if retry_waiting?)
+
+      # A persisted pending retry names the transition of the stored retry
+      # wait, or else the run's next one, with an attempt after the first, a
+      # key generation an earlier attempt could reach, and an error class
+      # name; a stored retry wait needs one. A malformed one raises
+      # SerializationError; one the class no longer allows (the transition
+      # declares no durable retry, or fewer attempts) is refused like an
+      # unknown position.
+      def restore_pending_retry(value, persistence_key)
+        return if value.nil? && !retry_waiting?
+
+        record = value.is_a?(Hash) ? value.transform_keys(&:to_s) : {}
+        transition = pending_retry_transition(record)
+        raise Smith::SerializationError, "persisted workflow pending_retry is invalid" unless
+          well_formed_pending_retry?(transition, record)
+
+        refuse_disallowed_pending_retry!(transition, record, persistence_key)
+        record.transform_values(&:freeze).freeze
+      end
+
+      def retry_waiting? = @awaiting&.fetch("kind") == "retry"
+
+      # The transition the record names, when it is the stored retry wait's,
+      # or the run's next while the run does not wait.
+      def pending_retry_transition(record)
+        return if @awaiting && !retry_waiting?
+
+        name = @awaiting ? @awaiting["transition"] : @next_transition_name&.to_s
+        self.class.transition_named(name) if name && record["transition"] == name
+      end
+
+      def well_formed_pending_retry?(transition, record)
+        !transition.nil? && (record.keys - ["continuation"]).sort == PENDING_RETRY_FIELDS &&
+          pending_retry_fields?(record) &&
+          (!record.key?("continuation") || Budget::Continuation.valid?(record["continuation"]))
+      end
+
+      def pending_retry_fields?(record)
+        attempt, generation, error = record.values_at("attempt", "key_generation", "error")
+        attempt.is_a?(Integer) && attempt >= 2 && generation.is_a?(Integer) && generation.between?(0, attempt - 1) &&
+          error.is_a?(String) && error.bytesize.between?(1, 256)
+      end
+
+      def refuse_disallowed_pending_retry!(transition, record, persistence_key)
+        return if transition.durable_retry? && record["attempt"] <= transition.retry_config.fetch(:attempts)
+
+        raise Smith::UnknownTransitionOnRestore.new(workflow: self.class.name, persistence_key:,
+                                                    transition: transition.name)
+      end
+    end
+  end
+end

data/lib/smith/workflow/run_result.rb

@@ -33,6 +33,16 @@ module Smith
         steps.reverse.map { |step| step[:error] }.compact.first
       end
 
+      # Every verdict an optimize step's loops recorded, in step, attempt and
+      # round order, each a frozen record naming its step's transition. Like
+      # `steps`, they belong to the run that executed the step: a terminal
+      # restore has none.
+      def evaluations
+        steps.flat_map do |step|
+          (step[:evaluations] || []).map { |evaluation| { transition: step[:transition], **evaluation }.freeze }
+        end
+      end
+
       def failed_transition
         failure_detail&.fetch(:transition)
       end

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

@@ -35,6 +35,9 @@ module Smith
           end
           @split_step_mutex.synchronize { @split_step_phase = :checkpointed } if checkpoint_claimed
           result
+        rescue PersistedStateTooLarge
+          release_split_step_checkpoint! if checkpoint_claimed
+          raise
         rescue StandardError
           mark_split_step_checkpoint_unknown! if checkpoint_claimed
           raise

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

@@ -40,6 +40,13 @@ module Smith
           end
         end
 
+        # A checkpoint refused before anything was written may be made again.
+        def release_split_step_checkpoint!
+          @split_step_mutex.synchronize do
+            @split_step_phase = :checkpoint_retryable if @split_step_phase == :checkpointing
+          end
+        end
+
         def mark_split_step_checkpoint_unknown!
           @split_step_mutex.synchronize do
             @split_step_phase = :checkpoint_unknown if @split_step_phase == :checkpointing