trailblazer-macro 2.1.11 → 2.1.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34955a47d4c5d006819242d4d9a13ce658a3473afe0d7f6b4570374dbff557c0
-  data.tar.gz: 4f8fb6b8ba5c8bcc3db19ac977507675550c0defa2be95b771c77914644837b6
+  metadata.gz: 14fa43e34517eca4e07e257fc5a172f406b88294b72f222109203156af53b684
+  data.tar.gz: 4d357be0a556d5431d7e10971e8ca1f9853e8029ecd5c1835c356d2169c9b7cb
 SHA512:
-  metadata.gz: 71cc088d718a756171fd402d12dfb3b55d817e87356ea13088871dbc539085b92af36f57b7e7e43c817181aac9b73c580f8e69208b96deec43c59f551df742f9
-  data.tar.gz: c400ba9542fd36400b6ebb0bffc142f3a51212a33b48504b527fdd35b15a5060a95d9c8735a9f146e2f259906568515a7199e9eae7087a3ad3a5b59cbb6a0374
+  metadata.gz: 600a2b8ae99cb504a0574b929e59ca63edc219b43e219b5af3c414d0c362e323f3cb6ff276f86ce02b19466aab1723ae60bc8b34f91d94764f3b82eadeaa7c2c
+  data.tar.gz: f03b36faa58d2e0ea5c265b48194cd14bb5825cfecace98777637d44a91bb2404ebb710e1db3ce7a7b7b383158413db9f4ffac5f6bb7abf7226ea1e02749d97c

data/.github/workflows/ci.yml

@@ -1,3 +1,6 @@
+## This file is managed by Terraform.
+## Do not modify this file directly, as it may be overwritten.
+## Please open an issue instead.
 name: CI
 on: [push, pull_request]
 jobs:
@@ -5,13 +8,12 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        # Due to https://github.com/actions/runner/issues/849, we have to use quotes for '3.0'
-        ruby: [2.5, 2.6, 2.7, '3.0', "3.1", head, jruby]
+        ruby: [2.7, '3.0', '3.1']
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - uses: ruby/setup-ruby@v1
       with:
         ruby-version: ${{ matrix.ruby }}
-        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+        bundler-cache: true
     - run: bundle exec rake

data/.github/workflows/ci_jruby.yml

@@ -0,0 +1,19 @@
+## This file is managed by Terraform.
+## Do not modify this file directly, as it may be overwritten.
+## Please open an issue instead.
+name: CI JRuby
+on: [push, pull_request]
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: [jruby, jruby-head]
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+        bundler-cache: true
+    - run: bundle exec rake

data/.github/workflows/ci_legacy.yml

@@ -0,0 +1,19 @@
+## This file is managed by Terraform.
+## Do not modify this file directly, as it may be overwritten.
+## Please open an issue instead.
+name: CI with EOL ruby versions
+on: [push, pull_request]
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: [2.5, 2.6]
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+        bundler-cache: true
+    - run: bundle exec rake

data/.github/workflows/ci_truffleruby.yml

@@ -0,0 +1,19 @@
+## This file is managed by Terraform.
+## Do not modify this file directly, as it may be overwritten.
+## Please open an issue instead.
+name: CI TruffleRuby
+on: [push, pull_request]
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: [truffleruby, truffleruby-head]
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+        bundler-cache: true
+    - run: bundle exec rake

data/CHANGES.md

@@ -1,3 +1,32 @@
+# 2.1.12
+
+## Internals
+
+* Introduce `AssignVariable`.
+* Use trailblazer-activity-dsl-linear-1.1.0.
+
+## Each()
+
+* Introducing the `Each()` macro to iterate over datasets while invoking a particular operation, as if
+  they were run as separate serially connected operations.
+
+## Nested()
+
+* Restructured internals, it's much more readable, `Dynamic` and `Static` are completely separated now.
+* `Static` handles `:auto_wire` and allows to route any nested terminus. This was not possible before,
+  you only had `FastTrack` generic termini.
+* Better warning when using `Nested(Operation)` without a dynamic decider.
+* Internal structure of `Nested()` has changed, the trace looks different.
+
+## Wrap()
+
+* Now implements patching.
+
+## Model()
+
+* Remove `ctx[:"result.model"]`.
+* Don't set `ctx[:model]` unless `Builder` returns a model.
+
 # 2.1.11
 
 * In `Nested()`, we no longer use `Railway::End::Success` and `Railway::End::Failure` as static outputs but

