Command Semantics
The command semantics module defines the policy-relevant meaning of a command.
It provides immutable data structures used by the observation consistency policies to evaluate command outcomes independently from the low-level command execution result.
Command semantics describe:
the command being evaluated;
the target observing state expected by the command;
the semantic role of each subsystem family;
the failure thresholds used by policy evaluation;
the reduced command outcome summary consumed by the consistency policies.
Semantic models used to evaluate command outcomes against policy rules.
This module defines small immutable data structures that describe the semantics of a command independently from its low-level execution result.
Here, command semantics means the policy-relevant meaning of a command: which observing state the command is expected to drive the system to, how different subsystem families should be interpreted for that command, and which failures should be considered significant when deciding whether the overall command outcome is acceptable, degraded, or failed.
For example, the same device failure may have a different impact depending on whether the command targets a core subsystem, a primary subsystem, or a commensal subsystem. These models provide the resolved information needed by policy evaluation without embedding that logic directly in the evaluator.
- class ska_csp_lmc_common.observation.command_semantics.FailureThreshold(min_success_ratio: float | None = None, max_failed: int | None = None)
Bases:
objectThresholds used to decide whether a set of failures is acceptable.
The threshold can be expressed either as a minimum success ratio, a maximum absolute number of failed elements, or both, depending on the policy rule being evaluated.
- class ska_csp_lmc_common.observation.command_semantics.FamilyRule(role: str, threshold: int | None = None)
Bases:
objectResolved semantic role for a subsystem family.
A family rule states how a subsystem family should be treated during policy evaluation for a given command. The role identifies the semantic importance of the family (for example
core,primary, orcommensal), whilethresholdcan optionally define how many failures are tolerated for that family.
- class ska_csp_lmc_common.observation.command_semantics.CommandSemantics(command_name: str, target_state: ska_control_model.ObsState, family_rules: ~typing.Mapping[str, ~ska_csp_lmc_common.observation.command_semantics.FamilyRule] = <factory>, allow_refresh_on_reconcile_timeout: bool = False)
Bases:
objectResolved policy-relevant semantics for a command.
Command semantics describes the meaning of a command from the point of view of policy evaluation rather than execution mechanics.
In particular, it captures:
the command being evaluated;
the target observing state the command is expected to reach;
how each subsystem family should be classified semantically (for example as
core,primary, orcommensal);whether special recovery behaviour is allowed during reconciliation.
This object is intended to be the resolved, evaluator-ready view of the command after configuration and command-specific policy rules have been interpreted.
- target_state: ska_control_model.ObsState
- family_rules: Mapping[str, FamilyRule]
- class ska_csp_lmc_common.observation.command_semantics.CommandSummary(degraded: bool, primary_failed: bool, failed_core_devices: tuple[str, ...] = (), failed_primary_devices: tuple[str, ...] = (), failed_commensal_devices: tuple[str, ...] = (), relevant_failed_devices: tuple[str, ...] = ())
Bases:
objectMinimal semantic summary of a command outcome.
This structure contains the reduced set of facts needed by policy evaluation after command execution or reconciliation has been analysed.
It indicates whether the outcome is degraded, whether any primary subsystem failure occurred, and which devices failed grouped by their semantic role.