smith-agents 0.11.0 → 0.12.0

data/lib/smith/workflow/batch_holds.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    # A batch step's requests on a host's budget ledger (`budget_ledger`,
+    # Budget::HostLedger): each is held when captured, under its custom_id,
+    # and settled when its result comes (BatchWait).
+    module BatchHolds
+      private
+
+      # A host's budget ledger admits each request's hold (priced at the
+      # batch discount) under its custom_id, inside the attempt, so a durable
+      # `retry_on Smith::BudgetUnavailable` can wait for budget. A refusal,
+      # or the step ending before the requests are queued, releases the
+      # holds taken; queued, they are settled when the results come.
+      def hold_batch!(token, holds)
+        ledger = run_budget_ledger
+        return unless ledger
+
+        release_batch_holds
+        @batch_holds = []
+        seconds = BatchExecution::WAIT_SECONDS + Smith.config.budget_hold_ttl
+        holds.each do |branch_key, amount|
+          key = Batch.custom_id(token, branch_key)
+          Budget::HostLedger.admit!(ledger, amount, key, seconds:)
+          @batch_holds << key
+        end
+      rescue StandardError
+        release_batch_holds
+        raise
+      end
+
+      def release_batch_holds
+        keys = @batch_holds
+        @batch_holds = nil
+        ledger = settling_ledger if keys
+        keys&.each { Budget::HostLedger.settle(ledger, _1, nil) } if ledger
+      end
+
+      # Each result settles the hold its request took on a host's budget
+      # ledger (BatchExecution), taken by a call or not: a succeeded one
+      # reconciles what it cost, any other (or a wait that expired) releases.
+      def settle_batch_holds(transition, token, entries)
+        ledger = settling_ledger
+        return unless ledger
+
+        entries.each do |branch_key, entry|
+          spent = batch_spent(transition, branch_key, entry.result)
+          Budget::HostLedger.settle(ledger, Batch.custom_id(token, branch_key), spent)
+        end
+      end
+
+      # The ledger to settle holds on. One that cannot be built then is
+      # logged, as a settlement that fails is: the money is spent, and the
+      # holds expire.
+      def settling_ledger
+        run_budget_ledger
+      rescue BudgetLedgerError => e
+        Smith.config.logger&.error("Smith budget ledger settle error: #{e.message}")
+        nil
+      end
+
+      def batch_spent(transition, branch_key, result)
+        return unless result["type"] == "succeeded"
+
+        message = result.fetch("message")
+        usage = batch_reply_usage(message)
+        model = batch_model_id(batch_agent_class(transition, branch_key), message)
+        Budget::HostLedger.amount(usage, model:, provider: "anthropic", mode: :batch) if usage
+      end
+    end
+  end
+end

