trailblazer-activity-dsl-linear 0.5.0 → 1.0.0.beta1

data/lib/trailblazer/activity/dsl/linear/normalizer/terminus.rb

@@ -0,0 +1,92 @@
+module Trailblazer
+  class Activity
+    module DSL
+      module Linear
+        module Normalizer
+          # Normalizer pipeline for the {terminus} DSL method.
+          module Terminus
+            module_function
+
+            def Normalizer
+              normalizer_steps =
+                {
+                "activity.normalize_step_interface"       => Normalizer.Task(Normalizer.method(:normalize_step_interface)),      # first
+                "activity.merge_library_options"          => Normalizer.Task(Normalizer.method(:merge_library_options)),    # Merge "macro"/user options over library options.
+                "activity.normalize_for_macro"            => Normalizer.Task(Normalizer.method(:merge_user_options)),
+                "activity.normalize_normalizer_options"   => Normalizer.Task(Normalizer.method(:merge_normalizer_options)),
+                "activity.normalize_non_symbol_options"   => Normalizer.Task(Normalizer.method(:normalize_non_symbol_options)),
+                "activity.normalize_context"              => Normalizer.method(:normalize_context),
+                "terminus.normalize_task"          => Normalizer.Task(Terminus.method(:normalize_task)),
+                "terminus.normalize_id"                   => Normalizer.Task(method(:normalize_id)),
+                "terminus.normalize_magnetic_to"          => Normalizer.Task(Terminus.method(:normalize_magnetic_to)),
+                "terminus.append_end"                     => Normalizer.Task(Terminus.method(:append_end)),
+
+                "activity.compile_data" => Normalizer.Task(Normalizer.method(:compile_data)), # FIXME
+                "activity.create_row" => Normalizer.Task(Normalizer.method(:create_row)),
+                "activity.create_add" => Normalizer.Task(Normalizer.method(:create_add)),
+                "activity.create_adds" => Normalizer.Task(Normalizer.method(:create_adds)),
+                }
+
+              TaskWrap::Pipeline.new(normalizer_steps.to_a)
+            end
+
+            # @private
+            def normalize_id(ctx, id: nil, semantic:, **)
+              ctx.merge!(
+                id: id || Strategy.end_id(semantic: semantic)
+              )
+            end
+
+            # @private
+            # Set {:task} and {:semantic}.
+            def normalize_task(ctx, task:, **)
+              if task.kind_of?(Activity::End) # DISCUSS: do we want this check?
+                ctx = _normalize_task_for_end_event(ctx, **ctx)
+              else
+                # When used such as {terminus :found}, create the end event automatically.
+                ctx = _normalize_task_for_symbol(ctx, **ctx)
+              end
+            end
+
+            def _normalize_task_for_end_event(ctx, task:, **) # you cannot override using {:semantic}
+              ctx.merge!(
+                semantic: task.to_h[:semantic]
+              )
+            end
+
+            def _normalize_task_for_symbol(ctx, task:, semantic: task, **)
+              ctx.merge!(
+                task:     Strategy.End(semantic),
+                semantic: semantic,
+              )
+            end
+
+            # @private
+            def normalize_magnetic_to(ctx, magnetic_to: nil, semantic:, **)
+              return if magnetic_to
+              ctx.merge!(magnetic_to: semantic)
+            end
+
+            # @private
+            def append_end(ctx, task:, semantic:, append_to: "End.success", **)
+              terminus_args = {
+                sequence_insert: [Activity::Adds::Insert.method(:Append), append_to],
+                stop_event:      true
+              }
+
+              ctx.merge!(
+                wirings: [
+                  Linear::Sequence::Search::Noop(
+                    Activity::Output.new(task, semantic), # DISCUSS: do we really want to transport the semantic "in" the object?
+                  )
+                ],
+                adds: [],
+                **terminus_args
+              )
+            end
+          end # Terminus
+        end
+      end
+    end
+  end
+end

data/lib/trailblazer/activity/dsl/linear/normalizer.rb

@@ -2,57 +2,119 @@ module Trailblazer
   class Activity
     module DSL
       module Linear
