smith-agents 0.8.0 → 0.11.0

data/lib/smith/provider_permanent_failure.rb

@@ -1,9 +1,15 @@
 # frozen_string_literal: true
 
+require_relative "diagnostic_text"
 require_relative "error"
 
 module Smith
   class ProviderPermanentFailure < Error
+    DETAIL_NAMES = %i[provider model_id source_error_class].freeze
+    DETAIL_KEYS = DETAIL_NAMES.to_h { |name| [name.to_s.freeze, name] }.freeze
+    MAX_DETAIL_BYTES = 512
+    private_constant :DETAIL_NAMES, :DETAIL_KEYS, :MAX_DETAIL_BYTES
+
     attr_reader :provider, :model_id, :source_error_class
 
     def initialize(message, provider:, model_id:, source_error_class:)
@@ -12,5 +18,43 @@ module Smith
       @source_error_class = source_error_class.to_s.dup.freeze
       super(message)
     end
+
+    def details
+      {
+        provider: provider && DiagnosticText.capture(provider.to_s, max_bytes: MAX_DETAIL_BYTES),
+        model_id: DiagnosticText.capture(model_id, max_bytes: MAX_DETAIL_BYTES),
+        source_error_class: DiagnosticText.capture(source_error_class, max_bytes: MAX_DETAIL_BYTES)
+      }.freeze
+    end
+
+    def self.from_details(details, message: nil)
+      new(message, **normalize_details(details))
+    end
+
+    def self.normalize_details(details)
+      raise ArgumentError, "provider failure details must be a Hash" unless details.is_a?(Hash)
+
+      values = {}
+      Hash.instance_method(:each_pair).bind_call(details) do |key, value|
+        name = key.is_a?(Symbol) ? key : DETAIL_KEYS[key]
+        raise ArgumentError, "provider failure details contain an unknown attribute" unless DETAIL_NAMES.include?(name)
+        raise ArgumentError, "provider failure details contain a duplicate attribute" if values.key?(name)
+
+        values[name] = bounded_detail(name, value)
+      end
+      raise ArgumentError, "provider failure details are incomplete" unless values.length == DETAIL_NAMES.length
+
+      values
+    end
+
+    def self.bounded_detail(name, value)
+      return value if name == :provider && value.nil?
+
+      bounded = value.is_a?(String) && value.valid_encoding? && value.bytesize <= MAX_DETAIL_BYTES
+      raise ArgumentError, "provider failure detail #{name} must be bounded text" unless bounded
+
+      value
+    end
+    private_class_method :normalize_details, :bounded_detail
   end
 end

data/lib/smith/tool/capture.rb

@@ -54,8 +54,16 @@ module Smith
         capture_failure(e, strict, reason: :capture_block_failed)
       end
 
+      # tool_call_id is additive only when present (a provider-batch
+      # invocation is ambient), so captures from direct invocations and
+      # pre-existing persisted payloads keep their exact two-key shape.
       def append_capture(collector, captured, strict)
-        collector.call({ tool: name.to_s, captured: captured }) if strict || captured
+        return unless strict || captured
+
+        entry = { tool: name.to_s, captured: captured }
+        tool_call_id = self.class.current_invocation&.tool_call_id
+        entry[:tool_call_id] = tool_call_id if tool_call_id
+        collector.call(entry)
       rescue StandardError => e
         capture_failure(e, strict, reason: :collector_failed)
       end

data/lib/smith/tool.rb

@@ -165,9 +165,18 @@ module Smith
     end
 
     def emit_tool_trace(kwargs, result, duration)
+      # tool_call_id is the provider's correlation id for this invocation
+      # (present only when the call came from a provider batch); it lets a
+      # host join this trace to its own per-invocation records.
       Smith::Trace.record(
         type: :tool_call,
-        data: { tool: name, args: kwargs, result: result, duration: duration },
+        data: {
+          tool: name,
+          args: kwargs,
+          result: result,
+          duration: duration,
+          tool_call_id: self.class.current_invocation&.tool_call_id
+        }.compact,
         sensitivity: self.class.capabilities&.dig(:sensitivity) || :low
       )
     end