data/lib/smith/workflow/batch_wait.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Smith
+  class Workflow
+    # Completing a batch step's wait (BatchExecution). `resume!` with the
+    # results (`{custom_id => result}`, every request's), or `expire_wait!`
+    # past the deadline (every result then `missing`), runs the step again at
+    # its attempt: each call takes its result instead of going over the wire,
+    # parsed by RubyLLM's own provider parser, if the request it renders now
+    # is the one sent, and the step goes on as after a synchronous call
+    # (usage with `mode: :batch`, output checks, a follow-up call over the
+    # wire, guardrails, `output_to:`, retries). Results are taken only by the
+    # batch's own attempt; a succeeded one no call took (a branch cancelled
+    # by a sibling's failure) is charged all the same (BatchCharges).
+    module BatchWait
+      PENDING_BATCH_FIELDS = %w[attempt key_generation requests transition].freeze
+      DIGEST = /\A\h{64}\z/
+      private_constant :PENDING_BATCH_FIELDS, :DIGEST
+
+      private
+
+      # [attempts already made, key generation] where a delivered batch's
+      # step starts again, or nil. A delivery runs only the stored batch
+      # wait's step, whose pending batch restore guarantees.
+      def pending_batch_position
+        [@pending_batch["attempt"] - 1, @pending_batch["key_generation"]] if @batch_delivery
+      end
+
+      # The step's branches in the wait's order (nil for an agent step).
+      def batch_branches(transition) = transition.fanout? ? transition.fanout_config.fetch(:branches).keys : [nil]
+
+      def batch_ids(transition, token)
+        batch_branches(transition).to_h { |branch_key| [branch_key, Batch.custom_id(token, branch_key)] }
+      end
+
+      def batch_results!(transition, payload)
+        ids = batch_ids(transition, @awaiting.fetch("token"))
+        results = Batch.results!(payload, ids.values)
+        batch_entries(ids) { |id| results.fetch(id) }
+      rescue StandardError
+        @wait_claimed = false
+        raise
+      end
+
+      def missing_batch_results(transition)
+        batch_entries(batch_ids(transition, @awaiting.fetch("token"))) { { "type" => Batch::MISSING }.freeze }
+      end
+
+      def batch_entries(ids)
+        digests = @pending_batch.fetch("requests")
+        ids.to_h { |branch_key, id| [branch_key, Batch::Delivery::Entry.new(yield(id), digests.fetch(id))] }
+      end
+
+      # The step runs again at the batch's attempt, each call taking its
+      # result. It may enter another wait (a batch sent again, or a durable
+      # retry's backoff); otherwise it counts. A completion that raises
+      # leaves the run waiting.
+      def complete_batch_wait(transition, entries, done)
+        record = @awaiting
+        @awaiting = nil
+        @batch_delivery = Batch::Delivery.new(entries, on_change: transition.on_request_change || :keep)
+        step = with_step_context(transition) do
+          Execution.instance_method(:execute_step_body).bind_call(self, transition)
+        ensure
+          settle_batch_holds(transition, record.fetch("token"), entries)
+          charge_untaken_batch_results(transition)
+        end
+        settle_batch_wait(step)
+        return done if wait_pending?(step)
+
+        step.key?(:error) && done == :resumed ? :failed : done
+      rescue Exception # rubocop:disable Lint/RescueException -- the wait outlives a completion that did not happen
+        @awaiting ||= record
+        raise
+      ensure
+        @batch_delivery = nil
+        @wait_claimed = false
+      end
+
+      def settle_batch_wait(step)
+        @pending_batch = nil unless batch_waiting?
+        return if wait_pending?(step)
+
+        @step_count += 1
+        @updated_at = Time.now.utc.iso8601(6)
+        record_step_snapshot(step)
+      end
+
+      def batch_waiting? = @awaiting&.fetch("kind") == "batch"
+
+      # The result a call of the batch's attempt takes, once (a follow-up
+      # call, or a later attempt's, goes over the wire), for its branch.
+      def take_batch_result = (@batch_delivery.take(Attribution.current&.branch_key) if delivering_batch?)
+
+      def batch_result_due? = (delivering_batch? && @batch_delivery.for?(Attribution.current&.branch_key)) || false
+
+      # A persisted pending batch names the stored batch wait's transition
+      # (which WaitRecord checked is still a batch step), an attempt its
+      # retry policy allows, a key generation only a declared
+      # `new_idempotency_key_on` moves, and the digest of each request the
+      # step's branches send; a stored batch wait needs one. Anything else
+      # raises SerializationError.
+      def restore_pending_batch(value)
+        return if value.nil? && !batch_waiting?
+
+        record = value.is_a?(Hash) ? value.transform_keys(&:to_s) : {}
+        raise Smith::SerializationError, "persisted workflow pending_batch is invalid" unless
+          well_formed_pending_batch?(record)
+
+        record.transform_values(&:freeze).freeze
+      end
+
+      def well_formed_pending_batch?(record)
+        transition = self.class.transition_named(@awaiting["transition"]) if batch_waiting?
+        transition && record.keys.sort == PENDING_BATCH_FIELDS && record["transition"] == transition.name.to_s &&
+          allowed_batch_position?(transition, *record.values_at("attempt", "key_generation")) &&
+          batch_digests?(transition, record["requests"])
+      end
+
+      def allowed_batch_position?(transition, attempt, generation)
+        config = transition.retry_config
+        attempt.is_a?(Integer) && attempt.between?(1, config&.fetch(:attempts) || 1) && generation.is_a?(Integer) &&
+          generation.between?(0, config&.key?(:new_idempotency_key_on) ? attempt - 1 : 0)
+      end
+
+      def batch_digests?(transition, requests)
+        requests.is_a?(Hash) && requests.keys.sort == batch_ids(transition, @awaiting["token"]).values.sort &&
+          requests.values.all? { _1.is_a?(String) && DIGEST.match?(_1) }
+      end
+    end
+  end
+end

