Aggregation Policy

This section describes how the Task Tracker aggregates subtask updates into a single command outcome.

The aggregation logic is delegated to the TaskAggregationPolicy and operates on collections of SubtaskResult objects.

Aggregation rules and precedence

Note

The current aggregation policy represents an initial proposal and is expected to be reviewed and refined. Consumers should treat the output semantics as stable at a high level (completion vs progress, device lists, and presence of contextual fields), but should not rely on the exact wording or precedence rules of the aggregated message.

The current policy applies a set of precedence rules to determine the final outcome. The main goals are:

  • ensure critical subsystem failures dominate the task outcome;

  • support partial-success semantics for PST group operations;

  • report non-critical failures as degraded outcomes where applicable.

The key rules are:

  1. Aborted dominates If any subtask is ABORTED, the overall outcome is ABORTED.

  2. In-progress dominates If any subtask is IN_PROGRESS, the overall outcome is IN_PROGRESS (result typically STARTED).

  3. CBF failures dominate If a CBF-associated subtask fails or is rejected, the overall outcome is FAILED / REJECTED respectively, regardless of other subsystem results.

  4. PST group tasks apply quorum-like logic For tasks identified as PST group tasks (based on task name patterns), partial success may be treated as acceptable. The current identification relies on task naming conventions and may be refined in future iterations.

    • if all PST subtasks fail → overall failure (severity depends on whether failures are abnormal);

    • if some PST subtasks succeed → overall COMPLETED with an FAILED result, but with a message indicating degraded/partial execution.

  5. Remaining failures For failures outside of the above rules:

    • severe failures lead to overall FAILED with health FAILED;

    • other failures may lead to COMPLETED with a failure result and health DEGRADED.

  6. No failures If no subtask failures are detected, the overall outcome is COMPLETED with OK result.

CBF rejection result normalization

When a CBF-associated subtask is rejected, the aggregation policy always produces an aggregated outcome with:

  • TaskStatus.REJECTED;

  • a non-UNKNOWN ResultCode.

If the originating CBF subtask reports ResultCode.UNKNOWN (or does not provide a meaningful result code), the aggregation policy normalizes the result to ResultCode.REJECTED.

This ensures that aggregated outcomes are semantically consistent and do not propagate UNKNOWN result codes in terminal states.

Any more specific CBF result codes (e.g. NOT_ALLOWED) are preserved when available.

This normalization currently applies only to CBF rejections and is intended to avoid ambiguous outcomes (TaskStatus.REJECTED with an UNKNOWN result code).

Note

At present, result-code normalization is implemented only for CBF rejection outcomes. Other subsystems may still propagate UNKNOWN result codes depending on the producer behaviour.

Device classification and failure reporting

For reporting and diagnostics, failed devices are classified by subsystem. Classification is based on substring matching against the device name:

  • devices containing cbf → CBF

  • devices containing pst → PST

  • devices containing pss → PSS

  • otherwise → OTHER

The policy builds deterministic device lists:

  • duplicates are removed while preserving order;

  • final payloads use stable ordering (typically sorted by the tracker).

Failure causes extraction

In addition to device lists, the policy extracts human-readable failure causes from the subtask messages and normalizes them into a single consolidated list.

Normalization rules include:

  • stripping an outer "Causes:" header when present;

  • flattening bullet lists (lines starting with -);

  • removing empty lines;

  • removing duplicates while preserving order.

The aggregated message uses a single consolidated Causes: block, with one bullet per normalized cause line.

Further details on aggregated message semantics are described in Aggregated message semantics.