trailblazer-activity-dsl-linear 1.0.0 → 1.2.0

data/lib/trailblazer/activity/dsl/linear/feature/variable_mapping/runtime.rb

@@ -0,0 +1,276 @@
+module Trailblazer
+  class Activity
+    module DSL::Linear
+      module VariableMapping
+        module_function
+
+        # Runtime classes
+
+        # These objects are created via the DSL, keep all i/o steps in a Pipeline
+        # and run the latter when being `call`ed.
+        module Pipe
+          class Input
+            def initialize(pipe, id: :vm_original_ctx)
+              @pipe = pipe
+              @id   = id
+            end
+
+            def call(wrap_ctx, original_args)
+              (original_ctx, original_flow_options), original_circuit_options = original_args
+
+              # let user compute new ctx for the wrapped task.
+              pipe_ctx, _       = @pipe.({original_ctx: original_ctx, aggregate: {}}, original_args)
+              ctx_from_input    = pipe_ctx[:input_ctx]
+
+              wrap_ctx = wrap_ctx.merge(@id => original_ctx) # remember the original ctx under the key {@id}.
+
+              # instead of the original Context, pass on the filtered `ctx_from_input` in the wrap.
+              return wrap_ctx, [[ctx_from_input, original_flow_options], original_circuit_options]
+            end
+          end
+
+          # API in VariableMapping::Output:
+          #   output_ctx = @filter.(returned_ctx, [original_ctx, returned_flow_options], **original_circuit_options)
+          # Returns {output_ctx} that is used after taskWrap finished.
+          class Output < Input
+            def call(wrap_ctx, original_args)
+              returned_ctx, returned_flow_options = wrap_ctx[:return_args]  # this is the Context returned from {call}ing the wrapped user task.
+              original_ctx                        = wrap_ctx[@id]           # grab the original ctx from before which was set in the {:input} filter.
+              _, original_circuit_options         = original_args
+
+              # let user compute the output.
+              pipe_ctx, _     = @pipe.({original_ctx: original_ctx, returned_ctx: returned_ctx, aggregate: {}}, [[original_ctx, returned_flow_options], original_circuit_options])
+              ctx_from_output = pipe_ctx[:aggregate]
+
+              wrap_ctx = wrap_ctx.merge(return_args: [ctx_from_output, returned_flow_options]) # DISCUSS: this won't allow tracing in the taskWrap as we're returning {returned_flow_options} from above.
+
+              return wrap_ctx, original_args
+            end
+          end
+        end
+
+        # Merge all original ctx variables into the new input_ctx.
+        # This happens when no {:input} is provided.
+        def default_input_ctx(wrap_ctx, original_args)
+          default_ctx = wrap_ctx[:original_ctx]
+
+          merge_variables(default_ctx, wrap_ctx, original_args)
+        end
+
+        # Write one particular variable to the {aggregate} using {aggregate[:name] = (value)}.
+        #
+        # This is much faster than merging a hash, and provides better overriding semantics. (to be done!)
+        #
+        # @param filter Any circuit-step compatible callable that exposes {#call(args, **circuit_options)}
+        #   and returns [value, new_ctx]
+        #
+
+        # Filter
+        class VariableFromCtx
+          def initialize(variable_name:)
+            @variable_name = variable_name
+          end
+
+          # Grab @variable_name from {ctx}.
+          def call((ctx, _), **) # Circuit-step interface
+            return ctx[@variable_name], ctx
+          end
+        end
+
+        # Filter
+        class VariablePresent < VariableFromCtx
+          # Grab @variable_name from {ctx} if it's there.
+          def call((ctx, _), **) # Circuit-step interface
+            return ctx.key?(@variable_name), ctx
+          end
+        end
+
+        # TODO: * ALL FILTERS and conditions expose circuit-step interface.
+        # @param name Identifier for the pipeline
+        # Call {user_filter} and set return value as variable on aggregate.
+        class SetVariable
+          def initialize(write_name:, filter:, user_filter:, name:, **)
+            @write_name  = write_name
+            @filter      = filter
+            @name        = name
+          end
+
+          attr_reader :name # TODO: used when adding to pipeline, change to to_h
+
+          def call(wrap_ctx, original_args, filter = @filter)
+            wrap_ctx = self.class.set_variable_for_filter(filter, @write_name, wrap_ctx, original_args)
+
+            return wrap_ctx, original_args
+          end
+
+          def self.set_variable_for_filter(filter, write_name, wrap_ctx, original_args)
+            value     = call_filter(filter, wrap_ctx, original_args)
+            wrap_ctx  = set_variable(value, write_name, wrap_ctx, original_args)
+
+            wrap_ctx
+          end
+
+          # Call a filter with a Circuit-Step interface.
+          def self.call_filter(filter, wrap_ctx, (args, circuit_options))
+            value, _ = filter.(args, **circuit_options) # circuit-step interface
+            value
+          end
+
+          def self.set_variable(value, write_name, wrap_ctx, original_args)
+            wrap_ctx[:aggregate][write_name] = value # yes, we're mutating, but this is ok as we're on some private hash.
+            wrap_ctx # DISCUSS: could be omitted.
+          end
+
+          # Set variable on ctx if {condition} is true.
+          class Conditioned < SetVariable
+            def initialize(condition:, **options)
+              super(**options)
+
+              @condition = condition # DISCUSS: adding this as an "optional" step in a "Railway"
+            end
+
+            def call(wrap_ctx, original_args)
+              decision, _ = SetVariable.call_filter(@condition, wrap_ctx, original_args)
+
+              return super if decision
+              return wrap_ctx, original_args
+            end
+          end
+
+          # Set variable on ctx if {condition} is true.
+          # Otherwise, set default_filter variable on ctx.
+          class Default < SetVariable
+            def initialize(default_filter:, condition:, **options)
+              super(**options)
+
+              @default_filter = default_filter
+              @condition      = condition
+            end
+
+            def call(wrap_ctx, original_args)
+              # FIXME: redundant with Conditioned.
+              decision, _ = SetVariable.call_filter(@condition, wrap_ctx, original_args)
+
+              filter = decision ? @filter : @default_filter
+
+              super(wrap_ctx, original_args, filter)
+            end
+          end # Default
+
+          # TODO: we don't have Out(:variable), yet!
+          class Output < SetVariable
+            # Call a filter with a Circuit-Step interface.
+            def self.call_filter(filter, wrap_ctx, original_args)
+              new_ctx = wrap_ctx[:returned_ctx]
+
+              call_filter_with_ctx(filter, new_ctx, wrap_ctx, original_args)
+            end
+
+            def self.call_filter_with_ctx(filter, ctx, wrap_ctx, ((_, flow_options), circuit_options))
+              SetVariable.call_filter(filter, wrap_ctx, [[ctx, flow_options], circuit_options])
+            end
+          end
+
+          # Do everything SetVariable does but read from {aggregate}, not from {ctx}.
+          # TODO: it would be cool to have this also for AddVariables.
+          class ReadFromAggregate < SetVariable
+            def self.call_filter(filter, wrap_ctx, original_args)
+              new_ctx = wrap_ctx[:aggregate]
+
+              Output.call_filter_with_ctx(filter, new_ctx, wrap_ctx, original_args)
+            end
+          end
+
+          # @private
+          # Always deletes from {:aggregate}.
+          class Delete < SetVariable
+            def call(wrap_ctx, original_args)
+              wrap_ctx[:aggregate].delete(@write_name) # FIXME: we're mutating a hash here!
+
+              return wrap_ctx, original_args
+            end
+          end
+        end # SetVariable
+
+        # AddVariables: I call something with an Option-interface and run the return value through merge_variables().
+        # works on {:aggregate} by (usually) producing a hash fragment that is merged with the existing {:aggregate}
+
+        # Add a hash of variables to aggregate after running a filter (which returns a hash!).
+        # Note that we only use those for "old-style" callables that produce hashes.
+        class AddVariables < SetVariable
+          def self.set_variable(variables, write_name, wrap_ctx, original_args)
+            wrap_ctx, _ = VariableMapping.merge_variables(variables, wrap_ctx, original_args)
+            wrap_ctx
+          end
+
+          # Merge hash of Out into aggregate.
+          # TODO: deprecate and remove.
+          class Output < SetVariable::Output
+            def self.set_variable(*args)
+              AddVariables.set_variable(*args)
+            end
+
+            # Pass {inner_ctx, outer_ctx, **inner_ctx}
+            class WithOuterContext_Deprecated < Output
+              def self.call_filter(filter, wrap_ctx, ((original_ctx, _), circuit_options))
+                new_ctx = wrap_ctx[:returned_ctx] # FIXME: redundant.
+
+                # Here, due to a stupid API decision, we have to call an Option with two positional args.
+                filter.(new_ctx, original_ctx, keyword_arguments: new_ctx.to_hash, **circuit_options)
+              end
+            end
+
+            class WithOuterContext < Output
+              def self.call_filter(filter, wrap_ctx, ((original_ctx, flow_options), circuit_options))
+                new_ctx = wrap_ctx[:returned_ctx]
+                new_ctx = new_ctx.merge(outer_ctx: original_ctx)
+
+                Output.call_filter_with_ctx(filter, new_ctx, wrap_ctx, [[original_ctx, flow_options], circuit_options])
+              end
+            end
+          end
+        end
+
+        def merge_variables(variables, wrap_ctx, original_args, receiver = wrap_ctx[:aggregate])
+          wrap_ctx[:aggregate] = receiver.merge(variables)
+
+          return wrap_ctx, original_args
+        end
+
+        # Finally, create a new input ctx from all the
+        # collected input variables.
+        # This goes into the step/nested OP.
+        def scope(wrap_ctx, original_args)
+          ((_, flow_options), _) = original_args
+
+          # this is the actual context passed into the step.
+          wrap_ctx[:input_ctx] = Trailblazer::Context(
+            wrap_ctx[:aggregate],
+            {}, # mutable variables
+            flow_options[:context_options]
+          )
+
+          return wrap_ctx, original_args
+        end
+
+        # @private
+        # The default {:output} filter only returns the "mutable" part of the inner ctx.
+        # This means only variables added using {inner_ctx[..]=} are merged on the outside.
+        def default_output_ctx(wrap_ctx, original_args)
+          new_ctx = wrap_ctx[:returned_ctx]
+
+          _wrapped, mutable = new_ctx.decompose # `_wrapped` is what the `:input` filter returned, `mutable` is what the task wrote to `scoped`.
+
+          merge_variables(mutable, wrap_ctx, original_args)
+        end
+
+        def merge_with_original(wrap_ctx, original_args)
+          original_ctx     = wrap_ctx[:original_ctx]  # outer ctx
+          output_variables = wrap_ctx[:aggregate]
+
+          merge_variables(output_variables, wrap_ctx, original_args, original_ctx)
+        end
+      end # VariableMapping
+    end
+  end
+end

