Examples and Scenarios
======================


Example: PST group task with partial success
--------------------------------------------

Consider a task that configures multiple PST beams in parallel. Each beam
configuration is represented by an independent subtask.
This task is treated as a PST group task; therefore, quorum-like
aggregation rules apply.

Assume the following execution outcome:

+-------------+--------------------+------------+
| Subtask     | Status             | ResultCode |
+=============+====================+============+
| PST beam 1  | COMPLETED          | OK         |
+-------------+--------------------+------------+
| PST beam 2  | FAILED             | FAILED     |
+-------------+--------------------+------------+
| PST beam 3  | FAILED             | FAILED     |
+-------------+--------------------+------------+

In this scenario:

- at least one PST subtask completed successfully;
- other PST subtasks failed, but the system remains partially operational.

The aggregation policy produces the following outcome:

- **TaskStatus**: ``COMPLETED``
- **ResultCode**: ``FAILED``
- **Health state**: ``DEGRADED``
- **Message**: indicates partial execution and lists failed PST devices
  and associated causes.

Note that ``COMPLETED`` indicates that the command reached a terminal
state, not that it executed successfully on all PST beams.

This allows downstream components to proceed while still being informed
that the operation completed in a degraded condition.

Further details on aggregated message semantics are described in
:ref:`aggregated-message-semantics`.

Aggregation outcome summary for PST group tasks
-----------------------------------------------

The table below summarizes how the aggregation policy evaluates PST group
tasks based on the outcome of individual PST subtasks.

.. list-table:: Aggregation outcome summary for PST group tasks
   :header-rows: 1
   :widths: 30 25 35

   * - PST subtasks outcome
     - Aggregated status
     - Aggregated result
   * - All FAILED
     - FAILED or COMPLETED (severity dependent)
     - FAILED (health state FAILED)
   * - Some OK, some FAILED
     - COMPLETED
     - FAILED (health state DEGRADED)
   * - All OK
     - COMPLETED
     - OK
     
Partial success semantics allow a task to complete even when only a subset
of PST subtasks succeed, provided that at least one PST beam is correctly
configured.

Notes:

- "Some OK, some FAILED" represents a **partial success** scenario.
- In partial success cases, the aggregated message reports failed devices
  and failure causes.
- The task may be associated with a ``DEGRADED`` health state, depending on
  the severity and origin of the failures.

Implications for consumers
--------------------------

Because the aggregation policy encodes domain rules, consumers should:

- use the completion status and result code as the authoritative command
  outcome;
- use ``devices`` and ``failed_devices`` for deterministic diagnostics;
- treat the aggregated message content (including specific cause strings)
  as best-effort, informational output subject to refinement as the policy
  evolves.