data/lib/smith/workflow/budget_integration.rb

@@ -31,6 +31,7 @@ module Smith
       def reconcile_branch_budget(ledger, reservation, agent_result: nil)
         return unless ledger && reservation
 
+        forget_call_reservation(reservation)
         actuals = extract_actuals(agent_results_for_settlement(agent_result))
         settlement = reservation.amounts.to_h do |dimension, _amount|
           [dimension, actual_for_dimension(dimension, actuals[:tokens], actuals[:cost])]
@@ -44,7 +45,7 @@ module Smith
         results = Array(agent_results).compact
 
         {
-          tokens: results.sum { |result| (result.input_tokens || 0) + (result.output_tokens || 0) },
+          tokens: results.sum(&:billable_tokens),
           cost: results.sum { |result| result.cost || 0 }
         }
       end
@@ -71,11 +72,16 @@ module Smith
       def release_branch_budget(ledger, reservation)
         return unless ledger && reservation
 
+        forget_call_reservation(reservation)
         return ledger.release_many!(reservation) if reservation.amounts.length > 1
 
         ledger.release!(reservation)
       end
 
+      def forget_call_reservation(reservation)
+        Thread.current[:smith_call_reservation] = nil if Thread.current[:smith_call_reservation].equal?(reservation)
+      end
+
       def settle_budget_on_failure(ledger, estimates, agent_result)
         return unless ledger && estimates
 
@@ -98,11 +104,11 @@ module Smith
         reserve_estimates!(ledger, estimates)
       end
 
+      # The reservation is also the current call's, for OutputIntegrity to
+      # stop making follow-up calls once it is spent.
       def reserve_estimates!(ledger, estimates)
-        return ledger.reserve_many!(estimates) if estimates.length > 1
-
-        dimension, amount = estimates.first
-        ledger.reserve!(dimension, amount)
+        reservation = estimates.length > 1 ? ledger.reserve_many!(estimates) : ledger.reserve!(*estimates.first)
+        Thread.current[:smith_call_reservation] = reservation
       end
 
       def finalize_branch(transition, index, result, ledger, reserved)