data/lib/trailblazer/activity/dsl/linear/feature/variable_mapping.rb

@@ -5,11 +5,10 @@ module Trailblazer
         # Normalizer-steps to implement {:input} and {:output}
         # Returns an Extension instance to be thrown into the `step` DSL arguments.
         def self.VariableMapping(input_id: "task_wrap.input", output_id: "task_wrap.output", **options)
-          input, output, normalizer_options, non_symbol_options = VariableMapping.merge_instructions_from_dsl(**options)
+          input, output = VariableMapping.merge_instructions_from_dsl(**options)
+          extension     = VariableMapping.Extension(input, output)
 
-          extension = VariableMapping.Extension(input, output)
-
-          return TaskWrap::Extension::WrapStatic.new(extension: extension), normalizer_options, non_symbol_options
+          TaskWrap::Extension::WrapStatic.new(extension: extension)
         end
 
         module VariableMapping
@@ -20,9 +19,10 @@ module Trailblazer
                 normalizer,
                 "activity.wirings",
                 {
-                   # In(), Out(), {:input}, Inject() feature
-                  "activity.normalize_input_output_filters" => Linear::Normalizer.Task(VariableMapping::Normalizer.method(:normalize_input_output_filters)),
-                  "activity.input_output_dsl"               => Linear::Normalizer.Task(VariableMapping::Normalizer.method(:input_output_dsl)),
+                  # In(), Out(), {:input}, Inject() feature
+                  "activity.convert_symbol_options"           => Linear::Normalizer.Task(VariableMapping::Normalizer.method(:convert_symbol_options)),
+                  "activity.normalize_input_output_filters"   => Linear::Normalizer.Task(VariableMapping::Normalizer.method(:normalize_input_output_filters)),
+                  "activity.input_output_dsl"                 => Linear::Normalizer.Task(VariableMapping::Normalizer.method(:input_output_dsl)),
                 }
               )
             end
