smith-agents 0.12.7 → 0.13.1

data/lib/smith/agent/provider_failure_handling.rb

@@ -23,7 +23,7 @@ module Smith
 
       def handle_provider_failure!(error, model_reference, agent_class, fallback_available:, attempt_id: nil)
         account_failed_attempt(error, model_reference, agent_class, attempt_id:)
-        if completed_tool_calls?
+        if uncertain_tool_calls?
           raise Smith::ToolOutcomeUncertain.new(
             "provider failed after tool execution began; retry or fallback could replay an uncertain outcome"
           ), cause: error
@@ -44,8 +44,10 @@ module Smith
         PROVIDER_ACCOUNT_ERRORS.any? { |error_class| error.is_a?(error_class) }
       end
 
-      def completed_tool_calls?
-        Tool.current_tool_execution_tracker&.started?
+      # A tool that is not replay-safe has run in the step: a fallback would
+      # run it again.
+      def uncertain_tool_calls?
+        Tool.current_tool_execution_tracker&.uncertain?
       end
 
       def fallback_eligible?(error)

data/lib/smith/agent/provider_streaming.rb

@@ -72,7 +72,9 @@ module Smith
 
       def paused_loop(error, chat, start)
         continuation = Budget::Continuation.dump(@budget_continuation, chat.messages.drop(start || 0))
-        BudgetUnavailable.new(error.message, continuation:) if continuation && storable_pause?(continuation)
+        return unless continuation && storable_pause?(continuation)
+
+        BudgetUnavailable.new(error.message, continuation:, paused_by: self)
       end
 
       # Whether the run's state, with the paused loop kept, stays within

data/lib/smith/errors.rb

@@ -74,12 +74,15 @@ module Smith
   # hold; nothing was sent. A BudgetExceeded, so it is not retried unless a
   # step's `retry_on` names it (a durable retry waits for budget). One that
   # paused a tool loop carries its `continuation` (Budget::Continuation),
-  # which the step's retry continues from.
+  # which the step's retry continues from, and the run whose step paused
+  # (`paused_by`): only that run's retry continues it, never a parent's,
+  # whose retry would start a nested workflow over.
   class BudgetUnavailable < BudgetExceeded
-    attr_reader :continuation
+    attr_reader :continuation, :paused_by
 
-    def initialize(message = "the budget ledger refused the request", continuation: nil)
+    def initialize(message = "the budget ledger refused the request", continuation: nil, paused_by: nil)
       @continuation = continuation
+      @paused_by = paused_by
       super(message)
     end
   end

data/lib/smith/response_memo.rb

@@ -31,7 +31,8 @@ module Smith
   # whose tools had not run answers the call's first request without
   # sending it, and its tools run again, under the same keys; kept tool
   # results count as tools the step ran (charged to its tool-call
-  # allowances, and never run again by a retry or fallback). A call whose
+  # allowances, and never run again by a retry or fallback unless each is a
+  # replay-safe tool's). A call whose
   # messages cannot be kept (an attachment, or too many bytes) is not
   # stored, and is logged. A record Smith does not keep (its shape, or tool
   # results that do not answer its replies' calls) is ignored, and an error

data/lib/smith/tool/budget_enforcement.rb

@@ -31,7 +31,7 @@ module Smith
       end
 
       def mark_tool_execution_started!
-        self.class.current_tool_execution_tracker&.mark_started!
+        self.class.current_tool_execution_tracker&.mark_started!(replay_safe: self.class.replay_safe?)
         self.class.__send__(:current_tool_dispatch_start_handler)&.call(self)
       end
     end

data/lib/smith/tool/capability_builder.rb

@@ -3,6 +3,9 @@
 module Smith
   class Tool < RubyLLM::Tool
     class CapabilityBuilder
+      REPLAY = %i[safe unsafe].freeze
+      private_constant :REPLAY
+
       def initialize
         @capabilities = {}
       end
@@ -12,7 +15,17 @@ module Smith
       def network(value)      = @capabilities[:network] = value
       def approval(value)     = @capabilities[:approval] = value
       def data_volume(value)  = @capabilities[:data_volume] = value
