smith-agents 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f0194d534f9aa31c42dc14a0bd92a092f0088b3ac138ffe65060b00c6c564a0
-  data.tar.gz: 314f07b2e7c51f2372fec28cf7d495672ce38f4ba1f09a9af4cccba6f9cefd17
+  metadata.gz: 986d706ecdf0a51035e20dde373106a6c6df18bc2150cae87e117993bd3fcd1e
+  data.tar.gz: e67ca0f8e6b4d6d35c5e1683876a9e191d0da92e29bee4c4379ca8b60b77c50e
 SHA512:
-  metadata.gz: f75713ef01aa104f3add7f6804dc8f77061ad12ea787598a16dce09bb0b08c23e256f35b346d4f3e53c99b86a0bdb5603ca6f7236dc66a1c60130a16ab9180a5
-  data.tar.gz: 28953ec750b620efff05055af313031eb24e97f6591dea4ea04b029d8c71d0a72de37d2aecb6ec78c532f73d3301d854b6f853bd26515abd98f93a5fe4668edb
+  metadata.gz: fa10aed2a7fc3874e8629af28beb07c230d5632b5a653630e70374931c8067775b8f17bee8c70a5c7e96c723e70dbad10c693491c37f8f4bb4a3c7f29b5aed1e
+  data.tar.gz: 13560c156073e79e1950d46e460a7f8a1a964a3af6d9b63b68394a0835b6b117f1fb60636c8cecb62d4fb6380e9064a535607cd2e57155e92f64915d2ab76228

data/CHANGELOG.md

@@ -6,6 +6,69 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Version
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-07-20
+
+### Added
+
+- Add a host-neutral durable composite lifecycle for same-agent parallel and
+  heterogeneous fan-out transitions. Smith emits immutable bounded plans and
+  inputs, executes one authorized branch through captured agent bindings, and
+  deterministically reduces a complete ordered outcome set through the normal
+  transition completion and failure paths.
+- Add exact transport contracts for ordered branch descriptors, redacted branch
+  failures, usage/tool/budget effects, and host-committed primary failure
+  selection. Composite branch retries remain explicitly unsupported; hosts own
+  scheduling, persistence, claims, fences, and incomplete-branch resumption.
+- Add compact selected-branch execution envelopes and stable host-declared agent
+  execution identities so workers do not receive the full plan and registry
+  replacement after planning fails closed.
+- Add scoped prepare, selected-branch execution, and reduction entry points so
+  process-local authority never crosses the supported public composite API.
+
+### Changed
+
+- Bump `Smith::EXECUTION_SEMANTICS_VERSION` to `2` so hosts invalidate generated
+  executable definitions when adopting the composite lifecycle.
+- Canonicalize aggregate branch output to the same JSON-compatible shape before
+  and after persistence.
+
+### Fixed
+
+- Preserve complete workflow, agent, and branch execution context across
+  nested parallel and heterogeneous fan-out work without leaking thread- or
+  Fiber-local Smith state.
+- Keep ordinary subclass setup and teardown extension points intact while
+  prepared execution seals framework-owned branch dispatch against subclass
+  replacement.
+- Restrict prepared execution authority to the exact coordinator or registered
+  branch Fiber, reject copied or serialized process-local authority, and make
+  activation, cleanup, and context restoration safe against asynchronous Ruby
+  thread interruption.
+- Keep composite planning and full-run validation linear in branch count, make
+  individual branch binding capture and validation constant-time in branch
+  count, reject the hard transport ceiling before descriptor allocation, and
+  incrementally enforce cumulative effect/output envelopes before consuming
+  execution authority.
+- Isolate decimal aggregation from host `BigDecimal` precision, reject aggregate
+  usage overflow, and preserve composite branch identity and retry
+  classification across persistence.
+- Bind one artifact execution namespace into every branch and the reducer,
+  reject aggregate budget overrun and known usage replay before consuming
+  authority, and validate cumulative persisted token/cost accounting.
+- Enforce complete canonical payload fields and encoded JSON byte limits before
+  returning transport values.
+- Allocate disjoint branch budget envelopes without exceeding the parent,
+  reconcile usage against branch-local token/cost consumption, bind branch
+  authority to one exact execution envelope, and prevent subclass collisions
+  from bypassing durable dispatch verification.
+- Reject forged retryability, untrusted error metadata, and unknown transport
+  keys without symbol interning; validate scalar and replay failures before
+  snapshotting tool effects.
+- Reject unknown transport enum values without symbol interning, reject corrupt
+  persisted branch-failure evidence instead of inventing defaults, enforce
+  cumulative encoded-effect bounds while streaming outcomes, and close active
+  branch authority before asynchronous interruption can escape a scoped call.
+
 ## [0.5.0] - 2026-07-19
 
 This release contains intentional pre-1.0 public contract tightening and is a