@@ -37,259 +37,103 @@ module Trailblazer
 
           # Steps that are added to the DSL normalizer.
           module Normalizer
-            # Process {In() => [:model], Inject() => [:current_user], Out() => [:model]}
-            def self.normalize_input_output_filters(ctx, non_symbol_options:, **)
-              input_exts  = non_symbol_options.find_all { |k,v| k.is_a?(VariableMapping::DSL::In) }
-              output_exts = non_symbol_options.find_all { |k,v| k.is_a?(VariableMapping::DSL::Out) }
-              inject_exts = non_symbol_options.find_all { |k,v| k.is_a?(VariableMapping::DSL::Inject) }
-
-              return unless input_exts.any? || output_exts.any? || inject_exts.any?
-
-              ctx[:inject_filters] = inject_exts
-              ctx[:in_filters]     = input_exts
-              ctx[:out_filters]    = output_exts
-            end
-
-            def self.input_output_dsl(ctx, extensions: [], **options)
-              # no :input/:output/:inject/Input()/Output() passed.
-              return if (options.keys & [:input, :output, :inject, :inject_filters, :in_filters, :output_filters]).empty?
-
-              extension, normalizer_options, non_symbol_options = Linear.VariableMapping(**options)
-
-              ctx[:extensions] = extensions + [extension] # FIXME: allow {Extension() => extension}
-              ctx.merge!(**normalizer_options) # DISCUSS: is there another way of merging variables into ctx?
-              ctx[:non_symbol_options].merge!(non_symbol_options)
-            end
-          end
-
-          module_function
-
-          # For the input filter we
-          #   1. create a separate {Pipeline} instance {pipe}. Depending on the user's options, this might have up to four steps.
-          #   2. The {pipe} is run in a lamdba {input}, the lambda returns the pipe's ctx[:input_ctx].
-          #   3. The {input} filter in turn is wrapped into an {Activity::TaskWrap::Input} object via {#merge_instructions_for}.
-          #   4. The {TaskWrap::Input} instance is then finally placed into the taskWrap as {"task_wrap.input"}.
-          #
-          # @private
-          #
-
-            # default_input
-          #  <or>
-            # oldway
-            #   :input
-            #   :inject
-            # newway(initial_input_pipeline)
-            #   In,Inject
-          # => input_pipe
-          def merge_instructions_from_dsl(**options)
-            # The overriding {:input} option is set.
-            pipeline, has_mono_options, _ = DSL.pipe_for_mono_input(**options)
-
-            if ! has_mono_options
-              pipeline = DSL.pipe_for_composable_input(**options)  # FIXME: rename filters consistently
-            end
-
-            # gets wrapped by {VariableMapping::Input} and called there.
-            # API: @filter.([ctx, original_flow_options], **original_circuit_options)
-            # input = Trailblazer::Option(->(original_ctx, **) {  })
-            input  = Pipe::Input.new(pipeline)
-
-
-            output_pipeline, has_mono_options, _ = DSL.pipe_for_mono_output(**options)
-
-            if ! has_mono_options
-              output_pipeline = DSL.pipe_for_composable_output(**options)
-            end
-
-            output = Pipe::Output.new(output_pipeline)
+            # TODO: remove me once {:input} API is removed.
+            # Convert {:input}, {:output} and {:inject} to In() and friends.
+            def self.convert_symbol_options(ctx, non_symbol_options:, output_with_outer_ctx: nil, **)
+              input, output, inject = ctx.delete(:input), ctx.delete(:output), ctx.delete(:inject)
+              return unless input || output || inject
 
