smith-agents 0.7.0 → 0.10.0

data/lib/smith/workflow/deadline_enforcement.rb

@@ -25,7 +25,7 @@ module Smith
         saved_deadline = Tool.current_deadline
         saved_call_ledger = Thread.current[:smith_call_ledger]
         snapshot = ThreadContextSnapshot.new(
-          tool_attributes: %i[current_deadline current_tool_call_allowance],
+          tool_attributes: %i[current_deadline current_tool_call_allowance current_tool_execution_tracker],
           thread_keys: %i[smith_call_deadline smith_call_ledger],
           scoped_artifacts: false
         )
@@ -41,6 +41,7 @@ module Smith
         apply_agent_deadline(agent_class)
         narrow_tool_deadline!
         apply_agent_tool_calls(agent_class)
+        Tool.current_tool_execution_tracker ||= Tool::ExecutionTracker.new
         apply_agent_call_ledger(agent_class)
       end
 
@@ -49,6 +50,7 @@ module Smith
         Thread.current[:smith_call_ledger] = call_ledger
         clear_agent_deadline
         clear_agent_tool_calls
+        Tool.current_tool_execution_tracker = nil
       end
 
       def effective_call_ledger
@@ -74,7 +76,23 @@ module Smith
 
       def apply_agent_tool_calls(agent_class)
         agent_tc = agent_class&.budget&.dig(:tool_calls)
-        Tool.current_tool_call_allowance = agent_tc ? Tool::CallAllowance.new(agent_tc) : nil
+        if agent_class&.tool_budget_exhaustion == :complete && agent_tc.nil?
+          raise AgentError, "tool_budget_exhaustion :complete requires a finite tool_calls budget"
+        end
+
+        Tool.current_tool_call_allowance = build_agent_tool_call_allowance(agent_class, agent_tc)
+      end
+
+      def build_agent_tool_call_allowance(agent_class, agent_tool_calls)
+        return unless agent_tool_calls
+
+        parent = Tool.current_tool_call_allowance
+        if parent && !parent.is_a?(Tool::CallAllowance)
+          raise AgentError, "agent tool_calls budgets cannot scope a legacy Hash tool call allowance"
+        end
+        return parent.scope(agent_tool_calls, on_exhaustion: agent_class.tool_budget_exhaustion) if parent
+
+        Tool::CallAllowance.new(agent_tool_calls, on_exhaustion: agent_class.tool_budget_exhaustion)
       end
 
       def clear_agent_tool_calls

data/lib/smith/workflow/deterministic_execution.rb

@@ -29,7 +29,8 @@ module Smith
           session_messages: snapshot_value(@session_messages || []),
           tool_results: snapshot_value(@tool_results || []),
           state: @state,
-          transition: transition
+          transition: transition,
+          last_agent_execution: snapshot_value(@last_agent_execution)
         )
       end
 

data/lib/smith/workflow/deterministic_step.rb

@@ -15,11 +15,24 @@ module Smith
         @current_state = state
         @transition_name = transition ? transition.name : options.fetch(:transition_name)
         @allowed_routes = snapshot_allowed_routes(transition ? transition.deterministic_routes : options[:allowed_routes])
+        @last_agent_execution = options[:last_agent_execution]
         @context_writes = {}
         @routed_to = nil
         @outcome = nil
       end
 
+      # The model id / provider that actually served the most recent serial
+      # `execute :agent` step (post fallback resolution), or nil if no serial
+      # agent step has run. Symmetric with `last_output`, which returns that
+      # step's content; use these to attribute an agent output to its model.
+      def last_agent_model
+        @last_agent_execution && @last_agent_execution[:model]
+      end
+
+      def last_agent_provider
+        @last_agent_execution && @last_agent_execution[:provider]
+      end
+
       def last_output
         return @last_output if defined?(@last_output)
 
@@ -59,7 +72,7 @@ module Smith
       private
 
       def validate_options!(options)
-        unknown = options.keys - %i[transition transition_name allowed_routes]
+        unknown = options.keys - %i[transition transition_name allowed_routes last_agent_execution]
         raise ArgumentError, "unknown keywords: #{unknown.join(", ")}" if unknown.any?
         return if options[:transition] || options.key?(:transition_name)
 

data/lib/smith/workflow/dsl.rb

@@ -17,6 +17,7 @@ module Smith
             duplicate_transition_index(@transitions_by_state)
           )
           subclass.instance_variable_set(:@transition_order, (@transition_order || {}).dup)