data/README.md

@@ -260,6 +260,89 @@ During authorized execution, Smith also seals its private execution path against
 workflow subclass method-name collisions, including nested child workflows.
 Ordinary non-authorized runs retain normal Ruby override behavior.
 
+For `parallel: true` and `fan_out` transitions, a host can split one confirmed
+dispatch into independently scheduled branch operations without invoking agent
+classes outside Smith:
+
+```ruby
+preparation = workflow.prepare_composite_step!
+
+# Persist preparation.plan and preparation.input in host-owned records.
+# Each worker recovers the same confirmed dispatch and receives one descriptor.
+branch = preparation.plan.branches.fetch(0)
+execution = preparation.plan.execution_for(branch)
+outcome = branch_workflow.execute_prepared_composite_branch!(
+  execution:,
+  input: preparation.input
+)
+
+# After every branch has a terminal outcome, use another fresh recovery to
+# complete the Smith transition exactly once.
+result = reducer_workflow.reduce_prepared_composite_step!(
+  plan: preparation.plan,
+  input: preparation.input,
+  outcomes: ordered_or_unordered_complete_outcome_set,
+  primary_failure: host_committed_failed_branch_key
+)
+```
+
+Plans bind the exact prepared dispatch, host-supplied complete workflow
+`definition_digest`, execution-semantics version, prepared input digest, budget
+baseline, one shared artifact execution namespace, ordered branch identities,
+and explicit policies. Each plan, input, outcome, or effect payload is
+canonical, immutable, bounded to 1 MiB after JSON encoding, rejects missing or
+unknown fields, and redacts exception messages and backtraces.
+Reduction additionally bounds cumulative effects to 1 MiB and final aggregate
+output to 4 MiB before consuming execution authority. Reduction accepts either
+an `Array` or an `Enumerator`, validates each outcome incrementally, and stops
+as soon as a cumulative bound is crossed. The transport hard limit is 10,000
+branches; every recovered worker also enforces the current
+`Smith.config.parallel_branch_limit` before work.
+
+Planning is `O(B * D)`, where `D` is the bounded number of budget dimensions.
+The coordinator derives a compact selected-branch execution envelope in
+`O(D)` without copying the full branch collection. The scoped branch execution
+entry point captures and validates one selected binding in `O(D)` and constant
+time with respect to total branch count; the reducer validates the complete plan
+once. Reduction is `O(B + P log P)` in
+the worst case because canonical nested Hash ownership sorts keys, and uses
+`O(B + P)` bounded space.
+Smith does not persist plans or outcomes, select scheduling slots, claim work,
+choose an uncertain-outcome policy, or infer the primary failure. The host
+durably owns those decisions, gives each branch and reduction a separately
+recovered workflow instance, and must pass a complete outcome set. Transport or
+encoding faults become typed branch failures when Smith can preserve accounting
+evidence; otherwise the host must treat the worker result as uncertain and must
+not infer safe retry. Resume policy is incomplete branches only; per-branch
+retry is intentionally unsupported in this contract version.
+Composite payload digests prove canonical content integrity, not worker
+authenticity. Before reduction, the host must authenticate every outcome against
+its own claimed operation identity and current fencing token; those durable
+receipts remain outside Smith.
+
+The supported composite API is the three scoped workflow methods above plus the
+immutable transport values they return or accept: `Preparation`, `Plan`,
+`Input`, `Branch`, `BranchExecution`, `BranchOutcome`, `BranchFailure`, `Error`,
+`Effects`, and `Reduction`. Other constants under `Workflow::Composite` are
+implementation collaborators, not extension points or compatibility promises.
+
+Every agent used by this durable composite boundary must declare a stable
+host-computed SHA-256 execution identity. The identity represents the exact
+sealed executable asset the host intends to dispatch; Smith records it in the
+branch descriptor and rejects registry replacement after planning. Identities
+are deliberately not inherited because a subclass is a distinct executable
+implementation.
+
+```ruby
+class Researcher < Smith::Agent
+  execution_identity Digest::SHA256.hexdigest(generated_asset_manifest)
+  register_as :researcher, publish: false
+end
+
+Researcher.freeze
+Researcher.publish_registration!
+```
+
 Hosts that generate agent classes dynamically may call
 `register_as :name, publish: false` while constructing the class. This records
 the class identity without exposing it through `Smith::Agent::Registry`. After