-            return input, output,
-              # normalizer_options:
-              {
-                variable_mapping_pipelines: [pipeline, output_pipeline],
-              },
-              # non_symbol_options:
-              {
-                Linear::Strategy.DataVariable() => :variable_mapping_pipelines # we want to store {:variable_mapping_pipelines} in {Row.data} for later reference.
-              }
-              # DISCUSS: should we remember the pure pipelines or get it from the compiled extension?
-              # store pipe in the extension (via TW::Extension.data)?
-          end
+              dsl_options = {}
 
-# < AddVariables
-#   Option
-#     filter
-#   merge_variables
+              # TODO: warn, deprecate etc
+              dsl_options.merge!(VariableMapping::DSL.In() => input) if input
 
-          # Runtime classes
-          Filter = Struct.new(:aggregate_step, :filter, :name, :add_variables_class)
+              if output
+                options = {}
+                options = options.merge(with_outer_ctx: output_with_outer_ctx) unless output_with_outer_ctx.nil?
 
-          # These objects are created via the DSL, keep all i/o steps in a Pipeline
-          # and run the latter when being `call`ed.
-          module Pipe
-            class Input
-              def initialize(pipe, id: :vm_original_ctx)
-                @pipe = pipe
-                @id   = id # DISCUSS: untested.
+                dsl_options.merge!(VariableMapping::DSL.Out(**options) => output)
               end
 