+          subclass.instance_variable_set(:@generated_transitions, (@generated_transitions || []).dup)
           subclass.instance_variable_set(:@transition_sequence, @transition_sequence)
           subclass.instance_variable_set(:@initial_state_name, @initial_state_name)
           subclass.instance_variable_set(:@budget_config, @budget_config&.dup)
@@ -50,7 +51,12 @@ module Smith
           declared = Transition.new(name, from: from, to: to, &)
           name = declared.name
           @transitions ||= {}
-          remove_from_transition_index(@transitions[name]) if @transitions.key?(name)
+
+          if @transitions.key?(name)
+            remove_from_transition_index(@transitions[name])
+            release_generated_transition_order(name)
+          end
+
           @transitions[name] = declared
           insert_into_transition_index(declared)
         end
@@ -279,10 +285,28 @@ module Smith
           transitions_by_state.delete(transition.from) if indexed.empty?
         end
 
+        # A user redeclaration replacing a GENERATED transition takes a fresh
+        # declaration-position order; a genuine user redefinition keeps its
+        # original position (matrix-pinned redefinition semantics). Without
+        # this, the synthetic :fail generated when `state :failed` is
+        # declared keeps its early order number, and a later user-declared
+        # :fail sharing an origin state with a primary transition would sort
+        # ahead of it and shadow it at run time.
+        def release_generated_transition_order(name)
+          return unless generated_transitions.delete(name)
+
+          transition_order.delete(name)
+        end
+
+        def generated_transitions
+          @generated_transitions ||= []
+        end
+
         def generate_fail_transition
           @transitions ||= {}
           return if @transitions.key?(:fail)
 
+          generated_transitions << :fail
           transition(:fail, from: nil, to: :failed)
         end
       end

data/lib/smith/workflow/evaluator_optimizer.rb

@@ -29,7 +29,9 @@ module Smith
 
       def run_optimization_loop(state)
         state.config[:max_rounds].times do |round|
-          result = run_optimization_round(state, round)
+          # The overlay scopes every trace and usage fact from this round's
+          # generator and evaluator calls to the round that produced them.
+          result = Attribution.with(round: round) { run_optimization_round(state, round) }
           return result if result
         end
 

data/lib/smith/workflow/event_integration.rb

@@ -15,7 +15,54 @@ module Smith
           Events::StepCompleted.new(
             transition: transition.name.to_sym,
             from: transition.from&.to_sym,
-            to: transition.to.to_sym
+            to: transition.to.to_sym,
+            workflow: Attribution.ambient.workflow
+          )
+        )
+      end
+
+      # Failure-path counterpart to emit_step_completed, fired from both
+      # failure handlers before they branch or re-raise, so an observer sees
+      # exactly where execution went dark. Classification reuses
+      # FailureRecord's bounded taxonomy; raw messages are never emitted. The
+      # rescue keeps a broken instrument from altering failure semantics:
+      # the original error, not an emission error, must win.
+      def emit_step_failed(step)
+        failure = FailureRecord.capture(step)
+        record_failed_transition_trace(failure)
+        emit_step_failed_event(failure)
+      rescue StandardError => e
+        Smith.config.logger&.error("Smith failed-step emission error: #{e.message}")
+      end
+
+      # `outcome`, not `result`: `result` is a reserved content key in the
+      # trace pipeline (it carries tool results and is stripped by the
+      # default content policy). Matches the :provider_call vocabulary.
+      # `from`/`to` stay present even when nil, matching the success-trace
+      # shape: an absent key would let the ambient attribution of an
+      # enclosing scope (a parent step's `from`) show through the
+      # fields-under-data merge and fabricate a foreign state fact.
+      def record_failed_transition_trace(failure)
+        data = {
+          transition: failure[:transition], from: failure[:from], to: failure[:to],
+          outcome: :failed,
+          error_class: failure[:error_class],
+          error_family: failure[:error_family]
+        }
+        data[:retryable] = failure[:error_retryable] unless failure[:error_retryable].nil?
+        Smith::Trace.record(type: :transition, data: data)
+      end
+
+      def emit_step_failed_event(failure)
+        Smith::Events.emit(
+          Events::StepFailed.new(
+            transition: DiagnosticText.capture(failure[:transition].to_s, max_bytes: 256).to_sym,
+            from: failure[:from]&.to_sym,
+            to: failure[:to]&.to_sym,
+            error_class: failure[:error_class],
+            error_family: failure[:error_family],
+            retryable: failure[:error_retryable],
+            workflow: Attribution.ambient.workflow
           )
         )
       end

