sketch of api additions/changes -- untested