data/lib/smith/agent.rb

@@ -4,6 +4,9 @@ require "ruby_llm"
 
 module Smith
   class Agent < RubyLLM::Agent
+    EXECUTION_IDENTITY_UNSET = Object.new.freeze
+    private_constant :EXECUTION_IDENTITY_UNSET
+
     # Reserved input names auto-injected by the normalizer into
     # runtime_context. User-side `inputs :name` calls cannot redeclare
     # these names; the override raises Smith::AgentError if they try.
@@ -20,9 +23,19 @@ module Smith
         subclass.instance_variable_set(:@data_volume, @data_volume)
         subclass.instance_variable_set(:@fallback_models_list, @fallback_models_list&.dup)
         subclass.instance_variable_set(:@model_block, @model_block)
+        subclass.instance_variable_set(:@execution_identity, nil)
         subclass.instance_variable_set(:@registered_name, nil)
       end
 
+      def execution_identity(value = EXECUTION_IDENTITY_UNSET)
+        return @execution_identity if value.equal?(EXECUTION_IDENTITY_UNSET)
+        unless value.is_a?(String) && /\A[0-9a-f]{64}\z/.match?(value)
+          raise ArgumentError, "execution_identity must be a lowercase SHA-256 hex digest"
+        end
+
+        @execution_identity = value.dup.freeze
+      end
+
       def budget(**opts)
         return @budget_config if opts.empty?
 

data/lib/smith/errors.rb

@@ -15,6 +15,10 @@ module Smith
     def self.retryable?(error)
       return false if error.nil?
 
+      composite_failure = defined?(Smith::Workflow::Composite::BranchFailure) &&
+                          error.is_a?(Smith::Workflow::Composite::BranchFailure)
+      return false if composite_failure
+
       case error
       when Smith::DeterministicStepFailure, Smith::ToolGuardrailFailed
         error.retryable == true

