[docs] Add state machine callback documentation

Author: teo

docs/handbook/overview.md

@@ -53,4 +53,35 @@ This is the order of callback execution upon a state transition:
 5. `enter_<NEW_STATE>`, `<NEW_STATE>` - called after entering `<NEW_STATE>`
 6. `enter_state` - called after entering all states
 7. `after_<EVENT>`, `<EVENT>` - called after event named `<EVENT>`
-8. `after_event` - called after all events
+8. `after_event` - called after all events
+
+Callback execution is further refined with integer indexes, with the syntax `±index`, e.g. `before_CONFIGURE+2`, `enter_CONFIGURED-666`. An expression with no index is assumed to be indexed `+0`. These indexes do not correspond to timestamps, they are discrete labels that allow more granularity in callbacks, ensuring a strict ordering of callback opportunities within a given callback moment. Thus, `before_CONFIGURE+2` will complete execution strictly after `before_CONFIGURE` runs, but strictly before `enter_CONFIGURED-666` is executed.
+
+## Workflow hook calls
+
+The state machine callback moments are exposed to the AliECS workflow template interface and can be used as triggers or synchronization points for integration plugin function calls. The `call` block can be used for this purpose, with similar syntax to the `task` block used for controllable tasks. Its fields are as follows.
+* `func` - mandatory, it parses as an `antonmedv/expr` expression that corresponds to a call to a function that belongs to an integration plugin object (e.g. `bookkeeping.StartOfRun()`, `dcs.EndOfRun()`, etc.).
+* `trigger` - mandatory, the expression at `func` will be executed once the state machine reaches this moment.
+* `await` - optional, if absent it defaults to the same as `trigger`, the expression at `func` needs to finish by this moment, and the state machine will block until `func` completes.
+* `timeout` - optional, Go `time.Duration` expression, the maximum time `func` will be granted to complete before its context is invalidated.
+* `critical` - optional, it defaults to `true`, if `true` then a failure or timeout for `func` will send the environment state machine to `ERROR`.
+
+Consider the following example:
+```
+# Trigger and await are different: any number of other operations may happen concurrently in between. Regardless of when in time the call actually finishes, its result isn't collected until the environment state machine reaches `after_RESET+0`. The state machine will only block if it reaches `after_RESET+0` and the call isn't done yet (completed or timed out).
+      - name: reset
+        call:
+          func: odc.Reset()
+          trigger: before_RESET
+          await: after_RESET
+          timeout: "{{ odc_reset_timeout }}"
+          critical: true
+# Trigger and await are the same (the await expression could be omitted here): the call must begin and end within the `after_RESET+100` step. If the workflow template defines no other calls straddling `after_RESET+100` then this call is fully serialized with respect to the state machine and its execution blocks everything else.
+      - name: part-term
+        call:
+          func: odc.PartitionTerminate()
+          trigger: after_RESET+100
+          await: after_RESET+100
+          timeout: "{{ odc_partitionterminate_timeout }}"
+          critical: true
+```