Critique this API design

Before other people start depending on an interface you're designing.

Critique this API as someone who will have to use it without reading its implementation.

- What is confusing or easy to misuse? Where would I reach for the wrong function?
- What is missing that I will obviously need?
- What is present that nobody needs?
- Is anything inconsistent with the rest of the surface — naming, argument order, return shapes, error handling?
- Which decisions here will be painful to change later, once callers depend on them?

Suggest a revised signature. Be specific about what you'd rename.

API:

Refactoring and design calls. Cutting code down, naming things properly, and choosing between two workable options.