trailblazer-activity-dsl-linear 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91482f9f8f3191ea94fccb525e24e55b95edb1f089ee24dd7748364af140476b
-  data.tar.gz: f85598f3e6796e6df4aa6a3927654dc882dae26e2e8c39eff4ea2b4a86db98f7
+  metadata.gz: 87302630d03df0e0e40ad7e7b9902744a1b9d7586e157018eab7652c6ad7276c
+  data.tar.gz: 10a821885b6a9e4228a0e04545d28689d28f4d3470f74b5f597f6d9bc1b4dd50
 SHA512:
-  metadata.gz: 88644ff777e10df4e7e6337742f4684e487bdac3e2899d5168f9f4769563171c68638608b2d3de495b66467d9046c2d3f2c12c94ebd4d046c9ec66bbb364cce6
-  data.tar.gz: 53279e4799c2e08909e4a60e55a139c8455faf1d12b8f2fa78a5c80eef6446981e5468e0f962569be1538ce87a4567aef3ef271923be56e8cb17a83ae11610c9
+  metadata.gz: '08a071547063505433e4400c7f5e23c8203c72f125397bf71af8402050d728e1e5995fc71f5cd23a8da362c277bedb16a71e9d4f0b5f1c439d96eed82c4589fc'
+  data.tar.gz: 11e54d0175baa4fa338605faf1ac44ef1ef891a763890730c44119a239f11ea2f37497c80156bc2895a11b7b0a6ce58e9349e4a44e49f90c3dc48535ff179b57

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', 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,31 @@
+# 1.1.0
+
+* Use `trailblazer-activity` 0.15.0.
+* Remove `Path::DSL.OptionsForSequenceBuilder` and move concrete code to `Path::DSL.options_for_sequence_build`
+  which returns a set:
+
+  1. default termini instructions for the concrete strategy
+  2. options specific for this strategy subclass.
+
+  Everything else, such as merging user options, computing and adding termini, etc, now happens in
+  `Strategy::DSL.OptionsForSequenceBuilder`.
+* Adding `Subprocess(Create, strict: true)` to wire all outputs of `Create` automatically.
+  Each output will be wired to its same named Track(semantic).
+* Adding `Strategy(termini: )`
+* For `output:` in combination with `:output_with_outer_ctx`, deprecate the second positional argument and make it
+  the `:outer_ctx` keyword argument instead.
+* Introduce `Linear.Patch` as the public entry point for patching activities.
+* Remove `Runtime.initial_aggregate` step for the input and output pipelines which results in slightly better runtime performance and less code.
+
+## Variable Mapping
+
+* Simplify the architecture in `VariableMapping`, filters are now added directly into the `Pipeline`.
+  Performance increase from 17k to 25k from 1.0.0 to this version.
+* Introduce `Inject(:variable)` to supersede the version receiving a big mapping hash.
+* Add `Inject(:variable, override: true)` to always write a variable to ctx, regardless of its presence.
+* Fix a bug where `Inject()` would override `In()` filters even though the latter was added latest. This
+  is fixed by treating both filter types equally and in the order they were added by the user (and the macro).
+
 # 1.0.0
 
 ## Additions

data/Gemfile

@@ -5,11 +5,11 @@ gemspec
 
 gem "minitest-line"
 
-gem "rubocop", require: false
-
-gem "trailblazer-developer", path: "../trailblazer-developer"
+# gem "trailblazer-developer", path: "../trailblazer-developer"
 # gem "trailblazer-developer", github: "trailblazer/trailblazer-developer"
 # gem "trailblazer-declarative", path: "../trailblazer-declarative"
 # gem "trailblazer-activity", path: "../trailblazer-activity"
 # gem "trailblazer-activity", github: "trailblazer/trailblazer-activity"
 # gem "trailblazer-activity", path: "../circuit"
+gem "benchmark-ips"
+# gem "trailblazer-core-utils", path: "../trailblazer-core-utils"

data/Rakefile

@@ -4,7 +4,7 @@ require "rake/testtask"
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
   t.libs << "lib"
-  t.test_files = FileList["test/**/*_test.rb"]
+  t.test_files = FileList["test/**/*_test.rb"] - FileList["test/docs/autogenerated/*"]
 end
 
 task :default => :test

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

@@ -1,6 +1,10 @@
 class Trailblazer::Activity
   module DSL
     module Linear
