smith-agents 0.11.0 → 0.12.1

data/lib/smith/doctor/checks/durability.rb

@@ -52,19 +52,13 @@ module Smith
         end
 
         def self.check_persist_and_restore(report, adapter)
-          workflow_class = build_probe_class
-          payload = JSON.generate(workflow_class.new.to_state)
-
-          adapter.store(PROBE_KEY, payload)
-          restored_payload = adapter.fetch(PROBE_KEY)
-          restored = workflow_class.from_state(JSON.parse(restored_payload))
-          adapter.delete(PROBE_KEY)
-
+          restored = probe_round_trip(adapter)
           valid = restored.state == :idle
           report.add(
             name: "durability.persist_restore",
             status: valid ? :pass : :fail,
-            message: valid ? "Host persistence round-trip works" : "Host persistence round-trip failed"
+            message: valid ? "Host persistence round-trip works" : "Host persistence round-trip failed",
+            detail: "Written as runs write, with #{probe_write(adapter)}"
           )
         rescue StandardError => e
           report.add(
@@ -74,15 +68,7 @@ module Smith
         end
 
         def self.check_resume_after_restore(report, adapter)
-          workflow_class = build_probe_class
-          payload = JSON.generate(workflow_class.new.to_state)
-
-          adapter.store(PROBE_KEY, payload)
-          restored_payload = adapter.fetch(PROBE_KEY)
-          restored = workflow_class.from_state(JSON.parse(restored_payload))
-          adapter.delete(PROBE_KEY)
-
-          result = restored.run!
+          result = probe_round_trip(adapter).run!
           valid = result.state == :done
 
           report.add(
@@ -95,6 +81,22 @@ module Smith
                      message: "Resume after restore failed", detail: e.message)
         end
 
+        # A probe run stored as runs are (Workflow#persist!: store_versioned
+        # where the adapter has it, and persistence_max_bytes) and restored.
+        def self.probe_round_trip(adapter)
+          workflow_class = build_probe_class
+          adapter.delete(PROBE_KEY)
+          workflow_class.new.persist!(PROBE_KEY, adapter:)
+          workflow_class.restore(PROBE_KEY, adapter:)
+        ensure
+          adapter.delete(PROBE_KEY)
+        end
+
+        def self.probe_write(adapter)
+          versioned = ::Smith::PersistenceAdapters.supports?(adapter, :store_versioned)
+          versioned ? "store_versioned" : "plain store (the adapter has no store_versioned)"
+        end
+
         def self.build_probe_class
           Class.new(::Smith::Workflow) do
             initial_state :idle

data/lib/smith/doctor/checks/state_model.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Smith
+  module Doctor
+    module Checks
+      # Whether an ActiveRecord persistence adapter's model can hold runs:
+      # its locking column, a text payload, and a string key the database
+      # keeps unique. It reads schema metadata only, and skips when the
+      # database cannot be reached (the default doctor run is offline).
+      # Other adapters, and an adapter configuration that does not resolve
+      # (Durability reports it), are not checked.
+      module StateModel
+        NAME = "persistence.state_model"
+
+        module_function
+
+        def run(report)
+          adapter = active_record_adapter
+          return unless adapter
+
+          adapter.check_schema!
+          report.add(name: NAME, status: :pass,
+                     message: "The workflow state model has a lock_version, a text payload and a unique key")
+          report_encryption(report) if adapter.encrypted_payload?
+        rescue StandardError => e
+          report_failure(report, e)
+        end
+
+        def report_failure(report, error)
+          if unreachable?(error)
+            report.add(name: NAME, status: :skip, detail: error.class.name,
+                       message: "The workflow state model was not checked: the database could not be reached")
+          else
+            report.add(name: NAME, status: :fail, message: "The workflow state model cannot hold runs",
+                       detail: error.message)
+          end
+        end
+
+        def report_encryption(report)
+          report.add(name: "#{NAME}.encryption", status: :warn,
+                     message: "The workflow state payload is encrypted",
+                     detail: "Runs store and read it, but split-step exact writes (replace_exact) compare " \
+                             "payloads in the database and cannot use an encrypted one")
+        end
+
+        def unreachable?(error)
+          classes = PersistenceAdapters::ActiveRecordConnectionErrors.classes
+          classes << ::ActiveRecord::NoDatabaseError if defined?(::ActiveRecord::NoDatabaseError)
+          classes.any? { error.is_a?(_1) }
+        end
+
+        def active_record_adapter
+          return unless ::Smith.config.persistence_adapter
+
+          adapter = ::Smith.persistence_adapter
+          adapter if adapter.is_a?(::Smith::PersistenceAdapters::ActiveRecordStore)
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/smith/doctor/installer.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "erb"
 require "fileutils"
 
 module Smith
@@ -41,8 +42,9 @@ module Smith
       end
 
       def rails_template
+        # The generator's initializer, as `rails g smith:install --skip-state-model` writes it.
         template_path = File.expand_path("../../generators/smith/install/templates/smith.rb.tt", __dir__)
-        File.read(template_path)
+        ERB.new(File.read(template_path), trim_mode: "-").result_with_hash(options: { skip_state_model: true })
       end
 
       def plain_template
@@ -78,7 +80,12 @@ module Smith
             #   store(key, payload)
             #   fetch(key)
             #   delete(key)
-            config.artifact_store = Smith::Artifacts::Memory.new
+            #
+            # Artifacts (large outputs, attached documents) need a store that
+            # outlives the process: :s3 (S3, R2) or :active_record, with
+            # config.artifact_options; :memory keeps them in this process.
+            # config.artifact_store = :s3
+            # config.artifact_options = { bucket: "smith-artifacts", region: "us-east-1" }
             config.trace_adapter = Smith::Trace::Memory.new
           end
         RUBY

data/lib/smith/doctor.rb

@@ -15,6 +15,8 @@ require_relative "doctor/checks/live"
 require_relative "doctor/checks/models_registry"
 require_relative "doctor/checks/openai_api_mode"
 require_relative "doctor/checks/persistence_capabilities"
+require_relative "doctor/checks/artifacts"
+require_relative "doctor/checks/state_model"
 
 module Smith
   module Doctor
@@ -23,6 +25,8 @@ module Smith
 
       Checks::Baseline.run(report)
       Checks::Configuration.run(report)
+      Checks::Artifacts.run(report)
+      Checks::StateModel.run(report)
       Checks::ModelsRegistry.run(report)
       Checks::OpenaiApiMode.run(report)
       Checks::Rails.run(report) if detect_rails?

data/lib/smith/errors.rb

@@ -69,6 +69,21 @@ module Smith
   end
 
   class BudgetExceeded < Error; end
+
+  # A host's budget ledger (`budget_ledger`) refused a provider request's
+  # hold; nothing was sent. A BudgetExceeded, so it is not retried unless a
+  # step's `retry_on` names it (a durable retry waits for budget). One that
+  # paused a tool loop carries its `continuation` (Budget::Continuation),
+  # which the step's retry continues from.
+  class BudgetUnavailable < BudgetExceeded
+    attr_reader :continuation
+
+    def initialize(message = "the budget ledger refused the request", continuation: nil)
+      @continuation = continuation
+      super(message)
+    end
+  end
+
   class DeadlineExceeded < Error; end
   class MaxTransitionsExceeded < Error; end
   class GuardrailFailed < Error; end
@@ -151,13 +166,32 @@ module Smith
 
   class WorkflowError < Error; end
 
+  # A host's budget ledger (`budget_ledger`) could not be built or failed to
+  # answer `reserve!` (its service down, say); nothing was sent. Not a
+  # provider failure, so no fallback model is tried; not retried unless a
+  # step's `retry_on` names it.
+  class BudgetLedgerError < WorkflowError
+    def initialize(message = "the budget ledger failed") = super
+  end
+
   class DeterministicStepFailure < WorkflowError
-    attr_reader :retryable, :kind, :details
+    attr_reader :retryable, :kind, :details, :new_idempotency_key, :idempotency_scope
+
+    # `new_idempotency_key: true` declares that the failed attempt's own
+    # requests took no effect, so a retry of the step that raised it sends
+    # them under new keys; `idempotency_scope` is that step's position. The
+    # flag is not persisted with the failure record.
+    def initialize(message, retryable: nil, kind: nil, details: nil, new_idempotency_key: false, # rubocop:disable Metrics/ParameterLists
+                   idempotency_scope: nil)
+      unless [true, false, nil].include?(new_idempotency_key)
+        raise ArgumentError, "new_idempotency_key must be true or false"
+      end
 
-    def initialize(message, retryable: nil, kind: nil, details: nil)
       @retryable = retryable
       @kind = kind
       @details = details
+      @new_idempotency_key = new_idempotency_key == true
+      @idempotency_scope = idempotency_scope
       super(message)
     end
   end
@@ -173,6 +207,141 @@ module Smith
     end
   end
 
+  # An `await` step passed its deadline before `resume!` delivered its
+  # event, and the transition declares no `on_timeout` route. It takes the
+  # failure path (`on_failure`, or a raise) and is never retried.
+  class WaitTimedOut < WorkflowError
+    DETAIL_NAMES = %w[transition event deadline_at].freeze
+    private_constant :DETAIL_NAMES
+
+    attr_reader :transition, :event, :deadline_at
+
+    def initialize(transition:, event:, deadline_at:, message: nil)
+      @transition = DiagnosticText.capture(transition.to_s, max_bytes: 256)
+      @event = DiagnosticText.capture(event.to_s, max_bytes: 256)
+      @deadline_at = DiagnosticText.capture(deadline_at.to_s, max_bytes: 64)
+      super(message || "await #{@event} on transition #{@transition} passed its deadline #{@deadline_at}")
+    end
+
+    # Kept with the failure record, so a restored run's error is still a
+    # WaitTimedOut that names its wait.
+    def details = { transition:, event:, deadline_at: }.freeze
+
+    def self.from_details(details, message: nil)
+      raise ArgumentError, "wait timeout details must be a Hash" unless details.is_a?(Hash)
+
+      values = details.to_h { |key, value| [key.to_s, value] }
+      unless values.keys.sort == DETAIL_NAMES.sort && values.values.all?(String)
+        raise ArgumentError, "wait timeout details are invalid"
+      end
+
+      new(transition: values["transition"], event: values["event"], deadline_at: values["deadline_at"], message:)
+    end
+  end
+
+  # A `compute` or `run` step that declares `routes:` finished without
+  # calling `route_to`, declares no `on_success`, and did not opt into
+  # `fallthrough: true`. Without this error the run would silently take the
+  # first transition declared from the step's target state.
+  class UnroutedDeterministicStep < WorkflowError
+    attr_reader :transition, :routes
+
+    def initialize(transition:, routes:)
+      @transition = transition
+      @routes = routes
+      super(
+        "#{DiagnosticText.capture(transition.inspect, max_bytes: 256)} declares routes: " \
+        "#{DiagnosticText.capture(routes.inspect, max_bytes: 1024)} but did not call route_to; " \
+        "route to one of them, declare on_success, or opt into fallthrough: true"
+      )
+    end
+  end
+
+  # A deterministic step wrote a context key that the workflow's
+  # Smith::Context does not list in `persist :a, :b`. The write would be
+  # dropped at the next checkpoint, so it fails the step instead.
+  class UndeclaredContextKey < WorkflowError
+    attr_reader :key, :persisted_keys
+
+    def initialize(key:, persisted_keys:)
+      @key = key
+      @persisted_keys = persisted_keys
+      super(
+        "context key #{DiagnosticText.capture(key.inspect, max_bytes: 256)} is not a persisted context key " \
+        "(persist #{DiagnosticText.capture(persisted_keys.map(&:inspect).join(", "), max_bytes: 1024)}); " \
+        "declare it in the context's persist list, or use persist :auto"
+      )
+    end
+  end
+
+  # A step's content parts cannot be sent: a document or image is missing,
+  # unreadable, empty, not what its media type says, or past a bound, or no
+  # model in the chain takes it. Raised before the provider call, so it is
+  # never retried as a provider failure.
+  class ContentUnavailable < WorkflowError; end
+
+  # No artifact store is configured. Artifacts must outlive the process that
+  # stored them whenever a run waits, retries or resumes elsewhere, so Smith
+  # assumes none outside test_mode.
+  class ArtifactStoreMissing < WorkflowError
+    def initialize(message = "Smith.config.artifact_store is not configured; set it to :s3, :active_record or " \
+                             ":file (or a store) for runs that wait, retry or move between processes, or :memory " \
+                             "for a single process")
+      super
+    end
+  end
+
+  # A step streams to a sink Smith.config.stream_sinks does not name.
+  # Raised before the step's provider call.
+  class StreamSinkMissing < WorkflowError
+    def initialize(name)
+      super("Smith.config.stream_sinks has no sink #{name.inspect}; register the sink the step streams to")
+    end
+  end
+
+  # A step sends its request as a batch and Smith.config.batch_queue is not
+  # configured. Raised before anything is sent.
+  class BatchQueueMissing < WorkflowError
+    def initialize(message = "Smith.config.batch_queue is not configured; batch mode hands its requests to it")
+      super
+    end
+  end
+
+  # A batch step's call cannot go as a batch: its model's provider has no
+  # batch interface in Smith (Anthropic has), or its agent has tools (a batch
+  # request is one turn). Raised before anything is sent.
+  class BatchModeUnavailable < WorkflowError; end
+
+  # A batch result that did not answer: a server error (`errored`), a
+  # `canceled` or `expired` request, or none by the wait's deadline
+  # (`missing`). An AgentError, so `retry_on` sends it again.
+  class BatchResultFailed < AgentError
+    attr_reader :kind, :error_type
+
+    def initialize(kind:, error_type: nil)
+      @kind = kind.to_s.dup.freeze
+      @error_type = DiagnosticText.capture(error_type.to_s, max_bytes: 128) if error_type
+      super("batch result #{@kind}#{" (#{@error_type})" if @error_type}")
+    end
+  end
+
+  # A batch result answers a request other than the one its step renders
+  # now (a date in the prompt, data read afresh, a changed prompt), and the
+  # step declares `on_request_change: :fail`. An AgentError, so `retry_on`
+  # may send the request again (synchronously, if the mode callable says so
+  # at the next attempt); the result is charged all the same.
+  class BatchRequestChanged < AgentError
+    def initialize(message = "the step renders another request than its batch result answers") = super
+  end
+
+  # The provider refused a batch request as invalid; sending it again would
+  # be refused again.
+  class BatchRequestInvalid < WorkflowError
+    def initialize(message = "the provider refused the batch request as invalid")
+      super
+    end
+  end
+
   class SerializationError < Error; end
   class AgentRegistryError < Error; end
 
@@ -190,6 +359,42 @@ module Smith
     end
   end
 
+  # A workflow state past Smith.config.persistence_max_bytes. A stored
+  # run's step whose result would not fit fails with it before the result
+  # is kept (its usage recorded, `on_failure` taken; a response memo keeps
+  # what its calls got). Any other state past the bound is refused when it
+  # is stored, before anything is written, and the stored state stays as it
+  # was.
+  class PersistedStateTooLarge < WorkflowError
+    DETAIL_NAMES = %w[key bytes limit].freeze
+
+    attr_reader :key, :bytes, :limit
+
+    def initialize(key:, bytes:, limit:, message: nil)
+      @key = key
+      @bytes = bytes
+      @limit = limit
+      super(message || "the workflow state for #{key.inspect} is #{bytes} bytes, past persistence_max_bytes (#{limit})")
+    end
+
+    def details = { key:, bytes:, limit: }.freeze
+
+    def self.from_details(details, message: nil)
+      raise ArgumentError, "state size details must be a Hash" unless details.is_a?(Hash)
+
+      values = details.to_h { |name, value| [name.to_s, value] }
+      raise ArgumentError, "state size details are invalid" unless details?(values)
+
+      new(key: values["key"], bytes: values["bytes"], limit: values["limit"], message:)
+    end
+
+    def self.details?(values)
+      values.keys.sort == DETAIL_NAMES.sort && values["key"].is_a?(String) &&
+        values.values_at("bytes", "limit").all? { _1.is_a?(Integer) && _1.positive? }
+    end
+    private_class_method :details?
+  end
+
   # Raised when an adapter's optimistic-lock check detects a concurrent
   # write: another process modified the key between this process's
   # restore and persist. Hosts can rescue + restore + retry, or fail
@@ -252,6 +457,48 @@ module Smith
     end
   end
 
+  # Raised when a persisted payload's state is not one the restoring
+  # workflow class knows: neither declared with `state` nor named by any
+  # transition's `from:` or `to:`. Usually a deploy renamed or removed the
+  # state while a run was persisted. Restoring anyway would treat the
+  # unknown state as terminal and end the run silently. Hosts bridge a
+  # rename with `migrate_from`, or let the run finish on the workflow
+  # version that declared the state.
+  class UnknownStateOnRestore < Error
+    attr_reader :workflow, :persistence_key, :state
+
+    def initialize(workflow:, persistence_key:, state:)
+      @workflow = workflow
+      @persistence_key = persistence_key
+      @state = state
+      super(
+        "unknown state #{DiagnosticText.capture(state.inspect, max_bytes: 256)} restoring #{workflow} " \
+        "key=#{DiagnosticText.capture(persistence_key.inspect, max_bytes: 256)}: bump " \
+        "persistence_schema_version and declare `migrate_from` to map it, or finish the run on the " \
+        "workflow version that declared it."
+      )
+    end
+  end
+
+  # Raised when a persisted payload's pending transition is not declared by
+  # the restoring workflow class, for the same reasons as
+  # UnknownStateOnRestore.
+  class UnknownTransitionOnRestore < Error
+    attr_reader :workflow, :persistence_key, :transition
+
+    def initialize(workflow:, persistence_key:, transition:)
+      @workflow = workflow
+      @persistence_key = persistence_key
+      @transition = transition
+      super(
+        "unknown pending transition #{DiagnosticText.capture(transition.inspect, max_bytes: 256)} restoring " \
+        "#{workflow} key=#{DiagnosticText.capture(persistence_key.inspect, max_bytes: 256)}: bump " \
+        "persistence_schema_version and declare `migrate_from` to map it, or finish the run on the " \
+        "workflow version that declared it."
+      )
+    end
+  end
+
   # Raised when restoring a persisted payload whose schema_version does
   # not match the workflow's current persistence_schema_version AND no
   # migration block is registered to bridge the gap. Hosts fix this by

data/lib/smith/idempotency_key/canonical.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Smith
+  module IdempotencyKey
+    MAX_SCOPE_DEPTH = 32
+    MAX_SCOPE_NODES = 100_000
+
+    module Canonical
+      module_function
+
+      # The JSON form a scope is hashed in: Symbols become Strings, Hash
+      # entries are sorted by key, and a Float with a whole value becomes
+      # the Integer, so equal scopes give equal keys whatever their key order
+      # or numeric spelling (`12` and `12.0` from a model's JSON). Other
+      # finite Floats keep their shortest exact text. NaN, Infinity and
+      # other objects are refused, because they have no stable identity; so
+      # are scopes past MAX_SCOPE_DEPTH levels or MAX_SCOPE_NODES values,
+      # which bounds the work at O(MAX_SCOPE_NODES).
+      def value(input, budget = [MAX_SCOPE_NODES], depth = 0)
+        charge!(budget, depth)
+        case input
+        when nil, true, false, Integer then input
+        when Float then float_value(input)
+        when String, Symbol then string(input.to_s)
+        when Array then input.map { |item| value(item, budget, depth + 1) }
+        when Hash then hash_entries(input, budget, depth)
+        else
+          raise ArgumentError,
+                "idempotency key scope must be built from Strings, Symbols, numbers, booleans, nil, Arrays " \
+                "and Hashes, got #{DiagnosticText.error_class_name(input)}"
+        end
+      end
+
+      def charge!(budget, depth)
+        raise ArgumentError, "idempotency key scope is nested deeper than #{MAX_SCOPE_DEPTH} levels" if too_deep?(depth)
+        return unless (budget[0] -= 1).negative?
+
+        raise ArgumentError, "idempotency key scope has more than #{MAX_SCOPE_NODES} values"
+      end
+
+      def too_deep?(depth) = depth > MAX_SCOPE_DEPTH
+
+      def float_value(value)
+        raise ArgumentError, "idempotency key scope numbers must be finite" unless value.finite?
+
+        value == value.truncate ? value.to_i : value
+      end
+
+      def hash_entries(hash, budget, depth)
+        entries = hash.map { |key, item| [hash_key(key), value(item, budget, depth + 1)] }
+        keys = entries.map(&:first)
+        raise ArgumentError, "idempotency key scope has two keys with the same name" unless keys.uniq.size == keys.size
+
+        entries.sort_by(&:first).to_h
+      end
+
+      def hash_key(key)
+        return string(key.to_s) if key.is_a?(String) || key.is_a?(Symbol)
+
+        raise ArgumentError, "idempotency key scope Hash keys must be Strings or Symbols"
+      end
+
+      def string(string)
+        utf8 = string.encoding == Encoding::UTF_8 ? string : string.encode(Encoding::UTF_8)
+        return utf8 if utf8.valid_encoding?
+
+        raise EncodingError
+      rescue EncodingError
+        raise ArgumentError, "idempotency key scope Strings must be valid UTF-8 or convert to it"
+      end
+    end
+    private_constant :Canonical
+  end
+end

data/lib/smith/idempotency_key.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+require_relative "idempotency_key/canonical"
+
+module Smith
+  # Keys for requests a step sends outside the system, so that a replay of
+  # the step (a retry, or a restore after a crash) repeats each request
+  # under the key it used before and the receiver can drop the duplicate.
+  #
+  # A key is the SHA-256 of the run's execution namespace (a UUID assigned
+  # when the workflow is built and persisted with it), the step's position
+  # (step number and transition, then any nested workflow step, parallel or
+  # fan-out branch, optimizer round and role, or orchestrator round and
+  # task inside it) and a caller-chosen scope. It is the same on every
+  # attempt of the step, so a retry after a timeout cannot repeat a request
+  # that took effect, and after a restore. An attempt of a step that fails
+  # in a way showing its own requests took no effect can ask for new keys
+  # on the attempts after it (`fail!` with `new_idempotency_key: true`, or
+  # `retry_on ... new_idempotency_key_on:`), for receivers that store a
+  # failed reply under its key. A replay keeps its keys only when the run
+  # was persisted before the step began, as `advance_persisted!` and
+  # `run_persisted!` do. A persisted payload is a run's identity: runs
+  # built with `new` never share keys, but runs restored from copies of one
+  # payload do.
+  #
+  # Keys exist only while a step does its own work (its body, agents,
+  # tools and guardrails); event handlers and `on_step` callbacks get none.
+  # The position is thread-local state Smith carries into its own branch
+  # threads and concurrent tool calls; code in a Fiber or Thread the host
+  # creates has none, while `step.idempotency_key` works anywhere.
+  #
+  #   transition :notify, from: :reviewed, to: :notified do
+  #     compute { |step| Mailer.deliver(review, idempotency_key: step.idempotency_key) }
+  #   end
+  module IdempotencyKey
+    VERSION = "smith.idempotency.v1"
+
+    # Where execution is: the run's namespace and the path of positions
+    # inside it, deeply frozen. Internal: hosts reach keys through
+    # `current`, `step.idempotency_key` and `Tool#idempotency_key`.
+    Scope = Data.define(:run, :path) do
+      def within(*segment)
+        self.class.new(run:, path: [*path, IdempotencyKey.__send__(:own_segment, segment)].freeze)
+      end
+
+      def key(scope = nil)
+        Digest::SHA256.hexdigest(JSON.generate([VERSION, run, path, Canonical.value(scope)]))
+      end
+    end
+    private_constant :Scope
+
+    class << self
+      # The key for `scope` at the current position. Raises WorkflowError
+      # outside a running workflow step.
+      def current(scope = nil)
+        current_scope!.key(scope)
+      end
+
+      private
+
+      def root_scope(run) = Scope.new(run: run.dup.freeze, path: [].freeze)
+
+      def current_scope
+        Tool.__send__(:current_idempotency_scope)
+      end
+
+      def current_scope!
+        current_scope || raise(WorkflowError, "an idempotency key is only available inside a running workflow step")
+      end
+
+      # Narrows the current position for the block, when there is one.
+      def within(*segment, &)
+        outer = current_scope
+        return yield unless outer
+
+        swap(outer.within(*segment), &)
+      end
+
+      # Runs the block with no position, so code that is not a step's own
+      # work (event handlers, callbacks) cannot take a step's key.
+      def without(&) = swap(nil, &)
+
+      # Interrupts are deferred while the position is installed and
+      # restored, as for every other per-step thread value.
+      def swap(scope, &block)
+        raise ArgumentError, "block required" unless block
+
+        outer = current_scope
+        Thread.handle_interrupt(Object => :never) do
+          install(scope)
+          begin
+            Thread.handle_interrupt(Object => :immediate, &block)
+          ensure
+            install(outer)
+          end
+        end
+      end
+
+      def install(scope)
+        raise ArgumentError, "an idempotency position must be a Scope or nil" unless scope.nil? || scope.is_a?(Scope)
+
+        Tool.__send__(:current_idempotency_scope=, scope)
+      end
+
+      # A namespace for a payload written before namespaces were assigned at
+      # construction: derived from the payload's own durable facts, so every
+      # restore of it gets the same one, and shaped as the version 4 UUID
+      # `new` assigns.
+      def legacy_namespace(*facts)
+        hex = Digest::SHA256.hexdigest(JSON.generate([VERSION, "namespace", *facts.map(&:to_s)]))
+        variant = ((hex[16].to_i(16) & 0x3) | 0x8).to_s(16)
+        "#{hex[0, 8]}-#{hex[8, 4]}-4#{hex[13, 3]}-#{variant}#{hex[17, 3]}-#{hex[20, 12]}"
+      end
+
+      # A position segment: a label and Strings, Symbols or Integers, held
+      # as frozen copies so a caller cannot change a key after the fact.
+      def own_segment(segment)
+        segment.map do |part|
+          case part
+          when Integer then part
+          when Symbol then part.to_s.freeze
+          when String then Canonical.string(part).dup.freeze
+          else raise ArgumentError, "an idempotency position segment must be Strings, Symbols or Integers"
+          end
+        end.freeze
+      end
+
+      # Narrows the position to the `count`th copy of `value` seen under
+      # `label`, named by its content: a list a model regenerates on replay
+      # keeps each item's key whatever its order.
+      def within_content(label, value, copies, &)
+        digest = content_digest(value)
+        copies[digest] += 1
+        within(label, digest, copies[digest], &)
+      end
+
+      # A digest of a value's canonical form, for a position named by its
+      # content (an orchestrator task) rather than by its place in a list.
+      def content_digest(value) = Digest::SHA256.hexdigest(JSON.generate(Canonical.value(value)))
+    end
+  end
+end