Retained Scan Context

The retained Scan context is an internal observation-supervision mechanism used to preserve the lifecycle information of a completed Scan command beyond the end of the command execution itself.

This is required because the completion of the Scan command does not always coincide with the completion of the observation-state transition driven by that command. In particular, subsystem observation-state events are asynchronous and may arrive after the command task has already completed. The retained context allows the observation supervisor to continue evaluating the expected Scan lifecycle using the command that initiated it.

The retained Scan context is not a command tracker. It does not indicate that a Scan command is still running. Instead, it records that a completed Scan command has established an observation lifecycle that may still need to be evaluated by the observation policy.

The scan lifecycle depends on the scan type. Legacy Scans are expected to start immediately, while scheduled Scans can remain pending after the Scan command has completed. Scheduled Scan semantics are described in Scheduled scan.

The retained Scan context must not be treated as a generic cache. It is part of the runtime contract between command execution, observation supervision, and scan-consistency evaluation.

Terminology

Legacy Scan

A legacy Scan is a Scan command whose accepted payload does not define any scheduling information.

In practical terms, a Scan is considered legacy when both of the following fields are absent from the accepted Scan payload:

start_time;
duration.

A legacy Scan is expected to start immediately from the point of view of CSP.LMC. After the command completes, the retained Scan context may still be required to evaluate the asynchronous transition of the involved subsystems to SCANNING and, later, the transition back to READY.

Scheduled Scan

A scheduled Scan is a Scan command whose accepted payload contains scheduling information.

The scheduling information may be provided in one of the following forms:

start_time only;
duration only;
both start_time and duration.

The exact lifecycle depends on which fields are present:

with start_time only, the Scan has a scheduled start but no scheduled end;
with duration only, the Scan starts immediately and has a scheduled end;
with both start_time and duration, the Scan has both a scheduled start and a scheduled end.

For scheduled Scans, the retained context is especially important because the Scan command may complete before the scheduled start or before all involved subsystems have published the expected observation-state transitions. A start_time in the past does not invalidate a scheduled Scan. Such a Scan is accepted and behaves as a scheduled Scan whose scheduled start has already elapsed. The subsystems should consider it as start immediately.

Purpose

The retained Scan context allows the observation supervisor to answer the following questions after the Scan command has completed:

which command initiated the current Scan lifecycle;
which devices were involved in the accepted Scan command;
which devices successfully received or completed the command;
whether the Scan was legacy or scheduled;
which observation states are expected from the involved subsystems;
whether CSP.LMC should continue waiting, apply an observation-state update, or report a consistency fault.

Without the retained context, the observation policy would lose the command semantics as soon as the Scan command completed. This would make it difficult to distinguish between a normal asynchronous Scan transition and an inconsistent subsystem state.

The retained context allows the supervisor to distinguish between:

an expected scan-related transition;
an inconsistent device state distribution;
a completed scan lifecycle;
a pending scheduled Scan that has been accepted but has not started yet.

Creation rules

A retained Scan context is created only from a completed Scan command context.

The context is eligible for retention when all of the following conditions are true:

the command is Scan;
the command has a command outcome;
the command task reached TaskStatus.COMPLETED.

The command result code does not need to be ResultCode.OK for the context to be retained. A completed Scan task may have a non-OK result code when execution was partial or degraded. Such a context can still represent a valid Scan lifecycle and may still be needed by the observation policy.

A Scan context is not retained when the command task ends in TaskStatus.FAILED or TaskStatus.ABORTED. In those cases, the command did not complete normally and must not establish a retained Scan lifecycle.

A Scan context is also not retained when the observation policy has already decided to apply FAULT for the active Scan lifecycle. In that case, the Scan lifecycle has ended abnormally and retaining the context would risk evaluating a failed lifecycle again during recovery.

The creation lifecycle can be summarised as follows:

Scan command accepted
    -> Scan CommandContext created
    -> context registered as active

Scan command task completed
    -> command outcome stored in the context
    -> context removed from active command registry
    -> context retained as retained_scan_context

Scan command task failed or aborted
    -> context removed from active command registry
    -> context not retained

Scan consistency policy applies FAULT
    -> context removed from active command registry
    -> context not retained

Legacy Scan behaviour

For a legacy Scan, the retained context is used after command completion to continue evaluating the subsystem observation-state transitions associated with the Scan.