+      def self.Patch(activity, instructions)
+        Patch.customize(activity, options: instructions)
+      end
+
       module Patch
       # DISCUSS: we could make this a generic DSL option, not just for Subprocess().
         # Currently, this is called from the Subprocess() helper.
@@ -21,7 +25,7 @@ class Trailblazer::Activity
 
           patch =
             if task_id
-              segment_activity = Introspect::Graph(activity).find(task_id).task
+              segment_activity = Introspect::TaskMap(activity).find_by_id(task_id).task
               patched_segment_activity = call(segment_activity, path, customization)
 
               # Replace the patched subprocess.

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

@@ -10,39 +10,17 @@ module Trailblazer
           module DSL
             module_function
 
-            # Compute pipeline for {:input} option.
-            def pipe_for_mono_input(input: [], inject: [], in_filters: [], output: [], **)
-              has_input              = Array(input).any?
-              has_mono_options       = has_input || Array(inject).any? || Array(output).any? # :input, :inject and :output are "mono options".
-              has_composable_options = in_filters.any? # DISCUSS: why are we not testing Inject()?
-
-              if has_mono_options && has_composable_options
-                warn "[Trailblazer] You are mixing `:input` and `In() => ...`. `In()` and Inject () options are ignored and `:input` wins: #{input} #{inject} #{output} <> #{in_filters} / "
-              end
-
-              pipeline = initial_input_pipeline(add_default_ctx: !has_input)
-              pipeline = add_steps_for_input_option(pipeline, input: input)
-              pipeline = add_steps_for_inject_option(pipeline, inject: inject)
-
-              return pipeline, has_mono_options, has_composable_options
-            end
-
             # Compute pipeline for In() and Inject().
             # We allow to inject {:initial_input_pipeline} here in order to skip creating a new input pipeline and instead
             # use the inherit one.
-            def pipe_for_composable_input(in_filters: [], inject_filters: [], initial_input_pipeline: initial_input_pipeline_for(in_filters), **)
-              inject_filters = DSL::Inject.filters_for_injects(inject_filters) # {Inject() => ...} the pure user input gets translated into AddVariable aggregate steps.
-              in_filters     = DSL::Tuple.filters_from_options(in_filters)
-
-              # With only injections defined, we do not filter out anything, we use the original ctx
-              # and _add_ defaulting for injected variables.
-              pipeline = add_filter_steps(initial_input_pipeline, in_filters)
-              pipeline = add_filter_steps(pipeline, inject_filters, path_prefix: "inject")
+            def pipe_for_composable_input(in_filters: [], initial_input_pipeline: initial_input_pipeline_for(in_filters), **)
+              in_filters  = DSL::Tuple.filters_from_options(in_filters)
+              pipeline    = add_filter_steps(initial_input_pipeline, in_filters)
             end
 
             # initial pipleline depending on whether or not we got any In() filters.
             def initial_input_pipeline_for(in_filters)
-              is_inject_only = Array(in_filters).empty?
+              is_inject_only = in_filters.find { |k, v| k.is_a?(VariableMapping::DSL::In) }.nil?
 
               initial_input_pipeline(add_default_ctx: is_inject_only)
             end