data/lib/smith/trace/logger.rb

@@ -7,6 +7,7 @@ module Smith
         transition: :trace_transitions,
         tool_call: :trace_tool_calls,
         token_usage: :trace_token_usage,
+        provider_call: :trace_provider_calls,
         cost: :trace_cost,
         normalizer_decision: :trace_normalizer
       }.freeze

data/lib/smith/trace/memory.rb

@@ -7,26 +7,62 @@ module Smith
         transition: :trace_transitions,
         tool_call: :trace_tool_calls,
         token_usage: :trace_token_usage,
+        provider_call: :trace_provider_calls,
         cost: :trace_cost,
         normalizer_decision: :trace_normalizer
       }.freeze
 
       CONTENT_KEYS = %i[content prompt response args result].freeze
 
-      attr_reader :traces
+      # Generous enough that test and development runs never hit it; a bound
+      # exists at all so a long-lived process with parallel branches cannot
+      # grow this adapter without limit.
+      DEFAULT_LIMIT = 10_000
 
-      def initialize
+      attr_reader :traces, :limit
+
+      def initialize(limit: DEFAULT_LIMIT)
+        unless limit.is_a?(Integer) && limit.positive?
+          raise ArgumentError, "Smith::Trace::Memory limit must be a positive integer, got #{limit.inspect}"
+        end
+
+        @limit = limit
         @traces = []
+        @dropped_count = 0
+        @mutex = Mutex.new
       end
 
       def record(type:, data:)
         return unless type_enabled?(type)
 
-        @traces << { type: type, data: filter_content(data) }
+        entry = { type: type, data: filter_content(data) }
+        @mutex.synchronize do
+          if @traces.length >= @limit
+            @dropped_count += 1
+          else
+            @traces << entry
+          end
+        end
+      end
+
+      # Entries rejected because the adapter was full. Zero in any healthy
+      # test run; a growing value means the limit needs raising or the
+      # process needs a clear!.
+      def dropped_count
+        @mutex.synchronize { @dropped_count }
+      end
+
+      # A consistent copy for readers that may race concurrent recording;
+      # #traces stays the live array for compatibility.
+      def snapshot
+        @mutex.synchronize { @traces.dup }
       end
 
       def clear!
-        @traces = []
+        @mutex.synchronize do
+          @traces = []
+          @dropped_count = 0
+        end
       end
 
       private

data/lib/smith/trace/open_telemetry.rb

@@ -7,7 +7,9 @@ module Smith
         transition: :trace_transitions,
         tool_call: :trace_tool_calls,
         token_usage: :trace_token_usage,
-        cost: :trace_cost
+        provider_call: :trace_provider_calls,
+        cost: :trace_cost,
+        normalizer_decision: :trace_normalizer
       }.freeze
 
       CONTENT_KEYS = %i[content prompt response args result].freeze
@@ -23,18 +25,60 @@ module Smith
         )
       end
 
+      # Smith trace events describe operations that already finished, so the
+      # span is created retroactively: when the event carries a duration
+      # (:tool_call seconds, :provider_call milliseconds) the span's start is
+      # backdated by it and the span duration is real; otherwise the span is
+      # an instant. Uses only the documented opentelemetry-api surface
+      # (Tracer#start_span with start_timestamp, Span#finish with
+      # end_timestamp) so any SDK the host installs applies.
       def record(type:, data:)
         return unless @tracer
         return unless type_enabled?(type)
 
         filtered = filter_content(data)
-        @tracer.in_span("smith.#{type}") do |span|
-          filtered.each { |key, value| span.set_attribute("smith.#{key}", value.to_s) }
+        finished_at = Time.now
+        span = @tracer.start_span("smith.#{type}", start_timestamp: span_start(filtered, finished_at))
+        begin
+          apply_attributes(span, filtered)
+        ensure
+          span.finish(end_timestamp: finished_at)
         end
       end
 
       private
 
