Write the docs the next engineer needs

Write documentation for the code below, for an engineer who joins in six months.

Structure:
1. WHAT AND WHY — what this does and the problem it exists to solve. Include the constraint that explains the design, if you can infer it.
2. HOW IT WORKS — the flow, with the two or three decisions that would surprise a newcomer called out explicitly.
3. HOW TO USE IT — a minimal working example that actually runs, then one realistic example.
4. CONTRACT — inputs, outputs, errors thrown, and guarantees (ordering, idempotency, atomicity) — only those you can verify from the code.
5. GOTCHAS — the non-obvious behaviours, from reading the code, not imagined.
6. OPERATIONS — config, dependencies, what to check when it misbehaves.
7. OPEN QUESTIONS — things the code implies but doesn't answer, for me to fill in.

Do not document what the function names already say. No "This method returns a value."

CODE:
{{paste}}