data/lib/smith/workflow/execution.rb

@@ -2,6 +2,7 @@
 
 require_relative "agent_result"
 require_relative "execution_binding_resolution"
+require_relative "guarded_step_execution"
 require_relative "prepared_branch_execution"
 require_relative "step_completion"
 require_relative "step_context"
@@ -10,6 +11,7 @@ module Smith
   class Workflow
     module Execution
       include ExecutionBindingResolution
+      include GuardedStepExecution
       include PreparedBranchExecution
       include StepCompletion
       include StepContext
@@ -29,6 +31,10 @@ module Smith
       end
 
       def execute_step_body(transition)
+        # Reset the per-step agent-attribution carrier so only a serial agent
+        # step that actually runs (below) leaves model/provider for complete_step;
+        # a deterministic step never sets it and must not inherit a stale value.
+        @pending_agent_execution = nil
         output = with_scoped_artifacts { run_with_retry_policy(transition) }
         StepCompletion.instance_method(:complete_step).bind_call(self, transition, output)
       end
@@ -39,15 +45,6 @@ module Smith
         Tool.current_tool_result_collector = tool_result_collector
       end
 
-      def run_guarded_step(transition)
-        return apply_composite_reduction!(transition) if @composite_reduction
-
-        @resolved_parallel_branch_count = preflight_branch_count(transition)
-        run_standard_guarded_step(transition)
-      ensure
-        @resolved_parallel_branch_count = nil
-      end
-
       def run_standard_guarded_step(transition)
         return dispatch_step(transition) if transition.deterministic?
         return run_guarded_fanout_step(transition) if transition.fanout?
@@ -100,6 +97,10 @@ module Smith
         begin
           result = execute_transition_body(transition, prepared_input: prepared_input)
           agent_result = result.is_a?(AgentResult) ? result : nil
+          # Capture the model/provider that actually served this serial agent
+          # step (post fallback resolution) for complete_step to fold into the
+          # durable step record. Nil when no agent ran (e.g. unconfigured model).
+          @pending_agent_execution = agent_result && { model: agent_result.model_used, provider: agent_result.provider_used }
           reconcile_branch_budget(ledger, reserved, agent_result: agent_result)
           reserved = nil
           agent_result ? agent_result.content : result

data/lib/smith/workflow/failure_detail_snapshot.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+require "json"
+
+require_relative "../diagnostic_text"
+require_relative "message_value_normalizer"
+
+module Smith
+  class Workflow
+    class FailureDetailSnapshot
+      OMITTED_KEY = "smith_failure_details_omitted"
+      OMITTED_REASON_BYTES = 1_024
+      private_constant :OMITTED_KEY, :OMITTED_REASON_BYTES
+
+      extend Dry::Initializer
+
+      param :value
+
+      def call
+        return if value.nil?
+
+        snapshot = MessageValueNormalizer.new(value, label: "workflow failure details").call
+        JSON.generate(snapshot)
+        snapshot
+      rescue StandardError => e
+        {
+          OMITTED_KEY => DiagnosticText.capture(e.message, max_bytes: OMITTED_REASON_BYTES)
+        }.freeze
+      end
+    end
+  end
+end

