ao_runtime_supervisor
=====================

Top-level active object driving startup and dispatching periodic and asynchronous events.

Inherited Component
-------------------

- :doc:`Runtime_Manager </generated/architecture/runtime-manager-67b5054c-aedb-47b5-8258-c8d97c4f7d69>`

Inherited Requirements
----------------------

- :doc:`REQ-REL-001 </generated/requirements/req-rel-001-2e6b7004-be8f-4e6b-8d4e-e4b18a08ff41>`
- :doc:`REQ-REL-004 </generated/requirements/req-rel-004-6f23cf0d-e838-4f23-b798-f39b79b8042a>`

Relationship Diagram
--------------------

.. image:: /_static/sw_unit_uml/ao_runtime_supervisor_46acab8f-6426-46ac-9b10-6f02a2ca442d_uml.svg
   :alt: UML class diagram for ao_runtime_supervisor
   :class: dblclick-open-image


SW Unit Relations
-----------------

Outgoing Relations
~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1

   * - Relation
     - UML Type
     - Visibility
     - Target Unit
     - Description
   * - :doc:`SWR-001 </generated/detailed_design/relations/swr-001-9e36aec0-c9a4-4e36-8d10-272503709949>`
     - composition
     - private
     - :doc:`evt_dispatcher </generated/detailed_design/units/evt-dispatcher-3b62a8e6-96c4-4b62-95cf-7cd61813bb5c>`
     - Runtime supervisor owns event dispatch lifecycle.
   * - :doc:`SWR-002 </generated/detailed_design/relations/swr-002-88436ca5-e2fa-4843-8d75-ab617c159b6e>`
     - composition
     - private
     - :doc:`evt_timer_service </generated/detailed_design/units/evt-timer-service-2c6052c1-a0af-4c60-9a3f-846e9498d908>`
     - Runtime supervisor owns timer event service.
   * - :doc:`SWR-003 </generated/detailed_design/relations/swr-003-0b2cab31-b379-4b2c-a7f0-4c55663fc66e>`
     - composition
     - private
     - :doc:`sm_operation_mode </generated/detailed_design/units/sm-operation-mode-c359a001-cc9a-4359-85ca-556ef59c6bcc>`
     - Runtime supervisor embeds operation mode state machine.
   * - :doc:`SWR-007 </generated/detailed_design/relations/swr-007-2b7a6716-5c99-4b7a-8851-5d5cc5fa7507>`
     - dependency
     - public
     - :doc:`ao_monitoring </generated/detailed_design/units/ao-monitoring-d00a296a-5578-400a-89d7-90d6c2b31039>`
     - Runtime supervisor dispatches monitoring events.
   * - :doc:`SWR-008 </generated/detailed_design/relations/swr-008-b9e7b61d-045b-49e7-b041-d6b915ad9131>`
     - dependency
     - public
     - :doc:`ao_control </generated/detailed_design/units/ao-control-c39fee55-334a-439f-9130-242b3170e9e4>`
     - Runtime supervisor dispatches control events.
   * - :doc:`SWR-009 </generated/detailed_design/relations/swr-009-2afa4333-8e78-4afa-b24a-ff1b6408c8db>`
     - dependency
     - public
     - :doc:`ao_safety </generated/detailed_design/units/ao-safety-572b6978-4204-472b-adc9-dfab6db77544>`
     - Runtime supervisor dispatches safety events.
   * - :doc:`SWR-010 </generated/detailed_design/relations/swr-010-5db60957-013d-4db6-9b6b-14b2ef93d645>`
     - dependency
     - public
     - :doc:`ao_diagnostics </generated/detailed_design/units/ao-diagnostics-393df213-9fc6-493d-94c4-e56fb9ff6d08>`
     - Runtime supervisor dispatches diagnostics events.
   * - :doc:`SWR-011 </generated/detailed_design/relations/swr-011-b11605dd-0b96-4116-8c4a-5d080c1e6801>`
     - dependency
     - public
     - :doc:`ao_modbus_server </generated/detailed_design/units/ao-modbus-server-c4a17ec8-b518-44a1-982f-7d2f82fa4b44>`
     - Runtime supervisor dispatches communication events.