data/lib/smith/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Smith
-  VERSION = "0.5.0"
-  EXECUTION_SEMANTICS_VERSION = "1"
+  VERSION = "0.6.0"
+  EXECUTION_SEMANTICS_VERSION = "2"
 end

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

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative "../../types"
+require_relative "../message_value_normalizer"
+require_relative "../prepared_step"
+require_relative "payload"
+require_relative "payload_digest"
+
+module Smith
+  class Workflow
+    module Composite
+      class Branch < Payload
+        MAX_BUDGET_DIMENSIONS = 128
+        HASH_LENGTH = Hash.instance_method(:length)
+        HASH_EACH_PAIR = Hash.instance_method(:each_pair)
+        private_constant :HASH_LENGTH, :HASH_EACH_PAIR
+        OwnedString = Types::String.constructor { |value| value.is_a?(String) ? value.dup.freeze : value }
+        private_constant :OwnedString
+
+        attribute :ordinal, Types::Integer.constrained(gteq: 0, lteq: PreparedStep::MAX_COUNTER_VALUE)
+        attribute :key, OwnedString.constrained(min_size: 1, max_size: 256)
+        attribute :agent, OwnedString.constrained(min_size: 1, max_size: 256)
+        attribute :binding_identity, OwnedString.constrained(format: PreparedStep::DIGEST_PATTERN)
+        attribute :budget, Types::Hash
+        attribute :digest, OwnedString.constrained(format: PreparedStep::DIGEST_PATTERN)
+
+        def self.build(ordinal:, key:, agent:, binding_identity:, budget:)
+          attributes = {
+            ordinal:,
+            key: key.to_s,
+            agent: agent.to_s,
+            binding_identity:,
+            budget: normalize_budget(budget)
+          }
+          new(attributes.merge(digest: PayloadDigest.call(attributes)))
+        end
+
+        def initialize(attributes)
+          owned = self.class.normalize_attributes(attributes)
+          owned[:budget] = self.class.send(:normalize_budget, owned[:budget])
+          super(owned)
+          expected = PayloadDigest.call(to_h.except(:digest))
+          raise ArgumentError, "composite branch digest does not match" unless digest == expected
+        end
+
+        class << self
+          private
+
+          def normalize_budget(value)
+            normalized = normalized_budget(value)
+            validate_budget_dimensions!(normalized)
+            copy_budget(normalized)
+          end
+
+          def normalized_budget(value)
+            normalized = MessageValueNormalizer.new(value, label: "composite branch budget").call
+            raise ArgumentError, "composite branch budget must be a Hash" unless normalized.is_a?(Hash)
+
+            normalized
+          end
+
+          def validate_budget_dimensions!(budget)
+            return if HASH_LENGTH.bind_call(budget) <= MAX_BUDGET_DIMENSIONS
+
+            raise ArgumentError, "composite branch budget contains too many dimensions"
+          end
+
+          def copy_budget(normalized)
+            budget = {}
+            HASH_EACH_PAIR.bind_call(normalized) do |name, amount|
+              validate_budget_dimension!(name)
+              validate_budget_amount!(amount)
+              budget[name.freeze] = amount
+            end
+            budget.freeze
+          end
+
+          def validate_budget_dimension!(name)
+            return if name.length.between?(1, 256)
+
+            raise ArgumentError, "composite branch budget dimensions must be bounded non-empty strings"
+          end
+
+          def validate_budget_amount!(amount)
+            return if amount.is_a?(Numeric) && amount.finite? && amount >= 0
+
+            raise ArgumentError, "composite branch budget values must be finite non-negative numbers"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "budget_allocator"
+require_relative "plan"
+
+module Smith
+  class Workflow
+    module Composite
+      module BranchBudgetContract
+        private
+
+        def validate_composite_branch_count!(count)
+          Plan.validate_branch_count!(count)
+        end
+
+        def composite_budget_allocator(branch_count)
+          return unless @ledger
+
+          BudgetAllocator.new(ledger: @ledger, branch_count:)
+        end
+
+        def composite_branch_budget(allocator, ordinal, agent_budget)
+          return {} unless allocator
+
+          caps = @ledger.limits.each_key.with_object({}) do |dimension, result|
+            cap = agent_cap_for_dimension(dimension, agent_budget)
+            result[dimension] = cap unless cap.nil?
+          end
+          allocator.call(ordinal:, caps:)
+        end
+
+        def composite_binding_identity!(agent_class, agent)
+          identity = agent_class&.execution_identity
+          return identity if identity
+
+          raise WorkflowError, "durable composite agent :#{agent} requires an execution_identity"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative "../parallel"
+require_relative "branch"
+require_relative "branch_budget_contract"
+require_relative "fanout_branch_contract"
+
+module Smith
+  class Workflow
+    module Composite
+      module BranchContract
+        include BranchBudgetContract
+        include FanoutBranchContract
+
+        private
+
+        def composite_branch_specs(authorization, transition, branch_count: nil)
+          return parallel_branch_specs(authorization, transition, branch_count:) if transition.parallel?
+
+          fanout_branch_specs(authorization, transition)
+        end
+
+        def parallel_branch_specs(authorization, transition, branch_count: nil)
+          validate_planned_parallel_count!(transition, branch_count) if branch_count
+          count = branch_count || Parallel.resolve_branch_count(transition, @context)
+          validate_composite_branch_count!(count)
+          agent = transition.agent_name
+          agent_class = captured_agent(authorization, transition, agent, :agent)
+          allocator = composite_budget_allocator(count)
+          Array.new(count) do |ordinal|
+            parallel_branch_spec(agent, agent_class, allocator, ordinal).merge(key: ordinal.to_s)
+          end.freeze
+        end
+
+        def parallel_branch_spec(agent, agent_class, allocator, ordinal)
+          {
+            agent: agent.to_s,
+            binding_identity: composite_binding_identity!(agent_class, agent),
+            budget: composite_branch_budget(allocator, ordinal, agent_class&.budget)
+          }.freeze
+        end
+
+        def validate_planned_parallel_count!(transition, branch_count)
+          Parallel.validate_branch_count!(branch_count)
+          configured = transition.agent_opts[:count]
+          return if configured.respond_to?(:call)
+          return if branch_count == (configured || 1)
+
+          raise WorkflowError, "composite plan branch count does not match the prepared transition"
+        end
+
+        def captured_agent(authorization, transition, agent, role)
+          authorization.fetch_agent!(
+            agent,
+            workflow_class: self.class,
+            transition_name: transition.name,
+            role:
+          )
+        end
+
+        def validate_composite_branches!(authorization, plan, transition)
+          specs = composite_branch_specs(authorization, transition, branch_count: plan.branches.length)
+          specs.each_with_index do |spec, ordinal|
+            expected = comparable_branch(Branch.build(ordinal:, **spec))
+            actual = comparable_branch(plan.branches.fetch(ordinal))
+            next if actual == expected
+
+            raise WorkflowError, "composite plan branches do not match the prepared transition"
+          end
+        end
+
+        def validate_composite_selected_branch!(authorization, execution, transition)
+          branch = execution.branch
+          spec = selected_branch_spec(authorization, execution, transition)
+          candidate = Branch.build(ordinal: branch.ordinal, **spec)
+          raise WorkflowError, "composite branch does not match the prepared transition" unless
+            comparable_branch(candidate) == comparable_branch(branch)
+        end
+
+        def selected_branch_spec(authorization, execution, transition)
+          return selected_parallel_branch_spec(authorization, execution, transition) if transition.parallel?
+
+          selected_fanout_branch_spec(authorization, execution, transition)
+        end
+
+        def selected_parallel_branch_spec(authorization, execution, transition)
+          branch = execution.branch
+          count = execution.branch_count
+          validate_planned_parallel_count!(transition, count)
+          agent = transition.agent_name
+          agent_class = captured_agent(authorization, transition, agent, :agent)
+          allocator = composite_budget_allocator(count)
+          parallel_branch_spec(agent, agent_class, allocator, branch.ordinal).merge(key: branch.ordinal.to_s)
+        end
+
+        def comparable_branch(branch)
+          [branch.ordinal, branch.key, branch.agent, branch.binding_identity, branch.budget]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require_relative "../../types"
+require_relative "../prepared_step"
+require_relative "../prepared_step_dispatch"
+require_relative "branch"
+require_relative "enums"
+require_relative "payload"
+require_relative "payload_digest"
+require_relative "plan"
+
+module Smith
+  class Workflow
+    module Composite
+      class BranchExecution < Payload
+        VERSION = 1
+        ENUM_ATTRIBUTES = %i[kind resume_policy failure_policy reduction_policy retry_policy].freeze
+        private_constant :ENUM_ATTRIBUTES
+        OwnedString = Types::String.constructor { |value| value.is_a?(String) ? value.dup.freeze : value }
+        private_constant :OwnedString
+
+        attribute :version, Types::Integer.enum(VERSION)
+        attribute :execution_semantics_version, OwnedString.constrained(min_size: 1, max_size: 32)
+        attribute :dispatch, Types.Instance(PreparedStepDispatch)
+        attribute :plan_digest, OwnedString.constrained(format: PreparedStep::DIGEST_PATTERN)
+        attribute :kind, Types::Symbol.enum(:parallel, :fanout)
+        attribute :transition, OwnedString.constrained(min_size: 1, max_size: 256)
+        attribute :from, OwnedString.constrained(min_size: 1, max_size: 256)
+        attribute :execution_namespace, OwnedString.constrained(format: PreparedStep::UUID_PATTERN)
+        attribute :branch_count, Types::Integer.constrained(gteq: 1, lteq: Plan::MAX_BRANCHES)
+        attribute :input_digest, OwnedString.constrained(format: PreparedStep::DIGEST_PATTERN)
+        attribute :budget_state_digest, OwnedString.constrained(format: PreparedStep::DIGEST_PATTERN)
+        attribute :resume_policy, Types::Symbol.enum(Plan::RESUME_POLICY)
+        attribute :failure_policy, Types::Symbol.enum(Plan::FAILURE_POLICY)
+        attribute :reduction_policy, Types::Symbol.enum(Plan::REDUCTION_POLICY)
+        attribute :retry_policy, Types::Symbol.enum(Plan::RETRY_POLICY)
+        attribute :branch, Types.Instance(Branch)
+        attribute :digest, OwnedString.constrained(format: PreparedStep::DIGEST_PATTERN)
+
+        class << self
+          def build(plan:, branch:)
+            validate_plan_branch!(plan, branch)
+            values = execution_attributes(plan, branch)
+            new(values.merge(digest: PayloadDigest.call(serializable(values))))
+          end
+
+          def normalize_attributes(attributes)
+            normalized = super
+            normalize_dispatch!(normalized)
+            normalize_branch!(normalized)
+            ENUM_ATTRIBUTES.each { |key| normalized[key] = Enums.normalize(key, normalized[key]) }
+            normalized
+          end
+
+          def serializable(values)
+            values.merge(dispatch: values.fetch(:dispatch).to_h, branch: values.fetch(:branch).to_h)
+          end
+
+          private
+
+          def execution_attributes(plan, branch)
+            {
+              version: VERSION,
+              execution_semantics_version: plan.execution_semantics_version,
+              dispatch: plan.dispatch,
+              plan_digest: plan.plan_digest,
+              kind: plan.kind,
+              transition: plan.transition,
+              from: plan.from,
+              execution_namespace: plan.execution_namespace,
+              branch_count: plan.branches.length,
+              input_digest: plan.input_digest,
+              budget_state_digest: plan.budget_state_digest,
+              resume_policy: plan.resume_policy,
+              failure_policy: plan.failure_policy,
+              reduction_policy: plan.reduction_policy,
+              retry_policy: plan.retry_policy,
+              branch:
+            }
+          end
+
+          def validate_plan_branch!(plan, branch)
+            raise ArgumentError, "plan must be a Smith composite plan" unless plan.is_a?(Plan)
+            raise ArgumentError, "branch must be a Smith composite branch" unless branch.is_a?(Branch)
+
+            expected = plan.branches.fetch(branch.ordinal) do
+              raise ArgumentError, "composite branch ordinal is invalid"
+            end
+            raise ArgumentError, "composite branch does not belong to plan" unless expected.to_h == branch.to_h
+          end
+
+          def normalize_dispatch!(attributes)
+            value = attributes[:dispatch]
+            attributes[:dispatch] = PreparedStepDispatch.deserialize(value) unless value.is_a?(PreparedStepDispatch)
+          end
+
+          def normalize_branch!(attributes)
+            value = attributes[:branch]
+            attributes[:branch] = Branch.deserialize(value) unless value.is_a?(Branch)
+          end
+        end
+
+        def initialize(attributes)
+          owned = self.class.normalize_attributes(attributes)
+          super(owned)
+          validate_contract!
+        end
+
+        private
+
+        def validate_contract!
+          Plan.validate_branch_count!(branch_count)
+          raise ArgumentError, "composite branch ordinal exceeds branch count" if branch.ordinal >= branch_count
+          unless execution_semantics_version == Smith::EXECUTION_SEMANTICS_VERSION
+            raise ArgumentError, "composite branch execution semantics do not match"
+          end
+
+          expected = PayloadDigest.call(self.class.serializable(to_h.except(:digest)))
+          raise ArgumentError, "composite branch execution digest does not match" unless digest == expected
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative "../../errors"
+require_relative "error"
+
+module Smith
+  class Workflow
+    module Composite
+      class BranchFailure < WorkflowError
+        DETAIL_KEYS = {
+          "branch_key" => :branch_key,
+          "error_class" => :error_class,
+          "error_family" => :error_family,
+          "retryable" => :retryable,
+          "kind" => :kind
+        }.freeze
+        DETAIL_NAMES = DETAIL_KEYS.values.freeze
+        private_constant :DETAIL_KEYS, :DETAIL_NAMES
+
+        attr_reader :branch_key, :error_class, :error_family, :retryable, :kind, :details
+
+        def self.from_details(details)
+          values = normalize_details(details)
+          error = Error.new(
+            class_name: values.fetch(:error_class),
+            family: values.fetch(:error_family),
+            retryable: values.fetch(:retryable),
+            kind: values.fetch(:kind)
+          )
+          new(branch_key: values.fetch(:branch_key), error:)
+        end
+
+        def self.normalize_details(details)
+          raise ArgumentError, "composite branch failure details must be a Hash" unless details.is_a?(Hash)
+
+          normalized = {}
+          Hash.instance_method(:each_pair).bind_call(details) do |key, value|
+            name = normalize_detail_key(key)
+            if normalized.key?(name)
+              raise ArgumentError, "composite branch failure details contain a duplicate attribute"
+            end
+
+            normalized[name] = value
+          end
+          missing = DETAIL_NAMES - normalized.keys
+          raise ArgumentError, "composite branch failure details are missing required attributes" if missing.any?
+
+          normalized
+        end
+
+        def self.normalize_detail_key(key)
+          name = key.is_a?(Symbol) ? key : DETAIL_KEYS.fetch(key, key)
+          return name if DETAIL_NAMES.include?(name)
+
+          raise ArgumentError, "composite branch failure details contain an unknown attribute"
+        end
+        private_class_method :normalize_details
+        private_class_method :normalize_detail_key
+
+        def initialize(branch_key:, error:)
+          validate_arguments!(branch_key, error)
+          @branch_key = branch_key.dup.freeze
+          @error_class = error.class_name.dup.freeze
+          @error_family = error.family.dup.freeze
+          @retryable = error.retryable
+          @kind = error.kind&.dup&.freeze
+          @details = failure_details
+          super("composite branch #{branch_key.inspect} failed")
+        end
+
+        private
+
+        def validate_arguments!(branch_key, error)
+          valid_key = branch_key.is_a?(String) && branch_key.length.between?(1, 256)
+          raise ArgumentError, "composite branch failure key must be a bounded non-empty String" unless valid_key
+          raise ArgumentError, "composite branch failure requires typed error evidence" unless error.is_a?(Error)
+        end
+
+        def failure_details
+          {
+            branch_key: @branch_key,
+            error_class: @error_class,
+            error_family: @error_family,
+            retryable: @retryable,
+            kind: @kind
+          }.freeze
+        end
+      end
+    end
+  end
+end