data/lib/smith/workflow/failure_reconstructor.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+require_relative "../errors"
+require_relative "failure_record_validator"
+
+module Smith
+  class Workflow
+    class FailureReconstructor
+      FAMILY_BUILDERS = {
+        "deterministic_step_failure" => ->(record) { deterministic_step_failure(record) },
+        "tool_guardrail_failed" => ->(record) { tool_guardrail_failure(record) },
+        "tool_failure_notification_failed" => ->(record) { tool_failure_notification_failure(record) },
+        "tool_capture_failed" => ->(record) { Smith::ToolCaptureFailed.from_details(record.fetch(:error_details)) },
+        "tool_outcome_uncertain" => ->(record) { Smith::ToolOutcomeUncertain.new(record[:error_message]) },
+        "tool_execution_not_admitted" => ->(record) { Smith::ToolExecutionNotAdmitted.new(record[:error_message]) },
+        "bounded_completion_error" => ->(record) { Smith::BoundedCompletionError.new(record[:error_message]) },
+        "persisted_failure_invalid" => ->(record) { Smith::PersistedFailureInvalid.new(record[:error_message]) },
+        "deadline_exceeded" => ->(record) { Smith::DeadlineExceeded.new(record[:error_message]) },
+        "agent_error" => ->(record) { Smith::AgentError.new(record[:error_message]) },
+        "workflow_error" => ->(record) { Smith::WorkflowError.new(record[:error_message]) },
+        "other" => ->(record) { RuntimeError.new(record[:error_message]) }
+      }.freeze
+      SPECIAL_CLASS_BUILDERS = {
+        "Smith::Workflow::Composite::BranchFailure" => lambda { |record|
+          Smith::Workflow::Composite::BranchFailure.from_details(record[:error_details])
+        }
+      }.freeze
+      private_constant :FAMILY_BUILDERS, :SPECIAL_CLASS_BUILDERS
+
+      extend Dry::Initializer
+
+      option :snapshot
+      option :transition_normalizer
+      option :state_normalizer
+
+      def call
+        {
+          transition: transition_normalizer.call(snapshot[:transition]),
+          from: state_normalizer.call(snapshot[:from]),
+          to: state_normalizer.call(snapshot[:to]),
+          error: reconstruct_error
+        }
+      end
+
+      private
+
+      def reconstruct_error
+        FailureRecordValidator.new(snapshot).call
+        builder = SPECIAL_CLASS_BUILDERS[snapshot[:error_class]] || FAMILY_BUILDERS.fetch(snapshot[:error_family])
+        builder.call(snapshot)
+      rescue Smith::PersistedFailureInvalid
+        raise
+      rescue ArgumentError, KeyError, TypeError
+        raise Smith::PersistedFailureInvalid, "persisted workflow failure details are invalid"
+      end
+
+      def self.deterministic_step_failure(record)
+        Smith::DeterministicStepFailure.new(
+          record[:error_message],
+          retryable: record[:error_retryable],
+          kind: record[:error_kind],
+          details: record[:error_details]
+        )
+      end
+
+      def self.tool_guardrail_failure(record)
+        Smith::ToolGuardrailFailed.new(record[:error_message], retryable: record[:error_retryable])
+      end
+
+      def self.tool_failure_notification_failure(record)
+        Smith::ToolFailureNotificationFailed.from_details(record.fetch(:error_details))
+      end
+
+      private_class_method :deterministic_step_failure, :tool_guardrail_failure, :tool_failure_notification_failure
+    end
+  end
+end

