Command Context Registry

class ska_csp_lmc_common.observation.command_context_registry.CommandContextRegistry(logger: Logger)

Bases: object

Registry managing command contexts and active-command lifecycle.

This class encapsulates the storage, activation, update, and cleanup of command contexts used by the observation supervisor.

The registry normally tracks a single active command context. Abort is treated as a special case: it may overlap with a previously active command, which is then marked as overridden instead of being removed immediately.

set_active(context: CommandContext) → None

Register a command context and make it the active one.

Under normal operation, at most one non-Abort command context should exist at a time. Abort is the only command allowed to overlap with an already active command.

If a new non-Abort command is registered while another context is still active, the previous one is discarded as a defensive cleanup measure. This is not the expected nominal flow, but it prevents the registry from retaining multiple incompatible active contexts.

If the new command is Abort, the previously active context is preserved and marked as overridden, so that its delayed outcome can still be processed.

Parameters:

context – Command context to register.

Raises:

ValueError – If context.command_id is empty.

update_outcome(command_id: str, command_outcome: CommandOutcome, completion_time: datetime) → bool

Update the terminal outcome of a registered command context.

If the updated context is no longer active and had been overridden, it is removed after the update.

Parameters:

• command_id – Command identifier.

• command_outcome – Final outcome to store.

• completion_time – Completion timestamp.

Returns:

True if the context was found and updated, else False.

get_active() → CommandContext | None

Return the currently active command context, if any.

clear_completed_active() → None

Remove the active command context once it has a terminal outcome.

This intentionally keeps in-flight command contexts alive until a conclusive supervisor decision has been applied after completion.

retain_scan_context_if_needed(context: CommandContext) → None

Retain a completed Scan context for post-scan lifecycle evaluation.

Only Scan contexts whose command task reached TaskStatus.COMPLETED are retained. This applies to both legacy and scheduled Scan commands.

A completed Scan task may still have a non-OK result code (partial execution). Such contexts are retained because they still represent a valid Scan lifecycle that may need to be considered by the observation policy after the command has completed.

Scan tasks ending in TaskStatus.FAILED or TaskStatus.ABORTED are not retained, because they did not complete normally and therefore must not establish a retained Scan lifecycle.

Retained Scan contexts are cleared by the supervisor lifecycle management: a new Scan command clears any previously retained Scan context before being registered; successful EndScan and Abort commands explicitly clear the retained context; legacy Scan contexts are also cleared once the subarray settles outside SCANNING. Scheduled Scan contexts may remain retained across their pending and active phases, and are cleared once the scheduled Scan lifecycle has completed or when an explicit successful clear event occurs.

clear_retained_scan_context() → None

Clear the retained Scan command context.

get_retained_scan_context() → CommandContext | None

Return the retained Scan context when still valid.

Retained Scan contexts remain available until they are explicitly cleared by Scan lifecycle management. This allows scheduled scans to stay active across the initial pending phase in READY and across the post-duration transition back to READY.

get_scan_lifecycle_context() → CommandContext | None

Return the currently relevant Scan lifecycle context, if any.

The active command context takes precedence when it is itself a Scan command. Otherwise, the retained Scan context is returned.

This allows callers such as Tango command-allowed hooks to detect an ongoing Scan lifecycle even when the CSP observing state is still READY during the pending phase of a scheduled scan.

has_active_scan_lifecycle() → bool

Return whether a Scan lifecycle is currently active.