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 Scheduled scan 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 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.