smith-agents 0.12.6 → 0.12.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97813bcba79ce652b05eb860da067e3c566b8ba3450344d66940c9f65d23a1dc
-  data.tar.gz: ea20e0a30b7517aab44a43b2668cb5e59fde6b98a829056e8e73ba585338f216
+  metadata.gz: 8158004e28c8bec8f58a83727cbfe9d91a7fff89dd24cc3435aefd06f87d826f
+  data.tar.gz: 6b7088fd850554492cbe98edb93c76b2d1958024206eec9a497fd423f7d2b794
 SHA512:
-  metadata.gz: 37d47a1f6268dc96cd05ce69f4138998d1c5a9649bbb41921882b6ae93a8f5d030586c273f37231501c121dd43492e1a37034cefe88981a5f89138cbf1ccd128
-  data.tar.gz: 40eb2c1a4ac979411860e4971b4814e0c2cdaebc39f1a827e956f7fcb2a5ca33c3f34d18aad339edfa1460a8fce07188f505aa174a2e59233d735c50bab258d3
+  metadata.gz: 442ebb9375a3e912f6d98c08da04e67d3aeec1afa8aa1b0f1a45f936e4e33ef9b9dd477d847b113510545a34327451566bd264b3ca2970a26762d61291c5d5f4
+  data.tar.gz: dc3fb7433a59f12a2e947e8eeec20670f4430e5c86b654ad5e1795c4f6e75da753450905de141b409e19162c2f034f070685bf40ef83aa3a93b370abd21fcab6

data/CHANGELOG.md

@@ -4,6 +4,33 @@ 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.12.7] - 2026-10-13
+
+### Added
+
+- A workflow can rename a state or a transition and keep its persisted runs:
+  `renamed_state :old, to: :new` and `renamed_transition :old, to: :new`.
+  On restore, a run persisted under an old name is mapped to the new one
+  before anything checks it: its state, the transition it takes next, the
+  transition its wait, pending retry or pending batch is in, and its last
+  failed step's names, each kept the type it was persisted as. A run waiting
+  in a renamed step resumes there under its wait's own token; one in a
+  renamed state carries on from the new one. A renamed transition keeps its
+  keys: its steps' idempotency keys and wait tokens are made under the first
+  name in its chain (`Workflow.transition_key_name`), so a step cut short, a
+  retry or an early delivery meets the keys its earlier attempt used. Renames
+  chain (a to b, then b to c); a name renamed twice or back to a name it had,
+  and two names renamed to one transition, are refused where declared. A name
+  the class still declares is never taken for an old one, a rename to a name
+  the class does not know is still refused on restore
+  (`Smith::UnknownStateOnRestore`, `UnknownTransitionOnRestore`), and
+  `validate_graph` reports both (`:rename_shadowed`,
+  `:renamed_to_unknown_state`, `:renamed_to_unknown_transition`). Subclasses
+  inherit their parent's renames, and `stuck_for?` follows them. Renames apply
+  after `migrate_from`; no `persistence_schema_version` is needed for one.
+  `Workflow.current_state_name` and `current_transition_name` give what a
+  persisted name stands for now, renames followed.
+
 ## [0.12.6] - 2026-10-13
 
 ### Fixed

data/README.md

@@ -30,7 +30,7 @@ What you get:
 
 ```ruby
 # Gemfile
-gem "smith-agents", "0.12.6", require: "smith"
+gem "smith-agents", "0.12.7", require: "smith"
 ```
 
 In a Rails app:
@@ -137,8 +137,11 @@ Your app delivers events (`resume!`), schedules the timeout
 (`expire_wait!` once `deadline_at` passes), and runs the next step from a
 job. Smith stores runs through an adapter (`:active_record`, `:redis`,
 `:rails_cache`, `:memory` or your own) and refuses a state past