-      def to_h                = @capabilities
+
+      # :safe when running the tool again under the same keys does what
+      # running it once did (a lookup), so a step whose tools are all safe
+      # keeps its retries and fallbacks; :unsafe, the default, otherwise.
+      def replay(value)
+        raise ArgumentError, "replay is :safe or :unsafe" unless REPLAY.include?(value)
+
+        @capabilities[:replay] = value
+      end
+
+      def to_h = @capabilities
     end
   end
 end

data/lib/smith/tool/capability_declaration.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Smith
+  class Tool < RubyLLM::Tool
+    # What a tool class declares about itself (`capabilities do ... end`,
+    # CapabilityBuilder), read for its privilege check, its traces'
+    # sensitivity and whether a step may run it again. A subclass inherits
+    # its parent's, key by key: its own block sets or replaces only the keys
+    # it names, so a subclass is never less guarded than its parent unless
+    # it says so. `replay` alone is not inherited: whether a tool is safe to
+    # run again is a fact about its own `perform`, so a subclass is
+    # replay-safe only when it declares `replay :safe` itself.
+    module CapabilityDeclaration
+      NOT_INHERITED = %i[replay].freeze
+      private_constant :NOT_INHERITED
+
+      def capabilities(&)
+        return inherited_capabilities unless block_given?
+
+        builder = CapabilityBuilder.new
+        builder.instance_eval(&)
+        @capabilities = builder.to_h.freeze
+      end
+
+      # Whether this class itself declares `capabilities { replay :safe }`.
+      def replay_safe? = capabilities&.dig(:replay) == :safe
+
+      private
+
+      def inherited_capabilities
+        inherited = parent_capabilities
+        own = @capabilities if instance_variable_defined?(:@capabilities)
+        return own unless inherited
+
+        own ? inherited.merge(own) : inherited
+      end
+
+      # The parent's capabilities this class takes (all but `replay`), or nil.
+      def parent_capabilities
+        inherited = parent_tool&.capabilities&.except(*NOT_INHERITED)
+        inherited if inherited&.any?
+      end
+    end
+  end
+end

data/lib/smith/tool/capture_configuration.rb

@@ -2,9 +2,12 @@
 
 module Smith
   class Tool < RubyLLM::Tool
+    # A tool class's capture, inherited (Declarations) with its strictness: a
+    # subclass's own `capture_result` replaces its parent's, block and
+    # strictness together.
     module CaptureConfiguration
       def capture_result(strict: false, &block)
-        return @capture_result unless block
+        return declared(:@capture_result) unless block
 
         raise ArgumentError, "capture_result strict must be true or false" unless [true, false].include?(strict)
 
@@ -13,7 +16,7 @@ module Smith
       end
 
       def capture_result_strict?
-        @capture_result_strict == true
+        declaring_tool(:@capture_result)&.instance_variable_get(:@capture_result_strict) == true
       end
     end
   end

data/lib/smith/tool/declarations.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Smith
+  class Tool < RubyLLM::Tool
+    # A tool class's declarations, which its subclasses inherit: each reads
+    # the nearest class up the chain that declared it, so a subclass
+    # overrides one by declaring it again. Parameters add up by name (a
+    # subclass's `param` adds one or replaces its parent's of that name), up
+    # to a class that gave a schema with `params`, which replaced the ones
+    # above it; that schema gives way to a subclass's own `param`s.
+    # Capabilities (CapabilityDeclaration) merge key by key, and a capture
+    # (CaptureConfiguration) comes with its strictness. A tool none of whose
+    # classes declares `authorize` or `before_execute` runs without one, as
+    # before. `O(D)` for a chain `D` classes deep.
+    module Declarations
+      def description(text = nil)
+        return declared(:@description) unless text
+
+        @description = text
+      end
+      alias desc description
+
+      def param(name, **) = own_parameters[name] = RubyLLM::Parameter.new(name, **)
+
+      def parameters
+        parent = parent_tool
+        inherited = parent.parameters if parent && !parent.instance_variable_defined?(:@params_schema_definition)
+        inherited.nil? || inherited.empty? ? own_parameters : inherited.merge(own_parameters)
+      end
+
+      def params_schema_definition
+        return @params_schema_definition if instance_variable_defined?(:@params_schema_definition)
+
+        parent_tool&.params_schema_definition if own_parameters.empty?
+      end
+
+      def provider_params = declared(:@provider_params) || {}
+
+      def category(value = nil)
+        return declared(:@category) if value.nil?
+
+        @category = value
+      end
+
+      def authorize(&block)
+        return declared(:@authorize) unless block
+
+        @authorize = block
+      end
+
+      def before_execute(&block)
+        return declared(:@before_execute) unless block
+
+        @before_execute = block
+      end
+
+      private
+
+      def own_parameters = (@own_parameters ||= {})
+
+      def parent_tool = (superclass if superclass <= Tool)
+
+      # The nearest class from this one up that set `ivar`, or nil.
+      def declaring_tool(ivar)
+        tool = self
+        tool = tool.__send__(:parent_tool) while tool && !tool.instance_variable_defined?(ivar)
+        tool
+      end
+
+      def declared(ivar) = declaring_tool(ivar)&.instance_variable_get(ivar)
+    end
+  end
+end