-        # Normalizers are linear activities that process and normalize the options from a DSL call. They're
-        # usually invoked from {Strategy#task_for}, which is called from {Path#step}, {Railway#pass}, etc.
+        # Normalizers are linear activities that process and normalize the options from a specific DSL call,
+        # such as `#step` or `#pass`. All defaulting should happen through the normalizer. An invoked
+        # normalizer produces an options hash that has to contain an [:adds] key with a ADDS structure usable
+        # for {Sequence.apply_adds}.
+        #
+        # They're usually invoked from {Strategy#invoke_normalizer_for!}, which is called from {Path#step},
+        # {Railway#pass}, etc.
         module Normalizer
+          # Container for all final normalizers of a specific Strategy.
+          class Normalizers
+            def initialize(**options)
+              @normalizers = options
+            end
+            # Execute the specific normalizer (step, fail, pass) for a particular option set provided
+            # by the DSL user. Usually invoked when you call {#step}.
+            def call(name, ctx)
+              normalizer = @normalizers.fetch(name)
+              wrap_ctx, _ = normalizer.(ctx, nil)
+              wrap_ctx
+            end
+          end
+
           module_function
 
-          # Wrap {task} with {Trailblazer::Option} and execute it with kw args in {#call}.
-          # Note that this instance always return {Right}.
+          # Helper for normalizers.
+          # To be applied on {Pipeline} instances.
+          def self.prepend_to(pipe, insertion_id, insertion)
+            adds =
+              insertion.collect do |id, task|
+                {insert: [Adds::Insert.method(:Prepend), insertion_id], row: Activity::TaskWrap::Pipeline.Row(id, task)}
+              end
+
+            Adds.apply_adds(pipe, insertion_id ? adds : adds.reverse)
+          end
+
+          # Helper for normalizers.
+          def self.replace(pipe, insertion_id, (id, task))
+            Adds.apply_adds(
+              pipe,
+              [{insert: [Adds::Insert.method(:Replace), insertion_id], row: Activity::TaskWrap::Pipeline.Row(id, task)}]
+            )
+          end
+
+          # Extend a particular normalizer with new steps and save it on the activity.
+          def self.extend!(activity_class, *step_methods)
+            activity_class.instance_variable_get(:@state).update!(:normalizers) do |normalizers|
+              hsh = normalizers.instance_variable_get(:@normalizers) # TODO: introduce {#to_h}.
+
+              new_normalizers = # {step: #<..>, pass: #<..>}
+                step_methods.collect do |name|
+                  extended_normalizer = hsh.fetch(name)            # grab existing normalizer.
+                  new_normalizer      = yield(extended_normalizer) # and let the user block change it.
+                  [name, new_normalizer]
+                end.to_h
+
+
+              Normalizers.new(**hsh.merge(new_normalizers))
+            end
+          end
+
+          # @private
           class Task < TaskBuilder::Task
             def call(wrap_ctx, flow_options={})
-              result = call_option(@task, [wrap_ctx, flow_options]) # DISCUSS: this mutates {ctx}.
+              _result = call_option(@task, [wrap_ctx, flow_options]) # DISCUSS: this mutates {ctx}.
 
               return wrap_ctx, flow_options
             end
           end
 
+          # Wrap user's normalizer task with {Trailblazer::Option} and thus execute it with
+          # convenient kw args.
+          #
+          # Example
+          #   normalizer_task = Normalizer.Task(method(:normalize_id))
+          #
+          #   # will call {normalizer_task} and pass ctx variables as kwargs, as follows
+          #   def normalize_id(ctx, id: false, task:, **)
           def Task(user_proc)
             Normalizer::Task.new(Trailblazer::Option(user_proc), user_proc)
           end
 