-              def call(wrap_ctx, original_args)
-                (original_ctx, original_flow_options), original_circuit_options = original_args
-
-                # let user compute new ctx for the wrapped task.
-                pipe_ctx, _ = @pipe.({original_ctx: original_ctx}, [[original_ctx, original_flow_options], original_circuit_options])
-                input_ctx   = pipe_ctx[:input_ctx]
-
-                wrap_ctx = wrap_ctx.merge(@id => original_ctx) # remember the original ctx under the key {:vm_original_ctx}.
+              if inject
+                inject.collect do |filter|
+                  filter = filter.is_a?(Symbol) ? [filter] : filter
 
-                # instead of the original Context, pass on the filtered `input_ctx` in the wrap.
-                return wrap_ctx, [[input_ctx, original_flow_options], original_circuit_options]
+                  dsl_options.merge!(VariableMapping::DSL.Inject() => filter)
+                end
               end
-            end
-
-            # API in VariableMapping::Output:
-            #   output_ctx = @filter.(returned_ctx, [original_ctx, returned_flow_options], **original_circuit_options)
-            # Returns {output_ctx} that is used after taskWrap finished.
-            class Output < Input
-              # def call(returned_ctx, (original_ctx, returned_flow_options), **original_circuit_options)
-                def call(wrap_ctx, original_args)
-                  returned_ctx, returned_flow_options = wrap_ctx[:return_args]  # this is the Context returned from {call}ing the wrapped user task.
-                  original_ctx                        = wrap_ctx[@id]           # grab the original ctx from before which was set in the {:input} filter.
-                  _, original_circuit_options         = original_args
-
-                # let user compute the output.
-                pipe_ctx, _ = @pipe.({original_ctx: original_ctx, returned_ctx: returned_ctx}, [[original_ctx, returned_flow_options], original_circuit_options])
-
-                output_ctx  = pipe_ctx[:aggregate]
 
-                wrap_ctx = wrap_ctx.merge(return_args: [output_ctx, returned_flow_options]) # DISCUSS: this won't allow tracing in the taskWrap as we're returning {returned_flow_options} from above.
-
-                return wrap_ctx, original_args
-              end
+              ctx.merge!(
+                non_symbol_options:           non_symbol_options.merge(dsl_options),
+                input_output_inject_options:  [{input: input, output: output, inject: inject}, dsl_options], # yes, there were {:input} options.
+              )
             end