data/lib/smith/workflow/budget_pause.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    # A tool loop that pauses for budget. A step whose `retry_on` names
+    # BudgetUnavailable (or an ancestor), on an attempt it may retry, holds
+    # every round of its call's tool loop on the host's budget ledger, not
+    # only the first. When the ledger refuses a later round, the step's
+    # tools have run: the refusal carries the messages the call added (its
+    # tool calls and their results, Budget::Continuation), the step's tool
+    # guard lets it through, and the retry (durable: a wait the host ends
+    # once there is budget, its continuation kept with the pending retry)
+    # continues the loop from them, running none of its tools again. A step
+    # that cannot retry for budget lets a later round go on, unheld, and
+    # reconciles what it spent. Only a serial agent step pauses so.
+    module BudgetPause
+      private
+
+      def start_budget_pause(transition)
+        @budget_pause_attempts = budget_pause_attempts(transition)
+        pending = @pending_retry
+        @budget_continuation = (pending["continuation"] if pending && pending["transition"] == transition.name.to_s)
+      end
+
+      def budget_pause_attempts(transition)
+        config = transition.retry_config
+        return unless config && serial_agent_step?(transition)
+
+        config.fetch(:attempts) if config.fetch(:error_classes).any? { _1 >= BudgetUnavailable }
+      end
+
+      def serial_agent_step?(transition)
+        !transition.agent_name.nil? && !transition.parallel? && !transition.fanout? && !transition.optimized? &&
+          !transition.orchestrated?
+      end
+
+      def budget_pausable? = !@budget_pause_attempts.nil? && @step_attempt.to_i < @budget_pause_attempts
+
+      def keep_budget_continuation(error)
+        @budget_continuation = error.continuation if error.is_a?(BudgetUnavailable) && error.continuation
+      end
+
+      # The paused loop's messages, after the attempt's prepared input.
+      def continue_paused_loop(chat)
+        return unless @budget_continuation
+
+        Budget::Continuation.load(@budget_continuation).each { chat.add_message(_1) }
+      end
+    end
+  end
+end