data/lib/smith/workflow/failure_record.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+require_relative "../diagnostic_text"
+require_relative "../errors"
+require_relative "failure_detail_snapshot"
+require_relative "failure_record_text"
+
+module Smith
+  class Workflow
+    class FailureRecord
+      ERROR_FAMILIES = [
+        [Smith::DeterministicStepFailure, "deterministic_step_failure"],
+        [Smith::ToolFailureNotificationFailed, "tool_failure_notification_failed"],
+        [Smith::ToolCaptureFailed, "tool_capture_failed"],
+        [Smith::ToolOutcomeUncertain, "tool_outcome_uncertain"],
+        [Smith::ToolExecutionNotAdmitted, "tool_execution_not_admitted"],
+        [Smith::BoundedCompletionError, "bounded_completion_error"],
+        [Smith::PersistedFailureInvalid, "persisted_failure_invalid"],
+        [Smith::ToolGuardrailFailed, "tool_guardrail_failed"],
+        [Smith::DeadlineExceeded, "deadline_exceeded"],
+        [Smith::AgentError, "agent_error"],
+        [Smith::WorkflowError, "workflow_error"]
+      ].freeze
+      BOOLEAN_VALUES = [true, false].freeze
+      EXCEPTION_CAUSE = Exception.instance_method(:cause)
+      EXCEPTION_MESSAGE = Exception.instance_method(:message)
+      MODULE_MATCH = Module.instance_method(:===)
+      MODULE_NAME = Module.instance_method(:name)
+      OBJECT_CLASS = Object.instance_method(:class)
+      private_constant :ERROR_FAMILIES, :BOOLEAN_VALUES, :EXCEPTION_CAUSE, :EXCEPTION_MESSAGE, :MODULE_MATCH,
+                       :MODULE_NAME, :OBJECT_CLASS
+
+      extend Dry::Initializer
+
+      option :step_result
+
+      def self.capture(step_result) = new(step_result:).call
+
+      def call
+        error = step_result.fetch(:error)
+        {
+          transition: step_result[:transition],
+          from: step_result[:from],
+          to: step_result[:to],
+          **error_attributes(error)
+        }.freeze
+      end
+
+      private
+
+      def error_attributes(error)
+        {
+          error_class: DiagnosticText.capture(error_class_name(error), max_bytes: 512),
+          error_family: error_family(error),
+          error_message: error_message(error),
+          error_retryable: retryable_value(error),
+          error_retry_forbidden: Smith::Errors.retry_forbidden?(error),
+          error_kind: error_kind(error),
+          error_details: error_details(error),
+          **cause_attributes(error)
+        }
+      end
+
+      # Uncertainty wrappers replace the causal failure at the transition
+      # boundary; without this classification a restored host cannot
+      # distinguish a deadline, cancellation, or defect behind an
+      # uncertain tool outcome.
+      def cause_attributes(error)
+        cause = uncertainty_cause(error)
+        {
+          error_cause_class: cause && DiagnosticText.capture(error_class_name(cause), max_bytes: 512),
+          error_cause_family: cause && error_family(cause),
+          error_cause_message: cause && error_message(cause)
+        }
+      end
+
+      def uncertainty_cause(error)
+        return unless MODULE_MATCH.bind_call(Smith::ToolOutcomeUncertain, error)
+
+        cause = EXCEPTION_CAUSE.bind_call(error)
+        cause if MODULE_MATCH.bind_call(Exception, cause)
+      rescue StandardError
+        nil
+      end
+
+      def error_family(error)
+        ERROR_FAMILIES.find { |error_class, _| MODULE_MATCH.bind_call(error_class, error) }&.last || "other"
+      end
+
+      def error_class_name(error)
+        error_class = OBJECT_CLASS.bind_call(error)
+        MODULE_NAME.bind_call(error_class) || "anonymous_error"
+      end
+
+      # Never captures blank text: restore requires non-empty messages, so
+      # a blank live message takes the shared deterministic placeholder.
+      def error_message(error)
+        captured = DiagnosticText.capture(EXCEPTION_MESSAGE.bind_call(error))
+        captured.empty? ? FailureRecordText::MISSING_TEXT : captured
+      rescue StandardError
+        FailureRecordText::MISSING_TEXT
+      end
+
+      def retryable_value(error)
+        return unless error.respond_to?(:retryable)
+
+        value = error.retryable
+        value if BOOLEAN_VALUES.include?(value)
+      rescue StandardError
+        nil
+      end
+
+      def error_kind(error)
+        return unless error.respond_to?(:kind)
+
+        value = error.kind
+        return unless value.is_a?(String) || value.is_a?(Symbol)
+
+        captured = DiagnosticText.capture(value.to_s, max_bytes: 256)
+        # Restore rejects blank kinds; an empty kind carries no signal.
+        captured unless captured.empty?
+      rescue StandardError
+        nil
+      end
+
+      def error_details(error)
+        return unless error.respond_to?(:details)
+
+        FailureDetailSnapshot.new(error.details).call
+      rescue StandardError => e
+        FailureDetailSnapshot.new(
+          smith_failure_details_omitted: DiagnosticText.capture(e.message, max_bytes: 1_024)
+        ).call
+      end
+    end
+  end
+end