+      def span_start(data, finished_at)
+        seconds = duration_seconds(data)
+        seconds ? finished_at - seconds : finished_at
+      end
+
+      def duration_seconds(data)
+        return data[:duration].to_f if data[:duration].is_a?(Numeric)
+        return data[:duration_ms] / 1000.0 if data[:duration_ms].is_a?(Numeric)
+
+        nil
+      end
+
+      def apply_attributes(span, data)
+        data.each do |key, value|
+          coerced = attribute_value(value)
+          span.set_attribute("smith.#{key}", coerced) unless coerced.nil?
+        end
+      end
+
+      # OpenTelemetry attributes accept strings, integers, floats, and
+      # booleans; numeric values keep their type instead of arriving as
+      # strings, everything else (symbols included) becomes a string, nil
+      # drops.
+      def attribute_value(value)
+        case value
+        when String, Integer, Float, true, false then value
+        when nil then nil
+        else value.to_s
+        end
+      end
+
       def type_enabled?(type)
         config_key = CONFIG_MAP[type]
         return true unless config_key

data/lib/smith/trace.rb

@@ -1,34 +1,53 @@
 # frozen_string_literal: true
 
+require_relative "attribution"
+
 module Smith
   module Trace
     SENSITIVITY_CONTENT_KEYS = %i[args result].freeze
+    ADAPTER_MUTEX = Mutex.new
+    private_constant :ADAPTER_MUTEX
 
     def self.record(type:, data:, sensitivity: :low)
       adapter = resolve_adapter
       return unless adapter
 
-      filtered = apply_content_policy(data, sensitivity)
+      filtered = apply_content_policy(attributed(data), sensitivity)
       filtered = filter_fields(type, filtered)
       adapter.record(type: type, data: filtered)
     rescue StandardError => e
       Smith.config.logger&.error("Smith::Trace adapter error: #{e.message}")
     end
 
+    # Ambient attribution keys are identifiers, not content: they merge in
+    # under the caller's own keys (the caller wins on conflict) and then pass
+    # through the same content policy and field allowlist as everything else,
+    # so a host's configured trace_fields contract keeps holding.
+    def self.attributed(data)
+      return data unless Smith.config.trace_attribution
+
+      fields = Attribution.current_fields
+      return data if fields.empty?
+
+      fields.merge(data)
+    end
+
+    # Class-configured adapters memoize one instance under a mutex so
+    # concurrent first records (every fan-out branch emits) share a single
+    # adapter instead of racing separate instances and losing entries.
     def self.resolve_adapter
       configured = Smith.config.trace_adapter
       return nil unless configured
+      return configured unless configured.is_a?(Class)
 
-      if configured.is_a?(Class)
+      ADAPTER_MUTEX.synchronize do
         @adapter_instances ||= {}
         @adapter_instances[configured] ||= configured.new
-      else
-        configured
       end
     end
 
     def self.reset!
-      @adapter_instances = nil
+      ADAPTER_MUTEX.synchronize { @adapter_instances = nil }
     end
 
     def self.apply_content_policy(data, sensitivity)

data/lib/smith/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Smith
-  VERSION = "0.8.0"
+  VERSION = "0.11.0"
   EXECUTION_SEMANTICS_VERSION = "5"
 end

data/lib/smith/workflow/budget_integration.rb

@@ -22,7 +22,7 @@ module Smith
         return nil unless ledger
 
         ledger.limits.each_with_object({}) do |(dim, _limit), est|
-          per_branch = estimate_for_dimension(dim, ledger.remaining(dim), branch_count)
+          per_branch = estimate_for_dimension(dim, ledger.remaining_share(dim, branch_count))
           cap = agent_cap_for_dimension(dim, agent_budget)
           est[dim] = cap ? [per_branch, cap].min : per_branch
         end
@@ -117,10 +117,10 @@ module Smith
         { branch: branch_key, agent: agent_name, output: agent_result ? agent_result.content : result }
       end
 
-      def estimate_for_dimension(dim, limit, branch_count)
+      def estimate_for_dimension(dim, share)
         return 0 unless BUDGET_DIMENSIONS.include?(dim)
 
