ARCP TimeoutError/CancelledError shadow Python builtins and asyncio.CancelledError

[nficano]

Category: clean-code Severity: minor
Location: src/arcp/_errors.py:68-75

What

TimeoutError shadows the builtin TimeoutError (which asyncio.timeout/wait_for raise) and CancelledError is one import away from being confused with asyncio.CancelledError. Both are exported from the package root. Code that does from arcp import TimeoutError and then except TimeoutError would silently fail to catch asyncio timeouts — a real footgun. _job_runner.py:106 already relies on the builtin (it does not import arcp's), which is fragile.

Evidence

class CancelledError(ARCPError):
    code = "CANCELLED"
    default_retryable = False


class TimeoutError(ARCPError):
    code = "TIMEOUT"
    default_retryable = False

Proposed fix

Rename to non-shadowing names (e.g. ARCPTimeoutError, JobCancelledError) or only expose them via the error_class_for/error_from_payload mapping; if kept, document the shadowing risk prominently.

Acceptance criteria

• The ARCP error classes no longer shadow builtins, or the public surface clearly prevents from arcp import TimeoutError shadowing; existing error round-trip tests pass.