Add a structured `RouteError` discriminated union for handler returns

[greatest0fallt1me]

Description

This is a backend issue for the GrantFox campaign. Convert ad-hoc throws into a typed RouteError union returned by services, then translated to HTTP by middleware.

Requirements and Context

• RouteError union
• Service returns Result<T, RouteError>
• Middleware translates
• Tests cover
• Must be secure, tested, and documented
• Should be efficient and easy to review

Suggested Execution

1. Fork the repo and create a branch

   git checkout -b task/route-error-union

2. Implement changes
   • src/errors/RouteError.ts (new)
   • src/services/*.ts
   • src/middleware/errorHandler.ts
3. Test and commit
   • Run the repo's standard test suite and lint
   • Cover edge cases; include output in the PR

Example commit message

refactor: discriminated union for route errors

Acceptance Criteria

• Union shipped
• Services updated
• Middleware translates
• Tests pass

Guidelines

• Minimum 90% test coverage on changed lines
• Input validation at the boundary; standardized error envelope
• Structured logging with correlation IDs
• Clear documentation and inline comments
• Timeframe: 96 hours