data/lib/smith/workflow/child_run_declarations.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Transition
+      # Steps that start other workflows as runs of their own, through the
+      # host's run launcher (`Smith.config.run_launcher`):
+      #
+      #   map :section_ids, workflow: Sections::Review, max_items: 500, timeout: 6 * 3600,
+      #       input: ->(section_id, ctx) { { document_id: ctx[:document_id], section_id: } },
+      #       into: :section_reviews, collect: :outputs, on_item_failure: :collect
+      #   call Documents::Summarize, input: ->(ctx) { { document_id: ctx[:document_id] } },
+      #        timeout: 3600, into: :summary
+      #   spawn :watcher_ids, workflow: Watchers::Notify, max_items: 1_000,
+      #         input: ->(watcher_id, ctx) { { watcher_id: } }
+      #
+      # `map` launches a run per item and waits, bounded by `timeout:`, for
+      # the host to resume the parent with every child's result; `call` is a
+      # map of one whose `into:` gets the child's output itself; `spawn`
+      # launches and continues. `items` is a context key holding an Array or
+      # a callable of the context, and more than `max_items` fails the step
+      # before anything launches. `input:` returns each child's whole
+      # context.
+      module ChildRunDeclarations
+        MAX_ITEMS = 10_000
+        COLLECT_MODES = %i[outputs states none].freeze
+        FAILURE_MODES = %i[fail collect].freeze
+        # Each kind's required options, optional ones with their defaults,
+        # and the settings it fixes.
+        OPTIONS = {
+          map: { required: %i[workflow max_items input timeout into],
+                 optional: { collect: :outputs, on_item_failure: :fail }, fixed: {} },
+          call: { required: %i[input timeout into], optional: {},
+                  fixed: { max_items: 1, collect: :outputs, on_item_failure: :fail } },
+          spawn: { required: %i[workflow max_items input], optional: {},
+                   fixed: { collect: :none, on_item_failure: :collect } }
+        }.freeze
+        private_constant :OPTIONS
+
+        attr_reader :children_config
+
+        def map(items, **options) = declare_child_runs!(:map, items, options)
+
+        def call(workflow, **options) = declare_child_runs!(:call, nil, options, workflow:)
+
+        def spawn(items, **options) = declare_child_runs!(:spawn, items, options)
+
+        def child_runs? = !@children_config.nil?
+
+        def spawns? = @children_config&.fetch(:kind) == :spawn
+
+        private
+
+        # A map or call that fails when a child fails needs on_failure. No
+        # map, call or spawn retries: its launcher retries launching, and a
+        # map's results arrive with the host's resume, outside any attempt.
+        def validate_child_run_controls!
+          return unless child_runs?
+          raise WorkflowError, "a map, call or spawn does not take retry_on" if @retry_config
+          return unless @children_config.fetch(:on_item_failure) == :fail && @failure_transition.nil?
+
+          raise WorkflowError, "a map or call that fails when a child fails must declare on_failure"
+        end
+
+        def declare_child_runs!(kind, items, options, given = {})
+          validate_execution_primitive_conflict!(kind.to_s)
+          settings = child_run_options!(kind, options).merge(given)
+          validate_child_runs!(kind, items, settings)
+          @children_config = settings.slice(:workflow, :max_items, :input, :collect, :on_item_failure)
+                                     .merge(kind:, items:).freeze
+          wait_for_children!(settings[:into], settings[:timeout], kind) unless kind == :spawn
+          commit_execution_primitive!(kind.to_s)
+        end
+
+        def child_run_options!(kind, options)
+          spec = OPTIONS.fetch(kind)
+          refuse_options!(kind, "does not take", options.keys - spec[:required] - spec[:optional].keys)
+          refuse_options!(kind, "needs", spec[:required] - options.keys)
+          spec[:optional].merge(options).merge(spec[:fixed])
+        end
+
+        def refuse_options!(kind, problem, names)
+          raise WorkflowError, "#{kind} #{problem} #{names.map(&:inspect).join(", ")}" if names.any?
+        end
+
+        def validate_child_runs!(kind, items, settings)
+          workflow = settings[:workflow]
+          unless workflow.is_a?(Class) && workflow < Workflow
+            raise WorkflowError, "#{kind} workflow must be a Smith::Workflow subclass"
+          end
+          raise WorkflowError, "#{kind} input: must be a callable" unless settings[:input].respond_to?(:call)
+
+          validate_child_items!(kind, items, settings[:max_items])
+          validate_child_modes!(kind, settings[:collect], settings[:on_item_failure])
+        end
+
+        def validate_child_items!(kind, items, max_items)
+          unless kind == :call || items.is_a?(Symbol) || items.respond_to?(:call)
+            raise WorkflowError, "#{kind} items must be a Symbol context key or a callable of the context"
+          end
+          return if max_items.is_a?(Integer) && max_items.between?(1, MAX_ITEMS)
+
+          raise WorkflowError, "#{kind} max_items: must be an Integer from 1 to #{MAX_ITEMS}"
+        end
+
+        def validate_child_modes!(kind, collect, on_item_failure)
+          unless COLLECT_MODES.include?(collect)
+            raise WorkflowError, "#{kind} collect: must be one of #{COLLECT_MODES.inspect}"
+          end
+          return if FAILURE_MODES.include?(on_item_failure)
+
+          raise WorkflowError, "#{kind} on_item_failure: must be one of #{FAILURE_MODES.inspect}"
+        end
+
+        # A map or call waits like an await, for the event `children`.
+        def wait_for_children!(into, timeout, kind)
+          raise WorkflowError, "#{kind} into: must be a Symbol context key" unless into.is_a?(Symbol)
+
+          @await_config = { kind: :children, event: :children, into:,
+                            timeout: wait_seconds!(timeout, "#{kind} timeout:"), block: nil }.freeze
+        end
+      end
+
+      include ChildRunDeclarations
+    end
+  end
+end

