update docs and specs around state cache