Command context lifecycle
=========================

The command context lifecycle follows the lifecycle of a long-running command,
but it is not identical to it.

A command context is created when a command is accepted by the component manager
and the command execution layer starts tracking it. At this point the context is
registered as an ``active command context`` and can be used by the observation
supervisor during observation state evaluation.


Command context builder
-----------------------

The command context is created by the command context builder.

The builder is responsible for translating the accepted command and the current
observation configuration into a ``CommandContext`` instance. This is the point
where the runtime metadata required by the observation supervision layer is
collected and associated with the command.

The builder can populate the context with information such as:

* the command name;
* the long-running command identifier;
* the devices selected for the command;
* the command semantics derived from the configured observation mode;
* command-specific metadata, such as the scan schedule.

The command context builder is also an important extension point. It separates
the creation of command semantics from the observation consistency policy that
uses them. This makes it possible to move from hard-coded command interpretation
towards a configuration-driven model, for example by deriving command semantics
and policy inputs from a YAML configuration file.

In this model, the builder prepares the command context according to the
configured rules, while the consistency policies consume the resulting context
without needing to know how the command semantics were produced.

The relationship can be summarised as follows::

    Accepted command
        -> command context builder invoked

    Current observation configuration
        -> used to derive command semantics

    Optional YAML configuration
        -> defines command-to-policy mapping and semantic rules

    CommandContext created
        -> stores command metadata, selected devices, and semantics

    Observation consistency policy
        -> consumes the CommandContext during state evaluation


Runtime usage
-------------

While the command is running, the context identifies the command currently
affecting the observation state. This allows the consistency policy to interpret
intermediate device states in the correct command-specific way. For example, a
transition caused by ``Scan`` is not interpreted in the same way as a transition
caused by ``EndScan`` or ``Abort``.

When the command completes, the command outcome is stored in the command
context. The outcome includes the command result and the devices that succeeded
or failed, when this information is available. The completed command context is
then removed from the active command context registry.

For most commands, this is the end of the command context lifecycle. Once the
command outcome has been recorded and the context has been removed from the
active registry, the context is discarded.

The default lifecycle can be summarised as follows::

    Command accepted
        -> CommandContext created by the builder
        -> context registered as active

    Command running
        -> context used by the observation supervisor
        -> context used by command-aware consistency policies

    Command completed
        -> command outcome stored in the context
        -> context removed from active command registry

    Completed command handled
        -> context discarded

The ``Scan`` command is a special case. A completed scan command may still be
relevant to observation state consistency after it has been removed from the
active command registry. For this reason, scan-specific command context
retention is described separately in :doc:`scan/retained_scan_context`.