data/lib/smith/workflow/child_run_execution.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require_relative "execution_result_snapshot"
+require_relative "message_value_normalizer"
+
+module Smith
+  class Workflow
+    # Launching the runs of `map`, `call` and `spawn` steps through the
+    # host's run launcher, and taking their results when the host resumes
+    # the parent. A child's ref is the index of its item; items come from
+    # the context (or a callable of it), so a replayed step launches the
+    # same children under the same keys, and the launcher must be
+    # idempotent on each child's `key`.
+    module ChildRunExecution
+      MAX_LAUNCH_BYTES = 4 * ExecutionResultSnapshot::MAX_BYTES
+      private_constant :MAX_LAUNCH_BYTES
+
+      private
+
+      # Launches the children; returns their results when the launcher runs
+      # them itself (`inline?`), else nil (the host resumes the parent
+      # later), whatever the launcher returned.
+      def launch_child_runs(transition, token)
+        launcher = Smith.config.run_launcher
+        kind = transition.children_config.fetch(:kind)
+        raise WorkflowError, "#{kind} needs Smith.config.run_launcher" unless launcher
+
+        children = child_runs(transition, token).freeze
+        unless @persistence_key || inline_launcher?(launcher)
+          raise WorkflowError, "#{kind} starts runs of their own, so it needs a persisted run " \
+                               "(run_persisted! or advance_persisted!)"
+        end
+
+        @launched_children = children.length
+        return [] if children.empty?
+
+        results = launcher.launch(children:, parent_key: @persistence_key, await_token: token)
+        return unless inline_launcher?(launcher)
+        return results if results.is_a?(Array)
+
+        raise WorkflowError, "a run launcher whose inline? is true must return the children's results"
+      end
+
+      def inline_launcher?(launcher) = launcher.respond_to?(:inline?) && launcher.inline? == true
+
+      def child_runs(transition, token)
+        config = transition.children_config
+        context = snapshot_value(@context)
+        bytes = 0
+        child_items(transition).each_with_index.map do |item, index|
+          input = child_input(config, item, context)
+          bytes = check_launch_size!(bytes + JSON.generate(input).bytesize, config[:kind])
+          child_run(config, token, index, input)
+        end
+      end
+
+      def child_run(config, token, ref, input)
+        ChildRun.new(ref:, key: ChildRun.key_for(token, ref), workflow: config.fetch(:workflow), input:,
+                     untrusted_keys: (untrusted_context_keys & input.keys).freeze,
+                     artifact_namespaces: child_artifact_namespaces)
+      end
+
+      # The inputs of one step's children together are bounded, as one
+      # step's result is, four times over; checked as each is built.
+      def check_launch_size!(bytes, kind)
+        return bytes if bytes <= MAX_LAUNCH_BYTES
+
+        raise WorkflowError, "#{kind} inputs come to more than #{MAX_LAUNCH_BYTES} bytes"
+      end
+
+      def child_items(transition)
+        config = transition.children_config
+        return [nil] if config.fetch(:kind) == :call
+
+        source = config.fetch(:items)
+        check_items_persisted!(source, config[:kind])
+        items = item_source(source)
+        raise WorkflowError, "#{config[:kind]} items must be an Array" unless items.is_a?(Array)
+        return items if items.length <= config.fetch(:max_items)
+
+        raise WorkflowError, "#{config[:kind]} has #{items.length} items, more than its max_items of " \
+                             "#{config[:max_items]}"
+      end
+
+      # A persisted run takes its children's results after a restore, which
+      # needs the items key the step launched from.
+      def check_items_persisted!(source, kind)
+        return unless @persistence_key && source.is_a?(Symbol)
+
+        keys = resolve_persist_keys
+        persisted = keys.nil? || (keys == :auto ? @persisted_keys.include?(source) : keys.include?(source))
+        raise WorkflowError, "#{kind} items key #{source.inspect} must be persisted" unless persisted
+      end
+
+      def item_source(source) = source.respond_to?(:call) ? source.call(snapshot_value(@context)) : @context[source]
+
+      # The child's whole context: a Hash, JSON-shaped and bounded, in the
+      # context's key shape.
+      def child_input(config, item, context)
+        input = config.fetch(:input)
+        raw = config.fetch(:kind) == :call ? input.call(context) : input.call(item, context)
+        raise WorkflowError, "#{config[:kind]} input: must return a Hash" unless raw.is_a?(Hash)
+
+        ContextKeys.normalize(MessageValueNormalizer.new(raw, label: "child run input").call).freeze
+      end
+
+      # Checks the results against the children the step launched (one per
+      # ref, each succeeded or failed), then, unless a failed child fails
+      # the step, writes them to `into:` as the step collects them.
+      def deliver_child_results(transition, results, expected = expected_children(transition))
+        config = transition.children_config
+        entries = checked_child_results(results, expected, config[:kind])
+        fail_on_failed_children!(transition, entries) if config[:on_item_failure] == :fail
+        write_wait_payload(transition, collected_child_results(config, entries))
+      end
+
+      def fail_on_failed_children!(transition, entries)
+        failed = entries.select { _1[:status] == "failed" }
+        return if failed.empty?
+
+        raise ChildRunsFailed.new(transition: transition.name, failed_refs: failed.map { _1[:ref] },
+                                  total: entries.length)
+      end
+
+      # How many children the step launched: as the stored wait records it,
+      # or, for a delivery that comes before the wait is stored, its items.
+      def expected_children(transition)
+        stored = @awaiting && @awaiting["children"]
+        stored.is_a?(Integer) ? stored : child_items(transition).length
+      end
+
+      # Child results are larger than a session message: a map's outputs
+      # together are bounded like a step's result.
+      def child_results_payload(payload)
+        bound = ExecutionResultSnapshot::MAX_BYTES
+        ContextKeys.normalize(MessageValueNormalizer.new(payload, label: "child run results", max_bytes: bound).call)
+      end
+
+      # A spawn launches and the step completes.
+      def execute_spawn_step(transition)
+        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
+        launch_child_runs(transition, token)
+        nil
+      end
+    end
+  end
+end