-          #   activity_normalizer.([{options:, user_options:, normalizer_options: }])
-          def activity_normalizer(pipeline)
-            pipeline = TaskWrap::Pipeline.prepend(
-              pipeline,
-              nil, # this means, put it to the beginning.
+          # The generic normalizer not tied to `step` or friends.
+          def Normalizer
+            pipeline = TaskWrap::Pipeline.new(
               {
-              "activity.normalize_step_interface"       => Normalizer.Task(method(:normalize_step_interface)),      # first
-              "activity.normalize_for_macro"            => Normalizer.Task(method(:merge_user_options)),
-              "activity.normalize_normalizer_options"   => Normalizer.Task(method(:merge_normalizer_options)),
-              "activity.normalize_non_symbol_options"   => Normalizer.Task(method(:normalize_non_symbol_options)),
-              "activity.normalize_context"              => method(:normalize_context),
-              "activity.normalize_id"                   => Normalizer.Task(method(:normalize_id)),
-              "activity.normalize_override"             => Normalizer.Task(method(:normalize_override)),
-              "activity.wrap_task_with_step_interface"  => Normalizer.Task(method(:wrap_task_with_step_interface)), # last
-              "activity.inherit_option"                 => Normalizer.Task(method(:inherit_option)),
-              },
-            )
-
-            pipeline = TaskWrap::Pipeline.prepend(
-              pipeline,
-              "path.wirings",
-              {
-              "activity.normalize_outputs_from_dsl"     => Normalizer.Task(method(:normalize_outputs_from_dsl)),     # Output(Signal, :semantic) => Id()
-              "activity.normalize_connections_from_dsl" => Normalizer.Task(method(:normalize_connections_from_dsl)),
-              "activity.input_output_dsl"               => Normalizer.Task(method(:input_output_dsl)),
-              },
-            )
-
-            pipeline = TaskWrap::Pipeline.append(
-              pipeline,
-              nil,
-              ["activity.cleanup_options", method(:cleanup_options)]
+                "activity.normalize_step_interface"       => Normalizer.Task(method(:normalize_step_interface)), # Makes sure {:options} is always a hash.
+                "activity.merge_library_options"          => Normalizer.Task(method(:merge_library_options)),    # Merge "macro"/user options over library options.
+                "activity.normalize_for_macro"            => Normalizer.Task(method(:merge_user_options)),       # Merge user_options over "macro" options.
+                "activity.normalize_normalizer_options"   => Normalizer.Task(method(:merge_normalizer_options)), # Merge user_options over normalizer_options.
+                "activity.normalize_non_symbol_options"   => Normalizer.Task(method(:normalize_non_symbol_options)),
+                "activity.path_helper.forward_block"      => Normalizer.Task(Helper::Path::Normalizer.method(:forward_block_for_path_branch)),     # forward the "global" block
+                "activity.normalize_context"              => method(:normalize_context),
+                "activity.normalize_id"                   => Normalizer.Task(method(:normalize_id)),
+                "activity.normalize_override"             => Normalizer.Task(method(:normalize_override)),
+                "activity.wrap_task_with_step_interface"  => Normalizer.Task(method(:wrap_task_with_step_interface)),
+
+                "activity.inherit_option"                 => Normalizer.Task(method(:inherit_option)),
+                "activity.sequence_insert"                => Normalizer.Task(method(:normalize_sequence_insert)),
+                "activity.normalize_duplications"         => Normalizer.Task(method(:normalize_duplications)),
+
+                "activity.path_helper.path_to_track"       => Normalizer.Task(Helper::Path::Normalizer.method(:convert_paths_to_tracks)),
+                "activity.normalize_outputs_from_dsl"     => Normalizer.Task(method(:normalize_outputs_from_dsl)),     # Output(Signal, :semantic) => Id()
+                "activity.normalize_connections_from_dsl" => Normalizer.Task(method(:normalize_connections_from_dsl)),
+
+                "activity.wirings"                            => Normalizer.Task(method(:compile_wirings)),
+
+                # TODO: make this a "Subprocess":
+                "activity.compile_data" => Normalizer.Task(method(:compile_data)),
+                "activity.create_row" => Normalizer.Task(method(:create_row)),
+                "activity.create_add" => Normalizer.Task(method(:create_add)),
+                "activity.create_adds" => Normalizer.Task(method(:create_adds)),
+              }.
+                collect { |id, task| TaskWrap::Pipeline.Row(id, task) }
             )
 
             pipeline
@@ -101,10 +163,15 @@ module Trailblazer
             ctx[:replace] = (id || raise)
           end
 
+          # {:library_options} such as :sequence, :dsl_track, etc.
+          def merge_library_options(ctx, options:, library_options:, **)
+            ctx[:options] = library_options.merge(options)
+          end
+
           # make ctx[:options] the actual ctx
