phronomy 0.25.0 → 0.27.0

data/lib/phronomy/agent/{recovery_coordinator → recovery/recovery_coordinator}/resolution.rb

@@ -10,7 +10,7 @@ module Phronomy
 
         def begin_resolve_on_event_loop(request)
           event_loop = @runtime.event_loop
-          state = event_loop.agent_execution_state(
+          state = Phronomy::Agent::ExecutionRegistry.for(event_loop).agent_execution_state(
             request.execution_id
           )
           unless state && state.agent.equal?(agent)
@@ -26,7 +26,7 @@ module Phronomy
           unless current.execution_revision ==
               request.expected_execution_revision
             request.completion.fail(
-              Phronomy::Persistence::ConflictError.new(
+              Phronomy::Storage::ConflictError.new(
                 "Recovery resolution revision conflict: expected " \
                 "#{request.expected_execution_revision}, actual " \
                 "#{current.execution_revision}"
@@ -69,7 +69,7 @@ module Phronomy
             result: request.result,
             failure: request.failure
           )
-          event_loop.mark_agent_execution_admission(
+          Phronomy::Agent::ExecutionRegistry.for(event_loop).mark_agent_execution_admission(
             agent.agent_id,
             execution_id: current.execution_id,
             state: :recovery_required
@@ -116,9 +116,9 @@ module Phronomy
           llm_call_id =
             operation.subject.fetch(:llm_call_id).to_s
           unless current.metadata[
-            RecoverySupport::PENDING_LLM_ID_KEY
+            ExecutionMetadata::PENDING_LLM_ID_KEY
           ].to_s == llm_call_id
-            raise Phronomy::Persistence::ConflictError,
+            raise Phronomy::Storage::ConflictError,
               "LLM Recovery subject is no longer pending"
           end
 
@@ -136,27 +136,27 @@ module Phronomy
                 "automatic semantic redispatch is unavailable without a replay contract"
             }.freeze
             recovery = {
-              "version" => RecoverySupport::CONTRACT_VERSION,
+              "version" => ExecutionMetadata::CONTRACT_VERSION,
               "resolution_outcome" => "not_performed",
               "failure" => failure
             }.freeze
             updated = current.with(
               phase: :recovery_resolved_failed,
               metadata: current.metadata.merge(
-                RecoverySupport::RECOVERY_METADATA_KEY => recovery
+                ExecutionMetadata::RECOVERY_METADATA_KEY => recovery
               )
             )
             intended = ResolutionResult.new(execution: updated)
             save_resolution_result(current, intended)
           when :failed
             recovery = {
-              "version" => RecoverySupport::CONTRACT_VERSION,
+              "version" => ExecutionMetadata::CONTRACT_VERSION,
               "failure" => operation.failure
             }
             updated = current.with(
               phase: :recovery_resolved_failed,
               metadata: current.metadata.merge(
-                RecoverySupport::RECOVERY_METADATA_KEY =>
+                ExecutionMetadata::RECOVERY_METADATA_KEY =>
                   recovery
               )
             )
@@ -170,7 +170,6 @@ module Phronomy
               )
             updated = nil
             with_resolution_f1_capture do |tx|
-              main = agent.send(:execution_coordinator_for, agent.__coordination_config)
               snapshot = {
                 llm_results: [{
                   llm_call_id: llm_call_id,
@@ -178,22 +177,22 @@ module Phronomy
                   error: nil,
                   streaming: (
                     current.metadata[
-                      RecoverySupport::INVOCATION_MODE_KEY
+                      ExecutionMetadata::INVOCATION_MODE_KEY
                     ].to_s == "stream"
                   ),
                   manifest_ref: current.metadata.fetch(
                     "manifest_ref"
                   ),
                   started_at: current.metadata[
-                    RecoverySupport::PENDING_LLM_STARTED_AT_KEY
+                    ExecutionMetadata::PENDING_LLM_STARTED_AT_KEY
                   ] || current.updated_at
                 }.freeze].freeze,
                 runtime_events: [].freeze,
                 active_call: nil
               }.freeze
-              records, calls = main.send(
-                :encode_runtime_records,
+              records, calls = RuntimeRecordEncoder.encode(
                 current,
+                agent_id: agent.agent_id,
                 tx: tx,
                 snapshot: snapshot,
                 context_candidate: true,
@@ -210,15 +209,15 @@ module Phronomy
                 :recovery_provider_completed : :recovery_tools
               metadata = current.metadata.dup
               metadata.delete(
-                RecoverySupport::PENDING_LLM_ID_KEY
+                ExecutionMetadata::PENDING_LLM_ID_KEY
               )
               metadata.delete(
-                RecoverySupport::PENDING_LLM_STARTED_AT_KEY
+                ExecutionMetadata::PENDING_LLM_STARTED_AT_KEY
               )
               metadata.delete("framework_calls_pending")
               metadata["framework_calls_pending"] = true unless framework_subjects.empty?
-              if subjects.any? && Array(metadata[RecoverySupport::TOOL_BATCH_METADATA_KEY]).empty?
-                metadata[RecoverySupport::TOOL_BATCH_METADATA_KEY] = subjects.map do |entry|
+              if subjects.any? && Array(metadata[ExecutionMetadata::TOOL_BATCH_METADATA_KEY]).empty?
+                metadata[ExecutionMetadata::TOOL_BATCH_METADATA_KEY] = subjects.map do |entry|
                   {
                     "tool_invocation_id" => entry.fetch("tool_invocation_id"),
                     "llm_call_id" => entry.fetch("llm_call_id"),
@@ -231,11 +230,11 @@ module Phronomy
               end
               if external_subjects.empty?
                 metadata.delete(
-                  RecoverySupport::RECOVERY_METADATA_KEY
+                  ExecutionMetadata::RECOVERY_METADATA_KEY
                 )
               else
                 metadata[
-                  RecoverySupport::RECOVERY_METADATA_KEY
+                  ExecutionMetadata::RECOVERY_METADATA_KEY
                 ] = RecoverySupport.build_recovery_hash(
                   external_subjects
                 )
@@ -268,7 +267,7 @@ module Phronomy
             recovery = RecoverySupport.build_recovery_hash(subjects)
           end
           unless recovery
-            raise Phronomy::Persistence::ConflictError,
+            raise Phronomy::Storage::ConflictError,
               "Tool Recovery state is missing"
           end
 
@@ -281,7 +280,7 @@ module Phronomy
               hash.fetch("state", "unresolved") == "unresolved"
           end
           unless subject_entry
-            raise Phronomy::Persistence::ConflictError,
+            raise Phronomy::Storage::ConflictError,
               "Tool Recovery subject is no longer unresolved"
           end
           subject_entry =
@@ -309,7 +308,7 @@ module Phronomy
             updated = current.with(
               phase: :recovery_resolved_failed,
               metadata: current.metadata.merge(
-                RecoverySupport::RECOVERY_METADATA_KEY =>
+                ExecutionMetadata::RECOVERY_METADATA_KEY =>
                   resolved_recovery
               )
             )
@@ -329,7 +328,7 @@ module Phronomy
             updated = current.with(
               phase: :recovery_resolved_failed,
               metadata: current.metadata.merge(
-                RecoverySupport::RECOVERY_METADATA_KEY =>
+                ExecutionMetadata::RECOVERY_METADATA_KEY =>
                   recovery_with_failure
               )
             )
@@ -338,9 +337,7 @@ module Phronomy
           when :succeeded
             updated = nil
             with_resolution_f1_capture do |tx|
-              main = agent.send(:execution_coordinator_for, agent.__coordination_config)
-              result_ref = main.send(
-                :put_runtime_content,
+              result_ref = RuntimeRecordEncoder.put_runtime_content(
                 tx,
                 operation.result
               )
@@ -363,9 +360,9 @@ module Phronomy
                     subject_entry.fetch("llm_call_id").to_s
                 }.freeze
               )
-              records, _calls = main.send(
-                :encode_runtime_records,
+              records, _calls = RuntimeRecordEncoder.encode(
                 current,
+                agent_id: agent.agent_id,
                 tx: tx,
                 snapshot: {
                   llm_results: [].freeze,
@@ -388,7 +385,7 @@ module Phronomy
                 RecoverySupport.unresolved_subjects(
                   next_recovery
                 )
-              tool_batch = Array(current.metadata[RecoverySupport::TOOL_BATCH_METADATA_KEY]).map do |entry|
+              tool_batch = Array(current.metadata[ExecutionMetadata::TOOL_BATCH_METADATA_KEY]).map do |entry|
                 if entry.fetch("tool_invocation_id") == subject_entry.fetch("tool_invocation_id")
                   entry.merge("status" => "completed", "result" => operation.result)
                 else
@@ -402,8 +399,8 @@ module Phronomy
                 working_records:
                   current.working_records + records,
                 metadata: current.metadata.merge(
-                  RecoverySupport::RECOVERY_METADATA_KEY => next_recovery,
-                  RecoverySupport::TOOL_BATCH_METADATA_KEY => tool_batch
+                  ExecutionMetadata::RECOVERY_METADATA_KEY => next_recovery,
+                  ExecutionMetadata::TOOL_BATCH_METADATA_KEY => tool_batch
                 )
               )
               tx.executions.save(
@@ -418,10 +415,10 @@ module Phronomy
         # simplecov:enable
 
         def known_non_f1_error?(error)
-          error.is_a?(Phronomy::Persistence::ConflictError) ||
-            error.is_a?(Phronomy::Persistence::NotFoundError) ||
-            error.is_a?(Phronomy::Persistence::SerializationError) ||
-            error.is_a?(Phronomy::Persistence::UnsupportedBackendError) ||
+          error.is_a?(Phronomy::Storage::ConflictError) ||
+            error.is_a?(Phronomy::Storage::NotFoundError) ||
+            error.is_a?(Phronomy::Storage::SerializationError) ||
+            error.is_a?(Phronomy::Storage::UnsupportedBackendError) ||
             error.is_a?(ArgumentError) ||
             error.is_a?(Phronomy::ConfigurationError)
         end
@@ -477,27 +474,27 @@ module Phronomy
           if current.to_h == operation.execution.to_h
             raise(error.is_a?(ResolutionOutcomeUnknownError) ? error.original_error : error)
           end
-          raise Phronomy::Persistence::ConflictError,
+          raise Phronomy::Storage::ConflictError,
             "Recovery resolution durable outcome conflicts with both expected pre-state and intended post-state"
         end
 
         def apply_resolve_on_event_loop(ready)
           request = ready.request
           event_loop = @runtime.event_loop
-          state = event_loop.agent_execution_state(request.execution_id)
+          state = Phronomy::Agent::ExecutionRegistry.for(event_loop).agent_execution_state(request.execution_id)
           unless state && state.agent.equal?(agent)
             raise Phronomy::ExecutionRehydrationRequiredError,
               "recovered execution disappeared before resolution apply"
           end
           unless state.execution.equal?(ready.operation.execution) && state.fsm_session_id.nil?
-            raise Phronomy::Persistence::ConflictError,
+            raise Phronomy::Storage::ConflictError,
               "Recovery execution changed before resolution apply"
           end
           raise ready.error if ready.error
 
           result = ready.result
           if result.execution
-            event_loop.replace_agent_execution(request.execution_id, execution: result.execution)
+            Phronomy::Agent::ExecutionRegistry.for(event_loop).replace_agent_execution(request.execution_id, execution: result.execution)
           end
           raise result.error if result.error
 

data/lib/phronomy/agent/{recovery_coordinator.rb → recovery/recovery_coordinator.rb}

@@ -57,14 +57,14 @@ module Phronomy
           Array(tx.executions.list_active(agent.agent_id))
         end
         if active.length > 1
-          raise Phronomy::Persistence::ConflictError,
+          raise Phronomy::Storage::ConflictError,
             "multiple active AgentExecutions exist for #{agent.agent_id}"
         end
         return agent if active.empty?
 
         execution = active.first
         unless execution.agent_id.to_s == agent.agent_id.to_s
-          raise Phronomy::Persistence::ConflictError,
+          raise Phronomy::Storage::ConflictError,
             "active AgentExecution belongs to another Agent: #{execution.agent_id}"
         end
 
@@ -89,7 +89,7 @@ module Phronomy
             "load must register on_event"
         end
 
-        completion = Phronomy::Task.deferred(
+        completion = Phronomy::TaskResult.deferred(
           name: "agent-recovery-load:#{execution.execution_id}"
         )
         command = InstallCommand.new(
@@ -140,7 +140,7 @@ module Phronomy
         failure = error_present ?
           RecoverySupport.resolution_failure(error) : nil
 
-        completion = Phronomy::Task.deferred(
+        completion = Phronomy::TaskResult.deferred(
           name: "agent-recovery-resolve:#{execution_id}"
         )
         command = ResolveCommand.new(
@@ -163,7 +163,7 @@ module Phronomy
         end
         completion
       rescue => caught
-        completion ||= Phronomy::Task.deferred(
+        completion ||= Phronomy::TaskResult.deferred(
           name: "agent-recovery-resolve:#{execution_id}"
         )
         completion.fail(caught)
@@ -187,14 +187,10 @@ module Phronomy
       private
 
       def post_control(command)
-        @runtime.event_loop.post(
-          Phronomy::Event.new(
-            type: :agent_control,
-            target_id:
-              Phronomy::EventLoop::SYSTEM_CHANNEL_ID,
-            payload: {command: command}.freeze
-          )
-        )
+        admission = command.is_a?(InstallCommand) || command.is_a?(ResolveCommand)
+        completion = admission ? command.completion : command.request.completion
+        ExecutionRegistry.for(@runtime.event_loop).post(command,
+          admission: admission, completion: completion)
       rescue Phronomy::RuntimeShutdownError
         false
       end

data/lib/phronomy/agent/recovery/recovery_support.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module RecoverySupport
+      module_function
+
+      def canonical_copy(value)
+        Phronomy::Values::Serializable.convert(value,
+          unsupported_message: "Recovery value is not canonically serializable")
+      end
+
+      def tool_calls_from_outcome(outcome)
+        Array(outcome.tool_calls)
+      end
+
+      def normalize_provider_outcome(value)
+        return value if value.is_a?(Phronomy::Agent::ProviderCallOutcome)
+
+        if value.is_a?(Hash)
+          return Phronomy::Agent::ProviderCallOutcome.from_h(value)
+        end
+
+        captured = Phronomy::Agent::ProviderCallOutcome.capture(value)
+        return captured if captured
+
+        raise ArgumentError,
+          "LLM Recovery :succeeded requires a Provider result or ProviderCallOutcome-compatible Hash"
+      end
+
+      def resolution_failure(error)
+        {
+          "class" => error.class.name.to_s,
+          "message" => error.message.to_s
+        }.freeze
+      end
+
+      def error_from_failure(failure)
+        hash = failure.to_h { |key, value| [key.to_s, value] }
+        Phronomy::Error.new(
+          "#{hash.fetch("class", "Error")}: #{hash.fetch("message", "Recovery-resolved failure")}"
+        )
+      end
+
+      def event_payload(execution, descriptor)
+        {
+          execution_id: execution.execution_id,
+          execution_revision: execution.execution_revision,
+          reason: descriptor.fetch(:reason),
+          subject: Phronomy::Recovery.normalize_subject(
+            descriptor.fetch(:subject)
+          ),
+          allowed_outcomes: Array(
+            descriptor.fetch(:allowed_outcomes)
+          ).map(&:to_sym).freeze,
+          facts: Phronomy::Values::Immutable.copy(
+            descriptor.fetch(:facts, {})
+          )
+        }.freeze
+      end
+
+      def pending_llm_descriptor(execution)
+        llm_call_id = execution.metadata[ExecutionMetadata::PENDING_LLM_ID_KEY]
+        return unless llm_call_id
+
+        {
+          reason: :outcome_unknown,
+          subject: {
+            type: :llm_call,
+            llm_call_id: llm_call_id
+          },
+          allowed_outcomes: Phronomy::Recovery::OUTCOMES,
+          facts: {
+            manifest_ref: execution.metadata["manifest_ref"],
+            call_sequence: execution.llm_calls.length + 1
+          }.compact.freeze
+        }.freeze
+      end
+
+      def recovery_hash(execution)
+        value = execution.metadata[ExecutionMetadata::RECOVERY_METADATA_KEY]
+        value.is_a?(Hash) ? value : nil
+      end
+
+      def current_tool_descriptor(execution)
+        recovery = recovery_hash(execution)
+        return unless recovery
+
+        subjects = Array(recovery["subjects"] || recovery[:subjects])
+        current = subjects.find do |entry|
+          hash = entry.to_h { |key, value| [key.to_s, value] }
+          hash.fetch("state", "unresolved") == "unresolved"
+        end
+        return unless current
+
+        hash = current.to_h { |key, value| [key.to_s, value] }
+        {
+          reason: (recovery["reason"] || recovery[:reason] || "outcome_unknown").to_sym,
+          subject: {
+            type: :tool_invocation,
+            tool_invocation_id: hash.fetch("tool_invocation_id")
+          },
+          allowed_outcomes: Array(
+            recovery["allowed_outcomes"] ||
+              recovery[:allowed_outcomes] ||
+              Phronomy::Recovery::OUTCOMES
+          ).map(&:to_sym),
+          facts: {
+            tool_call_id: hash["tool_call_id"],
+            tool_name: hash["tool_name"],
+            arguments: hash["arguments"],
+            llm_call_id: hash["llm_call_id"]
+          }.compact
+        }.freeze
+      end
+
+      def pending_tool_subjects(execution)
+        Array(execution.metadata[ExecutionMetadata::TOOL_BATCH_METADATA_KEY]).filter_map do |entry|
+          hash = entry.to_h { |key, value| [key.to_s, value] }
+          next unless %w[authorized awaiting_approval].include?(
+            hash.fetch("status")
+          )
+
+          {
+            "tool_invocation_id" => hash.fetch("tool_invocation_id"),
+            "llm_call_id" => hash["llm_call_id"],
+            "tool_call_id" => hash.fetch("tool_call_id"),
+            "tool_name" => hash.fetch("tool_name"),
+            "arguments" => canonical_copy(
+              hash["arguments"] || hash["raw_arguments"] || {}
+            ),
+            "state" => "unresolved"
+          }.compact.freeze
+        end.freeze
+      end
+
+      def pending_tool_descriptor(execution)
+        subjects = pending_tool_subjects(execution)
+        return if subjects.empty?
+
+        first = subjects.first
+        {
+          reason: :outcome_unknown,
+          subject: {
+            type: :tool_invocation,
+            tool_invocation_id: first.fetch("tool_invocation_id")
+          },
+          allowed_outcomes: Phronomy::Recovery::OUTCOMES,
+          facts: {
+            tool_call_id: first["tool_call_id"],
+            tool_name: first["tool_name"],
+            arguments: first["arguments"],
+            llm_call_id: first["llm_call_id"]
+          }.compact
+        }.freeze
+      end
+
+      def recovery_descriptor(execution)
+        case execution.phase.to_sym
+        when :calling_llm
+          pending_llm_descriptor(execution)
+        when :resuming
+          approved = execution.approval_request &&
+            (
+              execution.approval_request["approved"] ||
+              execution.approval_request[:approved]
+            )
+          approved ? pending_tool_descriptor(execution) : nil
+        when :dispatching_tools
+          pending_tool_descriptor(execution)
+        when :recovery_tools
+          current_tool_descriptor(execution)
+        end
+      end
+
+      def build_tool_subjects(execution, llm_call_id, outcome)
+        tool_calls_from_outcome(outcome).map do |call|
+          call_hash = canonical_copy(call)
+          tool_call_id = call_hash.fetch("id").to_s
+          tool_name = call_hash.fetch("name").to_s
+          {
+            "tool_invocation_id" => ToolInvocation.semantic_id(
+              execution_id: execution.execution_id,
+              llm_call_id: llm_call_id,
+              tool_call_id: tool_call_id,
+              tool_name: tool_name
+            ),
+            "llm_call_id" => llm_call_id.to_s,
+            "tool_call_id" => tool_call_id,
+            "tool_name" => tool_name,
+            "arguments" => canonical_copy(call_hash.fetch("arguments", {})),
+            "state" => "unresolved"
+          }.freeze
+        end.freeze
+      end
+
+      def build_recovery_hash(subjects, reason: :outcome_unknown, allowed_outcomes: Phronomy::Recovery::OUTCOMES)
+        {
+          "version" => ExecutionMetadata::CONTRACT_VERSION,
+          "reason" => reason.to_s,
+          "allowed_outcomes" => Array(allowed_outcomes).map(&:to_s),
+          "subjects" => Array(subjects).map { |entry| canonical_copy(entry) }
+        }.freeze
+      end
+
+      def update_recovery_subject(recovery, tool_invocation_id:, state:, outcome:, result_ref: nil)
+        copy = canonical_copy(recovery)
+        copy["subjects"] = Array(copy.fetch("subjects")).map do |entry|
+          next entry unless entry.fetch("tool_invocation_id").to_s == tool_invocation_id.to_s
+
+          entry.merge(
+            "state" => state.to_s,
+            "outcome" => outcome.to_s,
+            "result_ref" => result_ref
+          ).compact
+        end
+        copy.freeze
+      end
+
+      def unresolved_subjects(recovery)
+        Array(recovery.fetch("subjects")).select do |entry|
+          entry.fetch("state", "unresolved") == "unresolved"
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/selection/candidate.rb

@@ -41,7 +41,7 @@ module Phronomy
             sequence: values[:sequence] && Integer(values[:sequence]),
             constraint: effective_constraint,
             priority: Integer(values[:priority] || 0),
-            metadata: Immutable.copy(values[:metadata] || {})
+            metadata: Phronomy::Values::Immutable.copy(values[:metadata] || {})
           )
 
           super(**normalized)

data/lib/phronomy/agent/{approval_evaluation_request.rb → tool_execution/approval_evaluation_request.rb}

@@ -102,18 +102,7 @@ module Phronomy
       private
 
       def immutable_copy(value)
-        case value
-        when Hash
-          value.each_with_object({}) do |(key, item), result|
-            result[immutable_copy(key)] = immutable_copy(item)
-          end.freeze
-        when Array
-          value.map { |item| immutable_copy(item) }.freeze
-        when String
-          value.dup.freeze
-        else
-          value
-        end
+        Phronomy::Values::Immutable.copy(value)
       end
     end
   end

data/lib/phronomy/agent/{tool_approval_request.rb → tool_execution/tool_approval_request.rb}

@@ -75,16 +75,7 @@ module Phronomy
         private
 
         def immutable_copy(value)
-          case value
-          when Hash
-            value.each_with_object({}) { |(k, v), h| h[immutable_copy(k)] = immutable_copy(v) }.freeze
-          when Array
-            value.map { |v| immutable_copy(v) }.freeze
-          when String
-            value.dup.freeze
-          else
-            value
-          end
+          Phronomy::Values::Immutable.copy(value)
         end
       end
 

data/lib/phronomy/agent/tool_execution/tool_binding.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Builds invocation-independent Tool decorators from explicit Agent settings.
+    # Authorization, execution and Orchestrator context remain with their owners.
+    # @api private
+    class ToolBinding
+      def initialize(tool_class, alias_name:)
+        @tool_class = if alias_name
+          Class.new(tool_class) do
+            tool_name alias_name
+          end
+        else
+          tool_class
+        end
+      end
+
+      def prepare(result_filters:)
+        return @tool_class if result_filters.empty?
+
+        effective_name = @tool_class.new.name
+        custom_async_call =
+          @tool_class.instance_method(:call_async).owner !=
+          Phronomy::Agent::Context::Capability::Base
+        filter_async_result = method(:filter_async_result)
+
+        Class.new(@tool_class) do
+          tool_name effective_name
+          define_method(:call) do |args, **kwargs|
+            result = super(args, **kwargs)
+            result_filters.inject(result) { |val, filter|
+              filter.call(val, tool_name: name, args: args)
+            }
+          end
+
+          if custom_async_call
+            define_method(:call_async) do |args, **kwargs|
+              source = super(args, **kwargs)
+              filter_async_result.call(source, name) do |value|
+                result_filters.inject(value) { |val, filter|
+                  filter.call(val, tool_name: name, args: args)
+                }
+              end
+            end
+          end
+        end
+      end
+
+      private
+
+      def filter_async_result(source, tool_name, &filter_result)
+        filtered = Phronomy::Concurrency::PhysicalCompletionTask.deferred(
+          name: "tool-filter-#{tool_name}"
+        )
+        source_has_physical_signal = source.respond_to?(:on_physical_complete)
+        source.on_physical_complete { filtered.mark_physical_complete! } if
+          source_has_physical_signal
+        source.on_complete do |value, error|
+          if error
+            propagate_failure(filtered, source, error, source_has_physical_signal)
+          else
+            complete_filtered_result(filtered, source_has_physical_signal) do
+              filter_result.call(value)
+            end
+          end
+        end
+        filtered
+      end
+
+      def propagate_failure(filtered, source, error, source_has_physical_signal)
+        filtered.mark_physical_complete! unless source_has_physical_signal
+        if source.respond_to?(:status) && source.status == :cancelled
+          filtered.cancel!(error)
+        else
+          filtered.fail(error)
+        end
+      end
+
+      def complete_filtered_result(filtered, source_has_physical_signal)
+        result = yield
+        filtered.mark_physical_complete! unless source_has_physical_signal
+        filtered.complete(result)
+      rescue => filter_error
+        filtered.mark_physical_complete! unless source_has_physical_signal
+        filtered.fail(filter_error)
+      end
+    end
+  end
+end