<Design title>

1. Context

What we're building and why. Link the ADR or decision this implements. Lead with the point.

2. Goals & non-goals

What this design must achieve — and what it explicitly will not do. Non-goals prevent scope creep and pre-answer "why didn't you handle X?"

3. Design

The actual design. Be concrete:

• Interfaces — the APIs / traits / signatures.
• Data — structures, on-disk layout, encoding.
• Mechanics — control flow, the happy path step by step.
• Invariants — what must always hold. (If you can't assert it, you can't trust it.)

Diagrams welcome.

4. Alternatives considered

Other designs you weighed and why this one wins. For a big decision, defer to an ADR and link it instead of re-litigating here.

5. Risks & edge cases

Failure modes, edge cases, concurrency / crash / recovery concerns, performance characteristics. What could go wrong?

6. Testing

How this is validated — convince the reader it works. Unit · spec (sqllogictest) · e2e. Cover happy and unhappy paths.