Rewrite lifecycle page with complete state transition tables

The previous table was missing shelved, blackout, and expired statuses,
the unack/unshelve/close/open actions, severity change transitions,
system actions, and blackout/plugin override behavior.

Derived from the actual state machine in alerta/models/alarms/alerta.py.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: satterly

source/lifecycle.rst

@@ -1,17 +1,137 @@
+.. _lifecycle:
+
+Alert Lifecycle
+===============
+
+Alerta uses a state machine to manage alert status transitions. The status
+of an alert changes automatically based on incoming severity changes or
+explicitly via operator actions.
+
+Statuses
+--------
+
++-----------------+----------------------------------------------------------+
+| Status          | Description                                              |
++=================+==========================================================+
+| ``open``        | Alert is new or has been re-opened                       |
++-----------------+----------------------------------------------------------+
+| ``assign``      | Alert has been assigned (placeholder, no transitions)    |
++-----------------+----------------------------------------------------------+
+| ``ack``         | Alert has been acknowledged by an operator               |
++-----------------+----------------------------------------------------------+
+| ``shelved``     | Alert has been shelved (temporarily hidden)              |
++-----------------+----------------------------------------------------------+
+| ``blackout``    | Alert was received during a blackout period              |
++-----------------+----------------------------------------------------------+
+| ``closed``      | Alert has been closed (normal severity or by operator)   |
++-----------------+----------------------------------------------------------+
+| ``expired``     | Alert was not updated within its timeout period          |
++-----------------+----------------------------------------------------------+
+
+Actions
+-------
+
++------------------+---------------------------------------------------------+
+| Action           | Description                                             |
++==================+=========================================================+
+| ``open``         | Re-open a closed, ack'd or expired alert                |
++------------------+---------------------------------------------------------+
+| ``ack``          | Acknowledge an open alert                               |
++------------------+---------------------------------------------------------+
+| ``unack``        | Un-acknowledge, returns to previous status               |
++------------------+---------------------------------------------------------+
+| ``shelve``       | Shelve an open or ack'd alert                           |
++------------------+---------------------------------------------------------+
+| ``unshelve``     | Un-shelve, returns to previous status                   |
++------------------+---------------------------------------------------------+
+| ``close``        | Close an alert (sets severity to normal)                |
++------------------+---------------------------------------------------------+
+| ``expired``      | System action when alert times out                      |
++------------------+---------------------------------------------------------+
+| ``timeout``      | System action on ack/shelve timeout                     |
++------------------+---------------------------------------------------------+
 
 State Transition Table
-~~~~~~~~~~~~~~~~~~~~~~
-
-+-------------+----------------+--------------+-----------+------------+------------+-------------+
-| Status      | non-``normal`` | user ``ack`` | new > old | new <= old | ``normal`` | timeout     |
-+=============+================+==============+===========+============+============+=============+
-| ``open``    | ``open``       |   ``ack``    |           |            | ``closed`` | ``expired`` |
-+-------------+----------------+--------------+-----------+------------+------------+-------------+
-| ``ack``     |                |              | ``open``  |  ``ack``   | ``closed`` |             |
-+-------------+----------------+--------------+-----------+------------+------------+-------------+
-| ``assign``  |                |              |           |            |            |             |
-+-------------+----------------+--------------+-----------+------------+------------+-------------+
-| ``closed``  | ``open``       |              |           |            | ``closed`` |             |
-+-------------+----------------+--------------+-----------+------------+------------+-------------+
-| ``expired`` | ``open``       |              |           |            | ``closed`` |             |
-+-------------+----------------+--------------+-----------+------------+------------+-------------+
+----------------------
+
+The table below shows the resulting status for each combination of current
+status and trigger (operator action or severity change). Empty cells mean
+the transition is not valid or the status remains unchanged.
+
+**Operator Actions**
+
++------------------+------------+------------+------------+------------+------------+
+| Current Status   | ``open``   | ``ack``    | ``unack``  | ``shelve`` | ``close``  |
++==================+============+============+============+============+============+
+| ``open``         | *invalid*  | ``ack``    | *invalid*  | ``shelved``| ``closed`` |
++------------------+------------+------------+------------+------------+------------+
+| ``ack``          | ``open``   | *invalid*  | *previous* | ``shelved``| ``closed`` |
++------------------+------------+------------+------------+------------+------------+
+| ``shelved``      | ``open``   | *invalid*  | *invalid*  | *invalid*  | ``closed`` |
++------------------+------------+------------+------------+------------+------------+
+| ``blackout``     |            |            |            |            | ``closed`` |
++------------------+------------+------------+------------+------------+------------+
+| ``closed``       | ``open``   | *invalid*  |            | *invalid*  | *invalid*  |
++------------------+------------+------------+------------+------------+------------+
+| ``expired``      | ``open``   | *invalid*  |            |            |            |
++------------------+------------+------------+------------+------------+------------+
+
+.. note::
+    ``unack`` returns to the status the alert had before it was acknowledged.
+    ``unshelve`` returns to the status the alert had before it was shelved.
+
+**Severity Changes** (automatic, no operator action)
+
++------------------+---------------------+-------------------+--------------------+
+| Current Status   | More severe         | Less severe       | Normal severity    |
++==================+=====================+===================+====================+
+| ``open``         | ``open``            | ``open``          | ``closed``         |
++------------------+---------------------+-------------------+--------------------+
+| ``ack``          | ``open`` |dagger|   | ``ack``           | ``closed``         |
++------------------+---------------------+-------------------+--------------------+
+| ``shelved``      | ``shelved``         | ``shelved``       | ``closed``         |
++------------------+---------------------+-------------------+--------------------+
+| ``blackout``     | *previous*          | *previous*        | ``closed``         |
++------------------+---------------------+-------------------+--------------------+
+| ``closed``       | ``open`` |ddagger|  | ``closed``        | ``closed``         |
++------------------+---------------------+-------------------+--------------------+
+| ``expired``      | ``open``            | ``open``          | ``closed``         |
++------------------+---------------------+-------------------+--------------------+
+
+.. |dagger| unicode:: U+2020
+.. |ddagger| unicode:: U+2021
+
+|dagger| An ack'd alert is re-opened only if the severity genuinely increases
+(ie. the previous severity was not the default ``indeterminate``).
+
+|ddagger| A closed alert re-opens to ``shelved`` if it was previously shelved
+before being closed.
+
+**System Actions**
+
++------------------+-----------------------------------------------------+
+| Action           | Result                                              |
++==================+=====================================================+
+| ``expired``      | Any status -> ``expired``                           |
++------------------+-----------------------------------------------------+
+| ``timeout``      | If previously ``ack`` -> ``ack``, otherwise ``open``|
++------------------+-----------------------------------------------------+
+
+**Blackout Transitions**
+
+When a blackout period ends, the alert returns to the status it had before
+the blackout began. If the alert was created during a blackout (no previous
+status), it transitions based on the current severity.
+
+**Custom Actions**
+
+Unrecognised actions (ie. custom actions defined by plugins via the
+``take_action`` hook) do not trigger any state transition. The severity
+and status are returned unchanged.
+
+**Plugin Overrides**
+
+If a ``pre_receive()`` plugin sets a non-default status on the alert, the
+state machine respects that status and skips the normal transition logic.
+The only exception is normal-severity alerts, which are always auto-closed
+regardless of the plugin-set status.