Lifecycle and Progress Reporting

This page describes how the Task Tracker models the lifecycle of a long-running command and how execution progress is computed and reported to consumers.

It focuses on observable state transitions, progress semantics, and completion guarantees, independently of the specific aggregation rules used to determine command success or failure.

Execution Lifecycle

A long running command (LRC) tracked by the Task Tracker follows a well-defined lifecycle.

From the point of view of observable state transitions, the typical sequence is:

  • QUEUED: the command has been accepted but execution has not yet started;

  • IN_PROGRESS: one or more tasks are executing;

  • a final state among COMPLETED, FAILED, REJECTED or ABORTED.

The following guarantees apply:

  • exactly one completion notification is emitted;

  • progress notifications are never emitted after completion;

  • late or duplicate updates from completed tasks are ignored.

Progress Computation and Reporting

Overall command progress is computed by aggregating per-task progress values.

The aggregation rules are:

  • completed tasks contribute 100;

  • tasks without explicit progress information contribute 0;

  • overall progress is computed as the mean across all expected tasks.

Progress reporting is best-effort and intentionally throttled:

  • progress values are quantized to a fixed step (default: 10%);

  • a progress notification is emitted only when the quantized value changes;

  • progress notifications are emitted only while the command is not completed;

  • the final progress value (100) is included only in the completion notification.

Progress reporting is intentionally approximate and should not be used to infer detailed execution timing or task ordering.

As a consequence, the number and timing of progress notifications are not deterministic and should be treated as informational.

Completion Semantics and Context Propagation

The completion notification represents the authoritative outcome of the command execution.

During execution, the Task Tracker may emit progress updates, which should be treated as informational only. Consumers must rely exclusively on the completion notification to determine the final outcome of a command.

The completion notification is emitted exactly once and marks the end of command execution. It includes:

  • the final task status;

  • the aggregated result code and message;

  • the final progress value;

  • structured execution context when available.

The completion notification should be treated as the definitive signal that command execution has finished. Consumers should not infer final outcomes from intermediate progress or partial updates.

To improve observability and diagnostics, the Task Tracker may include:

  • devices: all devices involved in the execution;

  • failed_devices: the subset of devices that failed;

  • health_state: an aggregated health indicator.

Partial Failure Scenarios

The Task Tracker explicitly supports partial failure scenarios.

In these cases:

  • a command may return a FAILED result;

  • the device may still transition to a valid operational state (e.g. IDLE);

  • the failure reflects partial execution or resource allocation issues.

This behavior is expected and intentional. Command results and device state transitions must therefore be interpreted independently, using the propagated execution context to understand the nature of the failure.