data/lib/smith/workflow/child_run_results.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    # Checking the results a host reports for a step's child runs, and
+    # shaping them as the step collects them.
+    module ChildRunResults
+      STATUSES = %w[succeeded failed].freeze
+      RESULT_KEYS = %i[ref status state output error].freeze
+      private_constant :STATUSES, :RESULT_KEYS
+
+      private
+
+      # Outputs a map does not collect are dropped before the results are
+      # bounded, so a large map can report states or counts.
+      def collectable_results(config, payload)
+        return payload if config[:kind] == :call || config[:collect] == :outputs || !payload.is_a?(Array)
+
+        payload.map { |entry| entry.is_a?(Hash) ? entry.reject { |key, _value| key.to_s == "output" } : entry }
+      end
+
+      def checked_child_results(results, expected, kind)
+        entries = results.is_a?(Array) ? results.map { child_result(_1, kind) } : nil
+        unless entries && entries.map { _1[:ref] }.sort == (0...expected).to_a
+          raise WorkflowError, "#{kind} results must hold one entry for each of its #{expected} children, by ref"
+        end
+
+        entries.sort_by { _1[:ref] }
+      end
+
+      def child_result(entry, kind)
+        valid = entry.is_a?(Hash) && (entry.keys - RESULT_KEYS).empty? && entry[:ref].is_a?(Integer) &&
+                STATUSES.include?(entry[:status]) && [entry[:state], entry[:error]].all? { short_text?(_1) }
+        return entry if valid
+
+        raise WorkflowError, "#{kind} results are { ref:, status: \"succeeded\" | \"failed\", state:, output:, " \
+                             "error: }, with state and error short text"
+      end
+
+      def short_text?(value) = value.nil? || (value.is_a?(String) && value.bytesize <= 256)
+
+      def collected_child_results(config, entries)
+        return entries.first[:output] if config[:kind] == :call
+
+        case config[:collect]
+        when :outputs then entries.map { _1.slice(*RESULT_KEYS) }
+        when :states then entries.map { _1.slice(:ref, :status, :state, :error) }
+        else
+          failed = entries.count { _1[:status] == "failed" }
+          { succeeded: entries.length - failed, failed: }
+        end
+      end
+    end
+  end
+end