The expected behaviour is:

Scan is accepted and executed.
The command task completes.
If the task status is TaskStatus.COMPLETED, the Scan context is retained.
The observation supervisor continues to evaluate subsystem events using the retained context.
CSP.LMC remains or moves to SCANNING while the successful Scan devices are expected to be scanning.
Once the Scan lifecycle is no longer active and the subarray settles outside SCANNING, the legacy retained context can be cleared.

For legacy Scans, the retained context is therefore a bridge between command completion and observation-state convergence. It prevents CSP.LMC from losing the command-specific expectations while subsystem events are still being processed.

The legacy Scan retained context lifecycle can be summarised as follows:

Legacy Scan command accepted
    -> Scan CommandContext created
    -> context registered as active

Scan command task completed
    -> command outcome stored in the context
    -> context removed from active command registry
    -> context retained as retained_scan_context

CSP Subarray is SCANNING
    -> retained_scan_context used by the scan consistency policy

EndScan or Abort completes successfully
    -> retained_scan_context cleared

or

Supervisor detects that the legacy Scan lifecycle is complete
    -> retained_scan_context cleared

Scheduled Scan behaviour

For a scheduled Scan, the retained context may be needed for a longer interval than for a legacy Scan.

The command may complete while the Scan is still before its scheduled start, or while CSP.LMC is still waiting for subsystem observation states to converge. The retained context allows the supervisor to continue evaluating the schedule and the expected subsystem states after command completion.

The expected behaviour is:

Scan is accepted with scheduling information.
The command task completes.
If the task status is TaskStatus.COMPLETED, the Scan context is retained.
Before the scheduled start, CSP.LMC remains in the appropriate pre-start state, normally READY.
Around or after the scheduled start, the supervisor expects the successful Scan devices to transition to SCANNING.
CSP.LMC transitions to SCANNING when the policy determines that the Scan lifecycle has effectively started according to the configured semantics.
If a scheduled end is known, the supervisor later expects the successful Scan devices to return to READY.
Once the scheduled Scan lifecycle has completed, the retained context can be cleared.

For scheduled Scans, the retained context therefore preserves both the command semantics and the schedule-derived lifecycle information.

For the complete scheduled Scan lifecycle and pending Scan semantics, see Scheduled scan.

Clearing rules

The retained Scan context is cleared when it is no longer valid or no longer needed.

The retained context is cleared in the following cases:

before registering a new Scan command;
after a successful EndScan command;
after a successful Abort command;
when a legacy Scan lifecycle has settled outside SCANNING;
when a scheduled Scan lifecycle has completed or expired according to its schedule and policy rules;
when the observation policy applies FAULT for the active Scan lifecycle.

A successful EndScan or Abort command clears the retained context only when the command result code is ResultCode.OK. If these commands complete with a non-OK result code, the retained context is preserved because the Scan lifecycle may not have been closed cleanly.

A new Scan command always invalidates any previously retained Scan context. This prevents a previous Scan lifecycle from influencing the evaluation of a new one.

The cleanup logic for scheduled Scans must not depend on a time-based retention window alone. The retained context is part of the observation lifecycle and should be removed based on lifecycle completion, not simply because a timeout has expired.

Recovery commands

Recovery commands such as Abort, ObsReset and Restart must not be blocked by stale Scan lifecycle information.

When a recovery command is active, the observation supervisor must avoid applying the retained Scan context as if the previous Scan lifecycle were still the primary source of observation-state expectations. Otherwise, the retained context could cause CSP.LMC to keep evaluating the previous Scan during recovery and could keep scan-consistency diagnostics latched.

This is particularly important after a Scan consistency fault. Once the policy has decided to apply FAULT, the Scan lifecycle is considered abnormal and the corresponding Scan context must not be retained for later recovery evaluation.

Summary

The retained Scan context is created to preserve Scan lifecycle information after the Scan command has completed. It is required because command completion and observation-state convergence are asynchronous and do not necessarily happen at the same time.

For legacy Scans, the retained context mainly bridges the gap between immediate Scan command completion and subsystem observation-state convergence.

For scheduled Scans, the retained context also preserves the schedule-dependent lifecycle, including pre-start, active Scan and scheduled completion phases.

The retained context is cleared when the Scan lifecycle is explicitly closed, superseded by a new Scan, completed according to the relevant policy, or invalidated by a fault or recovery path.