-          def merge_user_options(ctx, options:, **)
+          def merge_user_options(ctx, options:, user_options:, **)
             # {options} are either a <#task> or {} from macro
-            ctx[:options] = options.merge(ctx[:user_options]) # Note that the user options are merged over the macro options.
+            ctx[:options] = options.merge(user_options) # Note that the user options are merged over the macro options.
           end
 
           # {:normalizer_options} such as {:track_name} get overridden by user/macro.
@@ -132,6 +199,48 @@ module Trailblazer
               end
           end
 
+          # Processes {:before,:after,:replace,:delete} options and
+          # defaults to {before: "End.success"} which, yeah.
+          def normalize_sequence_insert(ctx, end_id:, **)
+            insertion = ctx.keys & sequence_insert_options.keys
+            insertion = insertion[0]   || :before
+            target    = ctx[insertion] || end_id
+
+            insertion_method = sequence_insert_options[insertion]
+
+            ctx[:sequence_insert] = [Activity::Adds::Insert.method(insertion_method), target]
+          end
+
+          # @private
+          def sequence_insert_options
+            {
+              :before  => :Prepend,
+              :after   => :Append,
+              :replace => :Replace,
+              :delete  => :Delete,
+            }
+          end
+
+          def normalize_duplications(ctx, replace: false, **)
+            return if replace
+
+            raise_on_duplicate_id(ctx, **ctx)
+            clone_duplicate_activity(ctx, **ctx) # DISCUSS: mutates {ctx}.
+          end
+
+          # @private
+          def raise_on_duplicate_id(ctx, id:, sequence:, **)
+            raise "ID #{id} is already taken. Please specify an `:id`." if sequence.find { |row| row.id == id }
+          end
+
+          # @private
+          def clone_duplicate_activity(ctx, task:, sequence:, **)
+            return unless task.is_a?(Class)
+
+            ctx[:task] = task.clone if sequence.find { |row| row[1] == task }
+          end
+
+
           # Move DSL user options such as {Output(:success) => Track(:found)} to
           # a new key {options[:non_symbol_options]}.
           # This allows using {options} as a {**ctx}-able hash in Ruby 2.6 and 3.0.
@@ -144,24 +253,23 @@ module Trailblazer
           end
 
           # Process {Output(:semantic) => target} and make them {:connections}.
-          def normalize_connections_from_dsl(ctx, connections:, adds:, non_symbol_options:, **)
+          def normalize_connections_from_dsl(ctx, connections:, adds:, non_symbol_options:, sequence:, normalizers:, **)
             # Find all {Output() => Track()/Id()/End()}
-            output_configs = non_symbol_options.find_all{ |k,v| k.kind_of?(Activity::DSL::Linear::OutputSemantic) }
+            output_configs = non_symbol_options.find_all{ |k,v| k.kind_of?(Linear::OutputSemantic) }
             return unless output_configs.any?
 
+            # DISCUSS: how could we add another magnetic_to to an end?
             output_configs.each do |output, cfg|
               new_connections, add =
-                if cfg.is_a?(Activity::DSL::Linear::Track)
-                  [output_to_track(ctx, output, cfg), cfg.adds]
-                elsif cfg.is_a?(Activity::DSL::Linear::Id)
+                if cfg.is_a?(Linear::Track)
+                  [output_to_track(ctx, output, cfg), cfg.adds] # FIXME: why does Track have a {adds} field? we don't use it anywhere.
+                elsif cfg.is_a?(Linear::Id)
                   [output_to_id(ctx, output, cfg.value), []]
                 elsif cfg.is_a?(Activity::End)
-                  _adds = []
+                  end_id     = Activity::Railway.end_id(**cfg.to_h)
+                  end_exists = Activity::Adds::Insert.find_index(ctx[:sequence], end_id)
 
-                  end_id     = Linear.end_id(cfg)
-                  end_exists = Insert.find_index(ctx[:sequence], end_id)
-
-                  _adds      = [add_end(cfg, magnetic_to: end_id, id: end_id)] unless end_exists
+                  _adds = end_exists ? [] : add_terminus(cfg, id: end_id, sequence: sequence, normalizers: normalizers)
 
                   [output_to_id(ctx, output, end_id), _adds]
                 else
