Scan consistency policy ======================= The scan consistency policy defines the CSP-specific rules used to validate subsystem behaviour while a CSP.LMC Subarray is scanning. It is a specialisation of the base observation consistency policy. The base policy defines the generic CSP.LMC behaviour for detecting, representing, and handling observation inconsistencies. The scan policy reuses that behaviour and adds the rules required to evaluate scan-specific state distributions. The scan policy determines whether scanning: * can continue normally; * can continue in a degraded condition; * should wait for a more conclusive subsystem state distribution; * must transition to ``FAULT`` because the inconsistency is non-recoverable. When the policy is evaluated ---------------------------- The scan policy is evaluated while the aggregated CSP.LMC Subarray ``ObsState`` is ``SCANNING``. It is also evaluated when the aggregated state unexpectedly collapses from ``SCANNING`` to ``EMPTY`` or ``IDLE``. This allows the policy to classify restart-like conditions even when the aggregation has already dropped out of ``SCANNING``. Scheduled scans extend this evaluation model because a scheduled scan can be accepted while the CSP.LMC Subarray is still ``READY``. The scheduled scan extension is described in :doc:`scan_scheduled_policy`. Scan-specific behaviour ----------------------- During evaluation, the scan policy: * refines the set of required subsystems according to the active observing modes; * filters out subsystem components that are not relevant to the current scan; * classifies subsystems whose ``ObsState`` is not ``SCANNING``; * delegates generic inconsistency handling to the base policy model; * produces a policy decision containing the final state, action, severity, and diagnostic message. The scan policy should be read as an extension of the base policy, not as an independent consistency model. Command-aware scan evaluation ----------------------------- Scan consistency evaluation is command-aware when a retained ``Scan`` ``CommandContext`` is available. In this mode, the policy does not infer the scan target set only from the current subsystem snapshot or from the currently reported observing modes. Instead, it uses the runtime information captured in the ``Scan`` command context when the scan lifecycle started. The retained scan context provides: * the observing modes requested by the accepted ``Scan`` command; * the planned devices selected for the scan; * the command semantics associated with the scan; * the rules (family rules) used to interpret subsystem roles and thresholds. The command semantics are described generally in :doc:`../command_context/semantics` and summarised below from the scan policy point of view. The policy uses this information to select the observation devices that are relevant to the accepted scan and to evaluate only those devices against the accepted scan states. This ensures that scan consistency is evaluated using the same command semantics and the same planned device set that were used when the scan command was accepted. Command semantics ----------------- The scan policy uses the command semantics stored in the retained ``Scan`` ``CommandContext`` to interpret subsystem states during scan consistency evaluation. For scan consistency, the semantics identify the subsystem families that are relevant to the accepted scan and associate each family with a policy role. The role defines how inconsistencies in that family contribute to the final policy decision. Typical roles include: ``core`` A subsystem family that is essential for the command semantics. A failure in a core family is normally treated as policy-critical. The CBF subsystem is always assigned to this role ``primary`` A subsystem family that defines the main observation path for the accepted command. Primary family failures can determine whether the scan remains valid or must transition to ``FAULT``. ``commensal`` A subsystem family that participates in the observation together with the primary family, but does not define the main observation path on its own. Failures in commensal families can be reported as degraded scan conditions, depending on the configured command semantics. The semantics can also provide thresholds. A threshold defines how many failures are tolerated for a subsystem family before the inconsistency becomes policy-critical. By using the family rules stored in the command context, the policy evaluates subsystem inconsistencies according to the meaning of the accepted command, rather than applying the same hard-coded rule to every scan. Planned device selection ------------------------ When a retained ``Scan`` command context is available, the set of devices to validate is selected from the planned devices stored in the context. The planned devices are the devices that command execution selected for the accepted scan. They are already constrained by the command preparation logic and by the effective configured device set. The scan consistency policy combines the planned devices with the command semantics to identify the devices that are relevant to the observation. The command-aware flow can be summarised as follows:: Retained Scan CommandContext available -> requested observing modes read from the context -> planned devices read from the context -> command semantics read from the context Relevant scan devices selected -> planned devices filtered according to command semantics -> family rules applied to subsystem families Scan consistency evaluated -> only command-relevant devices are checked -> invalid devices classified using semantic family rules -> policy decision produced This prevents the policy from evaluating devices that are present in the snapshot but are not part of the accepted scan lifecycle. Legacy fallback --------------- The previous required-subsystem and subsystem-filtering logic is still used as a fallback when no retained ``Scan`` command context is available. This fallback is defensive. It preserves compatibility with legacy or observed scan evaluation paths where the policy has to infer the relevant subsystem set from the currently reported observing modes and from the subsystem snapshot. In the fallback path, the policy: * refines the default required subsystem families according to the active observing modes; * selects subsystem components whose FQDN matches one of the required subsystem family tokens; * resolves scan family rules from the current observing modes and the selected subsystem families; * evaluates the selected subsystem components against the accepted scan states. The default required subsystem set used by the fallback path is: * ``cbf`` * ``pss`` * ``pst`` This set is refined dynamically from the active observing modes: * if ``PULSAR_TIMING`` is not active, ``pst`` is not required; * if neither ``PULSAR_SEARCH`` nor ``TRANSIENT_SEARCH`` is active, ``pss`` is not required. This fallback should not be described as the primary scan selection mechanism for command-aware scans. For command-aware scan lifecycle evaluation, the retained ``Scan`` command context and its semantics are the source of truth. Subsystem filtering fallback ---------------------------- When the fallback path is used, subsystem filtering is based on the required subsystem family tokens inferred from the current observing modes. Only subsystem components matching one of the required family tokens are included in the fallback consistency check. Components that do not match the required families are ignored for that evaluation. This behaviour exists to support scan consistency evaluation when command context information is not available. When a retained ``Scan`` command context is available, device selection is instead driven by the planned devices and by the command semantics stored in the context. Classification of scan inconsistencies -------------------------------------- Each required subsystem whose ``ObsState`` differs from ``SCANNING`` is classified into a structured inconsistency containing: * the subsystem FQDN; * the observed ``ObsState``; * a diagnostic code; * a human-readable description; * a severity. Examples of classified conditions include: * subsystem timing mismatches; * unexpected restarts; * subsystem faults; * generic state mismatches. PST handling ------------ PST inconsistencies are handled separately from other subsystems because their impact depends on the active observing modes. PULSAR_TIMING-only scans ~~~~~~~~~~~~~~~~~~~~~~~~ When the active observing mode set is exactly ``{PULSAR_TIMING}``, PST beams are treated as fault-critical for the scan. The policy computes a PST failure threshold from the number of PST beams participating in the scan: * if only one PST beam is present, the threshold is ``0`` and failure of that beam is sufficient to trigger ``FAULT``; * otherwise, the threshold is ``pst_count // 2``. A ``FAULT`` decision is generated only when the number of failing PST beams is strictly greater than the threshold. If the threshold is not exceeded, the scan can continue and the individual PST beam inconsistencies are reported with their own severity. Commensal observing modes ~~~~~~~~~~~~~~~~~~~~~~~~~ When ``PULSAR_TIMING`` is active together with one or more additional observing modes, PST inconsistencies do not force the CSP Subarray ``ObsState`` to ``FAULT`` on their own. In this case, PST failures are treated as degraded commensal scan conditions: * PST beam inconsistencies are downgraded to ``MEDIUM`` severity; * a warning is logged explaining that scanning can continue because the observation is not ``PULSAR_TIMING``-only; * the scan continues for the non-PST observing modes that remain active. Diagnostic reporting -------------------- When inconsistencies are detected, the policy builds a human-readable diagnostic message containing: * the active observing modes; * the list of inconsistent subsystems; * the description of each inconsistency; * the associated severity. This message is used both for logging and for publication by the observation supervisor through the CSP Subarray diagnostic attributes. Relationship with command context --------------------------------- The scan policy uses the command context to obtain the runtime semantics of the accepted scan command. The context provides: * the selected scan devices; * the configured observation-mode semantics; * the active observing modes; * the scan schedule, when present; * the retained scan context, when the ``Scan`` command has completed but the scan lifecycle is still relevant. The policy does not rebuild this information only from the current subsystem state distribution. It consumes the command context prepared by the command context builder. This keeps scan consistency evaluation aligned with command execution and with the effective device set selected for the scan. Summary ------- The scan consistency policy validates subsystem behaviour during scanning, adapts the set of required subsystems to the active observing modes, handles PST beams with mode-specific logic, and reuses the base consistency model to: * continue scanning when inconsistencies are tolerable; * mark degraded scans through diagnostic information; * wait or refresh when the state distribution is not yet conclusive; * force a transition to ``FAULT`` when inconsistencies are non-recoverable.