-        TOKEN_DIMENSIONS.include?(dim) ? [limit / branch_count, 1].max : limit / branch_count
+        TOKEN_DIMENSIONS.include?(dim) ? [share, 1].max : share
       end
 
       def agent_cap_for_dimension(dim, agent_budget)

data/lib/smith/workflow/composite/effects.rb

@@ -4,19 +4,32 @@ require_relative "../../types"
 require_relative "../../budget/decimal_context"
 require_relative "../message_value_normalizer"
 require_relative "../prepared_step"
+require_relative "../usage_entry"
 require_relative "payload"
 
 module Smith
   class Workflow
     module Composite
-      class Effects < Payload
+      # Length is fail-closed value validation, not logic: every key the
+      # contract admits gets a bounded value check beside the contract that
+      # admits it. Splitting the checks away from the payload they guard
+      # would trade cohesion for a metric.
+      class Effects < Payload # rubocop:disable Metrics/ClassLength
         attr_reader :total_tokens, :total_cost
 
-        USAGE_ATTRIBUTES = %w[
-          usage_id agent_name model provider input_tokens output_tokens cost attempt_kind recorded_at
-        ].freeze
-        TOOL_ATTRIBUTES = %w[tool captured].freeze
-        private_constant :USAGE_ATTRIBUTES, :TOOL_ATTRIBUTES
+        # Required keys are the pre-attribution UsageEntry shape, so effects
+        # produced by an older Smith (a mid-deploy branch worker or a
+        # restored checkpoint) stay valid; allowed keys are the current
+        # member set, so unknown keys still reject. The attribution members
+        # (transition, branch_key, round, attempt_id) are optional by
+        # construction.
+        USAGE_ALLOWED_ATTRIBUTES = Workflow::UsageEntry.members.map(&:to_s).freeze
+        USAGE_REQUIRED_ATTRIBUTES =
+          (USAGE_ALLOWED_ATTRIBUTES - %w[transition branch_key round attempt_id workflow]).freeze
+        TOOL_REQUIRED_ATTRIBUTES = %w[tool captured].freeze
+        TOOL_ALLOWED_ATTRIBUTES = (TOOL_REQUIRED_ATTRIBUTES + %w[tool_call_id]).freeze
+        private_constant :USAGE_ALLOWED_ATTRIBUTES, :USAGE_REQUIRED_ATTRIBUTES,
+                         :TOOL_REQUIRED_ATTRIBUTES, :TOOL_ALLOWED_ATTRIBUTES
 
         attribute :usage_entries, Types::Array
         attribute :tool_results, Types::Array
@@ -25,17 +38,12 @@ module Smith
         def initialize(attributes)
           owned = self.class.normalize_attributes(attributes)
           normalized = MessageValueNormalizer.new(owned, label: "composite effects").call
-          usage_entries = normalized.fetch("usage_entries")
-          tool_results = normalized.fetch("tool_results")
-          budget_consumed = normalized.fetch("budget_consumed")
+          usage_entries, tool_results, budget_consumed =
+            normalized.values_at("usage_entries", "tool_results", "budget_consumed")
           @total_tokens, @total_cost = validate_usage_entries!(usage_entries)
           validate_tool_results!(tool_results)
           validate_budget!(budget_consumed)
-          super(
-            usage_entries:,
-            tool_results:,
-            budget_consumed:
-          )
+          super(usage_entries:, tool_results:, budget_consumed:)
         end
 
         private
@@ -44,8 +52,9 @@ module Smith
           raise ArgumentError, "composite usage entries must be an Array" unless entries.is_a?(Array)
 
           entries.each do |entry|
-            validate_exact_keys!(entry, USAGE_ATTRIBUTES, "composite usage entry")
+            validate_bounded_keys!(entry, USAGE_REQUIRED_ATTRIBUTES, USAGE_ALLOWED_ATTRIBUTES, "composite usage entry")
             validate_usage_identity!(entry)