data/lib/smith/tool/execution_tracker.rb

@@ -2,19 +2,30 @@
 
 module Smith
   class Tool < RubyLLM::Tool
+    # What the tools of one step attempt did: whether any began, and whether
+    # one that is not replay-safe did, which leaves the step's outcome
+    # uncertain (nothing may run its tools again).
     class ExecutionTracker
       def initialize
         @started = false
+        @uncertain = false
         @mutex = Mutex.new
       end
 
-      def mark_started!
-        @mutex.synchronize { @started = true }
+      def mark_started!(replay_safe: false)
+        @mutex.synchronize do
+          @started = true
+          @uncertain = true unless replay_safe
+        end
       end
 
       def started?
         @mutex.synchronize { @started }
       end
+
+      def uncertain?
+        @mutex.synchronize { @uncertain }
+      end
     end
   end
 end

data/lib/smith/tool.rb

@@ -2,7 +2,9 @@
 
 require "ruby_llm"
 
+require_relative "tool/declarations"
 require_relative "tool/capability_builder"
+require_relative "tool/capability_declaration"
 require_relative "tool/policy"
 require_relative "tool/call_budget"
 require_relative "tool/call_batch"
@@ -61,22 +63,14 @@ module Smith
     include ExecutionLifecycle
     include BudgetEnforcement
     include Capture
+    extend Declarations
+    extend CapabilityDeclaration
     extend CaptureConfiguration
     extend ScopedContext
 
     private_constant :ExecutionAuthority
 
     class << self
-      # Tool subclasses inherit the parent's compatible_with spec by
-      # reference (the spec is a frozen Hash; immutability makes shared
-      # references safe). Subclasses can override by calling
-      # `compatible_with` again — assigns a NEW frozen Hash to its own
-      # @compatible_with_spec, leaving the parent untouched.
-      def inherited(subclass)
-        super
-        subclass.instance_variable_set(:@compatible_with_spec, @compatible_with_spec)
-      end
-
       # Declarative compatibility DSL. Examples:
       #   compatible_with :anthropic, :gemini
       #   compatible_with :anthropic, :gemini, openai: :responses
@@ -85,38 +79,14 @@ module Smith
       # Tools that NEVER declare compatible_with are universally compatible.
       # Consumed by Smith::Models::Normalizer.drop_incompatible_tools when
       # the resolved model rejects the (tools + thinking) combo and no
-      # routing fallback (e.g., openai_api_mode :auto) is available.
+      # routing fallback (e.g., openai_api_mode :auto) is available. The
+      # spec is a frozen Hash, read like the other declarations: a subclass
+      # takes the nearest one up its chain (Declarations).
       def compatible_with(*providers, except: nil, **provider_endpoints)
         @compatible_with_spec = Compatibility.parse(providers, except: except, **provider_endpoints)
       end
 
-      attr_reader :compatible_with_spec
-
-      def category(value = nil)
-        return @category if value.nil?
-
-        @category = value
-      end
-
-      def capabilities(&)
-        return @capabilities unless block_given?
-
-        builder = CapabilityBuilder.new
-        builder.instance_eval(&)
-        @capabilities = builder.to_h
-      end
-
-      def authorize(&block)
-        return @authorize unless block_given?
-
-        @authorize = block
-      end
-
-      def before_execute(&block)
-        return @before_execute unless block_given?
-
-        @before_execute = block
-      end
+      def compatible_with_spec = declared(:@compatible_with_spec)
     end
 
     def execute(**kwargs)