@@ -179,23 +287,18 @@ module Trailblazer
           def output_to_track(ctx, output, track)
             search_strategy = track.options[:wrap_around] ? :WrapAround : :Forward
 
-            {output.value => [Linear::Search.method(search_strategy), track.color]}
+            {output.value => [Linear::Sequence::Search.method(search_strategy), track.color]}
           end
 
           def output_to_id(ctx, output, target)
-            {output.value => [Linear::Search.method(:ById), target]}
+            {output.value => [Linear::Sequence::Search.method(:ById), target]}
           end
 
-          # {#insert_task} options to add another end.
-          def add_end(end_event, magnetic_to:, id:)
-
-            options = Path::DSL.append_end_options(task: end_event, magnetic_to: magnetic_to, id: id)
-            row     = Linear::Sequence.create_row(**options)
+          # Returns ADDS for the new terminus.
+          def add_terminus(end_event, id:, sequence:, normalizers:)
+            step_options = Linear::Sequence::Builder.invoke_normalizer_for(:terminus, end_event, {id: id}, sequence: sequence, normalizer_options: {}, normalizers: normalizers)
 
-            {
-              row:    row,
-              insert: row[3][:sequence_insert]
-            }
+            step_options[:adds]
           end
 
           # Output(Signal, :semantic) => Id()
@@ -207,30 +310,32 @@ module Trailblazer
 
             output_configs.collect do |output, cfg| # {cfg} = Track(:success)
               outputs     = outputs.merge(output.semantic => output)
-              dsl_options = dsl_options.merge(Linear.Output(output.semantic) => cfg)
+              dsl_options = dsl_options.merge(Linear::Strategy.Output(output.semantic) => cfg)
             end
 
             ctx[:outputs]            = outputs
             ctx[:non_symbol_options] = non_symbol_options.merge(dsl_options)
           end
 
-          def input_output_dsl(ctx, extensions: [], **)
-            config = ctx.select { |k,v| [:input, :output, :output_with_outer_ctx, :inject].include?(k) } # TODO: optimize this, we don't have to go through the entire hash.
-            return unless config.any? # no :input/:output/:inject passed.
-
-            ctx[:extensions] = extensions + [Linear.VariableMapping(**config)]
-          end
-
           # Currently, the {:inherit} option copies over {:connections} from the original step
           # and merges them with the (prolly) connections passed from the user.
           def inherit_option(ctx, inherit: false, sequence:, id:, extensions: [], **)
-            return unless inherit
+            return unless inherit === true
 
-            index = Linear::Insert.find_index(sequence, id)
-            row   = sequence[index] # from this row we're inheriting options.
+            row = InheritOption.find_row(sequence, id) # from this row we're inheriting options.
+
+            inherited_connections = row.data[:connections]
+            inherited_extensions  = row.data[:extensions]
+
+            ctx[:connections] = get_inheritable_connections(ctx, inherited_connections)
+            ctx[:extensions]  = Array(inherited_extensions) + Array(extensions)
+          end
 
-            ctx[:connections] = get_inheritable_connections(ctx, row[3][:connections])
-            ctx[:extensions]  = Array(row[3][:extensions]) + Array(extensions)
+          module InheritOption # TODO: move all inherit methods in here!
+            def self.find_row(sequence, id)
+              index = Activity::Adds::Insert.find_index(sequence, id)
+              sequence[index]
+            end
           end
 
           # return connections from {parent} step which are supported by current step
@@ -240,12 +345,24 @@ module Trailblazer
             parent_connections.slice(*ctx[:outputs].keys)
           end
 
-          # TODO: make this extendable!
-          def cleanup_options(ctx, flow_options)
-            # new_ctx = ctx.reject { |k, v| [:connections, :outputs, :end_id, :step_interface_builder, :failure_end, :track_name, :sequence].include?(k) }
-            new_ctx = ctx.reject { |k, v| [:outputs, :end_id, :step_interface_builder, :failure_end, :track_name, :sequence, :non_symbol_options].include?(k) }
+          def create_row(ctx, task:, wirings:, magnetic_to:, data:, **)
+            ctx[:row] = Sequence.create_row(task: task, magnetic_to: magnetic_to, wirings: wirings, **data)
+          end
+
+          def create_add(ctx, row:, sequence_insert:, **)
+            ctx[:add] = {row: row, insert: sequence_insert}
+          end
+
+          def create_adds(ctx, add:, adds:, **)
+            ctx[:adds] = [add] + adds
+          end
+
+          # TODO: document DataVariable() => :name
+          # Compile data that goes into the sequence row.
+          def compile_data(ctx, default_variables_for_data: [:id, :dsl_track, :connections, :extensions, :stop_event], non_symbol_options:, **)
+            variables_for_data = non_symbol_options.find_all { |k,v| k.instance_of?(Linear::DataVariableName) }.collect { |k,v| Array(v) }.flatten
 
