modern-swift-api-design

name	modern-swift-api-design
description	Use when designing or reviewing Swift protocols, generics, `some`/`any`, enums, domain types, associated types, typed throws, or public API resilience. Do not invoke for a local implementation change with no API decision.

Modern Swift API design

Preserve relationships in the type system and introduce abstraction only for a demonstrated boundary.

Procedure

1. State who chooses the concrete type: the implementation, the caller, or runtime data. This determines concrete types, opaque types/generics, or existentials.
2. Model the domain states and invalid combinations. Prefer an enum or constrained value over correlated booleans and stringly typed cases.
3. Decide the boundary's resilience, specialization, and heterogeneity requirements. Start concrete; use some when one hidden type is returned, generics when a relationship must be preserved, and any when heterogeneous runtime values are required.
4. Define protocol requirements around capabilities, not the current implementation. Do not create a protocol solely for mocking or to hide one private type.
5. Keep errors untyped by default. Use typed throws only for a stable closed error contract, generic error preservation, or a proven constrained environment.
6. Compile client-like examples, including inference, error handling, and the intended evolution point.

Guardrails

• any P erases relationships; do not use it where two values must share an associated type or generic parameter.
• some P hides one concrete type; it does not mean “any conformer” and is not a universal abstraction marker.
• A primary associated type improves constraints but does not remove the need to reason about identity and type relationships.
• Public API choices include source, ABI, and resilience consequences. Check library-evolution requirements before changing a shipped signature.
• Typed throws is additive precision, not a mandate to convert every throws declaration.

Read references/type-choice-guide.md for the decision table and review traps. Use the compiler to validate inference rather than relying on remembered syntax.

Completion contract

Report the caller/implementation choice, the abstraction boundary, the invalid states excluded, the error contract, and client-facing proof.