documented public interface at the top of core sources