Single-club resolution service + typed club errors from club-scoped apps

[Sootopolis]

Follow-up to the use-club verify work (#173). We currently answer "is this club OK?" three incompatible ways: Club.selectBySlug (exact DB match, no recovery) gates job submission; ClubSlugRenameResolver (DB + board + admin tiers) lives inside the apps; and the CLI string-matches error.startsWith("Club not found"). There is no single-club verification against the DB — let alone Chess.com — and no route for one.

Proposal

1. One shared single-club resolver returning a typed verdict ADT:

sealed trait ClubStatus
  case Known(club: Club)                 // in our DB under this canonical slug
  case Renamed(from: ClubSlug, club: Club) // old slug 404s; recovered to a new canonical one
  case OnChessComOnly(apiClub: ApiClub)  // exists on Chess.com, never ingested into our DB
  case NotFound(slug: ClubSlug)          // 404 everywhere, no recovery
  case Problematic(slug: ClubSlug, reason) // tombstoned / cancelled / other

DB-first; then rename recovery (reuse ClubSlugRenameResolver); then an opt-in Chess.com fetch (reuse ChessComClient.getCacheable[ApiClub]) so OnChessComOnly / NotFound are only reached when a caller asks to pay the external request.

2. Two consumers:

• GET /api/clubs/{slug} returning the verdict. Powers use-club's verify (graduating it from managed-vs-not to a real existence check), the deferred interactive add-prompt, and a possible ccas club verify <slug>.
• Replace the Club.selectBySlug gate in JobRoutes.submitClubJob with the resolver. This makes rename recovery reachable at submission (closes Club rename: stale completion suggestion, and ClubSlugRenameResolver is unreachable from job submission #176) and lets a Renamed verdict flow back so the CLI can auto-repoint current_club + the cache.

3. Type the wire error. ClubJobResult/JobResult currently carry only error: Option[String]. Add a discriminant (ClubProblem enum: NotFound / Renamed(to) / NotManaged / Problematic) so the CLI branches on it instead of startsWith("Club not found"), and so Renamed carries the new slug.

Caveats to bake in

• On-demand Chess.com fan-out. A verify that hits Chess.com for arbitrary input is a way to make the server issue uncached external requests for any slug. getCacheable + the rate limiter bound it, but gate the Chess.com step (managed-only? authenticated?) — ties to the abuse concern in Gate job submission on managed status (JobRoutes.submitClubJob) #177 / Host CcasServer on Render (deferred until post-CLI-v0 + #51) #60.
• 404 is timeline-unstable. A club 404 today can flip to 200 later (recycled handle / fresh registration). A NotFound verdict must be advisory only — never a permanent skip, never tombstone from a single verify.
• Ingest-before-manage. OnChessComOnly exposes the real gap: club add (ManagedClubApp.mark) requires a pre-existing club row, so managing a never-seen club first needs an ingest step. That is the First-class managed_club marker (server-scoped, forward-compatible to per-user) #101 lifecycle piece; this resolver is a prerequisite for the interactive add-prompt (deferred from No way to check which club is currently in use #173).

Dissolves / unblocks

• Club rename: stale completion suggestion, and ClubSlugRenameResolver is unreachable from job submission #176 (rename recovery unreachable at submission) — fixed by consumer 2.
• The brittle startsWith("Club not found") match in Dispatcher — replaced by the typed error.
• The deferred use-club interactive add/use/cancel prompt — unblocked once existence and the ingest step exist.

Design proposal — refine before building. Needs a decision on how far the Chess.com-hitting path is exposed vs gated.