step.motion.path.passes.lowering
================================

.. py:module:: step.motion.path.passes.lowering

.. autoapi-nested-parse::

   Lowering pass — turn a tree of Step objects into the path IR.

   This is the entry point of the pipeline.  It walks the Step tree, recursively
   flattens ``Sequential`` and ``Parallel`` composites into a linear node list,
   identifies the motion spine inside parallel branches, and produces:

   - ``list[Optional[PathNode]]`` — flat path nodes (Segments, SideActions, or
     ``None`` placeholders for deferred steps).
   - ``list[tuple[int, Defer]]`` — deferred entries to resolve at runtime,
     keyed by their index in the node list.



Functions
---------

.. autoapisummary::

   step.motion.path.passes.lowering.extract_segment
   step.motion.path.passes.lowering.resolve_step
   step.motion.path.passes.lowering.is_same_type
   step.motion.path.passes.lowering.flatten_one
   step.motion.path.passes.lowering.flatten_parallel
   step.motion.path.passes.lowering.flatten_steps


Module Contents
---------------

.. py:function:: extract_segment(step: step.Step) -> step.motion.path.ir.Segment

   Extract motion IR from a resolved step via its ``lower_to_segments()``.

   A step that is not optimizer-supported returns ``None`` and is rejected
   here with ``TypeError`` so ``flatten_one`` can treat it as a side action.


.. py:function:: resolve_step(step) -> step.Step

   Resolve a builder to a concrete Step instance.


.. py:function:: is_same_type(a: step.motion.path.ir.Segment, b: step.motion.path.ir.Segment) -> bool

   Check if two segments can use warm-start (same motion type).

   ``follow_line`` is treated as a forward linear for warm-start purposes:
   it runs the same ``LinearMotion`` axis internally, so velocity can be
   carried across ``linear(Forward) ↔ follow_line`` transitions.
   ``spline`` never warm-starts.


.. py:function:: flatten_one(step, nodes: list[step.motion.path.ir.PathNode | None], deferred: list[tuple[int, step.logic.defer.Defer]]) -> None

   Recursively flatten ``step`` into path nodes.

   Appends to ``nodes`` in-place.  Deferred steps become ``None``
   placeholders with entries in ``deferred`` for runtime resolution.


.. py:function:: flatten_parallel(par, nodes: list[step.motion.path.ir.PathNode | None], deferred: list[tuple[int, step.logic.defer.Defer]]) -> None

   Flatten a Parallel step, identifying the motion spine branch.


.. py:function:: flatten_steps(steps: list) -> tuple[list[step.motion.path.ir.PathNode | None], list[tuple[int, step.logic.defer.Defer]]]

   Flatten a list of steps into a linear path.

   :returns: ``(nodes, deferred)`` where ``nodes`` is a flat list of ``Segment``,
             ``SideAction``, or ``None`` (deferred placeholder), and ``deferred``
             is a list of ``(index, Defer)`` pairs for runtime resolution.