introduce Advance (finally! 😆) and extract start_task_position and

start_positions computation from an Iteration.

lib/trailblazer/workflow.rb

@@ -21,3 +21,6 @@ module Workflow
 require "trailblazer/workflow/introspect/iteration"
 require "trailblazer/workflow/introspect/state_table"
 require "trailblazer/workflow/introspect/event_table"
+
+# runtime
+require "trailblazer/workflow/advance"

lib/trailblazer/workflow/advance.rb

@@ -0,0 +1,35 @@
+# Runtime
+module Trailblazer
+  module Workflow
+    module Advance
+      module_function
+
+      def call(schema, ctx, event_label:, iteration_set:, **)
+        planned_iteration = iteration_set.to_a.find { |iteration| iteration.event_label == event_label }
+
+        # TODO: run the state guard here.
+
+        position_options = position_options_from_iteration(planned_iteration) # :start_task_position and :start_positions
+
+
+        configuration, (ctx, flow) = Trailblazer::Workflow::Collaboration::Synchronous.advance(
+            schema,
+            [ctx, {throw: []}],
+            {}, # circuit_options
+
+            **position_options,
+            message_flow: message_flow,
+          )
+
+      end
+
+      # Computes {:start_task_position} and {:start_positions}.
+      def position_options_from_iteration(iteration)
+        {
+          start_task_position: iteration.start_task_position, # which event to trigger
+          lane_positions:     iteration.start_positions       # current position/"state"
+        }
+      end
+    end
+  end
+end

lib/trailblazer/workflow/test/assertions.rb

@@ -32,11 +32,8 @@ def self.error_message_for(position, expected_position, lanes_cfg:) # TODO: test
         def assert_advance(event_label, test_plan:, lanes_cfg:, schema:, message_flow:, expected_ctx:, ctx: {seq: []}, **) # TODO: allow {ctx}
           iteration = test_plan.to_a.find { |iteration| iteration.event_label == event_label } or raise
 
-          start_task_position = iteration.start_task_position
+          position_options = Advance.position_options_from_iteration(iteration)
 
-          # current position.
-          #DISCUSS: here, we could also ask the State layer for the start configuration, on a different level.
-          lane_positions = iteration.start_positions
 
           ctx_for_advance = ctx
 
@@ -45,8 +42,7 @@ def assert_advance(event_label, test_plan:, lanes_cfg:, schema:, message_flow:,
             [ctx_for_advance, {throw: []}],
             {}, # circuit_options
 
-            start_task_position: start_task_position,
-            lane_positions: lane_positions, # current position/"state"
+            **position_options,
 
             message_flow: message_flow,
           )

test/advance_test.rb

@@ -0,0 +1,32 @@
+require "test_helper"
+
+# high-level unit test that shows the user's interface.
+class AdvanceTest < Minitest::Spec
+  include BuildSchema
+  include DiscoveredStates
+
+  it "what" do
+    schema, lanes, message_flow, initial_lane_positions, lanes_cfg = build_schema()
+
+    # TODO: this is something that shouldn't be done every time.
+    states, lanes_sorted, lanes_cfg = states()
+
+    iteration_set = Trailblazer::Workflow::Introspect::Iteration::Set.from_discovered_states(states, lanes_cfg: lanes_cfg)
+    # "states"
+    position_to_iterations_table = Trailblazer::Workflow::Introspect::StateTable.aggregate_by_state(iteration_set)
+
+    ctx = {params: [], seq: []}
+
+    # TODO: this should be suitable to be dropped into an endpoint.
+
+    signal, (ctx, flow_options) = Trailblazer::Workflow::Advance.(
+      schema,
+      ctx,
+      event_label: "☝ ⏵︎Update",
+      lanes_cfg: lanes_cfg, # TODO: make this part of {schema}.
+
+      iteration_set: iteration_set, # this is basically the "dictionary" for lookups of positions.
+      state_guards: {} # TODO: design/implement this.
+    )
+  end
+end