OCTRL-1039 Documentation of status and state

README.md

@@ -120,6 +120,7 @@ There are two ways of interacting with AliECS:
       * [State machine triggers](/docs/handbook/operation_order.md#state-machine-triggers)
       * [START_ACTIVITY (Start Of Run)](/docs/handbook/operation_order.md#start_activity-start-of-run)
       * [STOP_ACTIVITY (End Of Run)](/docs/handbook/operation_order.md#stop_activity-end-of-run)
+      * [Virtual states and transitions](/docs/handbook/operation_order.md#virtual-states-and-transitions)
     * [Protocol documentation](/docs/apidocs_aliecs.md)
   * coconut
     * [The O² control and configuration utility overview](/coconut/README.md#the-o-control-and-configuration-utility-overview)

docs/handbook/operation_order.md

@@ -102,3 +102,21 @@ This is the order of actions happening at a healthy end of run.
 - `after_STOP_ACTIVITY` hooks with positive weights (incl. 0) are executed:
   - `ccdb.RunStop()` at `0`
   - `bookkeeping.UpdateRunStop()`, `bookkeeping.UpdateEnv()` at `+100`
+
+## Virtual states and transitions
+
+State **PENDING** and transitions **TEARDOWN**, and **DESTROY** lie outside the core FSM in `environment.go` and are driven by the Manager. See [core/environment/manager.go](../../core/environment/manager.go) for details.
+As these are not in a FSM we trigger them be calling specific methods. You can find details about triggering these in the according sections.
+
+### State PENDING
+
+Before the FSM enters `STANDBY`, the Manager drives the initial creation steps by emitting `Ev_EnvironmentEvent` messages (`Transition: CREATE, State: PENDING`) for both `before_CREATE` (running hooks) and `CREATE` (loading workflow).
+
+### Transition TEARDOWN
+
+When the FSM is in `RUNNING` and `TeardownEnvironment` function is called, the Manager records both `run_end_time_ms` and `run_end_completion_time_ms` and emits message `Ev_RunEvent` with content (`Transition: TEARDOWN`, `OpStatus_STARTED`) for each of timestamps. Right now there is only `OpStatus_STARTED` reported in Kafka. You can trigger `TeardownEnvironment` for example by invoking gRPC method `DestroyEnvironment` with `Force = true`. You cannot trigger `TEARDOWN` by calling gRPC method `Teardown`.
+
+### Transition DESTROY
+
+The Manager’s `TeardownEnvironment(...)` drives a four‑step `Ev_EnvironmentEvent` sequence (`before_DESTROY`, `leave_<state>`, `DESTROY`, `after_DESTROY`) on `topic.Environment` to release tasks, run hooks, and finalize teardown.
+You can trigger `TeardownEnvironment` for example by invoking gRPC method `DestroyEnvironment` with `Force = true`.