data/lib/smith/workflow/failure_record_restore.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+require "json"
+
+require_relative "../diagnostic_text"
+require_relative "../errors"
+require_relative "failure_record_text"
+require_relative "failure_record_validator"
+require_relative "message_value_normalizer"
+
+module Smith
+  class Workflow
+    class FailureRecordRestore
+      ATTRIBUTE_NAMES = %i[
+        transition from to error_class error_family error_message error_retryable error_retry_forbidden
+        error_kind error_details error_cause_class error_cause_family error_cause_message
+      ].freeze
+      OPTIONAL_NAMES = %i[error_retry_forbidden error_cause_class error_cause_family error_cause_message].freeze
+      REQUIRED_NAMES = (ATTRIBUTE_NAMES - OPTIONAL_NAMES).freeze
+      ATTRIBUTE_KEYS = ATTRIBUTE_NAMES.to_h { |name| [name.to_s, name] }.freeze
+      MODULE_MATCH = Module.instance_method(:===)
+      HASH_EACH_PAIR = Hash.instance_method(:each_pair)
+      private_constant :ATTRIBUTE_NAMES, :OPTIONAL_NAMES, :REQUIRED_NAMES, :ATTRIBUTE_KEYS, :MODULE_MATCH,
+                       :HASH_EACH_PAIR
+
+      extend Dry::Initializer
+
+      param :raw
+      option :transition_normalizer
+      option :state_normalizer
+
+      def call
+        return if raw.nil?
+
+        reject!("persisted workflow failure record must be a Hash") unless MODULE_MATCH.bind_call(Hash, raw)
+
+        values = attributes
+        FailureRecordValidator.new(restored_record(values)).call
+      end
+
+      private
+
+      def restored_record(values)
+        identity_attributes(values).merge(error_attributes(values)).freeze
+      end
+
+      def identity_attributes(values)
+        {
+          transition: normalize_identifier(values.fetch(:transition), transition_normalizer, "transition"),
+          from: normalize_identifier(values.fetch(:from), state_normalizer, "from state"),
+          to: normalize_identifier(values.fetch(:to), state_normalizer, "to state")
+        }
+      end
+
+      def error_attributes(values)
+        {
+          error_class: bounded_string(values.fetch(:error_class), 512, "class"),
+          error_family: bounded_string(values.fetch(:error_family), 64, "family"),
+          error_message: message_string(values.fetch(:error_message), "message"),
+          error_retryable: boolean_or_nil(values.fetch(:error_retryable), "retryable"),
+          error_retry_forbidden: boolean_or_nil(values[:error_retry_forbidden], "retry policy"),
+          error_kind: normalize_kind(values.fetch(:error_kind)),
+          error_details: normalize_details(values.fetch(:error_details)),
+          **cause_attributes(values)
+        }
+      end
+
+      def cause_attributes(values)
+        {
+          error_cause_class: optional_string(values[:error_cause_class], 512, "cause class"),
+          error_cause_family: optional_string(values[:error_cause_family], 64, "cause family"),
+          error_cause_message: optional_message(values[:error_cause_message], "cause message")
+        }
+      end
+
+      def attributes
+        values = {}
+        HASH_EACH_PAIR.bind_call(raw) do |key, value|
+          name = normalize_key(key)
+          reject!("persisted workflow failure record contains a duplicate attribute") if values.key?(name)
+
+          values[name] = value
+        end
+        missing = REQUIRED_NAMES - values.keys
+        reject!("persisted workflow failure record is incomplete") if missing.any?
+        values
+      end
+
+      def normalize_key(key)
+        return key if symbol?(key) && ATTRIBUTE_NAMES.include?(key)
+        return ATTRIBUTE_KEYS.fetch(key) if string?(key) && ATTRIBUTE_KEYS.key?(key)
+
+        reject!("persisted workflow failure record contains an unknown attribute")
+      end
+
+      def normalize_identifier(value, normalizer, label)
+        bounded_string(value, 256, label).then { normalizer.call(_1) }
+      end
+
+      def normalize_kind(value)
+        return if value.nil?
+
+        bounded_string(value, 256, "kind").to_sym
+      end
+
+      def normalize_details(value)
+        return if value.nil?
+
+        snapshot = MessageValueNormalizer.new(value, label: "persisted workflow failure details").call
+        JSON.generate(snapshot)
+        snapshot
+      rescue WorkflowError, JSON::GeneratorError, EncodingError
+        reject!("persisted workflow failure details are invalid")
+      end
+
+      def bounded_string(value, limit, label)
+        FailureRecordText.capture(value, limit:, label:)
+      end
+
+      def optional_string(value, limit, label) = value.nil? ? nil : bounded_string(value, limit, label)
+
+      # Messages restore with capture normalization (placeholder for blank
+      # text, capture-identical truncation for overlong text) because legacy
+      # states persisted them unbounded; length alone never rejects restore.
+      def message_string(value, label)
+        FailureRecordText.capture(value, limit: DiagnosticText::MAX_BYTES, label:, normalize_length: true)
+      end
+
+      def optional_message(value, label) = value.nil? ? nil : message_string(value, label)
+
+      def boolean_or_nil(value, label)
+        return value if value.nil? || value == true || value == false
+
+        reject!("persisted workflow failure #{label} is invalid")
+      end
+
+      def reject!(message) = raise(Smith::PersistedFailureInvalid, message)
+
+      def string?(value) = MODULE_MATCH.bind_call(String, value)
+
+      def symbol?(value) = MODULE_MATCH.bind_call(Symbol, value)
+    end
+  end
+end