-          end
-
-# DISCUSS: improvable sections such as merge vs hash[]=
-          def initial_aggregate(wrap_ctx, original_args)
-            wrap_ctx = wrap_ctx.merge(aggregate: {})
 
-            return wrap_ctx, original_args
-          end
+            # Process {In() => [:model], Inject() => [:current_user], Out() => [:model]}
+            def self.normalize_input_output_filters(ctx, non_symbol_options:, input_output_inject_options: [], **)
+              in_exts     = non_symbol_options.find_all { |k, v| k.is_a?(VariableMapping::DSL::In) || k.is_a?(VariableMapping::DSL::Inject) }
+              output_exts = non_symbol_options.find_all { |k, v| k.is_a?(VariableMapping::DSL::Out) }
 
-          # Merge all original ctx variables into the new input_ctx.
-          # This happens when no {:input} is provided.
-          def default_input_ctx(wrap_ctx, original_args)
-            default_ctx = wrap_ctx[:original_ctx]
+              return unless in_exts.any? || output_exts.any?
 
-            merge_variables(default_ctx, wrap_ctx, original_args)
-          end
+              deprecate_input_output_inject_option(input_output_inject_options, in_exts, output_exts)
 
-          # Input/output Pipeline step that runs the user's {filter} and adds
-          # variables to the computed ctx.
-          #
-          # Basically implements {:input}.
-          #
-# AddVariables: I call something with an Option-interface and run the return value through merge_variables().
-          # works on {:aggregate} by (usually) producing a hash fragment that is merged with the existing {:aggregate}
-          class AddVariables
-            def initialize(filter, user_filter)
-              @filter      = filter # The users input/output filter.
-              @user_filter = user_filter # this is for introspection.
+              ctx[:in_filters]  = in_exts
+              ctx[:out_filters] = output_exts
             end
 
-            def call(wrap_ctx, original_args)
-              ((original_ctx, _), circuit_options) = original_args
-              # puts "@@@@@ #{wrap_ctx[:returned_ctx].inspect}"
+            def self.input_output_dsl(ctx, non_symbol_options:, in_filters: nil, out_filters: nil, **options)
+              # no :input/:output/:inject/Input()/Output() passed.
+              return unless in_filters || out_filters
 
-              # this is the actual logic.
-              variables = call_filter(wrap_ctx, original_ctx, circuit_options, original_args)
+              extension = Linear.VariableMapping(in_filters: in_filters, out_filters: out_filters, **options)
 
-              VariableMapping.merge_variables(variables, wrap_ctx, original_args)
-            end
+              record = Linear::Normalizer::Inherit.Record((in_filters + out_filters).to_h, type: :variable_mapping)
 
-            def call_filter(wrap_ctx, original_ctx, circuit_options, original_args)
-              _variables = @filter.(original_ctx, keyword_arguments: original_ctx.to_hash, **circuit_options)
-            end
+              non_symbol_options = non_symbol_options.merge(record)
+              non_symbol_options = non_symbol_options.merge(Linear::Strategy.Extension(is_generic: true)  => extension)
 
-            class ReadFromAggregate < AddVariables # FIXME: REFACTOR
-              def call_filter(wrap_ctx, original_ctx, circuit_options, original_args)
-                new_ctx = wrap_ctx[:aggregate]
-
-                _variables = @filter.(new_ctx, keyword_arguments: new_ctx.to_hash, **circuit_options)
-              end
+              ctx.merge!(
+                non_symbol_options: non_symbol_options
+              )
             end
 
-            class Output < AddVariables
-              def call_filter(wrap_ctx, original_ctx, circuit_options, original_args)
-                new_ctx = wrap_ctx[:returned_ctx]
-
-                @filter.(new_ctx, keyword_arguments: new_ctx.to_hash, **circuit_options)
-              end
+            # TODO: remove for TRB 2.2.
+            def self.deprecate_input_output_inject_option(input_output_inject_options, *composable_options)
+              return unless input_output_inject_options.any?
+              options, _dsl_options = input_output_inject_options
 