+            validate_usage_attribution!(entry)
             validate_usage_amount!(entry.fetch("input_tokens"), "input_tokens")
             validate_usage_amount!(entry.fetch("output_tokens"), "output_tokens")
             validate_cost!(entry.fetch("cost"))
@@ -68,25 +77,40 @@ module Smith
         end
 
         def validate_usage_identity!(entry)
-          validate_usage_id!(entry.fetch("usage_id"))
-          validate_agent_name!(entry.fetch("agent_name"))
-          provider = entry.fetch("provider")
-          validate_nonempty_string!(provider, "composite usage entry provider") if provider
+          validate_uuid!(entry.fetch("usage_id"), "composite usage entry usage_id")
+          # agent_name and provider are nil-allowed; any other value
+          # (false included) must be a non-empty String.
+          %w[agent_name provider].each do |key|
+            value = entry.fetch(key)
+            validate_nonempty_string!(value, "composite usage entry #{key}") unless value.nil?
+          end
           %w[model attempt_kind recorded_at].each do |key|
             validate_nonempty_string!(entry.fetch(key), "composite usage entry #{key}")
           end
         end
 
-        def validate_usage_id!(usage_id)
-          return if usage_id.is_a?(String) && PreparedStep::UUID_PATTERN.match?(usage_id)
+        # The optional attribution keys are bounded values, not just bounded
+        # keys: a present key with a wrong-typed, empty, or oversized value
+        # rejects exactly like the identity fields do. Absent keys (older
+        # producers, or nil-omitting serialization) stay valid.
+        def validate_usage_attribution!(entry)
+          %w[transition branch_key workflow].each do |key|
+            validate_bounded_string!(entry.fetch(key), "composite usage entry #{key}", 256) if entry.key?(key)
+          end
+          validate_usage_amount!(entry.fetch("round"), "round") if entry.key?("round")
+          validate_uuid!(entry.fetch("attempt_id"), "composite usage entry attempt_id") if entry.key?("attempt_id")
+        end
+
+        def validate_uuid!(value, label)
+          return if value.is_a?(String) && PreparedStep::UUID_PATTERN.match?(value)
 
-          raise ArgumentError, "composite usage entry usage_id must be a UUID"
+          raise ArgumentError, "#{label} must be a UUID"
         end
 
-        def validate_agent_name!(agent_name)
-          return if agent_name.nil?
+        def validate_bounded_string!(value, label, max_length)
+          return if value.is_a?(String) && value.length.between?(1, max_length)
 
-          validate_nonempty_string!(agent_name, "composite usage entry agent_name")
+          raise ArgumentError, "#{label} must be a bounded non-empty String"
         end
 
         def validate_nonempty_string!(value, label)
@@ -102,8 +126,7 @@ module Smith
         end
 
         def validate_cost!(cost)
-          return if cost.nil?
-          return if cost.is_a?(Numeric) && cost.finite? && cost >= 0
+          return if cost.nil? || (cost.is_a?(Numeric) && cost.finite? && cost >= 0)
 
           raise ArgumentError, "composite usage entry cost must be a finite non-negative number or nil"
         end
@@ -112,10 +135,15 @@ module Smith
           raise ArgumentError, "composite tool results must be an Array" unless entries.is_a?(Array)
 
           entries.each do |entry|
-            validate_exact_keys!(entry, TOOL_ATTRIBUTES, "composite tool result")
-            tool = entry.fetch("tool")
-            unless tool.is_a?(String) && tool.length.between?(1, 256)
-              raise ArgumentError, "composite tool result tool must be a bounded non-empty String"
+            validate_bounded_keys!(entry, TOOL_REQUIRED_ATTRIBUTES, TOOL_ALLOWED_ATTRIBUTES, "composite tool result")
+            validate_bounded_string!(entry.fetch("tool"), "composite tool result tool", 256)
+
+            # Present only for provider-batch invocations; the producer never
+            # writes a nil, so a present key must carry a real id. Provider
+            # tool-call ids are short strings; 1024 is far above any observed
+            # provider format while still bounding the payload.
+            if entry.key?("tool_call_id")
+              validate_bounded_string!(entry.fetch("tool_call_id"), "composite tool result tool_call_id", 1024)
             end
           end
         end