Data Types
----------

.. _dt-dcf0726b-8673-4cf0-a148-e44248d4b8ca:

.. raw:: html

   <span id="dt-dcf0726b-8673-4cf0-a148-e44248d4b8ca"></span><div class="sw-dt-title"><span class="sw-dt-name">ao_runtime_supervisor_context</span><span class="sw-dt-badge sw-dt-badge-struct">struct</span></div>

Internal runtime context for ao_runtime_supervisor.

.. rubric:: Struct Members

.. list-table::
   :header-rows: 1

   * - Name
     - Type
     - Description
   * - lifecycle_state
     - :ref:`uint8_t <dt-45402023-5ffe-4540-ba19-64896d87b3dc>`
     - Runtime lifecycle state.
   * - ready_gate_mask
     - :ref:`uint16_t <dt-036d66c4-d7f5-436d-8f41-bf413e2d3351>`
     - Startup readiness mask.
   * - degraded_active
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - Degraded mode active.
   * - watchdog_ok
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - Watchdog health state.

.. _dt-07c7671e-791b-47c7-8ad0-23404e203237:

.. raw:: html

   <span id="dt-07c7671e-791b-47c7-8ad0-23404e203237"></span><div class="sw-dt-title"><span class="sw-dt-name">ao_runtime_supervisor_event</span><span class="sw-dt-badge sw-dt-badge-struct">struct</span></div>

Event payload handled by ao_runtime_supervisor.

.. rubric:: Struct Members

.. list-table::
   :header-rows: 1

   * - Name
     - Type
     - Description
   * - signal_id
     - :ref:`uint16_t <dt-036d66c4-d7f5-436d-8f41-bf413e2d3351>`
     - Supervisor event signal id.
   * - source_unit_id
     - :ref:`uint16_t <dt-036d66c4-d7f5-436d-8f41-bf413e2d3351>`
     - Event source unit identifier.
   * - gate_id
     - :ref:`uint8_t <dt-45402023-5ffe-4540-ba19-64896d87b3dc>`
     - Readiness gate identifier.
   * - fault_present
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - Fault condition input.

.. _dt-c8e3f24a-4682-48e3-ae1a-6d49b30d8e37:

.. raw:: html

   <span id="dt-c8e3f24a-4682-48e3-ae1a-6d49b30d8e37"></span><div class="sw-dt-title"><span class="sw-dt-name">ao_runtime_supervisor_result</span><span class="sw-dt-badge sw-dt-badge-enum">enum</span></div>

Result code for ao_runtime_supervisor operations.

.. rubric:: Enum Members

.. list-table::
   :header-rows: 1

   * - Name
     - Value
     - Description
   * - OK
     - 0
     - Lifecycle transition applied.
   * - INIT_TIMEOUT
     - 1
     - Initialization timed out.
   * - DEGRADED_ENTERED
     - 2
     - Entered degraded lifecycle.



Attributes
----------

.. list-table::
   :header-rows: 1

   * - Attribute
     - Type
     - Visibility
     - Description
   * - ctx
     - :ref:`ao_runtime_supervisor_context <dt-dcf0726b-8673-4cf0-a148-e44248d4b8ca>`
     - private
     - Runtime context for ao_runtime_supervisor state timing and error tracking.

Methods
-------

dispatch
~~~~~~~~

- **Return Type:** :ref:`ao_runtime_supervisor_result <dt-c8e3f24a-4682-48e3-ae1a-6d49b30d8e37>`
- **Visibility:** public
- **Description:** Process one ao_runtime_supervisor event and update runtime outputs.

.. rubric:: Parameters

.. list-table::
   :header-rows: 1

   * - Name
     - Type
     - Direction
     - Description
   * - event
     - :ref:`ao_runtime_supervisor_event <dt-07c7671e-791b-47c7-8ad0-23404e203237>`
     - in
     - Process one ao_runtime_supervisor event and update runtime outputs.