data/Gemfile

@@ -3,13 +3,15 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in trailblazer.gemspec
 gemspec
 
-# gem "trailblazer", github: "trailblazer/trailblazer"
-# gem "trailblazer-activity", path: "../trailblazer-activity"
+# gem "trailblazer-developer", github: "trailblazer/trailblazer-developer"
+# gem "trailblazer-activity", github: "trailblazer/trailblazer-activity"
+# gem "trailblazer-activity-dsl-linear", github: "trailblazer/trailblazer-activity-dsl-linear"
 # gem "trailblazer-activity-dsl-linear", path: "../trailblazer-activity-dsl-linear"
+# gem "trailblazer-developer", path: "../trailblazer-developer"
+# gem "trailblazer-activity", path: "../trailblazer-activity"
 # gem "trailblazer-macro-contract", git: "https://github.com/trailblazer/trailblazer-macro-contract"
 # gem "trailblazer-context", path: "../trailblazer-context"
-# gem "trailblazer-operation", path: "../trailblazer-operation"
-
+# gem "trailblazer-option", path: "../trailblazer-option"
 
 gem "minitest-line"
-gem "rubocop", require: false
+# gem "trailblazer-core-utils", path: "../trailblazer-core-utils"

data/lib/trailblazer/macro/each.rb