@@ -130,9 +158,12 @@ module Smith
           end
         end
 
-        def validate_exact_keys!(value, expected, label)
+        # Every required key present, no key outside the allowed set: older
+        # producers (missing optional keys) pass, unknown keys still reject.
+        # Passing the same set for both is an exact-keys check.
+        def validate_bounded_keys!(value, required, allowed, label)
           raise ArgumentError, "#{label} must be a Hash" unless value.is_a?(Hash)
-          return if value.keys.sort == expected.sort
+          return if (required - value.keys).empty? && (value.keys - allowed).empty?
 
           raise ArgumentError, "#{label} attributes are invalid"
         end

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
 
@@ -37,7 +38,7 @@ module Smith
         @context.merge!(step.context_writes)
         step.context_writes.each_key { |key| record_persisted_key!(key) }
         @router_next_transition = step.routed_to if step.routed_to
-        @outcome = snapshot_value(step.outcome) if step.outcome
+        @outcome = symbolize_value(snapshot_value(step.outcome)) if step.outcome
       end
 
       def emit_deterministic_trace(transition, result:, routed_to: nil, error: nil, outcome_kind: nil)

data/lib/smith/workflow/deterministic_step.rb

@@ -15,15 +15,28 @@ 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)
 
-        msg = session_messages.reverse.find { |m| m[:role] == :assistant || m["role"] == "assistant" }
+        msg = session_messages.reverse.find { |m| (m[:role] || m["role"]).to_s == "assistant" }
         @last_output = msg && (msg[:content] || msg["content"])
       end
 
@@ -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

@@ -3,6 +3,9 @@
 module Smith
   class Workflow
     module DSL
+      BUDGET_KEYS = %i[total_tokens token_limit total_cost tool_calls wall_clock].freeze
+      private_constant :BUDGET_KEYS
+
       def self.included(base)
         base.extend(ClassMethods)
       end
@@ -17,6 +20,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 +54,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
@@ -58,6 +67,12 @@ module Smith
         def budget(**opts)
           return @budget_config if opts.empty?
 
+          unknown = opts.keys - BUDGET_KEYS
+          unless unknown.empty?
+            raise ArgumentError, "workflow budget does not accept #{unknown.map(&:inspect).join(", ")}; " \
+                                 "accepted keys are #{BUDGET_KEYS.map(&:inspect).join(", ")}"
+          end
+
           @budget_config = opts
         end
 
@@ -190,11 +205,12 @@ module Smith
         #
         # Wiring contract: when the resolved TTL is non-nil,
         # Workflow#persist! forwards it to the adapter as a `ttl:`
-        # kwarg. Shipped adapters (Memory, RedisStore, CacheStore,
-        # ActiveRecordStore) accept this kwarg; external duck-typed
-        # adapters that implement only the bare REQUIRED_METHODS contract
-        # without a `ttl:` kwarg will only break when a host actually
-        # opts into TTL.
+        # kwarg. Memory, RedisStore, and CacheStore honour it;
+        # ActiveRecordStore cannot expire state and refuses a non-nil TTL
+        # before writing, which a persisted run reaches before its first
+        # step. External duck-typed adapters that implement only the bare
+        # REQUIRED_METHODS contract without a `ttl:` kwarg will only break
+        # when a host actually opts into TTL.
         def persistence_ttl(seconds = nil)
           return @persistence_ttl if seconds.nil?
 
@@ -279,10 +295,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/durability.rb

@@ -389,7 +389,7 @@ module Smith
       def invoke_on_step_callback(step, callback)
         callback&.call(step)
       rescue StandardError => e
-        Smith.config.logger&.error("Smith::Workflow on_step callback error: #{e.message}")
+        Smith.config.logger&.error("Smith::Workflow on_step callback error: #{e.message} (#{e.class})")
       end
     end
   end