httk.workflow.runtime
=====================

.. py:module:: httk.workflow.runtime

.. autoapi-nested-parse::

   Attempt identity and supervised commands.

   The attempt context and :func:`run_command` are protocol-level facilities every
   native runner uses; the environment-binding helper below is what the authoring
   SDK and the Bash bridge both recover an attempt through.



Classes
-------

.. autoapisummary::

   httk.workflow.runtime.AttemptContext
   httk.workflow.runtime.CommandResult


Functions
---------

.. autoapisummary::

   httk.workflow.runtime.run_command


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

.. py:class:: AttemptContext

   Describe the immutable identity and restart evidence for one running attempt.

   :param workspace_id: Identify the workspace.
   :param job_id: Identify the job.
   :param job_key: Identify the job payload.
   :param placement: Locate the job placement.
   :param payload: Record the absolute job payload path.
   :param step: Identify the runner step.
   :param activation_id: Identify the activation.
   :param attempt_id: Identify the attempt.
   :param activation_ordinal: Record the activation sequence position.
   :param attempt_ordinal: Record the attempt sequence position.
   :param total_attempts: Record the planned attempt count.
   :param is_restart: Mark whether this attempt is a restart.
   :param is_unclean_restart: Mark whether the restart followed an unclean exit.
   :param attempt_reason: Explain why this attempt was selected.
   :param previous_attempt_id: Identify the preceding attempt when present.
   :param activation_reason: Explain why the activation was selected.
   :param workdir_mode: Describe how the work directory was selected.
   :param workdir_reused: Mark whether the work directory was reused.
   :param unsafe_persistent_takeover: Record whether persistent takeover was enabled.
   :param data_generation: Record the data generation at claim time.
   :param durable: Record whether storage-crash durability was enabled.
   :param settings: Record workspace application settings at claim time.
   :param resources: Record the resources assigned to the attempt.
   :param join: Record the job's join description.
   :param raw: Preserve the complete decoded context.


   .. py:attribute:: workspace_id
      :type:  str


   .. py:attribute:: job_id
      :type:  str


   .. py:attribute:: job_key
      :type:  str


   .. py:attribute:: placement
      :type:  str


   .. py:attribute:: payload
      :type:  str


   .. py:attribute:: step
      :type:  str


   .. py:attribute:: activation_id
      :type:  str


   .. py:attribute:: attempt_id
      :type:  str


   .. py:attribute:: activation_ordinal
      :type:  int | None


   .. py:attribute:: attempt_ordinal
      :type:  int | None


   .. py:attribute:: total_attempts
      :type:  int | None


   .. py:attribute:: is_restart
      :type:  bool


   .. py:attribute:: is_unclean_restart
      :type:  bool


   .. py:attribute:: attempt_reason
      :type:  str | None


   .. py:attribute:: previous_attempt_id
      :type:  str | None


   .. py:attribute:: activation_reason
      :type:  str | None


   .. py:attribute:: workdir_mode
      :type:  str | None


   .. py:attribute:: workdir_reused
      :type:  bool


   .. py:attribute:: unsafe_persistent_takeover
      :type:  bool


   .. py:attribute:: data_generation
      :type:  int | None


   .. py:attribute:: durable
      :type:  bool


   .. py:attribute:: settings
      :type:  collections.abc.Mapping[str, object]


   .. py:attribute:: resources
      :type:  collections.abc.Mapping[str, int]


   .. py:attribute:: join
      :type:  object


   .. py:attribute:: raw
      :type:  collections.abc.Mapping[str, Any]


   .. py:method:: from_mapping(value)
      :classmethod:


      Validate a manager-written attempt context mapping.

      :param value: Decoded attempt context.
      :return: The validated attempt context.
      :raises ValueError: If the context format or required values are invalid.



.. py:class:: CommandResult

   Report the result of an argv-only supervised child process.

   :param argv: Preserve the command arguments that were run.
   :param returncode: Record the child process return code.
   :param stdout: Capture standard output.
   :param stderr: Capture standard error.
   :param timed_out: Mark whether the command exceeded its timeout.


   .. py:attribute:: argv
      :type:  tuple[str, ...]


   .. py:attribute:: returncode
      :type:  int


   .. py:attribute:: stdout
      :type:  bytes


   .. py:attribute:: stderr
      :type:  bytes


   .. py:attribute:: timed_out
      :type:  bool


.. py:function:: run_command(argv, *, timeout = None, cwd = None, environment = None, termination_grace = 10.0)

   Run an argv array and terminate its process group on timeout.

   :param argv: Supply the nonempty command argument sequence.
   :param timeout: Stop the command after this many seconds when supplied.
   :param cwd: Set the child working directory.
   :param environment: Set the child environment.
   :param termination_grace: Wait this long after termination before killing.
   :return: The supervised command result.
   :raises ValueError: If the command or timeout settings are invalid.