@@ -0,0 +1,170 @@
+module Trailblazer
+  module Macro
+    class Each < Macro::Strategy
+      # FIXME: for Strategy that wants to pass-through the exec_context, so it
+      # looks "invisible" for steps.
+      module Transitive
+        def call(args, exec_context:, **circuit_options)
+          # exec_context is our hosting Song::Activity::Cover
+          to_h[:activity].call(args, exec_context: exec_context, **circuit_options)
+        end
+      end
+
+      def self.call((ctx, flow_options), runner:, **circuit_options) # DISCUSS: do we need {start_task}?
+        dataset           = ctx.fetch(:dataset)
+        signal            = @state.get(:success_signal)
+        item_key          = @state.get(:item_key)
+        failing_semantic  = @state.get(:failing_semantic)
+        activity          = @state.get(:activity)
+
+        # I'd like to use {collect} but we can't {break} without losing the last iteration's result.
+        dataset.each_with_index do |element, index|
+          # This new {inner_ctx} will be disposed of after invoking the item activity.
+          inner_ctx = ctx.merge(
+            item_key => element, # defaults to {:item}
+            :index   => index,
+          )
+
+          # TODO: test aliasing
+          wrap_ctx, _ = ITERATION_INPUT_PIPE.({aggregate: {}, original_ctx: inner_ctx}, [[ctx, flow_options], circuit_options])
+          inner_ctx   = wrap_ctx[:input_ctx]
+
+          # using this runner will make it look as if block_activity is being run consequetively within {Each.iterate} as if they were steps
+          # Use TaskWrap::Runner to run the each block. This doesn't create the container_activity
+          # and literally simply invokes {block_activity.call}, which will set its own {wrap_static}.
+          signal, (returned_ctx, flow_options) = runner.(
+            block_activity,
+            [inner_ctx, flow_options],
+            runner:   runner,
+            **circuit_options,
+            activity: activity,
+          )
+
+          # {returned_ctx} at this point has Each(..., In => Out =>) applied!
+          #   Without configuration, this means {returned_ctx} is empty.
+          # DISCUSS: this is what usually happens in Out().
+          # merge all mutable parts into the original_ctx.
+          wrap_ctx, _ = ITERATION_OUTPUT_PIPE.({returned_ctx: returned_ctx, aggregate: {}, original_ctx: ctx}, [])
+          ctx         = wrap_ctx[:aggregate]
+
+          # Break the loop if {block_activity} emits failure signal
+          break if failing_semantic.include?(signal.to_h[:semantic]) # TODO: use generic check from older macro
+        end
+
+        return signal, [ctx, flow_options]
+      end
+
+      # This is basically Out() => {copy all mutable variables}
+      ITERATION_OUTPUT_PIPE = Activity::DSL::Linear::VariableMapping::DSL.pipe_for_composable_output()
+      # and this In() => {copy everything}
+      ITERATION_INPUT_PIPE  = Activity::DSL::Linear::VariableMapping::DSL.pipe_for_composable_input()
+
+      # Gets included in Debugger's Normalizer. Results in IDs like {invoke_block_activity.1}.
+      def self.compute_runtime_id(ctx, captured_node:, activity:, compile_id:, **)
+        # activity is the host activity
+        return compile_id unless activity[:each] == true
+
+        index = captured_node.captured_input.data[:ctx_snapshot].fetch(:index)
+
+        ctx[:runtime_id] = "#{compile_id}.#{index}"
+      end
+    end
+
+    # @api private The internals here are considered private and might change in the near future.
+    def self.Each(block_activity=nil, dataset_from: nil, item_key: :item, id: Macro.id_for(block_activity, macro: :Each, hint: dataset_from), collect: false, **dsl_options_for_iterated, &block)
+      dsl_options_for_iterated = block_activity if block_activity.is_a?(Hash) # Ruby 2.5 and 2.6
+
+      block_activity, outputs_from_block_activity = Macro.block_activity_for(block_activity, &block)
+
+      collect_options       = options_for_collect(collect: collect)
+      dataset_from_options  = options_for_dataset_from(dataset_from: dataset_from)
+
+      wrap_static_for_block_activity = task_wrap_for_iterated(
+        {Activity::Railway.Out() => []}. # per default, don't let anything out.
+        merge(collect_options).
+        merge(dsl_options_for_iterated)
+      )
+
+      # This activity is passed into the {Runner} for each iteration of {block_activity}.
+      container_activity = Activity::TaskWrap.container_activity_for(
+        block_activity,
+        each:         true, # mark this activity for {compute_runtime_id}.
+        nodes:        [Activity::NodeAttributes.new("invoke_block_activity", nil, block_activity)], # TODO: use TaskMap::TaskAttributes
+      ).merge(
+        wrap_static: Hash.new(wrap_static_for_block_activity)
+      )
+
+      # DISCUSS: move to Wrap.
+      termini_from_block_activity =
+        outputs_from_block_activity.
+          # DISCUSS: End.success needs to be the last here, so it's directly behind {Start.default}.
+          sort { |a,b| a.semantic == :success ? 1 : -1 }.
+          collect { |output|
+            [output.signal, id: "End.#{output.semantic}", magnetic_to: output.semantic, append_to: "Start.default"]
+          }
+
+      state = Declarative::State(
+        block_activity:   [block_activity, {copy: Trailblazer::Declarative::State.method(:subclass)}], # DISCUSS: move to Macro::Strategy.
+        item_key:         [item_key, {}], # DISCUSS: we could even allow the wrap_handler to be patchable.
+        failing_semantic: [[:failure, :fail_fast], {}],
+        activity:         [container_activity, {}],
+        success_signal:   [termini_from_block_activity[-1][0], {}] # FIXME: when subclassing (e.g. patching) this must be recomputed.
+      )
+
+      # {block_activity} looped. In the Stack, this will look as if {block_activity} is
+      # a child of {iterate_activity}, that's why we add {block_activity} as a Node in
+      # {iterate_activity}'s schema.
+      iterate_strategy = Class.new(Each) do
+        extend Macro::Strategy::State # now, the Wrap subclass can inherit its state and copy the {block_activity}.
+        initialize!(state)
+      end
+
+      each_activity = Activity::FastTrack(termini: termini_from_block_activity) # DISCUSS: what base class should we be using?
+      each_activity.extend Each::Transitive
+
+      # {Subprocess} with {strict: true} will automatically wire all {block_activity}'s termini to the corresponding termini
+      # of {each_activity} as they have the same semantics (both termini sets are identical).
+      each_activity.step Activity::Railway.Subprocess(iterate_strategy, strict: true),
+        id: "Each.iterate.#{block ? :block : block_activity}" # FIXME: test :id.
+
+      Activity::Railway.Subprocess(each_activity).
+        merge(id: id).
+        merge(dataset_from_options) # FIXME: provide that service via Subprocess.
+    end
+
+    def self.task_wrap_for_iterated(dsl_options)
+      # TODO: maybe the DSL API could be more "open" here? I bet it is, but I'm too lazy.
+      activity = Class.new(Activity::Railway) do
+        step({task: "iterated"}.merge(dsl_options))
+      end
+
+      activity.to_h[:config][:wrap_static]["iterated"]
+    end
+
+    # DSL options added to {block_activity} to implement {collect: true}.
+    def self.options_for_collect(collect:)
+      return {} unless collect
+
+      {
+        Activity::Railway.Inject(:collected_from_each) => ->(ctx, **) { [] }, # this is called only once.
+        Activity::Railway.Out() => ->(ctx, collected_from_each:, **) { {collected_from_each: collected_from_each += [ctx[:value]] } }
+      }
+    end
+
+    def self.options_for_dataset_from(dataset_from:)
+      return {} unless dataset_from
+
+      {
+        Activity::Railway.Inject(:dataset, override: true) => dataset_from, # {ctx[:dataset]} is private to {each_activity}.
+      }
+    end
+  end
+
+  if const_defined?(:Developer) # FIXME: how do you properly check for a gem?
+    Developer::Trace::Debugger.add_normalizer_step!(
+      Macro::Each.method(:compute_runtime_id),
+      id:     "Each.runtime_id",
+      append: :runtime_id, # so that the following {#runtime_path} picks up those changes made here.
+    )
+  end
+end