-            return new_ctx, flow_options
+            ctx[:data] = (default_variables_for_data + variables_for_data).collect { |key| [key, ctx[key]] }.to_h
           end
         end
 

data/lib/trailblazer/activity/dsl/linear/sequence/builder.rb

@@ -0,0 +1,47 @@
+module Trailblazer
+  class Activity
+    module DSL
+      module Linear
+        class Sequence
+          # Implements a DSL Builder pattern.
+          module Builder
+            # @return Sequence
+            def self.call(method, argument, options, **kws, &block)
+              update_sequence_for(method, argument, options, **kws, &block)
+            end
+
+            # @private
+            # Run a specific normalizer (e.g. for `#step`), apply the adds to the sequence and return the latter.
+            # DISCUSS: where does this method belong? Sequence + Normalizers?
+            def self.update_sequence_for(type, task, options={}, sequence:, **kws, &block)
+              step_options = invoke_normalizer_for(type, task, options, sequence: sequence, **kws, &block)
+
+              _sequence = Activity::Adds.apply_adds(sequence, step_options[:adds])
+            end
+
+            # @private
+            # DISCUSS: used in {Normalizer#add_terminus}, too.
+            def self.invoke_normalizer_for(type, task, options, normalizers:, normalizer_options:, sequence:, &block)
+              # These options represent direct configuration of the very method call that causes the normalizer to be run.
+              library_options = {
+                dsl_track:   type,
+                block:       block,
+
+                # DISCUSS: for some reason I am not entirely happy with those variables being here. Maybe this will change.
+                normalizers: normalizers,
+                sequence:    sequence,
+              }
+
+              _step_options = normalizers.(type,
+                normalizer_options: normalizer_options, # class-level Strategy configuration, such as :step_interface_builder
+                options:            task,               # macro-options
+                user_options:       options,            # user-specified options from the DSL method
+                library_options:    library_options     # see above, "runtime" options (from compile-time, haha).
+              )
+            end
+          end # Builder
+        end
+      end
+    end
+  end
+end

data/lib/trailblazer/activity/dsl/linear/sequence/compiler.rb

@@ -0,0 +1,72 @@
+module Trailblazer
+  class Activity
+    module DSL
+      module Linear
+        class Sequence
+          # Compile a {Schema} by computing {implementations} and {intermediate} from a {Sequence}.
+          module Compiler
+            module_function
+
+            # Default strategy to find out what's a stop event is to inspect the TaskRef's {data[:stop_event]}.
+            def find_stop_task_ids(intermediate_wiring)
+              intermediate_wiring.collect { |task_ref, outs| task_ref.data[:stop_event] ? task_ref.id : nil }.compact
+            end
+
+            # The first task in the wiring is the default start task.
+            def find_start_task_ids(intermediate_wiring)
+              [intermediate_wiring.first.first.id]
+            end
+
+            def call(sequence, find_stops: method(:find_stop_task_ids), find_start: method(:find_start_task_ids))
+              _implementations, intermediate_wiring =
+                sequence.inject([[], []]) do |(implementations, intermediates), seq_row|
+                  _magnetic_to, task, connections, data = seq_row
+                  id = data[:id]
+
+                  # execute all {Search}s for one sequence row.
+                  connections = find_connections(seq_row, connections, sequence)
+
+                  # FIXME: {:extensions} should be initialized
+                  implementations += [[id, Schema::Implementation::Task(task, connections.collect { |output, _| output }, data[:extensions] || []) ]]
+
+                  intermediates += [
+                    [
+                      Schema::Intermediate::TaskRef(id, data),
+                      # Compute outputs.
+                      connections.collect { |output, target_id| Schema::Intermediate::Out(output.semantic, target_id) }
+                    ]
+                  ]
+
+                  [implementations, intermediates]
+                end
+
+              start_task_ids = find_start.(intermediate_wiring)
+              stop_task_refs = find_stops.(intermediate_wiring)
+
+              intermediate   = Schema::Intermediate.new(Hash[intermediate_wiring], stop_task_refs, start_task_ids)
+              implementation = Hash[_implementations]
+
+              Schema::Intermediate.(intermediate, implementation) # implemented in the generic {trailblazer-activity} gem.
+            end
+
+            # private
+
+            def find_connections(seq_row, strategies, sequence)
+              strategies.collect do |search|
+                output, target_seq_row = search.(sequence, seq_row) # invoke the node's "connection search" strategy.
+
+                target_seq_row = sequence[-1] if target_seq_row.nil? # connect to an End if target unknown. # DISCUSS: make this configurable, maybe?
+
+                [
+                  output,                                     # implementation
+                  target_seq_row[3][:id],  # intermediate   # FIXME. this sucks.
+                  target_seq_row # DISCUSS: needed?
+                ]
+              end.compact
+            end
+          end # Compiler
+        end # Sequence
+      end
+    end
+  end
+end

