[NathanMartinez]

Summary

Add a small backend-independent failure model and shared transport/decoding adapters for media providers.

This is an additive foundation for translating backend-specific failures into a common application vocabulary without changing existing provider or repository APIs.

No existing provider behavior is changed by this PR.

Motivation

Chora currently supports multiple provider implementations, and additional backends can report equivalent failures in very different ways.

For example:

• connection timeout or DNS failure
• HTTP 429 rate limiting
• rejected authentication
• malformed responses
• backend-specific protocol errors
• explicitly missing content

Handling those directly at higher layers couples recovery and UI behavior to each backend's transport details.

This introduces a shared semantic boundary:

backend / transport details -> ProviderFailure -> recovery / presentation

Provider-specific adapters remain responsible for deciding what their backend responses mean.

Failure model

ProviderFailure currently represents:

• AuthenticationRejected
• AuthenticationRecoveryFailed
• RateLimited(retryAfter)
• Unavailable
• HttpError(status)
• ProtocolError(code)
• InvalidResponse
• MissingContent

ProviderException carries only the semantic failure and deliberately does not retain backend causes that could contain sensitive request or credential information.

Shared adapters

The PR also adds focused helpers for common boundaries:

• known network timeout / connection / DNS failures -> Unavailable
• known serialization failures -> InvalidResponse
• HTTP 429 -> RateLimited
• other terminal non-success HTTP responses -> HttpError
• Retry-After normalization for both delta-seconds and HTTP-date forms

The helpers intentionally do not catch arbitrary exceptions. Cancellation, programming defects, and unrelated failures remain visible rather than being misclassified as provider availability problems.

Scope

This PR only defines the shared contract and adapters.

It does not:

• change existing provider or repository signatures
• add UI behavior
• introduce recovery policy
• migrate Subsonic or Navidrome behavior yet

Provider-specific integrations are implemented separately so they can be reviewed independently.

Testing

Added focused tests covering the failure contract, validation rules, transport classification, decoding classification, HTTP status handling, and deterministic Retry-After parsing.

The shared semantic layer and its adapters have also been exercised as part of an integrated provider build without changing their public contract.