Hazardous Confirmations

A telecommand declared hazardous in the catalogue never leaves without a human confirmation, where the environment asks for one. The procedure marks the point of confirmation (ask operator); the environment decides who confirms: nobody on a simulator or a flatsat in AIT, the operator in IVV, an operator then a supervisor in orbit. The text of the procedure is the same everywhere.

Human orchestration#

Identity, confirmations, supervisor validation and mandatory planning form one block of the environment, human_orchestration:

environments:
  AIT:
    allow_draft: true
    human_orchestration: off
  IVV:
    allow_draft: false
    human_orchestration:
      identity: declared
      hazardous_confirmation: [operator]
  in_orbit:
    allow_draft: false
    human_orchestration:
      identity: jwt
      hazardous_confirmation: [operator, supervisor]
      hazardous_requires_plan: true

See Environments and Policies.

In the procedure#

Each send of a hazardous telecommand follows, in the same step, its own ask operator "…" confirmation, or the compiler refuses the step (procedure::unconfirmed-hazardous):

procedure "Blank firing"
  uses sat: platform-v3
  input tcu: tcu_id

  step "Fire the blank"
    ask operator "Fire the blank on the TCU?"
    send blank_firing to sat.tcu[tcu]

See Safety Rules.

The confirmation flow#

In a step that sends a hazardous telecommand, an ask operator without typed answer is a confirmation. Each role of hazardous_confirmation answers it in turn:

sequenceDiagram
    participant E as Executor
    participant O as Operator
    participant S as Supervisor
    E->>E: asked (role: operator)
    O->>E: stellar answer <run> yes
    E->>E: answered (by: alice, role: operator)
    E->>E: asked (role: supervisor)
    S->>E: stellar answer <run> yes
    E->>E: answered (by: carol, role: supervisor)
    E->>E: send the hazardous telecommand

1. The executor logs asked with the role awaited; stellar status and GET /v1/runs/{id} show it (pending.role), and stellar watch prints ask « … », confirmation of the operator.

2. An answer is taken only from a person who has the role awaited and has not confirmed the step yet: the operator and the supervisor are two distinct people.

3. With identity: jwt, the executor checks the token again itself: its signature, its expiry, its subject equal to the author of the answer, and the roles it carries. With identity: declared, the declared roles suffice.

4. An answer that does not qualify is logged as answer_refused, with its author and the reason, and the wait goes on:

     answer of alice not taken: `alice` already confirmed this step
     answer of bob not taken: `bob` is not supervisor

5. An explicit refusal (stellar answer <run> no) fails the step: the telecommand is not sent.

The report and the log show every confirmation with its role, its author and its time, and every answer refused.

# The operator
stellar answer <run> yes --token "$OPERATOR_TOKEN"
# The supervisor, from their own session
stellar answer <run> yes --token "$SUPERVISOR_TOKEN"

Where declared identities are accepted (identity: declared), --as and --role identify the person: stellar answer <run> yes --as carol --role supervisor. They are refused where the environment requires tokens, such as in_orbit.

Without human orchestration, the confirmation is acknowledged automatically (answered without author) and the run does not stop.

How long a confirmation waits#

• For a run bound to a pass (plan), the wait ends at the LOS of the pass minus scheduler.margin. Past it, the step fails cleanly, without sending the telecommand: "no answer before … (end of the pass minus the margin): nothing sent".
• A manual run waits without limit, until an answer, a suspension or an abort.

Mandatory planning#

With hazardous_requires_plan: true, a run whose procedure sends a hazardous telecommand, directly or through its calls, cannot be launched by hand:

• without plan, the request is refused at resolution (422 run::plan-required);
• with a plan too (422 run::must-be-scheduled): it starts only from a schedule, which the scheduler submits itself at its time (POST /v1/schedules, stellar schedules add).

In in_orbit, the pass must also be booked. See Scheduling.

Two validations: the plan, then the step#

The supervisor validates twice, because the state of the satellite may change between the planning and the pass:

1. The plan, beforehand. A schedule whose run sends a hazardous telecommand, in an environment where the supervisor confirms, is marked needs_validation when it is created. It stays at_risk ("awaiting the validation of the plan by a supervisor") and does not start until a validation holds.
2. The telecommand, live, during the pass, as above.

STELLAR_TOKEN="$SUPERVISOR_TOKEN" stellar schedules validate sch-0142

POST /v1/schedules/{id}/validate is reserved to an identity with the role supervisor (403 schedule::not-supervisor otherwise), allowed by the environment of the schedule. It records the validation: who, when, the pass, its AOS and LOS, and the hash of the resolved run, which covers the procedure, the inputs and the targets.

Any change of what was validated makes the validation fall, for good: at each evaluation, the scheduler compares it with the schedule and its pass (same resolved run, same pass, same AOS and LOS). At the first difference, the validation is dropped ("the validation of carol fell: the window of pass … changed") and the schedule is at_risk again, until a new validation. Replacing the schedule drops it too. A schedule still without a valid validation at its time is missed: nothing is sent.

Identity everywhere#

The identity rules of the environment apply to the launch, to the answers, to the commands of a run (suspend, resume, abort), and to the creation and the validation of a schedule. See Identity and Roles.