data/lib/trailblazer/activity/dsl/linear/sequence/search.rb

@@ -0,0 +1,58 @@
+class Trailblazer::Activity
+  module DSL
+    module Linear
+      # Search strategies are part of the {wirings}, they find the next step
+      # for an output.
+      class Sequence
+        module Search
+          module_function
+
+          # From this task onwards, find the next task that's "magnetic to" {target_color}.
+          # Note that we only go forward, no back-references are done here.
+          def Forward(output, target_color)
+            ->(sequence, me) do
+              target_seq_row = find_in_range(sequence[sequence.index(me)+1..-1], target_color)
+
+              return output, target_seq_row
+            end
+          end
+
+          # Tries to find a track colored step by doing a Forward-search, first, then wraps around going
+          # through all steps from sequence start to self.
+          def WrapAround(output, target_color)
+            ->(sequence, me) do
+              my_index      = sequence.index(me)
+              # First, try all elements after me, then go through the elements preceding myself.
+              wrapped_range = sequence[my_index+1..-1] + sequence[0..my_index-1]
+
+              target_seq_row = find_in_range(wrapped_range, target_color)
+
+              return output, target_seq_row
+            end
+          end
+
+          def Noop(output)
+            ->(sequence, me) do
+              return output, [nil,nil,nil,{}] # FIXME
+            end
+          end
+
+          # Find the seq_row with {id} and connect the current node to it.
+          def ById(output, id)
+            ->(sequence, me) do
+              index          = Adds::Insert.find_index(sequence, id) or return output, sequence[0] # FIXME # or raise "Couldn't find {#{id}}"
+              target_seq_row = sequence[index]
+
+              return output, target_seq_row
+            end
+          end
+
+          # @private
+          def find_in_range(range, target_color)
+            _target_seq_row = range.find { |seq_row| seq_row[0] == target_color }
+          end
+        end # Search
+      end
+    end
+  end
+end

data/lib/trailblazer/activity/dsl/linear/sequence.rb

@@ -0,0 +1,34 @@
+class Trailblazer::Activity
+  module DSL
+    module Linear
+      # A {Sequence} consists of rows, each row represents one step (or task) of an activity
+      # and its incoming and outgoing connections.
+      # {Sequence row} consisting of {[magnetic_to, task, connections_searches, data]}.
+      # A Sequence is compiled into an activity using {Compiler}.
+      #
+      # Complies with the Adds interface (#to_a).
+      class Sequence < Array
+        # Row interface is part of the ADDs specification.
+        class Row < Array
+          def id
+            data[:id]
+          end
+
+          def data
+            self[3]
+          end
+        end
+
+        # Return {Sequence row} consisting of {[magnetic_to, task, connections_searches, data]}.
+        def self.create_row(task:, magnetic_to:, wirings:, **data)
+          Row[
+            magnetic_to,
+            task,
+            wirings,
+            data # {id: "Start.success"}
+          ]
+        end
+      end # Sequence
+    end # Linear
+  end
+end