-`persistence_max_bytes`. Waits, child runs, durable retries, replay safety
-and storage: [`docs/PERSISTENCE.md`](docs/PERSISTENCE.md).
+`persistence_max_bytes`. A later version can rename a state or a step
+(`renamed_state :drafted, to: :written`, `renamed_transition :approve, to:
+:review`), and runs persisted under the old names carry on under the new ones,
+waits included, under the keys they had. Waits, child runs, durable retries, replay safety, renames and
+storage: [`docs/PERSISTENCE.md`](docs/PERSISTENCE.md).
 
 ## Agent outputs
 

data/docs/PERSISTENCE.md

@@ -72,12 +72,40 @@ What Smith does for you:
   `migrate_from` and after the `definition_digest` check, so a digest
   mismatch is reported as one and a migration can map an old name: bump
   `persistence_schema_version` and declare `migrate_from(<previous version>)`,
-  since migrations run only when the stored version is behind. Finished runs
-  are refused too, by `restore`, `restore_or_initialize`,
-  `restorable_billing_state?` and the class-level `run_persisted!`: to read the
-  outcome of a finished run whose terminal state was renamed, migrate it or
-  read the stored JSON directly. `stuck_for?` reports a stored run in an
-  unknown state as stuck, since it can neither advance nor restore
+  since migrations run only when the stored version is behind. A rename needs
+  neither: `renamed_state :old, to: :new` and `renamed_transition :old, to:
+  :new` map a run persisted under the old name to the new one after
+  `migrate_from` (a migration sees the names as they were persisted) and
+  before anything checks it (its state, the transition it takes next, the
+  transition its wait, pending retry or pending batch is in, and its last
+  failed step's names, each kept the type it was persisted as), so a run
+  waiting in a renamed step resumes there under its wait's own token. A
+  renamed transition keeps its keys: its steps' idempotency keys and wait
+  tokens are made under the first name in its chain
+  (`Workflow.transition_key_name`), so a step a deploy cut short runs again, a
+  retry makes its next attempt, and a delivery that came before its wait was
+  stored meets the block's token, all under the keys they had before the
+  rename. Renames chain (a to b, then b to c); a name is renamed at most once,
+  never back to a name it had, and at most one name is renamed to a given
+  transition, each refused with `ArgumentError` where it is declared. A name
+  the class still declares is never taken for an old one, and a rename to a
+  name the class does not know is refused as above when a run restores
+  through it; `validate_graph` reports both before then (`:rename_shadowed`,
+  a warning; `:renamed_to_unknown_state` and `:renamed_to_unknown_transition`,
+  errors). A subclass inherits its parent's renames. A state's rename stays
+  declared while runs persisted under its old name may remain; a
+  transition's, for good, since dropping it moves the transition's keys to
+  its new name.
+  `Workflow.current_state_name` and `current_transition_name` give what a
+  persisted name stands for now, renames followed. In strict mode a payload
+  caught mid-step is refused before renames apply, so
+  `Smith::StepInProgressOnRestore` names its transition as persisted. Finished
+  runs are refused too, by `restore`, `restore_or_initialize`,
+  `restorable_billing_state?` and the class-level `run_persisted!`: a finished
+  run whose terminal state was renamed restores while the rename is declared;
+  to read one whose terminal state was removed, migrate it or read the stored
+  JSON directly. `stuck_for?` reports a stored run in an unknown state
+  (renames followed) as stuck, since it can neither advance nor restore
 
 `preserve_seed: true` is intended for workflows whose seed is durable external
 conversation and whose later accepted outputs are internal stage handoffs. Smith
@@ -860,8 +888,9 @@ end
   transition raises `Smith::SerializationError`; one whose transition the
   class no longer declares exactly (kind, event, `into:`) or that does not
   start from the run's state raises `Smith::UnknownTransitionOnRestore`. A
-  `migrate_from` that renames such things must rewrite `awaiting` too, and
-  `pending_retry` for a retry wait.
+  rename declared with `renamed_transition` (or `renamed_state`) maps the
+  wait's transition first; a `migrate_from` that renames such things itself
+  must rewrite `awaiting` too, and `pending_retry` for a retry wait.
 - A wait that does not end within the store's persistence TTL is refused when
   it is entered, before the block runs. `stuck_for?` reports a waiting run as stuck
   only once its deadline has passed by the threshold.

data/lib/smith/version.rb

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

data/lib/smith/workflow/child_run_execution.rb

@@ -141,7 +141,8 @@ module Smith
         check_deadline!
         namespace = ArtifactIntegration.instance_method(:execution_namespace).bind_call(self)
         token = IdempotencyKey.__send__(:root_scope, namespace)
-                              .within(:step, @step_count + 1, transition.name.to_s).within(:spawn).key
+                              .within(:step, @step_count + 1, self.class.transition_key_name(transition.name))
+                              .within(:spawn).key
         launch_child_runs(transition, token)
         nil
       end

data/lib/smith/workflow/dsl.rb

@@ -33,6 +33,8 @@ module Smith
           subclass.instance_variable_set(:@persistence_key_builder, @persistence_key_builder)
           subclass.instance_variable_set(:@persistence_schema_version, @persistence_schema_version)
           subclass.instance_variable_set(:@migrations, (@migrations || {}).dup)
+          subclass.instance_variable_set(:@renamed_states, @renamed_states)
+          subclass.instance_variable_set(:@renamed_transitions, @renamed_transitions)
           subclass.instance_variable_set(:@seed_validation_mode, @seed_validation_mode)
           subclass.instance_variable_set(:@idempotency_mode, @idempotency_mode)
           subclass.instance_variable_set(:@session_mode, @session_mode)
@@ -165,6 +167,77 @@ module Smith
           @migrations || {}
         end
 
+        # A state a later version renamed: a run persisted in `old`
+        # restores in `to` and carries on from there. Renames chain (a to
+        # b, then b to c); a name is renamed at most once and never back
+        # to a name it had. A name the class still declares is never taken
+        # for an old one (validate_graph warns of such a rename). The
+        # persisted run is mapped after migrate_from, before anything
+        # checks its names, so a rename needs no persistence_schema_version.
+        # A rename stays declared while runs persisted under its old name
+        # may remain.
+        def renamed_state(old, to:)
+          @renamed_states = renamed_name_map(renamed_states, old, to, kind: "state")
+        end
+
+        # A transition a later version renamed: a run persisted about to
+        # take `old`, or waiting in it (its wait, pending retry or batch),
+        # restores at `to`, as renamed_state. A renamed transition keeps
+        # its keys: its steps' idempotency keys and wait tokens are made
+        # under the first name in its chain (transition_key_name), so a
+        # step a deploy cut short, a retry or an early delivery meets the
+        # keys its earlier attempt used. Hence at most one name is renamed
+        # to a transition, and the rename stays declared for good: dropping
+        # it moves the transition's keys to its new name.
+        def renamed_transition(old, to:)
+          renames = renamed_name_map(renamed_transitions, old, to, kind: "transition")
+          earlier = renamed_transitions.key(renames.fetch(old.to_s))
+          if earlier
+            raise ArgumentError, "transition #{to.inspect} is already the new name of #{earlier.inspect}; a " \
+                                 "transition keeps the keys of one first name, so only one name is renamed to it"
+          end
+
+          @renamed_transitions = renames
+        end
+
+        def renamed_states
+          @renamed_states || {}.freeze
+        end
+
+        def renamed_transitions
+          @renamed_transitions || {}.freeze
+        end
+
+        # The state a persisted state name stands for now, renames
+        # followed, or nil when the class knows none. `O(R·(S + T))` for
+        # `R` renamed states.
+        def current_state_name(name)
+          return if name.nil?
+
+          resolve_state_name(follow_renames(name, renamed_states) { |candidate| resolve_state_name(candidate) })
+        end
+
+        # The transition a persisted transition name stands for now,
+        # renames followed, or nil when the class knows none. `O(R·T)` for
+        # `R` renamed transitions.
+        def current_transition_name(name)
+          return if name.nil?
+
+          transition_named(follow_renames(name, renamed_transitions) { |candidate| transition_named(candidate) })&.name
+        end
+
+        # The name a transition's steps are keyed under (their idempotency
+        # keys and wait tokens): the first name in its rename chain, so a
+        # renamed transition keeps its keys. Renames have no cycles and at
+        # most one name renamed to each, so the chain back is a line.
+        # `O(R)` for `R` renamed transitions.
+        def transition_key_name(name)
+          earlier = renamed_transitions.invert
+          current = name.to_s
+          current = earlier[current] while earlier.key?(current)
+          current
+        end
+
         # Controls whether restore validates that the seed_messages
         # builder still produces the same digest as when this workflow
         # was originally persisted.
@@ -313,6 +386,56 @@ module Smith
           Identifier.normalize(identifier, label: "workflow identifier")
         end
 
+        # The renames with `old` renamed to `to`: refused when `old` is
+        # already renamed, or when the chain from `to` leads back to `old`
+        # (a rename back), so every chain is a line. `O(R)`.
+        def renamed_name_map(renames, old, to, kind:)
+          old_name = renamed_identifier(old, kind:)
+          new_name = renamed_identifier(to, kind:)
+          check_rename!(renames, old_name, new_name, kind:)
+          renames.merge(old_name => new_name).freeze
+        end
+
+        def check_rename!(renames, old_name, new_name, kind:)
+          if old_name == new_name
+            raise ArgumentError, "a renamed #{kind} must differ from its new name, got #{old_name.inspect}"
+          end
+
+          if renames.key?(old_name)
+            raise ArgumentError, "#{kind} #{old_name.inspect} is already renamed to #{renames[old_name].inspect}; " \
+                                 "rename #{renames[old_name].inspect} instead"
+          end
+
+          return unless renamed_back?(renames, old_name, new_name)
+
+          raise ArgumentError, "#{kind} #{new_name.inspect} was renamed from #{old_name.inspect}; a #{kind} is " \
+                               "never renamed back to a name it had"
+        end
+
+        def renamed_back?(renames, old_name, new_name)
+          current = new_name
+          current = renames[current] while renames.key?(current) && current != old_name
+          current == old_name
+        end
+
+        def renamed_identifier(name, kind:)
+          unless (name.is_a?(Symbol) || name.is_a?(String)) && !name.to_s.strip.empty?
+            raise ArgumentError, "a renamed #{kind} must be a non-blank Symbol or String, got #{name.inspect}"
+          end
+
+          name.to_s
+        end
+
+        # The name `name` stands for now: itself while the class declares
+        # it (`declared` says so), else where its renames lead. Chains are
+        # lines (renamed_name_map), so the walk ends. `O(R)` calls of
+        # `declared`.
+        def follow_renames(name, renames, &declared)
+          current = name.to_s
+          current = renames[current] until declared.call(current) || !renames.key?(current)
+          current
+        end
+
         def transitions_by_state
           @transitions_by_state ||= Hash.new { |index, state| index[state] = [] }
         end

data/lib/smith/workflow/durability.rb

@@ -244,10 +244,11 @@ module Smith
           false
         end
 
-        # A state the class no longer knows can never advance or restore, so
-        # it is not terminal: an old one reports as stuck.
+        # A state the class no longer knows, renames followed, can never
+        # advance or restore, so it is not terminal: an old one reports as
+        # stuck.
         def terminal_payload_state?(klass, state_name, next_transition)
-          state = klass.resolve_state_name(state_name)
+          state = klass.current_state_name(state_name)
           !state.nil? && !klass.transition_from?(state) && next_transition.nil?
         end
 

data/lib/smith/workflow/graph/rename_diagnostics.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Graph
+      # Renames (renamed_state, renamed_transition) found wanting before a
+      # run restores through one: a rename leading to no name the workflow
+      # declares is an error, as a run persisted under its old name cannot
+      # restore; one whose old name the workflow still declares is a
+      # warning, as a run persisted under that name stays there.
+      # `O(R·(S + T))` for `R` renames.
+      class RenameDiagnostics
+        attr_reader :graph
+
+        def initialize(graph)
+          @graph = graph
+        end
+
+        def to_a
+          workflow = graph.workflow_class
+
+          [
+            *diagnostics_for(:state, workflow.renamed_states) do |name|
+              [workflow.resolve_state_name(name), workflow.current_state_name(name)]
+            end,
+            *diagnostics_for(:transition, workflow.renamed_transitions) do |name|
+              [workflow.transition_named(name), workflow.current_transition_name(name)]
+            end
+          ]
+        end
+
+        private
+
+        def diagnostics_for(kind, renames)
+          renames.filter_map do |old, new|
+            declared, current = yield(old)
+            if declared
+              shadowed(kind, old, new)
+            elsif current.nil?
+              leads_nowhere(kind, old, new)
+            end
+          end
+        end
+
+        def shadowed(kind, old, new)
+          Diagnostic.new(
+            severity: :warning,
+            code: :rename_shadowed,
+            kind => old,
+            message: "Renamed #{kind} #{old.inspect} is still declared, so a run persisted in it stays there " \
+                     "rather than moving to #{new.inspect}.",
+            suggestion: "Drop the rename, or move such runs with persistence_schema_version and migrate_from."
+          )
+        end
+
+        def leads_nowhere(kind, old, new)
+          Diagnostic.new(
+            severity: :error,
+            code: :"renamed_to_unknown_#{kind}",
+            kind => old,
+            message: "Renamed #{kind} #{old.inspect} leads through #{new.inspect} to no #{kind} this workflow " \
+                     "declares, so a run persisted in it cannot restore.",
+            suggestion: "Declare #{kind} #{new.inspect} or rename #{old.inspect} to a declared #{kind}."
+          )
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/graph/validator.rb

@@ -29,6 +29,7 @@ module Smith
         def all_diagnostics
           [
             *StateDiagnostics.new(graph).to_a,
+            *RenameDiagnostics.new(graph).to_a,
             *TransitionDiagnostics.new(graph).to_a,
             *ReachabilityDiagnostics.new(graph, reachable_transition_names).to_a
           ]

data/lib/smith/workflow/graph.rb

@@ -88,6 +88,7 @@ require_relative "graph/identifier_projection"
 require_relative "graph/transition_contract"
 require_relative "graph/diagnostic"
 require_relative "graph/state_diagnostics"
+require_relative "graph/rename_diagnostics"
 require_relative "graph/targets"
 require_relative "graph/execution_successors"
 require_relative "graph/reachability"

data/lib/smith/workflow/persistence.rb

@@ -87,7 +87,7 @@ module Smith
       def restore_state(hash, allow_step_in_progress: false)
         validate_raw_step_in_progress!(hash) if
           self.class.idempotency_mode == :strict && !allow_step_in_progress
-        migrated = migrate_if_needed(hash)
+        migrated = apply_renames(migrate_if_needed(hash))
         normalized = normalize_persisted_state(migrated)
         persistence_version = validated_persistence_version(normalized)
         restore_persisted_keys(normalized)
@@ -447,6 +447,74 @@ module Smith
         payload
       end
 
+      # A run persisted under names a later version renamed
+      # (renamed_state, renamed_transition) carries on under the new
+      # ones: its state, the transition it takes next, the transition its
+      # wait, pending retry and pending batch are in, and its last failed
+      # step's names, each kept the type it was persisted as. A name the
+      # class still declares stays as it is.
+      RENAMED_RECORDS = {
+        awaiting: { transition: %w[transition] },
+        pending_retry: { transition: %w[transition] },
+        pending_batch: { transition: %w[transition] },
+        last_failed_step: { transition: %w[transition], state: %w[from to] }
+      }.freeze
+      private_constant :RENAMED_RECORDS
+
+      def apply_renames(payload)
+        return payload unless renames?
+
+        renamed = payload.dup
+        renamed[:state] = renamed_state_name(payload[:state])
+        renamed[:next_transition_name] = renamed_transition_name(payload[:next_transition_name]) if
+          payload.key?(:next_transition_name)
+        RENAMED_RECORDS.each_key { |key| renamed[key] = renamed_record(payload[key], RENAMED_RECORDS[key]) }
+        renamed
+      end
+
+      def renames? = !(self.class.renamed_states.empty? && self.class.renamed_transitions.empty?)
+
+      def renamed_state_name(name)
+        renamed_value(name) do |text|
+          self.class.send(:follow_renames, text, self.class.renamed_states) do |candidate|
+            self.class.resolve_state_name(candidate)
+          end
+        end
+      end
+
+      def renamed_transition_name(name)
+        renamed_value(name) do |text|
+          self.class.send(:follow_renames, text, self.class.renamed_transitions) do |candidate|
+            self.class.transition_named(candidate)
+          end
+        end
+      end
+
+      # A persisted name renamed, kept the type it was persisted as.
+      def renamed_value(name)
+        return name unless name.is_a?(String) || name.is_a?(Symbol)
+
+        renamed = yield(name.to_s)
+        name.is_a?(Symbol) ? renamed.to_sym : renamed
+      end
+
+      # A persisted record's name fields renamed, each by its kind
+      # (:state or :transition), under String or Symbol keys alike.
+      def renamed_record(record, fields_by_kind)
+        return record unless record.is_a?(Hash)
+
+        renamed = record.dup
+        fields_by_kind.each do |kind, fields|
+          fields.each do |field|
+            key = [field, field.to_sym].find { |candidate| renamed.key?(candidate) }
+            next if key.nil?
+
+            renamed[key] = kind == :state ? renamed_state_name(renamed[key]) : renamed_transition_name(renamed[key])
+          end
+        end
+        renamed
+      end
+
       def normalize_persisted_state(hash)
         normalized = snapshot_value(hash).transform_keys { |k| k.is_a?(String) ? k.to_sym : k }
         normalized[:outcome] = symbolize_value(normalized[:outcome]) if normalized[:outcome].is_a?(Hash)

data/lib/smith/workflow/step_context.rb

@@ -99,7 +99,8 @@ module Smith
         namespace = ArtifactIntegration.instance_method(:execution_namespace).bind_call(self)
         outer = IdempotencyKey.__send__(:current_scope)
         base = outer && outer.run == namespace ? outer : IdempotencyKey.__send__(:root_scope, namespace)
-        IdempotencyKey.__send__(:install, base.within(:step, @step_count + 1, transition.name.to_s))
+        position = base.within(:step, @step_count + 1, self.class.transition_key_name(transition.name))
+        IdempotencyKey.__send__(:install, position)
       end
 
       def teardown_step_context

data/lib/smith/workflow/wait_execution.rb

@@ -140,7 +140,8 @@ module Smith
 
       def wait_token_for(transition, scope)
         IdempotencyKey.__send__(:root_scope, ArtifactIntegration.instance_method(:execution_namespace).bind_call(self))
-                      .within(:step, @step_count + 1, transition.name.to_s).within(:wait).key(scope)
+                      .within(:step, @step_count + 1, self.class.transition_key_name(transition.name))
+                      .within(:wait).key(scope)
       end
 
       def check_wait_admissible!(transition, seconds)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: smith-agents
 version: !ruby/object:Gem::Version
-  version: 0.12.6
+  version: 0.12.7
 platform: ruby
 authors:
 - Samuel Ralak
@@ -485,6 +485,7 @@ files:
 - lib/smith/workflow/graph/reachability.rb
 - lib/smith/workflow/graph/reachability_diagnostics.rb
 - lib/smith/workflow/graph/reference.rb
+- lib/smith/workflow/graph/rename_diagnostics.rb
 - lib/smith/workflow/graph/report.rb
 - lib/smith/workflow/graph/retry_policy_diagnostic.rb
 - lib/smith/workflow/graph/run_launcher_diagnostic.rb