-              # Pass {inner_ctx, outer_ctx, **inner_ctx}
-              class WithOuterContext < Output
-                def call_filter(wrap_ctx, original_ctx, circuit_options, original_args)
-                  new_ctx = wrap_ctx[:returned_ctx]
-
-                  @filter.(new_ctx, original_ctx, keyword_arguments: new_ctx.to_hash, **circuit_options)
-                end
-              end
+              deprecated_options_count = options.find_all { |(name, option)| option }.count + (options[:inject] ? options[:inject].count - 1 : 0)
+              composable_options_count = composable_options.collect { |options| options.size }.sum
 
-              # Always deletes from {:aggregate}.
-              class Delete < AddVariables
-                def call(wrap_ctx, original_args)
-                  @filter.collect do |name|
-                    wrap_ctx[:aggregate].delete(name) # FIXME: we're mutating a hash here!
-                  end
+              return if composable_options_count == deprecated_options_count
 
-                  return wrap_ctx, original_args
-                end
-              end
+              Activity::Deprecate.warn Linear::Deprecate.dsl_caller_location, %(You are mixing #{options.inspect} with In(), Out() and Inject().\n#{VariableMapping.deprecation_link})
             end
           end
 
-          # Finally, create a new input ctx from all the
-          # collected input variables.
-          # This goes into the step/nested OP.
-          def scope(wrap_ctx, original_args)
-            ((_, flow_options), _) = original_args
-
-            # this is the actual context passed into the step.
-            wrap_ctx[:input_ctx] = Trailblazer::Context(
-              wrap_ctx[:aggregate],
-              {}, # mutable variables
-              flow_options[:context_options]
-            )
-
-            return wrap_ctx, original_args
-          end
-
-          # Last call in every step. Currently replaces {:input_ctx} by adding variables using {#merge}.
-          # DISCUSS: improve here?
-          def merge_variables(variables, wrap_ctx, original_args)
-            wrap_ctx[:aggregate] = wrap_ctx[:aggregate].merge(variables)
-
-            return wrap_ctx, original_args
-          end
+          module_function
 
+          # For the input filter we
+          #   1. create a separate {Pipeline} instance {pipe}. Depending on the user's options, this might have up to four steps.
+          #   2. The {pipe} is run in a lamdba {input}, the lambda returns the pipe's ctx[:input_ctx].
+          #   3. The {input} filter in turn is wrapped into an {Activity::TaskWrap::Input} object via {#merge_instructions_for}.
+          #   4. The {TaskWrap::Input} instance is then finally placed into the taskWrap as {"task_wrap.input"}.
+          #
           # @private
-          # The default {:output} filter only returns the "mutable" part of the inner ctx.
-          # This means only variables added using {inner_ctx[..]=} are merged on the outside.
-          def default_output_ctx(wrap_ctx, original_args)
-            new_ctx = wrap_ctx[:returned_ctx]
+          #
+          def merge_instructions_from_dsl(**options)
+            pipeline  = DSL.pipe_for_composable_input(**options)  # FIXME: rename filters consistently
+            input     = Pipe::Input.new(pipeline)
 
-            _wrapped, mutable = new_ctx.decompose # `_wrapped` is what the `:input` filter returned, `mutable` is what the task wrote to `scoped`.
+            output_pipeline = DSL.pipe_for_composable_output(**options)
+            output          = Pipe::Output.new(output_pipeline)
 
-            merge_variables(mutable, wrap_ctx, original_args)
+            return input, output
           end
 
-          def merge_with_original(wrap_ctx, original_args)
-            original_ctx     = wrap_ctx[:original_ctx]  # outer ctx
-            output_variables = wrap_ctx[:aggregate]
-
-            wrap_ctx[:aggregate] = original_ctx.merge(output_variables) # FIXME: use merge_variables()
-            # pp wrap_ctx
-            return wrap_ctx, original_args
+          def deprecation_link
+            %(Please refer to https://trailblazer.to/2.1/docs/activity.html#activity-variable-mapping-deprecation-notes and have a nice day.)
           end
         end # VariableMapping
       end