data/lib/smith/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Smith
-  VERSION = "0.12.7"
+  VERSION = "0.13.1"
   EXECUTION_SEMANTICS_VERSION = "7"
 end

data/lib/smith/workflow/budget_pause.rb

@@ -37,7 +37,14 @@ module Smith
       def budget_pausable? = !@budget_pause_attempts.nil? && @step_attempt.to_i < @budget_pause_attempts
 
       def keep_budget_continuation(error)
-        @budget_continuation = error.continuation if error.is_a?(BudgetUnavailable) && error.continuation
+        @budget_continuation = error.continuation if own_pause?(error)
+      end
+
+      # A tool loop this run's own step paused, which its retry continues
+      # from its tools' results. One a nested workflow paused is not: the
+      # retry starts the child over, and its tools run again.
+      def own_pause?(error)
+        error.is_a?(BudgetUnavailable) && !error.continuation.nil? && error.paused_by.equal?(self)
       end
 
       # The paused loop's messages, after the attempt's prepared input.

data/lib/smith/workflow/failure_record_restore.rb

@@ -45,10 +45,12 @@ module Smith
         identity_attributes(values).merge(error_attributes(values)).freeze
       end
 
+      # A step declared `from: nil` is recorded with that origin, as its
+      # step result is; any other `from` must be text of 1 to 256 bytes.
       def identity_attributes(values)
         {
           transition: normalize_identifier(values.fetch(:transition), transition_normalizer, "transition"),
-          from: normalize_identifier(values.fetch(:from), state_normalizer, "from state"),
+          from: optional_identifier(values.fetch(:from), state_normalizer, "from state"),
           to: normalize_identifier(values.fetch(:to), state_normalizer, "to state")
         }
       end
@@ -98,6 +100,10 @@ module Smith
         bounded_string(value, 256, label).then { normalizer.call(_1) }
       end
 
+      def optional_identifier(value, normalizer, label)
+        value.nil? ? nil : normalize_identifier(value, normalizer, label)
+      end
+
       def normalize_kind(value)
         return if value.nil?
 

data/lib/smith/workflow/failure_record_text.rb

@@ -15,11 +15,13 @@ module Smith
       MODULE_MATCH = Module.instance_method(:===)
       STRING_BYTESIZE = String.instance_method(:bytesize)
       STRING_ENCODING = String.instance_method(:encoding)
+      STRING_FORCE_ENCODING = String.instance_method(:force_encoding)
       STRING_INITIALIZE_COPY = String.instance_method(:initialize_copy)
       STRING_VALID_ENCODING = String.instance_method(:valid_encoding?)
       SYMBOL_TO_S = Symbol.instance_method(:to_s)
-      private_constant :MODULE_MATCH, :STRING_BYTESIZE, :STRING_ENCODING, :STRING_INITIALIZE_COPY,
-                       :STRING_VALID_ENCODING, :SYMBOL_TO_S
+      TEXT_ENCODINGS = [Encoding::UTF_8, Encoding::US_ASCII].freeze
+      private_constant :MODULE_MATCH, :STRING_BYTESIZE, :STRING_ENCODING, :STRING_FORCE_ENCODING,
+                       :STRING_INITIALIZE_COPY, :STRING_VALID_ENCODING, :SYMBOL_TO_S, :TEXT_ENCODINGS
 
       extend Dry::Initializer
 
@@ -33,8 +35,7 @@ module Smith
       end
 
       def call
-        text = owned_text
-        validate_encoding!(text)
+        text = utf8_text(owned_text)
         size = STRING_BYTESIZE.bind_call(text)
         return normalized(text, size) if normalize_length
         raise PersistedFailureInvalid, "persisted workflow failure #{label} is invalid" unless size.between?(1, limit)
@@ -44,11 +45,16 @@ module Smith
 
       private
 
-      def validate_encoding!(text)
-        valid = STRING_VALID_ENCODING.bind_call(text) && STRING_ENCODING.bind_call(text) == Encoding::UTF_8
-        return if valid
+      # US-ASCII text is UTF-8 text as it stands (a Symbol's name and a
+      # renamed state's or step's name are US-ASCII), so its owned copy is
+      # marked UTF-8; any other encoding, or bytes outside it, is refused.
+      def utf8_text(text)
+        encoding = STRING_ENCODING.bind_call(text)
+        unless STRING_VALID_ENCODING.bind_call(text) && TEXT_ENCODINGS.include?(encoding)
+          raise PersistedFailureInvalid, "persisted workflow failure #{label} is invalid"
+        end
 
