mid-refactor (non-functional) for v2 spec updates