smith-agents 0.13.0 → 0.13.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22c04af0f6062eb36758bb0fedc62663d68a27dce67f016942038ffc1ee3cc07
-  data.tar.gz: 0243fe30beb96d8bccc37869cb6ece9a3525ecd83004de98e18d8f97f4de8b8c
+  metadata.gz: 7c3bc332fe08b2ff077b3039603ddc8356ac65d5034f47abcf4253c3e167f8c6
+  data.tar.gz: 9eaf0e8548b473da25838206b63e2a5639d7ee4391f7cb6e30980a5b5aa46e67
 SHA512:
-  metadata.gz: 41b4452c51e7aa3e6946c192e0f6a9eb9bd89163c90886f013dfffd891da55a53f40ce30b00eb90ecebdc5adab3f7373687c7e0ae64be3e32085d6bfc05af47d
-  data.tar.gz: 4007dfee19e37843c993cf9abf5ea57a6e7450141594090fb0579ae013437de6e3053de16c382a88180bb5536b84fdbe951270e0e6707e7a0c73daec9036a569
+  metadata.gz: 1ff7f020acb2efd11f7143a074d3c65093137be5bc2646e10a668e1e5242b37255db15909f0c99aa3b6073ad73e31a2557f61fa3d2a35d2de716ba122d7deb4e
+  data.tar.gz: fab4fd19cd33c21b6800a8d75740bc62533aa4100a2d9ae5e26bad31ad5a1fa57b4869cce9efc9a351b41366ee5ee5a8cb24c0d21dc8369effdbe5b8fd8e703c

data/CHANGELOG.md

@@ -4,6 +4,54 @@ All notable changes to Smith are documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Smith is pre-1.0 and under active development; expect occasional contract tightening between minor versions until 1.0.
 
+## [0.13.1] - 2026-11-08
+
+### Changed
+
+- Split-step persistence refuses a step declared `from: nil` when it is
+  prepared: `prepare_persisted_step!` raises `Smith::WorkflowError` naming
+  the step and saying to run it with `advance_persisted!`, before anything
+  is written, as a prepared step is checked against the state its step is
+  declared from. It is not supported yet. Under 0.13.0 such a step was
+  prepared, which stores its run as a step in progress, and then failed:
+  its work ran first, a parallel or fan-out step's branches included, and
+  then "prepared execution did not return the claimed transition", so a
+  retry ran the work again. Only a parallel or fan-out step whose branches
+  the host ran through `prepare_composite_step!` failed in that call,
+  before any branch ran, its run left in progress all the same. A run
+  stored that way still raises `Smith::StepInProgressOnRestore` in strict
+  mode.
+
+### Fixed
+
+- A failure in a step declared `from: nil` (one that runs from whichever
+  state routes to it) restores. Smith records the failure with the step's
+  declared origin, `from: nil`, as its step result, its `StepFailed` event
+  and its trace have it, but restore refused a record without a `from`
+  state (`Smith::PersistedFailureInvalid`), so a stored run could not go on
+  to the step's `on_failure`, and a run that ended failed there could not
+  be read back. Restore now takes a nil `from`, in lax and strict modes and
+  through every store adapter, and a run stored by 0.13.0 restores as it
+  is. Any other `from`, and its `transition` and `to`, must still be text
+  of 1 to 256 bytes, and a record without the field is still refused.
+- A run whose last failed step was renamed (`renamed_transition`, or
+  `renamed_state` for the state it failed from or was headed to) restores.
+  The names a rename leads to are US-ASCII text, as a Symbol's name is,
+  and restore refused any failure record name not marked UTF-8
+  (`Smith::PersistedFailureInvalid`, "transition is invalid"), so such a
+  run could not go on to the step's `on_failure`, or be read back once it
+  ended failed. A failure record restored from `to_state` itself, without a
+  JSON round trip, was refused the same way. US-ASCII text is UTF-8 as it
+  stands and is now taken as such; text in any other encoding, or with
+  bytes outside its encoding, is still refused. Runs stored by 0.12.7 and
+  later restore as they are.
+
+### Upgrading
+
+- `Smith::EXECUTION_SEMANTICS_VERSION` stays `"7"`: no persisted state,
+  wait, pending retry or durable plan changes shape, and a run stored by
+  0.13.0 restores as it is.
+
 ## [0.13.0] - 2026-11-01
 
 ### Added

data/README.md

@@ -30,7 +30,7 @@ What you get:
 
 ```ruby
 # Gemfile
-gem "smith-agents", "0.13.0", require: "smith"
+gem "smith-agents", "0.13.1", require: "smith"
 ```
 
 In a Rails app:

data/docs/PERSISTENCE.md

@@ -60,6 +60,11 @@ What Smith does for you:
   not the caller's Hash
 - persists accepted session history
 - preserves chosen next transitions across persistence
+- keeps a step's failure across persistence: a restored run takes the step's
+  `on_failure`, and `RunResult#last_error` and `#failure_detail` read as they
+  did in the run that failed. A step declared `from: nil`, which runs from
+  whichever state routes to it, keeps `from: nil` there, as its step result
+  and its `StepFailed` event do
 - supports JSON host round-trips through `to_state` and `.from_state`
 - refuses to restore a payload whose state, or whose pending transition, the
   workflow class does not know (a deploy renamed or removed it, or the payload
@@ -307,6 +312,11 @@ a versioned persistence adapter whose `store_versioned` method accepts `ttl:`,
 and non-expiring workflow persistence. Smith explicitly pins `ttl: nil` for
 every boundary write, so a later global configuration change cannot turn an
 accepted checkpoint into expiring state.
+It does not run a step declared `from: nil` yet: `prepare_persisted_step!`
+refuses one with a `Smith::WorkflowError` naming the step, before anything is
+written, since a prepared step is checked against the state its step is
+declared from. The run itself is unchanged: run that step with
+`advance_persisted!`.
 `prepare_persisted_step!` writes the normal `step_in_progress` marker and returns
 the pending transition name without consuming it. Duplicate preparation on the
 same workflow object is rejected. The boundary is pinned to the exact

data/lib/smith/version.rb

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

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/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

data/lib/smith/workflow/split_step_persistence.rb

@@ -25,6 +25,7 @@ require_relative "split_step_persistence/state_snapshot"
 require_relative "split_step_persistence/preparation_claim"
 require_relative "split_step_persistence/preparation_recovery"
 require_relative "split_step_persistence/preparation"
+require_relative "split_step_persistence/unsupported_steps"
 require_relative "split_step_persistence/restart_safe_adapter"
 require_relative "split_step_persistence/recovery"
 require_relative "split_step_persistence/recovery_boundary"
@@ -66,6 +67,7 @@ module Smith
       include PreparationClaim
       include PreparationRecovery
       include Preparation
+      include UnsupportedSteps
       include RestartSafeAdapter
       include Recovery
       include RecoveryBoundary

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: smith-agents
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.13.1
 platform: ruby
 authors:
 - Samuel Ralak
@@ -592,6 +592,7 @@ files:
 - lib/smith/workflow/split_step_persistence/transition_contract_freezer.rb
 - lib/smith/workflow/split_step_persistence/transition_contract_signature.rb
 - lib/smith/workflow/split_step_persistence/transition_contract_structured_values.rb
+- lib/smith/workflow/split_step_persistence/unsupported_steps.rb
 - lib/smith/workflow/step_completion.rb
 - lib/smith/workflow/step_context.rb
 - lib/smith/workflow/step_io.rb