@@ -57,7 +35,6 @@ module Trailblazer
 
               pipe = Activity::TaskWrap::Pipeline.new(
                 [
-                  Activity::TaskWrap::Pipeline.Row("input.init_hash", VariableMapping.method(:initial_aggregate)), # very first step
                   default_ctx_row,
                   Activity::TaskWrap::Pipeline.Row("input.scope",     VariableMapping.method(:scope)), # last step
                 ].compact
@@ -70,36 +47,12 @@ module Trailblazer
 
               # Handle {:input} and {:inject} option, the "old" interface.
             def add_steps_for_input_option(pipeline, input:)
-              tuple         = DSL.In(name: ":input") # simulate {In() => input}
+              tuple         = DSL.In() # simulate {In() => input}
               input_filter  = DSL::Tuple.filters_from_options([[tuple, input]])
 
               add_filter_steps(pipeline, input_filter)
             end
 
-
-            def pipe_for_mono_output(output_with_outer_ctx: false, output: [], out_filters: [], **)
-              # No Out(), no {:output} will result in a default_output_ctx step.
-              has_output             = Array(output).any?
-              has_mono_options       = has_output
-              has_composable_options = Array(out_filters).any?
-
-              if has_mono_options && has_composable_options
-                warn "[Trailblazer] You are mixing `:output` and `Out() => ...`. `Out()` options are ignored and `:output` wins."
-              end
-
-              pipeline = initial_output_pipeline(add_default_ctx: !has_output)
-              pipeline = add_steps_for_output_option(pipeline, output: output, output_with_outer_ctx: output_with_outer_ctx)
-
-              return pipeline, has_mono_options, has_composable_options
-            end
-
-            def add_steps_for_output_option(pipeline, output:, output_with_outer_ctx:)
-              tuple         = DSL.Out(name: ":output", with_outer_ctx: output_with_outer_ctx) # simulate {Out() => output}
-              output_filter = DSL::Tuple.filters_from_options([[tuple, output]])
-
-              add_filter_steps(pipeline, output_filter, prepend_to: "output.merge_with_original", path_prefix: "output")
-            end
-
             def pipe_for_composable_output(out_filters: [], initial_output_pipeline: initial_output_pipeline(add_default_ctx: Array(out_filters).empty?), **)
               out_filters = DSL::Tuple.filters_from_options(out_filters)
 
@@ -112,7 +65,6 @@ module Trailblazer
 
               Activity::TaskWrap::Pipeline.new(
                 [
-                  Activity::TaskWrap::Pipeline.Row("output.init_hash", VariableMapping.method(:initial_aggregate)), # very first step
                   default_ctx_row,
                   Activity::TaskWrap::Pipeline.Row("output.merge_with_original", VariableMapping.method(:merge_with_original)), # last step
                 ].compact
@@ -123,14 +75,6 @@ module Trailblazer
               ["output.default_output", VariableMapping.method(:default_output_ctx)]
             end
 
-            def add_steps_for_inject_option(pipeline, inject:)
-              injects = inject.collect { |name| name.is_a?(Symbol) ? [DSL.Inject(), [name]] : [DSL.Inject(), name] }
-
-              tuples  = DSL::Inject.filters_for_injects(injects) # DISCUSS: should we add passthrough/defaulting here at Inject()-time?
-
-              add_filter_steps(pipeline, tuples, path_prefix: "inject")
-            end
-
             def add_filter_steps(pipeline, rows, prepend_to: "input.scope", path_prefix: "input")
               rows = add_variables_steps_for_filters(rows, path_prefix: path_prefix)
 
@@ -145,48 +89,10 @@ module Trailblazer
             # @param filters [Array] List of {Filter} objects
             def add_variables_steps_for_filters(filters, path_prefix:)
               filters.collect do |filter|
-                ["#{path_prefix}.add_variables.#{filter.name}", filter.aggregate_step] # FIXME: config name sucks, of course, if we want to allow inserting etc.
-              end
-            end
-
-
-          # Filter code
-            # Converting user options to callable filters.
-
-            # @param [Array, Hash, Proc] User option coming from the DSL, like {[:model]}
-            #
-            # Returns a "filter interface" callable that's invoked in {AddVariables}:
-            #   filter.(new_ctx, ..., keyword_arguments: new_ctx.to_hash, **circuit_options)
-            def self.build_filter(user_filter)
-              Trailblazer::Option(filter_for(user_filter))
-            end
-
-            # Convert a user option such as {[:model]} to a filter.
-            #
-            # Returns a filter proc to be called in an Option.
-            # @private
-            def self.filter_for(filter)
-              if filter.is_a?(::Array) || filter.is_a?(::Hash)
-                filter_from_dsl(filter)
-              else
-                filter
+                ["#{path_prefix}.add_variables.#{filter.name}", filter] # FIXME: config name sucks, of course, if we want to allow inserting etc.
               end
             end
 
-            # The returned filter compiles a new hash for Scoped/Unscoped that only contains
-            # the desired i/o variables.
-            #
-            # Filter expects a "filter interface" {(ctx, **)}.
-            def self.filter_from_dsl(map)
-              hsh = DSL.hash_for(map)
-
-              ->(incoming_ctx, **kwargs) { Hash[hsh.collect { |from_name, to_name| [to_name, incoming_ctx[from_name]] }] }
-            end
-
-            def self.hash_for(ary)
-              return ary if ary.instance_of?(::Hash)
-              Hash[ary.collect { |name| [name, name] }]
-            end
 
             # Keeps user's DSL configuration for a particular io-pipe step.
             # Implements the interface for the actual I/O code and is DSL code happening in the normalizer.
@@ -195,83 +101,272 @@ module Trailblazer
             # If a user needs to inject their own private iop step they can create this data structure with desired values here.
             # This is also the reason why a lot of options computation such as {:with_outer_ctx} happens here and not in the IO code.
 
-            class Tuple < Struct.new(:name, :add_variables_class, :filter_builder, :insert_args)
-              def self.filters_from_options(tuples_to_user_filters)
-                tuples_to_user_filters.collect { |tuple, user_filter| tuple.(user_filter) }
+            class Tuple
+              def initialize(variable_name, add_variables_class, filters_builder, add_variables_class_for_callable=nil, insert_args: nil, **options)
+                @options =
+                  {
+                    variable_name:        variable_name,
+                    add_variables_class:  add_variables_class,
+                    filters_builder:      filters_builder,
+                    insert_args:          insert_args,
+
+                    add_variables_class_for_callable: add_variables_class_for_callable,
+
+                    **options
+                  }
               end
 
+              def to_h
+                @options
+              end
+
+              def self.filters_from_options(tuples_to_user_filters)
+                tuples_to_user_filters.collect { |tuple, user_filter| tuple.(user_filter) }.flatten(1)
+              end
 
               # @return [Filter] Filter instance that keeps {name} and {aggregate_step}.
               def call(user_filter)
-                filter         = filter_builder.(user_filter)
-                aggregate_step = add_variables_class.new(filter, user_filter)
-
-                VariableMapping::Filter.new(aggregate_step, filter, name, add_variables_class)
+                @options[:filters_builder].(user_filter, **to_h)
               end
             end # TODO: implement {:insert_args}
 
             # In, Out and Inject are objects instantiated when using the DSL, for instance {In() => [:model]}.
-            class In < Tuple; end
-            class Out < Tuple; end
+            class In < Tuple
+              class FiltersBuilder
+                def self.call(user_filter, add_variables_class:, add_variables_class_for_callable:, type: :In, **options)
+                  # In()/Out() => {:user => :current_user}
+                  if user_filter.is_a?(Hash)
+                    # For In(): build {SetVariable} filters.
+                    # For Out(): build {SetVariable::Output} filters.
+                    return Filter.build_filters_for_hash(user_filter, add_variables_class: add_variables_class) do |options, from_name, to_name|
+                      options.merge(
+                        name:       Filter.name_for(type, "#{from_name.inspect}>#{to_name.inspect}"),
+                        read_name:  from_name,
+                        write_name: to_name,
+                      )
+                    end
+                  end
+
+                  # In()/Out() => [:current_user]
+                  if user_filter.is_a?(Array)
+                    user_filter = Filter.hash_for(user_filter)
+
+                    return Filter.build_filters_for_hash(user_filter, add_variables_class: add_variables_class) do |options, from_name, _|
+                      options.merge(
+                        name:        Filter.name_for(type, from_name.inspect),
+                        write_name:  from_name,
+                        read_name:   from_name,
+                      )
+                    end
+                  end
+
+                  # callable, producing a hash!
+
+                  return build_for_option(user_filter,
+                      name:                 Filter.name_for(type, user_filter.object_id, :add_variables),
+                      write_name:           nil,
+                      read_name:            nil,
+                      add_variables_class:  add_variables_class_for_callable, # for example, {AddVariables::Output}
+                      **options
+                    )
+                  # TODO: remove {add_variables_class_for_callable} and make everything SetVariable.
+                end # call
+
+                # Simply invoke user's filter.
+                # Use this for filters without condition and default.
+                def self.build_for_option(user_filter, **options)
+                  filter = Activity::Circuit.Step(user_filter, option: true)
+
+                  [
+                    Filter.build(
+                      filter:       filter,
+                      user_filter:  user_filter,
+                      **options
+                    )
+                  ]
+                end
+              end
+            end # In
+
+            class Out < Tuple
+              class FiltersBuilder
+                def self.call(user_filter, with_outer_ctx:, **options)
+                  if with_outer_ctx
+                    callable    = user_filter # FIXME: :instance_method, for fuck's sake.
+                    call_method = callable.respond_to?(:arity) ? callable : callable.method(:call)
+
+                    options =
+                      # TODO: remove {if} and only leave {else}.
+                      if call_method.arity == 3
+                        index = caller_locations.find_index { |location| location.to_s =~ /recompile_activity_for/ }
+                        caller_location = caller_locations[index+2]
+
+                        Activity::Deprecate.warn caller_location,
+                          "The positional argument `outer_ctx` is deprecated, please use the `:outer_ctx` keyword argument.\n#{VariableMapping.deprecation_link}"
+
+                        options.merge(
+                          filter:                           Trailblazer::Option(user_filter),
+                          add_variables_class_for_callable: AddVariables::Output::WithOuterContext_Deprecated, # old positional arg
+                        )
+                      else
+                        options.merge(
+                          add_variables_class_for_callable: AddVariables::Output::WithOuterContext,
+                        )
+                      end
+                  end
+
+                  In::FiltersBuilder.(user_filter, type: :Out, **options)
+                end
+              end
+            end # Out
 
-            def self.In(name: rand, add_variables_class: AddVariables, filter_builder: method(:build_filter))
-              In.new(name, add_variables_class, filter_builder)
+            def self.In(variable_name = nil, add_variables_class: SetVariable, filter_builder: In::FiltersBuilder, add_variables_class_for_callable: AddVariables)
+              In.new(variable_name, add_variables_class, filter_builder, add_variables_class_for_callable)
             end
 
             # Builder for a DSL Output() object.
-            def self.Out(name: rand, add_variables_class: AddVariables::Output, with_outer_ctx: false, delete: false, filter_builder: method(:build_filter), read_from_aggregate: false)
-              add_variables_class = AddVariables::Output::WithOuterContext  if with_outer_ctx
-              add_variables_class = AddVariables::Output::Delete            if delete
-              filter_builder      = ->(user_filter) { user_filter }         if delete
-              add_variables_class = AddVariables::ReadFromAggregate         if read_from_aggregate
+            def self.Out(variable_name = nil, add_variables_class: SetVariable::Output, with_outer_ctx: false, delete: false, filter_builder: Out::FiltersBuilder, read_from_aggregate: false, add_variables_class_for_callable: AddVariables::Output)
+              add_variables_class = SetVariable::Output::Delete     if delete
+              add_variables_class = SetVariable::ReadFromAggregate  if read_from_aggregate
+
+              Out.new(
+                variable_name,
+                add_variables_class,
+                filter_builder,
+                add_variables_class_for_callable,
 
-              Out.new(name, add_variables_class, filter_builder)
+                with_outer_ctx: with_outer_ctx,
+              )
             end
 
-            def self.Inject()
-              Inject.new
+            # Used in the DSL by you.
+            def self.Inject(variable_name = nil, override: false, **)
+              Inject.new(
+                variable_name,
+                nil, # add_variables_class # DISCUSS: do we really want that here?
+                Inject::FiltersBuilder,
+                nil,
+                override: override,
+              )
             end
 
             # This class is supposed to hold configuration options for Inject().
-            class Inject
-            # Translate the raw input of the user to {In} tuples
-              # @return Array of VariableMapping::Filter
-              def self.filters_for_injects(injects)
-                injects.collect do |inject, user_filter| # iterate all {Inject() => user_filter} calls
-                  DSL::Inject.compute_filters_for_inject(inject, user_filter)
-                end.flatten(1)
-              end
+            class Inject < Tuple
+              class FiltersBuilder
+                # Called via {Tuple#call}
+                def self.call(user_filter, add_variables_class:, variable_name:, **options)
+                  # Build {SetVariable::Default}
+                  if user_filter.is_a?(Hash) # TODO: deprecate in favor if {Inject(:variable_name)}!
+                    return Filter.build_filters_for_hash(user_filter, add_variables_class: SetVariable::Default) do |options, from_name, user_proc|
+                      options_with_condition_for_defaulted(
+                        **options,
+                        user_filter:  user_proc,
+                        write_name:   from_name,
+                        read_name:    from_name,
+                      )
+                    end
+                  end
+
+                  # Build {SetVariable::Conditioned}
+                  if user_filter.is_a?(Array)
+                    user_filter = Filter.hash_for(user_filter)
+
+                    return Filter.build_filters_for_hash(user_filter, add_variables_class: SetVariable::Conditioned) do |options, from_name, _|
+                      options_with_condition(
+                        **options,
+                        write_name:   from_name,
+                        read_name:    from_name,
+                        user_filter:  user_filter, # FIXME: this is not really helpful, it's something like [:field, :injects]
+                      )
+                    end
+                  end
+
+                  if options[:override]
+                    return In::FiltersBuilder.build_for_option(
+                      user_filter,
+                      name:                 Filter.name_for(:Inject, variable_name, :add_variables),
+                      write_name:           variable_name,
+                      read_name:            nil,
+                      add_variables_class:  SetVariable,
+                      **options
+                    )
+                  end
+
+
+                  # Build {SetVariable::Default}
+                  # {user_filter} is one of the following
+                  # :instance_method
+                  options = options_with_condition_for_defaulted(
+                    **options,
+                    write_name:   variable_name,
+                    read_name:    variable_name,
+                    user_filter:  user_filter,
+                  )
+
+                  [
+                    Filter.build_for_reading(add_variables_class: SetVariable::Default, **options)
+                  ]
+                end # call
+
+                def self.options_with_condition(user_filter:, write_name:, name_specifier: nil, **options)
+                  {
+                    name:           Filter.name_for(:Inject, write_name.inspect, name_specifier),
+                    **options,
+                    condition:      VariablePresent.new(variable_name: write_name),
+                    write_name:     write_name,
+                    user_filter:    user_filter,
+                  }
+                end
+
+                def self.options_with_condition_for_defaulted(user_filter:, **options)
+                  default_filter = Activity::Circuit.Step(user_filter, option: true) # this is passed into {SetVariable.new}.
 
-              # Compute {In} tuples from the user's DSL input.
-              # We simply use AddVariables but use our own {inject_filter} which checks if the particular
-              # variable is already present in the incoming ctx.
-              def self.compute_filters_for_inject(inject, user_filter) # {user_filter} either [:current_user, :model] or {model: ->{}}
-                return filters_for_array(inject, user_filter) if user_filter.is_a?(Array)
-                filters_for_hash_of_callables(inject, user_filter)
+                  options_with_condition(
+                    **options,
+                    user_filter:    user_filter,
+                    name_specifier: :default,
+                    default_filter: default_filter,
+                  )
+                end
+              end # FiltersBuilder
+            end # Inject
+
+            # DISCUSS: generic, again
+            module Filter
+              def self.build(add_variables_class:, **options)
+                add_variables_class.new(
+                  **options,
+                )
               end
 
-              # [:model, :current_user]
-              def self.filters_for_array(inject, user_filter)
-                user_filter.collect do |name|
-                  inject_filter = ->(original_ctx, **) { original_ctx.key?(name) ? {name => original_ctx[name]} : {} } # FIXME: make me an {Inject::} method.
+              def self.build_for_reading(read_name:, **options)
+                circuit_step_filter = VariableFromCtx.new(variable_name: read_name) # Activity::Circuit.Step(filter, option: true) # this is passed into {SetVariable.new}.
 
-                  filter_for(inject, inject_filter, name, "passthrough")
-                end
+                build(
+                  filter: circuit_step_filter,
+                  **options
+                )
               end
 
-              # {model: ->(*) { snippet }}
-              def self.filters_for_hash_of_callables(inject, user_filter)
-                user_filter.collect do |name, defaulting_filter|
-                  inject_filter = ->(original_ctx, **kws) { original_ctx.key?(name) ? {name => original_ctx[name]} : {name => defaulting_filter.(original_ctx, **kws)} }
+              def self.build_filters_for_hash(user_filter, **options)
+                return user_filter.collect do |from_name, to_name|
+                  options = yield(options, from_name, to_name)
 
-                  filter_for(inject, inject_filter, name, "defaulting_callable")
+                  Filter.build_for_reading(
+                    user_filter: user_filter,
+                    **options,
+                  )
                 end
               end
 
-              def self.filter_for(inject, inject_filter, name, type)
-                DSL.In(name: "#{type}.#{name.inspect}", add_variables_class: AddVariables).(inject_filter)
+              def self.hash_for(ary)
+                ary.collect { |name| [name, name] }.to_h
               end
-            end
+
+              def self.name_for(type, name, specifier=nil)
+                [type, specifier].compact.join(".") + "{#{name}}"
+              end
+            end # Filter
 
           end # DSL
         end