WIP: added docs about safety and liveness guarantees