document the recursions in the state transition code