-        raise PersistedFailureInvalid, "persisted workflow failure #{label} is invalid"
+        encoding == Encoding::UTF_8 ? text : STRING_FORCE_ENCODING.bind_call(text, Encoding::UTF_8)
       end
 
       # Message fields mirror capture normalization instead of rejecting on
@@ -65,14 +71,16 @@ module Smith
       end
 
       def owned_text
-        return owned_string if string?
-        return SYMBOL_TO_S.bind_call(value) if symbol?
+        return owned_copy(value) if string?
+        return owned_copy(SYMBOL_TO_S.bind_call(value)) if symbol?
 
         raise PersistedFailureInvalid, "persisted workflow failure #{label} must be text"
       end
 
-      def owned_string
-        String.allocate.tap { STRING_INITIALIZE_COPY.bind_call(_1, value) }
+      # A copy of its own, so marking it UTF-8 changes neither the caller's
+      # String nor the String a Symbol's name comes as (chilled, or frozen).
+      def owned_copy(source)
+        String.allocate.tap { STRING_INITIALIZE_COPY.bind_call(_1, source) }
       end
 
       def string? = MODULE_MATCH.bind_call(String, value)

data/lib/smith/workflow/guarded_step_execution.rb

@@ -22,20 +22,20 @@ module Smith
           ensure
             # Tool evidence travels up: a step running inside another step
             # (a nested workflow's step) marks the enclosing step too, so the
-            # enclosing step is never retried over tools that already ran.
-            previous_tracker&.mark_started! if tracker.started?
+            # enclosing step is never retried over tools that already ran,
+            # unless they were all replay-safe.
+            previous_tracker&.mark_started!(replay_safe: !tracker.uncertain?) if tracker.started?
             Tool.current_tool_execution_tracker = previous_tracker
           end
         end
       end
 
-      # A failure after a tool ran leaves its outcome uncertain, unless its
-      # retry could not run the tool again: a terminal failure, or a tool
-      # loop paused for budget, whose retry continues from its tools'
-      # results.
+      # A failure after a tool that is not replay-safe ran leaves its outcome
+      # uncertain, unless its retry could not run the tool again: a terminal
+      # failure, or a tool loop this run's step paused for budget, whose
+      # retry continues from its tools' results (BudgetPause#own_pause?).
       def uncertain_after_tools?(tracker, error)
-        tracker.started? && !terminal_retry_error?(error) &&
-          !(error.is_a?(BudgetUnavailable) && error.continuation)
+        tracker.uncertain? && !terminal_retry_error?(error) && !own_pause?(error)
       end
 
       def run_tracked_guarded_step(transition)

data/lib/smith/workflow/nested_execution.rb

@@ -16,9 +16,9 @@ module Smith
       end
 
       # A child that raises passes its error to the parent unchanged, after
-      # its billable usage is rolled up. If a tool ran in the child, the
-      # parent's step already carries that evidence and turns the failure
-      # into ToolOutcomeUncertain (GuardedStepExecution).
+      # its billable usage is rolled up. If a tool that is not replay-safe
+      # ran in the child, the parent's step already carries that evidence
+      # and turns the failure into ToolOutcomeUncertain (GuardedStepExecution).
       def run_child_workflow(child)
         child.run!
       rescue StandardError

data/lib/smith/workflow/remembered_calls.rb

@@ -53,12 +53,24 @@ module Smith
         messages = kept.fetch(:messages)
         messages.each { chat.add_message(_1) }
         ran = messages.filter_map { _1.tool_call_id if _1.role == :tool }
-        Tool.current_tool_execution_tracker&.mark_started! if ran.any?
-        charge_kept_calls(ran_calls(messages, ran))
+        calls = ran_calls(messages, ran)
+        mark_kept_tools(chat, ran, calls) if ran.any?
+        charge_kept_calls(calls)
       end
 
       def ran_calls(messages, ran) = messages.flat_map { _1.tool_calls&.values.to_a }.select { ran.include?(_1.id) }
 