data/lib/trailblazer/macro/model.rb

@@ -2,7 +2,7 @@ module Trailblazer
   module Macro
 
     def self.Model(model_class = nil, action = :new, find_by_key = :id, id: 'model.build', not_found_terminus: false)
-      task = Activity::TaskBuilder::Binary(Model.new)
+      task = Activity::Circuit::TaskAdapter.for_step(Model.new)
 
       injections = {
         Activity::Railway.Inject() => [:params], # pass-through {:params} if it's in ctx.
@@ -24,11 +24,10 @@ module Trailblazer
 
     class Model
       def call(ctx, params: {}, **)
-        builder                 = Model::Builder.new
-        ctx[:model]         = model = builder.call(ctx, params)
-        ctx[:"result.model"] = result = Operation::Result.new(!model.nil?, {})
+        builder = Builder.new
+        model   = builder.call(ctx, params) or return
 
-        result.success?
+        ctx[:model] = model
       end
 
       class Builder

data/lib/trailblazer/macro/nested.rb

@@ -1,111 +1,173 @@
-# per default, everything we pass into a circuit is immutable. it's the ops/act's job to allow writing (via a Context)
 module Trailblazer
   module Macro
     # {Nested} macro.
-    def self.Nested(callable, id: "Nested(#{callable})", auto_wire: [])
+    # DISCUSS: rename auto_wire => static
+    def self.Nested(callable, id: Macro.id_for(callable, macro: :Nested, hint: callable), auto_wire: [])
+      # Warn developers when they confuse Nested with Subprocess (for simple nesting, without a dynamic decider).
       if callable.is_a?(Class) && callable < Nested.operation_class
-        caller_location = caller_locations(2, 1)[0]
-        warn "[Trailblazer]#{caller_location.absolute_path}: " \
-             "Using the `Nested()` macro with operations and activities is deprecated. " \
-             "Replace `Nested(#{callable})` with `Subprocess(#{callable})`."
+        caller_locations = caller_locations(1, 2)
+        caller_location = caller_locations[0].to_s =~ /forwardable/ ? caller_locations[1] : caller_locations[0]
+
+        Activity::Deprecate.warn caller_location,
+          "Using the `Nested()` macro without a dynamic decider is deprecated.\n" \
+          "To simply nest an activity or operation, replace `Nested(#{callable})` with `Subprocess(#{callable})`.\n" \
+          "Check the Subprocess API docs to learn more about nesting: https://trailblazer.to/2.1/docs/activity.html#activity-wiring-api-subprocess"
 
         return Activity::Railway.Subprocess(callable)
       end
 
-      task, outputs, compute_legacy_return_signal = Nested.Dynamic(callable, auto_wire: auto_wire)
+      task =
+        if auto_wire.any?
+          Nested.Static(callable, id: id, auto_wire: auto_wire)
+        else # no {auto_wire}
+          Nested.Dynamic(callable, id: id)
+        end
 
+      # |-- Nested.compute_nested_activity...Trailblazer::Macro::Nested::Decider
+      # `-- task_wrap.call_task..............Method
       merge = [
-        [task, id: "Nested.compute_nested_activity", prepend: "task_wrap.call_task"],
+        [Nested::Decider.new(callable), id: "Nested.compute_nested_activity", prepend: "task_wrap.call_task"],
       ]
 
-      if compute_legacy_return_signal
-        merge << [compute_legacy_return_signal, id: "Nested.compute_return_signal", append: "task_wrap.call_task"]
-      end
-
       task_wrap_extension = Activity::TaskWrap::Extension::WrapStatic.new(extension: Activity::TaskWrap::Extension(*merge))
 
-      {
-        task:       task,
+      Activity::Railway.Subprocess(task).merge( # FIXME: allow this directly in Subprocess
         id:         id,
         extensions: [task_wrap_extension],
-        outputs:    outputs,
-      }
+      )
     end
 
     # @private
-    module Nested
-      def self.operation_class
-        Operation
+    # @api private The internals here are considered private and might change in the near future.
+    #
+    # We don't need to override {Strategy.call} here to prevent {:exec_context} from being changed.
+    # The decider is run in the taskWrap before the {Nested} subclass is actually called.
+    class Nested < Trailblazer::Activity::Railway
+      def self.operation_class # TODO: remove once we don't need the deprecation anymore.
+        Trailblazer::Activity::DSL::Linear::Strategy
       end
 
-      # For dynamic `Nested`s that do not expose an {Activity} interface.
-      #
-      # Dynamic doesn't automatically connect outputs of runtime {Activity}
-      # at compile time (as we don't know which activity will be nested, obviously).
-      # So by default, it only connects good old success/failure ends. But it is also
-      # possible to connect all the ends of all possible dynamic activities
-      # by passing their list to {:auto_wire} option.
-      #
-      # step Nested(:compute_nested, auto_wire: [Create, Update])
-      def self.Dynamic(nested_activity_decider, auto_wire:)
-        if auto_wire.empty?
-          is_legacy = true # no auto_wire means we need to compute the legacy return signal.
-          auto_wire = [Class.new(Activity::Railway)]
+      # TaskWrap step to run the decider.
+      # It's part of the API that the decider sees the original ctx.
+      # So this has to be placed in tW because we this step needs to be run *before* In() filters
+      # to resemble the behavior from pre 2.1.12.
+      class Decider
+        def initialize(nested_activity_decider)
+          @nested_activity_decider = Activity::Circuit.Step(nested_activity_decider, option: true)
         end
 
-        outputs = outputs_for(auto_wire)
-        task    = Dynamic.new(nested_activity_decider)
-        compute_legacy_return_signal = Dynamic::ComputeLegacyReturnSignal.new(outputs) if is_legacy
+        # TaskWrap API.
+        def call(wrap_ctx, original_args)
+          (ctx, flow_options), original_circuit_options = original_args
 
-        return task, outputs, compute_legacy_return_signal
+          # FIXME: allow calling a Step task without the Binary decision (in Activity::TaskAdapter).
+          nested_activity, _ = @nested_activity_decider.([ctx, flow_options], **original_circuit_options) # no TaskWrap::Runner because we shall not trace!
+
+          new_flow_options = flow_options.merge(
+            decision: nested_activity
+          )
+
+          return wrap_ctx, [[ctx, new_flow_options], original_circuit_options]
+        end
       end
 
-      # Go through the list of all possible nested activities and compile the total sum of possible outputs.
-      # FIXME: WHAT IF WE HAVE TWO IDENTICALLY NAMED OUTPUTS?
-      # @private
-      def self.outputs_for(activities)
-        activities.map do |activity|
-          Activity::Railway.Subprocess(activity)[:outputs]
-        end.inject(:merge)
+      # Dynamic is without auto_wire where we don't even know what *could* be the actual
+      # nested activity until it's runtime.
+      def self.Dynamic(decider, id:)
+        _task = Class.new(Macro::Nested) do
+          step task: Dynamic.method(:call_dynamic_nested_activity),
+               id:   :call_dynamic_nested_activity
+        end
       end
 
       class Dynamic
-        def initialize(nested_activity_decider)
-          @nested_activity_decider = Trailblazer::Option(nested_activity_decider)
-        end
+        SUCCESS_SEMANTICS = [:success, :pass_fast] # TODO: make this injectable/or get it from operation.
 
-        # TaskWrap step.
-        def call(wrap_ctx, original_args)
-          (ctx, _), original_circuit_options = original_args
+        def self.call_dynamic_nested_activity((ctx, flow_options), runner:, **circuit_options)
+          nested_activity       = flow_options[:decision]
+          original_flow_options = flow_options.slice(*(flow_options.keys - [:decision]))
 
-          # TODO: evaluate the option to get the actual "object" to call.
-          activity = @nested_activity_decider.(ctx, keyword_arguments: ctx.to_hash, **original_circuit_options)
+          host_activity = Dynamic.host_activity_for(activity: nested_activity)
 
-          # Overwrite :task so task_wrap.call_task will call this activity.
-          # This is a taskWrap trick so we don't have to repeat logic from #call_task here.
-          wrap_ctx[:task] = activity
+          # TODO: make activity here that has only one step (plus In and Out config) which is {nested_activity}
 
-          return wrap_ctx, original_args
+          return_signal, (ctx, flow_options) = runner.(
+            nested_activity,
+            [ctx, original_flow_options], # pass {flow_options} without a {:decision}.
+            runner:   runner,
+            **circuit_options,
+            activity: host_activity
+          )
+
+          return compute_legacy_return_signal(return_signal), [ctx, flow_options]
+        end
+
+        def self.compute_legacy_return_signal(return_signal)
+          actual_semantic  = return_signal.to_h[:semantic]
+          applied_signal   = SUCCESS_SEMANTICS.include?(actual_semantic) ? Activity::Right : Activity::Left # TODO: we could also provide PassFast/FailFast.
         end
 
-        # TODO: remove me when we make {:auto_wire} mandatory.
-        class ComputeLegacyReturnSignal
-          SUCCESS_SEMANTICS = [:success, :pass_fast] # TODO: make this injectable/or get it from operation.
+        # This is used in Nested and Each where some tasks don't have a corresponding, hard-wired
+        # activity. This is needed for {TaskWrap.invoke} and the Debugging API in tracing.
+        # @private
+        def self.host_activity_for(activity:)
+          Activity::TaskWrap.container_activity_for(
+            activity,
+            nodes: [Trailblazer::Activity::NodeAttributes.new(activity.to_s, nil, activity)],
+          )
+        end
 
-          def initialize(outputs)
-            @outputs = outputs # not needed for auto_wire!
+      end
+
+      # Code to handle [:auto_wire]. This is called "static" as you configure the possible activities at
+      # compile-time. This is the recommended way.
+      #
+      # TODO: allow configuring Output of Nested per internal nested activity, e.g.
+      #         step Nested(.., Id3Tag => {Output(:invalid_metadata) => ...}
+      #       this will help when semantics overlap.
+      #
+      def self.Static(decider, id:, auto_wire:)
+        decider_outputs = auto_wire.collect do |activity|
+          [Activity::Railway.Output(activity, "decision:#{activity}"), Activity::Railway.Track(activity)]
+        end.to_h
+
+        _task = Class.new(Macro::Nested) do
+          step(
+            {
+              task: Static.method(:return_route_signal),
+              id:   :route_to_nested_activity, # returns the {nested_activity} signal
+            }.merge(decider_outputs)
+          )
+
+          auto_wire.each do |activity|
+            activity_step = Subprocess(activity)
+
+            outputs = activity_step[:outputs]
+
+            # TODO: detect if we have two identical "special" termini.
+            output_wirings = outputs.collect do |semantic, output|
+              [Output(semantic), End(semantic)] # this will add a new termins to this activity.
+            end.to_h
+
+            # Each nested activity is a Subprocess.
+            # They have Output(semantic) => End(semantic) for each of their termini.
+            step activity_step,
+              {magnetic_to: activity}.merge(output_wirings)
+              # failure and success are wired to respective termini of {nesting_activity}.
           end
+        end
+      end
 
-          def call(wrap_ctx, original_args)
-            actual_semantic  = wrap_ctx[:return_signal].to_h[:semantic]
-            applied_semantic = SUCCESS_SEMANTICS.include?(actual_semantic) ? :success : :failure
+      module Static
+        def self.return_route_signal((ctx, flow_options), **circuit_options)
+          nested_activity = flow_options[:decision] # we use the decision class as a signal.
 
-            wrap_ctx[:return_signal] = @outputs.fetch(applied_semantic).signal
+          original_flow_options = flow_options.slice(*(flow_options.keys - [:decision]))
 
-            return wrap_ctx, original_args
-          end
-        end # ComputeLegacyReturnSignal
+          return nested_activity, [ctx, original_flow_options]
+        end
       end
-    end
+
+    end # Nested
   end
 end

data/lib/trailblazer/macro/rescue.rb

@@ -1,3 +1,5 @@
+require "securerandom"
+
 module Trailblazer
   module Macro
     NoopHandler = lambda { |*| }

data/lib/trailblazer/macro/strategy.rb

@@ -0,0 +1,32 @@
+module Trailblazer
+  module Macro
+    # {Macro::Strategy} always keeps a {block_activity} and has to define a `#call` method per macro type.
+    class Strategy # We want to look like a real {Linear::Strategy}.
+      class << self
+        extend Forwardable
+        def_delegators :block_activity, :step, :pass, :fail # TODO: add all DSL::Helper
+      end
+
+      # This makes {Wrap} look like {block_activity}.
+      def self.to_h
+        block_activity.to_h
+      end
+
+      def self.block_activity
+        @state.get(:block_activity)
+      end
+
+      # DISCUSS: move this to Linear::Strategy.
+      module State
+        def initialize!(state)
+          @state = state
+        end
+
+        def inherited(inheritor)
+          super
+          inheritor.initialize!(@state.copy)
+        end
+      end
+    end
+  end
+end

data/lib/trailblazer/macro/version.rb

@@ -1,7 +1,7 @@
 module Trailblazer
   module Version
     module Macro
-      VERSION = "2.1.11"
+      VERSION = "2.1.12"
     end
   end
 end