init
~~~~

- **Return Type:** :ref:`ao_runtime_supervisor_result <dt-c8e3f24a-4682-48e3-ae1a-6d49b30d8e37>`
- **Visibility:** public
- **Description:** Initialize ao_runtime_supervisor runtime state and dependencies.



Dynamic Behaviour
-----------------


State Machines
~~~~~~~~~~~~~~

ao_runtime_supervisor_state
^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. uml::

   @startuml
   hide empty description
   [*] --> Boot
   Boot --> Init_Subsystems : EVT_BOOT
   
   Init_Subsystems : entry / init_timer_service()
   Init_Subsystems : entry / init_dispatcher()
   Init_Subsystems : entry / init_active_objects()
   Init_Subsystems --> Run : EVT_INIT_OK [timer_ready && dispatcher_ready && required_aos_ready]
   Init_Subsystems --> Degraded : EVT_INIT_FAIL [init_timeout || required_service_failed]
   
   Run : do / dispatch_periodic_events()
   Run : do / dispatch_async_events()
   Run --> Degraded : EVT_FATAL_FAULT
   
   Degraded : do / minimal_safe_dispatch()
   Degraded --> Run : EVT_RESET [fault_cleared && watchdog_ok && required_services_ready]
   Degraded --> Shutdown : EVT_SHUTDOWN_REQ
   
   Shutdown : entry / publish_shutdown_status()
   Shutdown : do / stop_active_objects_orderly()
   Shutdown --> [*] : EVT_ALL_STOPPED
   @enduml


Runtime supervisor lifecycle with explicit readiness gates degraded entry and recovery criteria and controlled shutdown completion conditions.





Sequence Diagrams
~~~~~~~~~~~~~~~~~

SEQ-001_Runtime_Event_Orchestration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. uml::

   @startuml
   
   hide footbox
   title Runtime Event Orchestration
   
   participant ao_runtime_supervisor
   participant evt_timer_service
   participant evt_dispatcher
   participant ao_monitoring
   participant ao_control
   participant ao_safety
   participant ao_diagnostics
   participant ao_modbus_server
   
   ao_runtime_supervisor -> evt_timer_service : init periodic tick
   ao_runtime_supervisor -> evt_dispatcher : init event loop
   loop each scheduler tick
     evt_timer_service -> ao_runtime_supervisor : tick event
     ao_runtime_supervisor -> evt_dispatcher : dispatch cycle
     evt_dispatcher -> ao_monitoring : monitor_event
     evt_dispatcher -> ao_control : control_event
     evt_dispatcher -> ao_safety : safety_event
     evt_dispatcher -> ao_diagnostics : diagnostics_event
     evt_dispatcher -> ao_modbus_server : comms_event
   end
   
   @enduml


Primary runtime interoperability sequence showing scheduler tick propagation through dispatcher fan-out and deterministic active-object processing order across monitoring control safety diagnostics and communication units.


SEQ-004_Modbus_Event_Servicing
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. uml::

   @startuml
   
   hide footbox
   title Modbus Server Event Servicing
   
   participant ao_runtime_supervisor
   participant ao_modbus_server
   participant hal_event_adapter
   
   ao_runtime_supervisor -> ao_modbus_server : dispatch comms_event
   ao_modbus_server -> hal_event_adapter : request UART I/O
   hal_event_adapter --> ao_modbus_server : uart_rx/tx completion
   ao_modbus_server -> hal_event_adapter : publish protocol response
   
   @enduml


Runtime-driven communication events are processed by the Modbus server through hardware-adapted UART event exchange.


SEQ-005_Startup_To_Ready
^^^^^^^^^^^^^^^^^^^^^^^^