+      # As the tools themselves would mark the step: replay-safe only when
+      # each kept result answers a call to a tool of the chat's that
+      # declares it.
+      def mark_kept_tools(chat, ran, calls)
+        tools = calls.to_h { [_1.id, chat.tools[_1.name.to_sym]] }
+        safe = ran.all? { replay_safe_tool?(tools[_1]) }
+        Tool.current_tool_execution_tracker&.mark_started!(replay_safe: safe)
+      end
+
+      def replay_safe_tool?(tool) = tool.is_a?(Tool) && tool.class.replay_safe?
+
       # Each kept call against the agent's tool-call allowance and the
       # workflow's `tool_calls` budget, as a call that runs is, so a replay
       # runs no more tools than the step may. A call past them (a budget

data/lib/smith/workflow/retry_execution.rb

@@ -34,9 +34,7 @@ module Smith
         schedule = retry_schedule(config)
         begin
           attempt += 1
-          @step_attempt = attempt
-          @step_key_generation = key_generation
-          attempt_scope = attempt_idempotency_scope(key_generation)
+          attempt_scope = enter_attempt(attempt, key_generation)
           run_attempt_under_keys(transition, attempt_scope)
         rescue StandardError => e
           Interruptions.pass!(e)
@@ -48,10 +46,33 @@ module Smith
           return wait_to_retry(transition, delay, attempt + 1, key_generation, e) if config[:durable]
 
           sleep(delay) if delay.positive?
+          drop_attempt_tool_results(e)
           retry
         end
       end
 
+      # The attempt under way, under `key_generation`; returns its
+      # idempotency scope. `@attempt_tool_results_from` (transient, like
+      # `@step_attempt`) is where its tool results start.
+      def enter_attempt(attempt, key_generation)
+        @step_attempt = attempt
+        @step_key_generation = key_generation
+        @attempt_tool_results_from = @tool_results_mutex.synchronize { @tool_results.length }
+        attempt_idempotency_scope(key_generation)
+      end
+
+      # Once its retry is certain (in process, or waiting), a failed attempt's
+      # tool results go: its tools were replay-safe, or it would not be
+      # retried, and the next attempt runs them again. A tool loop this
+      # run's step paused for budget keeps them, as its retry goes on from
+      # them.
+      def drop_attempt_tool_results(error)
+        from = @attempt_tool_results_from
+        return if from.nil? || own_pause?(error)
+
+        @tool_results_mutex.synchronize { @tool_results.slice!(from..) }
+      end
+
       def attempt_idempotency_scope(key_generation)
         step_scope = IdempotencyKey.__send__(:current_scope)
         return step_scope if step_scope.nil? || key_generation.zero?

data/lib/smith/workflow/retry_wait.rb

@@ -24,6 +24,7 @@ module Smith
       # 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.
+      # The run waits without the failed attempt's tool captures.
       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"
@@ -38,6 +39,7 @@ module Smith
         @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"])
+        drop_attempt_tool_results(error)
         WAIT_PENDING
       end
 

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

@@ -76,9 +76,7 @@ module Smith
           transition_name = @next_transition_name || transition&.name
           raise WorkflowError, "workflow has no pending transition" unless transition_name
 
-          refusal = "split-step persistence does not run steps that wait or launch runs"
-          raise WorkflowError, refusal if transition&.waits_or_launches?
-
+          refuse_unsupported_split_step!(transition)
           ensure_transition_budget!
           resolved_key = normalize_split_step_persistence_key(candidate_split_step_persistence_key(key))
           store = persistence_adapter!(adapter)

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module SplitStepPersistence
+      # The steps split-step persistence does not run, refused when one is
+      # prepared, before anything is written.
+      module UnsupportedSteps
+        private
+
+        def refuse_unsupported_split_step!(transition)
+          return unless transition
+
+          if transition.waits_or_launches?
+            raise WorkflowError, "split-step persistence does not run steps that wait or launch runs"
+          end
+          return unless transition.from.nil?
+
+          # A prepared step is checked against the state its step is declared
+          # from, which a step declared `from: nil` does not have; not
+          # supported yet.
+          raise WorkflowError, "split-step persistence does not run :#{transition.name}: it is declared from: nil, " \
+                               "and a prepared step is checked against the state its step is declared from; " \
+                               "run it with advance_persisted!"
+        end
+      end
+    end
+  end
+end