.. uml::

   @startuml
   hide footbox
   participant ao_runtime_supervisor
   participant evt_timer_service
   participant evt_dispatcher
   participant ao_monitoring
   participant ao_control
   participant ao_safety
   participant ao_diagnostics
   participant ao_modbus_server
   
   ao_runtime_supervisor -> evt_timer_service : init()
   ao_runtime_supervisor -> evt_dispatcher : init()
   ao_runtime_supervisor -> ao_monitoring : init()
   ao_runtime_supervisor -> ao_control : init()
   ao_runtime_supervisor -> ao_safety : init()
   ao_runtime_supervisor -> ao_diagnostics : init()
   ao_runtime_supervisor -> ao_modbus_server : init()
   
   group readiness gates
     evt_timer_service --> ao_runtime_supervisor : EVT_TIMER_READY
     evt_dispatcher --> ao_runtime_supervisor : EVT_DISPATCH_READY
     ao_monitoring --> ao_runtime_supervisor : EVT_AO_READY
     ao_control --> ao_runtime_supervisor : EVT_AO_READY
     ao_safety --> ao_runtime_supervisor : EVT_AO_READY
     ao_diagnostics --> ao_runtime_supervisor : EVT_AO_READY
     ao_modbus_server --> ao_runtime_supervisor : EVT_AO_READY
   end
   
   ao_runtime_supervisor -> evt_dispatcher : EVT_INIT_OK / start Run
   @enduml


Startup lifecycle sequence with explicit readiness gates before entering Run state.


SEQ-006_Degraded_Entry_And_Recovery
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. uml::

   @startuml
   hide footbox
   participant ao_runtime_supervisor
   participant evt_dispatcher
   participant ao_control
   participant ao_safety
   participant ao_diagnostics
   
   ao_runtime_supervisor -> evt_dispatcher : dispatch cycle
   alt degraded entry criteria met
     note over ao_runtime_supervisor: init_timeout OR required_service_failed OR fatal_fault
     ao_runtime_supervisor -> ao_control : EVT_DEGRADED
     ao_runtime_supervisor -> ao_safety : EVT_DEGRADED
     ao_runtime_supervisor -> ao_diagnostics : EVT_DEGRADED
     ao_runtime_supervisor -> evt_dispatcher : restrict noncritical events
   end
   
   ao_runtime_supervisor -> evt_dispatcher : periodic degraded dispatch
   
   alt recovery criteria met
     note over ao_runtime_supervisor: fault_cleared AND watchdog_ok AND required_services_ready
     ao_runtime_supervisor -> evt_dispatcher : EVT_RESET
     ao_runtime_supervisor -> ao_control : EVT_RECOVERY
     ao_runtime_supervisor -> ao_safety : EVT_RECOVERY
     ao_runtime_supervisor -> ao_diagnostics : EVT_RECOVERY
   end
   @enduml


Lifecycle sequence for degraded entry triggers and guarded recovery back to Run.


SEQ-007_Controlled_Shutdown
^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. uml::

   @startuml
   hide footbox
   participant ao_runtime_supervisor
   participant evt_dispatcher
   participant ao_control
   participant ao_safety
   participant ao_diagnostics
   participant ao_modbus_server
   
   ao_runtime_supervisor -> evt_dispatcher : EVT_SHUTDOWN_REQ
   ao_runtime_supervisor -> ao_control : stop outputs to safe state
   ao_runtime_supervisor -> ao_safety : keep protective policy active
   ao_runtime_supervisor -> ao_diagnostics : publish shutdown status
   ao_runtime_supervisor -> ao_modbus_server : stop comm servicing
   
   ao_modbus_server --> ao_runtime_supervisor : EVT_STOPPED
   ao_diagnostics --> ao_runtime_supervisor : EVT_STOPPED
   ao_safety --> ao_runtime_supervisor : EVT_STOPPED
   ao_control --> ao_runtime_supervisor : EVT_STOPPED
   evt_dispatcher --> ao_runtime_supervisor : EVT_STOPPED
   
   ao_runtime_supervisor -> ao_runtime_supervisor : EVT_ALL_STOPPED / Shutdown complete
   @enduml


Controlled shutdown sequence defining stop ordering and completion criteria.